Trunk Settings
General Settings
Name: This setting allows you to name the trunk. The name can generally consist of any text, including spaces and special characters. The name should be unique.
Type: There are several types of trunks available. The most common type is the registration trunk where the system behaves similar to a VoIP softphone that registers to a SIP service provider.
Direction: Traffic can be limited to either inbound traffic or outbound traffic.
- Inbound and outbound: The trunk can be used for inbound and outbound traffic.
- Inbound only: Limiting traffic to inbound traffic prevents users from using the trunk for outbound calls.
- Outbound only: Enable this setting if you are using a trunk for outbound traffic only.
State: This setting enables you to temporarily disable a trunk rather than delete it from the system altogether. When a trunk is disabled, it cannot be used for routing, registration, etc.
Global: This setting is used only in multi-tenant environments. When it is enabled, calls that come in on this trunk are permitted to be routed into other tenants if a match is found on a global alias name. If the direction is not only inbound, then other domains may use this trunk in their dial plans for outbound calls.
Using global trunks is useful in multi-tenant environments and usually just complicates the setup in single tenant environments. When using a global trunk, the DID management must be strictly followed to avoid tricky routing scenarios.
Is Secure: This setting is used to indicate that outbound calls on the trunk can be treated as secure calls. For example, when the trunk goes to a local PSTN gateway, you might decide to treat this call as a secure call. Incoming calls with the SIPS scheme will ask the Vodia PBX system to ensure that the call be kept secure end-to-end.
Inter-Office Trunk
Trunk may terminate calls for remote systems: This flag enables trunk-to-trunk calls where calls that come in on this trunk can be routed to another trunk. This is used for example when using remote offices for local termination.
Dial plan for outbound calls: When the above flag is enabled, the system needs a dial plan to determine how to terminate the call on another trunk.
Registrations
Display Name: The display name is used on SIP level when registering the trunk in the REGISTER request and (unless there is another source, like CNAM) for outbound calls.
Account: Like the display name, this setting is used on SIP level to form the From header in SIP packets unless overwritten for example in outbound calls. If is used for the user part in the URI.
Domain: Like the display name, this setting is used on SIP level to form the From header in SIP packets unless overwritten for example in outbound calls. If is used for the host part in the URI.
Username: The user name and password are used for authentication purposes. In some cases this is identical like the Account, however in some other cases it is different.
Password: The password needs to match the password from the trunk provider.
Proxy Address: This setting defines where requests that are made of this trunk will be sent (also called the outbound proxy). When this field is set, requests will be sent to the specified address. The outbound proxy field follows the definitions of RFC 3263: Locating SIP Servers. You may use the fully qualified domain name (FQDN) for a SIP server. If you add a colon with the port number after the FQDN DNS, a resolution will be used; otherwise, the system will try DNS NAPTR and DNS SRV first. You can force the SIP connection to use TCP by supplying an outbound proxy.
The outbound proxy is an important setting. If an outbound proxy is not used, then the system will assume that SIP requests on this trunk can come from any location. This will make it difficult for the system to match incoming SIP requests and practically open up the system to the whole Internet. Unless you want to receive requests from any location on the Internet, you should specify an outbound proxy or explicitly list addresses.
Proposed duration: When registering, the PBX will propose a duration for the registration. Some SIP trunk providers look at this proposal, however the decision how long the registration is valid is made in the reponse to the registration request by the trunk provider.
Send re-registrations at this percent of expiry time: The system usually does not wait until the registration has expired. Instead it sends the request some time before the expiration. This setting controls when that is happening.
Minimum expiry time: Depending on the re-registrations percentage, the time for a re-registration can get very short. This settings limits the minimum value.
Keep-alive time: When the PBX is behind a firewall with NAT, some service providers are not able to detect this situation and come up with a registration time that will keep the NAT binding alive. In such cases this settings can override the time and explicitly set the registration time after which the system will send a re-registration. In a NAT environment, a typical value could be 30 seconds.
Proxy-Require: This setting tells the system what to put into the Proxy-Require header in the registration request. Some service providers need a text in this header to function properly.
Other headers in registration request: This setting is a generic way to add headers to the registration request. Multiple headers must be seperated by newline in the input field and the format matches the format in the SIP request (header: value). A typical example would be setting the User-Agent-header.
Send email on status change: The stability of a SIP registration is important for the overall experience of the system. In order to alert the administrator of the system, this setting can be used to trigger an email that is sent when there is a change of the SIP trunk. The system can also send registration metrics that contain more information like the response time of the SIP registrar.
DNS lookup for registration refresh: By default, the system will re-register the trunk to the same address like the last successful registration address. This avoids load on the DNS server and removes a point of failure (DNS server). However there are situations when the system should query the DNS whenever the DNS record has expired. This can be enabled with this setting.
Explicitly list addresses for inbound traffic: This setting allows you to explicitly state trusted inbound proxy addresses and enables you to identify the origin of the request. By default the system determines the list of addresses through a lookup of the proxy address (see above). The addresses can be either IP addresses (with an optional port number behind) or a DNS A or AAAA address.
Preferred SIP port for trunk: In some situations, it is neccessary to control what SIP port the trunk is using (this assumes that the trunk is using UDP). For example, in multi tenant environment this makes it possible to use SIP trunk providers that use the IP address and port to identify the tenant. The port must be in the list of SIP ports that the system opens.
Routing and Redirection
The routing of inbound calls is described in a seperate article Inbound Routing of Trunks.
Source for caller-ID information: This setting controls where the system is looking for the caller-ID for an incoming call. If the header is empty, it will fall back to the From-header.
Failover behavior: When the trunk receives an error code, it might send the call back to the dial plan and continue the matching process. The system continues the dial plan with the next highest priority, ignoring entries with lower or same priority. This is useful when the trunk is just a "trial" to place the call. One example is when several PSTN gateways are available for terminating the call and one gateway does not accept any more calls. Another example is when you first try to route the call via a peer-to-peer call using ENUM or other location methods and only if such resolution does not result in a connection fallback to a PSTN call. The setting allows four behaviors:
- No failover: This is the default behavior. In this case, the caller will receive the error code as a result of the attempted call.
- On 5xx and 408 error codes: This will trigger failover only when a 5xx or 408 class error code is received. PSTN gateways typically return 5xx class error codes when all channels are in use; however, this mode will allow you to switch to the next PSTN gateway when a line is busy and will not trigger the failover.
- On all error codes: In this case, all error codes will trigger the failover process. Note that call redirect will also be treated as an error code, as the redirection destination can easily be abused to route calls through expensive routes.
- Always, except for busy response: Except if the remote party is busy, the system will try alternate routes.
If you are using failover, you have the option to specify a request timeout value for the trunk. By default, this is 32 seconds (the SIP default request timeout). However, in many cases, it makes sense to specify a shorter value. After the request timeout, the system will internally generate a "408 Request Timeout" response code and process it according to the failover rules.
Request timeout: The SIP standard defines when a request times out. However in some situations those timeouts are too long, e.g. waiting 32 seconds for the failover to the next trunk. This settings will trigger the timeout event at the specified time.
Accept redirect: Use this setting if your trunk should respect redirect codes. By default, this introduces significant security risks because the system cannot determine whether these redirects introduce additional costs (redirection to expensive numbers). Therefore, enable this setting only if you are sure that your service provider or SIP gateway does not abuse this feature. This flag is especially important when you use the system with Microsoft Exchange or other Microsoft products, such as the speech server. Also enable this setting when you have a trunk that comes from another system. This will make it possible to call from one system to another.
Don't accept SIP routing changes in dialog: The SIP standard describes how the client and the server negotiate the routing of packets. However in some cases this does not work, for example when firewalls are involved or just software that is not SIP compliant. In this case the PBX will ignore routing changes and stick with the initial routing of the request.
Error message when all lines are busy: This setting determines what the system will respond when all CO-lines are in use.
Redirect destination when all lines are busy: The system can propose a redirection target for the case that all lines are busy. This is used for outbound calls from extensions.
Teams: This flag is used to tell the system that the trunk is used for the connection with Microsoft Teams.
Number/Call Identification
Prefix: This setting is used as a representation of the system when making outbound calls. If an ANI has not been set, the system puts the prefix (if there is one) in front of the primary account number and uses that as the ANI before it leaves the trunk. This is very useful in cases when a trunk deals with a range of numbers (typically outside of the NANPA area, e.g., Europe). The "extension" number is put after the prefix.
Trunk ANI: You can configure each trunk with an ANI (Automatic Number Identification). ANI is a service that tells the recipient of a telephone call the telephone number of the person making the call. In most cases, the ANI is used in the From field in the SIP packets or the caller ID.
Regular ANI rule: The rule set for determining the ANI for regular calls. For more information, see Trunk ANI.
Emergency ANI rule: The rule set for determining the ANI for emergency calls. For more information, see Trunk ANI.
SIP Caller-ID Presentation: This setting tells the system how to present the caller-ID on the trunk. The following values are available for configuring this setting:
- RFC3325 (P-Asserted-Identity): RFC 3325 describes a way to represent these two numbers. In most cases, it makes sense to use the P-Asserted-Identity header. In this case, the From header in the INVITE represents the display number, while the P-Asserted-Identity header has the network number. A similar representation can be done with the P-Preferred-Identity header. The system changes only the name of the header from P-Asserted-Identity to P-Preferred-Identity. The rest remains the same, as in the first method.
- No Indication: No Indication: This method simply discards the display number and uses only the network number in the From header. This method is a fallback when the provider cannot handle any other method. The disadvantage here is clearly that any redirection information gets lost.
- Remote-Party-ID: Remote-Party-ID: This method is described in a draft that expired years ago; however, there is still a lot of equipment outside that is supporting this method. In this case, the From header in the INVITE represents the network number, while the P-Asserted-Identity header is the display number.
- RFC3325, but don't hide: RFC 3325, but don’t hide: This method should not be used. It has been used in environments where the fields have gotten mixed up, and it is creating even more confusion.
- Custom Headers headers are discussed in detail on the Custom Trunk Headers page.
Rewrite global numbers: When you are using a trunk, you may have to represent the telephone number in a specific format. For example, in the NANPA area, you might want to use 10 or 11 digits to represent a national number. When Use + symbol at the beginning is selected, the system will automatically use 11 digits.
Country code: Sometimes the trunk "lives" in a different country than the tenant country. If set, this setting overrides the country code from the tenant.
Area code: Same like the country code, but the for area code.
P-Charging Vector: The "ICID" (IMS Charging Identifier) setting is used in the IMS(IP Multimedia Subsystem) environment. The setting is sent in the P-Charging-Vector header of the SIP packets on this trunk and it is essentially a token that identifies the trunk. If your provider uses this header, you should put it into this field.
Diversion header: This setting controls whether the system should send the Diversion-header in outgoing calls. If the header is set to {rfc} the RFC defined default is used. Otherwise the setting is subject to variable replacement like in the Custom Trunk Headers.
Avoid RFC4122 (UUID): UUID are a way to identify the SIP trunk in a unique way. This helps to avoid double registration, e.g. after a restart of the system. Like with many useful features, many SIP service providers don't support the feature and reject the request. In such cases, the UUID must be suppressed.
Attach PIDF-LO for emergency calls: PIDF-LO objects can be used to indicate the location of the caller. The system can use this to indicate the location for emergency calls in a multipart-MIME attachment for outbound calls.
Show History-Info: The History-Info-header is a powerful way to indicate how the call was redirected inside the system. Some service providers are able to use this header to provide additional information to the caller.
Indicate RTCP-XR support: RTCP-XR is a powerful way to measure and report the call quality for example for MOS, however it requires that both sides of the call support the standard. Although negotiated automatically, many SIP servers get confused when RTCP-XR support is proposed and reject calls. Because of this, the support indication can be suppressed.
SRTP key exchange: By defaut the system will propose that RTP is encrypted (SRTP) when a secure transport layer such as TLS is used for the call setup. However some SIP servers get confused with this. In such cases this setting can be used to suppress encrypted audio. This setting selects the method used for negotiating the keys.
Generate unique extension identifier: This setting allows you to use the extension’s EPID instead of the ANI if the extension’s EPID has already been set. If extension’s EPID is not set, "generate" a new EPID and use it (and set it for extension for the future use too).
Interpret SIP URI always as telephone number: When a call comes into the system, the system needs to know how to interpret the number. In SIP, the URI contains a domain name; however, in most cases, the domain name should be ignored when interpreting the URI coming from this trunk (because the user portion is just a telephone number). Usually, this is indicated by the parameter "user=phone," but not all service providers set this flag. By turning on the "Interpret SIP URI always as telephone number," you make the system believe that this flag was set on the trunk call.
Caller ID update on trunk: This setting is used to update the caller ID information on the trunk. For example, if you want to update the caller ID that is sent to a remote party, when a call is transferred, you can use this setting. This is dependent on whether the trunk provider supports that feature.
Lookup SPAM provider if available: When a SPAM provider was set up on the system, this setting controls if that provider i used to look the caller up when a call comes in through the trunk.
Identity header: This header is used when STIR/SHAKEN is used for outbound traffic.
Map STIR/SHAKEN stats to SPAM scores: When STIR/SHAKEN is available for inbound traffic, the PBX needs to map the attestation values to SPAM scores. When enbled, a table for the mapping opens up.
Contact header value: Some SIP servers get confused with the standard SIP contact header value. This setting can be used to override the value of the contact header.
Customer specific header: Like with the registration, additional headers can be specified for the trunk for outbound calls. The format is the same like with the registration. In contract to the registration header, this setting is subject to variable replacement, for example caller-ID information can be inserted in to the requests (e.g. X-Other-From: {from}).
Media/Audio
General codec preference: Use this setting to specify particular codec preferences for the trunk. By default, the system uses the codec preference of the system, which has the advantage of allowing the system to negotiate codecs in such a way that transcoding can be avoided. (When default mode is used, no codecs will be displayed on the left side of the codec selection box.) If it is necessary to enforce specific codecs on a trunk, choose a codec from the list of available codecs and click the Add button. Be sure to position the codec with the highest preference first. To delete a codec, click the Remove button. To move a codec up or down in the preference list, use the Up and Down buttons.
Number of codecs in SDP answer: When the PBX generates an SDP answer, it offers all codecs that would work. However some SIP trunk providers are unable to process this kind of choice, resulting in media problems. By setting this value to 1, only one codec will be selected.
Generate PCAP traces for calls. When this flag is turned on, the PBX is generating PCAP files for the call which can be retrieved from the system call log or from the file system.
Strict RTP Routing: This setting is needed because the IETF allows "RTP traffic send ports" to be different from "RTP receiving ports," creating a NAT-unfriendly situation. While most implementations today use the same port number for sending and receiving RTP, some gateways still insist on strict IETF compatibility. In such cases, this setting should be enabled. We recommend you keep this flag disabled unless asymmetrical ports are required.
Port range start, end: This setting overrides the setting for the RTP port range on system level. Some SIP trunks need the RTP ports to be in a specific range; if that range is very short it makes sense to set it for the trunk and not globally for the whole system.
Trunk requires out-of-band DTMF tones: When this setting is enabled, the trunk will use RFC 2833.
Requires busy tone detection: When an analog PSTN gateway is used, hangup detection can be an issue. In such situations, enabling the busy tone detection may be needed. If the SIP trunk provides proper hangup detection, it is strongly recommended to keep this setting disabled to disable false hangup detection.
Unfortunately, no international standard exists for the disconnect tone. Incoming international calls might give you a disconnect tone that the system has to recognize. Of course, if the PSTN gateway is capable of detecting this, the task should be left to the PSTN gateway. However, as a fallback, you may also configure the system to perform the hangup detection. The disadvantage of doing this is that it costs additional CPU resources, and it might randomly disconnect calls; for example, if the other party plays back a tone that sounds like a busy tone, the call may be disconnected.
Use T.38 for FAX: By default the trunk will attempt to use T.38 for FAX transmission. However in some cases, modem encoding must be used.
PRACK support: Not all SIP trunks support PRACK, which make the signaling of early media more reliable. This flag can be used to suppress PRACK.
Ringback on incoming calls: This feature was introduced to deal with network operators who were unable to deal with early media. Although using the 180 Message simplifies the signaling in forking calls scenarios, it creates additional delay when the called party picks the handset up and the first samples on the conversion may not be transported. We strongly recommend leaving the flag set to Media (which is default) and asking the operator to fix the problems with early media.
Local ringback generation for outbound calls: This setting is used in cases where the service provider sends back a 183 with SDP, but doesn't provide the ringback tone. With this setting, the PBX can force a local ringback. For providers that support P-Early-Media it is suggested to turn this feature on, so that the PBX can automatically determine wether to play local or remote ringback.
Play file for local ringback when needed: There are conflicting cases when the PBX should actually play local ringback, but the trunk is still providing it. There are only few cases when this flag needs to be turned off.