# Port configurations

Source: https://zotonic.com/docs/1482/port-configurations

URI: https://zotonic.com/id/1482

Language: en



<div>
            
  <aside class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="/id/doc_module_mod_ssl_letsencrypt"><span class="std std-ref">mod_ssl_letsencrypt</span></a>, <a class="reference internal" href="/id/doc_module_mod_ssl_ca"><span class="std std-ref">mod_ssl_ca</span></a>, <a class="reference internal" href="/id/doc_developerguide_deployment_privilegedports#guide-deployment-privilegedports"><span class="std std-ref">Running on Port 80 and Port 443</span></a></p>
</aside>
<div class="section">

<p>Port configurations can be tricky, especially in combination with SSL.
Here we explain all steps to come to a correctly configured installation
with working SSL connectivity.</p>
<p>There are basically two sets of port configurations:</p>

<p><ol class="arabic simple">
<li>The ports Zotonic <em>listens</em> on</li>
<li>The ports an <em>outside</em> visitor <em>connects to</em></li>
</ol>
</p>
<p>The listen ports are configured with <code class="docutils literal notranslate"><span class="pre">listen_port</span></code> and <code class="docutils literal notranslate"><span class="pre">ssl_listen_port</span></code>.</p>
<p>The outside ports are configured with <code class="docutils literal notranslate"><span class="pre">port</span></code> and <code class="docutils literal notranslate"><span class="pre">ssl_port</span></code>. They default to
the <em>listen_</em> variations if not defined.</p>
<p>Below are examples how to configure these.</p>
<div class="section">
<h2>Server direct on the Internet</h2>
<p>Here you can use the methods described in <a class="reference internal" href="/id/doc_developerguide_deployment_privilegedports#guide-deployment-privilegedports"><span class="std std-ref">Running on Port 80 and Port 443</span></a> to get your server
on ports 80 and/or 443.</p>
<p>The port configurations would be:</p>
<div class="table-wrapper"><table border="1" class="docutils">

<thead valign="bottom">
<tr><th class="head">Method</th>
<th class="head">listen_port</th>
<th class="head">ssl_listen_port</th>
<th class="head">port</th>
<th class="head">ssl_port</th>
<th class="head">listen_ip</th>
<th class="head">proxy_allowlist</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>authbind</td>
<td>80</td>
<td>443</td>
<td>80</td>
<td>443</td>
<td>any</td>
<td>none</td>
</tr>
<tr><td>setcap</td>
<td>80</td>
<td>443</td>
<td>80</td>
<td>443</td>
<td>any</td>
<td>none</td>
</tr>
<tr><td>iptables</td>
<td>8000</td>
<td>8443</td>
<td>80</td>
<td>443</td>
<td>127.0.0.1</td>
<td>none</td>
</tr>
<tr><td>http only</td>
<td>8000</td>
<td>none</td>
<td>80</td>
<td>none</td>
<td>127.0.0.1</td>
<td>none</td>
</tr>
</tbody>
</table></div>
<p>For <em>Network Address Translation</em> (NAT), see the next section. The <em>proxy_allowlist</em> is explained
in the section about proxies below.</p>
<p>In the case of <em>iptables</em> we restrict Zotonic to listen on the local 127.0.0.1 address.
This to prevent that people can connect on port 8000 from their browsers.</p>
<p>Alternatively you can run your server on the <em>outside</em> port 8000, though then it is impossible
to use Let’s Encrypt certificates for SSL (as they require the server to run on the default
http and https ports).</p>
</div>
<div class="section">
<h2>Server accessed via NAT</h2>
<p>With <em>Network Address Translation</em> (NAT) the traffic is routed straight to the server using port
mappings. This is typical for a situation where Zotonic runs on a local server behind a modem.</p>
<div class="table-wrapper"><table border="1" class="docutils">

<thead valign="bottom">
<tr><th class="head">Proxy method</th>
<th class="head">listen_port</th>
<th class="head">ssl_listen_port</th>
<th class="head">port</th>
<th class="head">ssl_port</th>
<th class="head">listen_ip</th>
<th class="head">proxy_allowlist</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>NAT (eg. modem)</td>
<td>8000</td>
<td>8443</td>
<td>80</td>
<td>443</td>
<td>any</td>
<td>none</td>
</tr>
</tbody>
</table></div>
<p>The <em>proxy_allowlist</em> is explained in the section about proxies below.</p>
</div>
<div class="section">
<h2>Server behind a proxy like Nginx or HAProxy</h2>
<p>A proxy could be <em>haproxy</em> or <em>nginx</em>. The proxy terminates the https connection and handles
the SSL certificates.</p>
<p>Typically the proxy connects to the default ports 8000 and 8443 on the Zotonic server.
The proxy itself could be running on the local server or another server.</p>
<div class="table-wrapper"><table border="1" class="docutils">

<thead valign="bottom">
<tr><th class="head">Proxy method</th>
<th class="head">listen_port</th>
<th class="head">ssl_listen_port</th>
<th class="head">port</th>
<th class="head">ssl_port</th>
<th class="head">listen_ip</th>
<th class="head">proxy_allowlist</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>localhost proxy</td>
<td>8000</td>
<td>none</td>
<td>80</td>
<td>443</td>
<td>127.0.0.1</td>
<td>local</td>
</tr>
<tr><td>proxy on LAN</td>
<td>8000</td>
<td>none</td>
<td>80</td>
<td>443</td>
<td>any</td>
<td>local</td>
</tr>
<tr><td>proxy on WAN</td>
<td>8000</td>
<td>none</td>
<td>80</td>
<td>443</td>
<td>any</td>
<td><em>see below</em></td>
</tr>
</tbody>
</table></div>
<p>The proxy adds the hostname, address of the visitor and protocol information (http or https) to a
HTTP header. Zotonic reads this header to know which site to serve and if the visitor was using https
or not.</p>
<p>Everybody could add this header and then connect directly to the Zotonic server, which can then make
wrong assumptions about the IP address of the visitor and if the visitor is on a secure connection.</p>
<p>To prevent the visitor spoofing the <em>Forward</em> header, Zotonic will check if the <em>inside</em> address of the
proxy (as seen from Zotonic, not from the visitor) is on a list of allowed proxies.</p>
<p>This allowlist is specified in <code class="docutils literal notranslate"><span class="pre">proxy_allowlist</span></code> and can have the following values:</p>

<p><ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">local</span></code> - default, only LAN addresses can connect</li>
<li><code class="docutils literal notranslate"><span class="pre">none</span></code> - no proxy exists, ignore proxy headers</li>
<li><code class="docutils literal notranslate"><span class="pre">any</span></code> - <em>insecure</em>, any server anywhere can be a proxy</li>
<li>A tuple with a single ip address, for example: <code class="docutils literal notranslate"><span class="pre">{192,168,1,1}</span></code></li>
<li>A string with ip addresses with optional masks, for example: <code class="docutils literal notranslate"><span class="pre">"127.0.0.0/8,10.0.0.0/8,fe80::/10"</span></code></li>
</ul>
</p>
<p>The <code class="docutils literal notranslate"><span class="pre">local</span></code> check is hardcoded and very fast.</p>
</div>
<div class="section">
<h2>SSL certificates</h2>
<p>After the server’s listen ports are correctly configured then the SSL connection can be tested.</p>
<p>Per default Zotonic will generate a self-signed certificate for all valid hostnames. Instead of these
self-signed certificates a real certificate can be used. Check for these the modules <a class="reference internal" href="/id/doc_module_mod_ssl_letsencrypt"><span class="std std-ref">mod_ssl_letsencrypt</span></a> and
<a class="reference internal" href="/id/doc_module_mod_ssl_ca"><span class="std std-ref">mod_ssl_ca</span></a></p>
<p>The self-signed certificates are stored in the <code class="file docutils literal notranslate"><span class="pre">self-signed</span></code> subdirectory of the security directory.</p>
<p>You can see the <code class="docutils literal notranslate"><span class="pre">security_dir</span></code> location using <code class="docutils literal notranslate"><span class="pre">bin/zotonic</span> <span class="pre">config</span></code></p>
<p>Possible locations are:</p>

<p><ul class="simple">
<li>The environment variable <code class="docutils literal notranslate"><span class="pre">ZOTONIC_SECURITY_DIR</span></code></li>
<li>The <code class="file docutils literal notranslate"><span class="pre">~/.zotonic/security</span></code> directory</li>
<li>The <code class="file docutils literal notranslate"><span class="pre">/etc/zotonic/security</span></code> directory (only on Linux)</li>
<li>The OS specific directory for application data files</li>
</ul>
</p>
<p>The OS specific directories are:</p>

<p><ul class="simple">
<li>On Unix: <code class="file docutils literal notranslate"><span class="pre">~/.config/zotonic/security/</span></code></li>
<li>On macOS: <code class="file docutils literal notranslate"><span class="pre">~/Library/Application</span> <span class="pre">Support/zotonic/security/</span></code></li>
</ul>
</p>
<p>The default is the OS specific directory.</p>
</div>
<div class="section">
<h2>HTTPS and security</h2>
<p>Zotonic always redirects all incoming HTTP connections to HTTPS. This can not be disabled.</p>
<div class="section">
<h3>Secure cookies</h3>
<p>All cookies related to authentication are set to <em>secure</em>. The cookie holding the authentication
token has <code class="docutils literal notranslate"><span class="pre">SameSite</span></code> set to <code class="docutils literal notranslate"><span class="pre">Strict</span></code>. This can not be configured or changed.</p>
</div>
</div>
<div class="section">
<h2>Erlang SSL Configuration</h2>
<p>The erlang ssl application is configured in the <code class="file docutils literal notranslate"><span class="pre">erlang.config</span></code> file. It is stored next to the
<code class="docutils literal notranslate"><span class="pre">zotonic.config</span></code> file. You can see the config files used with:</p>
<div class="highlight-erlang notranslate"><div class="highlight"><pre><span></span><span class="n">bin</span><span class="o">/</span><span class="n">zotonic</span> <span class="n">configfiles</span>
</pre></div>
</div>
<p>If this file is missing then it can be copied from <code class="file docutils literal notranslate"><span class="pre">apps/zotonic_launcher/priv/erlang.config.in</span></code>.
It contains a couple of important settings which we recommend you to change. The reason for this is that the
default settings Erlang uses are unsuitable for web servers. The most important settings are listed
below.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">session_lifetime</span></code></dt>
<dd>Sets the maximum lifetime of session data in seconds.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">session_cache_server_max</span></code></dt>
<dd>Sets the maximum number of client sessions cached by the server.</dd>
</dl>
<p>For more information on configuration options, please see <a class="reference external" href="http://erlang.org/doc/man/ssl_app.html">Erlang SSL App</a>.</p>
</div>
<div class="section">
<h2>Adding your own SSL options or certificates</h2>
<p>If you want to implement your own certificate handling you have to add a
notification observer which returns the certificates to the underlying
HTTPS server. This can be needed if you have a site with special hostname aliases, or if
you want to implement automated certificate handling for a specific certificate authority.</p>
<p>The notification use by the SNI (Server Name Indication) handler is:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">ssl_options{server_name=ServerName}</span></code></dt>
<dd>Return the certificate, key or other ssl options. <code class="docutils literal notranslate"><span class="pre">ServerName</span></code> is a string (list) with the
name of the server from the SSL handshake. You shoudl return a proplist with Erlang
<code class="docutils literal notranslate"><span class="pre">ssl:ssl_option()</span></code> terms. The proplist will override the default ssl options for this
connection. For more information about the possible properties see <a class="reference external" href="http://erlang.org/doc/man/ssl.html">Erlang SSL</a>.
If <code class="docutils literal notranslate"><span class="pre">undefined</span></code> is returned the SSL handshake will try the next SSL module. If all
modules return <code class="docutils literal notranslate"><span class="pre">undefined</span></code> then a self-signed certificate will be used.</dd>
</dl>
</div>
</div>


           </div>

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/1482?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/1482?language=en>)
