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), Voicemail e-mail (smtp.*) 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 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_addresssetting 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 | 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. | empty (none) | host or host:port |
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).
Voicemail e-mail
Onyx Voice sends voicemail to e-mail, call limit alerts and test messages through an SMTP server you choose.
| Key | Console label | What it does | Default | Allowed values |
|---|---|---|---|---|
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 | Mail port | The server's port. | 587, or 465 when smtp.security is tls | 1-65535 |
smtp.security | Mail encryption | starttls connects in plain and upgrades to TLS; tls uses TLS from the start; none sends unencrypted. | starttls | none, starttls, tls |
smtp.username | Mail username | The sign-in name, when the server wants one. | empty (no sign-in) | any text |
smtp.password | Mail password | The password. It is never shown: the console says "Set (type to replace)" and onyx setting list shows (set). | empty | any text |
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 message's own sender) | an e-mail address |
To check the settings, run sudo onyx mail test [email protected]. It prints sent, or the mail server's error.
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 |
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.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. | 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.