Onyx VoiceDocumentation
All chapters

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:

  1. Open Server settings.
  2. Type the new value in the setting's field. An empty field shows the default in grey.
  3. 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

KeyConsole labelWhat it doesDefaultAllowed values
engine.hostnameServer nameThe 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 namea host name, e.g. pbx.example.com
engine.external_addressPublic addressThe 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_netsLocal networksNetworks 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/16networks in CIDR form, comma separated
engine.sip_portSIP portPort for SIP over UDP and TCP.50601-65535
engine.sip_tls_portSIP TLS portPort for SIP over TLS (encrypted calls).50611-65535
engine.rtp_startAudio ports fromFirst UDP port for call audio (RTP).100001-65535
engine.rtp_endAudio ports toLast UDP port for call audio.200001-65535
engine.codecsPhone codecsCodecs offered to phones and softphones, in order of preference.g722,ulaw,alawcomma separated from g722, ulaw, alaw, gsm, g726, speex, opus, h264, vp8
engine.tone_zoneCountry tonesThe 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).usus, ca, uk, au, de, fr, nl
engine.stun_serverOutside STUN serverA 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_serviceSTUN service on this serverWhether 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.onon, off
engine.tls_cert_fileCertificate fileYour 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.emptyan absolute path
engine.tls_key_fileCertificate key fileThe private key (PEM) for engine.tls_cert_file.emptyan absolute path
engine.device_qualifyPhone keepalive (seconds)How often the engine checks that each registered phone is still there. The check also keeps NAT routers from forgetting remote phones.600 (never) or 10-3600

Notes:

  • If you change engine.sip_port, engine.sip_tls_port or 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.

KeyConsole labelWhat it doesDefaultAllowed values
smtp.providerSend withHow 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.smtpsmtp, microsoft365, gmail, google_workspace
smtp.m365_tenantDirectory (tenant) IDMicrosoft 365 only. From the app registration's Overview.emptya GUID, or a domain of the tenant such as contoso.onmicrosoft.com
smtp.m365_client_idApplication (client) IDMicrosoft 365 only. From the app registration's Overview (not the Object ID under it).emptya GUID
smtp.m365_client_secretClient secretMicrosoft 365 only. The secret's Value (not its Secret ID). Never shown back.emptyany text
smtp.google_keyService account keyGoogle 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.emptya Google service account JSON key
smtp.hostMail serverThe SMTP server that sends the mail. Nothing is sent while it is empty.emptya host name or IP address
smtp.portPortThe server's port.587, or 465 when smtp.security is tls1-65535
smtp.securityEncryptionstarttls connects in plain and upgrades to TLS (ports 587 and 25); tls uses TLS from the start (port 465); none sends unencrypted.starttlsnone, starttls, tls
smtp.usernameUsernameThe sign-in name, when the server wants one.empty (no sign-in)any text
smtp.passwordPasswordThe 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.emptyany text
voicemail.transcriptionVoicemail transcriptson 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.onon, off
voicemail.attachment_formatVoicemail attachmentThe recording's format in voicemail e-mail. mp3 is small and plays everywhere; wav is the engine's own recording, about four times larger.mp3mp3, wav
smtp.fromMail senderThe 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 senderan 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:

  1. Microsoft Entra admin center > App registrations > New registration: name it "Onyx Voice", accounts in this organizational directory only, no redirect URI.
  2. 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).
  3. API permissions > Add a permission > Microsoft Graph > Application permissions > Mail.Send, then Grant admin consent.
  4. 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.
  5. 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:

  1. Google Cloud console: in a project for Onyx Voice, APIs & Services > Library > Gmail API > Enable.
  2. 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.
  3. 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.
  4. 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.

KeyConsole labelWhat it doesDefaultAllowed values
tts.voiceDefault voiceThe voice the forms start with.kokoro:af_heartkokoro:<voice> on this server, or openai:, elevenlabs:, azure: + a voice of that service
tts.cloudCloud voice serviceThe cloud service offered next to this server's voices. The text of each prompt made in one of its voices is sent to it.offoff, openai, elevenlabs, azure
tts.cloud_keyCloud voice API keyThe service's API key (Azure: the Speech resource's key). It is never shown, like the mail password.emptyany text
tts.cloud_regionAzure regionAzure only: the Speech resource's region.emptye.g. eastus, westeurope
tts.cloud_voicesCloud voices offeredThe 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.emptyvoice 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.

FieldWhat to enter
Language modelOff (transcripts only), OpenAI or any OpenAI-compatible service, Anthropic (Claude) or Ollama (a server you run).
ModelThe provider's model name, for example a GPT model for OpenAI, a Claude model for Anthropic or gemma4:26b for Ollama.
AddressEmpty 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 keyThe key from the provider's console. Ollama usually needs none. It is never shown again.
Speech-to-textThis 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 modelOnly 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

KeyConsole labelWhat it doesDefaultAllowed values
provisioning.allowed_netsPhones may fetch settings fromThe 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_netsnetworks in CIDR form, comma separated; any; or empty
provisioning.ntp_serverTime server for phonesThe time server written into the phones' settings.pool.ntp.orga host name, or empty for the default
provisioning.pnpPlug-and-playWhether the server answers new phones that announce themselves on the local network (Yealink, Grandstream, Fanvil, Snom, Htek).onon, off
provisioning.pnp_tenantTenant for new plug-and-play phonesThe 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.emptya tenant code, or empty
provisioning.dhcp_overrideDHCP may move set-up phonesWhether 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.offon, 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.

KeyConsole labelWhat it doesDefaultAllowed values
security.ban_afterFailed sign-insHow many failed sign-ins (phones, softphones or the console) from one address block it.100 (never block) or 3-1000
security.ban_windowWithin (minutes)The time the failures must fall within.101-1440
security.ban_minutesBlock for (minutes)How long a block lasts.600 (until an administrator lifts it) up to 525600
security.never_banNever blockAddresses 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).emptyaddresses or CIDR networks, comma separated
security.floodProtect against floodsLimits per sending address against floods (denial of service); see Flood protection.onon, off
security.flood_sip_rateSIP packets a secondOver this from one address, the address is blocked.5010-100000
security.flood_conn_rateNew connections a secondNew connections to the web server and SIP over TCP or TLS; over this, the address is blocked.205-10000
security.flood_max_connsConnections at onceMore are refused, never blocked.20010-100000
security.flood_web_rateWeb requests a minuteOver this, requests are refused; at twice this, the address is blocked.120060-1000000
security.flood_ban_minutesBlock flooders for (minutes)How long a flood block lasts.151-10080
security.require_2faRequire it for administratorsWith 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.offoff, 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

KeyConsole labelWhat it doesDefaultAllowed values
security.alert_emailSend 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

See Call limits (toll fraud).

Let's Encrypt

These are set together in the Certificate card of the Security page, not one by one.

KeyConsole fieldWhat it doesDefaultAllowed values
tls.acmeGet a certificate for <server name> from Let's Encrypt and renew it automaticallyTurns 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.offon, off
tls.acme_emailContact e-mailThe address the certificate authority writes to about expiry problems. The console will not turn Let's Encrypt on without it.emptyan e-mail address
tls.acme_extra_namesAlso valid forMore 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.emptyhost names, comma separated
tls.acme_serverACME 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 Encryptan https:// directory URL
tls.acme_ca_fileTest server's CA file (same place)The certificate authority file of a test ACME server, trusted only for talking to that server.emptyan 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.