Docs / Reference
Server settings reference
Server settings apply to the whole server and every tenant on it: the ports and network addresses of the phone engine, outgoing mail, desk phone provisioning, intrusion prevention, two-factor sign-in and Let's Encrypt. This chapter lists every setting with what it does, its default and the values it accepts, and where to change it.
Where to change them
Most settings are on the Server settings page of the console (system administrators only). The page has three groups: Calls and network (the engine.* keys), E-mail (SMTP) (smtp.* and voicemail.*) and Desk phone provisioning (provisioning.*). To change one:
- Open Server settings.
- Type the new value in the setting's field. An empty field shows the default in grey.
- Press Save next to it (or Enter). A wrong value is refused with a message saying what it must be.
The other settings have their own place in the console:
security.*(except the alert address): the Security page, cards When to block, Flood protection and Two-factor sign-in.security.alert_email: the Call limits page, card Alerts.tls.*: the Security page, card Certificate.
From a shell, every setting works the same way with onyx:
sudo onyx setting list
sudo onyx setting set engine.external_address 203.0.113.10
sudo onyx setting unset engine.external_address
setting list shows each key with its value, or (default) and the default. setting set checks the value and saves it. setting unset removes the setting so the default applies again; the console has no button for that. Values are trimmed of spaces at both ends. See Command line (onyx).
Changes reach the engine within a second. A few need the engine to restart: the SIP TLS port, the certificate files, and turning a STUN server on or off. The engine restarts by itself once no calls are up, so calls in progress are not cut. Every change is recorded in Change history.
The first-boot setup (onyx-setup) writes two of these settings for you: engine.hostname (the server's name) and engine.external_address (the public address, when you said the server sits behind NAT).
Calls and network
| Key | Console label | What it does | Default | Allowed values |
|---|---|---|---|---|
engine.hostname | Server name | The name phones, softphones and browsers use to reach the server. Desk phone provisioning, the certificate and Let's Encrypt use it. | this machine's host name | a host name, e.g. pbx.example.com |
engine.external_address | Public address | The router's public address, announced in calls when the server is behind NAT and phones or carriers reach it from the internet. Without it, outside calls through NAT have one-way or no audio. | empty (no NAT) | an IP address or host name, or empty |
engine.local_nets | Local networks | Networks the server reaches without NAT. Calls to addresses in these networks use the server's own address; everything else gets the public address. Also the default for who may fetch phone settings. | 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 | networks in CIDR form, comma separated |
engine.sip_port | SIP port | Port for SIP over UDP and TCP. | 5060 | 1-65535 |
engine.sip_tls_port | SIP TLS port | Port for SIP over TLS (encrypted calls). | 5061 | 1-65535 |
engine.rtp_start | Audio ports from | First UDP port for call audio (RTP). | 10000 | 1-65535 |
engine.rtp_end | Audio ports to | Last UDP port for call audio. | 20000 | 1-65535 |
engine.codecs | Phone codecs | Codecs offered to phones and softphones, in order of preference. | g722,ulaw,alaw | comma separated from g722, ulaw, alaw, gsm, g726, speex, opus, h264, vp8 |
engine.tone_zone | Country tones | The dial, ringing and busy tones callers hear. us and ca also make 10-digit numbers count as North American (a leading 1 is added to DIDs and caller lookups). | us | us, ca, uk, au, de, fr, nl |
engine.stun_server | Outside STUN server | A STUN server the engine asks for its public address. Only for servers behind NAT whose public address changes; a fixed engine.external_address is better. When set, the browser softphone uses it too. | empty (none) | host or host:port |
engine.stun_service | STUN service on this server | Whether the server answers STUN requests on port 3478 (UDP and TCP), so the browser softphone, the apps and phones learn their public address from it instead of an outside service. Each address gets at most 20 answers in 10 seconds. | on | on, off |
engine.tls_cert_file | Certificate file | Your own certificate (PEM), used for SIP TLS and the console and portal. Leave empty to use Let's Encrypt or the server's self-signed certificate. | empty | an absolute path |
engine.tls_key_file | Certificate key file | The private key (PEM) for engine.tls_cert_file. | empty | an absolute path |
engine.device_qualify | Phone keepalive (seconds) | How often the engine checks that each registered phone is still there. The check also keeps NAT routers from forgetting remote phones. | 60 | 0 (never) or 10-3600 |
Notes:
- If you change
engine.sip_port,engine.sip_tls_portor the audio port range, change the firewall and any port forwards on the router to match. See Network, NAT and firewall. - The certificate files are used only when both files exist. See Names and certificates.
- Codecs that a trunk uses are set on the trunk, not here. See Trunks (carriers).
E-mail (SMTP)
Onyx Voice sends voicemail to e-mail, missed-call e-mail, call reports, faxes, call limit and health alerts and test messages through an SMTP server you choose, or through Microsoft 365, Gmail or Google Workspace. Send with at the top of the form picks which; the boxes below it change to match.
| Key | Console label | What it does | Default | Allowed values |
|---|---|---|---|---|
smtp.provider | Send with | How mail leaves: smtp = the mail server below; microsoft365 = Microsoft 365 through Microsoft Graph; gmail = Gmail with an app password (smtp.gmail.com, port 587, STARTTLS: the server, port and encryption boxes are not used); google_workspace = the Gmail API with a service account. | smtp | smtp, microsoft365, gmail, google_workspace |
smtp.m365_tenant | Directory (tenant) ID | Microsoft 365 only. From the app registration's Overview. | empty | a GUID, or a domain of the tenant such as contoso.onmicrosoft.com |
smtp.m365_client_id | Application (client) ID | Microsoft 365 only. From the app registration's Overview (not the Object ID under it). | empty | a GUID |
smtp.m365_client_secret | Client secret | Microsoft 365 only. The secret's Value (not its Secret ID). Never shown back. | empty | any text |
smtp.google_key | Service account key | Google Workspace only. The service account's JSON key file; the console shows only which service account it belongs to. From a shell: sudo onyx setting set smtp.google_key --file key.json. | empty | a Google service account JSON key |
smtp.host | Mail server | The SMTP server that sends the mail. Nothing is sent while it is empty. | empty | a host name or IP address |
smtp.port | Port | The server's port. | 587, or 465 when smtp.security is tls | 1-65535 |
smtp.security | Encryption | starttls connects in plain and upgrades to TLS (ports 587 and 25); tls uses TLS from the start (port 465); none sends unencrypted. | starttls | none, starttls, tls |
smtp.username | Username | The sign-in name, when the server wants one. | empty (no sign-in) | any text |
smtp.password | Password | The password. It is never shown: the console says "Set (type to replace)" and onyx setting list shows (set). Left empty in the form, the saved one stays. | empty | any text |
voicemail.transcription | Voicemail transcripts | on writes out each voicemail and puts the text in the e-mail and the portal. Speech recognition runs on this server (English). Each extension can turn its own off. | on | on, off |
voicemail.attachment_format | Voicemail attachment | The recording's format in voicemail e-mail. mp3 is small and plays everywhere; wav is the engine's own recording, about four times larger. | mp3 | mp3, wav |
smtp.from | Mail sender | The From address of every message. The display name stays (for example the caller's name on a voicemail). Use an address your mail server is allowed to send as, or SPF and DMARC checks may reject the mail. | empty: the username when it is an e-mail address, else the message's own sender | an e-mail address |
The smtp.* settings are one form on Server settings with one Save; emptying a field puts the setting back to its default. To check them, type an address under Send a test to and click Send test e-mail: it saves the form first, then sends. The console says where it went, or why not in one sentence (the wrong encryption for the port, no STARTTLS, a refused username or password, a refused sender with the hint to set Mail sender, or the mail server's own answer). From a shell, sudo onyx mail test [email protected] does the same.
For Gmail, smtp.username is the Gmail address and smtp.password an app password. For Microsoft 365 and Google Workspace, Send as (mailbox) (smtp.from) is the mailbox the messages come from and must be filled in.
Microsoft 365
Exchange Online no longer accepts a username and password over SMTP, so Onyx Voice sends through Microsoft Graph with an app registration. As a Microsoft 365 administrator:
- Microsoft Entra admin center > App registrations > New registration: name it "Onyx Voice", accounts in this organizational directory only, no redirect URI.
- Copy the Application (client) ID and Directory (tenant) ID from its Overview into the form (the Object ID there is a different GUID, not needed).
- API permissions > Add a permission > Microsoft Graph > Application permissions > Mail.Send, then Grant admin consent.
- Certificates & secrets > New client secret. Copy its Value (shown only once) into Client secret. Make a new secret before the expiry date shown there; mail stops when it runs out.
- Send as (mailbox): a user or shared mailbox in the tenant, for example
[email protected].
Recommended: limit the app to that one mailbox (Exchange Online RBAC for Applications, or an application access policy). Without a limit, Mail.Send lets the app send as any mailbox in the tenant.
A message up to about 3 MB goes in one call. A bigger one (a long voicemail with a WAV attachment, a fax of many pages) is made as a draft, its attachments uploaded in pieces, and then sent; that also needs the application permission Mail.ReadWrite. Without it the console says so. Setting Voicemail attachment to mp3 keeps voicemail well under the limit.
Gmail
For a single Gmail account: turn on 2-Step Verification on the account, make an app password at myaccount.google.com/apppasswords, and enter the Gmail address and the 16-letter app password. Gmail sends as the account itself; another From address works only after it is added in Gmail under Settings > Accounts > Send mail as. Gmail limits a personal account to about 500 messages a day.
Google Workspace
For a Workspace domain, without any user's password. As a Workspace super administrator:
- Google Cloud console: in a project for Onyx Voice, APIs & Services > Library > Gmail API > Enable.
- IAM & Admin > Service accounts > Create service account (no roles needed). On it, Keys > Add key > JSON, and choose the downloaded file under Service account key.
- Copy the service account's Unique ID (its client ID). Google Admin console > Security > Access and data control > API controls > Manage Domain-wide delegation > Add new: that client ID and the scope
https://www.googleapis.com/auth/gmail.send. - Send as (mailbox): a Workspace user with Gmail, for example
[email protected](not a group). Delegation can take a few minutes to start working.
Keep the key file safe, or delete it after choosing it: anyone holding it can send mail as the users the delegation allows.
Voices (greetings from text)
Prompts and greetings can be made from text (Making a prompt from text). Voices on this server need the onyx-voice-speech package and no settings; a cloud voice service is optional.
| Key | Console label | What it does | Default | Allowed values |
|---|---|---|---|---|
tts.voice | Default voice | The voice the forms start with. | kokoro:af_heart | kokoro:<voice> on this server, or openai:, elevenlabs:, azure: + a voice of that service |
tts.cloud | Cloud voice service | The cloud service offered next to this server's voices. The text of each prompt made in one of its voices is sent to it. | off | off, openai, elevenlabs, azure |
tts.cloud_key | Cloud voice API key | The service's API key (Azure: the Speech resource's key). It is never shown, like the mail password. | empty | any text |
tts.cloud_region | Azure region | Azure only: the Speech resource's region. | empty | e.g. eastus, westeurope |
tts.cloud_voices | Cloud voices offered | The service's voices to offer, comma separated. Empty offers OpenAI's and Azure's usual English voices; ElevenLabs needs the voice ids from your ElevenLabs account. | empty | voice ids |
To check the voice on this server, run sudo onyx tts test: it speaks a sentence and reads it back with speech-to-text. sudo onyx tts voices lists every voice on offer.
AI (call insights)
The language model and speech-to-text for call insights (see Call insights). Nothing is sent anywhere until a tenant has call insights switched on under Tenants.
| Field | What to enter |
|---|---|
| Language model | Off (transcripts only), OpenAI or any OpenAI-compatible service, Anthropic (Claude) or Ollama (a server you run). |
| Model | The provider's model name, for example a GPT model for OpenAI, a Claude model for Anthropic or gemma4:26b for Ollama. |
| Address | Empty for OpenAI and Anthropic. For another OpenAI-compatible service (Azure OpenAI, xAI Grok, a vLLM or LM Studio server) its address ending in /v1; for Ollama the server and port, for example http://10.0.0.30:11434. |
| API key | The key from the provider's console. Ollama usually needs none. It is never shown again. |
| Speech-to-text | This server (Whisper, free; the audio never leaves the server) or The AI service (an OpenAI-compatible service's speech-to-text, faster on a small server). |
| Speech-to-text model | Only for the AI service: empty for whisper-1. |
Click Save and test: the settings are saved and a short made-up call is sent to the model; its summary and score come back, or the provider's reason for refusing. With Ollama, pick a model that is already loaded there: loading another one can take a minute and slows down other users of that server.
The same settings from the command line: onyx setting set ai.provider anthropic, ai.model, ai.endpoint, ai.key, ai.transcriber (server or provider) and ai.stt_model.
Desk phone provisioning
| Key | Console label | What it does | Default | Allowed values |
|---|---|---|---|---|
provisioning.allowed_nets | Phones may fetch settings from | The networks desk phones may download their settings from. Requests from other addresses are refused. any allows the internet, for remote phones. | empty = the networks in engine.local_nets | networks in CIDR form, comma separated; any; or empty |
provisioning.ntp_server | Time server for phones | The time server written into the phones' settings. | pool.ntp.org | a host name, or empty for the default |
provisioning.pnp | Plug-and-play | Whether the server answers new phones that announce themselves on the local network (Yealink, Grandstream, Fanvil, Snom, Htek). | on | on, off |
provisioning.pnp_tenant | Tenant for new plug-and-play phones | The tenant whose phone list a new phone joins when its MAC address is not assigned anywhere yet. Empty means the only tenant, when there is just one; with several tenants and no value, unknown phones are not answered. | empty | a tenant code, or empty |
provisioning.dhcp_override | DHCP may move set-up phones | Whether a phone Onyx has set up still lets DHCP option 66 replace its provisioning address at every start (Grandstream). Off keeps it on its own tenant's address, also on a network whose option 66 points at another tenant. | off | on, off |
Plug-and-play answers only phones in the networks of provisioning.allowed_nets. See Desk phones.
Intrusion prevention and two-factor sign-in
These are on the Security page. The labels below are that page's.
| Key | Console label | What it does | Default | Allowed values |
|---|---|---|---|---|
security.ban_after | Failed sign-ins | How many failed sign-ins (phones, softphones or the console) from one address block it. | 10 | 0 (never block) or 3-1000 |
security.ban_window | Within (minutes) | The time the failures must fall within. | 10 | 1-1440 |
security.ban_minutes | Block for (minutes) | How long a block lasts. | 60 | 0 (until an administrator lifts it) up to 525600 |
security.never_ban | Never block | Addresses and networks that are never blocked: your offices, admin addresses and the server's own addresses (only 127.0.0.1 is exempt by itself). | empty | addresses or CIDR networks, comma separated |
security.flood | Protect against floods | Limits per sending address against floods (denial of service); see Flood protection. | on | on, off |
security.flood_sip_rate | SIP packets a second | Over this from one address, the address is blocked. | 50 | 10-100000 |
security.flood_conn_rate | New connections a second | New connections to the web server and SIP over TCP or TLS; over this, the address is blocked. | 20 | 5-10000 |
security.flood_max_conns | Connections at once | More are refused, never blocked. | 200 | 10-100000 |
security.flood_web_rate | Web requests a minute | Over this, requests are refused; at twice this, the address is blocked. | 1200 | 60-1000000 |
security.flood_ban_minutes | Block flooders for (minutes) | How long a flood block lasts. | 15 | 1-10080 |
security.require_2fa | Require it for administrators | With admins, every administrator must sign in with an authenticator code as well as the password; those who have not set it up are asked to at their next sign-in. | off | off, admins |
The intrusion prevention settings are read again every 30 seconds. The two-factor requirement takes effect within half a minute. See Security.
Call limit alerts
| Key | Console label | What it does | Default | Allowed values |
|---|---|---|---|---|
security.alert_email | Send alerts to (Call limits page) | Who gets an e-mail when a call limit stops a tenant's outside calls. Sent through the smtp.* settings. | empty (no alerts) | e-mail addresses, comma separated |
Let's Encrypt
These are set together in the Certificate card of the Security page, not one by one.
| Key | Console field | What it does | Default | Allowed values |
|---|---|---|---|---|
tls.acme | Get a certificate for <server name> from Let's Encrypt and renew it automatically | Turns Let's Encrypt on. The server's name (engine.hostname) must be a public DNS name pointing at the server, with port 80 open to the internet. | off | on, off |
tls.acme_email | Contact e-mail | The address the certificate authority writes to about expiry problems. The console will not turn Let's Encrypt on without it. | empty | an e-mail address |
tls.acme_extra_names | Also valid for | More names on the same certificate, for example an old name kept while phones move to the new one. Each needs a DNS record pointing at the server. When the host name is a private one (pbx.example.local), the certificate is for these names only. | empty | host names, comma separated |
tls.acme_server | ACME directory (under Test server (staging, Pebble)) | Another ACME server instead of Let's Encrypt, such as Let's Encrypt's staging server for tests. | empty = Let's Encrypt | an https:// directory URL |
tls.acme_ca_file | Test server's CA file (same place) | The certificate authority file of a test ACME server, trusted only for talking to that server. | empty | an absolute path |
When you turn Let's Encrypt on in the console you must also tick I accept the Let's Encrypt subscriber agreement. Setting tls.acme to on with onyx setting set skips that check box, so read the agreement first. See Names and certificates.
Settings you cannot change
The server also keeps the passwords the control plane uses to talk to the engine. They are made on the first start, are not listed by onyx setting list, and onyx setting set refuses them.