Monitoring SIP trunks for availability by issuing test calls with SIPp

Motivation for periodically checking your SIP trunks or PBXs for inbound calls

SIPp is an awesome tool to do load testing for your SIP infrastructure or applications, it uses a simple XML file to setup a test scenario and then you can pick up the results in different ways. And we can also use it to test the availability of our own VoIP infrastructure.

It may happen that your business relies on an Asterisk PBX or FreeSWITCH system to take calls (for example inbound calls for customer support), and it may also happen that these servers might be temporarily down for some reason (perhaps a misconfiguration ot any other temporal errors). This is emabarrasing when the customer wants to reach out to you by phone and it's not possible.

But VoIP sometimes fail, so it is really useful that we can check that calls to one or more of these telephone numbers (or DIDs) actually work as they should, and in case they don't take some action before the customers actually note it.

So the general idea is to use a real VoIP provider to periodically issue a call to a public telephone number and check that the call has been answered by for example an Automated Attendant playing a menu to the customer.

In this article we are going to see how we can use SIPp for such a task, essentially to monitor our PBXs or SIP trunks (it doesn't matter if we use Asterisk PBX, FreeSWITCH, or any other kind of SIP UAS).

Running the test to issue one call to check your SIP trunk for availability

We are going to use the following shell script to run SIPp with our scenario file:

The script takes the following arguments (in order):

  • Scenario File: Full path to the XML file with our scenario.
  • VoIP Gateway: IP address of where we should send this call to. This should be a real VoIP provider that is connected to the PSTN (the Public switched telephone network) so the call can actually make progress like it would in a real use case when a customer is calling.
  • From: A valid DID, or telephone number as required by the VoIP Gateway above. This should be seen in our calls as the Caller ID.
  • To: The DID we want to test, for example our customer support number.
  • Local IP Address: This should be the internal IP of the host running the script.

The script runs SIPp by specifying the following arguments:

  • -aa: Replies with 200 to INFO, UPDATE and NOTIFY messages (so we don't fail the test for these unexpected messages).
  • -d 30: Set duration of pauses to 30secs by default.
  • -r 1: Set the call rate to 1 call per second (we are not going to do more than 1 call ever, actually).
  • -rp 1s: Period duration, 1 sec. This means that option -r will do N calls per this period length.
  • -sf ${scenario}: Sets scenario file.
  • -l 1: Limit to 1 simultaneous call at most.
  • -m 1:Quit SIPp once this many number of calls have been processed, either with success or error.
  • -trace_err: Save unexpected messages to a file, useful for tracing.
  • -i ${my_ip}: Sets the local IP address.
  • -rtp_echo: Echo back all the audio we get once the call is answerwed.
  • -set from ${from}: Sets the global variable from that will be used in the scenario file.
  • -set to ${to}: Sets the global variable to that will be used in the scenario file.

After SIPp runs it will set an exit status code of 0 on success (all calls finished ok) and non-zero on errors, and that's how we can check it in our script and take an action accordingly (like sending an email on errors).

Complete SIPp scenario

Now this is where all the fun things happen, our XML scenario file for SIPp.

This will essentially:

  • Send a SIP INVITE to the VoIP Gateway to establish a call to our public telephone number (or DID) by using a predefined caller id. In this case we also specify G729 as our desired codec, and there's a chance that you will need to adjust this.
  • Expect a SIP OK message (200) (and save the contents of the Record-Route headers if any, rrs argument of the recv command).
  • Optionally expect the Provisional Response Messages: 100, 183, and 180. It will specifically fail the test on the 603 Rejected message (this one is used a lot by VoIP providers for example when issuing calls from an unauthorized IP address).
  • When the 200 is received, it will Send a SIP 200 ACK for it and honor the recorded routes and the contents of the Contact header by using next_url.
  • At this point the call is established, so we pause for 5 seconds. This is useful for example if we have an Automated Attendant that will for example play a menu for the user, so waiting 5 seconds seems reasonable to simulate a user listening to the menu.
  • After the pause the call is hanged up by sending the BYE Method and expecting a 200 in response.

An awesome tool to check that your PBX and SIP trunks are available, running, and taking inbound calls

Now you can set this up in a crontab and send emails when you detect that the calls are failing, giving you a heads up early, without waiting for the customer to notice. No more lost calls due to PBXs being offline :) Enjoy!