Migrating from Ranch 1.x

The changelog for Ranch releases before 1.6 can be found in this section.


  • Add transport functions getopts/2, getstat/1 and getstat/2
  • Fix ranch:info/0 and ranch:procs/2 in embedded mode
  • Prevent ranch_conns_sup from stopping on unexpected messages


  • Add new transport option num_acceptor
  • Deprecate ranch:start_listener/6 in favor of start_listener/5
  • Deprecate ranch:child_spec/6 in favor of child_spec/5


The version numbers 1.3.1 and 1.3.2 were later made to fix small mistakes made during the 1.3.0 release process. They do not include code changes.

  • Tested with OTP R16B+ on Linux, FreeBSD, OSX and Windows
  • Add ssl to the list of dependencies
  • Add ranch:info/0 and ranch:procs/2 to retrieve Ranch state information
  • Allow configuring a listener with only SNI, without a default certificate
  • Blacklist transport options instead of whitelist
    • Unknown options are now allowed, but will result in a Dialyzer warning
  • Add many transport options typespecs and documentation
  • Don't silently drop the accept rate when running out of fds
  • Prevent a race condition when stopping listeners
  • Improve reporting for common errors, for example eaddrinuse
  • Fix double removal of connections bug
    • The number of active connections should now be exact
  • Fix stuck acceptor bug when controlling_socket returned errors
  • Numerous documentation and examples improvements


  • Fix bug preventing node shutdown when SSL is used with OTP 17.1+
  • Tune restart intensity in all supervisors


  • Allow the supervised process and the process owning the socket to be different
  • Add many transport options (please refer to the documentation)
  • Add function ranch:get_addr/1 to retrieve both IP and port of listener
  • Don't pass Ranch-specific options down to transports
    • Should make Dialyzer happy in user projects
    • New types ranch:opt(), ranch_tcp:opt(), ranch_ssl:ssl_opt() and ranch_ssl:opt()
  • Fix crash when filtering unknown options out
  • Print a warning for each option filtered out
  • Handle Transport:controlling_socket/2 errors and close the socket
  • Handle Protocol:start_link/4 crashes to avoid killing all active connections
  • Use Asciidoc for documentation
  • Test Ranch across 14 Erlang versions on CircleCI
  • Improve and document test suites with recent ct_helper improvements
  • Fix a number of intermittent test issues


  • Add Transport:secure/0
  • Add SSL partial_chain option
  • Stop reporting errors on {error, closed} in accept_ack


  • Initial release

Ranch 1.7 User Guide


Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.