Docs / Start here
Getting started
This chapter explains the parts an Onyx Voice phone system is made of: tenants, extensions, devices, phone numbers, trunks and routes, and who manages what. It ends with a checklist for the first hour with a new server, with a link to the chapter for each step.
What Onyx Voice is
Onyx Voice is a business phone system that runs on one server (or two, for high availability). The server is an Ubuntu Server 24.04 machine with three main parts:
- The phone engine. It registers phones, connects calls, plays prompts and records voicemail. Phones and carriers talk to it with SIP.
- The control plane. It holds the configuration in a PostgreSQL database, writes the engine's settings, and serves the web pages and the phone provisioning files on ports 80 and 443.
- The database. Everything you set up in the console lives there. Backups copy it together with voicemail, prompts and settings (see Backup and restore).
You manage it in a web browser:
| Address | What it is | Who uses it |
|---|---|---|
https://pbx.example.com/admin | The console | System and tenant administrators |
https://pbx.example.com/portal | The portal | Phone users: voicemail, call history, forwarding, the browser softphone |
Most of the phone system's setup can also be done with the onyx command on the server, which is handy for scripts (see Command line (onyx)).
Tenants
A tenant is one company on the phone system. It has its own extensions, phone numbers, menus, call history, recordings and bill. One server can carry many tenants, which is how a reseller runs a hosted phone system. A server for a single company simply has one tenant.
Every tenant has:
- a Name, for example "Acme Dental";
- a Short code, for example
acme, used inside the system. It is 2 to 16 lowercase letters and digits and starts with a letter. It cannot change later; - a Time zone, used for business hours, voicemail time stamps and reports;
- an optional Main number, sent as caller ID when an extension has none of its own.
Tenants never see each other. Extension numbers can repeat across tenants: Acme Dental and another tenant can both have an extension 101. See Tenants (companies).
Extensions and other numbers
Inside a tenant, every number people dial is listed on the Extensions & numbers page. A number is 2 to 8 digits and is unique within its tenant. It can be:
| Kind | What it does | Suggested range |
|---|---|---|
| Extension | A person: their phones ring, then voicemail | 101 and up |
| Paging group | Phones answer on speaker at once, for announcements | 400 |
| Business hours | Sends calls one way when open, another way when closed or on holidays | 500 |
| Ring group | One number that rings several people, together or in turn | 600 |
| Call queue | Callers wait in line with music until an agent is free | 650 |
| Auto attendant | A recorded menu: "press 1 for sales, 2 for support" | 800 |
| Conference room | A number people dial to talk together, with optional PINs | 900 |
The console suggests the next free number in each range; you can type any free number. See Extensions and users, Calling features and feature codes, Auto attendants, opening hours and prompts, Call centre and Conference rooms and the switchboard.
Devices and SIP usernames
An extension is a person, not a phone. Each phone or softphone that rings for the extension is a device, with its own SIP username and password. One person can have a desk phone, a softphone on a laptop and the browser softphone at the same time, and all of them ring.
SIP usernames are made by Onyx Voice from the tenant code and the extension number:
| Device | SIP username |
|---|---|
The first phone of extension 101 in tenant acme | acme_101 |
| A second phone of the same extension | acme_101_2 |
| The browser softphone in the portal | acme_101_web |
Because the tenant code is part of the name, usernames are unique on the whole server, and two tenants' extension 101 never get in each other's way. You cannot choose a username yourself.
When you create an extension, Onyx Voice creates its first device at once and shows the SIP server, Username and Password with a Copy phone settings button, and the voicemail PIN. There are three ways to connect a phone:
- Desk phones that set themselves up. Add the phone by its MAC address on the Desk phones page. It fetches its settings from the server and keeps them up to date. See Desk phones.
- Any SIP phone or softphone. Type the server, username and password into it. See Softphones.
- The browser softphone. It is part of the portal and signs in by itself. See The user portal.
Phone numbers (DIDs)
A phone number, or DID, is an outside number your carrier sends calls to, such as +1 612 555 0100. On the Phone numbers (DIDs) page you route each number to a place in the tenant: an extension, a ring group, an auto attendant, a voicemail box, or hang up. A call to a number nobody routed is refused. See Phone numbers and routes.
Trunks and outbound routes
A trunk is the connection to a SIP carrier, for example "ExampleTel". Incoming numbers arrive on a trunk, and outside calls leave on one. A trunk either registers with a username and password, or the carrier recognises the server by its address. A system administrator can share a trunk with all tenants or give it to one tenant; tenant administrators can add trunks for their own tenant. See Trunks (carriers).
An outbound route decides which trunk carries a call to an outside number. Each tenant has its own routes, with dial patterns and a list of trunks to try in order. Without a matching route, a caller hears "not in service". Emergency numbers have their own route and caller ID. See Phone numbers and routes.
Without a trunk, only calls between extensions work.
Who manages what
Everyone signs in with an e-mail address and a password. Each sign-in account has one of three roles:
| Role | Signs in to | Can do |
|---|---|---|
| System administrator | The console | Everything: every tenant, shared trunks, server settings, security, call limits and the Server pages (network, storage, updates, backup) |
| Tenant administrator | The console | Everything inside their own tenant: extensions, numbers, routes, their own trunks, desk phones, reports |
| Phone user | The portal | Their own voicemail, call history, forwarding and do not disturb, and the browser softphone |
A system administrator picks the tenant to work on in the tenant picker at the top of the console. A tenant administrator only ever sees their own tenant. See The web console and sign-in accounts.
Your first hour
Work through these steps in order. Each one links to the chapter with the details.
- Install the server. Use the installer ISO, the Hyper-V or VMware image, or the packages on Ubuntu Server 24.04, and answer the first-boot setup on the server's screen. The setup names the server, sets its address, creates your console account and can create the first tenant. See Installing the server.
- Give it a fixed address. Phones are pointed at the server's address, so it must not change. Use a static address or a DHCP reservation. See Network, NAT and firewall.
- Set up NAT and the firewall if phones or carriers reach the server from the internet: the public address, the router's port forwards and the firewall rules. See Network, NAT and firewall.
- Sign in to the console at
https://<server>/adminwith the account from the setup. Your browser warns about the self-signed certificate the first time. - Get a proper certificate. With a public DNS name for the server, turn on Let's Encrypt on the Security page, or install your own certificate. See Names and certificates.
- Turn on two-factor sign-in for your own account on your account page, and decide whether all administrators must use it. See The web console and sign-in accounts.
- Create the tenant if the setup did not: Tenants, then New tenant. See Tenants (companies).
- Add a trunk for your carrier: Trunks (carriers), then Add a trunk. See Trunks (carriers).
- Create extensions for the people: Extensions & numbers, then Add. Give each person a portal sign-in if they want voicemail and call history in the browser. See Extensions and users.
- Connect the phones. Add desk phones by MAC address on Desk phones, or enter the SIP settings in softphones. Check Live calls: every registered phone is listed under Phones online. See Desk phones and Softphones.
- Route the phone numbers and outside calls. Route each DID on Phone numbers (DIDs) and create at least one route on Outbound routes, including the emergency route. See Phone numbers and routes.
- Build the call flow: an auto attendant, business hours with holidays, and hold music. See Auto attendants, opening hours and prompts.
- Set call limits so a stolen password cannot run up a large carrier bill. See Call limits (toll fraud).
- Set up backups to a NAS or file server on Server › Backup. See Backup and restore.
- Make test calls: extension to extension, in from a mobile phone, out to a mobile phone, and check that both sides hear each other. If audio is one-way or a phone does not register, see Troubleshooting.