diff options
| author | Loïc Hoguin <[email protected]> | 2017-10-03 15:50:36 +0200 |
|---|---|---|
| committer | Loïc Hoguin <[email protected]> | 2017-10-03 15:50:36 +0200 |
| commit | 5cb08c35580023b91091c93f9a1f9198e35055c2 (patch) | |
| tree | fcac3159b52e14db41d5f1d1b19f5d8530cc0d74 /docs/en/ranch | |
| parent | 35bc482f0be143abd728a228e937984dc5f6cc73 (diff) | |
| download | ninenines.eu-5cb08c35580023b91091c93f9a1f9198e35055c2.tar.gz ninenines.eu-5cb08c35580023b91091c93f9a1f9198e35055c2.tar.bz2 ninenines.eu-5cb08c35580023b91091c93f9a1f9198e35055c2.zip | |
Fix some links and add Ranch 1.4 docs
They were mistakenly labeled as 1.3. Sorry!
Diffstat (limited to 'docs/en/ranch')
61 files changed, 6407 insertions, 70 deletions
diff --git a/docs/en/ranch/1.2/guide/embedded/index.html b/docs/en/ranch/1.2/guide/embedded/index.html index ff2cf499..5f17e1d9 100644 --- a/docs/en/ranch/1.2/guide/embedded/index.html +++ b/docs/en/ranch/1.2/guide/embedded/index.html @@ -165,6 +165,8 @@ more details on how Ranch does it.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/index.html b/docs/en/ranch/1.2/guide/index.html index cd37ce05..fe654083 100644 --- a/docs/en/ranch/1.2/guide/index.html +++ b/docs/en/ranch/1.2/guide/index.html @@ -143,6 +143,8 @@ + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/internals/index.html b/docs/en/ranch/1.2/guide/internals/index.html index 0f731816..4ad24619 100644 --- a/docs/en/ranch/1.2/guide/internals/index.html +++ b/docs/en/ranch/1.2/guide/internals/index.html @@ -206,6 +206,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/introduction/index.html b/docs/en/ranch/1.2/guide/introduction/index.html index 130721a0..2a3c9321 100644 --- a/docs/en/ranch/1.2/guide/introduction/index.html +++ b/docs/en/ranch/1.2/guide/introduction/index.html @@ -145,6 +145,8 @@ modifications but there is no guarantee that it will work as expected.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/listeners/index.html b/docs/en/ranch/1.2/guide/listeners/index.html index 83c092a0..39191182 100644 --- a/docs/en/ranch/1.2/guide/listeners/index.html +++ b/docs/en/ranch/1.2/guide/listeners/index.html @@ -404,6 +404,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/parsers/index.html b/docs/en/ranch/1.2/guide/parsers/index.html index a5d18388..02686ce4 100644 --- a/docs/en/ranch/1.2/guide/parsers/index.html +++ b/docs/en/ranch/1.2/guide/parsers/index.html @@ -226,6 +226,8 @@ immediately if any. Otherwise wait for more data.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/protocols/index.html b/docs/en/ranch/1.2/guide/protocols/index.html index dffca064..2006cb5d 100644 --- a/docs/en/ranch/1.2/guide/protocols/index.html +++ b/docs/en/ranch/1.2/guide/protocols/index.html @@ -246,6 +246,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/ssl_auth/index.html b/docs/en/ranch/1.2/guide/ssl_auth/index.html index 3261ddc4..b04dedd0 100644 --- a/docs/en/ranch/1.2/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -275,6 +275,8 @@ user.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/guide/transports/index.html b/docs/en/ranch/1.2/guide/transports/index.html index b60d99e6..1d5c681e 100644 --- a/docs/en/ranch/1.2/guide/transports/index.html +++ b/docs/en/ranch/1.2/guide/transports/index.html @@ -306,6 +306,8 @@ is the transport’s module. See <code>ranch_ssl</code> for an example.</p>< + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.2/manual/index.html b/docs/en/ranch/1.2/manual/index.html index eecb6cbe..55200d4c 100644 --- a/docs/en/ranch/1.2/manual/index.html +++ b/docs/en/ranch/1.2/manual/index.html @@ -133,6 +133,8 @@ + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch/index.html b/docs/en/ranch/1.2/manual/ranch/index.html index 2cbc5dec..3bf9b923 100644 --- a/docs/en/ranch/1.2/manual/ranch/index.html +++ b/docs/en/ranch/1.2/manual/ranch/index.html @@ -518,6 +518,8 @@ completely stopped.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_app/index.html b/docs/en/ranch/1.2/manual/ranch_app/index.html index a3f2b89c..9e8e42c9 100644 --- a/docs/en/ranch/1.2/manual/ranch_app/index.html +++ b/docs/en/ranch/1.2/manual/ranch_app/index.html @@ -138,6 +138,8 @@ and <em>total.profile</em>. Do not use in production.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_protocol/index.html b/docs/en/ranch/1.2/manual/ranch_protocol/index.html index f88fad6c..2d258978 100644 --- a/docs/en/ranch/1.2/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.2/manual/ranch_protocol/index.html @@ -178,6 +178,8 @@ processes and degrade performance severely.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html index d1b83d48..6b1fd169 100644 --- a/docs/en/ranch/1.2/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -444,6 +444,8 @@ greater control over the client certificate validation.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_tcp/index.html b/docs/en/ranch/1.2/manual/ranch_tcp/index.html index 989da87d..cccc2cd6 100644 --- a/docs/en/ranch/1.2/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.2/manual/ranch_tcp/index.html @@ -369,6 +369,8 @@ portable. Use with caution.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.2/manual/ranch_transport/index.html b/docs/en/ranch/1.2/manual/ranch_transport/index.html index fcd30741..4306cd5b 100644 --- a/docs/en/ranch/1.2/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.2/manual/ranch_transport/index.html @@ -589,6 +589,8 @@ directly.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/embedded.asciidoc b/docs/en/ranch/1.3/guide/embedded.asciidoc index 55c018b1..593a8079 100644 --- a/docs/en/ranch/1.3/guide/embedded.asciidoc +++ b/docs/en/ranch/1.3/guide/embedded.asciidoc @@ -17,7 +17,7 @@ regardless of the number of listeners you will use. Then you need to add the child specs for each listener. Ranch has a convenience function for getting the listeners child specs -called `ranch:child_spec/5`, that works like `ranch:start_listener/5`, +called `ranch:child_spec/6`, that works like `ranch:start_listener/6`, except that it doesn't start anything, it only returns child specs. As for `ranch_sup`, the child spec is simple enough to not require a diff --git a/docs/en/ranch/1.3/guide/embedded/index.html b/docs/en/ranch/1.3/guide/embedded/index.html index a1d552af..c7d2bc57 100644 --- a/docs/en/ranch/1.3/guide/embedded/index.html +++ b/docs/en/ranch/1.3/guide/embedded/index.html @@ -82,7 +82,7 @@ First, you need to add <code>ranch_sup</code> to your supervision tree, only onc regardless of the number of listeners you will use. Then you need to add the child specs for each listener.</p></div> <div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs -called <code>ranch:child_spec/5</code>, that works like <code>ranch:start_listener/5</code>, +called <code>ranch:child_spec/6</code>, that works like <code>ranch:start_listener/6</code>, except that it doesn’t start anything, it only returns child specs.</p></div> <div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a convenience function.</p></div> @@ -165,6 +165,8 @@ more details on how Ranch does it.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/index.html b/docs/en/ranch/1.3/guide/index.html index e9986a13..c3677fa1 100644 --- a/docs/en/ranch/1.3/guide/index.html +++ b/docs/en/ranch/1.3/guide/index.html @@ -143,6 +143,8 @@ + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/internals.asciidoc b/docs/en/ranch/1.3/guide/internals.asciidoc index c5bde58f..fa63f1d3 100644 --- a/docs/en/ranch/1.3/guide/internals.asciidoc +++ b/docs/en/ranch/1.3/guide/internals.asciidoc @@ -47,7 +47,7 @@ that new process. === Number of acceptors -The second argument to `ranch:start_listener/5` is the number of +The second argument to `ranch:start_listener/6` is the number of processes that will be accepting connections. Care should be taken when choosing this number. diff --git a/docs/en/ranch/1.3/guide/internals/index.html b/docs/en/ranch/1.3/guide/internals/index.html index f75bc639..85c6d7b6 100644 --- a/docs/en/ranch/1.3/guide/internals/index.html +++ b/docs/en/ranch/1.3/guide/internals/index.html @@ -110,7 +110,7 @@ that new process.</p></div> <div class="sect1"> <h2 id="_number_of_acceptors">Number of acceptors</h2> <div class="sectionbody"> -<div class="paragraph"><p>The second argument to <code>ranch:start_listener/5</code> is the number of +<div class="paragraph"><p>The second argument to <code>ranch:start_listener/6</code> is the number of processes that will be accepting connections. Care should be taken when choosing this number.</p></div> <div class="paragraph"><p>First of all, it should not be confused with the maximum number @@ -206,6 +206,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/introduction/index.html b/docs/en/ranch/1.3/guide/introduction/index.html index 9c795d8b..08d5ec07 100644 --- a/docs/en/ranch/1.3/guide/introduction/index.html +++ b/docs/en/ranch/1.3/guide/introduction/index.html @@ -147,6 +147,8 @@ modifications but there is no guarantee that it will work as expected.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/listeners.asciidoc b/docs/en/ranch/1.3/guide/listeners.asciidoc index 97afa223..1055b804 100644 --- a/docs/en/ranch/1.3/guide/listeners.asciidoc +++ b/docs/en/ranch/1.3/guide/listeners.asciidoc @@ -26,7 +26,7 @@ When starting a listener, a number of different settings are required: Ranch includes both TCP and SSL transport handlers, respectively `ranch_tcp` and `ranch_ssl`. -A listener can be started by calling the `ranch:start_listener/5` +A listener can be started by calling the `ranch:start_listener/6` function. Before doing so however, you must ensure that the `ranch` application is started. @@ -42,7 +42,7 @@ to the `echo_protocol` handler. .Starting a listener for TCP connections on port 5555 [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, +{ok, _} = ranch:start_listener(tcp_echo, 100, ranch_tcp, [{port, 5555}], echo_protocol, [] ). @@ -108,12 +108,12 @@ the port number 0, or if you omit the port number entirely, Ranch will start listening on a random port. You can retrieve this port number by calling `ranch:get_port/1`. The -argument is the name of the listener you gave in `ranch:start_listener/5`. +argument is the name of the listener you gave in `ranch:start_listener/6`. .Starting a listener for TCP connections on a random port [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, +{ok, _} = ranch:start_listener(tcp_echo, 100, ranch_tcp, [{port, 0}], echo_protocol, [] ). @@ -159,7 +159,7 @@ connections are handled optimally. .Customizing the maximum number of concurrent connections [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, +{ok, _} = ranch:start_listener(tcp_echo, 100, ranch_tcp, [{port, 5555}, {max_connections, 100}], echo_protocol, [] ). @@ -169,7 +169,7 @@ You can disable this limit by setting its value to the atom `infinity`. .Disabling the limit for the number of connections [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, +{ok, _} = ranch:start_listener(tcp_echo, 100, ranch_tcp, [{port, 5555}, {max_connections, infinity}], echo_protocol, [] ). @@ -213,24 +213,6 @@ ranch:set_max_connections(tcp_echo, MaxConns). The change will occur immediately. -=== Customizing the number of acceptor processes - -By default Ranch will use 10 acceptor processes. Their role is -to accept connections and spawn a connection process for every -new connection. - -This number can be tweaked to improve performance. A good -number is typically between 10 or 100 acceptors. You must -measure to find the best value for your application. - -.Specifying a custom number of acceptor processes - -[source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, - ranch_tcp, [{port, 5555}, {num_acceptors, 42}], - echo_protocol, [] -). - === When running out of file descriptors Operating systems have limits on the number of sockets @@ -296,7 +278,7 @@ calling `ranch:get_protocol_options/1`. [source,erlang] Opts = ranch:get_protocol_options(tcp_echo). -=== Obtaining information about listeners +=== Obtain information about listeners Ranch provides two functions for retrieving information about the listeners, for reporting and diagnostic purposes. diff --git a/docs/en/ranch/1.3/guide/listeners/index.html b/docs/en/ranch/1.3/guide/listeners/index.html index bb7f3310..f21f169e 100644 --- a/docs/en/ranch/1.3/guide/listeners/index.html +++ b/docs/en/ranch/1.3/guide/listeners/index.html @@ -105,7 +105,7 @@ A protocol handler and its associated options. </ul></div> <div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively <code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div> -<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code> +<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/6</code> function. Before doing so however, you must ensure that the <code>ranch</code> application is started.</p></div> <div class="listingblock"> @@ -124,7 +124,7 @@ to the <code>echo_protocol</code> handler.</p></div> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], <span style="color: #FF6600">echo_protocol</span>, [] )<span style="color: #990000">.</span></tt></pre></div></div> @@ -196,14 +196,14 @@ can be overriden at listener startup.</p></div> the port number 0, or if you omit the port number entirely, Ranch will start listening on a random port.</p></div> <div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The -argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div> +argument is the name of the listener you gave in <code>ranch:start_listener/6</code>.</p></div> <div class="listingblock"> <div class="title">Starting a listener for TCP connections on a random port</div> <div class="content"><!-- Generator: GNU source-highlight 3.1.8 by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}], <span style="color: #FF6600">echo_protocol</span>, [] )<span style="color: #990000">.</span> @@ -254,7 +254,7 @@ connections are handled optimally.</p></div> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}], <span style="color: #FF6600">echo_protocol</span>, [] )<span style="color: #990000">.</span></tt></pre></div></div> @@ -265,7 +265,7 @@ http://www.gnu.org/software/src-highlite --> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}], <span style="color: #FF6600">echo_protocol</span>, [] )<span style="color: #990000">.</span></tt></pre></div></div> @@ -308,27 +308,6 @@ http://www.gnu.org/software/src-highlite --> </div> </div> <div class="sect1"> -<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2> -<div class="sectionbody"> -<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is -to accept connections and spawn a connection process for every -new connection.</p></div> -<div class="paragraph"><p>This number can be tweaked to improve performance. A good -number is typically between 10 or 100 acceptors. You must -measure to find the best value for your application.</p></div> -<div class="listingblock"> -<div class="title">Specifying a custom number of acceptor processes</div> -<div class="content"><!-- Generator: GNU source-highlight 3.1.8 -by Lorenzo Bettini -http://www.lorenzobettini.it -http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, - <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}], - <span style="color: #FF6600">echo_protocol</span>, [] -)<span style="color: #990000">.</span></tt></pre></div></div> -</div> -</div> -<div class="sect1"> <h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2> <div class="sectionbody"> <div class="paragraph"><p>Operating systems have limits on the number of sockets @@ -397,7 +376,7 @@ http://www.gnu.org/software/src-highlite --> </div> </div> <div class="sect1"> -<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2> +<h2 id="_obtain_information_about_listeners">Obtain information about listeners</h2> <div class="sectionbody"> <div class="paragraph"><p>Ranch provides two functions for retrieving information about the listeners, for reporting and diagnostic purposes.</p></div> @@ -484,6 +463,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/parsers/index.html b/docs/en/ranch/1.3/guide/parsers/index.html index 41f19b7e..f0db1c8d 100644 --- a/docs/en/ranch/1.3/guide/parsers/index.html +++ b/docs/en/ranch/1.3/guide/parsers/index.html @@ -226,6 +226,8 @@ immediately if any. Otherwise wait for more data.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/protocols.asciidoc b/docs/en/ranch/1.3/guide/protocols.asciidoc index b9a31f27..48c74ef5 100644 --- a/docs/en/ranch/1.3/guide/protocols.asciidoc +++ b/docs/en/ranch/1.3/guide/protocols.asciidoc @@ -10,7 +10,7 @@ which defines a single callback, `start_link/4`. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in -the call to `ranch:start_listener/5`. This callback must +the call to `ranch:start_listener/6`. This callback must return `{ok, Pid}`, with `Pid` the pid of the new process. The newly started process can then freely initialize itself. However, diff --git a/docs/en/ranch/1.3/guide/protocols/index.html b/docs/en/ranch/1.3/guide/protocols/index.html index d42e9d7d..513602aa 100644 --- a/docs/en/ranch/1.3/guide/protocols/index.html +++ b/docs/en/ranch/1.3/guide/protocols/index.html @@ -77,7 +77,7 @@ which defines a single callback, <code>start_link/4</code>. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in -the call to <code>ranch:start_listener/5</code>. This callback must +the call to <code>ranch:start_listener/6</code>. This callback must return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div> <div class="paragraph"><p>The newly started process can then freely initialize itself. However, it must call <code>ranch:accept_ack/1</code> before doing any socket operation. @@ -221,6 +221,8 @@ http://www.gnu.org/software/src-highlite --> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/ssl_auth.asciidoc b/docs/en/ranch/1.3/guide/ssl_auth.asciidoc index de16107a..de0bbaf0 100644 --- a/docs/en/ranch/1.3/guide/ssl_auth.asciidoc +++ b/docs/en/ranch/1.3/guide/ssl_auth.asciidoc @@ -49,7 +49,7 @@ the listener to enable this behavior. .Configure a listener for SSL authentication [source,erlang] -{ok, _} = ranch:start_listener(my_ssl, +{ok, _} = ranch:start_listener(my_ssl, 100, ranch_ssl, [ {port, SSLPort}, {certfile, PathToCertfile}, diff --git a/docs/en/ranch/1.3/guide/ssl_auth/index.html b/docs/en/ranch/1.3/guide/ssl_auth/index.html index 3cc585f2..ca934db0 100644 --- a/docs/en/ranch/1.3/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.3/guide/ssl_auth/index.html @@ -152,7 +152,7 @@ the listener to enable this behavior.</p></div> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, <span style="color: #993399">100</span>, <span style="color: #FF6600">ranch_ssl</span>, [ {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>}, {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>}, @@ -275,6 +275,8 @@ user.</p></div> + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/guide/transports/index.html b/docs/en/ranch/1.3/guide/transports/index.html index 1b13c696..d5130ec0 100644 --- a/docs/en/ranch/1.3/guide/transports/index.html +++ b/docs/en/ranch/1.3/guide/transports/index.html @@ -296,6 +296,8 @@ is the transport’s module. See <code>ranch_ssl</code> for an example.</p>< + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> diff --git a/docs/en/ranch/1.3/manual/index.html b/docs/en/ranch/1.3/manual/index.html index c0d63cf2..d506129d 100644 --- a/docs/en/ranch/1.3/manual/index.html +++ b/docs/en/ranch/1.3/manual/index.html @@ -133,6 +133,8 @@ + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.3/manual/ranch/index.html b/docs/en/ranch/1.3/manual/ranch/index.html index b8b4b35d..fc67cf1d 100644 --- a/docs/en/ranch/1.3/manual/ranch/index.html +++ b/docs/en/ranch/1.3/manual/ranch/index.html @@ -102,7 +102,6 @@ http://www.gnu.org/software/src-highlite --> <pre><tt><span style="font-weight: bold"><span style="color: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>} | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()} - | {<span style="color: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()} | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>} | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> <div class="paragraph"><p>Ranch-specific transport options.</p></div> @@ -145,14 +144,6 @@ max_connections (1024) </p> </dd> <dt class="hdlist1"> -num_acceptors (10) -</dt> -<dd> -<p> - Number of processes that accept connections. -</p> -</dd> -<dt class="hdlist1"> shutdown (5000) </dt> <dd> @@ -662,6 +653,8 @@ completely stopped.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.3/manual/ranch_app/index.html b/docs/en/ranch/1.3/manual/ranch_app/index.html index 2ad98222..f0651f7f 100644 --- a/docs/en/ranch/1.3/manual/ranch_app/index.html +++ b/docs/en/ranch/1.3/manual/ranch_app/index.html @@ -136,6 +136,8 @@ and <em>total.profile</em>. Do not use in production.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.3/manual/ranch_protocol/index.html b/docs/en/ranch/1.3/manual/ranch_protocol/index.html index ce82c3f0..f7e1f5a1 100644 --- a/docs/en/ranch/1.3/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.3/manual/ranch_protocol/index.html @@ -178,6 +178,8 @@ processes and degrade performance severely.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.3/manual/ranch_ssl/index.html b/docs/en/ranch/1.3/manual/ranch_ssl/index.html index 3a466dee..db8170d6 100644 --- a/docs/en/ranch/1.3/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.3/manual/ranch_ssl/index.html @@ -480,6 +480,8 @@ greater control over the client certificate validation.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.3/manual/ranch_tcp/index.html b/docs/en/ranch/1.3/manual/ranch_tcp/index.html index 60574604..135c5e2f 100644 --- a/docs/en/ranch/1.3/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.3/manual/ranch_tcp/index.html @@ -378,6 +378,8 @@ portable. Use with caution.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.3/manual/ranch_transport/index.html b/docs/en/ranch/1.3/manual/ranch_transport/index.html index 8840daad..9f74761f 100644 --- a/docs/en/ranch/1.3/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.3/manual/ranch_transport/index.html @@ -589,6 +589,8 @@ directly.</p></div> + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> diff --git a/docs/en/ranch/1.4/guide/embedded.asciidoc b/docs/en/ranch/1.4/guide/embedded.asciidoc new file mode 100644 index 00000000..55c018b1 --- /dev/null +++ b/docs/en/ranch/1.4/guide/embedded.asciidoc @@ -0,0 +1,48 @@ +== Embedded mode + +Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa. + +=== Embedding + +To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the `init/1` function +of one of your application supervisors. + +Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add `ranch_sup` to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener. + +Ranch has a convenience function for getting the listeners child specs +called `ranch:child_spec/5`, that works like `ranch:start_listener/5`, +except that it doesn't start anything, it only returns child specs. + +As for `ranch_sup`, the child spec is simple enough to not require a +convenience function. + +The following example adds both `ranch_sup` and one listener to another +application's supervision tree. + +.Embed Ranch directly in your supervision tree + +[source,erlang] +---- +init([]) -> + RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []}, + permanent, 5000, supervisor, [ranch_sup]}, + ListenerSpec = ranch:child_spec(echo, 100, + ranch_tcp, [{port, 5555}], + echo_protocol, [] + ), + {ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}. +---- + +Remember, you can add as many listener child specs as needed, but only +one `ranch_sup` spec! + +It is recommended that your architecture makes sure that all listeners +are restarted if `ranch_sup` fails. See the Ranch internals chapter for +more details on how Ranch does it. diff --git a/docs/en/ranch/1.4/guide/embedded/index.html b/docs/en/ranch/1.4/guide/embedded/index.html new file mode 100644 index 00000000..0b99dd05 --- /dev/null +++ b/docs/en/ranch/1.4/guide/embedded/index.html @@ -0,0 +1,205 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Embedded mode</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Embedded mode</span></h1> + +<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa.</p></div> +<div class="sect1"> +<h2 id="_embedding">Embedding</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the <code>init/1</code> function +of one of your application supervisors.</p></div> +<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add <code>ranch_sup</code> to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener.</p></div> +<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs +called <code>ranch:child_spec/5</code>, that works like <code>ranch:start_listener/5</code>, +except that it doesn’t start anything, it only returns child specs.</p></div> +<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a +convenience function.</p></div> +<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another +application’s supervision tree.</p></div> +<div class="listingblock"> +<div class="title">Embed Ranch directly in your supervision tree</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>([]) <span style="color: #990000">-></span> + <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []}, + <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]}, + <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] + ), + {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only +one <code>ranch_sup</code> spec!</p></div> +<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners +are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for +more details on how Ranch does it.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.4/guide/protocols/"> + Protocols + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.4/guide/parsers/"> + Writing parsers + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/index.html b/docs/en/ranch/1.4/guide/index.html new file mode 100644 index 00000000..f500390e --- /dev/null +++ b/docs/en/ranch/1.4/guide/index.html @@ -0,0 +1,183 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Ranch User Guide</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Ranch User Guide</span></h1> + +<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="listeners/">Listeners</a> +</p> +</li> +<li> +<p> +<a href="transports/">Transports</a> +</p> +</li> +<li> +<p> +<a href="protocols/">Protocols</a> +</p> +</li> +<li> +<p> +<a href="embedded/">Embedded mode</a> +</p> +</li> +<li> +<p> +<a href="parsers/">Writing parsers</a> +</p> +</li> +<li> +<p> +<a href="ssl_auth/">SSL client authentication</a> +</p> +</li> +<li> +<p> +<a href="internals/">Internals</a> +</p> +</li> +</ul></div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/internals.asciidoc b/docs/en/ranch/1.4/guide/internals.asciidoc new file mode 100644 index 00000000..c5bde58f --- /dev/null +++ b/docs/en/ranch/1.4/guide/internals.asciidoc @@ -0,0 +1,94 @@ +== Internals + +This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application. + +Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system. + +=== Architecture + +Ranch is an OTP application. + +Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the `ranch_server` process and all the listeners that +will be started. + +The `ranch_server` gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called `ranch_server`. The table is owned by the top supervisor +to improve fault tolerance. This way if the `ranch_server` gen_server +fails, it doesn't lose any information and the restarted process can +continue as if nothing happened. + +Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual `sys` and `supervisor` calls will work on +it as expected. + +Listeners are grouped into the `ranch_listener_sup` supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +`ranch_server` gen_server with varying amount of information. + +All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process. + +=== Number of acceptors + +The second argument to `ranch:start_listener/5` is the number of +processes that will be accepting connections. Care should be taken +when choosing this number. + +First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down. + +Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn't +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however. + +Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it's big enough to always have acceptors ready +and it's low enough that it doesn't have a negative impact on the +system's performances. + +=== Platform-specific TCP features + +Some socket options are platform-specific and not supported by `inet`. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the `raw` option, for which we will see an example. + +One of these features is `TCP_DEFER_ACCEPT` on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process. + +This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections. + +To enable this mechanism, the following option can be used. + +.Using raw transport options + +[source,erlang] +{raw, 6, 9, << 30:32/native >>} + +It means go on layer 6, turn on option 9 with the given integer parameter. diff --git a/docs/en/ranch/1.4/guide/internals/index.html b/docs/en/ranch/1.4/guide/internals/index.html new file mode 100644 index 00000000..e45a609e --- /dev/null +++ b/docs/en/ranch/1.4/guide/internals/index.html @@ -0,0 +1,246 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Internals</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Internals</span></h1> + +<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application.</p></div> +<div class="paragraph"><p>Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system.</p></div> +<div class="sect1"> +<h2 id="_architecture">Architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is an OTP application.</p></div> +<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the <code>ranch_server</code> process and all the listeners that +will be started.</p></div> +<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called <code>ranch_server</code>. The table is owned by the top supervisor +to improve fault tolerance. This way if the <code>ranch_server</code> gen_server +fails, it doesn’t lose any information and the restarted process can +continue as if nothing happened.</p></div> +<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on +it as expected.</p></div> +<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +<code>ranch_server</code> gen_server with varying amount of information.</p></div> +<div class="paragraph"><p>All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_number_of_acceptors">Number of acceptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The second argument to <code>ranch:start_listener/5</code> is the number of +processes that will be accepting connections. Care should be taken +when choosing this number.</p></div> +<div class="paragraph"><p>First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down.</p></div> +<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn’t +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however.</p></div> +<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it’s big enough to always have acceptors ready +and it’s low enough that it doesn’t have a negative impact on the +system’s performances.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the <code>raw</code> option, for which we will see an example.</p></div> +<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process.</p></div> +<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections.</p></div> +<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div> +<div class="listingblock"> +<div class="title">Using raw transport options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div> +<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.4/guide/ssl_auth/"> + SSL client authentication + </a> + + + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/introduction.asciidoc b/docs/en/ranch/1.4/guide/introduction.asciidoc new file mode 100644 index 00000000..ac27862e --- /dev/null +++ b/docs/en/ranch/1.4/guide/introduction.asciidoc @@ -0,0 +1,28 @@ +== Introduction + +Ranch is a socket acceptor pool for TCP protocols. + +Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own. + +=== Prerequisites + +It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols. + +=== Supported platforms + +Ranch is tested and supported on Linux, FreeBSD, OSX and Windows. + +Ranch is developed for Erlang/OTP R16B+. + +There are known issues with the SSL application found in Erlang/OTP +18.3.2 and 18.3.3. These versions are therefore not supported. + +Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected. + +=== Versioning + +Ranch uses http://semver.org/[Semantic Versioning 2.0.0] diff --git a/docs/en/ranch/1.4/guide/introduction/index.html b/docs/en/ranch/1.4/guide/introduction/index.html new file mode 100644 index 00000000..c7023a3c --- /dev/null +++ b/docs/en/ranch/1.4/guide/introduction/index.html @@ -0,0 +1,187 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Introduction</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Introduction</span></h1> + +<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div> +<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supported_platforms">Supported platforms</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.</p></div> +<div class="paragraph"><p>Ranch is developed for Erlang/OTP R16B+.</p></div> +<div class="paragraph"><p>There are known issues with the SSL application found in Erlang/OTP +18.3.2 and 18.3.3. These versions are therefore not supported.</p></div> +<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.4/guide/listeners/"> + Listeners + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/listeners.asciidoc b/docs/en/ranch/1.4/guide/listeners.asciidoc new file mode 100644 index 00000000..97afa223 --- /dev/null +++ b/docs/en/ranch/1.4/guide/listeners.asciidoc @@ -0,0 +1,320 @@ +== Listeners + +A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the use of transport handlers. + +The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application. + +=== Starting a listener + +Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections. + +A listener can be started and stopped at will. + +When starting a listener, a number of different settings are required: + +* A name to identify it locally and be able to interact with it. +* The number of acceptors in the pool. +* A transport handler and its associated options. +* A protocol handler and its associated options. + +Ranch includes both TCP and SSL transport handlers, respectively +`ranch_tcp` and `ranch_ssl`. + +A listener can be started by calling the `ranch:start_listener/5` +function. Before doing so however, you must ensure that the `ranch` +application is started. + +.Starting the Ranch application + +[source,erlang] +ok = application:start(ranch). + +You are then ready to start a listener. Let's call it `tcp_echo`. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the `echo_protocol` handler. + +.Starting a listener for TCP connections on port 5555 + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, [{port, 5555}], + echo_protocol, [] +). + +You can try this out by compiling and running the `tcp_echo` example in the +examples directory. To do so, open a shell in the 'examples/tcp_echo/' +directory and run the following command: + +.Building and starting a Ranch example + +[source,bash] +$ make run + +You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you're done testing, you can use +the `Ctrl+]` key to escape to the telnet command line and type +`quit` to exit. + +.Connecting to the example listener with telnet + +[source,bash] +---- +$ telnet localhost 5555 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +Hello! +Hello! +It works! +It works! +^] + +telnet> quit +Connection closed. +---- + +=== Stopping a listener + +All you need to stop a Ranch listener is to call the +`ranch:stop_listener/1` function with the listener's name +as argument. In the previous section we started the listener +named `tcp_echo`. We can now stop it. + +.Stopping a listener + +[source,erlang] +ranch:stop_listener(tcp_echo). + +=== Default transport options + +By default the socket will be set to return `binary` data, with the +options `{active, false}`, `{packet, raw}`, `{reuseaddr, true}` set. +These values can't be overriden when starting the listener, but +they can be overriden using `Transport:setopts/2` in the protocol. + +It will also set `{backlog, 1024}` and `{nodelay, true}`, which +can be overriden at listener startup. + +=== Listening on a random port + +You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port. + +You can retrieve this port number by calling `ranch:get_port/1`. The +argument is the name of the listener you gave in `ranch:start_listener/5`. + +.Starting a listener for TCP connections on a random port + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, [{port, 0}], + echo_protocol, [] +). +Port = ranch:get_port(tcp_echo). + +=== Listening on privileged ports + +Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an `{error, eacces}` error when trying +to open a listening socket on such a port. + +The methods for listening on privileged ports vary between systems, +please refer to your system's documentation for more information. + +We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide. + +=== Accepting connections on an existing socket + +If you want to accept connections on an existing socket, you can use the +`socket` transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(`gen_tcp:connect`, `ssl:connect`). The accept function will then be +called on the passed in socket. You should connect the socket in +`{active, false}` mode, as well. + +Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process. + +=== Limiting the number of concurrent connections + +The `max_connections` transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally. + +.Customizing the maximum number of concurrent connections + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, [{port, 5555}, {max_connections, 100}], + echo_protocol, [] +). + +You can disable this limit by setting its value to the atom `infinity`. + +.Disabling the limit for the number of connections + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, [{port, 5555}, {max_connections, infinity}], + echo_protocol, [] +). + +The maximum number of connections is a soft limit. In practice, it +can reach `max_connections` + the number of acceptors. + +When the maximum number of connections is reached, Ranch will stop +accepting connections. This will not result in further connections +being rejected, as the kernel option allows queueing incoming +connections. The size of this queue is determined by the `backlog` +option and defaults to 1024. Ranch does not know about the number +of connections that are in the backlog. + +You may not always want connections to be counted when checking for +`max_connections`. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don't consume +much resources and can safely be removed from the count. + +To remove the connection from the count, you must call the +`ranch:remove_connection/1` from within the connection process, +with the name of the listener as the only argument. + +.Removing a connection from the count of connections + +[source,erlang] +ranch:remove_connection(Ref). + +As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol's `start_link/4` callback. + +You can modify the `max_connections` value on a running listener by +using the `ranch:set_max_connections/2` function, with the name of the +listener as first argument and the new value as the second. + +.Upgrading the maximum number of connections + +[source,erlang] +ranch:set_max_connections(tcp_echo, MaxConns). + +The change will occur immediately. + +=== Customizing the number of acceptor processes + +By default Ranch will use 10 acceptor processes. Their role is +to accept connections and spawn a connection process for every +new connection. + +This number can be tweaked to improve performance. A good +number is typically between 10 or 100 acceptors. You must +measure to find the best value for your application. + +.Specifying a custom number of acceptor processes + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, [{port, 5555}, {num_acceptors, 42}], + echo_protocol, [] +). + +=== When running out of file descriptors + +Operating systems have limits on the number of sockets +which can be opened by applications. When this maximum is +reached the listener can no longer accept new connections. The +accept rate of the listener will be automatically reduced, and a +warning message will be logged. + +---- +=ERROR REPORT==== 13-Jan-2016::12:24:38 === +Ranch acceptor reducing accept rate: out of file descriptors +---- + +If you notice messages like this you should increase the number +of file-descriptors which can be opened by your application. How +this should be done is operating-system dependent. Please consult +the documentation of your operating system. + +=== Using a supervisor for connection processes + +Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a `worker`. +When the `connection_type` configuration value is set to `supervisor`, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree. + +Connection processes of type `supervisor` can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket). + +Instead of returning `{ok, ConnPid}`, simply return +`{ok, SupPid, ConnPid}`. + +It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped. + +=== Upgrading + +Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections. + +To upgrade the protocol options, call `ranch:set_protocol_options/2` +with the name of the listener as first argument and the new options +as the second. + +.Upgrading the protocol options + +[source,erlang] +ranch:set_protocol_options(tcp_echo, NewOpts). + +All future connections will use the new options. + +You can also retrieve the current options similarly by +calling `ranch:get_protocol_options/1`. + +.Retrieving the current protocol options + +[source,erlang] +Opts = ranch:get_protocol_options(tcp_echo). + +=== Obtaining information about listeners + +Ranch provides two functions for retrieving information about the +listeners, for reporting and diagnostic purposes. + +The `ranch:info/0` function will return detailed information +about all listeners. + +.Retrieving detailed information +[source,erlang] +ranch:info(). + +The `ranch:procs/2` function will return all acceptor or listener +processes for a given listener. + +.Get all acceptor processes +[source,erlang] +ranch:procs(tcp_echo, acceptors). + +.Get all connection processes +[source,erlang] +ranch:procs(tcp_echo, connections). diff --git a/docs/en/ranch/1.4/guide/listeners/index.html b/docs/en/ranch/1.4/guide/listeners/index.html new file mode 100644 index 00000000..3f0b0710 --- /dev/null +++ b/docs/en/ranch/1.4/guide/listeners/index.html @@ -0,0 +1,524 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Listeners</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Listeners</span></h1> + +<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the use of transport handlers.</p></div> +<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application.</p></div> +<div class="sect1"> +<h2 id="_starting_a_listener">Starting a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections.</p></div> +<div class="paragraph"><p>A listener can be started and stopped at will.</p></div> +<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div> +<div class="ulist"><ul> +<li> +<p> +A name to identify it locally and be able to interact with it. +</p> +</li> +<li> +<p> +The number of acceptors in the pool. +</p> +</li> +<li> +<p> +A transport handler and its associated options. +</p> +</li> +<li> +<p> +A protocol handler and its associated options. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively +<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div> +<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code> +function. Before doing so however, you must ensure that the <code>ranch</code> +application is started.</p></div> +<div class="listingblock"> +<div class="title">Starting the Ranch application</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the <code>echo_protocol</code> handler.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on port 5555</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the +examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em> +directory and run the following command:</p></div> +<div class="listingblock"> +<div class="title">Building and starting a Ranch example</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ make run</tt></pre></div></div> +<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you’re done testing, you can use +the <code>Ctrl+]</code> key to escape to the telnet command line and type +<code>quit</code> to exit.</p></div> +<div class="listingblock"> +<div class="title">Connecting to the example listener with telnet</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ telnet localhost <span style="color: #993399">5555</span> +Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span> +Connected to localhost<span style="color: #990000">.</span> +Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span> +Hello<span style="color: #990000">!</span> +Hello<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +<span style="color: #990000">^]</span> + +telnet<span style="color: #990000">></span> quit +Connection closed<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stopping_a_listener">Stopping a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All you need to stop a Ranch listener is to call the +<code>ranch:stop_listener/1</code> function with the listener’s name +as argument. In the previous section we started the listener +named <code>tcp_echo</code>. We can now stop it.</p></div> +<div class="listingblock"> +<div class="title">Stopping a listener</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_default_transport_options">Default transport options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the +options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set. +These values can’t be overriden when starting the listener, but +they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div> +<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which +can be overriden at listener startup.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_a_random_port">Listening on a random port</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port.</p></div> +<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The +argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on a random port</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span> +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an <code>{error, eacces}</code> error when trying +to open a listening socket on such a port.</p></div> +<div class="paragraph"><p>The methods for listening on privileged ports vary between systems, +please refer to your system’s documentation for more information.</p></div> +<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the +<code>socket</code> transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be +called on the passed in socket. You should connect the socket in +<code>{active, false}</code> mode, as well.</p></div> +<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally.</p></div> +<div class="listingblock"> +<div class="title">Customizing the maximum number of concurrent connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div> +<div class="listingblock"> +<div class="title">Disabling the limit for the number of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The maximum number of connections is a soft limit. In practice, it +can reach <code>max_connections</code> + the number of acceptors.</p></div> +<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop +accepting connections. This will not result in further connections +being rejected, as the kernel option allows queueing incoming +connections. The size of this queue is determined by the <code>backlog</code> +option and defaults to 1024. Ranch does not know about the number +of connections that are in the backlog.</p></div> +<div class="paragraph"><p>You may not always want connections to be counted when checking for +<code>max_connections</code>. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don’t consume +much resources and can safely be removed from the count.</p></div> +<div class="paragraph"><p>To remove the connection from the count, you must call the +<code>ranch:remove_connection/1</code> from within the connection process, +with the name of the listener as the only argument.</p></div> +<div class="listingblock"> +<div class="title">Removing a connection from the count of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol’s <code>start_link/4</code> callback.</p></div> +<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by +using the <code>ranch:set_max_connections/2</code> function, with the name of the +listener as first argument and the new value as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the maximum number of connections</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The change will occur immediately.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is +to accept connections and spawn a connection process for every +new connection.</p></div> +<div class="paragraph"><p>This number can be tweaked to improve performance. A good +number is typically between 10 or 100 acceptors. You must +measure to find the best value for your application.</p></div> +<div class="listingblock"> +<div class="title">Specifying a custom number of acceptor processes</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Operating systems have limits on the number of sockets +which can be opened by applications. When this maximum is +reached the listener can no longer accept new connections. The +accept rate of the listener will be automatically reduced, and a +warning message will be logged.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 === +Ranch acceptor reducing accept rate: out of file descriptors</code></pre> +</div></div> +<div class="paragraph"><p>If you notice messages like this you should increase the number +of file-descriptors which can be opened by your application. How +this should be done is operating-system dependent. Please consult +the documentation of your operating system.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a <code>worker</code>. +When the <code>connection_type</code> configuration value is set to <code>supervisor</code>, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree.</p></div> +<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket).</p></div> +<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return +<code>{ok, SupPid, ConnPid}</code>.</p></div> +<div class="paragraph"><p>It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading">Upgrading</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections.</p></div> +<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code> +with the name of the listener as first argument and the new options +as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the protocol options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All future connections will use the new options.</p></div> +<div class="paragraph"><p>You can also retrieve the current options similarly by +calling <code>ranch:get_protocol_options/1</code>.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the current protocol options</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch provides two functions for retrieving information about the +listeners, for reporting and diagnostic purposes.</p></div> +<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information +about all listeners.</p></div> +<div class="listingblock"> +<div class="title">Retrieving detailed information</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener +processes for a given listener.</p></div> +<div class="listingblock"> +<div class="title">Get all acceptor processes</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get all connection processes</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.4/guide/introduction/"> + Introduction + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.4/guide/transports/"> + Transports + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/parsers.asciidoc b/docs/en/ranch/1.4/guide/parsers.asciidoc new file mode 100644 index 00000000..9eacbfa9 --- /dev/null +++ b/docs/en/ranch/1.4/guide/parsers.asciidoc @@ -0,0 +1,92 @@ +== Writing parsers + +There are three kinds of protocols: + +* Text protocols +* Schema-less binary protocols +* Schema-based binary protocols + +This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators. + +This chapter isn't specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn't been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two. + +=== Parsing text + +Text protocols are generally line based. This means that we can't +do anything with them until we receive the full line. + +A simple way to get a full line is to use `binary:split/{2,3}`. + +.Using binary:split/2 to get a line of input + +[source,erlang] +case binary:split(Buffer, <<"\n">>) of + [_] -> + get_more_data(Buffer); + [Line, Rest] -> + handle_line(Line, Rest) +end. + +In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket. + +Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string. + +.Using binary:split/3 to split text + +[source,erlang] +case binary:split(Line, <<" ">>, [global]) of + [<<"HELLO">>] -> + be_polite(); + [<<"AUTH">>, User, Password] -> + authenticate_user(User, Password); + [<<"QUIT">>, Reason] -> + quit(Reason) + %% ... +end. + +Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions. + +After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data. + +=== Parsing binary + +Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters. + +Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian. + +The general idea stays the same though. + +.Using binary pattern matching to split frames + +[source,erlang] +<< Size:32, _/bits >> = Buffer, +case Buffer of + << Frame:Size/binary, Rest/bits >> -> + handle_frame(Frame, Rest); + _ -> + get_more_data(Buffer) +end. + +You will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data. diff --git a/docs/en/ranch/1.4/guide/parsers/index.html b/docs/en/ranch/1.4/guide/parsers/index.html new file mode 100644 index 00000000..c663bad3 --- /dev/null +++ b/docs/en/ranch/1.4/guide/parsers/index.html @@ -0,0 +1,266 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Writing parsers</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Writing parsers</span></h1> + +<div class="paragraph"><p>There are three kinds of protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +Text protocols +</p> +</li> +<li> +<p> +Schema-less binary protocols +</p> +</li> +<li> +<p> +Schema-based binary protocols +</p> +</li> +</ul></div> +<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators.</p></div> +<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn’t been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two.</p></div> +<div class="sect1"> +<h2 id="_parsing_text">Parsing text</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t +do anything with them until we receive the full line.</p></div> +<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/2 to get a line of input</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000">_</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>); + [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>) +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket.</p></div> +<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/3 to split text</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>(); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-style: italic"><span style="color: #9A1900">%% ...</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions.</p></div> +<div class="paragraph"><p>After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_parsing_binary">Parsing binary</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters.</p></div> +<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian.</p></div> +<div class="paragraph"><p>The general idea stays the same though.</p></div> +<div class="listingblock"> +<div class="title">Using binary pattern matching to split frames</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>, +<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>) +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.4/guide/embedded/"> + Embedded mode + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.4/guide/ssl_auth/"> + SSL client authentication + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/protocols.asciidoc b/docs/en/ranch/1.4/guide/protocols.asciidoc new file mode 100644 index 00000000..b9a31f27 --- /dev/null +++ b/docs/en/ranch/1.4/guide/protocols.asciidoc @@ -0,0 +1,99 @@ +== Protocols + +A protocol handler starts a connection process and defines the +protocol logic executed in this process. + +=== Writing a protocol handler + +All protocol handlers must implement the `ranch_protocol` behavior +which defines a single callback, `start_link/4`. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to `ranch:start_listener/5`. This callback must +return `{ok, Pid}`, with `Pid` the pid of the new process. + +The newly started process can then freely initialize itself. However, +it must call `ranch:accept_ack/1` before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener's name as argument. + +.Acknowledge accepting the socket + +[source,erlang] +ok = ranch:accept_ack(Ref). + +If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling `ranch:accept_ack/1`. You can use `Transport:setopts/2` +for that purpose. + +Following is the complete protocol code for the example found +in `examples/tcp_echo/`. + +.Protocol module that echoes everything it receives + +[source,erlang] +---- +-module(echo_protocol). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/4]). + +start_link(Ref, Socket, Transport, Opts) -> + Pid = spawn_link(?MODULE, init, [Ref, Socket, Transport, Opts]), + {ok, Pid}. + +init(Ref, Socket, Transport, _Opts = []) -> + ok = ranch:accept_ack(Ref), + loop(Socket, Transport). + +loop(Socket, Transport) -> + case Transport:recv(Socket, 0, 5000) of + {ok, Data} -> + Transport:send(Socket, Data), + loop(Socket, Transport); + _ -> + ok = Transport:close(Socket) + end. +---- + +=== Using gen_server + +Special processes like the ones that use the `gen_server` or `gen_fsm` +behaviours have the particularity of having their `start_link` call not +return until the `init` function returns. This is problematic, because +you won't be able to call `ranch:accept_ack/1` from the `init` callback +as this would cause a deadlock to happen. + +Use the `gen_server:enter_loop/3` function. It allows you to start your process +normally (although it must be started with `proc_lib` like all special +processes), then perform any needed operations before falling back into +the normal `gen_server` execution loop. + +.Use a gen_server for protocol handling + +[source,erlang] +---- +-module(my_protocol). +-behaviour(gen_server). +-behaviour(ranch_protocol). + +-export([start_link/4]). +-export([init/1]). +%% Exports of other gen_server callbacks here. + +start_link(Ref, Socket, Transport, Opts) -> + {ok, proc_lib:spawn_link(?MODULE, init, [{Ref, Socket, Transport, Opts}])}. + +init({Ref, Socket, Transport, _Opts = []}) -> + %% Perform any required state initialization here. + ok = ranch:accept_ack(Ref), + ok = Transport:setopts(Socket, [{active, once}]), + gen_server:enter_loop(?MODULE, [], {state, Socket, Transport}). + +%% Other gen_server callbacks here. +---- + +Check the `tcp_reverse` example for a complete example. diff --git a/docs/en/ranch/1.4/guide/protocols/index.html b/docs/en/ranch/1.4/guide/protocols/index.html new file mode 100644 index 00000000..eef4ca91 --- /dev/null +++ b/docs/en/ranch/1.4/guide/protocols/index.html @@ -0,0 +1,261 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Protocols</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Protocols</span></h1> + +<div class="paragraph"><p>A protocol handler starts a connection process and defines the +protocol logic executed in this process.</p></div> +<div class="sect1"> +<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior +which defines a single callback, <code>start_link/4</code>. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to <code>ranch:start_listener/5</code>. This callback must +return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div> +<div class="paragraph"><p>The newly started process can then freely initialize itself. However, +it must call <code>ranch:accept_ack/1</code> before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener’s name as argument.</p></div> +<div class="listingblock"> +<div class="title">Acknowledge accepting the socket</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code> +for that purpose.</p></div> +<div class="paragraph"><p>Following is the complete protocol code for the example found +in <code>examples/tcp_echo/</code>.</p></div> +<div class="listingblock"> +<div class="title">Protocol module that echoes everything it receives</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_gen_server">Using gen_server</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code> +behaviours have the particularity of having their <code>start_link</code> call not +return until the <code>init</code> function returns. This is problematic, because +you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback +as this would cause a deadlock to happen.</p></div> +<div class="paragraph"><p>Use the <code>gen_server:enter_loop/3</code> function. It allows you to start your process +normally (although it must be started with <code>proc_lib</code> like all special +processes), then perform any needed operations before falling back into +the normal <code>gen_server</code> execution loop.</p></div> +<div class="listingblock"> +<div class="title">Use a gen_server for protocol handling</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>])<span style="color: #990000">.</span> +<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">proc_lib:spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [{<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>}])}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>({<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []}) <span style="color: #990000">-></span> + <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), + <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div> +<div class="paragraph"><p>Check the <code>tcp_reverse</code> example for a complete example.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.4/guide/transports/"> + Transports + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.4/guide/embedded/"> + Embedded mode + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/ssl_auth.asciidoc b/docs/en/ranch/1.4/guide/ssl_auth.asciidoc new file mode 100644 index 00000000..de16107a --- /dev/null +++ b/docs/en/ranch/1.4/guide/ssl_auth.asciidoc @@ -0,0 +1,120 @@ +== SSL client authentication + +=== Purpose + +SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security. + +The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate. + +As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of `Transport:name/0`. + +=== Obtaining client certificates + +You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free. + +Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser. + +* Open http://cacert.org in your favorite browser +* Root Certificate link: install both certificates +* Join (Register an account) +* Verify your account (check your email inbox!) +* Log in +* Client Certificates: New +* Follow instructions to create the certificate +* Install the certificate in your browser + +You can optionally save the certificate for later use, for example +to extract the `IssuerID` information as will be detailed later on. + +=== Transport configuration + +The SSL transport does not request a client certificate by default. +You need to specify the `{verify, verify_peer}` option when starting +the listener to enable this behavior. + +.Configure a listener for SSL authentication + +[source,erlang] +{ok, _} = ranch:start_listener(my_ssl, + ranch_ssl, [ + {port, SSLPort}, + {certfile, PathToCertfile}, + {cacertfile, PathToCACertfile}, + {verify, verify_peer} + ], + my_protocol, [] +). + +In this example we set the required `port` and `certfile`, but also +the `cacertfile` containing the CACert.org root certificate, and +the option to request the client certificate. + +If you enable the `{verify, verify_peer}` option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients. + +=== Authentication + +To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly. + +.Retrieve the issuer ID from a certificate + +[source,erlang] +---- +certfile_to_issuer_id(Filename) -> + {ok, Data} = file:read_file(Filename), + [{'Certificate', Cert, not_encrypted}] = public_key:pem_decode(Data), + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID. +---- + +The `IssuerID` variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved. + +To retrieve the `IssuerID` from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the `ssl:peercert/1` function. Once you have the +certificate, you can again use the `public_key:pkix_issuer_id/2` to +extract the `IssuerID` value. + +The following function returns the `IssuerID` or `false` if no client +certificate was found. This snippet is intended to be used from your +protocol code. + +.Retrieve the issuer ID from the certificate for the current connection + +[source,erlang] +---- +socket_to_issuer_id(Socket) -> + case ssl:peercert(Socket) of + {error, no_peercert} -> + false; + {ok, Cert} -> + {ok, IssuerID} = public_key:pkix_issuer_id(Cert, self), + IssuerID + end. +---- + +You then only need to match the `IssuerID` value to authenticate the +user. diff --git a/docs/en/ranch/1.4/guide/ssl_auth/index.html b/docs/en/ranch/1.4/guide/ssl_auth/index.html new file mode 100644 index 00000000..d57afa20 --- /dev/null +++ b/docs/en/ranch/1.4/guide/ssl_auth/index.html @@ -0,0 +1,315 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: SSL client authentication</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>SSL client authentication</span></h1> + +<div class="sect1"> +<h2 id="_purpose">Purpose</h2> +<div class="sectionbody"> +<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security.</p></div> +<div class="paragraph"><p>The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate.</p></div> +<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of <code>Transport:name/0</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free.</p></div> +<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser.</p></div> +<div class="ulist"><ul> +<li> +<p> +Open <a href="http://cacert.org">http://cacert.org</a> in your favorite browser +</p> +</li> +<li> +<p> +Root Certificate link: install both certificates +</p> +</li> +<li> +<p> +Join (Register an account) +</p> +</li> +<li> +<p> +Verify your account (check your email inbox!) +</p> +</li> +<li> +<p> +Log in +</p> +</li> +<li> +<p> +Client Certificates: New +</p> +</li> +<li> +<p> +Follow instructions to create the certificate +</p> +</li> +<li> +<p> +Install the certificate in your browser +</p> +</li> +</ul></div> +<div class="paragraph"><p>You can optionally save the certificate for later use, for example +to extract the <code>IssuerID</code> information as will be detailed later on.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_transport_configuration">Transport configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport does not request a client certificate by default. +You need to specify the <code>{verify, verify_peer}</code> option when starting +the listener to enable this behavior.</p></div> +<div class="listingblock"> +<div class="title">Configure a listener for SSL authentication</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, + <span style="color: #FF6600">ranch_ssl</span>, [ + {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>}, + {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>}, + {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>}, + {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>} + ], + <span style="color: #FF6600">my_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also +the <code>cacertfile</code> containing the CACert.org root certificate, and +the option to request the client certificate.</p></div> +<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_authentication">Authentication</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from a certificate</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>), + [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved.</p></div> +<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the <code>ssl:peercert/1</code> function. Once you have the +certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to +extract the <code>IssuerID</code> value.</p></div> +<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client +certificate was found. This snippet is intended to be used from your +protocol code.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from the certificate for the current connection</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span> + <span style="color: #000080">false</span>; + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</span> + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You then only need to match the <code>IssuerID</code> value to authenticate the +user.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.4/guide/parsers/"> + Writing parsers + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.4/guide/internals/"> + Internals + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/guide/transports.asciidoc b/docs/en/ranch/1.4/guide/transports.asciidoc new file mode 100644 index 00000000..f5bb17eb --- /dev/null +++ b/docs/en/ranch/1.4/guide/transports.asciidoc @@ -0,0 +1,161 @@ +== Transports + +A transport defines the interface to interact with a socket. + +Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive. + +=== TCP transport + +The TCP transport is a thin wrapper around `gen_tcp`. + +=== SSL transport + +The SSL transport is a thin wrapper around `ssl`. + +Ranch depends on `ssl` by default so any necessary +dependencies will start when Ranch is started. It is +possible to remove the dependency when the SSL transport +will not be used. Refer to your release build tool's +documentation for more information. + +When embedding Ranch listeners that have an SSL transport, +your application must depend on the `ssl` application for +proper behavior. + +=== Sending and receiving data + +This section assumes that `Transport` is a valid transport handler +(like `ranch_tcp` or `ranch_ssl`) and `Socket` is a connected +socket obtained through the listener. + +You can send data to a socket by calling the `Transport:send/2` +function. The data can be given as `iodata()`, which is defined as +`binary() | iolist()`. All the following calls will work: + +.Sending data to the socket + +[source,erlang] +---- +Transport:send(Socket, <<"Ranch is cool!">>). +Transport:send(Socket, "Ranch is cool!"). +Transport:send(Socket, ["Ranch", ["is", "cool!"]]). +Transport:send(Socket, ["Ranch", [<<"is">>, "cool!"]]). +---- + +You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking `Transport:recv/3` call, while +active mode means that you will receive the data as a message. + +By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols. + +Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with `{error, timeout}`. + +The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size. + +.Receiving data from the socket in passive mode + +[source,erlang] +{ok, Data} = Transport:recv(Socket, 0, 5000). + +Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it. + +There are two kinds of active modes: `{active, once}` and +`{active, true}`. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the `{active, true}` mode as it could quickly +flood your process mailbox. It's better to keep the data in the socket +and read it only when required. + +Three different messages can be received: + +* `{OK, Socket, Data}` +* `{Closed, Socket}` +* `{Error, Socket, Reason}` + +The value of `OK`, `Closed` and `Error` can be different +depending on the transport being used. To be able to properly match +on them you must first call the `Transport:messages/0` function. + +.Retrieving the transport's active message identifiers + +[source,erlang] +{OK, Closed, Error} = Transport:messages(). + +To start receiving messages you will need to call the `Transport:setopts/2` +function, and do so every time you want to receive data. + +.Receiving messages from the socket in active mode + +[source,erlang] +---- +{OK, Closed, Error} = Transport:messages(), +Transport:setopts(Socket, [{active, once}]), +receive + {OK, Socket, Data} -> + io:format("data received: ~p~n", [Data]); + {Closed, Socket} -> + io:format("socket got closed!~n"); + {Error, Socket, Reason} -> + io:format("error happened: ~p~n", [Reason]) +end. +---- + +You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages. + +=== Sending files + +As in the previous section it is assumed `Transport` is a valid transport +handler and `Socket` is a connected socket obtained through the listener. + +To send a whole file, with name `Filename`, over a socket: + +.Sending a file by filename + +[source,erlang] +{ok, SentBytes} = Transport:sendfile(Socket, Filename). + +Or part of a file, with `Offset` greater than or equal to 0, `Bytes` number of +bytes and chunks of size `ChunkSize`: + +.Sending part of a file by filename in chunks + +[source,erlang] +Opts = [{chunk_size, ChunkSize}], +{ok, SentBytes} = Transport:sendfile(Socket, Filename, Offset, Bytes, Opts). + +To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode: + +.Sending a file opened in raw mode + +[source,erlang] +{ok, RawFile} = file:open(Filename, [raw, read, binary]), +{ok, SentBytes} = Transport:sendfile(Socket, RawFile, Offset, Bytes, Opts). + +=== Writing a transport handler + +A transport handler is a module implementing the `ranch_transport` behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler. + +The behavior doesn't define the socket options available when opening a +socket. These do not need to be common to all transports as it's easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The `setopts/2` function *must* +implement the `{active, once}` and the `{active, true}` options. + +If the transport handler doesn't have a native implementation of `sendfile/5` a +fallback is available, `ranch_transport:sendfile/6`. The extra first argument +is the transport's module. See `ranch_ssl` for an example. diff --git a/docs/en/ranch/1.4/guide/transports/index.html b/docs/en/ranch/1.4/guide/transports/index.html new file mode 100644 index 00000000..fe8da963 --- /dev/null +++ b/docs/en/ranch/1.4/guide/transports/index.html @@ -0,0 +1,336 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Transports</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Transports</span></h1> + +<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div> +<div class="paragraph"><p>Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive.</p></div> +<div class="sect1"> +<h2 id="_tcp_transport">TCP transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ssl_transport">SSL transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>.</p></div> +<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary +dependencies will start when Ranch is started. It is +possible to remove the dependency when the SSL transport +will not be used. Refer to your release build tool’s +documentation for more information.</p></div> +<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport, +your application must depend on the <code>ssl</code> application for +proper behavior.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_and_receiving_data">Sending and receiving data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler +(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected +socket obtained through the listener.</p></div> +<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code> +function. The data can be given as <code>iodata()</code>, which is defined as +<code>binary() | iolist()</code>. All the following calls will work:</p></div> +<div class="listingblock"> +<div class="title">Sending data to the socket</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking <code>Transport:recv/3</code> call, while +active mode means that you will receive the data as a message.</p></div> +<div class="paragraph"><p>By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols.</p></div> +<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with <code>{error, timeout}</code>.</p></div> +<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size.</p></div> +<div class="listingblock"> +<div class="title">Receiving data from the socket in passive mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it.</p></div> +<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and +<code>{active, true}</code>. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the <code>{active, true}</code> mode as it could quickly +flood your process mailbox. It’s better to keep the data in the socket +and read it only when required.</p></div> +<div class="paragraph"><p>Three different messages can be received:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>{OK, Socket, Data}</code> +</p> +</li> +<li> +<p> +<code>{Closed, Socket}</code> +</p> +</li> +<li> +<p> +<code>{Error, Socket, Reason}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different +depending on the transport being used. To be able to properly match +on them you must first call the <code>Transport:messages/0</code> function.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the transport’s active message identifiers</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #009900">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> +function, and do so every time you want to receive data.</p></div> +<div class="listingblock"> +<div class="title">Receiving messages from the socket in active mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #009900">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(), +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), +<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]); + {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>); + {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</span>, [<span style="color: #009900">Reason</span>]) +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_files">Sending files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport +handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div> +<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div> +<div class="listingblock"> +<div class="title">Sending a file by filename</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of +bytes and chunks of size <code>ChunkSize</code>:</p></div> +<div class="listingblock"> +<div class="title">Sending part of a file by filename in chunks</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="color: #009900">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}], +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode:</p></div> +<div class="listingblock"> +<div class="title">Sending a file opened in raw mode</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #009900">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]), +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_a_transport_handler">Writing a transport handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler.</p></div> +<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a +socket. These do not need to be common to all transports as it’s easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong> +implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div> +<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a +fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument +is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.4/guide/listeners/"> + Listeners + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.4/guide/protocols/"> + Protocols + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/guide">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/guide">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/guide">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/manual/index.html b/docs/en/ranch/1.4/manual/index.html new file mode 100644 index 00000000..d5248194 --- /dev/null +++ b/docs/en/ranch/1.4/manual/index.html @@ -0,0 +1,173 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: Ranch Function Reference</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>Ranch Function Reference</span></h1> + +<div class="ulist"><ul> +<li> +<p> +<a href="ranch_app">ranch(7)</a> +</p> +</li> +<li> +<p> +<a href="ranch">ranch(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_protocol">ranch_protocol(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_ssl">ranch_ssl(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_tcp">ranch_tcp(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_transport">ranch_transport(3)</a> +</p> +</li> +</ul></div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/manual/ranch/index.html b/docs/en/ranch/1.4/manual/ranch/index.html new file mode 100644 index 00000000..dd9cc9fe --- /dev/null +++ b/docs/en/ranch/1.4/manual/ranch/index.html @@ -0,0 +1,702 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: ranch(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>ranch(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - socket acceptor pool</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and +manipulating Ranch listeners.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3> +<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div> +<div class="paragraph"><p>This is a soft limit. The actual number of connections +might be slightly above the limit due to concurrency +when accepting new connections. Some connections may +also be removed from this count explicitly by the user +code.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>} + | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()} + | {<span style="color: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()} + | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>} + | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Ranch-specific transport options.</p></div> +<div class="paragraph"><p>These options are not passed on to the transports. +They are used by Ranch while setting up the listeners.</p></div> +</div> +<div class="sect2"> +<h3 id="_ref_any">ref() = any()</h3> +<div class="paragraph"><p>Unique name used to refer to a listener.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +ack_timeout (5000) +</dt> +<dd> +<p> + Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish. +</p> +</dd> +<dt class="hdlist1"> +connection_type (worker) +</dt> +<dd> +<p> + Type of process that will handle the connection. +</p> +</dd> +<dt class="hdlist1"> +max_connections (1024) +</dt> +<dd> +<p> + Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely. +</p> +</dd> +<dt class="hdlist1"> +num_acceptors (10) +</dt> +<dd> +<p> + Number of processes that accept connections. +</p> +</dd> +<dt class="hdlist1"> +shutdown (5000) +</dt> +<dd> +<p> + Maximum allowed time for children to stop on listener shutdown. +</p> +</dd> +<dt class="hdlist1"> +socket +</dt> +<dd> +<p> + Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div> +<div class="paragraph"><p>This function MUST be used by a connection process to inform +Ranch that it initialized properly and let it perform any +additional operations before the socket can be safely used.</p></div> +</div> +<div class="sect2"> +<h3 id="_child_spec_ref_numacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NumAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return child specifications for a new listener.</p></div> +<div class="paragraph"><p>This function can be used to embed a listener directly +in an application instead of letting Ranch handle it.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the interface used by this listener. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +Current maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Current protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_info_8594_ref_key_value">info() → [{Ref, [{Key, Value}]}]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Key = atom() +</dt> +<dd> +<p> +Information key. +</p> +</dd> +<dt class="hdlist1"> +Value = any() +</dt> +<dd> +<p> +Information value. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return detailed information about all Ranch listeners.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +pid +</dt> +<dd> +<p> +Pid of the listener’s top-level supervisor. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> +Interface Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +port +</dt> +<dd> +<p> +Port number Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +num_acceptors +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +max_connections +</dt> +<dd> +<p> +Maximum number of connections. +</p> +</dd> +<dt class="hdlist1"> +active_connections +</dt> +<dd> +<p> +Number of active connections. +</p> +</dd> +<dt class="hdlist1"> +all_connections +</dt> +<dd> +<p> +Number of connections, including those removed from the count. +</p> +</dd> +<dt class="hdlist1"> +transport +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +transport_options +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +protocol +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +protocol_options +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_procs_ref_acceptors_connections_8594_pid">procs(Ref, acceptors | connections) → [pid()]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return all acceptor or connection processes for one listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div> +<div class="paragraph"><p>You can use this function for long-running connection processes +which spend most of their time idling rather than consuming +resources. This allows Ranch to accept a lot more connections +without sacrificing the latency of the system.</p></div> +<div class="paragraph"><p>This function may only be called from a connection process.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +New maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will not kill the extra +connections, but will wait for them to terminate properly.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +New protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the protocol options for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately for all new connections. +Old connections will not receive the new options.</p></div> +</div> +<div class="sect2"> +<h3 id="_start_listener_ref_numacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NumAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start listening for connections using the given transport +and protocol. Returns the pid for this listener’s supervisor.</p></div> +<div class="paragraph"><p>There are additional transport options that apply +regardless of transport. They allow configuring how the +connections are supervised, rate limited and more. Please +consult the previous section for more details.</p></div> +</div> +<div class="sect2"> +<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stop the given listener.</p></div> +<div class="paragraph"><p>The listener is stopped gracefully, first by closing the +listening port, then by stopping the connection processes. +These processes are stopped according to the <code>shutdown</code> +transport option, which may be set to brutally kill all +connection processes or give them some time to stop properly.</p></div> +<div class="paragraph"><p>This function does not return until the listener is +completely stopped.</p></div> +</div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/manual/ranch_app/index.html b/docs/en/ranch/1.4/manual/ranch_app/index.html new file mode 100644 index 00000000..41da7131 --- /dev/null +++ b/docs/en/ranch/1.4/manual/ranch_app/index.html @@ -0,0 +1,176 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: ranch(7)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>ranch(7)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application depends on the <code>ssl</code> application to +start. It is used for handling secure connections, when the +transport is <code>ranch_ssl</code>. It can be disabled if SSL is not +used.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application defines one application environment +configuration parameter.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +profile (false) +</dt> +<dd> +<p> + When enabled, Ranch will start <code>eprof</code> profiling automatically. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop +profiling and output the results to the files <em>procs.profile</em> +and <em>total.profile</em>. Do not use in production.</p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/manual/ranch_protocol/index.html b/docs/en/ranch/1.4/manual/ranch_protocol/index.html new file mode 100644 index 00000000..54cdbd45 --- /dev/null +++ b/docs/en/ranch/1.4/manual/ranch_protocol/index.html @@ -0,0 +1,218 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: ranch_protocol(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>ranch_protocol(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used +by Ranch protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ranch:ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start a new connection process for the given socket.</p></div> +<div class="paragraph"><p>The only purpose of this callback is to start a process that +will handle the socket. It must spawn the process, link and +then return the new pid. This function will always be called +from inside a supervisor.</p></div> +<div class="paragraph"><p>This callback can also return two pids. The first pid is the +pid of the process that will be supervised. The second pid is +the pid of the process that will receive ownership of the +socket. This second process must be a child of the first. This +form is only available when <code>connection_type</code> is set to +<code>supervisor</code>.</p></div> +<div class="paragraph"><p>If any other value is returned, the supervisor will close the +socket and assume no process has been started.</p></div> +<div class="paragraph"><p>Do not perform any operations in this callback, as this would +block the supervisor responsible for starting connection +processes and degrade performance severely.</p></div> +</div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/manual/ranch_ssl/index.html b/docs/en/ranch/1.4/manual/ranch_ssl/index.html new file mode 100644 index 00000000..b51cdd36 --- /dev/null +++ b/docs/en/ranch/1.4/manual/ranch_ssl/index.html @@ -0,0 +1,520 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: ranch_ssl(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>ranch_ssl(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_ssl_opt">ssl_opt()</h3> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">beast_mitigation</span>, <span style="color: #FF6600">one_n_minus_one</span> | <span style="color: #FF6600">zero_n</span> | <span style="color: #FF6600">disabled</span>} + | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]} + | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}} + | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>} + | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>} + | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>} + | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}} + | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">padding_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)} + | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">signature_algs</span>, [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]} + | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]} + | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">v2_hello_compatible</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()} + | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>SSL-specific listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> +<div class="paragraph"><p>Listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code> +or the <code>certfile</code> option. None of the other options are required.</p></div> +<div class="paragraph"><p>The default value is given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +alpn_preferred_protocols +</dt> +<dd> +<p> + Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. +</p> +</dd> +<dt class="hdlist1"> +beast_mitigation +</dt> +<dd> +<p> + Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software. +</p> +</dd> +<dt class="hdlist1"> +cacertfile +</dt> +<dd> +<p> + Path to PEM encoded trusted certificates file used to verify peer certificates. +</p> +</dd> +<dt class="hdlist1"> +cacerts +</dt> +<dd> +<p> + List of DER encoded trusted certificates. +</p> +</dd> +<dt class="hdlist1"> +cert +</dt> +<dd> +<p> + DER encoded user certificate. +</p> +</dd> +<dt class="hdlist1"> +certfile +</dt> +<dd> +<p> + Path to the PEM encoded user certificate file. May also contain the private key. +</p> +</dd> +<dt class="hdlist1"> +ciphers +</dt> +<dd> +<p> + List of ciphers that clients are allowed to use. +</p> +</dd> +<dt class="hdlist1"> +client_renegotiation (true) +</dt> +<dd> +<p> + Whether to allow client-initiated renegotiation. +</p> +</dd> +<dt class="hdlist1"> +crl_cache ({ssl_crl_cache, {internal, []}}) +</dt> +<dd> +<p> + Customize the module used to cache Certificate Revocation Lists. +</p> +</dd> +<dt class="hdlist1"> +crl_check (false) +</dt> +<dd> +<p> + Whether to perform CRL check on all certificates in the chain during validation. +</p> +</dd> +<dt class="hdlist1"> +depth (1) +</dt> +<dd> +<p> + Maximum of intermediate certificates allowed in the certification path. +</p> +</dd> +<dt class="hdlist1"> +dh +</dt> +<dd> +<p> + DER encoded Diffie-Hellman parameters. +</p> +</dd> +<dt class="hdlist1"> +dhfile +</dt> +<dd> +<p> + Path to the PEM encoded Diffie-Hellman parameters file. +</p> +</dd> +<dt class="hdlist1"> +fail_if_no_peer_cert (false) +</dt> +<dd> +<p> + Whether to refuse the connection if the client sends an empty certificate. +</p> +</dd> +<dt class="hdlist1"> +hibernate_after (undefined) +</dt> +<dd> +<p> + Time in ms after which SSL socket processes go into hibernation to reduce memory usage. +</p> +</dd> +<dt class="hdlist1"> +honor_cipher_order (false) +</dt> +<dd> +<p> + If true, use the server’s preference for cipher selection. If false, use the client’s preference. +</p> +</dd> +<dt class="hdlist1"> +key +</dt> +<dd> +<p> + DER encoded user private key. +</p> +</dd> +<dt class="hdlist1"> +keyfile +</dt> +<dd> +<p> + Path to the PEM encoded private key file, if different than the certfile. +</p> +</dd> +<dt class="hdlist1"> +log_alert (true) +</dt> +<dd> +<p> + If false, error reports will not be displayed. +</p> +</dd> +<dt class="hdlist1"> +next_protocols_advertised +</dt> +<dd> +<p> + List of protocols to send to the client if it supports the Next Protocol extension. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +padding_check +</dt> +<dd> +<p> + Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software. +</p> +</dd> +<dt class="hdlist1"> +partial_chain +</dt> +<dd> +<p> + Claim an intermediate CA in the chain as trusted. +</p> +</dd> +<dt class="hdlist1"> +password +</dt> +<dd> +<p> + Password to the private key file, if password protected. +</p> +</dd> +<dt class="hdlist1"> +psk_identity +</dt> +<dd> +<p> + Provide the given PSK identity hint to the client during the handshake. +</p> +</dd> +<dt class="hdlist1"> +reuse_session +</dt> +<dd> +<p> + Custom policy to decide whether a session should be reused. +</p> +</dd> +<dt class="hdlist1"> +reuse_sessions (false) +</dt> +<dd> +<p> + Whether to allow session reuse. +</p> +</dd> +<dt class="hdlist1"> +secure_renegotiate (false) +</dt> +<dd> +<p> + Whether to reject renegotiation attempts that do not conform to RFC5746. +</p> +</dd> +<dt class="hdlist1"> +signature_algs +</dt> +<dd> +<p> + The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake. +</p> +</dd> +<dt class="hdlist1"> +sni_fun +</dt> +<dd> +<p> + Function called when the client requests a host using Server Name Indication. Returns options to apply. +</p> +</dd> +<dt class="hdlist1"> +sni_hosts +</dt> +<dd> +<p> + Options to apply for the host that matches what the client requested with Server Name Indication. +</p> +</dd> +<dt class="hdlist1"> +user_lookup_fun +</dt> +<dd> +<p> + Function called to determine the shared secret when using PSK, or provide parameters when using SRP. +</p> +</dd> +<dt class="hdlist1"> +v2_hello_compatible +</dt> +<dd> +<p> + Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions. +</p> +</dd> +<dt class="hdlist1"> +verify (verify_none) +</dt> +<dd> +<p> + Use <code>verify_peer</code> to request a certificate from the client. +</p> +</dd> +<dt class="hdlist1"> +verify_fun +</dt> +<dd> +<p> + Custom policy to decide whether a client certificate is valid. +</p> +</dd> +<dt class="hdlist1"> +versions +</dt> +<dd> +<p> + TLS protocol versions that will be supported. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Note that the client will not send a certificate unless the +value for the <code>verify</code> option is set to <code>verify_peer</code>. This +means that the <code>fail_if_no_peer_cert</code> only apply when combined +with the <code>verify</code> option. The <code>verify_fun</code> option allows +greater control over the client certificate validation.</p></div> +<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/manual/ranch_tcp/index.html b/docs/en/ranch/1.4/manual/ranch_tcp/index.html new file mode 100644 index 00000000..e11bbb25 --- /dev/null +++ b/docs/en/ranch/1.4/manual/ranch_tcp/index.html @@ -0,0 +1,418 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: ranch_tcp(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>ranch_tcp(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div> +<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is +recommended to disable async threads when using the +<code>sendfile</code> function of this transport, as it can make +the threads stuck indefinitely.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | <span style="color: #FF6600">inet</span> + | <span style="color: #FF6600">inet6</span> + | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()} + | {<span style="color: #FF6600">ipv6_v6only</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}} + | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} + | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()} + | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Listen options.</p></div> +<div class="paragraph"><p>This does not represent the entirety of the options that can +be set on the socket, but only the options that may be +set independently of protocol implementation.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to <code>gen_tcp</code>. +Defaults are given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +backlog (1024) +</dt> +<dd> +<p> + Max length of the queue of pending connections. +</p> +</dd> +<dt class="hdlist1"> +buffer +</dt> +<dd> +<p> + Size of the buffer used by the Erlang driver. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +delay_send (false) +</dt> +<dd> +<p> + Always queue packets before sending, to send fewer, larger packets over the network. +</p> +</dd> +<dt class="hdlist1"> +dontroute (false) +</dt> +<dd> +<p> + Don’t send via a gateway, only send to directly connected hosts. +</p> +</dd> +<dt class="hdlist1"> +exit_on_close (true) +</dt> +<dd> +<p> + Disable to allow sending data after a close has been detected. +</p> +</dd> +<dt class="hdlist1"> +fd +</dt> +<dd> +<p> + File descriptor of the socket, if it was opened externally. +</p> +</dd> +<dt class="hdlist1"> +high_msgq_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the socket message queue before the socket queue becomes busy. +</p> +</dd> +<dt class="hdlist1"> +high_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy. +</p> +</dd> +<dt class="hdlist1"> +inet +</dt> +<dd> +<p> + Set up the socket for IPv4. +</p> +</dd> +<dt class="hdlist1"> +inet6 +</dt> +<dd> +<p> + Set up the socket for IPv6. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> + Interface to listen on. Listen on all interfaces by default. +</p> +</dd> +<dt class="hdlist1"> +ipv6_v6only (false) +</dt> +<dd> +<p> + Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6. +</p> +</dd> +<dt class="hdlist1"> +keepalive (false) +</dt> +<dd> +<p> + Enable sending of keep-alive messages. +</p> +</dd> +<dt class="hdlist1"> +linger ({false, 0}) +</dt> +<dd> +<p> + Whether to wait and how long to flush data sent before closing the socket. +</p> +</dd> +<dt class="hdlist1"> +low_msgq_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the socket message queue before the socket queue leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +low_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +port (0) +</dt> +<dd> +<p> + TCP port number to listen on. 0 means a random port will be used. +</p> +</dd> +<dt class="hdlist1"> +priority (0) +</dt> +<dd> +<p> + Priority value for all packets to be sent by this socket. +</p> +</dd> +<dt class="hdlist1"> +recbuf +</dt> +<dd> +<p> + Minimum size of the socket’s receive buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +send_timeout (30000) +</dt> +<dd> +<p> + How long the send call may wait for confirmation before returning. +</p> +</dd> +<dt class="hdlist1"> +send_timeout_close (true) +</dt> +<dd> +<p> + Whether to close the socket when the confirmation wasn’t received. +</p> +</dd> +<dt class="hdlist1"> +sndbuf +</dt> +<dd> +<p> + Minimum size of the socket’s send buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +tos +</dt> +<dd> +<p> + Value for the IP_TOS IP level option. Use with caution. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific +options by specifying the protocol level, the option number and +the actual option value specified as a binary. This option is not +portable. Use with caution.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/ranch/1.4/manual/ranch_transport/index.html b/docs/en/ranch/1.4/manual/ranch_transport/index.html new file mode 100644 index 00000000..f15173fd --- /dev/null +++ b/docs/en/ranch/1.4/manual/ranch_transport/index.html @@ -0,0 +1,629 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content=""> + <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> + + <meta name="generator" content="Hugo 0.26" /> + + <title>Nine Nines: ranch_transport(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<h1 class="lined-header"><span>ranch_transport(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used +by Ranch transports.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3> +<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div> +<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +LSocket = CSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Accept timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div> +<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket +after accepting the connection. This is most useful when the +transport is not raw TCP, like with SSL for example.</p></div> +</div> +<div class="sect2"> +<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Ack timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div> +<div class="paragraph"><p>This function will be called by connection processes +before performing any socket operation. It allows +transports that require extra initialization to perform +their task and make the socket ready to use.</p></div> +</div> +<div class="sect2"> +<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Close the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +Pid = pid() +</dt> +<dd> +<p> +Pid of the new owner of the socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change the controlling process for the given socket.</p></div> +<div class="paragraph"><p>The controlling process is the process that is allowed to +perform operations on the socket, and that will receive +messages from the socket when active mode is used. When +the controlling process dies, the socket is closed.</p></div> +</div> +<div class="sect2"> +<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +LSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Listen for connections on the given port.</p></div> +<div class="paragraph"><p>The port is given as part of the transport options under +the key <code>port</code>. Any other option is transport dependent.</p></div> +<div class="paragraph"><p>The socket returned by this call can then be used to +accept connections. It is not possible to send or receive +data from the listening socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +OK = Closed = Error = atom() +</dt> +<dd> +<p> +Tuple names. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div> +</div> +<div class="sect2"> +<h3 id="_name_8594_name">name() → Name</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name = atom() +</dt> +<dd> +<p> +Transport module name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the name of the transport.</p></div> +</div> +<div class="sect2"> +<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the remote endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the remote endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div> +</div> +<div class="sect2"> +<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Length = non_neg_integer() +</dt> +<dd> +<p> +Requested length. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Receive timeout. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() | any() +</dt> +<dd> +<p> +Data received. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div> +<div class="paragraph"><p>Trying to receive data from a socket that is in active mode +will return an error.</p></div> +<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div> +<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>, +this is highly discouraged as this could cause your process +to get stuck waiting for data that will never come. This may +happen when a socket becomes half-open due to a crash of the +remote endpoint. Wi-Fi going down is another common culprit +of this issue.</p></div> +</div> +<div class="sect2"> +<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() +</dt> +<dd> +<p> +Data to be sent. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data to the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>The file may be sent full or in parts, and may be specified +by its filename or by an already open file descriptor.</p></div> +<div class="paragraph"><p>Transports that manipulate TCP directly may use the +<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile +syscall where applicable (on Linux, for example). Other +transports can use the <code>sendfile/6</code> function exported from +this module.</p></div> +</div> +<div class="sect2"> +<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +SockOpts = any() +</dt> +<dd> +<p> +Socket options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change options for the given socket.</p></div> +<div class="paragraph"><p>This is mainly useful for switching to active or passive mode +or to set protocol-specific options.</p></div> +</div> +<div class="sect2"> +<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +How = read | write | read_write +</dt> +<dd> +<p> +Which side(s) of the socket to close. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div> +</div> +<div class="sect2"> +<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the local endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the local endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code> +and may be used when transports are not manipulating TCP +directly.</p></div> +</div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Ranch + 1.4 + Function Reference + +</h3> + +<ul> + + <li><a href="/docs/en/ranch/1.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/ranch/1.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/ranch/1.4/manual">1.4</a></li> + + <li><a href="/docs/en/ranch/1.3/manual">1.3</a></li> + + <li><a href="/docs/en/ranch/1.2/manual">1.2</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2016</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + |