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
| Small office (minimum) | What the VM images are set to | |
|---|---|---|
| Processor | 2 cores, 64-bit x86 (amd64) | 4 virtual CPUs |
| Memory | 4 GB | 4 GB, fixed (not dynamic memory) |
| Disk | 40 GB, more if you record calls | 64 GB virtual disk |
| Operating system | Ubuntu Server 24.04 LTS (included in the ISO and the images) | |
| Network | One network card with a fixed IPv4 address | DHCP until the setup changes it |
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
| You have | Use |
|---|---|
| A physical server, or a hypervisor other than Hyper-V and VMware | The installer ISO |
| Hyper-V (Windows Server or Windows 10/11 Pro) | The VHDX disk and New-OnyxVM.ps1 |
| VMware vSphere, Workstation or Fusion | The OVA appliance |
| An Ubuntu Server 24.04 machine you already run | The packages |
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.
- 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. - The boot menu starts Install Onyx Voice after 10 seconds.
- 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.
- 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.
- 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.
- Copy
onyx-voice-<version>.vhdxandNew-OnyxVM.ps1to the Hyper-V host. - Open PowerShell as an administrator on the host and run, for example:
.\New-OnyxVM.ps1 -Vhdx .\onyx-voice-0.2.9.vhdx -Name PBX01 -SwitchName "LAN" - 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.
| Parameter | Default | What it is |
|---|---|---|
-Vhdx | (required) | The downloaded VHDX file |
-SwitchName | (required) | The Hyper-V virtual switch for the phone network |
-Name | Onyx Voice | The VM's name |
-Path | The host's default VM folder | Where the VM and its disk go |
-ProcessorCount | 4 | Virtual CPUs |
-MemoryBytes | 4GB | Memory |
-VlanId | 0 (none) | A VLAN ID for the network adapter, for example your voice VLAN |
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
- In vSphere, choose Deploy OVF Template and select
onyx-voice-<version>.ova. In Workstation or Fusion, open the OVA file. - Map the network "VM Network" to the network your phones are on.
- 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 three packages on the download page: the engine, onyx-voice-engine_<version>_amd64.deb, Onyx Voice itself, onyx-voice_<version>_amd64.deb, and the speech package, onyx-voice-speech_<version>_amd64.deb, with the voices greetings are made in on the server. The speech package is optional; without it, greetings from text need a cloud voice service.
- Copy the files to the server.
- 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 ./onyx-voice-speech_*_amd64.deb - Run the setup now, on the server's screen or over SSH:
sudo onyx-setupUntil 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 roleonyxand a databaseonyxin 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
sudogroup) 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 first time the server starts (from the ISO or an image), its screen shows where to continue, in a web browser:
Finish setting up this server in a web browser. Open:
https://192.168.10.20/setup
Setup code: K7PM-4XRD
Open that address from a computer on the same network. The browser warns about the certificate the first time, because the server uses a certificate it made itself until it has a public name: continue to the site. Type the setup code from the server's screen; it makes sure that nobody else on the network can set the server up before you. Nothing needs to be typed on the server's own screen.
No address on the screen? The network has no DHCP server. Press N on the server's screen to give it a static address, then open the address it shows.
No browser at hand? Press T to answer the same questions on the server's own screen instead (arrow keys and Enter). Finishing there closes the web setup.
The setup runs in steps. Back returns to the previous step with your answers kept, and the steps on the left lead back to any step you have done. Nothing changes on the server until you press Set up the server on the last page. Every answer can be changed later in the console.
- Welcome. Choose A new phone system, or Join an existing server to make this the standby of a server you already run (see Joining an existing server).
- Host name. The server's full name with its domain, for example
pbx.example.com; a name without a domain, such asonyx-voice, is refused. For a server used only on your own network, a name likepbx.localworks. 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. - Network. The page shows the network card, its current address, gateway and DNS servers, and offers:
- Keep it as it is: fine when your DHCP server always gives the server the same address (a reservation);
- DHCP;
- Static address: the address with its prefix length (for example
10.0.0.20/24), the gateway (10.0.0.1) and the DNS servers.
A phone system needs a fixed address, because phones are provisioned to it. A new static address is applied last; the page then tells you to continue at the new address. The previous network files are kept in
/etc/netplan/disabled. - Internet access. Choose Through a router (NAT) 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. Choose Only this network otherwise. See Network, NAT and firewall. - Time zone. Preset to your browser's time zone.
- Server account. The password of
onyxadmin, the server's own administrator account for its screen and for SSH, withsudo. At least 10 characters. - Firewall. Turn it on to 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), UDP 5062 for desk phone plug-and-play and 3478 (UDP and TCP) for the STUN service. Addresses that keep failing to sign in, or flood the server, are blocked separately (see Security).
- Web console. Your e-mail address, your name and a password of at least 10 characters: the first system administrator of the console at
https://<server>/admin. - First company. Create it now with its name, for example "Acme Dental", and a short code, or Later in the console. The company gets the server's time zone.
- Review. Every answer with a Change link. Set up the server applies them; the page shows the progress (about a minute, with one restart of the service, after which the page reconnects by itself) and then links to the web console.
Tenant codes are 2 to 16 lowercase letters and digits, starting with a letter: the setup suggests one made from the company name (
acmedentalfor "Acme Dental"), and you can shorten it to something likeacme.
Once the setup is done, https://<server>/setup only says so and links to the console. On a server that is already in use (accounts exist), the web setup never opens.
sudo onyx-setup on the server's screen or over SSH is the same setup in text form, for example to change the network later without the console.
Joining an existing server
To make this server the standby of an existing one (two servers for high availability):
- 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.
- In this server's web setup, choose Join an existing server.
- Host name is this machine's own name, for example
voip2.example.com. Phones keep using the existing server's name. - 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 internet access step.
- Paste the join token.
The server copies the database from the existing server. The console accounts, companies and settings come with it, so the setup creates none. The last page 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
}
| Field | What it does |
|---|---|
hostname | The full host name, as in the interactive setup. |
network | A static address: address with prefix length, gateway and dns (a list). All three are needed; leave network out to keep DHCP. |
timezone | An IANA time zone name. |
admin.sshKeys | Public keys that may sign in as onyxadmin over SSH. |
admin.passwordHash | The onyxadmin password as a SHA-512 crypt hash, made with openssl passwd -6. Give a key, a hash or both. With keys and no hash, onyxadmin signs in with its key and may use sudo without a password. |
firewall | true turns on the firewall with the phone system's ports, as in the interactive setup. |
join | A join token from Server › Cluster of an existing server: this server becomes its standby. |
witness | A witness token instead of join: this machine becomes the cluster's witness, with no phone system on it (see High availability). |
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>/adminin 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 withsudo 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 helplists the phone system commands (see Command line (onyx)).onyxadmincan run them withoutsudo.
What runs on the server
| Service | What it is |
|---|---|
onyx-voice | The control plane: the console, the portal, phone provisioning and the API, on ports 80 and 443. It writes the engine's settings and watches the engine. |
onyx-voice-engine | The phone engine: phones, trunks and calls. |
postgresql | The database. |
onyx-voice-init | Runs before every start of onyx-voice: prepares the database, the configuration and the folders. |
onyx-os.socket | The helper behind the console's Server pages (network, storage, updates, backup). |
onyx-backup.timer | Scheduled backups, once you set a schedule. |
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
| What | Where |
|---|---|
| Engine programs, modules and sounds | /usr/lib/onyx-voice/engine (from the package; do not change) |
| Control plane | /usr/lib/onyx-voice/app (from the package; do not change) |
| Engine settings, written by Onyx Voice | /etc/onyx-voice/engine (do not edit: they are rewritten) |
| Control plane settings | /etc/onyx-voice/appsettings.json |
| Database password and the key for stored secrets | /etc/onyx-voice/db-password, /etc/onyx-voice/secret.key |
| Tenant prompts and hold music, engine state, certificates | /var/lib/onyx-voice |
| Voicemail, recordings, faxes | /var/spool/onyx-voice |
| Logs | /var/log/onyx-voice |
| Network configuration written by Onyx Voice | /etc/netplan/90-onyx.yaml |
| Unattended setup log | /var/log/onyx-setup.log |
/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.