Serve HTTPS

By default, Vigie speaks plain HTTP. With server.tls, it speaks HTTPS only, on the same listen_addr. Use it when clients reach Vigie over a network you don’t trust, so they can check that the endpointsOne IP address and port that a service gives, with its load balancing weight. See HTTP API. come from your server.

Vigie doesn’t check the certificates of its clients. To restrict who can read it, require a password or filter the port with a firewall.

Before you start

You need a certificate for the name the clients use to reach Vigie, and its private key, both in PEM. The certificate file can hold the chain after the certificate of the server.

Turn HTTPS on

1. Put the files where the user that runs Vigie can read them, and only that user for the key.

   sudo install -m 0644 vigie.crt /etc/vigie/vigie.crt
   sudo install -m 0600 -o vigie vigie.key /etc/vigie/vigie.key

   With the dynamic user of the systemd unit of the repository, add LoadCredential= to the unit, or a fixed User=, so the key can stay private.

2. Set server.tls in the configuration.

   config.yml

   server
   server
   Type object · Required no · Default none
   Settings of the HTTP server. A change needs a restart, a reload doesn’t apply it.:
     listen_addr
   server.listen_addr
   Type string · Required no · Default :8080
   Address the server listens on.: :8443
     tls
   server.tls
   Type object · Required no · Default none
   Turns HTTPS on, with the certificate and its key. Without it, the server speaks plain HTTP.:
       cert_file
   server.tls.cert_file
   Type path · Required with server.tls · Default none
   Certificate of the server, in PEM.: /etc/vigie/vigie.crt
       key_file
   server.tls.key_file
   Type path · Required with server.tls · Default none
   Private key of the certificate, in PEM.: /etc/vigie/vigie.key
   services
   services
   Type list · Required yes · Default none
   Services the server answers for, at least one.:
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: web
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 8080
       file
   services[].file
   Type object · Required one source · Default none
   Reads the endpoints from a local file.:
         path
   services[].file.path
   Type path · Required yes · Default none
   File holding one endpoint line per line.: /etc/vigie/web-endpoints.txt

3. Check the file and restart Vigie. A reloadReading the configuration file again to replace the services, on SIGHUP or POST /reload. See Reload the services. doesn’t apply a change to server.

   vigie check-config -c /etc/vigie/config.yml
   sudo systemctl restart vigie

Vigie reads the certificate once at start, so a renewed certificate also needs a restart.

Check the result

curl -s --cacert ca.crt 'https://vigie.example.com:8443/services?service_name=web'

--cacert gives the CA that signed the certificate, when the system doesn’t trust it already. The clients need the same CA, such as the ca field of a Flock backend.

Error	Cause
server tls: cert_file and key_file are required	server.tls is set with an empty cert_file or key_file.
open /etc/vigie/vigie.key: permission denied at start	The user that runs Vigie can’t read the key.
tls: private key does not match public key at start	The key isn’t the key of the certificate.