diff options
Diffstat (limited to 'doc/src/manual/cowboy.start_tls.asciidoc')
-rw-r--r-- | doc/src/manual/cowboy.start_tls.asciidoc | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy.start_tls.asciidoc b/doc/src/manual/cowboy.start_tls.asciidoc new file mode 100644 index 0000000..b85abe6 --- /dev/null +++ b/doc/src/manual/cowboy.start_tls.asciidoc @@ -0,0 +1,131 @@ += cowboy:start_tls(3) + +== Name + +cowboy:start_tls - Listen for connections using TLS + +== Description + +[source,erlang] +---- +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. + +== Arguments + +Name:: + +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`. + +NumAcceptors:: + +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. + +TransportOpts:: + +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 +link:man:ranch_ssl(3)[ranch_ssl(3)] manual. + +ProtocolOpts:: + +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. +// @todo For Websocket this might change in the future. ++ +The HTTP/1.1 options are documented in the +link:man:cowboy_http(3)[cowboy_http(3)] manual; +the HTTP/2 options in +link:man:cowboy_http2(3)[cowboy_http2(3)]; +and the Websocket options in +link:man:cowboy_websocket(3)[cowboy_websocket(3)]. + +== Return value + +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. + +== Changelog + +* *2.0*: HTTP/2 support added. +* *2.0*: Function introduced. Replaces `cowboy:start_https/4`. + +== Examples + +.Start a listener +[source,erlang] +---- +Dispatch = cowboy_router:compile([ + {'_', [ + {"/", toppage_h, []} + ]} +]), + +{ok, _} = cowboy:start_tls(example, 100, [ + {port, 8443}, + {cert, "path/to/cert.pem"} +], #{ + env => #{dispatch => Dispatch} +}). +---- + +.Start a listener on a random port +[source,erlang] +---- +Name = example, + +{ok, _} = cowboy:start_tls(Name, 100, [ + {cert, "path/to/cert.pem"} +], #{ + env => #{dispatch => Dispatch} +}), + +Port = ranch:get_port(Name). +---- + +== See also + +link:man:cowboy(3)[cowboy(3)], +link:man:cowboy:start_clear(3)[cowboy:start_clear(3)], +link:man:ranch(3)[ranch(3)] |