====== SIP Trunk ======
The SIP Trunk module is designed to connect IP-PBX's and other SIP endpoints (phones) to Internet Telephony Service Providers by acting as a B2BUA (Back-To-Back User Agent) with one interface to the ITSP and the other to the IP-PBX and SIP phones. The ITSP interface is called SIP Trunk and the protocol used on both interfaces are SIP. The main function performed by this module is to provide a demarcation point where all communication on the SIP trunk behaves in a predictable way regardless of what equipment connects on the PBX interface. 

^ :!: You might need to purchase a [[:license]] to be able to use SIP Trunks in your unit. ^
| Without SIP Trunk license the [[web GUI:SIP Trunk]] page is not functional. |

===== Configuration =====
SIP Trunks are configured on the [[web GUI:SIP Trunk]] page.
To make an outgoing call use the SIP Trunk module the [[web GUI:SIP Switch#Dial Plan]] on the [[web GUI:SIP Switch]] page is used.

===== Interoperabilty =====
Interoperability problems between different SIP equipment may hinder SIP deployments, with the SIP Trunk module such problems can be avoided as SIP messages gets translated to support requirements on the SIP Trunk. Interoperability problems often arises due to presence of certain information in header fields of SIP messages, most common issues are addressed by GUI settings, however there is also a way to manipulate generic SIP message header fields, see [[#Header manipulation and variable substitution]] below.

===== PSTN Access and Pools =====
As the SIP Trunk module gives PSTN access to SIP devices connected to Internet Gate it has options of sharing PSTN numbers as well as using individual PSTN numbers for each SIP user. Sharing can be done so that the same number (caller-id) is always used for a particular set of users or a pool of PSTN numbers can be used by a group of SIP users. The idea of the pooling feature is that if the SIP Trunk does not support multiple calls using the same number, the pool will automatically select a number that is not busy. The pooling feature is configured though the "User Name" field in Trunk Lines below. 

===== Routing calls =====
To make an outgoing call use the SIP Trunk module the Dial Plan on the [[web GUI:SIP Switch]] page is used. The call is routed to the SIP Trunk module if the "Forward to" field of the Dial Plan equals the string "SIPTRUNKx" where x is the SIP Trunk module number (1-9). 

===== Firewall/NAT traversal =====
The SIP Trunk module communicates with the builtin SIP proxy and firewall/NAT to support communication through the firewall and NAT. 

===== Header manipulation and variable substitution =====
A generic SIP header manipulation tool for SIP requests passing through the box is available through configuration using the grammar for the header field component in a SIP URI using '?', '=', '%' and '&', as described in [[http://www.ietf.org/rfc/rfc3261.txt|RFC 3261]].

In short, header fields for usage in SIP messages are put at the end of a SIP URI after a '?'. The header is written on the form header_name=header_value and additional headers are separated by a '&'. Any characters not allowed in this header component according to RFC 3261 must be escaped with %HEX construction where HEX is the 2-digit hexadecimal number representing the escaped character. 

Specific to Internet Gate is that the string "%%__remove%%" put as header_value means the header should be removed. Also the Internet Gate supports variable substitution in the form $(variable_name) so the "$(" sequence is treated specially. If a specified header field is already present in the SIP request it is replace, else the header field is added.

Variables that can be used for variable substitution are:

  * ruri.user = user from Request-URI 
  * ruri.host = host from Request-URI 
  * to.user = user from To header 
  * to.host = host from To header 
  * from.user = user from From header 
  * from.host = host from From header 
  * hdr.header_name = The complete header value of header "header_name". 
  * net.if.ip=[et1] = The IP adress of network interface "et1"

Example:
  ?User-Agent=$(hdr.user-agent)&Contact=sip:foo%40$(net.if.ip=[et4])%3buser%3dphone&Organization=mycompany&Privacy=__remove

Assuming the IP address of et4 is 1.2.3.4 and the received request contains a Privacy and a User-Agent header field, the following will happen: 
  * Privacy header field will be removed 
  * User-Agent will be kept unchanged (an IX may otherwise change User-Agent if used in b2bua mode) 
  * The following fields are added:\\ Contact: %%sip:foo@1.2.3.4;user=phone%%\\ Organization: mycompany 

Header manipulation can be set for outgoing calls in the "User Name" field below and for incoming calls it can be set in the "Forward to" field. If you wish to use header manipulation, append the header string starting with '?' after other things that should go in the respective field. 

Software License
The SIP Trunk Module is a software option that is purchased by pressing the Buy link at the top of the page. Without software license this page is not functional.