Migrating from Ranch 2.0 to Ranch 2.1

Ranch 2.1 adds counters and alarms.

The Prometheus collector was updated to include accepted/terminated connections metrics.

Ranch 2.1 is compatible with Erlang/OTP 22.0 onward. Support for Erlang/OTP 21 has been removed.

Features added

  • Metrics are now provided by ranch:info/0,1. Currently includes accepted/terminated connection counts per connection supervisor.
  • Alarms can now be configured. The only alarm currently available is num_connections. When the number of connections goes over a configurable treshold Ranch will call the given callback. This can be used to programmatically shut down idle connections to make up space for new connections, for example.
  • A post_listen_callback option has been added. It receives sockets immediately after the Transport:listen/1 call. It can be used for some additional initialization of the socket, such as setting file permissions on Unix domain sockets.
  • It is now possible to use TLS-PSK authentication without having to specify a default certificate for TLS < 1.3.

Experimental features added

  • The inet_backend option is now properly handled and tested for TCP listeners. This allows using the experimental socket backend. The socket backend is now tested with Ranch. Note that there are known issues and Windows support is not currently implemented.

Changed behaviors

  • Ranch will now remove unsupported SSL/TLS options where applicable. A warning will be logged when this happens. Options are only removed when they are not compatible with the selected TLS version and leaving them would prevent the listener from starting.

    The following options are removed when using TLS 1.1, 1.2 or 1.3: beast_mitigation and padding_check.

    The following options are removed when using TLS 1.3 exclusively: client_renegotiation, next_protocols_advertised, psk_identity, reuse_session, reuse_sessions, secure_renegotiate and user_lookup_fun.

Added functions

  • The function ranch_proxy_header:to_connection_info/1 converts PROXY protocol information to the same format as ssl:connection_information/1. Because there is little overlap only the protocol, selected_cipher_suite and sni_hostname will be available, however.

Ranch 2.1 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.