ibm sametime 8.5.2 unified telephony lite client...
TRANSCRIPT
IBM Sametime 8.5.2 Unified Telephony Lite Clienttroubleshooting guide
Mark Wallace ([email protected]), IBM
November 2012
© Copyright International Business Machines Corporation 2012. All rights reserved.
Summary: This guide is an aid to troubleshooting an IBM Sametime Unified Telephony Lite Client deployment. It includes information on how to diagnose common problems, starting with product activation and going through to making and receiving calls.
Table of Contents1 Overview...................................................................................................................................2
1.1 Reference system..............................................................................................................21.2 Deploying a proof-of-concept system.................................................................................21.3 Terminology.......................................................................................................................3
2 Enabling the SUT Lite Client.....................................................................................................32.1 Activating the product license.............................................................................................32.2 Enabling product features..................................................................................................62.3 Enabling Client Policy........................................................................................................6
3 Creating routing rules................................................................................................................73.1 Name and description........................................................................................................73.2 Conditions..........................................................................................................................73.3 Destination.........................................................................................................................93.4 Identifying trunk versus client SIP messages...................................................................10
4 Outbound calls.........................................................................................................................114.1 Creating an outbound route..............................................................................................114.2 Sample valid outbound call route.....................................................................................114.3 Common problems with outbound calls...........................................................................13
5 Inbound calls...........................................................................................................................135.1 Creating an inbound route...............................................................................................135.2 Sample valid inbound call route.......................................................................................145.3 Common problems with inbound calls..............................................................................155.4 Correcting an inbound call flow........................................................................................15
6 Other deployment problems....................................................................................................176.1 Configuring a health-check method for WebSphere SIP Proxy........................................176.2 Sametime SIP Proxy responds to initial incoming request with 483 error.........................186.3 Is UDP supported by SUT Lite?.......................................................................................18
7 Appendix A: Collecting diagnostic information.........................................................................198 Appendix B: Working with Wireshark.......................................................................................209 Appendix C: Replacing the existing proxy.xml file....................................................................25
1
10 Conclusion............................................................................................................................2511 Resources.............................................................................................................................2512 Author biography...................................................................................................................26
1 OverviewThe purpose of this guide is to help you troubleshoot an IBM® Sametime® Unified Telephony (SUT) Lite Client deployment. It includes information on how to diagnose common problems, starting with product activation and continuing through making and receiving calls.
This white paper is a companion to the wiki Community Article, “From Zero To Hero: Sametime Unified Telephony Lite Client”. The Zero To Hero guide explains the product features, architecture, and configuration of the SUT Lite Client product and guides you through the deployment process. This guide helps you when things go wrong and is based on our experiences in supporting multiple customer deployments.
1.1 Reference systemThe reference system used in this guide includes a Sametime Community Server and a Sametime Media Manager server in the Sametime 8.5.2 deployment, plus an Asterisk PBX.
The Sametime Media Manager is installed on a single computer that hosts the Session Initiation Protocol (SIP) Proxy/Registrar, Conference Manager, and Packet Switcher components. The Conference Manager has a SIP back-to-back user agent and is responsible for routing calls to and from the Sametime softphone.
The Asterisk PBX is installed on its own computer. It includes its own SIP Registrar that can be used to register external softphones. A SIP trunk is established between the Sametime SIP Proxy/Registrar and the Asterisk PBX, and is used to establish calls between the Sametime softphone and the softphones connected to Asterisk.
1.2 Deploying a proof-of-concept systemWhen deploying an SUT Lite Client proof-of-concept system we recommended the following best practices:
1. Install the Sametime 8.5.2 IFR1 Media Manager and Sametime Connect client. Many improvements have been made in the 8.5.2 IFR1 release in both the server and client.
2. Confirm with IBM that interoperability testing has been completed with the system to which you are trunking. The interoperability test may have identified additional configuration steps and/or hotfixes that are required to get the deployment working.
3. At least initially, disable SIP security (as described in the Zero To Hero guide). This will simplify analyzing the SIP traffic, in the event that are are problems establishing calls, and will also allow IBM Support to review your Wireshark traces.
4. Configure the route for outbound calls (from Sametime softphone) as the first step and get this working, so you can resolve any connectivity issues with your SIP trunk.
2
1.3 TerminologyConference Focus. The Media Manager Conference Focus (CF) acts as a back-to-back user agent (B2BUA) and can be used to handle inbound and outbound calls to the Sametime computer softphone. The CF communicates with the SIP Proxy, initiates the SIP dialog for outbound calls, and is the initial destination for inbound calls.
SDP. Session Description Protocol describes multimedia communication sessions for the purposes of session announcement, session invitation, and parameter negotiation. SDP does not deliver media itself but is used for negotiation between end points of media type, format, and all associated properties. The set of properties and parameters are often called a session profile. SDP is designed to be extensible to support new media types and formats. SIP. This is an IETF-defined signalling protocol widely used for controlling communication sessions such as voice and video calls over Internet Protocol (IP). The protocol can be used for creating, modifying and terminating two-party (unicast) or multiparty (multicast) sessions. Sessions may consist of one or several media streams.
The remaining sections of this paper describe common problems and their solutions, starting with enabling the SUT Lite Client.
2 Enabling the SUT Lite ClientPer the Zero To Hero guide there are three steps required to enable the SUT Lite Client:
1. Activate a special product license2. Enable the SUT Lite Client feature3. Set a new policy to allow SIP trunking calls
2.1 Activating the product licenseRunning the activation process modifies the Media Manager policy portlet to make the SUTLite Client policy visible, allowing you to turn on the feature for your users. You must download the product license kit and run it on the server on which you have the Sametime System Console installed.
Note that the procedure will fail if you run the activation script from the wrong folder, so use these steps to ensure the operation succeeds:
1. On the computer hosting the Sametime System Console, open a browser and download the "IBM SUTLite Client V8.5.2 Multiplatform Multilingual" image from the Passport Advantage web site to a temporary folder.
2. Extract the files and then move the temporary folder into install directory for the Sametime System Console, that is, the same folder in which you find IBM WebSphere®, IBM Installation Manager, and SQLLIB folders. The reason is that the SUTLite activation has some relative paths set and will fail if not in the correct folder, for example:
C:\Program Files\IBM\Installation ManagerSQLLIBWebSphere<License temporary folder>
3
3. The license enablement files are stored in a the SUTLiteClient directory, so open a command prompt and change to that directory, and then run the following command to activate the SUTLite Client license:
Linux®: ./LiteClient.sh path_to_STSCServerCell
Microsoft® Windows®: LiteClient.bat path_to_STSCServerCell
where “path_to_STSCServerCell” is the full path to the "STSCServerCell" (Sametime System Console cell) directory on that computer. For example:
Linux: ./LiteClient.sh /opt/IBM/WebSphere/STSC/STSCServerCell
Windows: LiteClient.bat C:\IBM\WebSphere\STSC\STSCServerCell
After running the activation command, your command line should display a message “Successfully updated the jsp to enable SUT license feature” (see figure 1).
Figure 1. Example success message
4
If you have any other result, then verify that you have the temporary folder in the correct directory. If you have issues with the activation, the easiest way to check whether the install has worked is to open the config.xml file. The file is located in the mediaserveradmin.war which on our system is located here:
C:\Program Files\IBM\WebSphere\AppServer\systemApps\isclite.ear\mediaserveradmin.war\Config.xml
Open the file in an editor, like Notepad, scroll toward the bottom of the file, and you will see the following:
Listing 1. Code if activation succeeded <fieldset> <legend align="left"><h:outputText value="#{productResource.sutLiteHeader}" /></legend> <f:verbatim><br></f:verbatim> <h:panelGrid id="sutLiteSettingsGrid" styleClass="panelGrid" columns="2"> <h:selectBooleanCheckbox styleClass="selectBooleanCheckbox" id="allowSUTLiteCheckBox" value="#{pc_Config.SUTLiteClientEntitled}" /> <h:outputText id="allowSUTLiteLabel" value="#{productResource.allowSUTLiteLabel}" /> <h:outputText value="" /> <h:outputText value="#{productResource.allowSUTLiteNote}" id="allowSUTLiteNote"/> </h:panelGrid> </fieldset>
Listing 2. Code if activation failed<%--SUTLICSECTION <fieldset> <legend align="left"><h:outputText value="#{productResource.sutLiteHeader}" /></legend> <f:verbatim><br></f:verbatim> <h:panelGrid id="sutLiteSettingsGrid" styleClass="panelGrid" columns="2"> <h:selectBooleanCheckbox styleClass="selectBooleanCheckbox" id="allowSUTLiteCheckBox" value="#{pc_Config.SUTLiteClientEntitled}" /> <h:outputText id="allowSUTLiteLabel" value="#{productResource.allowSUTLiteLabel}" /> <h:outputText value="" /> <h:outputText value="#{productResource.allowSUTLiteNote}" id="allowSUTLiteNote"/> </h:panelGrid> </fieldset>SUTLICSECTION--%>
The difference between the two paragraphs of code are the ‘SUTLICSECTION’ tags.
5
2.2 Enabling product featuresGo to the Sametime System Console as shown in figure 2.
Figure 2. Sametime System Console
1. Select Sametime Media Manager and select the deployment Identifier that relates to your Media Manager.
2. When the screen updates, you should see the Media Manager configuration document and at the bottom you should have a new section (see figure 3).
3. Select the check box to enable the SUT Lite capabilities and select OK to apply these changes.
Figure 3. New SUT Lite capabilities section
2.3 Enabling Client Policy1. In the Sametime System Console, under the Manager Policies section, select Manage
Policies.2. Select the tab at the top labelled Media Manager (see figure 4), select the Default Policy,
and click the Edit button.
Figure 4. Media Manager tab
6
3. At the bottom of the configuration you will see the addition of an SIP Trunk capability option (see figure 5). Select the option to allow calls that use SIP Trunk capability and save your changes.
Figure 5. New SIP Trunk capability option
Note that it typically takes a couple of hours for the policy change to take effect.
3 Creating routing rulesThis section contains some general guidance on creating routing rules. For each rule you need to specify the following information:
• Name and Description• Conditions• Destination
3.1 Name and descriptionThese values are straightforward, enter a name that clearly identifies what route is to be used, for example, “Asterisk Outbound SIP” (see figure 6). You can optionally add additional descriptive information; for example, including the phone numbers or SIP URI's that will be handled by this route will be useful later, if you need to add additional routes.
Figure 6. Name and Description window
3.2 ConditionsThe Conditions section is used to match a specific SIP message. Only SIP messages that match this condition are routed to the destination specified in the route. Be careful to match only the specific messages required; conditions that are too greedy and match many messages often have unexpected side effects like routing messages intended for the Sametime softphone out over an SIP trunk.
The routing rules are processed by the SIP Proxy based on the priority set on each rule, and the first match will win. The SIP Proxy is a generic component and, as such, includes functionality that is not used in a SUT Lite deployment.
7
A condition includes the following information (see figure 7):
• Method. This allows the SIP message type to be specified and typically is set to INVITE.
• Source Address. This allows a SIP message to be matched based on where the message originated. This is typically used with inbound call routes where you are creating an inbound SIP trunk from a device, for PBX. The source address is set to the address of that device.
• Request URI. This allows a SIP message to be matched based on the SIP address of the request. It is typically used for outbound call routes where you are creating an outbound route to a device that can handle certain requests, for example calls to numbers beginning with a certain prefix. The Request-URI setting is typically configured with a regular expression, which is executed against the SIP message Request-URI.
• Contact Header. This allows a SIP message to be matched against the contact header field (which contains a SIP URI).
• User defined header. This allows a SIP message to be matched based on a user-defined header; you can specify the header name and then a regular expression that is used to check whether the header value matches the request. The Conference Manager marks messages intended for the Sametime client and messages that are intended for the SIP trunk, and this setting can be used to ensure calls route correctly.
Figure 7. Conditions window
8
3.3 DestinationThe Destination section is used to configure how the message should be routed (see figure 8). There are two main options:
• Push a Route header field. Using this options leaves the Request-URI unmodified and adds a SIP route header that points to the next hop of the SIP route to the final destination. This option is used only for outbound routes in an SUT Lite deployment. The reason we add a route header is to keep the SIP trunk in the SIP flow.
• Replace a Request-URI. Using this option modifies the Request-URI value. This option is typically used for inbound calls because we need to change the SIP address to match the Sametime softphone. It is also may be used for outbound calls where the user dialed a number, which means the Request-URI includes the address of the Conference Focus.
Figure 8. Destination window
There are two options for constructing the SIP URI:
• Using fields. Use this option to build the SIP URI from scratch, specifying the fields used to build up the SIP URI (the scheme, IP address or full qualified domain name, port and transport).
• Using a regular expression. Use this option to derive the SIP URI from the existing SIP-URI, specifying two regular expressions:
◦ Request-URI pattern. Extracts part of the Request-URI, that is, the part of the original request you want to reuse, and is typically used to extract the user-dialed phone number.
◦ Output pattern. Uses input from the execution of the above regular expression to build the SIP URI. Typically you will replace the host name in the SIP URI, but you could also perform some basic number manipulation, like adding a prefix.
9
TIP: Regular expressions are complex to work with and it's easy to make mistakes; fortunately there are some great web-based tools that allow you to test regular expressions, for example, http://regex.powertoy.org/. Use “Java regex syntax (match only)” when testing the regular expression for the Request URI, and use “Java plus replacement (2nd box)” when testing using regular expression for the Destination.
3.4 Identifying trunk versus client SIP messagesThis section applies only if you have a Conference Focus hot fix dated later than 17 May 2012 installed. We recommend you install the latest Conference Focus hot fix when deploying the SUT Lite Client.
Note the following recommendations for SIP Trunking (SUT Lite Client) rules:
• Rules added for outbound INVITES (that is, outbound from the Sametime client to a SIP Trunk) should have the ".*;endpoint=trunk.*" condition added (see figure 9).
Figure 9. ".*;endpoint=trunk.*" condition added
This helps guarantee that the rule will only match an outbound INVITE, for which it was intended. Note that the header value is ".*;endpoint=trunk.*".
• For inbound INVITES (that is, inbound from the SIP Trunk to the Sametime client), if the Source Address is not specified, it is recommended that the "(?!.*;endpoint=client.*).*" condition be added (see figure 10).
Figure 10. "(?!.*;endpoint=client.*).*" condition added
This helps guarantee that the rule will not accidentally match an INVITE sent by the Conference Manager to the client. An inbound INVITE from a SIP Trunk (which is what such a rule is for) is not expected to have ";endpoint=client" in the From field, whereas an INVITE from the Conference Manager to the client may have this ";endpoint=client" string in the From field.
Note that the header value "(?!.*;endpoint=client.*).*" means do not match a From field containing ";endpoint=client". If the Source Address of the SIP Trunk is used in the rule, then this additional condition should not be needed (but will not harm anything if added).
10
4 Outbound callsThis section covers problems that can arise when trying to make outbound calls from the Sametime softphone to an external phone or video device.
The main cause of failures with outbound calls are errors in the outbound route definition. The outbound route determines how the SIP traffic is routed, that is, which SIP trunk is used. However, a badly formed outbound route can also impact other SIP traffic that should not be sent over the SIP trunk, for example, SIP messages intended for the Sametime client.
4.1 Creating an outbound routeWhen creating an outbound route you must first consider what type of dial strings your users will be dialling, typically either dialing phone numbers and/or SIP URI's.
Use the following guide when configuring the route Conditions:
• Set the Method to INVITE as this will be the first message dispatched and will establish the route to be used.
• Set the Request URI to match the SIP URI: ◦ If the user is dialing a phone number, then you need to use a regular expression that
matches some part of the number. You may want to use different SIP trunks for different number ranges (one for internal dialling, local dialling, etc.)
◦ If the user is dialing a SIP URI, then you need to use a regular expression that matches some generic part of the URI, for example, the host name.
Use the following guide when configuring the route Destination:
• Select “Push a Route header field” when creating a route used when the user dials a SIP URI. Typically you can leave SIP URI's unmodified, but you do need to include a route header to make sure the SIP proxy routes the request over the SIP Trunk. If you don't, it will attempt to resolve the host from the Request URI.
• Select “Replace a Request-URI” when creating a route used when the user dials a telephone number or a SIP URI you need to modify. Typically you want to replace the host name in the existing Request-URI.
• Select “Using fields” to construct the SIP URI when you don't need to reuse any data from the original Request-URI. This is typically used in conjunction with the “Push a Route header field” to add the SIP trunk route.
• Select “Using a regular expression” when you want to modify the existing Request-URI e.g. to replace the host name.
4.2 Sample valid outbound call routeFigure 11 shows the Conditions settings used to establish a SIP trunk to Asterisk to dial phone numbers beginning with 1533.
11
Figure 11. Conditions settings
Figure 12 shows the Destination settings to manipulate the Request-URI for the trunk to Asterisk and to replace the Request-URI host with the IP address of the Asterisk server.
Figure 12. Destination settings
12
4.3 Common problems with outbound callsThe three most common problems with outbound calls involve the route; specifically:
• Not having a condition that matches the Request URI. The only way to confirm when this occurs is to analyze the SIP Proxy server logs; however, you can use a regular expression tool (http://regex.powertoy.org/) to test whether the regular expression you have entered will match the Request URI.
• Conditions that match to many messages, for example, setting the Request URI to “sip:*” because you want to use this trunk for all calls. The problem with doing this is that it will also match messages that are intended to go to the Sametime client. A hot fix is available that provides a mechanism to identify trunk versus client messages as explained above in Section 3.4, “Identifying trunk versus client SIP messages.”
• Using a regular expression to construct the Destination SIP URI that isn't working as expected (it may generate a SIP URI that is not valid). You can use a regular expression tool (http://regex.powertoy.org/) to test whether the regular expressions you have entered will construct the expected Request URI.
5 Inbound callsThis section addresses problems that can arise when you try to make inbound calls to the Sametime softphone from an external phone or video device. Again, the main problem involves the inbound route definition.
5.1 Creating an inbound routeWhen you create an inbound route, the goal is to route the inbound SIP traffic to the Conference Focus. As mentioned earlier it is acting as a B2BUA and must be included in the SIP call flow.
If you attempt to route directly to the Sametime softphone, your inbound calls will fail because the Sametime softphone will reject unsolicited SIP messages. The Sametime softphone must be notified about an incoming call by the Conference Focus before it responds to the associated SIP messages.
Use the following guide when configuring the route Conditions:
• Set the Method to INVITE as this will be the first message received and will establish the route to be used.
• Set the Source Address to identify the source of the SIP messages.
Use the following guide when configuring the route Destination:
• Select “Push a Route header field” when creating a route used when the user dials a SIP URI. You can usually leave SIP URI's unmodified, but you do need to include a route header to ensure the SIP proxy routes the request via the Conference Focus. If the Conference Focus and SIP Proxy are on the same machine, make sure to use the correct port.
13
5.2 Sample valid inbound call routeFigure 13 shows the Conditions for an inbound route from an Asterisk server. The Method is the type of incoming SIP method, and for SUT Lite you should only ever need “INVITE”, so that when the system receives a SIP INVITE, it will know what should it do.
Figure 13. Conditions for inbound route from Asterisk server
We also specify a source address in figure 13 so that, not only are we waiting for a SIP INVITE but we are also accepting them only from a specific source address---in this case the Asterisk PBX. As long as the INVITE is from this source, then the INVITE will be passed to our specified destination; if not, then the inbound SIP request will be ignored.
Figure 14 shows the Destination for an inbound route from an Asterisk server. For the incoming Sametime SIP INVITE we select “Push a route header field”, to change the route of the call from the ST Media Manager SIP Proxy to the Conference Focus, and then onto the SIP Registrar.
14
Figure 14. Destination for inbound route from Asterisk server
To do this, we enter the Conference Focus’ IP address or the Fully Qualified Domain Name and its port, which is the default SIP Port for either Secure or Insecure SIP communication.
This example is using insecure SIP and the port is the default of 5060. As SIP is insecure, TCP is selected as the transport mechanism. When using Secure SIP (SIPS) then you would use TLS as the transport mechanism.
5.3 Common problems with inbound callsThe two most common problems with inbound calls are problems with the route:
• Not having a condition which matches the incoming request. The only way to confirm when this happens is to analyze the SIP Proxy server logs. You will typically be matching based on source address so you can use Wireshark to confirm you have the correct IP/FQDN.
• Specifying the wrong port e.g. entering the port of the SIP Registrar rather than the Conference Focus will cause the call to fail because the Sametime softphone isn't told to expect a SIP invite then it will reject it. One of the jobs of the Conference Focus is to give the Sametime softphone a message to expect a SIP invite.
5.4 Correcting an inbound call flowFigure 15 is an example of a call flow in which SIP messages bypass the Conference Focus.
15
Figure 15. Failing call flow
Let's follow this flow:
1. We type the phone number of the Sametime user into the phone (softphone).
2. The call is routed by the PBX to the SIP Trunk to Sametime Media Manager (SIP Proxy), and the Sametime Media Manager checks the routing rules.
3. As this is an incoming call we must add a route Header, to tell the incoming call where to go.
4. The Route header is set to add the URL of the Sametime Media Server (SIP Proxy) and the port.
5. We have used the URL and the port 5080, which is the port for the SIP registrar, and see that the call routes from the SIP proxy to the SIP registrar.
6. The SIP invite is sent from the SIP Registrar to the Sametime client and is rejected; Sametime won't accept unexpected SIP invites, as in this case.
7. As the Conference Focus isn’t in the flow due to an incorrect port, the Sametime client never receives a message to tell it to expect a SIP invite.
8. The fix here is to change the port used in the rule to the Default SIP or Default SIPS port, which adds the Conference Focus to the route (this is listed in the ports list on the Media Server details in the system console):
a) Log in to the IBM Integrated Solutions Console (https://<FQDN of Server running SSC>:8701/ibm/console), and on the left-hand pane select Servers --- Server Types --- WebSphere Application Servers --- ST Media Server.
b) Once the Details window loads, on the right-hand side, find the Communications section and select Ports.
c) Scroll down the list and find the SIP_DEFAULTHOST & SIP_DEFAULTHOST_SECURE port details and then, depending on whether you are currently using secure or insecure (TLS or TCP), use this port in your incoming rule.
16
Now, the client receives a message from the Conference Focus telling it to expect a SIP invite, which it now accepts, changing the failing call flow into the working call flow and the call is successful (see figure 16).
Figure 16. Working call flow
For more information, refer to the Sametime product documentation topic, “Determining the ports for a stand-alone SIP Proxy and Registrar or Conference Manager.”
6 Other deployment problemsThis section covers some general issues that can arise when deploying the SUT Lite Client.
6.1 Configuring a health-check method for WebSphere SIP ProxyIn an environment that includes a load balance, the load balancer periodically sends a SIP OPTIONS to monitor the health of backend servers (WebSphere SIP Proxy servers). Most load balancers support this mechanism (there are also other methods for health check).
In this case, a WebSphere SIP proxy server should be configured with additional settings that allow it to distinguish between regular and health-checking requests. When a health-check (keep-alive) request arrives, a WebSphere SIP proxy server responds without forwarding a request to servers in a cluster. The Max-Forwards header set to zero is legal, since a WebSphere SIP proxy server is the final destination.
Use these steps to configure a health-check method for the WebSphere SIP Proxy servers in a load-balancing environment (this assumes that a load balancer uses SIP for health checking):
1. Log into the ISC administrative console and select Servers --- WebSphere proxy servers --- proxy-name.
2. Under Proxy Settings, select SIP Proxy Server Settings --- SIP proxy settings. This setting can be used for defining WebSphere SIP Proxy Load balancer health checking.
3. Under Load balancer health checking --- Load balancer members --- IP address 1, type the Load balancer IP address (physical IP address of the machine on which the Load Balancer is installed):
17
● SIP health check method name: Enter the SIP method name that your load balancer uses for the health-check mechanism (usually OPTIONS).
4. Save the changes by clicking the Save link.5. Repeat these steps for each WebSphere Proxy Server.
6.2 Sametime SIP Proxy responds to initial incoming request with 483 error
A request sent by an external SIP trunk is rejected by the Sametime SIP proxy with a 483 (Too many hops) error.
The main cause of this problem is an incorrect configuration. Usually this problem occurs when the destination address in the route rule for incoming messages is configured with the Sametime SIP P/R address and SIP port, rather than with the Conference Focus address and SIP port.
If there is a load balancer in use, then use the steps above to configure a health check method for the SIP Proxy. If there is no load balancer, use the following steps:
1. Log in to the ISC administrative console and select Servers --- WebSphere proxy servers --- proxy-name.
2. Under Proxy Settings, select SIP Proxy Server Settings --- SIP proxy settings 3. Under Load balancer health checking ---Load balancer members --- IP address 1, enter the
IP address of the SIP endpoint that sends this OPTIONS request:
SIP health check method name – type OPTIONS
4. Save the changes by clicking the Save link.
6.3 Is UDP supported by SUT Lite?The short answer is No, and in this section we describe the problem that prevents SUT from supporting User Datagram Protocol (UDP).
The Conference Focus uses the same transport to send messages to Sametime clients and external devices. The transport protocol is configured in the stavconfig.xml file (SIPProxyServerTransportProtocol attribute).
UDP is not well supported for an SIP outbound message, specifically, when the message size exceeds the Maximum Transmission Unit (MTU) size (which by default is 1500 bytes), then the WebSphere Application Server (WAS) SIP container switches from UDP to TCP (as the SIP standard mandates).
Switching from UDP to TCP is not covered in the SIP outbound specification. When the transport switch occurs, WAS might send a request sent by the client back to the client (rather than forwarding is to the CF), causing the call to fail.
Because of this behavior we can't use UDP with Sametime clients. You can still configure an external device with UDP; however, it's not guaranteed that all messages to an external device will be sent over UDP.
18
For example, suppose that the transport protocol in the stavconfig.xml file is TCP/TLS, and a route rule for an external device is configured with UDP:
1. Select Conference Focus --- Proxy Registrar --- External device. The CF sends a request to an external device (over TCP/TLS).
2. The IBM SIP Proxy/Registrar (PR) forwards a request to en external device over UDP (based on route-rule settings).
3. Before the PR forwards a request to an external device, it adds a Record-Route header field to an initial INVITE request with the transport attribute set to TCP/TLS.
4. A call is initialized, and so far so good....5. An external device sends a mid-call request, and a request is sent over the protocol
specified in the Route header field (TCP/TLS), meaning that a call was started over UDP, but mid-dialog requests are sent over transport specified in a Route header (TCP/TLS).
Usually, in such cases WAS should add two Record--Route header fields, one with TCP/TLS and one with UDP, allowing communication with the Conference Focus over TCP/TLS and with an external endpoint over UDP. This approach is not covered in the main SIP standard (RFC 3261); instead, it's covered in the supplementary RFC 5658 (http://tools.ietf.org/html/rfc5658). This feature (transport switch) is not supported in earlier WAS releases.
Starting in Sametime 8.5.2 the SIP Proxy/Registrar adds a new attribute (flow token) to a Route header field (as described in the SIP outbound RFC). This attribute contains connection details over which the last REGISTER request arrived, allowing the underlying SIP Container to send all future requests to a client over an existing connection (that was established by a client).
When a client sends a mid-dialog request that exceeds the MTU size, a request is sent over TCP, and the SIP Container examines a Route header field to determine whether this is an incoming or outgoing request.
Connection details don't match to the connection over which a mid-dialog request arrived (since a mid-dialog request arrived over TCP, and the flow token indicates that a connection to a client is over UDP). Thus, the SIP container assumes that it's an outgoing request and sends it to a client (rather than forwarding it to the CF).
7 Appendix A: Collecting diagnostic informationIBM Support needs the following information to diagnose problems with a SUT Lite Client deployment:
• Sametime Client traces• Sametime Media Manager traces• Sametime SIP Proxy configuration file• Wireshark trace taken on the Sametime Media Manager
Collecting Sametime Client tracesThe steps for logging and tracing on Sametime Connect client are documented in the Sametime product documentation topic, “Logging and tracing on Sametime Connect.” Note that you must enable the trace levels for Audio/Video quality issues.
19
Collecting Sametime Media Manager tracesThe steps for setting a diagnostic trace on Sametime Media Manager are in the Sametime product documentation topic, “Setting a diagnostic trace on a Sametime Media Manager server.”You must enable trace levels for the Conference Manager and the SIP Proxy/Registrar components.
The steps for gathering Sametime Media Manager logs are documented in the product documentation topic, “Gathering Sametime Media Manager logs and traces for IBM Support.”
Collecting the SIP Proxy configuration fileTo collect the SIP Proxy configuration file (proxy.xml), you first must have access to the file system on the server on which the Sametime SIP Proxy/Registrar is deployed. The SIP Proxy configuration is saved to the file system in a file called proxy.xml.
You may need to search the file system for the proxy.xml file; for example, the proxy.xml file is stored in the following location on a single-server deployment:
<Install>\AppServer\profiles\STSCDMgrProfile\config\cells\<Server>SSCCell\nodes\<Server>STMSNode1\servers\STMediaServer
NOTE: The proxy.xml contains the configuration information that you entered for the Proxy Administration via the Sametime System Console.
Collecting a Wireshark trace on the Sametime Media ManagerSee Section 8: Appendix B, below for more information on working with Wireshark. If you are already familiar with Wireshark, use the following steps to collect a Wireshark trace:
1. Install Wireshark on the Sametime Media Manager.2. Launch Wireshark and start capturing data:
(http://www.wireshark.org/docs/wsug_html_chunked/ChCapCapturingSection.html)
3. Perform the call scenarios you want to test.4. Stop capturing and save the Wireshark traces to a file.
NOTE: If you have SIP security enabled, then the SIP messages are encrypted. You can temporarily disable it so that the IBM Support team can see the SIP traffic, or you can retrieve the key store used by WAS hosting the Media manager. Wireshark can be configured with this key store so it will allow Wireshark to decrypt TLS traffic.
8 Appendix B: Working with WiresharkWireshark is a network packet analyzer that lets you capture the SIP messages that flow to and from the Sametime Media Manager. SIP is used to set up the calls, and errors during the SIP negotiations are the most likely cause of failures in an SUT Lite deployment.
You can download Wireshark for free here: http://www.wireshark.org, and access the product documentation here: http://www.wireshark.org/docs/wsug_html_chunked/.
Once you have the Wireshark software, you need to install it onto the Media Manager server, to get the best results. Once installed, open it and let it run a trace to monitor SIP (the call flow).
20
Wireshark capture controlsThe main controls used to start tracing the call flows are shown in figure 17. From the five icons pictured, select the first, “List of available capture Interfaces”, from the list that displays and select your network card; you may have multiple cards, so make sure you select the correct one (wireless, Ethernet, etc.). Then click the Start button to the right-hand side of the network card.
Figure 17. Wireshark controls
Wireshark capture outputFigure 18 shows the result of a working SUT Lite call-flow capture. The Wireshark user interface provides a filter field that lets you filter specific network packets; for instance, entering the text “sip” will filter SIP traffic. The filter edit box should go green, which means Wireshark understands and can monitor that type of traffic.
Figure 18. Wireshark capture output
Viewing VoIP callsWireshark provides an option to analyze Voice over IP (VoIP) call flows and view them as a graph analysis. Select from the menu Telephony --- VoIP Calls, to display the list of calls in the current Wireshark trace output. An example of an SUT Lite call is shown in figure 19.
21
Figure 19. Example SUT Lite VoIP call
The first thing you notice in the figure is that there are two call legs shown. This is because for each SUT Lite call there are two call legs established. The Sametime Conference Manager is acting as a SIP B2BUA and manages each call leg, that is, one leg to the Sametime softphone and one to the external device over the SIP trunk.
Select both call legs and then use the Flow button to open the graph analysis for the call (see figure 20). The IP addresses for the agents involved in the call flow are as follows:
IP: 9.161.84.248 - Sametime Media Manager/Sip RegistrarIP: 9.161.142.136 - Sametime ClientIP: 9.161.98.107 – Asterisk PBX
Figure 20. Example graph analysis
22
Understanding VoIP call flowsConsider this call flow:
1. From the client the user starts a call (either click to call or by typing a number), which is sent to the Server via the VP protocol, not listed here. The section of the call flow shown in figure 21 includes the SIP messages for this part of the call.
Figure 21. SIP messages
2. The Sametime Media Server then sends an invite to the local Sametime Client. The 180 ringing is an optional set command and does nothing at this point, so ignore it.
3. The Client responds with an SDP 200 OK response, meaning that it is accepting the invite. Since the SDP is being sent at the end, it is known as a “Late Media Offer”; if the SDP were sent with the initial invite, that would be an “Early Media Offer.”
4. The SDP message includes a list of supported codecs from that system including G.711 μ-law and G.711 A-law, which are default codecs. So the Sametime client has told the server it is ready and what codecs it supports.
The section of the call flow shown in figure 22 shows that the Sametime Media server sends an invite to the PBX to set up the connection.
5. The Sametime Media Server sends the SDP details from the Sametime client in an INVITE to the PBX, basically asking the PBX to reply with its list of supported codecs (this is an Early Media Offer since the SDP details are sent within the initial message).
6. The PBX responds with a holding message of “100 Trying.”
Figure 22. Invite sent to PBX
23
7. The next three lines shown in figure 23 show the Sametime Client repeatedly sending its 200 OK SDP message because it hasn’t received a response yet.
Figure 23. Sametime sending 200 OK SDP messages
8. Next comes the response from the Asterisk PBX (see figure 24), in which we see that the PBX sends a “180 ringing” message back to the Sametime Media Server.
Figure 24. Response from Asterisk PBX
• In green we can see that the Sametime client is still waiting for a reply and continuing to send its SDP message.
• The PBX sends it’s “200 OK SDP” with the codecs to set up the call (G.711 μ-law & G. 711 A-law, and this is a telephone event: 101—DTMF) to the Sametime Media server.
• The Sametime Media Server then sends an “ACK” message back to the PBX, meaning that the connection is set up to the PBX.
• Finally, the Sametime Media Server sends the ACK message to the Sametime client to complete the setup of the SIP dialogue. A complete SIP dialogue requires the two ACK messages, basically indicating the servers know how to contact each other, and from here a call can be set up between the clients, using RTP point-to-point between the clients.
9. At this point the call has been successfully established. The next sequence of events in figure 25 show the call being ended.
Figure 25. Call ending
24
• Since the Sametime client is ending the call, it sends the “BYE” message to the Sametime Media Server. This BYE is just the way the system has been coded; it's redundant, so you can ignore it, as well as the first “200 OK” response.
• The third BYE is sent to the PBX to end the call.• The second 200 OK tells the Sametime client the call has ended.• The final 200 OK tells the Sametime Media Server that the PBX has accepted the call and it
has ended.
9 Appendix C: Replacing the existing proxy.xml fileRouting rules are stored in the proxy.xml file on the machine hosting the Deployment Manager (DMgr) of the SIP Proxy/Registrar (usually, the Sametime System Console). If you have modified the proxy.xml file manually, you must replace all instances of the file on the machine hosting the DMgr.
On the server hosting the DMgr of the SIP Proxy/Registrar, navigate to the following directory:
<Deployment_manager_install_root>/config/cells/cell_name/nodes/node_name/servers/server_name
where “node_name” is the node that manages the server hosting the SIP P/R application, and “server_name” is the server hosting the SIP P/R application. For example:
C:\Program Files\IBM\WebSphere\AppServer\profiles\STSCDMgrProfile\config\cells\avenv22SSCCell\nodes\avenv22STMSNode1\servers\STMediaServer
Note that in a clustered environment there are a few instances of this file, so you must modify/ replace them all (we recommend backing up the existing file before you modify/replace it).
After you modify/replace the proxy.xml file on the DMgr machine, you must synchronize all nodes:
1. In the DMgr's Integrated Solutions Console, select System Administration --- Nodes.2. Select all nodes in the cluster, and then click the Full Resynchronize button at the top of the
table.3. Restart the SIP Proxy/Registrar server/cluster for the change to take effect.
10 ConclusionYou should now be familiar with how to diagnose problems encountered when enabling the Sametime Unified Lite client feature, how to create inbound and outbound rules, and troubleshooting other common issues.
11 Resources• developerWorks® IBM Sametime product page:
http://www.ibm.com/developerworks/lotus/products/instantmessaging/
• IBM Sametime Forum:http://www-10.lotus.com/ldd/stforum.nsf
25
• IBM Sametime wiki product documentation:http://www-10.lotus.com/ldd/stwiki.nsf/xpViewCategories.xsp?lookupName=Product%20Documentation
• Sametime wiki Community article, “IBM Sametime Unified Telephony: User provisioning for reliability testing”:http://www-10.lotus.com/ldd/stwiki.nsf/dx/IBM_Sametime_Unified_Telephony_User_provisioning_for_reliability_testing
12 Author biographyMark Wallace is a Software Architect based at IBM's Ireland Software Lab. He has worked on the Sametime Unified Telephony product and has a keen interest in programming models and improving developer productivity. Mark joined IBM more than 19 years ago, working on various products, and is focusing on IBM Social Business Toolkit. You can reach him at [email protected].
AcknowledgementThe author extends his special thanks to former IBM colleague, Jon Crouch, who co-wrote this paper.
Trademarks• developerWorks, IBM, Sametime, and WebSphere are trademarks or registered trademarks of IBM
Corporation in the United States, other countries, or both.
• Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.
• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
• Other company, product, or service names may be trademarks or service marks of others.
26