docs/oikia/jail-httpd.md

HTTP reverse proxy

Before applying any change test the configuration running nginx -t inside the jail.

Use service nginx {start,stop,restart,reload} to start, stop, restart nginx or to reload the configuration.

SSL

SSL certificates are used by multiple applications but you find here the documentation because the generation/renoval procedure is handled by this jail.

The SSL certificates, the Letsencrypt private key, the domain list used to generate certificates and the certificate request script are stored in a separate ZFS filesystem (storage/data/letsencrypt) and it is bind mounted both in the host system and in this jail.

In the host system the filesystem is mounted on the /var/letsencrypt directory. In the httpd jail the filesystem is mounted on the /var/letsencrypt directory inside the jail.

As stated previously this filesystem is also mounted in other jails that require access to SSL certificates (e.g.: the slapd jail).

Certificates managements is handled by acme-client, a Letsencrypt client focused on security.

Certificate renoval

Certificates renoval is automatic and you should not really care (until something goes wrong).

A weekly check handled by periodic(8). If a certificate is expired or is about to expire it is automatically renewed.

You can change this behaviour in the /etc/periodic.conf file inside the jail: just change the value of the weekly_acme_client_enable variable to "NO".

The periodic behaviour is managed by the /usr/local/etc/periodic/weekly/000.acme-client.sh script. This script is provided by the acme-client package itself and you must not edit it.

The script does nothing more than executing the /var/letsencrypt/acme-client.sh, as specified in the periodic.conf file.

Keep in mind that you still must reload the nginx configuration on your own, since the script will only update the SSL certificates.

You also might want to reload/restart other services that uses SSL files, such as OpenLDAP.

If something goes wrong

Just execute the /var/letsencrypt/acme-client.sh script inside the jail.

acme-client will not force the certificates renoval if there is no need for that.

Remember to reload the nginx configuration and do the same for other services using the SSL certificates.

robots.txt

You can specify a robots.txt file on a domain basis or use a default file.

All the robots files must be placed in the /usr/local/www/robots directory inside the jail.

The default.txt robots file is used if there is no domain-specific file.

In the same directory you can find domain-specific robots file with the name format {FQDN}.txt. E.g.: git.unit.macaomilano.org.txt.

Add a new robots file for a specific domain

1. Create a new file containing the robots rules you want

   In the robots directory (/usr/local/www/robots) create a new file with the name in the format {FQDN}.txt.

   E.g.: git.unit.macaomilano.org.txt.

2. Add your file to the robots gateway

   Open the robots file router configuration file (/usr/local/etc/nginx/common/robots-router.conf) and in the body of the map add the FQDN and the full path to the robots file.

   E.g.: git.unit.macaomilano.org /usr/local/www/robots/git.unit.macaomilano.org.txt;

Don't forget to check the nginx configuration with nginx -t and reload the configuration with service nginx reload. You must run the command inside the jail.