Skip to content
BILLETKnowledge Base

Create the certificate authority

Create the portal's own certificate authority once, on the first portal node, and keep it safe. Hosts and relays are issued certificates from it.

For
Administrators
Applies to
Billet 1.0
Updated

The portal runs its own certificate authority (CA). It issues certificates to hosts and relays, so the Billet app and the portal can check they are talking to the deployment's own machines. Until it exists, the portal keeps serving, but cannot issue those certificates, so hosts and relays cannot enroll fully.

This is not the portal's public HTTPS certificate. That one comes from a public authority such as Let's Encrypt and is held by your reverse proxy.

Create it

In the console: open Deployment, find Certificate authority, and press Create the certificate authority.

Or on the server:

sudo billet-portal-task task ca:init -e production

Either prints the root certificate's SHA-256 fingerprint. Write it down: it is how you, and the people using the Billet app, check that a copy of the root is the right one.

File Kept at Who reads it
Root certificate /var/lib/billet-portal/ca/ca.crt Anyone. The portal serves it at /ca.pem.
Signing key /var/lib/billet-portal/ca/ca.key, mode 0600 The portal, and nothing else

Nothing else creates a CA: not the portal when it starts, and not a request to /ca.pem. That is deliberate. See the next section.

A second portal node

Warning: A second portal node must be given a copy of the first node's CA directory before it starts. Never create a CA on it. Two nodes with different CAs issue certificates that only half the deployment trusts, and connections then fail intermittently, depending on which node answered.

On the new node, before starting its portal:

sudo install -d -o billet -g billet -m 0700 /var/lib/billet-portal/ca
sudo rsync -a --chown=billet:billet \
  node1:/var/lib/billet-portal/ca/ /var/lib/billet-portal/ca/
sudo chmod 600 /var/lib/billet-portal/ca/ca.key

Then check both nodes print the same fingerprint:

sudo openssl x509 -in /var/lib/billet-portal/ca/ca.crt -noout -fingerprint -sha256

Keep it safe

  • Back up /var/lib/billet-portal/ca with the database and /etc/billet. Losing the signing key means replacing the CA.
  • Replace it... on the Deployment page makes a new CA. Every host, relay and Billet app then has to trust the new root, so it interrupts the whole deployment. Do it only when the key may have been exposed.

Next

Activate your license.