ranch:set_transport_options(3)

NAME

ranch:set_transport_options - Set the transport options

DESCRIPTION
    set_transport_options(Ref       :: ranch:ref(),
                          TransOpts :: ranch:opts())
        -> ok | {error, Reason :: term()}

Set the transport options.

The complete set of transport options is replaced. To update a subset of the transport options, it is recommended to get the current transport options using ranch:get_transport_options(3), update them and then set them back using this function.

Changes to the following options will take effect...

    • immediately:
        • max_connections
        • handshake_timeout
        • shutdown
    • only after the listener has been suspended and resumed:
        • num_acceptors
        • num_listen_sockets
        • post_listen_callback
        • socket_opts
    • only when the entire listener is restarted:
        • connection_type
        • num_conns_sups
        • logger

ARGUMENTS

Ref
    The listener name.

TransOpts
    The new transport options.

RETURN VALUE

The atom ok is returned on success.

An error tuple is returned on failure, for example if the given transport options contain invalid values.

CHANGELOG
    • 2.0: The restriction that the listener must be suspended has been removed.
    • 2.0: The TransOpts argument must no longer contain Ranch-specific options if given as a list. Use a map.

EXAMPLES

Set the transport options
    Ref = example,

    ok = ranch:suspend_listener(Ref),
    ok = ranch:set_transport_options(Ref, TransOpts),
    ok = ranch:resume_listener(Ref).

Update the listener TCP port within the `socket_opts` transport option
    Ref = example,

    TransOpts0 = ranch:get_transport_options(Ref),
    #{socket_opts = SocketOpts0} = TransOpts0,
    SocketOpts = [{port, 12345}|proplists:delete(port, SocketOpts0)],
    TransOpts = TransOpts0#{socket_opts = SocketOpts},

    ok = ranch:suspend_listener(Ref),
    ok = ranch:set_transport_options(Ref, TransOpts),
    ok = ranch:resume_listener(Ref).

SEE ALSO

ranch:suspend_listener(3), ranch:resume_listener(3), ranch:get_transport_options(3), ranch:set_max_connections(3), ranch:set_protocol_options(3), ranch(3)