Onyx VoiceDocumentation
All chapters

Docs / Start here

Names and certificates

This chapter covers the server's name, the certificate it uses for HTTPS and for encrypted SIP (SIP over TLS), and the three kinds of certificate it can have: the self-signed one it makes itself, a free Let's Encrypt certificate it gets and renews by itself, and your own certificate files.

The server's name

The phone system's name is the Server name setting (engine.hostname) on Server settings, for example pbx.example.com. The first-boot setup sets it from the host name you type (see Installing the server).

Onyx Voice uses the name for:

  • the Let's Encrypt certificate, which is issued for this name;
  • desk phones with encrypted calls: when the certificate is a trusted one, they are set up to connect to this name, so the name matches the certificate;
  • the SIP server shown with a device's phone settings, next to the server's own address, when no public address is set.

The name needs a DNS record that points to the address phones use (see Network, NAT and firewall).

The server also has a machine host name, shown in the console's header and changed on Server › System & updates under This server (Change host name). The first-boot setup sets both to the same name. Changing the host name on the System & updates page does not change Server name: change both.

Changing the name

  1. Create a DNS record for the new name, for example voice.example.com, pointing to the server.
  2. On Server settings, change Server name and press Save.
  3. On Server › System & updates, change Host name to the same name and press Change host name. The control plane restarts with it; calls in progress continue.
  4. With Let's Encrypt on, the server requests a certificate for the new name within about a minute. To keep the old name working while phones and apps move over, put it in Also valid for (see below).
  5. Point phones, softphones and DHCP option 66 that use the old name at the new one (see Desk phones).

Which certificate is in use

The server picks its certificate in this order:

  1. Your own certificate files, when Certificate file and Certificate key file are set and both files exist;
  2. Let's Encrypt, once it has issued a certificate;
  3. Self-signed (made by this server) otherwise.

To see which one is in use, open Security (system administrators only). The Certificate card at the top shows:

  • In use: one of the three kinds above;
  • Names: the names and addresses the certificate is valid for;
  • Issued by;
  • Valid until, with the number of days left.

The box in the console's menu also shows it: HTTPS certificate with SELF-SIGNED or TRUSTED, the name and the days until it expires.

The self-signed certificate

Until it has another certificate, the server makes its own. It is valid for the machine's host name, localhost, 127.0.0.1 and every IPv4 address of the server, so https://10.0.0.20/admin works as well as the name. It lasts five years. Each time the control plane starts, it makes a new one if less than 30 days are left or if the server's addresses changed.

A self-signed certificate encrypts the connection, but nobody vouches for it:

  • Browsers warn that the connection is not private the first time you open the console or the portal. You can continue past the warning.
  • Many desk phones refuse it for encrypted calls (SIP over TLS).
  • Desk phones fetch their settings over plain HTTP, which does not need a certificate, so setting up phones works with a self-signed certificate.

It is fine for a first look or a phone system used only inside the office. For anything else, use Let's Encrypt or your own certificate.

The first-boot setup makes a new self-signed certificate when it sets the name, and so does Change host name on System & updates (the console restarts for a few seconds; calls continue). To make a new one by hand, for example after adding an address to the server, run on the server:

sudo rm /var/lib/onyx-voice/tls/self-signed.pfx
sudo systemctl restart onyx-voice

Let's Encrypt

Let's Encrypt is a free certificate authority. The server gets a certificate from it, proves that it owns the name, and renews it before it runs out.

What it needs:

  • Server name is a full public DNS name, for example pbx.example.com. An IP address, a single word, or a name ending in .local, .lan or .internal cannot get a certificate.
  • A public DNS record for the name points to the server's public address.
  • Port 80 reaches the server from the internet (forwarded on the router, open on the firewall). Let's Encrypt checks each name by fetching a file from it over plain HTTP.
  • The server can reach Let's Encrypt over HTTPS.

If the name is not suitable, the Certificate card says so: "Let's Encrypt is not possible yet: ...", with the reason.

To turn it on:

  1. Open Security.
  2. On the Certificate card, tick Get a certificate for pbx.example.com from Let's Encrypt and renew it automatically (the card shows your server's name).
  3. In Contact e-mail, enter an address that is read, for example [email protected]. Let's Encrypt writes there about expiry problems.
  4. In Also valid for, add other names for the same certificate if you need them, separated by commas. This keeps an old name working while phones and apps move to a new one. Each name needs a DNS record pointing to the server.
  5. Tick I accept the Let's Encrypt subscriber agreement.
  6. Press Save. The certificate is requested within a minute. To request it now and wait for the answer, press Get it now.

The card shows the result of the last request, for example "Certificate for pbx.example.com issued, valid until 2027-01-05." HTTPS uses the new certificate at once, and the engine loads it for SIP over TLS.

When a request fails, the message says why. The most common cause is "port 80 of pbx.example.com must reach this server from the internet": check the DNS record, the port forward and the firewall. After a failure, the server waits an hour before it tries again by itself, because Let's Encrypt limits failed attempts; changing the name, the e-mail address or Also valid for makes it try again at once, and Get it now tries at once.

Renewal

You do not need to do anything. The server checks the certificate every minute or so and renews it 30 days before it expires, and as soon as the names it needs change. A renewed certificate replaces the old one without dropping calls: phones connected over SIP over TLS stay connected.

On a cluster, only the active server requests and renews the certificate; the standby gets a copy (see High availability).

Turning it off

Untick the box and press Save. Renewals stop, but the server keeps using the Let's Encrypt certificate it has, also after it expires. To go back to a self-signed certificate, remove the Let's Encrypt files and restart the control plane:

sudo rm /var/lib/onyx-voice/acme/cert.pem /var/lib/onyx-voice/acme/key.pem
sudo systemctl restart onyx-voice

Trying it on a test server

Under Test server (staging, Pebble) you can point the server at another ACME server: ACME directory (for Let's Encrypt's staging server, https://acme-staging-v02.api.letsencrypt.org/directory) and Test server's CA file, a PEM file on the server that is trusted only for that ACME server. Certificates from a test server are not trusted by browsers or phones. Leave both fields empty for the real Let's Encrypt.

Your own certificate

Use your own certificate when it comes from your company's certificate authority, when you have a wildcard certificate, or when the server cannot be reached from the internet on port 80.

You need two PEM files:

  • the certificate, followed by any intermediate certificates;
  • its private key, not protected by a passphrase.
  1. Copy the files to the server, for example to /etc/onyx-voice/certs/. The phone system runs as the account onyx, which must be able to read them, and files under /home are out of its reach:
    sudo mkdir -p /etc/onyx-voice/certs
sudo cp pbx.crt pbx.key /etc/onyx-voice/certs/
sudo chown root:onyx /etc/onyx-voice/certs/pbx.crt /etc/onyx-voice/certs/pbx.key
sudo chmod 640 /etc/onyx-voice/certs/pbx.crt /etc/onyx-voice/certs/pbx.key
  2. On Server settings, in the Calls and network group, set Certificate file to /etc/onyx-voice/certs/pbx.crt and press Save, then set Certificate key file to /etc/onyx-voice/certs/pbx.key and press Save. Both must be full paths.
  3. Within about a minute, the Certificate card on Security shows In use: Your own certificate files. The engine switches SIP over TLS to the new files with a restart, which waits until no calls are up.

Your own files take precedence over Let's Encrypt; turn Let's Encrypt off so it does not keep renewing a certificate that is not used.

To renew, replace the two files at the same paths. Within about a minute the server uses the new certificate for HTTPS, and the engine loads it for SIP over TLS. If you use new file names instead, update both settings; the engine then restarts once no calls are up.

To stop using your own files, empty both settings and save. The server goes back to Let's Encrypt (if it has a certificate) or a self-signed certificate.

Check the paths and the permissions before you save. If the files exist but the onyx account cannot read them, or the key does not belong to the certificate, the console stops answering over HTTPS. Fix the files, or clear the settings on the server with onyx setting unset engine.tls_cert_file and onyx setting unset engine.tls_key_file.

How HTTPS and SIP over TLS share the certificate

One certificate serves both:

  • HTTPS on port 443: the console, the portal, the browser softphone and desk phone settings over HTTPS. Plain HTTP on port 80 sends browsers on to HTTPS, except for desk phone settings (phones at factory settings do not trust a self-signed certificate), the Let's Encrypt check and the health check.
  • SIP over TLS on port 5061 (the SIP TLS port setting): encrypted calls from desk phones and softphones, and TLS trunks. It uses TLS 1.2, which current phones and carriers support, and does not ask phones for certificates of their own.

The engine reads your own certificate files directly. A self-signed or Let's Encrypt certificate is copied for it, with its chain, to /var/lib/onyx-voice/tls/sip.crt and sip.key. When the certificate changes, the engine reloads it on the running SIP over TLS listener, so connected phones stay registered.

Encrypted calls need a certificate the phones trust. With Let's Encrypt or a certificate from a public certificate authority and a full server name, desk phones set up for encrypted calls connect to the server name and check the certificate against it. With your company's own certificate authority, the phones must trust that authority too. See Desk phones and Security.