cowboy/doc/src/manual/cowboy.start_tls.asciidoc

= cowboy:start_tls(3)

== Name

cowboy:start_tls - Listen for connections using TLS

== Description

[source,erlang]
----
start_tls(Name          :: ranch:ref(),
          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`.

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.
+
The HTTP/1.1 options are documented in the
link:man:cowboy_http(3)[cowboy_http(3)] manual;
and the HTTP/2 options in
link:man:cowboy_http2(3)[cowboy_http2(3)]. Stream handlers
such as link:man:cowboy_stream_h(3)[cowboy_stream_h(3)]
(which is enabled by default) may also define options.

== 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, [
    {port, 8443},
    {certfile, "path/to/cert.pem"}
], #{
    env => #{dispatch => Dispatch}
}).
----

.Start a listener on a random port
[source,erlang]
----
Name = example,

{ok, _} = cowboy:start_tls(Name, [
    {certfile, "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)]