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.
There are basically two sets of port configurations:
- The ports Zotonic listens on
- The ports an outside visitor connects to
The listen ports are configured with
The outside ports are configured with
ssl_port. They default to
the listen_ variations if not defined.
Below are examples how to configure these.
Server direct on the Internet
Here you can use the methods described in Running on Port 80 and Port 443 to get your server on ports 80 and/or 443.
The port configurations would be:
For Network Address Translation (NAT), see the next section. The proxy_allowlist is explained in the section about proxies below.
In the case of iptables 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.
Alternatively you can run your server on the outside 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).
Server accessed via NAT
With Network Address Translation (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.
|NAT (eg. modem)||8000||8443||80||443||any||none|
The proxy_allowlist is explained in the section about proxies below.
Server behind a proxy like Nginx or HAProxy
A proxy could be haproxy or nginx. The proxy terminates the https connection and handles the SSL certificates.
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.
|proxy on LAN||8000||none||80||443||any||local|
|proxy on WAN||8000||none||80||443||any||see below|
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.
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.
To prevent the visitor spoofing the Forward header, Zotonic will check if the inside address of the proxy (as seen from Zotonic, not from the visitor) is on a list of allowed proxies.
This allowlist is specified in
proxy_allowlist and can have the following values:
local- default, only LAN addresses can connect
none- no proxy exists, ignore proxy headers
any- insecure, any server anywhere can be a proxy
- A tuple with a single ip address, for example:
- A string with ip addresses with optional masks, for example:
local check is hardcoded and very fast.
After the server’s listen ports are correctly configured then the SSL connection can be tested.
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 mod_ssl_letsencrypt and mod_ssl_ca
The self-signed certificates are stored in the
self-signed subdirectory of the security directory.
You can see the
security_dir location using
Possible locations are:
- The environment variable
/etc/zotonic/securitydirectory (only on Linux)
- The OS specific directory for application data files
The OS specific directories are:
- On Unix:
- On macOS:
The default is the OS specific directory.
HTTPS and security
Zotonic always redirects all incoming HTTP connections to HTTPS. This can not be disabled.
All cookies related to authentication are set to secure. The cookie holding the authentication
SameSite set to
Strict. This can not be configured or changed.
Erlang SSL Configuration
The erlang ssl application is configured in the
erlang.config file. It is stored next to the
zotonic.config file. You can see the config files used with:
If this file is missing then it can be copied from
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
- Sets the maximum lifetime of session data in seconds.
- Sets the maximum number of client sessions cached by the server.
For more information on configuration options, please see Erlang SSL App.
Adding your own SSL options or certificates
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.
The notification use by the SNI (Server Name Indication) handler is:
- Return the certificate, key or other ssl options.
ServerNameis a string (list) with the name of the server from the SSL handshake. You shoudl return a proplist with Erlang
ssl:ssl_option()terms. The proplist will override the default ssl options for this connection. For more information about the possible properties see Erlang SSL. If
undefinedis returned the SSL handshake will try the next SSL module. If all modules return
undefinedthen a self-signed certificate will be used.