TLS certificates

A TLS (or SSL) certificate is issued by a Certificate Authority (CA) and is used by clients to establish an encrypted channel and verify the server's identity.

In NethServer 8, applications do not handle TLS directly. Each cluster node runs a Traefik HTTP proxy in front of local applications, receiving TLS connections. Traefik presents the correct certificate based on the requested site name (the "Host" header in HTTP). See HTTP routes for details. Even non-HTTP services, such as IMAP, rely on Traefik to store and distribute certificates.

Upon installation, Traefik generates a self-signed certificate and uses it as the default for local applications, including the cluster web interface.

The TLS certificates page has two tabs:

• Certificates lists certificates available on every node and in use by its applications. The table can be filtered by Node, Status, Type, or by typing a keyword that matches a certificate attribute.
• ACME settings configures how each node obtains certificates from Let's Encrypt. See ACME settings.

Certificates are not shared between cluster nodes. They are valid only on the node where they are requested or uploaded.

The main types of certificates are:

• Uploaded: custom certificates added through Upload certificate. They are not renewed automatically.
• Requested: each cluster node can request one Let's Encrypt certificate containing up to 100 names. Use the Manage names action to update the list of names; this issues a new request and marks the old certificate as Obsolete. Let's Encrypt certificates are renewed automatically.

Other certificate types:

• Automatic: a Let's Encrypt certificate requested and currently used by applications or custom HTTP routes for their host name.
• Obsolete: a Let's Encrypt certificate that was obtained by an application, an HTTP route, or a user request, but now is not referenced by any of them. See also Delete a TLS certificate.

Both Automatic and Obsolete certificates are renewed automatically.

Let's Encrypt certificate requirements

Let's Encrypt is a nonprofit CA that issues TLS certificates for free. NethServer 8 uses HTTP-based ACME challenges to obtain them, which require:

1. The cluster node must be publicly reachable on the port of its challenge type. The challenge type is set per node in the ACME settings tab:

   • TLS-ALPN-01 requires port 443. It is the default for nodes installed with Traefik 3.0.0 or later.
   • HTTP-01 requires port 80. Nodes installed before Traefik 3.0.0 still use it, unless the challenge type was changed.

   Ensure the required port is open to the public internet. You can test it with sites like CSM. Also ensure there are no IP-based firewall rules on the node's network. Let's Encrypt validates challenges from unpredictable IPs, which may be blocked by geographic or custom filters.

2. Certificate names must be public domains pointing to the server's public IP. Ensure you have DNS records for both IPv4 and IPv6 addresses. Sites like VDNS can help verify DNS.

note

Wildcard certificates (e.g. *.nethserver.org) are not supported with HTTP-based ACME challenges.

Certificates obtained from Let's Encrypt are renewed automatically before expiration. Renewal attempts run daily, starting 30 days before the certificate expires.

If a certificate is marked as Expiring or Expired, check that the requirements above are still met and wait for the next renewal attempt. Alternatively, remove the certificate as explained in Delete a TLS certificate.

Request a Let's Encrypt certificate

If requirements are met, request a certificate as follows:

1. Go to Settings → TLS certificates.
2. Click Request certificate.
3. Select the cluster node that will issue the request. Only this node can use the certificate.
4. Enter the list of names to include. Each must meet the requirements.
5. Click Request certificate to confirm.

Validation may take up to 60 seconds before a timeout.

Certificates are renewed automatically by a daily process that begins 30 days before expiration. If renewal fails, an expiration alert is triggered (see Receive certificate expiration alerts). See the Let's Encrypt requirements to identify the cause.

ACME settings

The ACME settings tab lists, for each cluster node, the parameters its Traefik instance uses to obtain certificates:

• ACME directory URL: the URL of the ACME provider that issues certificates. The default is the Let's Encrypt production directory, https://acme-v02.api.letsencrypt.org/directory.
• Challenge type: how the ACME provider verifies that the node controls the requested names. It is either TLS-ALPN-01, through port 443, or HTTP-01, through port 80.

Choose HTTP-01 if port 443 of the node is not reachable from the internet, for example because another service or device handles it. Otherwise, prefer TLS-ALPN-01: port 80 can stay closed.

For tests, you can set the Let's Encrypt staging directory, https://acme-staging-v02.api.letsencrypt.org/directory. It has much higher rate limits, but its certificates are signed by a test CA that clients do not trust.

note

Changing the ACME directory URL does not replace existing certificates. After switching back from staging to production, the staging certificates stay in use until they are renewed. To replace them sooner, delete them, or use Manage names to issue a new request.

To change the settings of a node:

1. Go to Settings → TLS certificates and select the ACME settings tab.
2. Click Edit on the node row.
3. Enter the ACME directory URL and select the Challenge type.
4. Click Save.

warning

Saving the ACME settings restarts Traefik on the node, and HTTP clients connected to it are briefly disconnected. Avoid changing them during office hours.

Because of the Traefik restart, the UI may not receive the result of the operation. In that case, check the node row in the table and repeat the change if needed.

Upload custom TLS certificates

If you already have a certificate and private key, you can upload them to a node:

1. Go to Settings → TLS certificates.
2. Click Upload certificate.
3. Select the cluster node. Only this node and its applications can use the certificate.
4. Select the Certificate and Private key files. If provided by the CA, also select the Chain file. Use drag-and-drop or the file picker. All files must be PEM-encoded.
5. Click Upload.

If the upload fails, an error is shown. Otherwise, the modal closes and the list refreshes.

Common errors include wrong file order or mismatched certificate, private key, and chain. The key must not be encrypted with a passphrase.

An application uses the uploaded certificate if it matches its configured host name. Wildcard names are supported.

Uploaded certificates are added to Traefik's backup and can be restored from it.

If the certificate is signed by a private/custom certification authority (CA), it needs to be added to the OS certificate store to be trusted and to allow the upload:

• RHEL distributions (Rocky)
• Debian

Receive certificate expiration alerts

If alert notifications are configured (see Alerts notifications), the cluster sends an alert when a certificate is nearing expiration or has already expired. Alerts begin 28 days before the expiration date.

• For an Uploaded certificate, resolve the alert by uploading a new certificate. The old one can then be deleted.

• For Let's Encrypt certificates (Requested, Automatic, Obsolete), an expiration alert indicates renewal has failed. Check that requirements are still met.

  Common renewal failure causes include:

  • DNS records for a certificate name were changed or removed.
  • A firewall blocks ACME challenges, either by network address or by geographic IP rules.
  • The port required by the node's challenge type is closed.

Delete a TLS certificate

You can delete a certificate if it is no longer needed. Do this with caution, because removing a certificate can break applications.

A certificate is considered "obsolete" when no HTTP route, application, or past user request references any of its names. This only reflects the current configuration, not actual usage: an obsolete certificate may still be used by network clients to reach the node, especially if its name is also registered as a DNS record pointing to the node.

When you delete a certificate:

• Traefik is restarted and HTTP connections are closed. For some applications this may lead to client data loss.
• If no alternative matches the host name, clients will fail to reconnect.
• Automatic renewal (for Let's Encrypt) stops.

If you delete an Automatic certificate, the related HTTP route is modified and its Let's Encrypt switch is cleared.

Use Delete obsolete certificates to remove all obsolete certificates of a node in a single operation. This limits Traefik restarts.

Alternatively, to delete a single certificate:

1. Go to Settings → TLS certificates.
2. Find the certificate to remove.
3. Click Delete and confirm.

note

Deletion is irreversible. Ensure no application depends on the certificate, or install a replacement first to avoid downtime.