---
title: "How to Install FreeSWITCH on Debian 12 for SIP Calls"
description: "Install FreeSWITCH on Debian 12 from the official SignalWire repository, secure the defaults, create SIP extensions and place test calls between softphones."
category: "VoIP and Communication"
language: en
source: https://cubepath.com/docs/voip-and-communication/freeswitch-voip-server-installation
updated: 2026-09-25
---
# How to Install FreeSWITCH on Debian 12 for SIP Calls
FreeSWITCH is an open-source telephony platform that can act as a SIP PBX, a media server, a conference bridge or a softswitch between carriers. In this tutorial you will install FreeSWITCH 1.10 on Debian 12 from the official packages published by SignalWire, lock down the insecure defaults, configure two SIP extensions and verify that they can call each other, reach the echo test and join a conference room.
## Prerequisites
To follow this guide you need:
- A server running Debian 12 (bookworm), 64-bit, for example a CubePath VPS. The official FreeSWITCH packages are built for Debian; Ubuntu is not a supported target for them.
- A non-root user with `sudo` privileges.
- At least 1 GB of RAM (2 GB is more comfortable if you plan to run conferences or transcoding).
- A public IPv4 address on the server. SIP behind NAT works, but it needs extra configuration that is out of scope here.
- A free SignalWire account, used only to generate the Personal Access Token (PAT) that gives access to the package repository.
- Two SIP softphones for testing, for example Linphone, Zoiper or MicroSIP, on a desktop or phone.
## Step 1 - Getting a SignalWire access token
Since 2022 the FreeSWITCH binary repository requires authentication. The token is free and is only used by apt to download packages.
1. Sign in to your SignalWire account.
2. Open your profile menu and go to **Personal Access Tokens**.
3. Create a new token and copy its value.
On the server, store the token in a shell variable for the next commands. Replace `your_signalwire_token` with the value you copied:
```bash
TOKEN=your_signalwire_token
```
The variable only lives in your current shell session, so run the commands in Step 2 from the same terminal.
## Step 2 - Adding the FreeSWITCH repository
Install the tools needed to fetch the repository key:
```bash
sudo apt update
sudo apt install -y gnupg2 wget lsb-release
```
Download the repository signing key. The repository uses HTTP basic authentication with the fixed user `signalwire` and your token as the password:
```bash
sudo wget --http-user=signalwire --http-password="$TOKEN" \
-O /usr/share/keyrings/signalwire-freeswitch-repo.gpg \
https://freeswitch.signalwire.com/repo/deb/debian-release/signalwire-freeswitch-repo.gpg
```
Give apt the credentials so that `apt update` can authenticate. The file is restricted to root because it contains the token:
```bash
echo "machine freeswitch.signalwire.com login signalwire password $TOKEN" | sudo tee /etc/apt/auth.conf > /dev/null
sudo chmod 600 /etc/apt/auth.conf
```
Add the repository itself:
```bash
echo "deb [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] https://freeswitch.signalwire.com/repo/deb/debian-release/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/freeswitch.list
```
Refresh the package index and confirm that apt sees the FreeSWITCH packages:
```bash
sudo apt update
apt-cache policy freeswitch
```
```output
freeswitch:
Installed: (none)
Candidate: 1.10.x~release~...~bookworm
Version table:
1.10.x~release~...~bookworm 500
500 https://freeswitch.signalwire.com/repo/deb/debian-release bookworm/main amd64 Packages
```
If `apt update` returns `401 Unauthorized`, the token in `/etc/apt/auth.conf` is wrong or has been revoked.
## Step 3 - Installing FreeSWITCH
The `freeswitch-meta-all` package pulls in the core, the common modules, the default ("vanilla") configuration and the English sound prompts:
```bash
sudo apt install -y freeswitch-meta-all
```
Check that the configuration was installed in `/etc/freeswitch`:
```bash
ls /etc/freeswitch
```
```output
autoload_configs dialplan directory freeswitch.xml ivr_menus sip_profiles vars.xml ...
```
If the directory is empty, copy the vanilla configuration shipped with the packages and give it to the `freeswitch` user:
```bash
sudo cp -a /usr/share/freeswitch/conf/vanilla/. /etc/freeswitch/
sudo chown -R freeswitch:freeswitch /etc/freeswitch
```
Enable and start the service:
```bash
sudo systemctl enable --now freeswitch
sudo systemctl status freeswitch --no-pager
```
```output
● freeswitch.service - freeswitch
Loaded: loaded (/lib/systemd/system/freeswitch.service; enabled; preset: enabled)
Active: active (running) since ...
```
FreeSWITCH ships with `fs_cli`, a console that connects to the running server through the Event Socket on `127.0.0.1:8021`. Use `-x` to run a single command:
```bash
sudo fs_cli -x "status"
```
```output
UP 0 years, 0 days, 0 hours, 1 minute, 12 seconds, 530 milliseconds, 41 microseconds
FreeSWITCH (Version 1.10.x ...) is ready
...
```
## Step 4 - Securing the default configuration
The vanilla configuration is designed for a lab. Before exposing the server to the internet, fix the three settings that SIP scanners look for first.
### Change the default SIP password
All the sample users (extensions 1000 to 1019) share the password defined by `default_password` in `vars.xml`, and its default value is `1234`. FreeSWITCH even adds a 10 second delay to calls while it stays unchanged. Open the file:
```bash
sudo nano /etc/freeswitch/vars.xml
```
Find the line that sets `default_password` and replace `1234` with a long random value:
```xml
```
You will give the extensions you actually use their own passwords in Step 5, so this value only protects the unused sample users. Generate a suitable string with `openssl rand -base64 24` if you need one.
### Keep the Event Socket on localhost
Anyone who can reach port 8021 with the default password `ClueCon` has full control of the server. Open the Event Socket configuration:
```bash
sudo nano /etc/freeswitch/autoload_configs/event_socket.conf.xml
```
Make sure `listen-ip` is the loopback address:
```xml
```
You will not open port 8021 in the firewall, so only local tools such as `fs_cli` can use it.
### Open only the ports you need
Allow SSH first so you do not lock yourself out, then SIP on the internal profile (5060) and the RTP media range used by FreeSWITCH (16384 to 32768 UDP):
```bash
sudo apt install -y ufw
sudo ufw allow OpenSSH
sudo ufw allow 5060/udp
sudo ufw allow 5060/tcp
sudo ufw allow 16384:32768/udp
sudo ufw enable
```
The `external` SIP profile listens on port 5080 and is meant for carrier trunks. Leave it closed until you add a trunk, and then allow it only from your provider's IP addresses.
Restart FreeSWITCH to apply the new passwords and Event Socket settings:
```bash
sudo systemctl restart freeswitch
```
## Step 5 - Configuring SIP extensions
Users live in `/etc/freeswitch/directory/default/`, one XML file per extension. The default dialplan already routes calls to any extension between 1000 and 1019, so you only need to give two of them their own passwords.
Open the file for extension 1000:
```bash
sudo nano /etc/freeswitch/directory/default/1000.xml
```
Replace the `password` parameter, which points to `$${default_password}`, with a unique password, and set a caller ID name:
```xml
```
Do the same in `1001.xml` with a different password and caller ID name. Then reload the XML configuration without dropping active calls:
```bash
sudo fs_cli -x "reloadxml"
```
```output
+OK [Success]
```
Check that the internal SIP profile is running:
```bash
sudo fs_cli -x "sofia status"
```
```output
Name Type Data State
=================================================================================================
external-ipv6 profile sip:mod_sofia@[...]:5080 RUNNING (0)
internal profile sip:mod_sofia@203.0.113.10:5060 RUNNING (0)
external profile sip:mod_sofia@203.0.113.10:5080 RUNNING (0)
...
```
## Step 6 - Registering softphones and testing calls
Configure each softphone with these values, replacing `your_server_ip` with the public IP address of the server:
| Setting | Softphone A | Softphone B |
|---|---|---|
| Username / extension | `1000` | `1001` |
| Password | password from `1000.xml` | password from `1001.xml` |
| Domain / server | `your_server_ip` | `your_server_ip` |
| Transport | UDP, port 5060 | UDP, port 5060 |
Once both clients show as registered, confirm it from the server:
```bash
sudo fs_cli -x "show registrations"
```
```output
reg_user,realm,token,url,expires,network_ip,network_port,network_proto,hostname,metadata
1000,203.0.113.10,...,sofia/internal/sip:1000@198.51.100.20:5060,...
1001,203.0.113.10,...,sofia/internal/sip:1001@198.51.100.21:5060,...
2 total.
```
Now test the dialplan that ships with the vanilla configuration:
- From 1000, dial `1001`. The other softphone should ring and you should hear audio in both directions.
- Dial `9196` to reach the echo test. You should hear your own voice back, which proves that RTP flows through the firewall.
- Dial `3000` from both phones to join the same conference room.
To watch calls in real time, open the interactive console (type `/exit` to leave it):
```bash
sudo fs_cli
```
## Step 7 - Adding your own dialplan extension
Custom routing belongs in its own file under `/etc/freeswitch/dialplan/default/`, which the main `default.xml` includes automatically. Keeping your changes there makes upgrades of the vanilla files painless.
Create a file for a "front desk" number, 5000, that plays a greeting and then rings extension 1000:
```bash
sudo nano /etc/freeswitch/dialplan/default/10_front_desk.xml
```
```xml
```
Set the owner, reload the configuration and dial `5000` from extension 1001:
```bash
sudo chown freeswitch:freeswitch /etc/freeswitch/dialplan/default/10_front_desk.xml
sudo fs_cli -x "reloadxml"
```
You should hear the welcome prompt, after which extension 1000 rings.
## Troubleshooting
**`apt update` fails with 401 Unauthorized.** The repository credentials are missing or the token was revoked. Check the content of `/etc/apt/auth.conf` and generate a new token in SignalWire if needed.
**Softphones fail to register.** Increase SIP logging, try to register again, then turn it off:
```bash
sudo fs_cli -x "sofia global siptrace on"
sudo journalctl -u freeswitch -f
sudo fs_cli -x "sofia global siptrace off"
```
A `403 Forbidden` reply means a wrong username or password. No reply at all usually means port 5060 is blocked by a firewall.
**Calls connect but there is no audio or only one-way audio.** Confirm that the RTP range is open with `sudo ufw status`, and check which public IP FreeSWITCH advertises in its SDP:
```bash
sudo fs_cli -x "sofia status profile internal" | grep -i "ext-rtp-ip"
```
By default it discovers the address with STUN. If the value is wrong, set it explicitly in `vars.xml` by changing `external_rtp_ip` and `external_sip_ip` to your public IP, then restart FreeSWITCH.
**The service does not start.** Read the last log lines, which usually point to an XML syntax error and the file that contains it:
```bash
sudo journalctl -u freeswitch -n 50 --no-pager
```
## Conclusion
You now have FreeSWITCH running on Debian 12 from the official repository, with the default passwords replaced, the Event Socket restricted to localhost, two working SIP extensions and a custom dialplan entry. From here you can connect a SIP trunk on the `external` profile to make and receive PSTN calls, enable TLS and SRTP on the internal profile to encrypt signalling and media, or build IVR menus with the `ivr_menus` configuration or Lua scripts.