Best of Both Worlds: Safely Marrying Asterisk to OpenSIPS

Not all users on an Asterisk PBX need anonymous lurkers to have worldwide, public access to their individual phones. For most, DIDs suffice for public access. For users that do need such access, we will begin by creating a SIP account on your OpenSIPS server that is separate and apart from your Asterisk user account or extension. Also keep in mind that anonymous SIP calls require a match on the SIP URI to reach the person or function desired. You can enable and disable these SIP URI-accessible functions on your OpenSIPS server as desired. And you can determine how obscure to make each of the SIP URIs. Security through obscurity works and deters many SIP attacks. Now let’s address what you can and cannot do with this setup.

Using a SIP phone from anywhere in the world, any SIP user CAN:

• Make SIP URI calls to authorized extensions and ring groups on your Asterisk PBX
• Make SIP URI calls to authorized clients registered to a 3CX PBX with a SIP UUID
• With a legitimate password, make DISA-like calls with Asterisk trunks, if enabled
• With an invalid DISA password, converse with Lenny
• With a legitimate password, check and manage authorized Asterisk voicemail accounts
• With a legitimate password, participate in authorized Asterisk conferences
• Access other authorized Asterisk applications available from Asterisk extensions

Using a SIP phone from anywhere in the world, an OpenSIPS-registered User also CAN:

• Make PSTN calls from OpenSIPS-registered SIP phones, if enabled
• Receive calls from Asterisk forwarded to any OpenSIPS-registered SIP phone
• Receive calls from Asterisk forwarded to any 3CX-registered client or SIP phone

Using any SIP phone registered to a SIP proxy, you CANNOT:

• Log into any Asterisk user account without whitelist permission and credentials
• Make 911 calls

Prerequisites: To complete today’s setup, we’re assuming you have (1) an Incredible PBX server running Asterisk 13, (2) an OpenSIPS server built with version 1.2.0 or later of the Incredible PBX for OpenSIPS installer, and (3) either a registered SIP account and SIP URI on your OpenSIPS PBX or a SIP account with a provider such as a free linphone.org account.

Running pbxstatus on your OpenSIPS server will tell you which version you have. If you don’t have pbxstatus or the version is below 1.2.0, please initialize your Debian 8 platform, download the latest release, and reinstall following the our OpenSIPS tutorial here. There were major changes in the OpenSIPS configuration to support Asterisk connectivity which made an in place upgrade too complex. Our apologies.

Before creating user accounts on your OpenSIPS server, give some thought to a numbering scheme that won’t conflict with extension registrations on your Asterisk server. For example, if your Asterisk server uses extensions 701 through 750, then you may wish to consider using 7701 through 7750 on your OpenSIPS server. The one-to-one match keeps things simple without running into conflicts between the Asterisk extension numbers and the OpenSIPS user accounts. We’ll use the 700 (Asterisk) and 7700 (OpenSIPS) extension ranges in our examples which follow. And we’ve reworked the original OpenSIPS tutorial in keeping with this design to simplify Asterisk integration for new readers just joining the party.

We want to express our sincere appreciation to Bill Simon for his patient tutelage in walking us through some of the potential landmines in marrying an OpenSIPS server with Asterisk. Should your organization ever need professional help with a SIP deployment, there is no finer SIP authority than Simon Telephonics.

Assuming you have an Incredible PBX 13 platform, open the GUI as admin using a browser from your desktop. First, let’s create a Trunk for the OpenSIPS server. Choose Connectivity -> Trunks -> Add SIP (chan_sip) Trunk. For Trunk Name, use opensips. Next, click on the SIP Settings tab in the dialog. For Trunk Name, again use opensips. In PEER DETAILS, enter the following and replace xxx.xxx.xxx.xxx twice with the actual IP address of your OpenSIPS server. Then click Submit and Reload Dialplan when prompted.

type=peer
host=xxx.xxx.xxx.xxx
context=from-opensips
insecure=port,invite
disallow=all
allow=ulaw
deny=0.0.0.0/0.0.0.0
permit=xxx.xxx.xxx.xxx/255.255.255.255

Next, using SSH or Putty, login to your Asterisk server as root and issue these commands replacing xxx.xxx.xxx.xxx with the IP address of your OpenSIPS server (choose option 0 when prompted for access type):

cd /root
./add-ip opensips xxx.xxx.xxx.xxx
wget http://incrediblepbx.com/from-opensips.tar.gz
tar zxvf from-opensips.tar.gz
rm -f from-opensips.tar.gz
nano -w from-opensips.txt

When the editor opens, scroll down to line 16 and enter a very secure PIN (up to 10 digits) for access to the DISA-like service to make outbound calls via SIP URI. It’s your phone bill so make it long (up to 10 digits) and something that is not easily guessed. On line 20, we have configured DISA for numbers up to 11 digits. If your dialplan requires international dialing support, you can adjust 11 to the desired number of digits. Then save the file and copy the dialplan code into extensions_custom.conf and reload your dialplan:

cd /etc/asterisk
cat /root/from-opensips.txt >> extensions_custom.conf
asterisk -rx "dialplan reload"

IMPORTANT NOTE: Just because you have configured this DISA option on your Asterisk server does not mean it is available via SIP URI. In fact, no SIP URI access to your Asterisk server is enabled at this juncture. You still must set up the SIP URI connections on your OpenSIPS server. Whether to do that and which features to activate are completely up to you.

Beginning with version 1.2.0 of the Incredible PBX installer for OpenSIPS, the server itself is preconfigured to support Asterisk connectivity using AVPs. Implementation only requires command line execution of an AVP script to enable each feature you wish to activate. A similar script can be used to deactivate any AVP feature previously activated. To install the scripts on your OpenSIPS server, log in as root using SSH or Putty and issue these commands:

cd /root
wget http://incrediblepbx.com/asterisk-features-for-opensips.tar.gz
tar zxvf asterisk-features-for-opensips.tar.gz
rm -f asterisk-features-for-opensips.tar.gz

The function of each of the Asterisk scripts is self-explanatory from the script names:

• asterisk-add-forward
• asterisk-delete-forward
• asterisk-list-forwards

Three pieces of information are required to add a SIP URI forward from OpenSIPS to your Asterisk server using the AVP asterisk-add-forward script:

• UUID of SIP URI (from any SIP phone, dial UUID@opensips.yourdomain.com to connect)
• Asterisk Extension (destination where incoming OpenSIPS call should be forwarded)
• Asterisk Public IP Address

To add a SIP URI for extension 701 on your Asterisk server at xx.xx.xx.xx reachable at 701@opensips.yourdomain.com, the command would look like this where xx.xx.xx.xx is the public IP address of your Asterisk server and opensips.yourdomain.com is the FQDN of your OpenSIPS server: /root/asterisk-add-forward 701 701 xx.xx.xx.xx

CAUTION: Other than for forwards like this, do NOT set up User accounts in the OpenSIPS Control Panel using the same numbers as existing extensions on your Asterisk server. Otherwise, if your SIP phone is registered to a 701 user account on your OpenSIPS server, you lose the ability to connect to any extension on your Asterisk server if a 701 account requiring registration also existed on the Asterisk platform.

To use a name in the SIP URI or enable a second SIP URI for the same Asterisk 701 extension (jdoe@opensips.yourdomain.com): /root/asterisk-add-forward jdoe 701 xx.xx.xx.xx

Simply repeat the steps above for every SIP URI you wish to enable for an Asterisk extension.

To enable DISA-like access via SIP URI using dial as UUID (dial@opensips.yourdomain.com): /root/asterisk-add-forward dial *1 xx.xx.xx.xx

Keep in mind that you need not use "dial" as the UUID. You can make up any name you like. So long *1 is the DISA extension, the UUID can be as obscure as desired e.g. disa5038now.

For voicemail access via SIP URI, you can do it in two ways. For generic access triggering prompts for both the voice mailbox number and the mailbox PIN, use the following: /root/asterisk-add-forward vm *98 xx.xx.xx.xx

For voicemail access to a specific mailbox (701) with only a prompt for the mail PIN, use: /root/asterisk-add-forward vm701 *98701 xx.xx.xx.xx

For access to a specified conference (2663) with a prompt for the conference PIN, use: /root/asterisk-add-forward conf2663 2663 xx.xx.xx.xx

For access to Weather Reports (947) with a prompt for the ZIP Code, use something like this: /root/asterisk-add-forward weather 947 xx.xx.xx.xx

For News Headlines (951), use: /root/asterisk-add-forward news 951 xx.xx.xx.xx

To delete any previously created UUID forward: /root/asterisk-delete-forward

To list existing UUID forwards for SIP URIs: /root/asterisk-list-forwards

Calling Tip: If your softphone is registered to an OpenSIPS User account, you can call any of the enabled forwarding entries by entering the UUID without @opensips.yourdomain.com, e.g. dialing vm would connect to the Asterisk voicemail system with a prompt for mailbox.

In today’s design, incoming calls to your Asterisk PBX can be forwarded to a user account on your OpenSIPS server or a free linphone.org user account by (1) creating a free User account in the OpenSIPS Control Panel or at linphone.org, (2) logging into that user account with a SIP phone or softphone, (3) creating a custom extension in the Incredible PBX GUI that points to the SIP URI of your user account on the OpenSIPS server or your free linphone.org SIP user account or a 3CX client, and (4) adding that custom extension to either a Ring Group that includes your Asterisk extension or enabling FindMe/FollowMe for your Asterisk extension and designating the custom extension as the No Answer Destination. Need support for multiple Asterisk users? Not a problem. Repeat the drill for each user.

The procedure for adding a User Account in the OpenSIPS Control Panel was covered in last week’s article. The procedure for creating a free Linphone User Account was covered in an earlier article so we won’t repeat it here. Another obvious SIP URI destination is any 3CX Client if you’ve previously set up a free 3CX server following our 3CX tutorial. Refer back to those articles if you need a refresher.

On the Asterisk side, login to the Incredible PBX GUI as admin with your favorite browser. Then choose Applications -> Extensions -> Add Custom Extension. For the User Extension and Display Name, we recommend using the 7701 numbering scheme for remote accounts. Then click on the Advanced tab and enter the SIP URI of your OpenSIPS, Linphone, or 3CX User account as the Dial option, e.g. SIP/yourname@sip.linphone.org or SIP/7701@opensips.yourdomain.com. Click Submit and Apply Config to reload dialplan.

To assure that incoming calls ring on both your Asterisk phone (701) and your registered SIP phone, we recommend setting up a Ring Group on the Asterisk side that includes both the 701 extension and the new 7701 custom extension. Then adjust your Inbound Routes to point to the number of this Ring Group instead of to 701. In this way, you can preserve the voicemail functionality associated with your 701 extension. FYI: None of these servers proxy audio and video of your calls. They provide a SIP registration service only.

The other alternative to a Ring Group is to enable FindMe/FollowMe in the 701 extension settings and then specify Extension:701 as the No Answer Destination. With this approach, voicemail will never be triggered on calls sent to extension 701 on your PBX. Since OpenSIPS lacks voicemail, you would lose calls not answered on your registered SIP phone or softphone.

TIP: We use 3CX clients exclusively for inbound calls on iPhones and Android devices because we have found they are far superior in dealing with both push notifications and NAT routing. 3CX clients actually ring when someone calls AND you can hear both sides of every call.

The DISA setup documented above allows your existing Trunks to continue to be managed and secured exclusively on your Asterisk server with no trunk exposure on the OpenSIPS platform at all. Thus, if either your public-facing OpenSIPS server or Linphone is ever compromised, nobody will be able to make any calls on your nickel because there will be no trunks available to process the outbound calls. Your DISA password is never exposed.

For some (like us), a two-step outbound calling procedure is just too painful. In that case, with providers such as Skyetel, you can deploy a PSTN calling platform on both your Asterisk server and on OpenSIPS. We documented the Skyetel trunk setup for OpenSIPS in our tutorial last week. The good news is nothing precludes deployment of Skyetel at multiple sites even if you only use Skyetel on the OpenSIPS platform for outbound calling. And this completely avoids implementing a DISA solution which has security implications of its own. Effective 10/1/2023, $25/month minimum spend at Skyetel is required.

Enabling direct PSTN calling with OpenSIPS means nobody can ever make PSTN calls merely by guessing a SIP URI. It requires an actual SIP registration to OpenSIPS, and you have Fail2Ban to assist with securing that process. So the outbound calling design is completely up to you. Direct PSTN calling from OpenSIPS is no less safe so long as none of your OpenSIPS User account passwords are compromised.

For OpenSIPS AVP forwards that have been enabled to Asterisk extensions, you probably will also want to provide a way for Asterisk users to return those calls directly to OpenSIPS users since that will be the CallerID that displays when an OpenSIPS user places a call directly to a forwarded Asterisk extension. Assuming a SIP phone has been registered to User account 7709, when that OpenSIPS user places a call to a forwarded Asterisk extension 701, it means the Asterisk user will see 7709 displayed as the CallerID for the incoming call even though the User of the OpenSIPS 7709 extension may also be associated with extension 709 on the Asterisk side. If the Asterisk callee attempts to return the call by dialing 7709 instead of 709, the call would fail. To avoid confusion by Asterisk users, the simple solution is to add an additional Custom SIP extension for every OpenSIPS User account.

For example, on the Asterisk side, login to the Incredible PBX GUI as admin with your favorite browser. Then choose Applications -> Extensions -> Add Custom Extension. For the User Extension, enter 7709. For the Display Name, enter the name of the person using that OpenSIPS user account. Next, click on the Advanced tab and enter the SIP URI for this OpenSIPS User account as the Dial option, e.g. SIP/7709@opensips.yourdomain.com. Click Submit and Apply Config to reload dialplan.

FYI: Matching Custom Extension numbers on the Asterisk platform to identical extensions on your OpenSIPS server does not create the registration problems we cautioned against earlier. Only Asterisk extensions requiring actual SIP registration need to remain unique from accounts on your OpenSIPS platform.

If you’ve been using Incredible PBX with its Travelin’ Man 3 firewall, it’s not unlike living in a gated community where most of the outside world doesn’t even know you exist. Adding a "second home" with OpenSIPS is not unlike buying a summer place next door to Fred Sanford in Watts. You might as well have set up shop in the middle of Russia because, for all intents and purposes, you have. Anybody in the world can guess your IP address and spend the day trying to break into your server. So the name of the game is vigilance. Especially for the first few weeks, you need to run iptables -nL regularly and see how quickly your Fail2Ban blacklist is filling up. If you heeded our advice and set up your OpenSIPS server on a KVM platform (instead of OpenVZ), we’ve got a handy little script that will let you move bad guys snagged by Fail2Ban to the permanent IPset blacklist. Just download the script and run it daily to move the Fail2Ban entries to permanent block status in the IPset blacklist:

cd /root
wget http://incrediblepbx.com/move-fail2bans-to-ipset.tar.gz
tar zxvf move-fail2bans-to-ipset.tar.gz
rm -f move-fail2bans-to-ipset.tar.gz
./move-fail2bans-to-ipset

Once you have verified that the IP addresses actually are being populated in the IPset blacklist table (ipset list | sort), you can add the script to /etc/crontab to run automatically each night:

echo "2 4 * * * root /root/move-fail2bans-to-ipset > /dev/null 2>&1" >> /etc/crontab

If you’d like a head start on your IPset blacklist, simply download our latest list and then reboot your server:

cd /etc
wget http://incrediblepbx.com/badguys.tar.gz
tar zxvf badguys.tar.gz
rm -f badguys.tar.gz 

Another potential vulnerability is SSH. This command will tell you who has attempted to login to your server as root: cat /var/log/auth.log | grep password. If you ever see a failed login and it wasn’t a mistake on your part, change your SSH access port immediately if not sooner: nano -w /etc/ssh/sshd_config. Then restart SSH: /etc/init.d/ssh restart. Better yet, set up SSH public key authentication.

The other major consideration is the number of holes you punch into the security of your Asterisk server using the OpenSIPS asterisk-add-forward script. Every time you add an extension to this list, you open another (read-only) window into your Asterisk communications world. And anybody can connect to these extensions using either the FQDN of your OpenSIPS server or its IP address. Even though we don’t practice what we preach, we strongly recommend using alphanumeric UUIDs instead of numbers for these access points. That at least avoids random calls from bad guys that are accustomed to numeric numbers only in SIP URIs. Regularly review your OpenSIPS log for unusual strings of forwarded calls and adjust your forwarding UUIDs accordingly: cat /var/log/opensips.log | grep forwarded.

In our previous article, we’ve already addressed how important it is to limit User accounts to your FQDN and never the IP address of your OpenSIPS server. In this way, you limit OpenSIPS registration exposure to your FQDN and never the IP address of your server. Fail2Ban also assists here by blocking failed login attempts after a single failure unless you have whitelisted the IP address in Fail2ban’s ignoreip list in /etc/fail2ban/jail.conf and restarted Fail2Ban with this command: /etc/init.d/fail2ban restart. These are the only entry points that offer the ability to actually register to your server. AVPs never do. Obviously, a successful SIP registration is much more dangerous than a random phone call on a SIP URI set up using AVP extension forwarding.

Finally, passwords now matter on your Asterisk PBX for any port forward you’ve established with OpenSIPS. For example, if you’ve set up a generic forward to access voicemail, then it means anybody guessing the SIP URI you created can spend the day (at no cost) attempting to break into ANY voicemail account on your Asterisk server by guessing the PIN. Fail2Ban will not protect you here. If you’ve set up DISA-like access to your Asterisk server on OpenSIPS, then the same applies except now the attacker gets a blank check to make commercial calls if they can guess your access PIN. Worried yet? We hope so. Sure beats a $100,000 phone bill.

We usually provide a Demo Line for readers to try out our latest creations. For obvious reasons, we prefer not to disclose our OpenSIPS FQDN to the general public. But we have set up a port forward from a DID that we temporarily configured on our OpenSIPS server. So, if you’d like to sample the voice quality of placing a call to a DID in Atlanta forwarded to an OpenSIPS server in New York forwarded to an Asterisk server in Miami and then back to you, try calling 843-606-0555 for a weather report in your favorite ZIP code. We’re betting you will be dumbfounded by the quality of the call. Enjoy!

Originally published: Monday, May 20, 2019

Need help with Asterisk? Visit the VoIP-info Forum.

Special Thanks to Our Generous Sponsors

FULL DISCLOSURE: ClearlyIP, Skyetel, Vitelity, DigitalOcean, Vultr, VoIP.ms, 3CX, Sangoma, TelecomsXchange and VitalPBX have provided financial support to Nerd Vittles and our open source projects through advertising, referral revenue, and/or merchandise. As an Amazon Associate and Best Buy Affiliate, we also earn from qualifying purchases. We’ve chosen these providers not the other way around. Our decisions are based upon their corporate reputation and the quality of their offerings and pricing. Our recommendations regarding technology are reached without regard to financial compensation except in situations in which comparable products at comparable pricing are available from multiple sources. In this limited case, we support our sponsors because our sponsors support us.

BOGO Bonaza: Enjoy state-of-the-art VoIP service with a $10 credit and half-price SIP service on up to $500 of Skyetel trunking with free number porting when you fund your Skyetel account. No limits on number of simultaneous calls. Quadruple data center redundancy. $25 monthly minimum spend required. Tutorial and sign up details are here.

The lynchpin of Incredible PBX 2020 and beyond is ClearlyIP components which bring management of FreePBX modules and SIP phone integration to a level never before available with any other Asterisk distribution. And now you can configure and reconfigure your new Incredible PBX phones from the convenience of the Incredible PBX GUI.

VitalPBX is perhaps the fastest-growing PBX offering based upon Asterisk with an installed presence in more than 100 countries worldwide. VitalPBX has generously provided a customized White Label version of Incredible PBX tailored for use with all Incredible PBX and VitalPBX custom applications. Follow this link for a free test drive!
 

Special Thanks to Vitelity. Vitelity is now Voyant Communications and has halted new registrations for the time being. Our special thanks to Vitelity for their unwavering financial support over many years and to the many Nerd Vittles readers who continue to enjoy the benefits of their service offerings. We will keep everyone posted on further developments.