Skip to main content

Category: VoIP

pyribbon: Python Module for Sonus/Ribbon SBC REST API

jimmy Leave a comment

Part of my recent stumbling into supporting VoIP systems again is supporting and maintaining Ribbon session border controllers (SBCs). SBCs are pretty much gateways/routers and even firewalls for VoIP traffic, which not only routes/limits traffic between disparate voice systems (like ISDN lines to SIP trunks), but can also manipulate the traffic such as adjusting the phone number format, media codec, changing SIP header information, yada yada — you get the point.

Diagram showing Ribbon SBC connecting to different systems

Pretty much all SBCs are configured via extensive web interfaces with lots of deep options, so if you have to manage these at scale, it can get a little time consuming — which is what my problem was. I have many SBCs scattered across our state, and I generally loathe having to make mass changes via any GUI, so does Ribbon have some method of configuring SBCs at scale? Yes, through its Ribbon API.

However, I’m not going to sit down and use Postman to configure these (well, maybe initially to test), so I need a scripting framework. I could use PowerShell or curl with bash scripting to do this, but most of my work in networking is done via Python, and thus because I couldn’t find any Python module built for this already (and it seemed like fun to create), I made this simple Python module and it’s on Github.

pyribbon: Python Module for Sonus/Ribbon SBC REST API

I wrote this with a VoIP engineer in-mind, and the basic idea is you import the module in a Python script, then interact with source of data to make changes or perform actions. For example, I’ve used it to create a ton of phone number changes with the routing and transformation tables, and I’ve used it to perform configuration backups across all systems.

To do most of this though, you need to get familiar with API and how object resources are designed. Personally I started with Postman and got a sense for how the API works, then I built the class to handle the API. Initially I started small, but then realized it was rather simple to add additional methods to the pyribbon class to perform different tasks. One could easily build additional methods such as reboot, backup, etc., but I just didn’t see the need for that — yet.

One potential cool use is to perhaps use the module to query for call statistics and send that to a database, then maybe graph it out with Grafana; or, if your NMS allows for script pollers, perhaps use that versus digging through SNMP OIDs.

Final thoughts: I know this is probably high on the esoteric use-cases. I mean, how many VoIP engineers are there in the world, then narrow that down to Sonus/Ribbon VoIP engineers, then dwindle that down to those that interact with the API, and then dwindle that down even more that do it via Python. Pretty small, but if you like Python for this kind of work, this should help.

Also, I thought about putting this in PyPi, but I can’t imagine this getting much use or further development on my end (it does what I need it to do well), and thus I’m shying away from that.

Let me know if you find this useful or have questions.

Audiocodes IP Phone Manager Custom Placeholders

jimmy Leave a comment

Audiocodes, Audiocodes…oh, Audiocodes. I continually battle with your poorly written documentation for your excellent products. It’s either you write your documentation poorly, I’m just a terrible reader of technical documentation, or maybe it’s somewhere in the middle. Usually I blame myself, but I really think it’s you this time.

AudioCodes Logo

A great example of this is AudioCodes IP Phone Manager Express, a centralized management server for AudioCodes VoIP phones that is free for the first 500 phones purchased. The program sits on top of IIS, installs and utilizes SQL Express, and leverages option 160 (custom option) from DHCP for directing phones for registration. These guys have an excellent write-up on how to install it (just don’t have two option 160s like I did, for some stupid reason).

So you get it installed, phones are registering with it, the wind is against your back, and now you want to customize options. If you follow the administrative manual that comes bundled with the download (or just download it here), you might think you’re limited to just the placeholder values that come with it. Page 21 in the manual demonstrates how to enter the values for the placeholders, but it doesn’t show you where. The manual for the IP Phone Manager (non-express, download it here), has more information to explain what’s going on, but even it lacks some clear, explicit directions for creating those placeholder values.

This is my biggest complaint about AudioCodes documentation: instructions and documentation isn’t always clear and straightforward, written from the perspective of someone installing this stuff.

So how do you create those placeholders? Turns out it relatively simple, and makes sense once you connect the dots.

To create placeholders, you create the variable values in the configuration templates. Go to Phones Configuration > Templates > select the phone template you want to adjust:

IPP Template

In the above example, I’m creating a multicast group for paging. Also, I kept the naming scheme consistent, but you don’t need to include “ITCS_” for the variable, as long as it matches later. (09/22/16) Correction: you do need to keep the naming scheme the same, at least from what I can tell in setting region placeholders. When you enter the placeholder name, IPP appends the name with “%ITCS_<yourPlaceHolder>%”.

Then, you can create your ‘Regions’ for customizing configurations, and then add your customized values to each region like this:

IPP Region Values

Next, change the region of the phone(s), if you haven’t done this already:

IPP Phone Options

Finally, update the phone configurations. Go to Users > Manage Multiple Devices, add the devices you want to update, select the action “Generate IP Phones Configuration Files” or “Update Configuration File”, then click “Generate IP Phones Configuration Files”:

IPP Update Config

Generating will restart the phone, updating will not. I prefer generating, but you may not want to avoid the phone restart.

That’s it.

AudioCodes has a great system here, and it’s pretty cool that it comes free. The only hiccup I’ve encountered with the program so far is that I have some phones that I can’t issue commands to for some reason. There are some users that I can’t put in regions or update configurations, and when I try, IPP tells me that the user is not approved, but when I try to approve the user, it says the user is already approved. It’s very strange, and thankfully I don’t worry about it much because the users are in the default region, but I could see this being an issue for sure. I haven’t reached out to AudioCodes yet for support, but I’ll update something here when I do.

Happy phone managing!