Summary

sipXtools is a general purpose collection of utilities for managing a sipXecs system. The sipXtools RPM is built as part of the sipXecs build process and can be installed from the sipXecs 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 sipXecs system or to monitor certain critical performance parameters. The current components of sipXtools are the following:

sipxcar	Configuration Utility for RPM based sipXecs installations Since sipXecs 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.
sipxproc	Utility to Start/Stop/Restart and check status of sipXecs processes Provides a command line access to restart one or more processes controlled by the sipXecs system. Also to display the state and other useful info (version, output and error messages, etc).
sipx-network-trace	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 sipXecs developers like it). Requires tcpdump.
polycom-config	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.
sipdb-dump	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 sipXecs 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.
expire-spread	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.
monitor-spread	Tool to monitor registrations and send alarms monitor-spread - regularly monitor registration state and send alarms
regtimes	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.
sipx-stats	Digests sipXecs 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.
sipx-alias2dot	Converts a sipXecs 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.
sipx-servtest	Check the health of a sipXecs 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 sipXecs system. sipx-servtest executes the following tests: Connect, Auth Proxy Forwarding, Proxy Forwarding, Redirect, Domain Response, End Point.

Installation

To install the executables and documentation:

- On Fedora and CentOS machines, import the appropriate sipXecs 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 http://code.sipfoundry.org/browse/sipXecs/main/sipXtools

Roadmap

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 sipXecs log files for common issues, such as failed phone registrations and "decypher" obtuse messages into reports like this: "wrong password for user agent : phoebe@example.org"
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 --siplog2siptrace, siptest, syslog2siptrace, sipsend.pl, etc.
Move the configuration files for interop.pingtel.com from their current home in sipXpbx/doc/developer/interop.pingtel.com. --DLH: This doesn't sound like a tool?
*sipx-obliterate - Delete all traces of sipXecs that RPM distro might leave behind. Modified configuration, log files, postgres db, even sipXtools itself?!

Manifesto

Goals for the sipXtools project include:

sipXtools from the nightly build of the sipXecs "main" development directory will always be the most usable and stable copy.
sipXtools will not require any specific version of the sipXecs components, rather it will be safe to install into a sipXecs system of any version or configuration. If a tool requires a specific feature of another sipXecs component, and that feature is not present, the tool will gracefully fail at runtime and be documented to do so.
No other sipXecs 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 sipXecs components, but care should be taken to address the deficiency in the sipXecs component, thereby obsoleting the tool in future sipXecs 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.