Docs / Phone system

Trunks (carriers)

A trunk connects the phone system to a SIP carrier for outside calls. Incoming numbers arrive on a trunk; outbound routes choose which trunk carries a call. Without a trunk, only calls between extensions work. This chapter covers adding a trunk from a carrier template or by hand, registration and IP authentication, number formats, caller ID headers, encryption, failover and checking that a trunk works. Which numbers ring where, and which calls go out, is in Phone numbers and routes.

Before you add a trunk, make sure the server can be reached from the internet if the carrier needs to send calls to it: a public address, forwarded ports and the server's Public address setting. See Network, NAT and firewall.

Shared and tenant trunks

A trunk is either shared by all tenants or belongs to one tenant.

• Shared by all tenants: every tenant's outbound routes may use it, and phone numbers of every tenant can arrive on it. This is the usual setup for a hosted server with one carrier account. Only system administrators create and change shared trunks.
• Only one tenant: only that tenant's routes and numbers use it. A tenant administrator can add trunks for their own tenant; they see shared trunks in the list but cannot change them.

A system administrator chooses this under Used by when adding the trunk; it cannot be changed afterwards.

Adding a trunk

1. Open Trunks (carriers) and click Add a trunk.
2. Under Carrier, pick your carrier if it is listed. Its documented settings fill the form and a box shows what is known about it (below). Otherwise keep Another carrier (enter the details yourself).
3. Check the Name, for example ExampleTel. It is how routes and phone numbers refer to the trunk.
4. Choose How the carrier knows us: Registration (username + password) or IP address (carrier knows our address).
5. Enter the Carrier server, Port and Transport your carrier gives you.
6. For registration, enter the Username and Password, and the Auth username if the carrier gives a separate one.
7. Check the number and caller ID settings (the sections below explain each).
8. Click Add trunk. The trunk appears in the list and the engine starts using it within a second.

The form's fields:

Trunk usernames, passwords, From user and From domain cannot contain spaces, semicolons or line breaks.

Carrier templates

Onyx Voice includes 17 carrier templates from the US carriers that 3CX lists: 6 under Supported carriers (for example Callcentric, Twilio Elastic SIP Trunking, Voxtelesys) and 11 under Tested carriers (for example Bandwidth, Flowroute, Skyetel, Telnyx, VoIP.ms). Each was researched from the carrier's own documentation.

Picking a template fills in what the carrier documents: authentication, server, port and transport, the addresses it sends calls from, where it puts the dialled number, codecs, number formats, caller ID header and From domain. Picking another carrier on an existing trunk fills the form again with that carrier's values.

The box under Carrier shows:

• links to the carrier's website and sign-up page, and the authentication methods it offers;
• a button per server when the carrier has several (by region); click one to use it;
• the carrier's own notes, for example what to set in its portal;
• a warning when the carrier does not publish its settings; ask the carrier for the server, authentication and number format and enter them yourself.

Some carriers give each customer their own server name. The template then shows a part in braces, such as {account}.sip.example.net; replace it with the value from your carrier account. A trunk with braces left in the server name is not saved.

onyx trunk providers lists the templates on the command line, and onyx trunk providers <id> shows one with its notes.

Registration or IP authentication

Registration (username + password) is the usual choice for business SIP accounts. Onyx Voice registers with the carrier using the username and password and renews the registration every hour. If the carrier does not answer it tries again every minute; if the carrier refuses the password it waits 10 minutes between tries.

IP address (carrier knows our address) is for carriers that recognise you by your public address. Give the carrier your server's public address. Username and password are optional and only answer the carrier's challenges on outgoing calls, if it sends any.

Either way, incoming calls are matched to the trunk by the address they come from: the Carrier server always, and every address in Other carrier addresses (IP addresses or networks, comma separated, for example 203.0.113.0/24, 198.51.100.7). Templates fill in the addresses the carrier publishes. For IP authentication this list must be complete, or calls from an unlisted address are rejected.

Put your carriers' addresses in Never block on Security (system administrators), so that failed attempts from a carrier's address can never get it blocked by the intrusion prevention. See Security.

Server, port and transport

• UDP on port 5060 is what most carriers expect.
• TCP for carriers that require it or for large messages.
• TLS encrypts the signalling, usually on port 5061. The engine connects with TLS 1.2. It does not check the carrier's certificate, so TLS protects the call setup from eavesdropping but does not prove the carrier's identity. TLS is also needed for encrypted audio (below).

Incoming numbers

Phone number is in says where the carrier puts the number that was called:

• Automatic: the To header for registration trunks, the request URI for IP trunks. Right for most carriers.
• Request URI or To header: when the carrier's documentation says so, or when incoming calls are refused as unrouted although the number is routed.

Onyx Voice keeps only the digits of that number, and when the server's Country tones setting is us or ca it adds the leading 1 to 10-digit numbers. Then it looks the number up as described in Incoming calls.

Number formats

Carriers differ in how they want numbers written. Send numbers as applies to the number dialled; Send caller ID as to your caller ID number.

A number counts as international when it starts with 011, or with + and a country code other than 1. A 10-digit number is treated as North American and gets its 1. Short numbers such as 911 or 411, and anything else that does not fit, are sent as dialled.

Dial prefix is put in front of every dialled number after formatting. Some carriers use it to pick an account or a rate (a tech prefix); leave it empty unless yours asks for one. Up to 20 characters: digits, *, # and +.

Caller ID header

Caller ID header says where the carrier reads your caller ID:

• P-Asserted-Identity (default): the common choice.
• Remote-Party-ID: for carriers that ask for it.
• From header only: the caller ID goes only in the From header.

If you set a From user, the From header always carries that value instead of the caller ID, so use P-Asserted-Identity or Remote-Party-ID with it. From domain replaces the server name in the From header and in the registration, for carriers that require their own domain there.

Which number is sent as caller ID is decided per call; see Caller ID.

Codecs

The default ulaw,alaw,g722 suits nearly every carrier. List the codecs your carrier supports, separated by commas, in order of preference. A name the engine does not know is refused with the list of allowed names. The codecs phones use are a server setting, Phone codecs (see Server settings reference); the engine converts between them when needed.

Call limit and the minute check

Maximum simultaneous calls counts calls in both directions on this trunk. An incoming call over the limit is refused; an outgoing call over the limit moves on to the next trunk of its route. Set it to what your carrier account allows, so calls fail over instead of being rejected by the carrier.

Check every minute that the carrier answers (skip the trunk while it does not) sends an OPTIONS request every 60 seconds. While the carrier does not answer, the trunk is shown as Not answering and routes move on to their next trunk. Turn it off for carriers that do not answer OPTIONS; otherwise such a trunk would always look down.

Encrypted audio (SRTP)

On a TLS trunk the list shows Encrypt audio. Click it to encrypt the call audio to the carrier (SRTP, with the keys sent inside the TLS signalling); Plain audio switches it back. The carrier must support SRTP, or calls on the trunk fail. Switching a trunk's transport away from TLS turns SRTP off automatically, because the keys would otherwise travel unencrypted.

From the command line: onyx trunk srtp ExampleTel on. Encryption between phones and the server is covered in Security.

Failover between trunks

Failover is set on the outbound route: a route lists up to 8 trunks and tries them in order, moving on when a trunk is unreachable, refuses the call as congested, is at its call limit, is switched off, or (with the minute check on) is not answering. See Trunk order and failover.

For incoming calls, route a phone number with Any trunk if the carrier may deliver it on more than one trunk.

Checking a trunk

The Status column of the list shows:

The Carrier column shows the server and port, how the trunk authenticates (Registers as the username, or Recognised by address), the transport and whether audio is encrypted. Limit shows the call limit. The Dashboard counts the trunks that are up, and its registration log shows trunks signing on and off.

The status comes from the minute check, not from the registration: a carrier can answer OPTIONS while refusing the registration. To see whether a registration succeeded, run onyx trunk status on the server; it prints every registration with its state and every trunk's reachability. Refused registrations and calls also appear in the logs under Server › Logs & diagnostics. More help is in Troubleshooting.

Editing, switching off and deleting

• Edit opens the form with the trunk's settings. The password is never shown; leave Password empty (it says Unchanged (type to replace)) to keep it. Click Save trunk.
• Switch off takes the trunk out of service without deleting it: routes skip it and calls from the carrier on it are not accepted. Switch on brings it back.
• Delete (click twice) removes the trunk. It is refused while an outbound route still uses the trunk, and the message names the routes: delete or recreate them first.

Deleting a trunk also deletes the phone number routes that are tied to it (those with this trunk under Arriving on, and its catch-all). Routes with Any trunk stay.

From the command line

onyx trunk providers
onyx trunk add ExampleTel --mode register --host sip.example.net --user 6125550100 --secret 'S3cret' --dial-format e164plus --callerid-header pai
onyx trunk add ExampleTel --provider telnyx --user acme --secret 'S3cret'
onyx trunk add BackupTel --tenant acme --mode ip --host 203.0.113.20 --match 203.0.113.0/24 --no-qualify
onyx trunk list
onyx trunk enable|disable|delete ExampleTel [--tenant acme]
onyx trunk srtp ExampleTel on
onyx trunk status

Without --tenant, onyx trunk add creates a shared trunk. --provider starts from a carrier template; options you give still win. There is no command to change an existing trunk: edit it in the console. Every option is in Command line (onyx).