Skip to main content

Setting up Let's Encrypt for Halon

Let's Encrypt offers a convenient way to enable SSL certificates for Halon as well as the web administration, ensuring automatic certificate renewal. Setting up Let's Encrypt for Halon is pretty straightforward, and you can start by following the official Certbot instructions to set up the basic requirements needed.

smtpd​

For the smtpd process, you will need to incorporate the SSL certificates into both the startup and running configurations to avoid having to restart the service when Certbot renews the certificates:

/src/config/smtpd.yaml
pki:
  private:
    - id: mx.example.com
      privatekey:
        path: /etc/letsencrypt/live/mx.example.com/privkey.pem
/src/config/smtpd-app.yaml
pki:
  private:
    - certificate:
        path: /etc/letsencrypt/live/mx.example.com/fullchain.pem
      id: mx.example.com

halon-web​

To enable Let's Encrypt for the web component, ensure you have halon-web installed on your server. Then, set up the SSL certificate by adding it to the pki directive for the listener:

/src/config/web.yaml
- pki:
    certificate:
      path: /etc/letsencrypt/live/mx.example.com/fullchain.pem
    privatekey:
      path: /etc/letsencrypt/live/mx.example.com/privkey.pem

Renewal​

It is important to enable the renewal hook for Certbot to ensure that services are restarted during certificate renewal, and the new certificates are loaded into the configuration. If your web server exclusively uses port 443 for HTTPS, you can opt for the standalone authentication method. This method is suitable when no other web server or service occupies port 80:

mx.example.com.conf
# renew_before_expiry = 30 days
version = x.x.x
archive_dir = /etc/letsencrypt/archive/mx.example.com
cert = /etc/letsencrypt/live/mx.example.com/cert.pem
privkey = /etc/letsencrypt/live/mx.example.com/privkey.pem
chain = /etc/letsencrypt/live/mx.example.com/chain.pem
fullchain = /etc/letsencrypt/live/mx.example.com/fullchain.pem

# Options used in the renewal process
[renewalparams]
account = ...
authenticator = standalone
server = https://acme-v02.api.letsencrypt.org/directory
renew_hook = systemctl restart halon-web; systemctl reload halon-smtpd
reuse_key = True

However, if halon-web uses port 80 or you wish to minimize downtime, you should consider using the webroot authentication method instead. For halon-web the webroot path is /opt/halon/web/node_modules/@halon/web-frontend/dist.

To verify the automatic renewal process for the certificate(s), you can perform a dry run by using the following command:

sudo certbot renew --dry-run