Build your own Open Secure Telephony Network, some assembly required

The Open Secure Telephony Network is a standard that defines how to configure a VoIP softswitch with the capability to have secure two-way VoIP conversations if both parties are using the same server. The system requires both backend and frontend components, which makes OSTN is a little different than some of the other Guardian apps. Unlike Gibberbot, there are few public SIP services that support secure signalling for a mobile app to connect with. Notably offers free accounts. But it’s more fun to run your own.

Ready? Here’s the 12 step program.

The core server system is what provides user registration and media proxying. The reference application I used is called Freeswitch. It has a plethora of configuration options, so I chose to use a configuration management system called Chef to get everything set correctly.

  1. Bootstrap a Debian server. Right now the only supported platform for an automated installation is Debian 6 “Squeeze”. The adventerous may try to run the cookbook on another platform and do some bug fixing
  2. Install sudo, curl and git if you don’t already have them. apt-get install sudo curl git-core
  3. Get a static IP address. This is crucial! Your users will need a place to register from anywhere in the world
  4. Get a domain name. This is also crucial! Your users will prefer to register to a name rather than an IP address
  5. Configure a local hostname. This is a dependency for the cookbook to properly configure Freeswitch to serve your custom domain. Unfortunately, this process varies based on OS and has bizarre conventions that make no sense. Just follow the instructions and don’t ask questions. Remember to reboot after changing the hostname
  6. Install Chef from the opscode full stack.
  7. Download the freeswitch cookbook and execute it with chef-solo
  8. Walk away and have some coffee or a beer, depending on where the sun is relative to you
  9. When the Chef run is finished, Freeswitch will be up and running. Check with netstat -lntp you should see freeswitch listening on TCP port 5061
  10. Create users by running /opt/chef/embedded/bin/ruby /usr/local/freeswitch/scripts/gen_users. Without arguments, it will print the required parameters. Run it with an offset of 1000 and as many users as you like. Copy the XML files output by the script to /usr/local/freeswitch/conf/directory/default/ The script will also output a file with plaintext passwords so you can provision user handsets. Put this file somewhere safe and encrypted
  11. Reload the XML into Freeswitch’s memory. /usr/local/freeswitch/bin/fs_cli -x "reloadxml"
  12. Install CSipSimple and configure it to connect to your domain name with the username/password pair

If you make it through these steps, congratulations! You are now a Freeswitch operator. If you’re curious what is behind all of this and why it works, you should read about SIP, ZRTP and SDP. It’s also worth noting that the Chef cookbook configures the server to act as an SSL Certificate Authority. This is used for Secure SIP. The current landscape of using commercially signed certificates in Freeswitch is far more complicated than any HTTPS web server you may have worked with.

If you’d like to get help from me or another Guardian Project hacker, you can create issues in our tracker and message SteeleNivenson on Freenode or OFTC in channel #guardianproject. Oh yeah, and there’s Twitter @leeazzarello.

12 comments for “Build your own Open Secure Telephony Network, some assembly required

  1. eduardo
    2012/07/18 at 10:05 am

    deberias traducirlo al español saludos

  2. Paul
    2012/12/31 at 5:55 pm

    Unfortunately, the installs I did with this recipe were all broken upon upgrade from Precise to Quantal, and the cookbook no longer works, for reinstall on Quantal either.

  3. Lee
    2013/01/02 at 2:19 pm

    I’m targeting stable releases of Debian and Ubuntu with the cookbook. The Ubuntu website says the latest LTS release is 12.04. I’ll set up a server with 12.10. In the meantime, can you post the log output of the run failure you encountered?

  4. Jahil
    2013/02/28 at 12:33 pm

    I’m able to compiled it successfully on debian squeeze with cookbook, when a registering client on andorid: Error while registering – Forbidden.

    Any idea where i did wrong, btw i’m running it on AWS EC2.

  5. ubuntu-tester
    2013/06/13 at 10:55 pm

    chef is apparently worthless garbage , at least on ubuntu 12.04 –

    – first, the link given here only installs a chef-client (script? not even packages and config files correctly..), and definitely not all the ruby dependencies.. installing the apt repo only contains chef10 (why isn’t it current?)

    issue is that the chef-solo process starts up, looks like it might do something, but just sits there doing nothing, with a bunch of defunct ruby processes. opscode has no intelligent bug tracking of the issue anywhere – the problem is mentioned but the best answer someone can muster is “upgrade your kernel” — chef seems like a nice idea but just doesn’t work.

    so, question, whats the real ‘recipe’ for running this on ubuntu?

    > freeswitch
    > ?
    > certificate authority?

  6. ubuntu-tester
    2013/06/16 at 5:05 am

    more time wasted attempting to use upgraded ruby (1.9.3) with “rvm” tool and chef 11.4.4 installed via ruby-gems (however gems failed to load probably too many ruby environments by now).. also tried the deb file download for chef 11.4.2 . the default ruby version on ubuntu-precise is 1.8ish and opscode only has apt sources for versions prior to 12 (11 and back) – quite a few conflicting versions in all the different instructions and install methods..

    the only thing that happens when trying to run this, it says the chef version and forks a handful of defunct processes. (this is on a clean and fully updated install of “precise” release, kernel 3.2.0-48 x86_64 – have not tried this in a 32bit environment)

    FYI: after canceling the hung process, delete the pid file, but its not located where opscode says it should be in /var, but is somewhere in /tmp

    also, the posted method above REQUIRES the “sudo -i” step and THEN downloading the sources.. the ‘recipe’ assumes the files are located in /root/ .. why not “sudo ./start-cooking” or something portable?

    apparently when it says the instructions work for debian6 “squeeze” they must mean it really does not work with anything else.

    there are plenty of instructions for how to setup chef in a client/server situation, but not many for running ‘chef-solo’, which this requires. further digging shows a very few potentially related issues registered, but they aren’t resolved.

    Good news is that the configuration directives in the cookbooks directory {app}/default.rb are fairly simple to read and figure out whats going on to do manually..

    forgetting about chef, these instructions work up to ssl and nginx, just need links/instructions on configuring nginx.. and a better description of what is needed for the “certificate authority” mentioned in this post.

  7. ubuntu-tester
    2013/06/17 at 2:12 am

    chef seems to be working with debian squeeze (64bit)

    link posted above for how to install chef points to the wrong instructions — that only installs chef client and you have to get the full chef stack and all dependencies.

    keep in mind some of the instructions on opscode website show using older versions of things.

    use this and ignore the “10.0” version stuff and add the apt repository as ‘squeeze main’ and it pulls down the current version. (browse the repo to see whats available)

    looks like they left out a ‘current’ version tree for “precise” dist (??)

  8. 2013/07/25 at 5:16 am

    Please consider releasing this as a pfSense package 😉

    the freeswitch package in pfSense 2.0 and 2.1 is very broken.

    The Fusion PBX wiki on pfSense links to outdated material.

    none of the other freeswitch GUI, , have pfSense instructions afaict

  9. 2014/03/15 at 5:49 pm

    Hello, I was able to get it working with Ubuntu 12.04

    From Android Csipsimple I’m able to register extensions and have them call each other.

    From JITSI, I can’t get it to register extensions. Which is kinda weird because it works with regular OSTEL.CO accounts.

    Any suggestions?

    • Guillermo
      2014/04/16 at 8:01 am

      Hi, could you post detailed as you have configured and the files you’ve used for them, thanks

  10. 2014/04/22 at 6:20 pm

    This configuration has been rendered obsolete in favor of a more flexible system, documented at

Leave a Reply

Your email address will not be published. Required fields are marked *