Diagnosing complex SIP problems often requires looking at the SIP message flow between the components of sipXecs, as well as to and from phones and external gateways. This page tells the adventurous how to use the tools that come with sipXecs to display SIP message flows. Sipviewer is a very powerful toll used to diagnose problems.
Contents[hide] |
Installation
Before you can display the messages, you need to install the viewer. You can do that either on the sipXecs system itself (which requires a few prerequisites not installed by the ISO image), or standalone on your regular system (Windows, Mac, or Linux). Once you've gotten one of these done, you're ready to collect trace data for viewing.
Standalone
There is a standalone installer for the sipviewer tool in the temp area on the sipxecs project server:
Download the sipviewer installer
The above installer is a java .jar file - execute it on your system to run the installer, eg:
java -jar sipviewer-install.jar
The installer should work on any system (Linux, Windows, Mac) that has java installed.
On your sipXecs system
On RPM-based distributions sipviewer is installed with the sipxtacklib RPM; there is a separate package sipviewer for Debian. Sipviewer is written in Java and requires an X server to be running to display results graphically (the ISO installer does not by default include this, but see .
Make sure the necessary packages are installed on the host that runs sipXecs:
yum install xorg-x11-xinit
yum install java-1.5.0-sun-fonts
The package java-1.5.0-sun-fonts can be found in the sipXecs repository.
Getting SIP Messages to display
The SIP messages are logged by sipXecs components at the INFO logging level; this is a more verbose level than the default NOTICE level. You will need to reset the logging level for the components you're interested in tracing - you should always include the proxy (in 3.8 or earlier, both the proxy and authproxy, in 3.10 they are merged into one proxy) and the registrar.
- Enable INFO or DEBUG log level for the sipXecs proxy server. You can do this using the sipXconfig UI.
You must restart the components for the change in logging level to take effect.
There is a script named 'sipx-trace' installed (by the sipxtools rpm) in your sipXecs system. To create an xml file that contains trace data for messages on your system:
sipx-trace --all-components --output <filename> <token>...
where <filename> is the output file and <token> is some token that will be in the call (call-id values are best for this, but even the calling number followed by '@' will find it; it will just find lots of other stuff too).
You can copy that xml file to any system where you have installed the sipviewer tool to display the trace, and you can post that file to a mailing list to ask for help interpreting it (be sure to also post a description of your configuration, including the IP addresses for all the components that show in the trace).
Using Sipviewer over an ssh connection
In many cases you will not have an X server running on the sipXecs host.
- From your client type the following:
xhost +
ssh -Y [email protected]
The DISPLAY variable for the X server is set automatically. You can verify this using "echo $DISPLAY". You can also verify the connection by starting xterm. The xterm window should appear on your client workstation.
- Now run these commands in the shell you just started over ssh on the sipXecs host:
cd /var/log/sipxpbx
merge-logs
sipviewer merged.xml
sipviewer is sensitive to log files that are too large. You can delete all the logs in /var/log/sipxpbx and then reproduce the problem before capturing the logs. All the log files are created if they do not exist automatically.
- If your log is really big or you want to narrow your inspection to just one user
grep "[email protected]" /var/log/sipxpbx/sipproxy.log | syslog2siptrace > /tmp/sipproxy-trace.xml
sipviewer /tmp/sipproxy-trace.xml
Using Sipviewer - More details
First, the needed information must be contained in the sipX log
files. The level of detail in the logs is controlled by the log level
for each component. If sipXconfig is running the log level can easily
be changed in the Web UI by going to "System/General/Logging".
Alternatively logging levels can be changed in the configuration files
of the respective component. These configuration files are located in
the directory /etc/sipxpbx:
proxy-config.in
authproxy-config.in
registrar-config.in
mediaserver-config.in
sipxpark-config.in
sipxpresence-config.in
status-config.in
For most of the components, look for a line like this:
SIP_AUTHPROXY_LOG_LEVEL : NOTICE
and replace NOTICE with DEBUG. In mediaserver-config.in, the controlling line is:
mediaserver.log.level VXIString NOTICE
To get useful information, the first three components listed above (proxy, authproxy, registrar) must be set at INFO or DEBUG (usually INFO is sufficient, and makes for much smaller log files). You should also have detailed logging about for any other component you suspect to be involved in the problem.
In order to display the SIP traffic through sipX, execute the following commands:
cd /var/log/sipxpbx
merge-logs
sipviewer merged.xml
- The executables (merge-logs and sipviewer, and the two
programs that merge-logs invokes, syslog2siptrace and siptrace-merge)
are normally installed in
/usr/bin. If you have them installed in a non-standard directory, you should have that directory in your path. You can invoke merge-logs and sipviewer with full path names, but merge-logs expects syslog2siptrace and siptrace-merge to be runnable through the path. - These programs are a collection of shell scripts, Perl scripts, and Java executables. If you con't have those interpreters available, this method won't work.
- Often there are many SIP messages in the logs that you
aren't interested in. merge-logs takes a collection of arguments that
will exclude messages that are not of interest. Its arguments are the
same as those of siptrace-merge, which are described at the top of that
file (
/usr/bin/siptrace-merge). Especially useful are--containing, to specify the call-ID of a dialog,--afterand--before, to restrict to a certain period of time, and--exclude-method, to screen out the housekeeping SUBSCRIBE, NOTIFY, PUBLISH, and REGISTER transactions. The timestamps that--afterand--beforeuse are in GMT, use the format2006-09-01T20:32:10, and are compared with the lines of the log files as text strings. Usedate -u +%Y-%m-%dT%H:%M:%Sto print the current time in this format. - SIP messages are displayed by sipviewer. sipviewer takes some getting used to, but is quite sophisticated. The vertical lines denote the SIP agents sending and receiving messages. Beware that sometimes sipviewer cannot determine that two addresses are equivalent, and so an agent will be represented by more than one vertical line. You can click between the headers of two vertical lines to exchange them, so you can put the vertical lines in any order you want. If two vertical lines are really the same agent, it usually helps to put them next to each other.
- When the mouse is over a SIP message, it is highlighed in red, and the details of the message are shown in the lower panels. If you click on the message, a window pops up giving the full text of the message. The window can be closed with the Escape key.
- When a SIP message is highlighted, related messages are highlighted:
- green - other messages in this transaction, between these two agents
- blue - other messages in this transaction, between different agents in the chain
- yellow - other messages in this dialog
- SIP messages colored blue and yellow also are coded:
- light color - has the same from-tag and to-tag as the chosen message, and so is in the same branch of a fork
- dark color - has different tags, and so is either in a different branch of a fork, or (more likely) are the request and response of an initial request (since the request has no to-tag, but the response does)
- Looking at a few normal calls will familiarize you with the standard sipX message flow, so you will be able to recognize erroneous message flows.
