1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
= 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:cowboy:stop_listener(3)[cowboy:stop_listener(3)],
link:man:ranch(3)[ranch(3)]
|
