Child pages
  • sipXtools
Skip to end of metadata
Go to start of metadata


sipXtools is a general purpose collection of utilities for managing a sipXcom system. The sipXtools RPM is built as part of the sipXcom build process and can be installed from the sipXcom repository. On systems that are installed using the installation CD, the sipXtools RPM is already on the system.

The sipXtools utilities are typically used for debugging a sipXcom system or to monitor certain critical performance parameters. The current components of sipXtools are the following:


Configuration Utility for RPM based sipxcom installations Since sipxcom v3.4, on rpm based system, a pristine copy of every configuration file is tucked away in various archives. This utility uses those archives to assist common configuration operations.


Utility to Start/Stop/Restart and check status of sipXcom processes Provides a command line access to restart one or more processes controlled by the sipxcom system. Also to display the state and other useful info (version, output and error messages, etc).


Utility to capture network packets Provides a simple command line access to allow network packets to be captured to assist in debugging (default invocation captures up to 10 minutes of data as sipxcom developers like it). Requires tcpdump.


Displays polycom configuration files in a format that's easier to work with from the command line Polycom configuration files are heavily nested xml files with potentially large number of attributes. They can be hard to view and compare. This utility flattens out the configuration files into one line.


Displays /var/sipxdata/sipdb/.xml in a format that's easier to digest for command line tools like grep and awk, and add extract and calculate additional information like ip address and expired true/false flag.* Many of the sipxcom services store information periodically to the disk in the form of XML files. These files can provide insight to the current state of the system. This tool displays the files in a format conducive to command line tools like awk, grep and sed for handy "real-time" reports.


Show distribution of subscriptions and registrations Show how subscriptions and/or registrations are distributed over time.By default, a histogram is printed showing the number of expirations and the rate per second in each sample interval.


Tool to monitor registrations and send alarms monitor-spread - regularly monitor registration state and send alarms


Show intervals for renewal of registrations The time for each registration of each contact is shown, with when the previous expiration would have expired, the actual time it was renewed and the difference between them. If the refresh is late (there was a period when the registration had expired),then that is flagged.


Digests sipXcom log files to create message statistics Given one or more log files on standard input (or file names on the command line), this prints statistics in tabular form on the standard output.


Converts a sipXcom alias.xml file into input for the graph-drawing tool. This can be helpful in diagnosing problems with how calls are routed. Given an alias.xml file (the persistent copy of the aliases in-memory database), prints a directed graph (on stdout) for processing with 'dot' to produce a visual map of the aliases.


Check the health of a sipXcom server or cluster. May also be used as a continuous monitor that sends an email alarm when a failure is detected. Monitors the reachability and functionality of a sipxcom system. sipx-servtest executes the following tests: Connect, Auth Proxy Forwarding, Proxy Forwarding, Redirect, Domain Response, End Point.


To install the executables and documentation:

  - On Fedora and CentOS machines, import the appropriate sipxcom yum .repo file and run

 yum install --enablerepo=sipx-development sipxtools

 RHEL/CentOS 4

 up2date --install sipxtools

The sipXtools source is accessible via subversion at


Projected future components of sipXtools include:

  • check-sync - Sends unsolicited NOTIFY directory to an IP address to restart phones that support this type of messages (polycom, snom, cisco, many others)
  • sipxua-discovery - Query the arp table for phones looking for configuration files. Get the MAC address and present in a form ready for import into sipXconfig for managed phone support. This will not work for systems using phones behind a router that reports the MAC address of the router, not the phone. ***May be moot if XCF-1378 is implemented
  • sipxlog-analyze - Rummage through sipxcom log files for common issues, such as failed phone registrations and "decypher" obtuse messages into reports like this: "wrong password for user agent :"
  • Move sipviewer to remove java dependency on sipXtack, but more importantly provide a more agile environment(see manifesto) for such a useful tool
  • Similarly, there are a lot of other diagnostic/testing/development tools that could be separated out from the "production" code, etc.
  • Move the configuration files for from their current home in sipXpbx/doc/developer/ This doesn't sound like a tool?
    *sipx-obliterate - Delete all traces of sipxcom that RPM distro might leave behind. Modified configuration, log files, postgres db, even sipXtools itself?!


Goals for the sipXtools project include:

  • sipXtools from the nightly build of the sipxcom "main" development directory will always be the most usable and stable copy.
  • sipXtools will not require any specific version of the sipxcom components, rather it will be safe to install into a sipxcom system of any version or configuration. If a tool requires a specific feature of another sipxcom component, and that feature is not present, the tool will gracefully fail at runtime and be documented to do so.
  • No other sipxcom component will have a dependency on sipXtools.
  • sipXtools will only be comprised of non-required tools. If a tool becomes required, it should be moved to a more appropriate project
  • Unit tests will be strongly encouraged to ensure minimal regression
  • It's perfectly acceptable for tools to be written to compensate for deficiencies of sipxcom components, but care should be taken to address the deficiency in the sipxcom component, thereby obsoleting the tool in future sipxcom versions. (I.e., avoid the crutch "anti-pattern".)
  • A "man page" is required to document each tool to ensure some end-user consistency for an otherwise very diverse set of tools.
  • No labels