From fdc955ab18ba2fe285c75b75a8b92cf9f9436adc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 2 Jan 2017 19:56:53 +0100
Subject: Update docs

---
 docs/index.xml | 376 ++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 209 insertions(+), 167 deletions(-)

(limited to 'docs/index.xml')

diff --git a/docs/index.xml b/docs/index.xml
index 09ef6b82..edeafd2e 100644
--- a/docs/index.xml
+++ b/docs/index.xml
@@ -210,8 +210,6 @@ environment configuration parameters.&lt;/p&gt;&lt;/div&gt;
 &lt;a href=&#34;getting_started/&#34;&gt;Getting started&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
-&lt;/ul&gt;&lt;/div&gt;
-&lt;div class=&#34;ulist&#34;&gt;&lt;ul&gt;
 &lt;li&gt;
 &lt;p&gt;
 &lt;a href=&#34;flow_diagram/&#34;&gt;Flow diagram&lt;/a&gt;
@@ -231,11 +229,6 @@ environment configuration parameters.&lt;/p&gt;&lt;/div&gt;
 &lt;/li&gt;
 &lt;li&gt;
 &lt;p&gt;
-&lt;a href=&#34;streams/&#34;&gt;Streams&lt;/a&gt;
-&lt;/p&gt;
-&lt;/li&gt;
-&lt;li&gt;
-&lt;p&gt;
 &lt;a href=&#34;routing/&#34;&gt;Routing&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
@@ -339,45 +332,68 @@ environment configuration parameters.&lt;/p&gt;&lt;/div&gt;
 &lt;/li&gt;
 &lt;li&gt;
 &lt;p&gt;
-&lt;a href=&#34;ws_handlers/&#34;&gt;Handling Websocket connections&lt;/a&gt;
+&lt;a href=&#34;ws_handlers/&#34;&gt;Websocket handlers&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
 &lt;/ul&gt;&lt;/div&gt;
 &lt;/div&gt;
 &lt;/div&gt;
 &lt;div class=&#34;sect1&#34;&gt;
-&lt;h2 id=&#34;_internals&#34;&gt;Internals&lt;/h2&gt;
+&lt;h2 id=&#34;_advanced&#34;&gt;Advanced&lt;/h2&gt;
 &lt;div class=&#34;sectionbody&#34;&gt;
 &lt;div class=&#34;ulist&#34;&gt;&lt;ul&gt;
 &lt;li&gt;
 &lt;p&gt;
-&lt;a href=&#34;architecture/&#34;&gt;Architecture&lt;/a&gt;
+&lt;a href=&#34;streams/&#34;&gt;Streams&lt;/a&gt;
+&lt;/p&gt;
+&lt;/li&gt;
+&lt;li&gt;
+&lt;p&gt;
+&lt;a href=&#34;middlewares/&#34;&gt;Middlewares&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
 &lt;/ul&gt;&lt;/div&gt;
 &lt;div class=&#34;ulist&#34;&gt;&lt;ul&gt;
 &lt;li&gt;
 &lt;p&gt;
-&lt;a href=&#34;broken_clients/&#34;&gt;Dealing with broken clients&lt;/a&gt;
+&lt;a href=&#34;sub_protocols/&#34;&gt;Sub protocols&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
+&lt;/ul&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_deprecated_chapters&#34;&gt;Deprecated chapters&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_about_the_deprecated_chapters&#34;&gt;About the deprecated chapters&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The following chapters were relevant in Cowboy 1.0. They have
+not been updated for Cowboy 2.0 yet. The information in these
+chapters may or may not be useful.&lt;/p&gt;&lt;/div&gt;
+&lt;div class=&#34;ulist&#34;&gt;&lt;ul&gt;
 &lt;li&gt;
 &lt;p&gt;
-&lt;a href=&#34;middlewares/&#34;&gt;Middlewares&lt;/a&gt;
+&lt;a href=&#34;architecture/&#34;&gt;Architecture&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
 &lt;li&gt;
 &lt;p&gt;
-&lt;a href=&#34;sub_protocols/&#34;&gt;Sub protocols&lt;/a&gt;
+&lt;a href=&#34;broken_clients/&#34;&gt;Dealing with broken clients&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
-&lt;/ul&gt;&lt;/div&gt;
-&lt;div class=&#34;ulist&#34;&gt;&lt;ul&gt;
 &lt;li&gt;
 &lt;p&gt;
 &lt;a href=&#34;hooks/&#34;&gt;Hooks&lt;/a&gt;
 &lt;/p&gt;
 &lt;/li&gt;
+&lt;li&gt;
+&lt;p&gt;
+&lt;a href=&#34;overview/&#34;&gt;Overview&lt;/a&gt;
+&lt;/p&gt;
+&lt;/li&gt;
 &lt;/ul&gt;&lt;/div&gt;
 &lt;/div&gt;
 &lt;/div&gt;
@@ -1080,158 +1096,6 @@ client and the connection is closed.&lt;/p&gt;&lt;/div&gt;
 </description>
     </item>
     
-    <item>
-      <title>Request overview</title>
-      <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/overview/</link>
-      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-      
-      <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/overview/</guid>
-      <description>&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This chapter explains the different steps a request
-goes through until a response is sent, along with
-details of the Cowboy implementation.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;sect1&#34;&gt;
-&lt;h2 id=&#34;_request_response&#34;&gt;Request/response&lt;/h2&gt;
-&lt;div class=&#34;sectionbody&#34;&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;As you already know, HTTP clients connect to the server and
-send a request for a resource; the server then sends a
-response containing the resource if it could obtain it.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Before the server can send the resource, however, it
-needs to perform many different operations to read the
-request, find the resource, prepare the response being
-sent and often other related operations the user can
-add like writing logs.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Requests take the following route in Cowboy:&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;imageblock&#34;&gt;
-&lt;div class=&#34;content&#34;&gt;
-&lt;img src=&#34;../http_req_resp.png&#34; alt=&#34;HTTP request/response flowchart&#34; /&gt;
-&lt;/div&gt;
-&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This shows the default middlewares, but they may be
-configured differently in your setup. The dark green
-indicates the points where you can hook your own code,
-the light green is the Cowboy code that you can of
-course configure as needed.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The &lt;code&gt;acceptor&lt;/code&gt; is the part of the server that accepts
-the connection and create an Erlang process to handle
-it. The &lt;code&gt;parser&lt;/code&gt; then starts reading from the socket
-and handling requests as they come until the socket
-is closed.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;A response may be sent at many different points in the
-life of the request. If Cowboy can&amp;#8217;t parse the request,
-it gives up with an error response. If the router can&amp;#8217;t
-find the resource, it sends a not found error. Your
-own code can of course send a response at any time.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;When a response is sent, you can optionally modify it
-or act upon it by enabling the &lt;code&gt;onresponse&lt;/code&gt; hook. By
-default the response is sent directly to the client.&lt;/p&gt;&lt;/div&gt;
-&lt;/div&gt;
-&lt;/div&gt;
-&lt;div class=&#34;sect1&#34;&gt;
-&lt;h2 id=&#34;_and_then&#34;&gt;And then?&lt;/h2&gt;
-&lt;div class=&#34;sectionbody&#34;&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Behavior depends on what protocol is in use.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/1.0 can only process one request per connection,
-so Cowboy will close the connection immediately after
-it sends the response.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/1.1 allows the client to request that the server
-keeps the connection alive. This mechanism is described
-in the next section.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/2 is designed to allow sending multiple requests
-asynchronously on the same connection. Details on what
-this means for your application is described in this
-chapter.&lt;/p&gt;&lt;/div&gt;
-&lt;/div&gt;
-&lt;/div&gt;
-&lt;div class=&#34;sect1&#34;&gt;
-&lt;h2 id=&#34;_keep_alive_http_1_1&#34;&gt;Keep-alive (HTTP/1.1)&lt;/h2&gt;
-&lt;div class=&#34;sectionbody&#34;&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;With HTTP/1.1, the connection may be left open for
-subsequent requests to come. This mechanism is called
-&lt;code&gt;keep-alive&lt;/code&gt;.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;When the client sends a request to the server, it includes
-a header indicating whether it would like to leave the
-socket open. The server may or may not accept, indicating
-its choice by sending the same header in the response.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Cowboy will include this header automatically in all
-responses to HTTP/1.1 requests. You can however force
-the closing of the socket if you want. When Cowboy sees
-you want to send a &lt;code&gt;connection: close&lt;/code&gt; header, it will
-not override it and will close the connection as soon
-as the reply is sent.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This snippet will force Cowboy to close the connection.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;listingblock&#34;&gt;
-&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite --&gt;
-&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;color: #009900&#34;&gt;Req2&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy_req:reply&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #993399&#34;&gt;200&lt;/span&gt;, [
-    {&lt;span style=&#34;color: #990000&#34;&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;connection&#34;&lt;/span&gt;&lt;span style=&#34;color: #990000&#34;&gt;&amp;gt;&amp;gt;&lt;/span&gt;, &lt;span style=&#34;color: #990000&#34;&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;close&#34;&lt;/span&gt;&lt;span style=&#34;color: #990000&#34;&gt;&amp;gt;&amp;gt;&lt;/span&gt;},
-], &lt;span style=&#34;color: #990000&#34;&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;Closing the socket in 3.. 2.. 1..&#34;&lt;/span&gt;&lt;span style=&#34;color: #990000&#34;&gt;&amp;gt;&amp;gt;&lt;/span&gt;, &lt;span style=&#34;color: #009900&#34;&gt;Req&lt;/span&gt;)&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Cowboy will only accept a certain number of new requests
-on the same connection. By default it will run up to 100
-requests. This number can be changed by setting the
-&lt;code&gt;max_keepalive&lt;/code&gt; configuration value when starting an
-HTTP listener.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;listingblock&#34;&gt;
-&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite --&gt;
-&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy:start_http&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #FF6600&#34;&gt;my_http_listener&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;100&lt;/span&gt;, [{&lt;span style=&#34;color: #FF6600&#34;&gt;port&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;8080&lt;/span&gt;}], [
-        {&lt;span style=&#34;color: #FF6600&#34;&gt;env&lt;/span&gt;, [{&lt;span style=&#34;color: #FF6600&#34;&gt;dispatch&lt;/span&gt;, &lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt;}]},
-        {&lt;span style=&#34;color: #FF6600&#34;&gt;max_keepalive&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;5&lt;/span&gt;}
-])&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Cowboy implements the keep-alive mechanism by reusing
-the same process for all requests. This allows Cowboy
-to save memory. This works well because most code will
-not have any side effect impacting subsequent requests.
-But it also means you need to clean up if you do have
-code with side effects. The &lt;code&gt;terminate/3&lt;/code&gt; function can
-be used for this purpose.&lt;/p&gt;&lt;/div&gt;
-&lt;/div&gt;
-&lt;/div&gt;
-&lt;div class=&#34;sect1&#34;&gt;
-&lt;h2 id=&#34;_pipelining_http_1_1&#34;&gt;Pipelining (HTTP/1.1)&lt;/h2&gt;
-&lt;div class=&#34;sectionbody&#34;&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;While HTTP is designed as a sequential protocol, with
-the client sending a request and then waiting for the
-response from the server, nothing prevents the client
-from sending more requests to the server without waiting
-for the response, due to how sockets work. The server
-still handles the requests sequentially and sends the
-responses in the same order.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This mechanism is called pipelining. It allows reducing
-latency when a client needs to request many resources
-at the same time. This is used by browsers when requesting
-static files for example.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This is handled automatically by the server.&lt;/p&gt;&lt;/div&gt;
-&lt;/div&gt;
-&lt;/div&gt;
-&lt;div class=&#34;sect1&#34;&gt;
-&lt;h2 id=&#34;_asynchronous_requests_http_2&#34;&gt;Asynchronous requests (HTTP/2)&lt;/h2&gt;
-&lt;div class=&#34;sectionbody&#34;&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;In HTTP/2, the client can send a request at any time.
-And the server can send a response at any time too.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This means for example that the client does not need
-to wait for a request to be fully sent to send another,
-it is possible to interleave a request with the request
-body of another request. The same is true with responses.
-Responses may also be sent in a different order.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Because requests and responses are fully asynchronous,
-Cowboy creates a new process for each request, and these
-processes are managed by another process that handles the
-connection itself.&lt;/p&gt;&lt;/div&gt;
-&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;HTTP/2 servers may also decide to send resources to the
-client before the client requests them. This is especially
-useful for sending static files associated with the HTML
-page requested, as this reduces the latency of the overall
-response. Cowboy does not support this particular mechanism
-at this point, however.&lt;/p&gt;&lt;/div&gt;
-&lt;/div&gt;
-&lt;/div&gt;
-</description>
-    </item>
-    
     <item>
       <title>cowboy(3)</title>
       <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/</link>
@@ -1822,6 +1686,184 @@ http://www.gnu.org/software/src-highlite --&gt;
 &lt;a href=&#34;../ranch&#34;&gt;ranch(3)&lt;/a&gt;&lt;/p&gt;&lt;/div&gt;
 &lt;/div&gt;
 &lt;/div&gt;
+</description>
+    </item>
+    
+    <item>
+      <title>cowboy:start_tls(3)</title>
+      <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</link>
+      <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
+      
+      <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</guid>
+      <description>&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_name&#34;&gt;Name&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;cowboy:start_tls - Listen for connections using TLS&lt;/p&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_description&#34;&gt;Description&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;listingblock&#34;&gt;
+&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite --&gt;
+&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;start_tls&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt;          &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;ranch:ref&lt;/span&gt;&lt;/span&gt;(),
+          &lt;span style=&#34;color: #009900&#34;&gt;NumAcceptors&lt;/span&gt;  &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;non_neg_integer&lt;/span&gt;&lt;/span&gt;(),
+          &lt;span style=&#34;color: #009900&#34;&gt;TransportOpts&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;ranch_ssl:opts&lt;/span&gt;&lt;/span&gt;(),
+          &lt;span style=&#34;color: #009900&#34;&gt;ProtocolOpts&lt;/span&gt;  &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;opts&lt;/span&gt;&lt;/span&gt;())
+    &lt;span style=&#34;color: #990000&#34;&gt;-&amp;gt;&lt;/span&gt; {&lt;span style=&#34;color: #FF6600&#34;&gt;ok&lt;/span&gt;, &lt;span style=&#34;color: #009900&#34;&gt;ListenerPid&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;::&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000080&#34;&gt;pid&lt;/span&gt;&lt;/span&gt;()}
+     | {&lt;span style=&#34;color: #FF6600&#34;&gt;error&lt;/span&gt;, &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;any&lt;/span&gt;&lt;/span&gt;()}&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;Start listening for connections over a secure TLS channel.&lt;/p&gt;&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;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.&lt;/p&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_arguments&#34;&gt;Arguments&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;dlist&#34;&gt;&lt;dl&gt;
+&lt;dt class=&#34;hdlist1&#34;&gt;
+Name
+&lt;/dt&gt;
+&lt;dd&gt;
+&lt;p&gt;
+The listener name is used to refer to this listener in
+future calls, for example when stopping it or when
+updating the routes defined.
+&lt;/p&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;It can be any Erlang term. An atom is generally good enough,
+for example &lt;code&gt;api&lt;/code&gt;, &lt;code&gt;my_app_clear&lt;/code&gt; or &lt;code&gt;my_app_tls&lt;/code&gt;.&lt;/p&gt;&lt;/div&gt;
+&lt;/dd&gt;
+&lt;dt class=&#34;hdlist1&#34;&gt;
+NumAcceptors
+&lt;/dt&gt;
+&lt;dd&gt;
+&lt;p&gt;
+The number of acceptors is the number of processes that
+will accept connections. Tweak this value to improve the
+accept rate for incoming connections.
+&lt;/p&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The ideal value is between 10 and 100 on most systems.
+Larger values may have the opposite effect and reduce the
+accept rate. It&amp;#8217;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.&lt;/p&gt;&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;This value is unrelated to the maximum number of concurrent
+connections.&lt;/p&gt;&lt;/div&gt;
+&lt;/dd&gt;
+&lt;dt class=&#34;hdlist1&#34;&gt;
+TransportOpts
+&lt;/dt&gt;
+&lt;dd&gt;
+&lt;p&gt;
+The transport options are where the TCP options, including
+the listener&amp;#8217;s port number, are defined. They also contain
+the TLS options, like the server&amp;#8217;s certificate. Transport options
+are provided as a list of keys and values, for example
+&lt;code&gt;[{port, 8443}, {certfile, &#34;path/to/cert.pem&#34;}]&lt;/code&gt;.
+&lt;/p&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The available options are documented in the
+&lt;a href=&#34;../ranch_ssl&#34;&gt;ranch_ssl(3)&lt;/a&gt; manual.&lt;/p&gt;&lt;/div&gt;
+&lt;/dd&gt;
+&lt;dt class=&#34;hdlist1&#34;&gt;
+ProtocolOpts
+&lt;/dt&gt;
+&lt;dd&gt;
+&lt;p&gt;
+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.
+&lt;/p&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;The HTTP/1.1 options are documented in the
+&lt;a href=&#34;../cowboy_http&#34;&gt;cowboy_http(3)&lt;/a&gt; manual;
+the HTTP/2 options in
+&lt;a href=&#34;../cowboy_http2&#34;&gt;cowboy_http2(3)&lt;/a&gt;;
+and the Websocket options in
+&lt;a href=&#34;../cowboy_websocket&#34;&gt;cowboy_websocket(3)&lt;/a&gt;.&lt;/p&gt;&lt;/div&gt;
+&lt;/dd&gt;
+&lt;/dl&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_return_value&#34;&gt;Return value&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;An ok tuple is returned on success. It contains the pid of
+the top-level supervisor for the listener.&lt;/p&gt;&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;An error tuple is returned on error. The error reason may
+be any Erlang term.&lt;/p&gt;&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;A common error is &lt;code&gt;eaddrinuse&lt;/code&gt;. It indicates that the port
+configured for Cowboy is already in use.&lt;/p&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_changelog&#34;&gt;Changelog&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;ulist&#34;&gt;&lt;ul&gt;
+&lt;li&gt;
+&lt;p&gt;
+&lt;strong&gt;2.0&lt;/strong&gt;: HTTP/2 support added.
+&lt;/p&gt;
+&lt;/li&gt;
+&lt;li&gt;
+&lt;p&gt;
+&lt;strong&gt;2.0&lt;/strong&gt;: Function introduced. Replaces &lt;code&gt;cowboy:start_https/4&lt;/code&gt;.
+&lt;/p&gt;
+&lt;/li&gt;
+&lt;/ul&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_examples&#34;&gt;Examples&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;listingblock&#34;&gt;
+&lt;div class=&#34;title&#34;&gt;Start a listener&lt;/div&gt;
+&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite --&gt;
+&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy_router:compile&lt;/span&gt;&lt;/span&gt;([
+    {&lt;span style=&#34;color: #FF6600&#34;&gt;&#39;_&#39;&lt;/span&gt;, [
+        {&lt;span style=&#34;color: #FF0000&#34;&gt;&#34;/&#34;&lt;/span&gt;, &lt;span style=&#34;color: #FF6600&#34;&gt;toppage_h&lt;/span&gt;, []}
+    ]}
+]),
+
+{&lt;span style=&#34;color: #FF6600&#34;&gt;ok&lt;/span&gt;, &lt;span style=&#34;color: #990000&#34;&gt;_&lt;/span&gt;} &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy:start_tls&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #FF6600&#34;&gt;example&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;100&lt;/span&gt;, [
+    {&lt;span style=&#34;color: #FF6600&#34;&gt;port&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;8443&lt;/span&gt;},
+    {&lt;span style=&#34;color: #FF6600&#34;&gt;cert&lt;/span&gt;, &lt;span style=&#34;color: #FF0000&#34;&gt;&#34;path/to/cert.pem&#34;&lt;/span&gt;}
+], #{
+    &lt;span style=&#34;color: #0000FF&#34;&gt;env&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; #{&lt;span style=&#34;color: #0000FF&#34;&gt;dispatch&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; &lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt;}
+})&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
+&lt;div class=&#34;listingblock&#34;&gt;
+&lt;div class=&#34;title&#34;&gt;Start a listener on a random port&lt;/div&gt;
+&lt;div class=&#34;content&#34;&gt;&lt;!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite --&gt;
+&lt;pre&gt;&lt;tt&gt;&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #FF6600&#34;&gt;example&lt;/span&gt;,
+
+{&lt;span style=&#34;color: #FF6600&#34;&gt;ok&lt;/span&gt;, &lt;span style=&#34;color: #990000&#34;&gt;_&lt;/span&gt;} &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;cowboy:start_tls&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt;, &lt;span style=&#34;color: #993399&#34;&gt;100&lt;/span&gt;, [
+    {&lt;span style=&#34;color: #FF6600&#34;&gt;cert&lt;/span&gt;, &lt;span style=&#34;color: #FF0000&#34;&gt;&#34;path/to/cert.pem&#34;&lt;/span&gt;}
+], #{
+    &lt;span style=&#34;color: #0000FF&#34;&gt;env&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; #{&lt;span style=&#34;color: #0000FF&#34;&gt;dispatch&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&amp;gt;&lt;/span&gt; &lt;span style=&#34;color: #009900&#34;&gt;Dispatch&lt;/span&gt;}
+}),
+
+&lt;span style=&#34;color: #009900&#34;&gt;Port&lt;/span&gt; &lt;span style=&#34;color: #990000&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;font-weight: bold&#34;&gt;&lt;span style=&#34;color: #000000&#34;&gt;ranch:get_port&lt;/span&gt;&lt;/span&gt;(&lt;span style=&#34;color: #009900&#34;&gt;Name&lt;/span&gt;)&lt;span style=&#34;color: #990000&#34;&gt;.&lt;/span&gt;&lt;/tt&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect1&#34;&gt;
+&lt;h2 id=&#34;_see_also&#34;&gt;See also&lt;/h2&gt;
+&lt;div class=&#34;sectionbody&#34;&gt;
+&lt;div class=&#34;paragraph&#34;&gt;&lt;p&gt;&lt;a href=&#34;../cowboy&#34;&gt;cowboy(3)&lt;/a&gt;,
+&lt;a href=&#34;../cowboy.start_clear&#34;&gt;cowboy:start_clear(3)&lt;/a&gt;,
+&lt;a href=&#34;../cowboy.stop_listener&#34;&gt;cowboy:stop_listener(3)&lt;/a&gt;,
+&lt;a href=&#34;../ranch&#34;&gt;ranch(3)&lt;/a&gt;&lt;/p&gt;&lt;/div&gt;
+&lt;/div&gt;
+&lt;/div&gt;
 </description>
     </item>
     
-- 
cgit v1.2.3