Trunks in FreePBX 2.5

Alex Robar

September 2009

A trunk in the simplest of terms is a pathway into or out of a telephone system. A trunk connects a PBX to outside resources, such as PSTN telephone lines, or additional PBX systems to perform inter-system transfers. Trunks can be physical, such as a PRI or PSTN line, or they can be virtual by routing calls to another endpoint using Internet Protocol (IP) links.

Trunk types

FreePBX allows the creation of six different types of trunks as follows:

  1. Zap
  2. IAX2
  3. SIP
  4. ENUM
  5. DUNDi
  6. Custom

Zap, IAX2, and SIP trunks utilize the technologies of their namesake. These trunks have the same highlights and pitfalls that extensions and devices using the same technology do. Zap trunks require physical hardware cards for incoming lines to plug into. SIP trunks are the most widely adopted and compatible, but have difficulties traversing firewalls. IAX2 trunks are able to traverse most firewalls easily, but are limited to adoption mainly on Asterisk-based systems.

In terms of VoIP, ENUM(E.164 NUmber Mapping) is a method for unifying E.164 (the international telecommunication numbering plan) with VoIP routing. The ENUM system can be considered very similar to the way that the Internet DNS system works. In the DNS system, when a domain name is looked up an IP address is returned. The IP address allows a PC to traverse the Internet and find the server that belongs to that IP address. The ENUM system provides VoIP routes back when queried for a phone number. The route that is returned is usually a SIP or IAX2 route.

An ENUM trunk allows FreePBX to send the dialed phone number to the publice164.orgENUM server. If the called party has listed their phone number in the directory, a VoIP route will be returned and the call will be connected using that route. A VoIP route contains the VoIP protocol, the server name or IP address, the port, and the extension to use in order to contact the dialed phone number. For example, a SIP route for dialing the number 555-555-1234 might appear as This is advantageous in several ways. It is important to note that indirect routes to another telephony system are often costly. Calling a PSTN telephone number typically requires that call to route through a third-party provider's phone lines and switching equipment (a service they will happily charge for). If a number is listed in the ENUM directory, the returned route will bridge the call directly to the called party (or their provider), bypassing the cost of routing through a third party.

ENUM also benefits the called party, allowing them to redirect inbound calls to wherever they would like. Service disruptions that would otherwise render a particular phone number useless can be bypassed by directing the phone number to a different VoIP route in the ENUM system.

More information on ENUM can be found at the following web sites:

DUNDi (Distributed Universal Number Discovery) is a routing protocol technology similar to ENUM. In order to query another Asterisk system using DUNDi, that system must be "peered" with your own Asterisk system. Peering requires generating and exchanging key files with the other peer.

DUNDi is a decentralized way of accomplishing ENUM-style lookups. By peering with one system you are effectively peering with any other system that your peer is connected to. If system A peers with system B, and system B peers with system C, then system C will be able to see the routes provided by system A. In peer-topeer fashion, system B will simply pass the request along to system A, even though system C has no direct connection to system A.

DUNDi is not limited to E.164 numbering schemes like ENUM and it allows a PBX to advertise individual extensions, or route patterns, instead of whole phone numbers. Therefore, it is a good candidate for distributed office setups, where a central PBX can be peered with several satellite PBX systems. The extensions on each system will be able to call one another directly without having to statically set up routes on each individual PBX.

More information on DUNDi can be found at the following web sites:

Custom trunks work in the same fashion as custom extensions do. Any valid Asterisk Dial command can be used as a custom trunk by FreePBX. Custom trunks typically use additional VoIP protocols such as H.323 and MGCP.

Setting up a new trunk

Setting up a trunk in FreePBX is very similar to setting up an extension. All of the trunks share eight common setup fields, followed by fields that are specific to the technology that trunk will be using.

In order to begin setting up a trunk, click on Trunks in the left side navigation menu as shown in the following screenshot:

FreePBX 2.5 Powerful Telephony Solutions

From the Add a Trunk screen, click on the name of the technology that the trunk will be using (for example, if a SIP trunk will be used, click on Add SIP Trunk) as shown in the following screenshot:

FreePBX 2.5 Powerful Telephony Solutions

Common trunk setup fields

No matter which technology a trunk will be using, the same eight fields will appear first on the configuration page as shown in the following screenshot:

FreePBX 2.5 Powerful Telephony Solutions

Outbound Caller ID sets the caller ID name and number that will be displayed to the called party. Caller ID should be in the format of "Name" <##########>,where "Name" is the name that will be displayed, and <##########> will be the telephone number displayed. Be sure to include the quotes and angle brackets to send both name and number information. In order to send just a telephone number without a name, simply put the telephone number in the Outbound Caller ID field without quotes or angle brackets. Note that setting outbound caller ID only works on digital lines (T1/E1/J1/PRI/BRI/SIP/IAX2), not POTS lines. The ability to set outbound caller ID must also be supported by your provider.

FreePBX will ignore the Outbound Caller ID field if it is not in the proper format. Be sure that a caller ID with a name and number contains a name in quotes and a telephone number in angle brackets. A caller ID with just a telephone number must only contain the number and nothing else. FreePBX will not set the caller ID on outbound calls that do not match one of these two formats.

The Never Override CallerID checkbox should be selected in order to disable any other part of FreePBX from setting the caller ID on this trunk. If this box is checked, a caller ID value must be set in the Outbound Caller ID field. This option is useful when the trunk connects with a provider who will drop calls that set a different caller ID than the one they are expecting. This can often mean that calls that are forwarded out to an external number ("hair-pinning" a call) will be dropped, as FreePBX will attempt to set the caller ID to that of the original caller. If inbound calls are routed back through this trunk and the provider seems to be dropping them, try turning this option on.

Maximum Channels  is the maximum number of outbound calls that this trunk can support. Note that FreePBX does not count inbound calls against the channel limit. Whole numbers greater than one are the only valid values for this field. If no limit should be imposed, leave this field blank.

The Disable Trunk checkbox allows a trunk to be temporarily disabled in any outbound route where the trunk is in use. If a trunk is experiencing difficulties, it can be disabled here in order to have outbound calls skip the trunk entirely in their routing sequence. Under normal circumstances, a downed trunk will simply refuse a call, but in scenarios in which a trunk accepts a call but fails to connect it properly, this option is especially useful. Without disabling the trunk in this scenario, all of the calls will be dropped. Disabling the trunk allows outbound calls to bypass the problematic trunk while it is repaired, instead of having to remove the trunk entirely and recreate it when the problem is resolved.

The Monitor Trunk Failures field allows an AGI script to be called when a trunk fails. FreePBX determines that a trunk has failed when calls cannot be completed and the returned status from Asterisk is not BUSY, NOANSWER, or CANCEL. Scripts specified in this field can perform any action that can be scripted, including reloading Asterisk configuration to force trunk re-registration, or notifying a system administrator of the failure through email. Failure scripts must be located in the /var/lib/asterisk/agi-bin directory. The full name of the failure script should be specified.

Dial Rules  allow dialed numbers to be manipulated before they are passed to the trunk. Dialed numbers are altered based on the patterns entered into this field. There should only be one pattern per line. Only the first matched rule will be acted upon (other patterns will be ignored, even if they match). Patterns are matched based upon the order they are listed in, that is, from top to bottom. Patterns can consist of the following items:




Any whole number from 0-9


Any whole number from 1-9


Any whole number from 2-9


Any whole number or letter in brackets. Note that multiple numbers can be separate by commas, and ranges of numbers can be specified with a dash ([1,3,6-8] would match the numbers 1, 3, 6, 7, and 8).


Matches one or more characters (acts a wildcard)


Removes a prefix from the dialed number (555|1234567 would take 5551234567 and pass 1234567 to the trunk)


Adds a prefix to the dialed number (555+1234567 would take 1234567 and pass 5551234567 to the trunk)

Note that wildcards are not valid before a "+" or "|". Also, "+" and "|" can be used in the same pattern (0|01+15551234567 would take 015551234567 and pass 0115551234567 to the trunk). Dial rules are very useful for allowing users to continue dialing numbers the way they are accustomed to, even if the provider is expecting them to be delivered in a different way.

A few real-world examples of dial pattern usage are given below:


Dial Pattern(s)

Users are used to dialing 9 to access an outside line. A FreePBX system replaces their existing PBX, but should accommodate this dialing pattern instead of forcing users to learn a new one. The provider is expecting all of the numbers to be sent in standard North American 10 digit format.



The provider requires an account code to be sent in front of all of the dialed calls (in this example, the account code is 654321). Calls must be sent in standard North American 10 digit format.




The provider requires all of the numbers to be sent in standard North American 10 digit format except for toll free calls. Toll free calls should never send the leading 1.

In this example, note the order that items are listed in. If the last item were listed first and a user were to dial 800-555-1234, a 1 would be appended and sent to the provider, and the call would fail.






Dial Rules Wizards are pre-constructed dial patterns for use in the Dial Rules field. Selecting the name of one of the pre-made patterns will populate the Dial Rulesbox with the appropriate pattern.

Outbound Dial Prefix can be used in order to add a prefix to every single call dialed through this trunk. This option can be useful if accessing an outside line requires dialing an extra number (usually 9). This option can also be useful for certain Zap cards that are slow to pick up the line and therefore, start dialing before the line is listening for the digits. Adding a "w" as the outbound dial prefix will cause the system to wait for 50 milliseconds before dialing (multiple "w" characters can be strung together to create a longer wait). Anything that is valid in an Asterisk dial string command can be entered into this field.

Zap trunks

Beyond the common trunk fields, Zap trunks only have one additional field to fill in as shown in the following screenshot:

FreePBX 2.5 Powerful Telephony Solutions

Zap Identifier (trunk name) should match the group (and optionally the channel number) that is set up for this Zap trunk in the /etc/asterisk/zapata.conf file. Zapata.conf will have a section like the ones below for each Zaptel card that is present in the system:

signalling = fxs_ks
channel => 1

signalling = fxs_ks
channel => 2

Entering a value of g0 in the Zap Identifier (trunk name) field will call each channel in group zero sequentially until it finds one that picks up. Alternatively, it is possible to separate out each channel in unique trunks by entering values such as g0-1 for group zero, channel one, g0-2 for group zero, channel two, and so on.

When all of the required values have been entered, click on the Submit button to write the changes to the database. As with all of the changes, click the orange-colored Apply Configuration Changes bar to load the new configuration changes into memory.

IAX2 and SIP trunks

IAX2 and SIP trunks share the same additional configuration settings as shown in the following screenshot:

FreePBX 2.5 Powerful Telephony Solutions

Trunk Name  is a "friendly" name. This value is not parsed by FreePBX in any way; it is simply used to refer to the trunk in other parts of the FreePBX interface.

PEER Details are the outbound configuration details that would normally be placed into iax.conf or sip.conf for IAX2 or SIP trunks, respectively. These details will vary widely from trunk to trunk, and should be supplied by the trunk provider. By default, FreePBX populates this field with the most commonly required values.

In the PEER Details field, host is the IP address or DNS hostname of the provider. This is the destination server or network that Asterisk will send calls to when they use this trunk. The username and secret lines are for the credentials used to authenticate this trunk against the provider. The type line should almost always be set to peer, as this designates that this set of details is for a destination that Asterisk is sending calls to (not receiving calls from).

The USER Context field is the telephone number, account number, or account name that your provider is sending inbound calls to. Some providers will simply send a call to the registered IP address, in which case this field is not required.

The USER Details field is for the inbound configuration details that would normally be placed into the iax.conf or sip.conf files for IAX2 or SIP trunks, respectively. As with the PEER Details field, these details can vary widely, but will likely be supplied by the trunk provider.

In the USER Details field, the secret line is the password that the provider will use to authenticate incoming calls against. The type line should almost always be set to user, as this designates that this set of details is for a peer that Asterisk is receiving calls from (not sending calls to). The context line indicates the context that inbound calls from this trunk should be sent to. Unless you have defined custom contexts, leave this field set to from-trunk to allow FreePBX to process the calls.

Order is important.
The order that parameters are specified in for both the PEER Details and USER Details fields is important. Details are set from top to bottom. If a certain parameter appears twice in one of these fields, the second instanceof it will be used and the first will be ignored. If allow=ulaw is followed by deny=all, all of the codecs will be denied and the allow statement will be ignored. Pay close attention to how these parameters are ordered. It can often save hours of troubleshooting later on when a trunk seems to be refusing calls for no reason at all.

The Register String   is also a setting that should be supplied by the trunk provider. The value in this field will cause FreePBX to attempt to register with the trunk provider. Registration lets the provider know where to send calls when they come in for your telephone number. The register string is usually in the format of [username]:[password]@[voipserver] (for example, If a register string is not provided then the provider must be set up in order to send calls to a specific IP address, and the IP address of your VoIP server must not change.

ENUM trunks

ENUM trunks require absolutely no additional configuration beyond the common configuration fields. The only item worth noting for ENUM trunks is that all of the calls are queried against the database. expects calls to be in the format of [CountryCode][PhoneNumber], so adjust dial patterns appropriately for your location.

DUNDi trunks

DUNDi trunks require a bit of prep work before they can be successfully used to route calls. Before a DUNDi trunk can be set up, your PBX must be peered with one or more nodes. Peering DUNDi nodes are not set up within the FreePBX interface. Peering is completed by editing the /etc/asterisk/dundi.conf file on both PBX systems.

Once the PBX systems have been peered, FreePBX can be used to create a DUNDi trunk. Beyond the common fields, DUNDi trunks only require one additional piece of information as shown in the following screenshot:

FreePBX 2.5 Powerful Telephony Solutions

The DUNDi Mapping field tells FreePBX which DUNDi context to query for results. It is possible to have various DUNDi contexts for sharing different types of VoIP routes. One might have one DUNDi context for sharing local extensions between branch offices, and another context for advertising which external phone numbers they own. Each DUNDi context will require its own DUNDi trunk within FreePBX.

To find the name of the DUNDi context, open the /etc/asterisk/dundi.conf file for editing, and look for the [mappings] section. The section should look like the following:

priv => dundi-localextensions,0,IAX,priv:${SECRET}@pbx.examplehost.
pub => dundi-publicnumbers,0,IAX,priv:${SECRET}

In this example, priv is the name of the DUNDi context that advertises local extensions. Asterisk will advertise any extension that exists under the dundilocalextensions dialplan context if a peer queries it using this context. Likewise, pub is the public DUNDi context that will advertise any telephone route listed in the dundi-publicnumbers dialplan context. Type the name of the DUNDi context that this trunk will query into the DUNDi Mapping field and click on the Submit button. Once the changes have been saved, click on the orange-colored Apply Configuration Changes bar at the top of the screen.

Custom trunks

Custom trunks are very similar to custom extensions and devices. There is only one additional field for setting up custom trunks as shown in the following screenshot:

FreePBX 2.5 Powerful Telephony Solutions

The Custom Dial String can be any valid dial command that would normally be used in the Asterisk dialplan, with one notable exception: the called number is inserted into the dial string using the $OUTNUM$ variable. For example, the string to call an H.323 device at IP address might be H323/$OUTNUM$.

As with any changes made to FreePBX, make sure to click on the Submit Changes button, followed by the orange-colored Apply Configuration Changes bar at the top of the screen to save and reload all of the settings.


By now, we should have a FreePBX system with some fully-functional trunks configured. We should be able to configure a new trunk of any type from the various choices available. We have covered a lot on trunks in FreePBX which included the various types of trunks allowed by FreePBX and the various methods for setting up each type of trunk.


If you have read this article you may be interested to view :

You've been reading an excerpt of:

FreePBX 2.5 Powerful Telephony Solutions

Explore Title