WaTTS server settings


This section will describe the general settings of the WaTTS server. This will include options like ports, hostname and SSL.

Typical values that should be changed during the initial setup are:

  • hostname, change it to an actual fully qualified hostname
  • port, which can be removed if the incoming traffic arrives at port 80 for http or 443 for https
  • listen_port, it will be set to the internal port WaTTS is listening at

And for production use:

  • ssl, set to 'true'
  • cachain_file, set to the path to the file
  • dh_file, set to the path to the file
  • cert_file, set to the path to the file
  • key_file, set to the path to the file


Key Description Datatype Default
nodename The name of the Erlang distrubuted node. Do not change unless really needed. string watts@
distributed_cookie The cookie of the Erlang distrubution. Do not change unless really needed. string watts
hostname Hostname of the web server host localhost
port Port number where clients seem to connect to; default is port 80 for non SSL, 443 for SSL. In production systems this should be left 'default' port number or 'default' 8080
listen_port Port at which WaTTS actually listens, used to support listening at non-privileged ports; the traffic must then be redirected from the privileged ports to the listen_port usually by the firewall. The value 'port' means using the same value as port port or 'port' 'port'
web_acceptors The number of parallel waiting processes for incomming connection integer 5
web_parallel_conns The number of maximal parallel connections at the rest interface integer 50
web_background_image The path to a png image to use as background file default
ssl Whether SSL should be used boolean true
cachain_file Location of the ca chain for the server file none
cert_file Location of the certificate file /etc/watts/watts.crt
key_file Path to the private key file file /etc/watts/watts.key
dh_file Path to the file containing the diffie hellman parameter. To generate it simply run openssl dhparam -out watts_dh.pem 2048 file none
allow_insecure_plugins If insecure plugins, that means plugins that do not support stdin, should be allowed boolean false
session_timeout The duration for which a session at the web-app is valid during inactivity duration 15m
session_max_duration The maximum duration of a session at the web interface, even if active. After this time an additional Login is required duration 30m
database_type The type of database to user 'sqlite', 'mnesia', 'eleveldb' 'sqlite'
sqlite_file Path to the sqlite database, used if database_type is 'sqlite' file /etc/watts/watts.db
mnesia_dir Base directory of the mnesia database, used if database_type is 'mnesia' dir /var/lib/watts/mnesia
eleveldb_dir Base directory of the eleveldb database, used if database_type is 'eleveldb' dir /var/lib/watts/eleveldb
redirection.enable Whether redirection should be enabled boolean false
redirection.listen_port The port to listen on for browsers to redirect port 8080
secret_dir A directory to contain sensible secrets. WaTTS creates the directory if it does not yet exist and forces it to have the permissions 700 on it. dir /var/lib/watts/secret/
jwt_key_rotation_interval The interval at which the RSA keys for signing the session info (stored in cookies of the user) will be rotated. duration 14d
jwt_key_bits The number of bits to use in the RSA key. integer 2014
allow_dropping_credentials Whether credentials of unknown services can be silently dropped boolean false
enable_user_doc Whether the user documentation is reachable at /docs/user/ boolean true
enable_code_doc Whether the code documentation is reachable at /docs/code/ boolean true
max_provider_wait The duration to wait for provider results. If the duration is passed the results of OpenID Connect provider won't be logged, the provider will still function. duration 30s
log_dir The path where the log files will be put path /var/log/watts
syslog_facility The facility to use for syslog 'daemon','local0'-'local7' 'daemon'
enable_rsp Enable support for RSP (relying service provider) at WaTTS. This will enable support for other services to rely on WaTTS to perform certain taks e.g. run plugins for them. boolean false
privacy_doc The html file containing the privacy statement for you WaTTS instance file none
debug_mode enable debug output, this adds a lot of load. debug_mode is only allowed when running on localhost as it might log senstive data. boolean false
max_error_msg_per_sec The number of error messages that should be log at max, if there are more messages per second they will be dropped. If the number is negative nothing will be dropped. integer -1
web_connection_rate The number of connection per seccond that will be allowed to pass, every additional connection gets a '503 - service not available' available error. A negative value or zero changes it to unlimited, which should be used with caution. integer 10
rsp_connection_rate same as the web_connection_rate but for the rsp endpoint integer 10
web_queue_max_wait The maximum amount of time to wait until the request get cancelled while waiting in the queue duration 100ms
rsp_queue_max_wait Same as web_queue_max_wait but for the rsp duration 1s
admin_mail The email address of the administrator string none
email.enable Whether email sending should be enabled in general boolean false
email.on_plugin_error If a mail should be sent on issues with a plugin (only if email is enabled, see email.enable) boolean true
email.name The sender name to use in the email string WaTTS
email.address The sender address to use in the email string watts@
email.relay The mail server or the domain to use to send the mails string none
email.no_mx_lookups disable lookups of mx records of the relay boolean false
email.port The port of the mail server to connect to port 25 (465 SSL)
email.ssl Whether a ssl connection should be established (see also tls) boolean false
email.tls Use tls for starting a secure connection 'never', 'if_available', 'always' 'always'
email.user username to use to authenticate at the server string none
email.password password to authenticate with at the server string none

Listen_Port, Redirection Explained

The idea is to run WaTTS as a dedicated non root user for security reasons. The drawback of not beeing root is that ports 1-1024 are not available to WaTTS. To still be able to have WaTTS running at port 80 or 443 several settings are needed.

As an image tells more than a thousand words, soma ascii art:

client --[port]---> firewall rules --[listen_port]--> WaTTS

In the picture above the client connects to the port port and firewall rules redirect the packages arriving at port to the listen_port at which WaTTS is actually listen. The corresponding firewall rule is:

iptables -t nat -A PREROUTING -i eth0 -p tcp --dport `port` -j REDIRECT --to-port `listen_port`

Redirection is needed when using SSL and http traffic should be forwarded to the https endpoint. The problem is that http and https work completely different, so a pure redirection using the firewall does not work, instead a valid http-redirection message needs to be send. Sending this valid http message is the task of the redirection and needs to be listening at a different port:

client --[some port]--> firewall rules --[redirection.listen_port]--> redirection endpoint
       <-------[ valid http message, redirecting to the http endpoint ]----/

The redirection follows the same idea as the port and listen_port above. So WaTTS is listening at redirection.listen_port for incomming traffic and sending a valid http redirection message back, which tells the browser to go tho the ssl endpoint: https://`hostname`:`port`.

For the redirection another firewall rule is needed:

# redirecting all traffic arriving at the default http port, 80, to the the listen port
# for redirection
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port `redirection.listen_port`


The following example is the basic SSL setup.

hostname = my-watts.example.com
listen_port = 8443
port = 443
ssl = true
# using default values for cachain_file, cert_file and key_file
session_timeout = 10m
redirection.enable = true
redirection.listen_port = 8000

and the firewall rules

# for the ssl traffic forwarding from 443 to the listen port of WaTTS
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 8443

# for the non ssl traffic trying port 80 forwarding it to the redirection.listen_port of WaTTS
iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8000

results matching ""

    No results matching ""