Docs / Reference

Command line (onyx)

Everything you set up in the console can also be done from a shell on the server with the onyx command: tenants, extensions, phones, numbers, queues, settings and more. This chapter lists every command with its options and an example. It ends with the root tools behind the Server pages and the console menu: onyx-os, onyx-console, onyx-setup and onyx-ha.

Running onyx

Sign in to the server over SSH (or on its own screen) as the administrator account you made during setup, onyxadmin.

• sudo onyx ... always works. When root runs it, onyx switches to the service account onyx, which owns the phone system's configuration.
• Members of the onyx group can run onyx ... without sudo. The setup puts onyxadmin in that group (sign out and in again once after setup for it to count).
• onyx help prints the list of commands. Running onyx with nothing after it prints the same list.

How options work:

• Options are --name value or --name=value. A value cannot start with --; use the = form if it must.
• Switches such as --record or --join-empty take no value.
• Some options can be given several times: --pattern, --option, --hours and --holiday.
• On and off options take on or off (also yes/no, true/false).
• Put values with spaces in quotes: --name "Front desk".

When something is wrong, onyx prints a line starting with error: (a value it does not accept), engine: (it cannot reach the phone engine) or database: and exits with code 1. On success it exits with 0, so you can use it in scripts.

Every change is recorded in Change history like a change made in the console. The person shows as your Linux user name (with sudo, the user who ran sudo).

Destinations: wherever a command asks where a call goes (a DID, a failover, an auto attendant key), the answer is one of:

• a number in the tenant: an extension, ring group, queue, conference room, auto attendant or time condition, for example 500
• a voicemail box: vm:101
• hangup

Tenants

onyx tenant list
onyx tenant add <code> --name <name> [--domain <sip domain>] [--tz <IANA zone>]
onyx tenant set <code> [--name ..] [--main-number <number>] [--tz <zone>] [--enabled on|off] [--moh <class>|default]
onyx tenant delete <code> --yes

• tenant list shows every tenant with its code, name, main number, SIP domain, time zone and whether it is enabled.
• tenant add creates a tenant. The code is 2 to 16 lower-case letters or digits and starts with a letter (acme, not acme-dental). It is used inside the phone system and cannot be changed later. Without --tz the time zone is America/Chicago.
• tenant set changes the name, the main number, the time zone, turns the tenant off or on, or picks its hold music class (--moh default goes back to the standard music).
• tenant delete removes the tenant with all its extensions and devices. It refuses unless you add --yes.

sudo onyx tenant add acme --name "Acme Dental" --tz America/Chicago

See Tenants (companies).

Extensions

onyx ext list <tenant>
onyx ext add <tenant> <number> --name <name> [--email <address>]
onyx ext show <tenant> <number>
onyx ext set <tenant> <number> [--name ..] [--email ..] [--callerid ..] [--emergency-cid ..] [--vm on|off] [--pin ..]
                               [--ring <seconds>] [--enabled on|off] [--record always|never] [--supervisor on|off] [--operator on|off]
onyx ext calls <tenant> <number> [--dnd on|off] [--always <number>] [--busy <number>] [--noanswer <number>]
onyx ext delete <tenant> <number>

• ext list shows every number in the tenant: extensions, but also ring groups, queues, conference rooms, auto attendants, time conditions and paging groups, with their devices and call handling.
• ext add creates a user extension (2 to 8 digits) with voicemail and one SIP device. It prints the voicemail PIN and the device's SIP server, user name and password. onyx device show prints the credentials again later.
• ext show prints one extension: name, e-mail, caller ID, voicemail and PIN, ring time and its devices.
• ext set changes an extension. --callerid is the number shown on outside calls, --emergency-cid the number sent on emergency calls, --vm turns voicemail on or off, --pin sets the voicemail PIN, --ring is how many seconds it rings before voicemail. --record always records every call of this extension. --supervisor on lets it listen in (*222), coach (*223) and join (*224) calls. --operator on gives the person the switchboard in the portal.
• ext calls sets call handling the way the feature codes do: do not disturb (*76), forward always (*72), on busy (*90) and on no answer (*52). Give an option with no value to clear that forward, for example --always on its own.
• ext delete deletes the number, whatever it is. This is also how you delete a ring group, queue, conference room, auto attendant, time condition or paging group.

sudo onyx ext add acme 101 --name "Alice Example" --email [email protected]
sudo onyx ext calls acme 101 --noanswer 6125550100

See Extensions and users and Calling features and feature codes.

Devices and hot desks

onyx device list <tenant> [<number>]
onyx device add <tenant> <number> [--kind sip|webrtc|provisioned] [--label ..] [--mac ..] [--model ..]
onyx device show <sip username>
onyx device secret <sip username>
onyx device delete <sip username>
onyx device hotdesk <tenant> <sip username> on|off
onyx device secure <tenant> <sip username> on|off
onyx hotdesk list [<tenant>]

• device list shows the tenant's devices (or one extension's) with SIP user name, kind, label, MAC address and model.
• device add adds a device to an extension and prints its credentials. --kind sip (the default) is any SIP phone or app, webrtc the browser softphone, provisioned a desk phone that sets itself up: give its --mac and --model.
• device show prints a device's SIP server, user name and password. SIP user names are unique on the whole server, so no tenant is needed.
• device secret makes a new random SIP password. The phone stops registering until it gets the new one (a provisioned phone gets it at its next provisioning check).
• device delete removes the device.
• device hotdesk on turns a desk phone into a shared hot desk: people log in with *55 (their extension and voicemail PIN) and out with *56. When you turn it off, someone still logged in stays routed there until they dial *56 or the service's next check, within 2 minutes.
• device secure on turns on encrypted calls for the device: it registers over SIP TLS and the audio must be SRTP.
• hotdesk list shows who is logged in at which desk.

sudo onyx device add acme 102 --kind provisioned --mac 805ec0123456 --model T54W --label "Reception"

See Desk phones and Softphones.

Sign-in accounts

onyx user list [--tenant <code>]
onyx user add <email> --name .. [--role SystemAdmin|TenantAdmin|User] [--tenant <code>] [--extension <number>] [--password-stdin]
onyx user password <email> [--password-stdin]
onyx user delete <email>
onyx user 2fa-reset <email>

• user list shows console and portal accounts with role, tenant, two-factor sign-in and last sign-in.
• user add creates an account. Without --role, an account with --tenant is a TenantAdmin and one without is a SystemAdmin. A User is a portal user: give --tenant and --extension to link the account to the extension whose phone, voicemail and calls it shows. onyx prints a generated password, unless you pipe your own in with --password-stdin (it reads the first line).
• user password sets a new password (generated, or from stdin) and signs the person out everywhere.
• user delete removes the account.
• user 2fa-reset turns two-factor sign-in off for someone who lost their phone. They sign in with the password and set it up again (they are asked to if it is required).

sudo onyx user add [email protected] --name "Alice Example" --role User --tenant acme --extension 101

Reading the password from stdin keeps it out of the shell history and the process list:

read -rs PW && printf '%s\n' "$PW" | sudo onyx user password [email protected] --password-stdin

See The web console and sign-in accounts.

Ring groups, paging and conference rooms

onyx group add|set <tenant> <number> --name .. --members 101,102,.. [--strategy ringall|hunt] [--member-ring 15] [--ring 60]
                                     [--cid-prefix ..] [--failover vm:101|<number>|hangup]
onyx group list <tenant>
onyx page add <tenant> <number> --name .. --members 101,102 [--duplex]
onyx page list <tenant>
onyx conf add|set <tenant> <number> --name .. [--pin 1234] [--moderator-pin 9876] [--max 0] [--wait-for-moderator]
                                    [--start-muted] [--quiet] [--record]
onyx conf list <tenant>

• group add creates a ring group and group set replaces its settings (give every option again; anything left out goes back to its default). --strategy ringall rings everyone at once for --ring seconds; hunt rings members one after another for --member-ring seconds each. Members can be extensions or outside numbers. --cid-prefix is put in front of the caller's name ("Sales: "). --failover is where the call goes when nobody answers (default hangup).
• page add creates a paging group that calls every member's phone on speaker. --duplex lets them answer back (intercom).
• conf add creates a conference room; conf set replaces its settings. --pin is asked of everyone, --moderator-pin makes the caller a moderator. --max 0 means no limit. --wait-for-moderator keeps people on hold music until a moderator joins, --start-muted mutes everyone but moderators, --quiet drops the join and leave sounds, --record records the room.

sudo onyx group add acme 600 --name Sales --members 101,102,103 --strategy ringall --ring 30 --failover vm:101
sudo onyx conf add acme 900 --name "Board room" --pin 4826 --moderator-pin 9173 --wait-for-moderator

See Calling features and feature codes and Conference rooms and the switchboard.

Queues

onyx queue add|set <tenant> <number> --name .. [--agents 101,102:2] [--static 103]
                   [--strategy rrmemory|ringall|leastrecent|fewestcalls|random|linear]
                   [--agent-ring 20] [--retry 5] [--wrapup 10] [--max-wait 600] [--max-callers 0] [--join-empty]
                   [--no-position] [--hold-time] [--announce-every 60] [--service-level 20] [--cid-prefix ..] [--record]
                   [--overflow vm:101|<number>|hangup] [--callback [--callback-prefix 9]]
onyx queue list <tenant>
onyx queue callbacks <tenant>

• queue add creates a call queue; queue set replaces its settings. Give every option again: anything left out goes back to its default.
• --agents are agents who log in and out with *45 and pause with *46. A number after a colon is the agent's penalty: 102:2 gets calls only when agents with a lower penalty are busy. --static agents are always logged in.
• --agent-ring is how long an agent's phone rings, --retry the pause before the next try, --wrapup the seconds an agent gets after a call before the next one.
• --max-wait is the longest a caller waits (seconds) before going to --overflow. --max-callers 0 means no limit. --join-empty lets callers in even when no agent is logged in.
• Callers hear their position unless you give --no-position; --hold-time adds the expected wait. --announce-every sets how often (seconds). --service-level is the answer time the reports measure against.
• --callback lets callers press 1 to be called back instead of waiting. --callback-prefix is dialled in front of their number (for example 9 for an outside line).
• queue list shows the queues; agents marked * are always logged in. queue callbacks shows the latest callback requests and how they went.

sudo onyx queue add acme 650 --name Support --agents 101,102,103:2 --strategy rrmemory --max-wait 300 --overflow vm:101 --callback

See Call centre.

Auto attendants and time conditions

onyx ivr add|set <tenant> <number> --name .. [--greeting <prompt name>] --option 1=600 [--option 0=101 ..]
                 [--no-direct-dial] [--timeout 5] [--attempts 3] [--timeout-dest ..] [--invalid-dest ..]
onyx ivr list <tenant>
onyx time add|set <tenant> <number> --name .. --hours "mon-fri 08:00-17:00" [--hours ..]
                  [--holiday 2026-12-25=Christmas | --holiday 12-25=Christmas ..] --open <dest> --closed <dest> [--holiday-dest <dest>]
onyx time list <tenant>
onyx time override <tenant> <number> open|closed|auto

• ivr add creates an auto attendant (a menu callers press keys in); ivr set replaces it. --greeting names a prompt uploaded under Prompts & hold music or with onyx media add. Each --option is one key (0-9, * or #), an equals sign and a destination. Callers may also dial an extension directly unless you give --no-direct-dial. After --timeout seconds without a key the menu repeats, up to --attempts times, then the call goes to --timeout-dest; a key with no option goes to --invalid-dest (both default to hangup).
• time add creates a time condition that sends calls to --open during the opening hours and to --closed outside them. Give --hours once per block of days. A --holiday with a full date happens once; one with only month and day (12-25) every year. On holidays calls go to --holiday-dest, or to the closed destination when it is not set.
• time override forces a time condition open or closed until you set it back to auto. Phones can do the same: *27 plus the number closes, *28 plus the number opens.

sudo onyx ivr add acme 800 --name "Main menu" --greeting welcome --option 1=600 --option 2=650 --option 0=101 --timeout-dest 101
sudo onyx time add acme 500 --name "Office hours" --hours "mon-fri 08:00-17:00" --hours "sat 09:00-12:00" --holiday 12-25=Christmas --open 800 --closed vm:101

Create the menu before the time condition that points at it: a destination must exist.

See Auto attendants, opening hours and prompts.

Prompts and hold music

onyx media add <tenant> <name> <file|-> [--moh <class>]
onyx media list <tenant>
onyx media delete <tenant> <id>

• media add uploads a WAV, MP3, FLAC or OGG file and converts it for the engine. A - instead of a file name reads the audio from stdin. Without --moh it becomes a prompt (for auto attendant greetings); with --moh <class> it is added to that hold music class.
• media list shows prompts and hold music with their id, class and length. media delete removes one by id.

sudo onyx media add acme welcome /tmp/welcome.mp3

Trunks

onyx trunk providers [<id>]
onyx trunk list [--tenant <code>]
onyx trunk add <name> [--tenant <code>] --mode register|ip --host <host> [--port 5060] [--transport udp|tcp|tls]
               [--user ..] [--auth-user ..] [--secret ..] [--from-user ..] [--from-domain ..]
               [--match <ip,cidr,..>] [--did-source auto|ruri|to] [--codecs ulaw,alaw] [--max-channels N] [--no-qualify]
               [--provider <id>] [--dial-format|--callerid-format asis|e164plus|e164|nanp11|nanp10]
               [--callerid-header pai|rpid|from] [--dial-prefix <tech prefix>]
onyx trunk enable|disable|delete <name> [--tenant <code>]
onyx trunk srtp <name> on|off [--tenant <code>]
onyx trunk status

• trunk providers lists the carrier templates; with an id it shows one carrier's servers, authentication, number formats and notes.
• trunk list shows the trunks with their owner (system for a trunk every tenant may use, or the tenant's code).
• trunk add connects a carrier. Without --tenant the trunk is a system trunk. --mode register registers with --user and --secret; --mode ip accepts calls from the addresses in --match. --provider starts from a carrier template (mode, server, number formats, codecs); any option you give still wins. --dial-format and --callerid-format set how numbers are written to the carrier: asis, e164plus (+16125550100), e164 (16125550100), nanp11 (11 digits) or nanp10 (10 digits). --callerid-header picks where the caller ID goes. --dial-prefix is a tech prefix some carriers want in front of every number. --no-qualify is for carriers that do not answer the engine's OPTIONS checks. Without --codecs a trunk offers ulaw, alaw and G.722.
• trunk enable, disable and delete do what they say. Give --tenant for a tenant's own trunk.
• trunk srtp on encrypts the call audio to the carrier. It needs a TLS trunk.
• trunk status shows the registrations and whether each trunk answers.

sudo onyx trunk add exampletel --mode register --host sip.example.net --user 6125550100 --secret 'S3cret-from-carrier' --dial-format e164plus

The secret on the command line ends up in your shell history; the Trunks (carriers) page avoids that. See Trunks (carriers).

Phone numbers and outbound routes

onyx did list <tenant>
onyx did add <tenant> <did|*> <destination> [--trunk <name>] [--name ..] [--cid-prefix ..] [--record] [--priority 0-10]
onyx did delete <tenant> <id>
onyx route list <tenant>
onyx route add <tenant> <name> --pattern <prefix|prepend|match> [--pattern ..] --trunks <a,b> [--priority 100] [--callerid <number>] [--emergency]
onyx route delete <tenant> <name>

• did add sends an incoming number to a destination. The number may be written in any common form: +16125550100, 16125550100 and (612) 555-0100 are the same DID. * is a catch-all for every number on one trunk and needs --trunk. --cid-prefix goes in front of the caller's name, --record records every call to the number, and --priority (0 to 10) moves its callers ahead in a queue. did list shows each route's id; did delete takes that id.
• route add creates an outbound route. Each --pattern is either just a match, or prefix, prepend and match separated by |: the caller dials the prefix plus something that fits the match, the prefix is taken off and the prepend added. In the match, X is any digit, Z is 1-9, N is 2-9, [1-4] is a range, and a trailing . means one or more digits. --trunks lists the trunks to try in order. Routes with a lower --priority are tried first. --callerid overrides the caller ID on this route, and --emergency marks it as the route for emergency calls.

sudo onyx did add acme +16125550100 500 --name "Main number"
sudo onyx route add acme "US calls" --pattern "9|1|NXXNXXXXXX" --pattern "9||1NXXNXXXXXX" --trunks exampletel
sudo onyx route add acme Emergency --pattern 911 --trunks exampletel --emergency --priority 1

Put patterns in quotes: the shell treats | as a pipe. See Phone numbers and routes.

Contacts and directory sync

onyx contact add <tenant> <name> [--company ..] [--work ..] [--mobile ..] [--other ..] [--email ..]
onyx contact list <tenant> [--search ..]
onyx contact delete <tenant> <id>
onyx contact import <tenant> <file.csv> [--replace]
onyx directory add-ldap <tenant> --name .. --url ldap://host --base-dn dc=example,dc=com [--bind-dn ..] [--filter ..] [--every 60]
onyx directory add-m365 <tenant> --name .. --m365-tenant <guid> --client-id <guid> [--every 60]
onyx directory list <tenant>
onyx directory sync <tenant> [<id>]
onyx directory delete <tenant> <id>

• contact add, list and delete manage the tenant's phone book. contact import reads a CSV with the columns name, company, work, mobile, other and email; --replace replaces the contacts that were there.
• directory add-ldap adds an Active Directory or LDAP source and add-m365 a Microsoft 365 source. The bind password or client secret is read from the environment variable ONYX_DIRECTORY_SECRET, never from the command line. --every is the sync interval in minutes (default 60).
• directory list shows each source with its last sync and result. directory sync syncs now (all sources, or one by id) and exits with 1 when one fails. directory delete removes a source and the contacts it brought.

To pass the secret without it showing in the shell history:

read -rs ONYX_DIRECTORY_SECRET && export ONYX_DIRECTORY_SECRET
sudo --preserve-env=ONYX_DIRECTORY_SECRET onyx directory add-ldap acme --name "Office AD" --url ldaps://dc1.example.com --base-dn dc=example,dc=com --bind-dn "cn=onyx,cn=Users,dc=example,dc=com"

See Contacts and directory sync.

Import

onyx import plan <tenant> <file> [<file> ...]
onyx import apply <tenant> <file> [<file> ...]

• import plan reads the export of a FreePBX or 3CX system and prints what would be created, with notes. It writes nothing.
• import apply creates it. Numbers already in use in the tenant are left alone, and it exits with 1 when an item failed.
• Files: a FreePBX database dump (freepbx.sql) with voicemail.conf, FreePBX Bulk Handler CSVs, or a 3CX user export.

sudo onyx import plan acme freepbx.sql voicemail.conf

See Importing from FreePBX and 3CX.

Call history and recordings

onyx calls [<tenant>] [--limit 25]
onyx recordings <tenant> [--limit 25]
onyx recordings retention <tenant> [<days>]
onyx recordings purge

• calls shows the latest call records (all tenants, or one): start time in UTC, direction, from, to, DID, result and talk time.
• recordings lists the tenant's latest recorded calls with the path of each file on the server.
• recordings retention shows or sets how many days the tenant's recordings are kept. 0 keeps them until someone deletes them. Recordings on legal hold are never deleted.
• recordings purge deletes recordings past their retention period now, instead of waiting for the hourly clean-up.

sudo onyx recordings retention acme 90

See Call history and reports and Call recordings.

Security and call limits

onyx security bans
onyx security unban <address>
onyx toll show [<tenant>]
onyx toll set <tenant> [--international blocked|allowed|extensions] [--countries "44 49"] [--extensions "101 102"]
              [--premium on|off] [--max-calls <n>] [--per-hour <n>] [--daily-cap <amount>]
onyx toll block <tenant> [--reason ..]
onyx toll unblock <tenant>
onyx toll refused [<tenant>]

• security bans lists the addresses intrusion prevention has blocked, why, and until when.
• security unban lifts the block. The running service takes the address out of the firewall within a minute (Unblock on the Security page does it at once).
• toll show prints each tenant's call limits, its usage today, and whether its outside calls are stopped.
• toll set changes a tenant's limits. --international is blocked (nobody), extensions (only those in --extensions) or allowed (everybody); --countries limits international calls to these country codes. --premium on allows premium-rate numbers. --max-calls limits outside calls at once, --per-hour outside calls per hour, and --daily-cap the day's spending (0 = no cap). Crossing the hourly or daily limit stops the tenant's outside calls until someone lifts the stop.
• toll block stops a tenant's outside calls by hand, and toll unblock lifts a stop. Either takes effect within a minute. Emergency numbers always work.
• toll refused shows the latest 50 calls the limits refused.

sudo onyx toll set acme --international extensions --extensions "101 102" --countries "44 49" --daily-cap 50

See Security and Call limits (toll fraud).

Billing

onyx billing plans
onyx billing plan add <name> [--currency USD]
onyx billing plan delete <name>
onyx billing rates import <plan> <file.csv> [--replace]
onyx billing rates export <plan>
onyx billing tenant <tenant> [--plan <name>|none] [--fee-monthly ..] [--fee-per-extension ..] [--fee-per-did ..]
onyx billing bill [<yyyy-MM>]

• billing plans lists the rate plans with their currency, number of rates and the tenants on them. plan add and plan delete create and remove a plan.
• rates import loads a CSV with the columns prefix, description, per_minute, connect_fee, increment and minimum; --replace replaces the plan's rates. rates export prints the plan's rates as CSV.
• billing tenant puts a tenant on a plan (none takes it off) and sets its monthly fee and its fees per extension and per DID. Amounts use a dot as the decimal point.
• billing bill prints this month's bill for every tenant, or the month you give.

sudo onyx billing rates import "Standard" rates.csv --replace
sudo onyx billing bill 2026-09

See Billing.

Server settings and mail

onyx setting list
onyx setting set <key> <value>
onyx setting unset <key>
onyx mail test <address>

• setting list prints every server setting with its value, or (default) and the default. The mail password shows as (set).
• setting set checks and saves a value. The engine picks it up within a second.
• setting unset puts a setting back to its default.
• mail test sends a test message through the smtp.* settings, so you can check voicemail e-mail works.

sudo onyx setting set engine.external_address 203.0.113.10
sudo onyx mail test [email protected]

Every key is described in the Server settings reference.

Engine and database

onyx engine status
onyx engine render
onyx engine apply
onyx engine cli "<command>"
onyx migrate

• engine status prints the engine's version and uptime, the registered phones and the number of active calls.
• engine apply asks the service to rebuild the engine configuration and reload it now. You rarely need it: every change does this by itself.
• engine render writes the engine configuration files now, without a reload. Support may ask for it.
• engine cli runs one engine console command and prints the answer, for example onyx engine cli "pjsip show endpoints".
• migrate updates the database to the installed version. The package does this on every update; run it by hand only when support asks.

onyx sendmail also exists: the engine uses it to send voicemail e-mail through the smtp.* settings. You do not run it yourself.

Root tools

These come with the appliance and run as root.

onyx-os

onyx-os does the operating-system work behind the Server pages of the console: network, firewall, storage, updates, services, logs, backups and the cluster. The console calls it through a local socket; you can run the same operations from a root shell, which helps when the console cannot be reached.

sudo onyx-os <operation> ['<arguments as JSON>']

It prints the answer as JSON. sudo onyx-os help lists the operations:

Long operations (updates, backups, restores, disks, joining a cluster) run as jobs that survive a restart of the service. sudo onyx-os jobs lists them and sudo onyx-os job '{"job": "<id>"}' shows one.

sudo onyx-os overview
sudo onyx-os service.restart '{"unit": "onyx-voice.service"}'

See Server tools.

onyx-console, onyx-setup and onyx-ha

• onyx-console is the text menu on the server's own screen. It opens when an administrator signs in there; over SSH run sudo onyx-console. It has the network, storage, system, firewall, diagnostics and backup tools, and works even when the Onyx Voice service or the web console is down.
• onyx-setup is the first-boot setup: host name, network, public address behind NAT, time zone, the onyxadmin account, the firewall, the first console administrator and the first tenant, or joining an existing server as a cluster's second server. Run it again any time with sudo onyx-setup. See Installing the server.
• onyx-ha is the failover service of a two-server cluster. You use it by hand only for a planned switchover (sudo onyx-ha --switchover), to take over when the active server and the witness are both gone (sudo onyx-ha --takeover), or to let a database start once without the witness (sudo onyx-ha --allow-start). See High availability.