mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 12:40:25 +00:00
0424724062
This commit separates the documentation of the functions into separate manual pages, with at least one example per function and a lot more details about parameters, return values and related functions and modules. It also includes a changelog indicating when the function was added or changed. The inspiration for this comes mainly from the PHP documentation and feedback from users.
131 lines
3.2 KiB
Text
131 lines
3.2 KiB
Text
= 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)]
|