Docs / Start here

Installing the server

This chapter covers what the server needs, the four ways to install Onyx Voice (the installer ISO, the Hyper-V image, the VMware image and the packages on an existing Ubuntu server), the first-boot setup, the unattended setup from a seed disk, and what runs on the server afterwards.

Downloads are on onyxvoice.net. They ask for a user name and password; the page says how to get access. A SHA256SUMS file next to the downloads lets you check every file before you use it.

Requirements

Onyx Voice is its own small operating system: Ubuntu Server 24.04 with PostgreSQL and the phone engine included. Install it on a server or virtual machine of its own. On a machine that already runs other services, nothing else may use ports 80, 443 and 5060 to 5062.

Call recordings and voicemail use most of the disk over time. You can grow the disk or add a second one later from Server › Storage (see Server tools).

Choose how to install

All four end the same way: the first-boot setup on the server's screen, then the console in your browser.

The installer ISO

The ISO is Ubuntu Server 24.04's installer with Onyx Voice added. It needs no internet connection: every package is on the disc.

The disk you choose in the installer is erased. The installer uses all of it, with LVM.

1. Start the server or virtual machine from onyx-voice-<version>-installer.iso. On a VM, give it at least the resources in Requirements and turn on UEFI with Secure Boot if your hypervisor offers it.
2. The boot menu starts Install Onyx Voice after 10 seconds.
3. The installer asks for two things only: the network and the disk. Set the network card (DHCP is fine for now; the first-boot setup can make it static) and choose the disk.
4. Everything else is automatic. The installer copies Ubuntu, installs Onyx Voice and its engine from the disc, and restarts. Remove the ISO from the drive when it restarts.
5. After the restart, the first-boot setup starts on the screen. See The first-boot setup.

The server is called onyx-voice until the setup names it. Its administrator account, onyxadmin, is locked until the setup gives it a password.

Hyper-V: the VHDX image

The VHDX is a ready-made disk for a Generation 2 virtual machine. The script New-OnyxVM.ps1, next to it on the download page, creates the VM for you.

1. Copy onyx-voice-<version>.vhdx and New-OnyxVM.ps1 to the Hyper-V host.
2. Open PowerShell as an administrator on the host and run, for example:

   .\New-OnyxVM.ps1 -Vhdx .\onyx-voice-0.2.0.vhdx -Name PBX01 -SwitchName "LAN"

3. Open the VM's console in Hyper-V Manager (Connect). The first-boot setup is waiting there.

The script copies the VHDX into the VM's folder (the original stays as it is), creates a Generation 2 VM with Secure Boot and the "Microsoft UEFI Certificate Authority" template that Linux needs, turns off dynamic memory, turns on the Guest Service Interface, connects the network and starts the VM.

If you create the VM by hand instead, make it Generation 2 and set Secure Boot to the "Microsoft UEFI Certificate Authority" template, or it does not start.

VMware: the OVA image

1. In vSphere, choose Deploy OVF Template and select onyx-voice-<version>.ova. In Workstation or Fusion, open the OVA file.
2. Map the network "VM Network" to the network your phones are on.
3. Start the VM and open its console. The first-boot setup is waiting there.

The OVA describes a VM with 4 virtual CPUs, 4 GB of memory, a 64 GB disk, a VMXNET3 network card and UEFI with Secure Boot (hardware version 14). VMware Tools (open-vm-tools) are included. The VM does not take its time from the host; it uses time servers, which you can set on Server › System & updates.

Notes for both VM images

• The virtual disk is 64 GB. On first boot the system partition grows to fill it. If you made the disk larger before the first start, it grows to that size.
• Until the setup changes it, every network card uses DHCP.
• The image has no SSH keys of its own: each VM makes new ones on its first start, so two VMs from the same image never share them.

Packages on an existing Ubuntu Server

For an Ubuntu Server 24.04 (amd64) machine you already run, there are two packages on the download page: the engine, onyx-voice-engine_<version>_amd64.deb, and Onyx Voice itself, onyx-voice_<version>_amd64.deb.

1. Copy both files to the server.
2. Install them together; apt fetches what they depend on (PostgreSQL 16, sox, ufw, nftables and others) from Ubuntu:

   sudo apt install ./onyx-voice-engine_*_amd64.deb ./onyx-voice_*_amd64.deb

3. Run the setup now, on the server's screen or over SSH:

   sudo onyx-setup

   Until the setup has run once, it opens by itself on the server's screen at the next restart.

What the packages do to the machine:

• They create the service account onyx, a PostgreSQL role onyx and a database onyx in the machine's PostgreSQL 16 cluster.
• They start the services listed in What runs on the server. The web server listens on ports 80 and 443 on every address.
• They add the Onyx Voice update source and its signing key (see below).
• When an administrator (a member of the sudo group) signs in on the server's own screen, the server menu opens (see After the setup).

The update repository

The package adds this file, /etc/apt/sources.list.d/onyx-voice.sources:

Types: deb
URIs: https://onyxvoice.net/apt
Suites: stable
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/onyx-archive-keyring.gpg
Enabled: yes

The repository is signed with the Onyx Voice archive key, which the package installs in /usr/share/keyrings/onyx-archive-keyring.gpg. Because of Signed-By, the server trusts that key for this repository only. From then on, new versions arrive with Ubuntu's own updates: sudo apt update && sudo apt upgrade, or Server › System & updates in the console. A server without internet can turn the source off there and update from a new installer ISO instead. See Updates.

Servers installed from version 0.1.0 have this source switched off. Turn it on once with: sudo sed -i -e 's#^URIs:.*#URIs: https://onyxvoice.net/apt#' -e 's#^Enabled:.*#Enabled: yes#' /etc/apt/sources.list.d/onyx-voice.sources

The first-boot setup

The setup runs on the server's screen the first time it starts (from the ISO or an image), and whenever you run sudo onyx-setup. Move with the arrow keys and Tab, and confirm with Enter. Every step can be changed later in the console.

1. Welcome. The setup waits for the database to be ready, then starts.
2. First server or second. Choose The first server for a new phone system. Choose Join an existing server to make this the standby of a server you already run (see Joining an existing server).
3. Host name. Type the server's full name, for example pbx.example.com, in lowercase. Phones, softphones and browsers connect to this name, and it goes on the server's certificate. The setup sets it as the machine's name and as the phone system's Server name, and makes a new self-signed certificate for it. See Names and certificates.
4. Network. The setup shows the network card and its current address and offers:
   • Keep the current configuration;
   • DHCP, with a reservation on your DHCP server so the address never changes;
   • Static address: the address with its prefix length (for example 10.0.0.20/24), the default gateway (10.0.0.1) and the DNS servers, separated by commas.

   A phone system needs a fixed address, because phones are provisioned to it. The setup replaces the network configuration; the previous files are kept in /etc/netplan/disabled.

5. NAT. Answer Yes if phones or carriers reach the server from the internet through a router, and type the router's public address (for example 203.0.113.10) or a DNS name for it. The phone system then announces that address in its calls; without it, calls from outside have one-way audio. Answer No for a server that only serves its own network. See Network, NAT and firewall.
6. Time zone. An IANA name such as America/Chicago, Europe/Stockholm or UTC.
7. The onyxadmin password. onyxadmin is the server's own administrator account, for its screen and for SSH, with sudo. The password needs at least 10 characters. On first boot this step cannot be skipped.
8. Firewall. Answer Yes to turn on the firewall and open only what the phone system needs: SSH 22, HTTP and HTTPS 80 and 443, SIP 5060 UDP and TCP, SIP over TLS 5061, the call audio ports (UDP 10000 to 20000 unless you changed them) and UDP 5062 for desk phone plug-and-play. Addresses that keep failing to sign in are blocked separately, on the Security page.
9. Console account. Your e-mail address, your name and a password of at least 10 characters. This is the first system administrator of the console at https://<server>/admin. If the console already has one (when you run the setup again), the setup asks whether to create another.
10. First tenant. Answer Yes to create the first tenant (company) now: its name, for example "Acme Dental", and a short code, for example acme. The tenant gets the server's time zone. You can also create tenants later in the console. The setup skips this step when a tenant exists.

Tenant codes are 2 to 16 lowercase letters and digits, starting with a letter: the setup suggests one made from the company name (acmedental for "Acme Dental"), and you can shorten it to something like acme.

At the end, a summary shows the server's name and address, the console and portal addresses, your console sign-in, the first tenant, the DNS record to create and, behind NAT, the ports to forward on the router.

Joining an existing server

To make this server the standby of an existing one (two servers for high availability):

1. On the existing server, open Server › Cluster in the console and prepare it there. In Add the second server, enter this server's fixed address and press Create join token.
2. On this server, choose Join an existing server in the setup.
3. Host name is this machine's own name, for example voip2.example.com. Phones keep using the existing server's name.
4. Set the network (a fixed address, the one you gave in step 1), the time zone, the onyxadmin password and the firewall as above. There is no NAT step.
5. Paste the join token. It is long: if the server's screen cannot paste, run sudo onyx-setup over SSH instead.

The server copies the database from the existing server. The console accounts, tenants and settings come with it, so the setup creates none. The summary then says the server is the cluster's standby.

Unattended setup with a seed disk

For deploying many servers, or a second server without typing, the setup can take every answer from a file. Attach a small disk or ISO whose volume label is ONYXSEED and that holds a file named seed.json. On its first start the server reads it, sets everything up without asking and writes what it did to /var/log/onyx-setup.log.

{
  "hostname": "pbx.example.com",
  "network": { "address": "10.0.0.20/24", "gateway": "10.0.0.1", "dns": ["10.0.0.1"] },
  "timezone": "America/Chicago",
  "admin": { "sshKeys": ["ssh-ed25519 AAAA... [email protected]"], "passwordHash": "$6$..." },
  "firewall": true
}

To make the seed ISO on a Linux machine:

xorriso -as mkisofs -V ONYXSEED -o seed.iso seed.json

A seeded first server has no console account and no tenant yet; there is no NAT step either. Create them over SSH with the onyx command, for example:

onyx user add [email protected] --name "Alice" --role SystemAdmin
onyx tenant add acme --name "Acme Dental" --tz America/Chicago
onyx setting set engine.external_address 203.0.113.10

onyx user add prints a generated password. The seed disk is only read on the first start; remove it afterwards. The server deletes its copy of the file once it is done.

After the setup

• The console. Open https://<server>/admin in a browser and sign in with the account from the setup. Until the server has a proper certificate, the browser warns that the connection is not private; that is the self-signed certificate (see Names and certificates).
• The server's screen. Sign in as onyxadmin. A menu opens with Status, Network and firewall, Storage, System: updates, time, services, restart, Diagnostics: logs, tests, support bundle and Backup and restore, the same tools as the console's Server pages, plus Open a shell. Over SSH, open it with sudo onyx-console.
• The setup again. Run sudo onyx-setup, or choose Run the setup wizard again under System: updates, time, services, restart in the menu.
• Commands. onyx help lists the phone system commands (see Command line (onyx)). onyxadmin can run them without sudo.

What runs on the server

Server › System & updates lists these services with their state and lets you restart them. Restarting the engine drops every call in progress; restarting onyx-voice makes the console unavailable for a few seconds, and calls continue. If onyx-voice stops, the engine keeps carrying calls with the settings it has.

Where things live

/etc/onyx-voice/secret.key encrypts the two-factor sign-in keys of console accounts. Backups include it; if it is lost, everyone who uses two-factor sign-in has to set it up again.