<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2171/18/9/_/styles/combined.css?spaceKey=TOP&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/TOP/SIP+Session+Gateway+Configuration">SIP Session Gateway Configuration</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~beagles">Brent Eagles</a>
</h4>
<br/>
<h4>Changes (8)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h1. Overview <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Configuration of the SIP Session <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Manager</span> <span class="diff-added-words"style="background-color: #dfd;">Gateway</span> component is done through configuration interfaces consistent with the Asterisk SCF [Configuration Pattern]. The Slice definitions for SIP configuration groups and items can be found in {{sip/slice/AsteriskSCF/Configuration/SIPSessionManager/SIPConfigurationIf.ice}}. Deployment architects can develop their own mechanism for pushing configuration to a SIP component instance or they may use the provided Python configuration script, {{SIPConfigurator.py}}, found in the {{sip/config}} directory. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >In addition to the SIP component configuration, there are a few SIP Session <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Manager</span> <span class="diff-added-words"style="background-color: #dfd;">Gateway</span> specific icebox configuration item <br></td></tr>
<tr><td class="diff-unchanged" > <br>h2. SIPConfigurator.py <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >Similar to other example Python configuration script tools in Asterisk SCF, SIPConfigurator.py reads configuration from a text file and initializes structures defined in Slice and invokes on an Ice object that supports the configuration interface. The format of the text file is similar to the "INI" file format. Configuration items are typically separated into INI sections and have "type" field that holds a string value that the configuration script uses to determine the type of configuration item to create and populate with the contents of the section. The full details of how configurator.py scripts are described in [Configurator Python Module]. <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{info}</span> <span class="diff-added-words"style="background-color: #dfd;">{tip}</span> <br></td></tr>
<tr><td class="diff-unchanged" >Unless an alternate configuration mechanism is being used, {{SIPConfigurator.py}} is one of the four key elements that need to be modified to support new configuration items. The other three are the SIPConfigurationIf.ice Slice file, the {{AsteriskSCF::System::Component::V1::Configuration}} object implementation in SIPConfiguration.cpp and, of course, the SIP component code. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{info}</span> <span class="diff-added-words"style="background-color: #dfd;">{tip}</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>h2. IceBox configuration <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The SIP Session <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Manager</span> <span class="diff-added-words"style="background-color: #dfd;">Gateway</span> has only one component specific Icebox configuration item: _ServiceName_{{.SIP.Modules}}. The property is a space delimited list with the following as valid non-mutually-exclusive values: <br></td></tr>
<tr><td class="diff-unchanged" >* Logging - enables logging in the third party SIP library (pjsip) <br>* Session - enables the SIP session management features <br>* Registrar - enables the SIP registrar features <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">For example: <br>{code} <br>DefaultSIP.SIP.Modules=Session Registrar Logging <br>{code} <br> <br></td></tr>
<tr><td class="diff-unchanged" >>>> <<< <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br>h5. StateReplicatorListener <br></td></tr>
<tr><td class="diff-changed-lines" >Yes or No value to determine whether the SIP Session <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Manager</span> <span class="diff-added-words"style="background-color: #dfd;">Gateway</span> should have state information pushed to it from a SIP state replicator. You can think of this option as answering the question "Should I run as a backup for another SIP Session <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Manager?"</span> <span class="diff-added-words"style="background-color: #dfd;">Gateway?"</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>The property defaults to "No." <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Future Changes: Currently, this option only controls whether the SIP Session <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Manager</span> <span class="diff-added-words"style="background-color: #dfd;">Gateway</span> listens for state information. There is nothing in place to prevent SIP traffic from being directed to the SIP Session <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Manager</span> <span class="diff-added-words"style="background-color: #dfd;">Gateway</span> if it is running as a listener. There are likely other measures that need to be taken when running as a listener to ensure that nothing unusual occurs. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h5. StateReplicatorName <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This page is highly outdated. Edits in progress.</td></tr></table></div>
<h1><a name="SIPSessionGatewayConfiguration-Overview"></a>Overview</h1>
<p>Configuration of the SIP Session Gateway component is done through configuration interfaces consistent with the Asterisk SCF <a href="/wiki/display/TOP/Configuration+Pattern" title="Configuration Pattern">Configuration Pattern</a>. The Slice definitions for SIP configuration groups and items can be found in <tt>sip/slice/AsteriskSCF/Configuration/SIPSessionManager/SIPConfigurationIf.ice</tt>. Deployment architects can develop their own mechanism for pushing configuration to a SIP component instance or they may use the provided Python configuration script, <tt>SIPConfigurator.py</tt>, found in the <tt>sip/config</tt> directory. </p>
<p>In addition to the SIP component configuration, there are a few SIP Session Gateway specific icebox configuration item</p>
<h2><a name="SIPSessionGatewayConfiguration-SIPConfigurator.py"></a>SIPConfigurator.py</h2>
<p>Similar to other example Python configuration script tools in Asterisk SCF, SIPConfigurator.py reads configuration from a text file and initializes structures defined in Slice and invokes on an Ice object that supports the configuration interface. The format of the text file is similar to the "INI" file format. Configuration items are typically separated into INI sections and have "type" field that holds a string value that the configuration script uses to determine the type of configuration item to create and populate with the contents of the section. The full details of how configurator.py scripts are described in <a href="/wiki/display/TOP/Configurator+Python+Module" title="Configurator Python Module">Configurator Python Module</a>. </p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Unless an alternate configuration mechanism is being used, <tt>SIPConfigurator.py</tt> is one of the four key elements that need to be modified to support new configuration items. The other three are the SIPConfigurationIf.ice Slice file, the <tt>AsteriskSCF::System::Component::V1::Configuration</tt> object implementation in SIPConfiguration.cpp and, of course, the SIP component code.</td></tr></table></div>
<h2><a name="SIPSessionGatewayConfiguration-IceBoxconfiguration"></a>IceBox configuration</h2>
<p>The SIP Session Gateway has only one component specific Icebox configuration item: <em>ServiceName</em><tt>.SIP.Modules</tt>. The property is a space delimited list with the following as valid non-mutually-exclusive values:</p>
<ul>
<li>Logging - enables logging in the third party SIP library (pjsip)</li>
<li>Session - enables the SIP session management features</li>
<li>Registrar - enables the SIP registrar features</li>
</ul>
<p>For example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">DefaultSIP.SIP.Modules=Session Registrar Logging</pre>
</div></div>
<p>>>> <<< </p>
<p>SIP parameters are configured using Ice properties read from a configuration file. As such, the terms "property" and "option" are used interchangeably on this page. The general mechanism for specifying options is using the scheme</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.Category.SubCategory.OptionName = OptionValue</pre>
</div></div>
<p>Some properties do not have a category or subcategory, and so they can be left out entirely:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.OptionName = OptionValue</pre>
</div></div>
<p>For properties that accept a sequence of values, values may be separated by whitespace, commas, or a combination thereof. Any of the following are valid:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.OptionName = Value1 Value2 Value3
Sip.OptionName = Value1,Value2,Value3
Sip.OptionName = Value1, Value2, Value3</pre>
</div></div>
<p>At the time of this writing, peroperty names and values are <b>CASE SENSITIVE</b> so please be aware of this!</p>
<h2><a name="SIPSessionGatewayConfiguration-GlobalOptions"></a>Global Options</h2>
<h3><a name="SIPSessionGatewayConfiguration-GeneralOptions"></a>General Options</h3>
<p>"General" options are those that apply globally to all SIP services as well as options that potentially effect the global behavior of PJSIP. These options all take the form "Sip.OptionName = OptionValue" .</p>
<h5><a name="SIPSessionGatewayConfiguration-Modules"></a>Modules</h5>
<p>A sequence of the names of the PJSIP modules to load on startup.</p>
<p>Currently defined modules are:<br/>
Session: Responsible for incoming and outgoing media sessions.<br/>
Logging: Responsible for printing all incoming and outgoing SIP messages to the logger. These messages are written at the Debug level. The name "Logger" is also accepted for this module.</p>
<p>Possible future modules include:<br/>
Registrar: Responsible for handling incoming registrations and managing the lifetime of registrations<br/>
Subscriber: Responsible for outgoing subscriptions. This may be broken out into separate modules for different event types.<br/>
Notifier: Responsible for sending outgoing notifications. This may be broken out into separate modules for different event types.<br/>
Event State Compositor: Responsible for handling incoming publications. This may be broken out into separate modules for different event types.<br/>
Event Publication Agent: Responsible for sending outgoing publications. This may be broken out into separate modules for different event types.<br/>
Messager: Responsible for incoming and outgoing non session-oriented communications, such as instant messaging and other chat services.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.Modules = Session Logging</pre>
</div></div>
<h5><a name="SIPSessionGatewayConfiguration-StateReplicatorListener"></a>StateReplicatorListener</h5>
<p>Yes or No value to determine whether the SIP Session Gateway should have state information pushed to it from a SIP state replicator. You can think of this option as answering the question "Should I run as a backup for another SIP Session Gateway?"</p>
<p>The property defaults to "No."</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.StateReplicatorListener = Yes</pre>
</div></div>
<p>Future Changes: Currently, this option only controls whether the SIP Session Gateway listens for state information. There is nothing in place to prevent SIP traffic from being directed to the SIP Session Gateway if it is running as a listener. There are likely other measures that need to be taken when running as a listener to ensure that nothing unusual occurs.</p>
<h5><a name="SIPSessionGatewayConfiguration-StateReplicatorName"></a>StateReplicatorName</h5>
<p>The name of the Sip State Replicator to send state information to or receive state information from. In some clusters, there may be multiple instances of Sip Session Managers running at the same time. By controlling which state replicators to send data to and receive data from, you can control exactly which SIP Session Managers are paired with each other for failover purposes. Do not confuse this option with the SIP State Replicator option, SipStateReplicator.Name.</p>
<p>The property defaults to the string "default" .</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.StateReplicatorName = AtlantaReplicator</pre>
</div></div>
<p>Future Expansion: This option currently only supports a single name. It may be worthwhile to change this to take a sequence of names so that state can be replicated to multiple SIP State Replicators.</p>
<h5><a name="SIPSessionGatewayConfiguration-RoutingId"></a>RoutingId</h5>
<p>When registering with the Routing Service, use this as an identifier. This is useful when running multiple SIP Session Managers who are responsible for managing specific sets of endpoints. This ensures the Routing Service will start sessions using the appropriate Sip Session Manager.</p>
<p>The property defaults to the string "pjsip" .</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.RoutingId = AtlantaEndpoints</pre>
</div></div>
<p>Future Changes: The name RoutingId is the current name because this identifier is only passed to the routing service. It seems likely that future services may wish to be passed an identifier as well, and so it would make sense for this option to morph into a general-purpose identifier for this specific SIP Session Manager. If that were the case, the name of this option would need to change.</p>
<h5><a name="SIPSessionGatewayConfiguration-Endpoints"></a>Endpoints</h5>
<p>A sequence of the names of Endpoints serviced by this SIP Session Manager. More specific information about the endpoints is configured in the Endpoint options, as specified below.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.Endpoints = 1000 2000 3000</pre>
</div></div>
<h3><a name="SIPSessionGatewayConfiguration-GlobalTransportOptions"></a>Global Transport Options</h3>
<p>Transport options for the Sip Session Manager. Currently, we only bind using UDP as our transport mechanism. Future options will include adding TCP and TLS bind addresses, plus TLS certificate information.</p>
<p>This is an interesting area because PJSIP currently does not allow for binding to an IPv6 address when using TCP or TLS as the transport. This needs to be corrected ASAP.</p>
<h5><a name="SIPSessionGatewayConfiguration-UdpBindAddr"></a>UdpBindAddr</h5>
<p>The address and port to bind to for UDP transport. This may be an IPv4 or IPv6 address.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.Transport.UdpBindAddr = [::]:5060</pre>
</div></div>
<p>Future Changes: This really needs to accept a sequence of values instead of a single value, and it needs to happen sooner rather than later.</p>
<h2><a name="SIPSessionGatewayConfiguration-EndpointOptions"></a>Endpoint Options</h2>
<p>Endpoint options are configured by using the prefix "Sip.Endpoint" then the endpoint name, then the endpoint subcategory, then the option name. For instance, if you had an endpoint called 1000, then you could specify that Asterisk SCF is only capable of starting outbound sessions with the endpoint with the following notation:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.Endpoint.1000.Session.CallDirection = Outbound</pre>
</div></div>
<p>Options specified for endpoints that are not listed in the Sip.Endpoints property will be ignored.</p>
<h3><a name="SIPSessionGatewayConfiguration-EndpointTransportOptions"></a>Endpoint Transport Options</h3>
<p>These are options pertaining to transportation of SIP messages, independent of the nature of the overarching SIP dialog type.</p>
<h5><a name="SIPSessionGatewayConfiguration-Address"></a>Address</h5>
<p>The IP address of the SIP endpoint in question. This may be an IPv4 or IPv6 address.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.Endpoint.1000.Transport.Address = 2001:fd8::1
Sip.Endpoint.2000.Transport.Address = 192.168.100.20</pre>
</div></div>
<p>Future Changes: Allow for hostnames to be specified. Also allow for an Asterisk-like "dynamic" option to indicate that the endpoint will register with us.</p>
<h3><a name="SIPSessionGatewayConfiguration-EndpointSessionOptions"></a>Endpoint Session Options</h3>
<h5><a name="SIPSessionGatewayConfiguration-CallDirection"></a>CallDirection</h5>
<p>Specifies the direction that calls to/from this endpoint can be made. The direction is given from the perspective of the SIP Session Manager, not the endpoint. So "Inbound" would indicate that calls may only come into the SIP Session Manager from the endpoint. Valid values are "None," "Inbound," "Outbound," and "Both."</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Example</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false">Sip.Endpoint.1000.Session.CallDirection = Both</pre>
</div></div>
<p>Future Changes: This property likely needs a new name since we are trying as hard as possible to not use telephony-specific terms in Asterisk SCF. A good change would be to just call the option "Direction" since it is already part of the Session subcategory.</p>
<h3><a name="SIPSessionGatewayConfiguration-EndpointAuthorizationOptions"></a>Endpoint Authorization Options</h3>
<p>None Yet!</p>
<h3><a name="SIPSessionGatewayConfiguration-EndpointRegistrationOptions"></a>Endpoint Registration Options</h3>
<p>None Yet!</p>
<h3><a name="SIPSessionGatewayConfiguration-EndpointMediaOptions"></a>Endpoint Media Options</h3>
<p>None Yet!</p>
<h3><a name="SIPSessionGatewayConfiguration-EndpointSubscriptionOptions"></a>Endpoint Subscription Options</h3>
<p>None Yet!</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=TOP">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/SIP+Session+Gateway+Configuration">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=6979697&revisedVersion=12&originalVersion=11">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/SIP+Session+Gateway+Configuration?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>