Creating and editing routing rules for SIP-based messaging

Add or edit routing rules that define how the IBM® Sametime® SIP Proxy/Registrar routes SIP-based messages.

About this task

Routing rules tell Sametime where to direct SIP-based messages under certain conditions. The rule consists of one or more conditions, and a destination (SIP endpoint) where call requests that meet the conditions are routed.

A routing rule uses the same transport protocol as the Sametime Media Manager. For example, if the Media Manager is configured to use TLS for the SIP signalling, you must use TLS for all routing rules. The supported transport protocols are TCP and TLS over TCP. UDP is not supported.

Procedure

Use the routing rules table in the Proxy Administration page to view, create, or edit rules.
  1. On the Sametime System Console, log in to the Integrated Solutions Console as the IBM WebSphere® administrator.
  2. In the navigation tree, click Sametime System Console > Sametime Servers > SIP Proxies and Registrars.
  3. On the SIP page, look in the proxies table and click the Deployment Identifier of the SIP Proxy/Registrar.
  4. On the SIP Proxies and Registrars page, click Proxy Administration.
  5. In the routing rules table, do one of the following:
    • Click the name of a rule to edit it.
    • Click New to create a new rule.
  6. Add or modify settings for the routing rule as follows:
    1. Type a name and description of the route in the Name and Description fields.

      It is helpful to indicate the route's direction and endpoint in the name so you can easily distinguish among routes in the routing rules table later.

    2. Use the "Conditions" section to configure the routing rule by defining at least one condition:
      Table 1. Conditions fields and descriptions
      Field Description
      Method A predefined value indicating the type of request: INVITE, INFO, MESSAGE, or ANY. Select the appropriate value from the field's list; if you do not select a method, then all methods are accepted by this condition.
      Source Address The originating caller's IP address, which must match the pattern specified in the regular expression that you provide. You could specify a single IP address: 9\.3\.186\.215 or use an expression to specify a range of IP addresses: 9\.3\.186\.215|9\.3\.186\.216 (Notice that the . is preceded with the escape character \ so it can be interpreted as a period and not the "any character" symbol.)
      Request URI The resource, usually the origin server, on which to apply the request. The URI must match the pattern specified in the regular expression that you provide. For example: .*example\.com.* matches both of these incoming initial requests : sip:example.com:5060;transport=tcp SIP/2.0 and sips:subdomain.example.com:5061 SIP/2.0
      Contact Header The SIP URI of the originating caller. The URI must match the pattern specified in the regular expression that you provide. For example, .*20100@192\.192\.0\.2\.12:506<01>.* matches incoming initial requests with either of these contact header values: <sip:20110@192.0.2.12:5060;transport=tcp> or <sips:user9920100@192.0.2.12:5061;transport=tcp>
    3. In the "Destination" section, select the method to use for storing the address of the destination SIP endpoint:
      Table 2. Destination addressing methods and descriptions
      Field Description
      Push a Route header field Insert the destination address into a Route header field of the outgoing SIP request.
      Replace a Request-URI Replace the original Request-URI with the destination address when creating the outgoing request.
    4. Construct the destination address using the method you selected in substep c.

      Push a Route header field

      Supply a value in one or more of the fields described in the table.

      Table 3. SIP URI addressing fields and descriptions
      Field Value
      Scheme The scheme can be either SIP or SIPS (the secure version of SIP); the default is SIP. This field is required.
      IP/FQDN The IP address or fully qualified host name of the destination server (the SIP endpoint). For incoming calls, use the fully qualified domain name of the Sametime Conference Manager. This field is required.
      Port The port that the destination server (the SIP endpoint) is listening on for SIP-based communications. This field is optional; if you do not provide a value, the server uses the correct port.
      Note: Make sure you specify the correct port for the transport protocol. For unsecured TCP communications, the Sametime Conference Manager typically uses port 5063; for encrypted TLS communications, the Conference Manager typically uses port 5062.
      Transport The network transport protocol to use for sending SIP messages: TCP or TLS over TCP (UDP is not supported). Use the same transport protocol throughout the entire route (from the Sametime client to the Sametime SIP Proxy/Registrar to the third-party SIP endpoint). For example, if the Sametime Media Manager is configured to use TLS for SIP communications, you must use TLS for all routes. This field is optional; if you do not provide a value, the server supplies a transport protocol.

      Replace a Request-URI

      Construct regular expressions to define the original Request-URI pattern and its replacement Output pattern, which are explained in the table.

      Table 4. URI pattern fields and descriptions
      Field Description
      Request-URI pattern A regular expression defining the pattern of the original Request URI. Use this field to extract fields or parameters from a Request-URI of a SIP request. A variable stores the part of the Request-URI matched by the part of the regular expression inside the parentheses, indicated by a number. The variables are recalled with the dollar-sign, for example, $1, $2, and so on. These fields or parameters can be used to build the Output pattern. This field is optional.
      Output pattern A regular expression defining the pattern of the destination's URI (address). This field can contain either a SIP URI or a replacement expression with variables for example, $1, $2, and so on. Variables store the portion of a parenthesized pattern captured from the Request-URI pattern field. After processing any captured variables, the resulting field value must be a valid SIP or SIPS URI.
      Note: If you do not provide a value in the Request-URI pattern field , this field must contain a valid SIP or SIPS URI.
      Remember: Regular expressions must follow a strict notation, different from other notation forms you may use. For example, the operating system shell notation for a wild card (series of 0 or more characters) is the asterisk character: *, The regular expression equivalent for a wild card is different: it is a combination of a dot followed by an asterisk, as follows: .*

      Before adding the regular expression to the routing rule, you should test the expressions using any of the testing engines available online. To learn more about creating regular expressions, see the Java™ Regular Expressions class on the Oracle web site.

    5. Click OK to save the rule.
    6. Repeat this procedure starting with step 5 until all of your routing rules are defined.

      You must create at least one inbound route and one outbound route between Sametime and each third-party SIP endpoint. You can create different versions of a route using different sets of conditions (all of a route's conditions must be satisfied for that route to be selected), and you can prioritize routing rules as explained in the next step.

  7. Prioritize the routing rules by arranging them in the sequence in which you want them processed:

    If a message does not satisfy all of the routing conditions, the route is ignored. Therefore, the sequence can contain a mix of inbound routes and outbound routes.

    1. In the routing rules table, select a route and click the Move Up button or the Move Down button until the route is positioned in the correct sequence.
    2. Repeat step 7.a as needed until the rules are in priority sequence.
  8. Save the set of routing rules and priorities by clicking the Save link in the "Messages" box at the beginning of the page.
  9. Restart the Sametime SIP Proxy/Registrar's server or cluster:
    • For a stand-alone Sametime Media Manager or SIP Proxy/Registrar, restart the server now as follows:
      1. In the server's Integrated Solutions Console, click Servers > Server Types > server_type.
      2. In the list of servers, select your server and click the Restart.
      3. Click Refresh and verify that all components are active.
    • For a cluster of Sametime SIP Proxy/Registrars, synchronize the nodes before restarting them:
      1. In the Deployment Manager's Integrated Solutions Console, click System Administration > Nodes.
      2. Select all nodes in the cluster, and then click the Full Resynchronize button at the beginning of the table.
      3. In the navigation tree, click System Administration > Node agents.
      4. Select all nodes in the cluster, and then click the Restart button at the beginning of the table.

Example

The following examples show different combinations of values for Request-URI pattern and Output pattern that produce specific destination addresses.

  • Route all incoming SIP requests to this destination: sip:example.com;transport=tcp

    Request-URI pattern: empty

    Output pattern: sip:example.com;transport=tcp

    Because the Request-URI pattern field is empty, the destination is modified on all incoming requests.

  • Route incoming SIP requests to a new host, keeping the original user name

    Request-URI pattern: sip:(.+)@.*

    Output pattern: sip:$1@example.com

    The expression in parentheses for Request-URI pattern captures the user name in a variable and the output pattern refers to the variable as $1.

    For example, assume an incoming initial SIP request with a Request-URI of sip:12345@company.com. The Request-URI pattern runs, resulting in the variable $1=12345. The SIP URI for the destination address maintains the same user name, but adds a new host name: sip:12345@example.com.

  • Route incoming SIP requests to "host," keeping the original user name if the user-name prefix in the Request-URI is "45"

    Request-URI pattern: sip:(45.+)@.*

    Output pattern: sip:$1@host

  • Route incoming SIP requests to "host," omitting the prefix if the user-name prefix in the Request-URI is "45"

    Request-URI pattern: sip:45(.+)@.*

    Output pattern: sip:$1@host