Chapter 14 Configuring the SIP Service

The SIP service is the component of the Communications Server that provides facilities for deploying SIP applications and for making deployed SIP applications accessible by SIP clients

Unlike the HTTP service, the SIP service does not use virtual servers.

SIP Service

You can change the following attributes of SIP service through the Admin Console, or by using the asadmin get and set commands. The SIP service attributes apply to all the listeners in the SIP service.

The sub-elements of the SIP service are the Access Log, Request Processing, Keep-Alive, SIP protocol, SIP listeners, and Connection Pool.

To edit SIP service sub-elements and their attributes through the Admin Console, click Configuration > config-name > SIP Service.

To list all the sub-elements of the SIP service, you can use the following command:

list server-config.sip-service.*

Typical output is as follows:

server-config.sip-service.access-log
server-config.sip-service.connection-pool
server-config.sip-service.keep-alive
server-config.sip-service.request-processing
server-config.sip-service.sip-listener.sip-listener-1
server-config.sip-service.sip-listener.sip-listener-2
server-config.sip-service.sip-listener.sip-listener-2.ssl
server-config.sip-service.sip-listener.sip-listener-3
server-config.sip-service.sip-protocol
server-config.sip-service.sip-protocol.sip-link
server-config.sip-service.sip-protocol.sip-timers

Setting the SIP Service Access Log Attributes

You can enable and configure rotation for the access logs for the SIP service. These logs are in the as-install/domains/domain_dir/logs/sipaccess directory and are named as follows: sip_access_log.yyyy-mm-dd. This location can be changed by editing the accesslog property under the sip-service element.

The accessLoggingEnabled property under sip-service is used for enabling SIP access log. Restart the server after enabling or disabling the access log. Use the following command:

asadmin set config.sip-service.property.accessLoggingEnabled=true

The accesslogsize property under sip-service can be used for log rotation based on file size. The default value of this property if set to 2000000.

The following is the list of SIP service access log attributes (The actual attribute name as defined in the domain.xml file appears in brackets)

• Rotation (rotation-enabled): Check the File Rotation box to enable file rotation.

• Rotation Policy (rotation-policy): Choose a policy from the Rotation Policy drop-down list. (The only policy available is time).

• Rotation Interval (rotation-interval-in-minutes): Enter a numeric value to specify the number of minutes between rotations of the access log. This field is valid only if the Rotation Policy is time. The default is 1440 minutes.

  When you specify a rotation-interval, and the rotation interval has elapsed, the access log file will be rotated only if the resulting rotation suffix of the new access log file is different from the rotation suffix of the existing access log file. So, the rotation interval must coincide with the rotation suffix in order to see your access log file rotated within the expected time-frame interval.

• Rotation Suffix (rotation-suffix): Enter a string value to specify the suffix to be added to the log file name after rotation. The default is YYYY-MM-DD.

• Format(format): Enter a string value to specify the format of the access log. Use the formats shown in the following table. The default format is %client.name% %auth-user-name% %datetime% %request% %status% %response.length%.

  The following SIP headers are also supported: client.name,auth-user-name,datetime, request, status, response.length, max.forwards, from, cseq, contact, to, content.type, via, call.id

  To enable all headers, run the following command:

  asadmin set server-config.sip-service.access-log.format="\"%client.name% %auth-user-name% %datetime% %request% %status% %response.length% %max.forwards% %from% %cseq% %contact% %to% %content.type% %via% %call.id%\""

  ---

  Note –

  Ensure that you escape the format string.

  ---

You can edit these properties through the Admin Console or through the following get and set commands

To get the values of all properties of the SIP service access log, use the following command: asadmin get server-config.sip-service.access-log.*

To set an attribute of the SIP service access log, use the set command as follows: asadmin set server-config.sip-service.access-log.rotation-enabled=false

Setting the SIP Service Keep Alive Attributes

You can edit these attributes through the Admin Console or through the following get and set commands

To get the values of all attributes and properties of the SIP service keep-alive, use the following command: asadmin get server-config.sip-service.keep-alive.*

You can set the timeout-in-seconds property of the SIP service keep-alive. By default, this property is set to —1. A value of 0 or less means keep alive connections are kept open indefinitely.

To set an attribute of the SIP service keep-alive, use the set command as follows: asadmin set server-config.sip-service.keep-alive.timeout-in-seconds=0

Setting the SIP Service Connection Pool Attributes

You can edit these attributes through the Admin Console or through the following get and set commands

To get the values of all attributes of the SIP service connection pool, use the following command: asadmin get server-config.sip-service.connection-pool.*

• Queue size(queue-size-in-bytes): Specifies the maximum number of messages that can be queued until threads are available to process them for SIP listeners. The default is —1 and specifies that there is no limit on the number of messages.

• Size of Receive Buffer (receive-buffer-size-in-bytes): Specifies the size of the byte buffer that is used to read from the socket channel. By default, this property is tuned to the socket channel receive buffer size.

• Size of Send Buffer (send-buffer-size-in-bytes): Specifies the maximium size of the SIP message that can be written out. By default, this property is set to 8192.

To set an attribute of the SIP service connection pool, use the set command as follows: asadmin set server-config.sip-service.connection-pool.receive-buffer-size-in-bytes=10

Setting the SIP Service Protocol Attributes

You can edit these attributes through the Admin Console or through the following get and set commands

To get the values of all attributes and properties of the SIP service protocol, use the following command: asadmin get server-config.sip-service.sip-protocol.*

• Enable Error Response (error-response-enabled): Specifies whether an error response is sent or not. Set to false by default.

• Default TCP Transport(default-tcp-transport): If set to true, transport=tcpis inserted in the URI of the contactand record-routeheaders.

To set an attribute of the SIP service protocol, use the set command as follows: asadmin set server-config.sip-service.sip-protocol.default-tcp-transport=false

The SIP Service Protocol has a sub-element called SIP timer. You can list the sub-elements of the SIP service protocol by using the following command: asadmin list server-config.sip-service.access-log.*

To get the values of all attributes and properties of the SIP service timers, use the following command: asadmin get server-config.sip-service.protocol.sip-timers.*

SIP Listeners

You can configure SIP listeners through the Admin Console or through the get and set commands. The server port on which the SIP container listens on can be configured using a SIP listener.

To list all SIP listeners in the default domain, type the following asadmin command:

list server.sip-service.sip-listener.*

Typical output is as follows:

server.sip-service.sip-listener.sip-listener-1
server.sip-service.sip-listener.sip-listener-2
server.sip-service.sip-listener.sip-listener-2.ssl

By default, a domain has two SIP listeners created: sip-listener-1 and sip-listener-2, representing the SIP and SIPS ports, respectively. By default, sip-listener-2 is configured to use TLS transport.

To list all attributes of sip-listener-1 in the default domain, type the following asadmin command:

get server.sip-service.sip-listener.sip-listener-1.*

Typical output is as follows:

server.sip-service.sip-listener.sip-listener-1.address = 0.0.0.0
server.sip-service.sip-listener.sip-listener-1.enabled = true
server.sip-service.sip-listener.sip-listener-1.external-sip-address =
server.sip-service.sip-listener.sip-listener-1.external-sip-port =
server.sip-service.sip-listener.sip-listener-1.id = sip-listener-1
server.sip-service.sip-listener.sip-listener-1.port = 5060
server.sip-service.sip-listener.sip-listener-1.transport = udp_tcp
server.sip-service.sip-listener.sip-listener-1.type = default

By default, the port is set to 5060 and the address to 0.0.0.0. The 0.0.0.0 address is what we call a BIND to ANY address and which allows you to bind the server socket to any network interface on your system.

To change the default port of sip-listener-1, use the following command:

set server.sip-service.sip-listener.sip-listener-1.port=5065

Communications Server provides the flexibility of changing the SIP listener at runtime. Currently, Communications Server does not consider the effects of those change. It is recommended that you plan ahead of time when you change SIP listener settings.

Creating and Editing a SIP Listener

To create a SIP listener, in the Admin Console, expand the Configuration node, select the configuration you want to configure, then select SIP service, then the SIP Listeners node, and click New. Define the SIP listener settings and click Save.

Alternatively, you can use the asadmin create-sip-listener command. A sample command is as follows:

asadmin create-sip-listener --siplisteneraddress=127.0.0.1 --siplistenerport=5066 --transport=udp_tcp mysiplistener

The following is a list of SIP listener attributes:

• Name (id): Provide a unique identifier for your new listener.

• Network Address (address): Enter 0.0.0.0 if you want the listener to listen on all IP addresses for the server, using a unique port value. Otherwise, type a valid IP address for the server.

• Listener Port (port): Enter a unique port value if the Network Address field is 0.0.0.0, or the desired port value if you are using another IP address.

• Enabled (enabled): Determines whether the listener is active. If set to false, any attempts to connect to the listener result in a socket exception (java.net.ConnectException).

• Transport (transport): Specifies the type of transport layer protocol. Allowed values are udp_tcp and tls.

• External SIP Port (external-sip-port): Specifies the external SIP port. If specified, this value overrides the value of the external SIP port in the SIP container.

• External SIPS Port (external-sips-port): Specifies the external SIP port. If specified, this value overrides the value of the external SIPS port in the SIP container.

• Transport (transport): Specifies the type of transport layer protocol. Allowed values are udp_tcp and tls.

• Type (type): Valid values for this options are internal, external, and default. If set to internal, this listener will be used only for proxying by the converged load balancer. If set to external, this listener will be used only for SIP user agents. If set to default, the listener will be used by SIP user agents and converged load balancers. By default, the value this option is set to default.

To change an attribute of the SIP listener you can use the asadmin set command or you can use the Admin Console. To edit a SIP listener, in the Admin Console, expand the Configuration node, select the configuration you want to configure, then select SIP service, then the SIP Listeners node, and choose the SIP listener to edit. Edit the SIP listener settings and click Save.

A sample command to change the SIP port of a SIP listener is: asadmin set server.sip-service.sip-listener.sip-listener-1.port=5065

To Configure a SIP Listener to Use SSL

1. In the Developer profile, expand the Configuration, SIP service, then SIP Listeners node.

2. In the Clusters and Enterprise profile, expand the Configuration node, select the configuration you want to configure, then select SIP service, then the SIP Listeners node.

3. Select the SIP Listener you want to configure.

4. Select the SSL tab to configure the listener to use SSL as follows:

   • Client Authentication: Check this field to force clients to authenticate themselves to the server when using this listener.

   • Certificate NickName: Enter the name of an existing server key pair and certificate. See the Security chapter for more information.

   • SSL3, SSL2, TLS: Check the Enabled checkbox to enable security protocol(s) on the listener. Check either SSL3, SSL2 or TLS, or all three.

   • Cipherssuites: Select the available cipher suite used by the protocol(s) and select the Add button. To enable all cipher suites, select the Add All button.

5. Click Save.

Equivalent asadmin command

create-ssl