> For the complete documentation index, see [llms.txt](https://indigo-dc.gitbook.io/token-translation-service/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://indigo-dc.gitbook.io/token-translation-service/config/config_server.md). # Server Settings ## Introduction 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 ## Settings | Key | Description | Datatype | Default | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------- | | nodename | The name of the Erlang distrubuted node. Do not change unless really needed. | string | watts\@127.0.0.1 | | 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\`](https://app.gitbook.com/s/-LFRonNTeBrrZS7LzzDy/config/%60hostname%60:%60port%60). 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` ``` ## Example 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 ```