Image Removed

What is the Trunks Module used for?

The "Trunks Module" is used to connect your FreePBX/Asterisk system to another VOIP system or VOIP device so that you can send calls out to and receive calls in from that system/device.  You can create connections with Internet Telephone Service Providers ("ITSPs"), with other FreePBX/Asterisk systems, with commercial VOIP phone systems, with FXO Gateways (a device that connects an ordinary telephone line with a VOIP phone system using a network connection), and with FXO cards (cards that are installed in your computer and allow you to connect a standard telephone line).

If you don't have a Trunk set-up, you can still make calls, but only to other extensions on your same phone system.

How is the Trunks Module related to the other Modules?

The “Trunks Module” works together with two other modules that you need to know about:  The “Outbound Routes Module” and the “Inbound Routes Module.”

...

When a call comes into your system on a Trunk, the remote system will send your system the phone number that it is trying to reach and, sometimes, a Caller ID for the person calling.  In the Inbound Routes Module, you will specify the phone numbers that can reach your system and what FreePBX should do with them.  For example, you could configure your system to route calls to 212-555-0001 to extension 100, while routing calls to 212-555-0002 to extension 101.  If you don’t have anything specified in the Inbound Routes Module, Asterisk will play a disconnect recording to the caller.

How Do I Get to the Trunks Module?

To access the Trunks Module in FreePBX 2.10 and later, access the graphical user interface using a web browser.  Click on the "Connectivity" pull down menu at the top and then select "Trunks".

Image Removed

How Do I Create a New Trunk?

To create a new Trunk, click on the "Add Trunk" link at the top, right hand side of the screen in the Trunks Module.

How Do I Modify an Existing Trunk?

All of your existing Trunks should be listed at the upper right hand section of the screen, under the "Add Trunk" option.  If you want to modify or delete one of your existing Trunks, just click on it.

What Type of Trunk Should I choose?

After you choose to create a new trunk, you'll be asked for the type of Trunk you want to add.  

Image Removed

Each Trunk type is used for a different purpose.

SIP Trunk:  A SIP trunk is used to create a connection with another VOIP system/device using the SIP protocol.  The SIP protocol is the most common method of carrying VOIP traffic and most trunks that you create will be SIP Trunks.

IAX2 Trunk:  The IAX protocol is a protocol created by Digium and used only by Asterisk.  It can be used to create a connection between two Asterisk based systems.  Although you can connect two Asterisk systems using SIP protocol, the IAX protocol is usually a better choice for connecting two FreePBX/Asterisk systems together because is much easier to configure.

Custom Trunk:  A custom trunk is used to configure simple connections between two systems that do not require the use of a username, password, registration, etc.  It is most often used to set-up SIP dialing.  For example, if you want to allow your callers to call sip:[email protected], you'll want to use a Custom Trunk.

DAHDi Trunk:  A DAHDi Trunk is used to link FreePBX to a PCI or PCI Express card that is installed into the computer running FreePBX.  The cards can either be configured at the Linux Command Prompt or using the newly release DAHDi Config Module (available with FreePBX 2.10 and later).  Each DAHDi card is assigned a group number, i.e. g0, g1, g2, and each channel on a card is assigned a channel number.  To link a DAHDi trunk to a DAHDi card, just enter the group number (g0) or channel number (3) in the FreePBX Trunk Module’s DAHDi Identifier field.  Only one identifier can be used in each DAHDi Trunk.

ENUM Trunk:  A special trunk that routes calls that are dialed to regular phone numbers over the internet instead, by looking up the phone number on e164.org and then routing the call to the destination specified on e164.org. To use an ENUM trunk, set up the trunk in FreePBX and then make the trunk your first trunk in any outgoing route that can carry regular telephone numbers.  FreePBX will then attempt any ordinary phone call via e164.org's database.  If a match is found, the call will be routed directly to the destination specified in e164.org's database over the internet.  If that fails, FreePBX will attempt the next Trunk in the Outbound Route for that particular call.  

To receive incoming calls via ENUM, you need to make your system available directly on the internet, allow anonymous inbound SIP calls, and then register your phone number at e164.org and give it the SIP address for your system.  WARNING:  Making your system available over the internet exposes your system to hackers, and is not recommended except for the most experienced users.

DUNDi Trunk:  DUNDI allows you to cluster two or more systems together so that each system is aware of the extensions on another system and can route calls.  For more information on DUNDI with Asterisk please see:

1.  http://www.pbxinaflash.com/community/index.php?threads/configuring-dundi-with-piaf2.12598/
2. http://www.voip-info.org/wiki/view/Asterisk+DUNDi+Call+Routing
3. www.dundi.com
4. Digium's sample dundi.conf file.

Zap Trunk:  Zap trunks are the predecessor to DAHDi, are rarely used today, and have been removed from FreePBX 2.11 and higher.

What Do Each of the Trunk Options Mean?

Image Removed

Image Removed

After you select the type of trunk, you'll be brought a new screen that lists the configuration options that are used for that type of trunk.  Generally, your ITSP or your hardware provider will give you the configuration settings to use.  You can get a general description of what each option does by placing your mouse on the question mark to the right of the option (in FreePBX 2.10 and higher) or on the text of the option (in FreePBX 2.9 and earlier), and a tooltip will appear that explains the option. Make the changes that you desire, then scroll to the bottom, click "Submit Changes," and then click the red "Apply Config" bar at the top of the screen. 

Trunk Name:  You can choose any name for your Trunk.  The Trunk Name will be used when you select which calls to route to this Trunk in the Outbound Routes Module.  The Trunk Name has no impact on the operation of the Trunk. 

Outbound CallerID:  See the tooltip for a description of this field.

Maximum Channels:  See the tooltip for a description of this field.

Continue if Busy:  This option should normally be left disabled. It is available as a troubleshooting measure to handle the situation where an outbound route has been defined with multiple trunks set in the calling out trunk sequence and a trunk is failing to place an outgoing call but not returning an expected error condition to Asterisk. Normally (when this option is left unchecked), the next trunk in the sequence is only tried upon the earlier trunk being 'Congested' in some form, or unavailable. Checking this box will force a failed call to always continue to the next configured trunk or destination even when the channel reports BUSY or INVALID NUMBER. This can be a way of enabling the call to succeed when it would otherwise fail when using with a problematic VoIP termination service that is, for example, indicating the number is busy when it actually is not. This option should not be enabled on a trunk that is used as the only or last outbound trunk for any outgoing route as it will break Asterisk's normal busy number handling in this case, causing the number busy tone to not play as expected. For a more detailed description of this feature, see http://www.freepbx.org/news/2012-10-02/more-routing-and-trunking-enhancements-in-2-11.

Disable Trunk:  If this option is selected, the trunk will be turned off and will not do anything until the option is de-selected.

Monitor Trunk Failures:  See the tooltip for a description of this field.

Dialed Number Manipulation Rules:  See the tooltip and the next section for a description of this field.

Dial Rules Wizards:  This pull-down menu offers a variety of options to automatically populate the Dialed Number Manipulation Rules field.

Outgoing Settings / Trunk Name:  The name set in this field should match the username sent by the remote system for incoming calls.  Your system will reject incoming calls whose username does not match this field, unless insecure=invite is used in the PEER details.  If insecure=invite is used in the PEER details, then the name need not match, and you can set this to whatever you want.

PEER Details:  These are where the majority of the Trunk settings are set.  The precise details will vary depending upon the Trunk you are trying to set-up.  Most ITSP's and hardware vendors will supply you with the recommended settings.  We will provide some examples below.

Incoming Settings/USER Context/USER Details:  These are almost never used nowadays and are beyond the scope of this document.

Registration String:  The Registration String is a command sent to Asterisk to tell it to contact the other system, introduce your system, and tell the other system your system's IP address.  It is generally used when the other system has the host= field in its PEER details set to dynamic.  If the other system already knows where to find you, registration is not required.  Generally, the registration string will look like either this:

username:[email protected]

or this:

username:[email protected]:5060/2125551212

Notes:

1. "username" is the username that other system expects to authenticate you.
2. "password" is the password that the other system expects to authenticate you.
3. remoteIPaddress is the IP address or hostname (i.e. test.com) of the remote system.
4. "5060" is the port number Asterisk should connect to the remote system using.  If you omit the port number, you should also omit the colon (:), and Asterisk will attempt the connection on port 5060.
5. "2125551212" tells the remote system to send all calls for your system to 2125551212@yourIPaddress.com.  It is an optional command, and if you omit it, you should also omit the / that precedes it.  This part of the registration string is usually not used, because most users want the remote system to address them using whatever phone number has been dialed by the remote caller.  If you have more than one phone number with the remote provider, for example, you would want to omit this part of the registration string.

Click the "Submit Changes" button at the bottom of the screen to save the Route, and then the red "Apply Config" button at the top to have your changes put into effect by FreePBX/Asterisk.  

Note that "Apply Config" will NOT terminate any existing calls.

How do the Dialed Number Manipulation Rules Work?

The Dialed Number Manipulation Rules settings allow you to change the number that was dialed into another number before the call is sent out on a trunk.

For example, if you put this into the Dialed Number Manipulation Rules:

(18882472425) + 411 |  empty

Then if a system phone dials 411, the system would delete 411 and replace it with 18882472524, which is a free voice activated information system.

If you put this into the Dialed Number Manipulation Rules:

(1212) + empty | XXXXXXX

Then if a system phone dials a seven digit number (XXXXXXX), the system would add 1212 (the area code for New York) before sending the call out.

If you put this into the Dialed Number Manipulation Rules:

(1212) + 9 | XXXXXXX

Then if a system phone dials 9 + a seven digit number, the system would remove the 9 and then add 1212 to the beginning of the number.  So, if a user dialed 9 + 5551212, the system would send the call to 12125551212.

Sample Trunk Configurations:

1.  Dead/Restricted Trunk using SIP Protocol:

Trunk Name:  DeadRestricted

Disable Trunk:  Checked

Outgoing Settings / Trunk Name:  DeadRestricted

Notes:

The DeadRestricted Trunk is a special trunk that is disabled.  It is intended to be used as a dead-end for restricted calls that you don't want completed.  You might choose to use the DeadRestricted Trunk as a destination in your Outbound Routes for calls to 1900 numbers and 976 numbers.

2.  Generic Configuration for Internet Telephone Service Providers using SIP protocol: 

Trunk Name:  ProviderA

Outbound Caller ID:  YOURCALLERIDHERE

Dialed Number Manipulation Rules:

(18882472425) + 411 |  empty

(1212) + empty | XXXXXXX

(1) + empty | XXXXXXXXXX

Notes:  

1. The first line re-routes 411 calls to 1-888-247-2425.  You can change the desired phone number if you prefer.  You can also add additional lines to route calls to other X11 services, such as 211, 311, 411, and so on.
2. The second line adds 1 + 212 to the beginning of any number that is seven digits long.  You should change 212 to your area code.  
3. The third line adds 1 + to the beginning of any ten digit number.  
4. You can delete any of these lines if you don't prefer this functionality.

Trunk Name:  ProviderA

PEER Details:

Registration String:  username:[email protected]

Notes:

1. Replace "ProviderA" with whatever name you want to use for the provider.
2. Replace "YOURCALLERIDHERE" with the Caller ID to be used on outgoing calls on this Trunk.  Note that most of the time, this Caller ID will not be used, as Caller IDs set in the Outbound Routes module and the Extensions Module usually take priority (unless the CID Options field is set to Force Trunk Caller ID).
3. Replace "username" with the username assigned by your ITSP.
4. Replace "password" with the password assigned by your ITSP.
5. Replace provideraddress.com with the IP address or domain name supplied by your ITSP.
6. If the Caller-ID on incoming calls come in with a + at the beginning and you don't want them to, change "from-trunk" to "from-pstn-e164-us".
7. If your inbound calls have no Caller ID, delete trustrpid=yes.
8. If your outbound calls never have the correct Caller ID, delete the fromuser= line.
9. If your outbound calls always fail, try deleting the sendrpid= line.
10. If your inbound calls always fail, try changing "from-trunk" to "from-pstn-toheader"

3.  Using a Custom Trunk to allow your callers to dial a SIP address.

A Custom Trunk is generally used to place a direct SIP Call.  A SIP call is a call placed to a SIP address.  For example, sip:[email protected] or sip:[email protected].  Use these settings to set-up a Custom Trunk:

Trunk Name:  OutboundSIPCalls

Outbound Caller ID:  YOURCALLERIDHERE

Custom Dial String:  

To route calls to a specific destination:  

SIP/[email protected]

To route calls to whatever number has been dialed by the user (as modified by the Dialed Number Manipulation Rules) at a specific remote system:  

SIP/[email protected]provideraddress.com

Notes:

1. Replace "OutboundSIPCalls" with whatever name you want to use for the Trunk.
2. Replace "YOURCALLERIDHERE" with your Caller ID.
3. $OUTNUM$ will pass whatever number was dialed by the inside caller to the Trunk, after it is modified by the Dialed Number Manipulation Rules.
   

4.  Connecting two FreePBX systems:

Connecting two FreePBX/Asterisk systems together requires configuring Trunks and Outbound Routes on both systems.  We've written a separate article on how to connect two systems.  Click here to read it.

What Does That Stuff in the PEER Details Mean?

The PEER details can contain a number of different parameters.  Here are the most commonly used ones in a SIP Trunk, and what they do:

host=192.168.1.99

"192.168.1.99" is the IP address of the remote system that you are going to connect to.  You can also put the domain name (i.e. othersystem.com).  If the other system will register to your system (using the Registration String field on the remote system), you should put the word "dynamic" here.

username=name 

"name" is the username that will be sent to the remote system when you attempt to place a call to authenticate the call.  If the remote system requires authentication on incoming calls, the username= on the local system must match the name put in the "Trunk Name" in the PEER details on the remote system.

secret=password

"password" is the password that will be sent to the remote system when you attempt to place a call to authenticate the call.  It is also the password that you will expect to receive when you receive a call, unless insecure=invite is used int the PEER details (see below).

fromuser=name

"name" is the name that will appear in the from field of the call.  When you place a SIP call, the SIP headers include a to: field ([email protected]) and a from: field ([email protected]).  If you include the fromuser=name line, the "callerID" in the from: field will be replaced with "name".  If the remote system expects the Caller ID to appear in the from field, you should not fromuser=.

fromdomain=test.com

See notes above regarding fromuser=, except that "mysystem.com" will be replaced with "test.com".

type=friend

"friend" means that you will both send calls to and receive calls from this server and that the PEER details will be used both for incoming and outgoing calls on this trunk.

context=from-trunk

"from-trunk" means that incoming calls from this trunk will be treated as if they are coming from an outside line, and will be routed using the rules that you setup in the Inbound Routes Module.  If there is no matching Inbound Route, Asterisk will deliver a "not in service message."  "from-pstn-e164-us" is the same as "from-trunk," except that any leading + in the Caller ID will be removed.  "from-pstn-toheader" is the same as "from-trunk," but that the called number (the DID) will be derived from the to: header instead of the From-DID header.  "from-internal" means that incoming calls from this trunk will be treated as if they were made by an internal phone, and will be routed directly to an extension number, a feature code, or through the outbound routes module.  

Generally, you use "from-trunk" when routing calls from an outside source and "from-internal" for trunks that tie two trusted systems together.

trustrpid=yes

"yes" means that your system will look at the Remote Party ID header for the Caller ID on received calls instead of the from: field of the incoming call.  If you aren't getting Caller ID for incoming calls, you may wish to delete this line.

sendrpid=yes

"yes" means that your system will send the Caller ID on outgoing calls using the Remote-Party-ID header.  If your outgoing calls are always rejected, you may wish to remove this line.  "pai" means that your system will send the Caller ID on outgoing calls using the "P-Asserted-Identity" header.  If your outgoing calls have an incorrect Caller ID, you may wish to add this line.

qualify=yes

"yes" means that your system will periodically send a request that the other system identify itself.  If there is no answer within 2 seconds, your system will assume that the other system is down and stop sending calls to the system until the system responds.  Instead of "yes," you can also put a number, in miliseconds.  For example, qualify=3000 means that your system will wait 3 seconds for a response, instead of 2 seconds.

qualifyfreq=59

"59" is how often, in seconds, that Asterisk will send a qualify, if qualify is set to yes or a number.  If qualifyfreq= is not set, the default of 60 seconds will be used.

nat=yes

"yes" tells Asterisk that the system you are communicating with is or may be behind a NAT, and that Asterisk should ignore the IPAddress in the from line and instead use the IP address that the packets actually come from.

keepalive=30

"30" is the number of seconds that Asterisk will wait between sending keepalive messages.  Keepalive messages are important if you are behind a NAT firewall, because if the firewall closes the port, you may not receive all incoming calls.

port=5060

"5060" is the port where Asterisk will attempt to send outgoing calls and where Asterisk expects incoming calls to come from.  This line is usually omitted.  If omitted, Asterisk will use the default port of 5060.  When used in the PEER details, this has no effect on the Port to which your system expects to receive incoming calls.

insecure=port,invite

"port" tells Asterisk to accept incoming calls even if they come from a port other than the one where calls are expected to come from.  "invite" means that Asterisk should accept incoming calls even if they are not accompanied by the proper username and password.  Most ITSP's require this line.  If only one is used, the comma separating them is omitted.

directmedia=no

canreinvite=no

"no" in these two commands means that Asterisk will not attempt to connect two phones directly together, and will instead route the calls through itself.  canreinvite is the pre-Asterisk 1.8 command and directmedia is the Asterisk 1.8 or later command.

dtmfmode=rfc2833

"rfc2833" is the most common method of signaling touchtones.  "inband" is another method, although less reliable.

disallow=all

"all" tells Asterisk to not use any audio codecs unless they are expressly allowed in an allow= line.

allow=ulaw

"ulaw" is the codec that is allowed.  This command only has an effect if disallow=all appears before it.

For more details on the settings that can be included in the PEER details for a SIP Trunk, see Digium's Sample sip.conf file.

For details on the settings that can be included in the PEER details for an IAX2 Trunk, see Digium's Sample iax.conf file.

Troubleshooting Trunk Problems

1.  Double check your PEER details and Registration String.  Often, Trunk problems occur when the information in the PEER details or Registration String is wrong

2.  Pull-down "Reports", select "Asterisk Info," and then select "Full Report" on right.  In many cases, the information in this report can guide you in the right direction.

3.  Refer to the General FreePBX Troubleshooting Instructions (link).

• From the top menu click Connectivity
• In the drop down click Trunks

How Do I Use the Trunks Module?

See the User Guide