Common Configuration (SIP)

Overview

Some Application instances contain SIP functionality based on the SipApp base class. In addition to the common Application configuration parameters and their application-specific attributes, these SIP Applications typically require SIP configuration as indicated below.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="(name)" module="(module)">
      <include><lib>/path/to/library</lib></include>
      <parameters>
        <!-- application-specific parameters -->
        ...
        <!-- SIP application parameters -->
        <parameter name="sip_bind_host" value="0.0.0.0"/>
        <parameter name="sip_bind_port" value="5060"/>
        ...
        <!-- SDP and RTP integration -->
        <parameter name="early_media_policy" value="never"/>
      </parameters>

      <!-- SIP extended configuration -->
      <config>
        <!-- INVITE headers -->
        <invite_headers>
          <invite_header name="Diversion"                         request_edr="DVT"     response_edr="DVT2"   relay_request="yes"/>
          <invite_header name="Remote-Party-ID"                                                               relay_request="yes"/>
          <invite_header name="Ring-Timer"                                                                    relay_response="yes"/>
        </invite_headers>

        <!-- Outbound -->
        <sip_peers>
          <sip_peer id="LOCAL-IVR"  sip_host="192.168.1.5" sip_port="5060"/>
          <sip_peer id="LOCAL-MSS1"  sip_host="192.168.1.6" sip_port="5060"/>
          <sip_peer id="LOCAL-MSS2"  sip_host="192.168.1.7" sip_port="5060"/>
          <sip_peer id="REMOTE-MSS" sip_host="1.2.3.4" sip_port="5060"/>
        </sip_peers>
        <sip_peer_groups>
          <sip_peer_group name="MSS-GROUP">
            <sip_peer id="LOCAL-MSS1" priority="2"/>
            <sip_peer id="LOCAL-MSS2" priority="2"/>
            <sip_peer id="REMOTE-MSS" priority="1"/>
          </sip_peer_group>
        </sip_peer_groups>
        <trunks>
          <trunk sip_peer_id="LOCAL-IVR" leading="999" />
          <trunk sip_peer_group="MSS-GROUP"/>
        </trunks>

        <!-- Inbound -->
        <sip_accounts>
          <sip_account id="LP1" username="665566" password="ABC" from_user_prefix="+9111421451"/>
          <sip_account id="IVR" username="+911142145100@192.168.1.5" password="Aclmob#1" from_user="665566"/>
        </sip_accounts>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

These SIP parameters include both server-relevant (inbound) and client-relevant (outbound) configuration parameters.

Not all parameters are relevant to all SIP applications.

Configuration Details

The application element attributes for all SIP Application instances are as below.

SIP INVITE Headers

Each SIP INVITE Header definition in this section defines an additional “known” SIP INVITE Header which will be given additional handling for inbound/outbound SIP INVITE requests and responses.

The base SIP App provides base support for the mandatory, base headers such as From, To, Via, Requires, CSeq etc. as documented in this technical guide and the Protocol Conformance Statement documentation. Those base headers already have special treatment built into the system, and hence do not need to be (and must not be) configured in this section. The complete list of special headers which may not be configured here is:

• Via
• From
• To
• Call-ID
• CSeq
• Contact
• Authorization
• WWW-Authenticate
• Content-Type
• Content-Length
• Allow
• User-Agent
• Require
• Supported
• RSeq
• Privacy
• P-Asserted-Identity
• P-Preferred-Identity
• P-Charging-Vector
• Route
• Record-Route

Specifically, when handling inbound SIP INVITE, for headers whose name (case-insensitive) matches a header from the SIP INVITE Header configuration.

• The Header will (if configured) be logged to the IN-ALEG-INVITE EDR.
• The Header will (if configured) be automatically confirmed back in any 2XX Response.
• The Header will (if configured) be automatically confirmed back in any 300-699 Response.
• The Header will (if configured) be automatically relayed in any outbound B-Leg INVITE for this call and will (if configured) be logged to the OUT-BLEG-INVITE EDR.
• The Header will (if configured) be automatically relayed in any outbound A-Leg/B-Leg re-INVITE for this call and will (if configured) be logged to the OUT-ALEG-INVITE/OUT-BLEG-INVITE EDR.

Specifically, when the service logic expressly adds one of these additional known SIP INVITE Headers to an outbound SIP A-Leg INVITE:

• The Header will (if configured) be logged to the OUT-ALEG-INVITE EDR.
• The Header will (if configured) be automatically relayed in any outbound B-Leg INVITE for this call and will (if configured) be logged to the OUT-BLEG-INVITE EDR.
• The Header will (if configured) be automatically relayed in any outbound A-Leg/B-Leg re-INVITE for this call and will (if configured) be logged to the OUT-ALEG-INVITE/OUT-BLEG-INVITE EDR.

Specifically, when the service logic expressly adds one of these additional known SIP INVITE Headers to an outbound SIP B-Leg INVITE:

• The Header will (if configured) be logged to the OUT-BLEG-INVITE EDR.

Each invite_header Object in the config.invite_headers Array is configured as follows.

Note that:

• Any inbound INVITE header listed here will be silently ignored when received on the initial A-Leg INVITE. It will not be passed to the service logic and will not be logged to any EDR
• The service logic (when generating an outbound SIP INVITE for the A-Leg or B-Leg) may add headers over and above the headers expressly defined here. However, those additional headers will not be logged to the base SIP EDRs, and will not automatically be relayed as headers in any other A-Leg or B-Leg set-up such as re-INVITE.
• All automatic relay/confirmation/provision of the headers configured here will treat the header value as opaque, and will never attempt to parse or modify it.

SIP Transport Policies

SIP transport policies control the outbound transport protocol selected for requests that may create a dialog (INVITE) or new requests within an existing dialog (e.g. re-INVITE or BYE).

SIP Peers may specify which transport policy to use. If no policy is specified:

• If configured, the default transport policy will apply.
• Otherwise, the default transport policy values will apply.

An example transport policy definition might be:

        <transport_policies>
          <policy name="policy1"
                  inbound_invite_tcp_reuse="always"
                  ignore_drt_transport="yes"
                  protocol_preference="udp,tcp"/>
        </transport_policies>

Each policy Object in the config.transport_policies Object is configured as follows.

All attributes of SIP transport policies may be N2SVCD evaluated parameters.

Peer Protocol Availability

Some protocols may not be available for use regardless of transport policy configuration:

• If SIP peer configuration prevents protocol selection (e.g. peer tcp_connect is false and dialog remote target specifies tcp), the selected transport policy will continue to be parsed for an applicable protocol.
• When link status checks are in use:
  • TCP and UDP connections to peers are individually considered available if the last status check on that transport succeeded.
  • When a link status check indicates that a particular protocol is not available for a given SIP peer, that protocol will not be used in messages to that peer regardless of all other circumstances until a successful status check has been made.
• When link status checks are not in use:
  • UDP is always considered to be available.
  • TCP is considered to be available if a TCP connection has been successfully established.

New Dialog Transport Policy Use

At runtime, the following procedure is used to select the transport to be used for a new outbound dialog:

1. Determine the SIP peer to use via inbound REGISTER or SIP trunks (and possibly SIP peer groups).
2. For each protocol in the peer transport policy’s protocol_preference (or default if not defined or a dyanmic peer), use that protocol if the protocol is considered available.

In-Dialog Transport Policy Use

At runtime, the following procedure is used to select the transport policy to be used for a new outbound transaction within an existing dialog:

1. Preferentially by matching dialog remote target details to configured SIP peers -> the SIP peer transport policy (or default values if not defined or complete) is used.
2. Otherwise, the default transport policy values are used.

Transport policy values are applied in this order:

1. TCP connection reuse -> existing TCP connection only; no route determination
2. Dialog remote target transport -> restrict to specified protocol only for finding route
3. Find route in (possibly restricted) protocol preference order.

Default Transport Policy Values

If no peer-defined transport policy applies and no default transport policy name is configured, default values will be used whenever a transport policy is required. These default values are:

• inbound_invite_tcp_reuse: never
• ignore_drt_transport: true
• protocol_preference: tcp,udp

SIP Peers

Each SIP Peer definition defines an endpoint which is “known” for the purposes of initiating a new outbound (client) SIP Transaction. Specifically:

• A peer may contain one or more endpoints. We send REGISTER and INVITE.
• A peer may terminate one or more trunks. We send INVITE without registration.
• A peer has credentials which may be used if a sent Request receives a 401 Unauthorized Response.

Each sip_peer Object in the config.sip_peers Array is configured as follows.

All attributes of SIP peers may be N2SVCD evaluated parameters.

Note that the combination of resolved sip_host and sip_port must be unique for each protocol.

SIP Peer Groups

Each SIP peer group definition specifies a collection of one or more SIP peers, along with a priority determining preferred peer usage.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="<name>" module="<module>">
      ...
      <config>
        ...
        <sip_peer_groups>
          <sip_peer_group name="MSS-GROUP">
            <sip_peer id="LOCAL-MSS1" priority="2"/>
            <sip_peer id="LOCAL-MSS2" priority="2"/>
            <sip_peer id="REMOTE-MSS" priority="1"/>
          </sip_peer_group>
        </sip_peer_groups>
        ...
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

SIP peer groups may be used within SIP trunk definitions to allow preferential routing of trunks.

Each sip_peer_group object in the config.sip_peer_groups array is configured as follows.

Note that:

• SIP peers may appear in multiple SIP peer groups.
• A SIP peer group must have one or more SIP peers.
• A SIP peer may only appear once in a SIP peer group.
• SIP peers with the same priority in a group will have traffic loadshared amongst themselves at the same priority.

SIP Trunks

Each Trunk specifies a number block which is statically configured for sending the outbound INVITE transaction which attempts to create a new dialog for a call leg.

These addresses do not use REGISTER. They are assumed to be always available for INVITE.

When routing INVITE messages, all matching trunks are selected for use, in order of:

• Matching leading characters, longest first, then
• If a SIP peer group is defined, by peer priority in that group.

Each trunk Object in the config.trunks Array is configured as follows.

Note that in-Dialog client transactions (for re-INVITE, BYE, or 2XX ACK) do not use this SIP Trunks configuration. They will instead search directly for an available entry in the SIP Peers configuration where the SIP Peer host, port, and protocol match the dialog target as defined by the Contact headers supplied to us within the dialog.

SIP Endpoints

Each Endpoint specifies a called party number which this application “dynamically manages”, meaning that the nominated SIP Peer will be sent REGISTER events informing it of local availability to receive inbound requests related to that endpoint.

Each endpoint Object in the config.endpoints Array is configured as follows.

SIP Accounts

Each SIP Account definition defines an account identity which is recognised for inbound request processing. Account membership is determined by simple exact or prefix match of the offered From address URI.

Specifically, when authorization is enabled:

• An account has credentials which are verified by sending 401 Unauthorized.
• If no account is matched, the response will be 404 Not Found.

Note that if sip_auth_schema is configured to be open then SIP Account checking is completely bypassed for all inbound requests, and the sip_accounts configuration is irrelevant.

Otherwise, this access challenge is applied to all inbound SIP Requests, excepting that:

• SIP CANCEL is never challenged.
• SIP BYE is challenged by default, but this may be disabled with sip_open_bye.
• SIP OPTIONS is challenged by default, but this may be disabled with sip_open_options.
• Challenges may be bypassed for requests recevied on TCP connections associated with known SIP Peers.

Each sip_account Object in the config.sip_accounts Array is configured as follows.

Trace Trap Entry

Each Trace Trap defines a rule for potentially enabling tracing for inbound or outbound calls.

Each trace_trap Object is configured as follows: