start_tls(Name :: ranch:ref(), NumAcceptors :: non_neg_integer(), TransportOpts :: ranch_ssl:opts(), ProtocolOpts :: opts()) -> {ok, ListenerPid :: pid()} | {error, any()}
cowboy:start_tls - Listen for connections using TLS
start_tls(Name :: ranch:ref(), NumAcceptors :: non_neg_integer(), TransportOpts :: ranch_ssl:opts(), ProtocolOpts :: opts()) -> {ok, ListenerPid :: pid()} | {error, any()}
Start listening for connections over a secure TLS channel.
Both HTTP/1.1 and HTTP/2 are supported on this listener. The ALPN TLS extension must be used to initiate an HTTP/2 connection.
The listener name is used to refer to this listener in future calls, for example when stopping it or when updating the routes defined.
It can be any Erlang term. An atom is generally good enough,
for example api, my_app_clear or my_app_tls.
The number of acceptors is the number of processes that will accept connections. Tweak this value to improve the accept rate for incoming connections.
The ideal value is between 10 and 100 on most systems. Larger values may have the opposite effect and reduce the accept rate. It’s generally safe to start with a value of 100 (or 10 on low memory systems). Then, when accept rates become a concern, measure the performance and update the value accordingly.
This value is unrelated to the maximum number of concurrent connections.
The transport options are where the TCP options, including
the listener’s port number, are defined. They also contain
the TLS options, like the server’s certificate. Transport options
are provided as a list of keys and values, for example
[{port, 8443}, {certfile, "path/to/cert.pem"}].
The available options are documented in the ranch_ssl(3) manual.
The protocol options are in a map containing all the options for the different protocols that may be involved when connecting to the listener, including HTTP/1.1 and HTTP/2 but also subprotocols like Websocket.
The HTTP/1.1 options are documented in the cowboy_http(3) manual; the HTTP/2 options in cowboy_http2(3); and the Websocket options in cowboy_websocket(3).
An ok tuple is returned on success. It contains the pid of the top-level supervisor for the listener.
An error tuple is returned on error. The error reason may be any Erlang term.
A common error is eaddrinuse. It indicates that the port
configured for Cowboy is already in use.
2.0: HTTP/2 support added.
2.0: Function introduced. Replaces cowboy:start_https/4.
Dispatch = cowboy_router:compile([ {'_', [ {"/", toppage_h, []} ]} ]), {ok, _} = cowboy:start_tls(example, 100, [ {port, 8443}, {cert, "path/to/cert.pem"} ], #{ env => #{dispatch => Dispatch} }).
Name = example, {ok, _} = cowboy:start_tls(Name, 100, [ {cert, "path/to/cert.pem"} ], #{ env => #{dispatch => Dispatch} }), Port = ranch:get_port(Name).