Require a password

By default, anyone who reaches the port of Vigie can read its services and reloadReading the configuration file again to replace the services, on SIGHUP or POST /reload. See Reload the services. them. With server.basic_auth, every endpointOne IP address and port that a service gives, with its load balancing weight. See HTTP API. but GET /healthz asks for the username and password of one of the users you list. Probes keep working without credentials.

Basic authentication sends the password in clear on each request. Turn it on with HTTPS when the network between the clients and Vigie isn’t trusted.

Turn it on

1. Add the users to server in the configuration. Give each client its own user, so you can change one password without touching the other clients.

   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
     basic_auth
   server.basic_auth
   Type list · Required no · Default empty
   Users allowed to call the server. When set, every endpoint but GET /healthz asks for the username and password of one of them.:
       - username
   server.basic_auth[].username
   Type string · Required with server.basic_auth · Default none
   Username of the user, unique among the users.: flock
         password
   server.basic_auth[].password
   Type string · Required with server.basic_auth · Default none
   Password of the user.: change-me
       - username
   server.basic_auth[].username
   Type string · Required with server.basic_auth · Default none
   Username of the user, unique among the users.: meridian
         password
   server.basic_auth[].password
   Type string · Required with server.basic_auth · Default none
   Password of the user.: change-me-too
   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

   The file now holds passwords, so only the user that runs Vigie should read it.

2. Check the file and restart Vigie. A reload doesn’t apply a change to server.

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

Check the result

curl -s -o /dev/null -w '%{http_code}\n' 'https://vigie.example.com:8443/services?service_name=web'
curl -s -u flock:change-me 'https://vigie.example.com:8443/services?service_name=web'

The first request answers 401, the second the endpoints of web. A browser asks for a username and password before showing the page.

Give the credentials to the clients

A Flock backend gives them in url.user_info of its eds block. Any other client sends them in an Authorization: Basic header, as curl -u does.

Change a password

Every user of server.basic_auth is accepted, so a password can change without a moment where the clients get 401:

1. Add a user with the new password next to the old one, and restart Vigie.
2. Once every client sends the new credentials, remove the old user and restart Vigie again.

Error	Cause
server basic_auth: username and password are required	A user has an empty username or password.
server basic_auth: username <name> is given twice	Two users have the same username.
401 unauthorized from a client	The client sends no credentials, or not those of a user of server.basic_auth.