How to Install FreeSWITCH on Debian 12 with SignalWire Personal Access Tokens (PAT)

How to Install FreeSWITCH on Debian 12 with SignalWire Personal Access Tokens (PAT)

Introduction

FreeSWITCH is a robust, scalable, and open-source telecommunications platform that supports voice, video, messaging, and various signaling protocols. It is widely used to build private branch exchanges (PBXs), softswitches, conferencing systems, and VoIP gateways. If you’re looking to integrate FreeSWITCH with SignalWire — a modern cloud-based communication platform — you can do so using SignalWire’s Personal Access Tokens (PAT), enabling secure and streamlined API access.

This guide walks you through installing FreeSWITCH on Debian 12 (Bookworm) and integrating it with SignalWire using PATs. Whether you’re building a VoIP application, a conferencing system, or a cloud-based communications service, this setup is a flexible starting point.

Prerequisites

Before we begin, ensure the following:

• You have a Debian 12 (Bookworm) server with root or sudo privileges.
• Internet access is available on the server.
• You have a SignalWire account with a project and generated PAT.
• Basic understanding of Linux commands and configuration files.

Step 1: Update the System

Start by updating your package list and upgrading installed packages.

sudo apt update && sudo apt upgrade -y

Also, install essential build tools and dependencies:

sudo apt install -y git gnupg2 wget curl lsb-release

Step 2: Add the FreeSWITCH Repository

FreeSWITCH provides official packages for Debian-based systems. First, install the GPG key and repository:

wget -O - https://files.freeswitch.org/repo/deb/debian-release/fsstretch-archive-keyring.asc | sudo gpg --dearmor -o /usr/share/keyrings/freeswitch-archive-keyring.gpg

Then, add the FreeSWITCH repository to your APT sources:

echo "deb [signed-by=/usr/share/keyrings/freeswitch-archive-keyring.gpg] https://files.freeswitch.org/repo/deb/debian bookworm main" | sudo tee /etc/apt/sources.list.d/freeswitch.list

Update APT cache:

sudo apt update

Step 3: Install FreeSWITCH

Install FreeSWITCH core packages and modules:

sudo apt install -y freeswitch-meta-all freeswitch-lang-en

This will install:

• The core FreeSWITCH binary
• Default configuration
• English sound files
• Common modules

To enable FreeSWITCH to start on boot and start the service:

sudo systemctl enable freeswitch
sudo systemctl start freeswitch

Verify it’s running:

sudo systemctl status freeswitch

If successful, FreeSWITCH should be listening on port 5060 (SIP).

Step 4: Configure UFW (Optional but Recommended)

If you are using UFW, open necessary ports:

sudo ufw allow 5060/udp     # SIP
sudo ufw allow 5080/udp     # Alternative SIP
sudo ufw allow 8021/tcp     # FreeSWITCH CLI interface
sudo ufw allow 16384:32768/udp  # RTP media
sudo ufw reload

Step 5: Create a SignalWire Project and Generate PAT

1. Go to https://signalwire.com and sign in or create an account.

2. Create a Project.

3. Navigate to API > Access Tokens.

4. Click “Create New Token” and generate a Personal Access Token.

5. Note the following:

   • Project ID
   • Space URL (e.g., your-space.signalwire.com)
   • PAT

These credentials will be used for authentication and integration.

Step 6: Install mod_signalwire

FreeSWITCH supports integration with SignalWire through the mod_signalwire module.

A. Compile from Source (if not included)

If the module is not available in the Debian package, you can build it:

cd /usr/src
sudo git clone https://github.com/signalwire/freeswitch.git
cd freeswitch
sudo ./bootstrap.sh -j
sudo ./configure
sudo make mod_signalwire-install

This will build and install the module under the proper directory.

B. Load the Module

To load mod_signalwire, add it to the FreeSWITCH autoload modules list:

echo "load mod_signalwire" | sudo tee -a /etc/freeswitch/autoload_configs/modules.conf.xml

Or manually edit the XML file:

sudo nano /etc/freeswitch/autoload_configs/modules.conf.xml

Add:

<load module="mod_signalwire"/>

Restart FreeSWITCH:

sudo systemctl restart freeswitch

Step 7: Configure SignalWire Settings in FreeSWITCH

Now create a configuration file for mod_signalwire.

Create or edit /etc/freeswitch/autoload_configs/signalwire.conf.xml:

sudo nano /etc/freeswitch/autoload_configs/signalwire.conf.xml

Paste the following, replacing with your actual credentials:

<configuration name="signalwire.conf" description="SignalWire Configuration">
  <settings>
    <param name="project" value="YOUR_PROJECT_ID"/>
    <param name="token" value="YOUR_PAT"/>
    <param name="space" value="your-space.signalwire.com"/>
    <param name="context" value="public"/>
  </settings>
</configuration>

Replace:

• YOUR_PROJECT_ID with your SignalWire project ID.
• YOUR_PAT with your Personal Access Token.
• your-space.signalwire.com with your SignalWire space domain.

Save and exit.

Step 8: Test the Integration

To verify that the module is loaded and your credentials are working:

1. Launch the FreeSWITCH CLI:

sudo fs_cli

2. Check module status:

module_exists mod_signalwire

If it returns true, the module is loaded.

3. Look at logs:

log level debug

Check for any authentication or network issues related to SignalWire.

Step 9: (Optional) Configure SignalWire SIP Trunks

If you wish to route calls via SignalWire SIP, you’ll need to add a gateway to your FreeSWITCH configuration.

Example Gateway:

Edit or create the following file:

sudo nano /etc/freeswitch/sip_profiles/external/signalwire.xml

Add the following:

<include>
  <gateway name="signalwire">
    <param name="username" value="YOUR_SIP_USERNAME"/>
    <param name="password" value="YOUR_SIP_PASSWORD"/>
    <param name="proxy" value="YOUR_SPACE.sip.signalwire.com"/>
    <param name="register" value="true"/>
    <param name="realm" value="YOUR_SPACE.sip.signalwire.com"/>
  </gateway>
</include>

Note: You must configure SIP credentials in your SignalWire project for this to work.

Reload the SIP profiles:

fs_cli -x "reloadxml"
fs_cli -x "sofia profile external rescan"

Step 10: Security and Hardening

• Use strong passwords for all SIP endpoints.
• Enable TLS if you’re transmitting calls over the Internet.
• Regularly update FreeSWITCH and dependencies.
• Use fail2ban to prevent brute-force attacks.

Example fail2ban for FreeSWITCH (based on logs):

sudo apt install fail2ban

Configure a jail in /etc/fail2ban/jail.local for FreeSWITCH:

[freeswitch]
enabled = true
port = 5060,5061
filter = freeswitch
logpath = /var/log/freeswitch/freeswitch.log
maxretry = 5
bantime = 3600

You can customize this further depending on your usage.

Conclusion

Installing FreeSWITCH on Debian 12 and integrating it with SignalWire using Personal Access Tokens (PAT) is a powerful combination. SignalWire brings modern cloud infrastructure to traditional telephony systems, while FreeSWITCH provides the flexibility and performance for real-time communications.

By following this guide, you now have a basic setup ready to handle calls, messages, or other programmable interactions. You can extend this by:

• Adding IVRs and call routing logic
• Integrating with webhooks or APIs
• Building a full contact center or conferencing solution

FreeSWITCH’s modularity and SignalWire’s cloud APIs make it a solid foundation for next-gen telecommunication systems.

If you’d like a follow-up guide on advanced call routing or building a custom dialplan using SignalWire events, let me know!