04 Apr 2019

Notes on FreeSWITCH

Here are some notes on FreeSWITCH from my journal working on telephony projects which interestingly is one of the most exhilarating things I have worked on in the last couple of years.

It’s in a raw form. I may one day take time to flesh it out better or even add more notes if I get the chance to work on new things.

  • Unless really necessary and you are badass at this already, always go with the simple installation instruction and not try to overthink things. The installation page details how you can install from some OS packages. Go with that. My fav is using Debian 8 (see the easy way section).
  • The configuration folder may defer depending on your installation method and OS. Normally, you will find it /etc/freeswitch. (Your certs will be in /etc/freeswitch/tls)
  • Very important!!!! Change the default password in /etc/freeswitch/vars.xml. I can’t over emphasise this enough. There are many other default configs you can change in the file so go through it.
  • If you are going to be connecting via websockets (I’d assume you are doing some webRTC/browser play here), put SSL on it. Your browser will most likely not connect to ws alone so you have to make it wss (same way you add s to http to become https you know). Your quick bet? Letsencrypt. But because you can’t generate SSL for just an IP, you will have to also get a domain/register one and point it to the IP. Then put SSL on that domain. For experiments, I mostly just use subdomains of an existing domain I own.
    If you need to edit anything related to the web socket and SSL configuration (ports and all those things), see /etc/freeswitch/sip_profiles/internal.xml. One more thing, don’t forget auto renewal setup for your SSL. Either set it up in such a way it renews automatically or you are reminded to do it when due.
  • You most likely will need to update auto_conf/switch.conf as most of the default settings there are for child play. If you want to do heavy stuff, you will have to increase some of the limits set in that file. Some of the important things you should up are max-db-handles, max-sessions, sessions-per-second. Also very important, take note of the RTP ports. Ensure the difference between your rtp-start-port and rtp-end-port is a lot. It’s about 16k by default but if you are going to reduce or edit the ports, know what you are doing. Every call will use 4 ports meaning if your RTP ports are only 20, that will only allow 5 concurrent calls. The default ~16k is about 4k concurrent calls which should be ok.
    Remember, with great power comes great responsibility. If you are going to be upping settings to allow lots of connections, be sure your box has the required strength (CPU/RAM) to handle it (don’t miss the ulimit section of that page)
  • Ah firewall. There are two parts to this. One is that be careful when installing on a box that is already firewalled or has network restrictions. To start with, confirm all the ports that are available to you and be sure they are in FreeSWITCH’s typical ports. If any of the ports are permanently restricted on the box, then find a different provider. If it is that you need to enable the ports yourself, do so. I once did a setup on Google Compute Engine and had to start adding network rules to enable the ports. It was a tiring experience. For security reasons, I’d say that’s the best way to go but I’d rather just grab an open box from DigitalOcean and setup my firewall myself; which leads me to the second part.
    The second part is you need to restrict access to just the IPs your calls will be originating from. Granted if you get your FreeSWITCH settings right (and of course change that default password), no unauthorised call will be able to pass through, blocking other IPs won’t even allow them reach your box in the first place. This will save your FreeSWITCH a lot of stress from unauthorised requests and of course DOS.
  • The default configuration uses SQLite for some data storage. Under heavy load, the databases can get corrupted due to writes/second and locks. Options: switch the DB to an in-memory filesystem or use a different database that can handle the scale. If SQLite is already corrupted, backup the old db (will probably be at /var/lib/freeswitch/db and restart FreeSwitch. The dbs will be recreated.


Looking for a simple marketing automation tool to automate your customer onboarding, retention and lifecycle emails? Check out Engage and signup for free.


My name is Opeyemi Obembe. I build things for web and mobile and write about my experiments. Follow me on Twitter—@kehers.


Next post: 2018