The sipcodes script

[Matt Keys]

Monitoring SIP traffic is imperative for reliable day to day operation and security of your UC infrastructure. The sipcodes script (19.12 and above /usr/bin/sipcodes.sh) was developed to provide quick counts from the Uniteme or sipXcom /var/log/sipxpbx/sipXproxy.log, or /var/log/sipxpbx/sipxbridge.log. The log verbosity of these services must be set to INFO or DEBUG in order to see and count the SIP signaling within the log.

A basic understanding of SIP signaling is required to understand and act upon the output of the script. In summary:

* A REGISTER is used to authenticate a SIP user. Within the REGISTER message, the From: header indicates the user attempting registration. The Contact: header provides the IP address of the phone or device sending the REGISTER.

* A INVITE is used when a user places a call to either internal extensions or external PSTN numbers. The To: header is the number dialed, the From: header is the user that sent it, and again the Contact: usually contains the IP of the device sending the message.

* A SUBSCRIBE is used when a SIP phone uses a feature on the Uniteme or sipXcom server, such as the Message Waiting Indicator (MWI), when subscribed to the presence status of another user (speed dial with presence checked), or when using Shared Line Appearance (SLA/BLA) between phones (shared box is checked under lines). Within the SUBSCRIBE message, the Event: header describes the service requested. "Event: message-summary" is a MWI subscription, "Event: dialog" is when a user is subscribing to presence of another, and "Event: dialog;sla" is used for the Shared Line Appearance. Again the Contact: is usually the IP of the device sending the message.

There are more such as OPTIONS and ACKs (see https://tools.ietf.org/html/rfc3261) but these are usually not as important. 

The first section of the sipcodes output describes the time period covered in the log file provided. Note that both proxy and bridge timestamps are in UTC/GMT. This portion is simply gathering and filtering output from the top (head) two lines and the last (tail) two lines of the log.

The next section describes overall SIP message counts mentioned previously, including OPTIONS and ACKs.

The "additional information" of each provides the most useful troubleshooting information. The default output only counts the top 50 results of each. If you have thousands of users or if there are more than 50 users/devices spamming the proxy, you may need to increase this (edit the "head -n50" parts of the script) to get a higher level perspective.

Users with the lowest counts are likely the typical user with one phone assignment and properly configured. Users with substantially higher counts than others should be suspected as misconfigured. For example... 

* A user who has configured a incorrect SIP password on a gateway/phone will have a much higher REGISTER count than others, because the gateway/phone will continually send and fail, where a successful user tries once and does not try again until the registration has expired. The only legitimate reason for a high registration count (in comparison to others) is multiple phone assignment or the device is configured manually with a shorter registration interval than everyone else.

* A user with a much higher SUBSCRIBE "Event: message-summary" count may not have voicemail permission, or even exist anymore within uniteme/sipxcom, but the phone that is (or was) assigned to the user is still attempting to subscribe to the MWI feature. If the user doesn't exist, you would also see a high REGISTER count.

At the bottom of the output are some 400 and 500 series (see: https://en.wikipedia.org/wiki/List_of_SIP_response_codes) checks. A healthy output would be 0 on all of those. 

If you need to determine the IP address of a phone the Contact: header can usually be used. The exception to that is if the device is behind a SBC (aka upper registered). For example, if were to see a very high REGISTER count from user 200 who no longer exists in the system anymore but still assigned to a phone, you could manually filter the proxy log like:

grep "REGISTER sip" /var/log/sipxpbx/sipXproxy.log | grep "INCOMING" | grep "sip:200" | syslogviewer --no-pager | grep "Contact:" | awk -F ";" '{ print $1 }' | sort | uniq -c | sort -rn

Regards,

Matt