Onyx VoiceDocumentation
All chapters

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). --call-centre on|off switches the call centre add-on (queues, agents, wallboard); off is refused while the tenant has queues.
  • 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]
                               [--vm-email attach|notify|off] [--vm-transcribe on|off] [--vm-delete on|off]
onyx hours <tenant> <number> [--follow <business hours> --closed <dest> [--holiday <dest>] [--break <dest>] | --off]
onyx ext set <tenant> <number> ... [--record always|external|never] [--record-ondemand on|off]
onyx ext calls <tenant> <number> [--dnd on|off] [--always <number>] [--busy <number>] [--noanswer <number>]
onyx ext status <tenant> <number> [available|away|dnd|lunch|trip] [--mobile <number>] [--follow <time condition>] [--closed away|lunch|trip]
onyx ext profile <tenant> <number> <status> [--ring <seconds>] [--noanswer-int <n>] [--noanswer-ext <n>] [--busy-int <n>] [--busy-ext <n>] [--mobile-too on|off] [--clear]
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. --vm-email attach|notify|off sets what new voicemail e-mails (the recording attached, a notice only, nothing), --vm-transcribe on|off the transcript in it, and --vm-delete on removes a message from the mailbox once it has been e-mailed with its recording.
  • ext status shows a status profile (the status now and each status's targets) or sets the status; --mobile, --follow <business hours number> and --closed set the mobile number and the office hours it follows. ext profile sets where calls go in one status, for example onyx ext profile acme 101 away --noanswer-ext 6125550199 --mobile-too on; --clear empties it. See Status profiles.
  • 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>
onyx user app-setup <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).
  • user app-setup prints a one-time setup code for the Onyx Softphone, with the server and the setup link: the app connects with it instead of the password (see softphones). The account needs an extension. The code works once, for 7 days.
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 set <tenant> <id> [--did ..] [--to <destination>] [--trunk <name>|any] [--name ..] [--cid-prefix ..] [--record on|off] [--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 set and did delete take that id. did set changes only the options given, for example --to 801 to send the number elsewhere or --trunk any to accept it on every trunk.
  • 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

A whole 3CX system, one tenant per 3CX department:

onyx import 3cx plan <backup>
onyx import 3cx apply <backup> [--codes "Department=code,..."] [--only code,...] [--no-voicemail]
  • <backup> is the 3CX backup .zip, the folder it was unpacked to, or its …Db.xml.
  • import 3cx plan prints the trunks, then each department's tenant and what it would get. It writes nothing.
  • import 3cx apply creates the tenants, trunks, outbound routes, numbers and voicemail. What already exists is left alone, and it exits with 1 when an item failed.
  • --codes gives departments other tenant codes than the suggested ones; --only imports some of them; --no-voicemail leaves the messages out.
sudo onyx import 3cx apply 3CXScheduledBackup.zip --codes "Networks Cinema and Sound=ncs"

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.
  • speech test <audio file> transcribes a recording the way voicemail transcripts are made and prints the model, the time it took and the text. Use it to check transcripts work, or how fast they are on your server.
  • tts voices lists the voices prompts can be made in: this server's and the cloud service's.
  • tts say <tenant> <prompt name> [--voice <id>] [--speed 0.7-1.3] [--pause <seconds>] [--replace] [--text ..] makes a prompt from text (the text from --text or standard input); --replace makes an existing prompt again with new words. --speed is the pace (1 = the voice's own) and --pause the silence after each comma, semicolon or colon (0 to 1.5 seconds; 0 = the voice's own short pause).
  • tts test [--voice <id>] [--speed ..] [--pause ..] speaks a sentence on this server and reads it back with speech-to-text: a quick check that greetings from text work.
sudo onyx setting set engine.external_address 203.0.113.10
sudo onyx mail test [email protected]
sudo onyx speech test /tmp/message.wav
sudo onyx tts test
echo "Our office is closed today." | sudo onyx tts say acme "Closed today" --voice kokoro:bf_emma

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 hands it each voicemail e-mail, and it adds the transcript, converts the recording, applies the extension's e-mail options and sends it through the smtp.* settings. You do not run it yourself. Its log lines (one per voicemail, with the transcript time) are in the engine's journal: journalctl -u onyx-voice-engine | grep sendmail.

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:

AreaOperations
System & updatesoverview, services, service.restart, hostname.set, timezones, timezone.set, ntp.set, ssh.set, power, updates, updates.check, updates.install, updates.source
Networknetwork, network.apply, network.confirm, network.rollback, network.test, firewall, firewall.set, firewall.add, firewall.remove, firewall.defaults
Storagestorage, storage.grow, storage.adddisk, cleanup
Logs & diagnosticslogs.sources, logs, support.bundle, support.list, support.delete
Backupbackup.config, backup.configure, backup.test, backup.list, backup.run, backup.restore, backup.delete
Clustercluster, cluster.create, cluster.token, cluster.join, cluster.syncmode, cluster.recopy, cluster.refresh, ha, ha.switchover, witness.setup
Long operationsjobs, job

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.