FreeSWITCH

Installation

This section covers installing FreeSWITCH v1.10 on Debian 12, using the official SignalWire repositories. While written for version 1.10, the steps should also work with future releases.

info

The mod_xml_radius module is required for RADIUS integration. Since it's not included in the pre-built packages, FreeSWITCH must be built from source.

If you already have FreeSWITCH installed with mod_xml_radius, you can skip this section and go directly to the Integration.

#
# 1. Start on a clean Debian 12.
#
# 2. Create SignalWire Personal Access Token at
#    https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Installation/how-to-create-a-personal-access-token/how-to-create-a-personal-access-token
#

# Set SignalWire Personal Access Token in the environment.
export TOKEN=<TOKEN>

# Install time sync service.
apt -y install chrony
systemctl start chrony
systemctl enable chrony

# Install general dependencies.
apt-get update && apt-get install -y git gnupg2 wget lsb-release

# Get SignalWire repo keys.
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

# Store auth details.
echo "machine freeswitch.signalwire.com login signalwire password $TOKEN" > /etc/apt/auth.conf
chmod 600 /etc/apt/auth.conf

# Configure SignalWire repository.
echo "deb [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] https://freeswitch.signalwire.com/repo/deb/debian-release/ `lsb_release -sc` main" > /etc/apt/sources.list.d/freeswitch.list
echo "deb-src [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] https://freeswitch.signalwire.com/repo/deb/debian-release/ `lsb_release -sc` main" >> /etc/apt/sources.list.d/freeswitch.list

# Update information about repositories.
apt-get update

# Install dependencies required for the build.
apt-get build-dep freeswitch

# Get the source. Use the -b flag to get a specific branch.
cd /usr/src/
git clone https://github.com/signalwire/freeswitch.git -bv1.10 freeswitch
cd freeswitch

# Because we're in a branch that will go through many rebases, it's
# better to set this one, or you'll get CONFLICTS when pulling (update).
git config pull.rebase true

# Bootstrap files for the build.
./bootstrap.sh -j

# Configure modules that you need to build.
# Enable: xml_int/mod_xml_radius
sed -i 's/^#xml_int\/mod_xml_radius/xml_int\/mod_xml_radius/' modules.conf

# ... and do the build.
./configure
make
make install

# Set owner and permissions.
cd /usr/local
groupadd freeswitch
adduser --quiet --system --home /usr/local/freeswitch --gecos "FreeSWITCH open source softswitch" --ingroup freeswitch freeswitch --disabled-password
chown -R freeswitch:freeswitch /usr/local/freeswitch/
chmod -R ug=rwX,o= /usr/local/freeswitch/
chmod -R u=rwx,g=rx /usr/local/freeswitch/bin/*

# Create symlink for freeswitch console fs_cli or add into PATH.
ln -s /usr/local/freeswitch/bin/fs_cli /usr/bin/fs_cli

# Create systemd config (check below for the file contents).
cat > /etc/systemd/system/freeswitch.service << 'EOF'
[Unit]
Description=freeswitch
Wants=network-online.target
Requires=network.target local-fs.target
After=network.target network-online.target local-fs.target

[Service]
; service
Type=forking
PIDFile=/usr/local/freeswitch/run/freeswitch.pid
; PermissionsStartOnly has been deprecated in favor of the ExecStart= and similar series, see:
; https://github.com/NixOS/nixpkgs/issues/53852
; PermissionsStartOnly=true
; -nonat disables Network Address Translation probing at FreeSWITCH start, which might not be what you want!
; blank ExecStart= line flushes the list
ExecStart=
ExecStart=/usr/local/freeswitch/bin/freeswitch -u freeswitch -g freeswitch -ncwait -rp
TimeoutStartSec=45
TimeoutStopSec=45
; Restart=always will ALWAYS restart FreeSWITCH even when you wish to stop it to debug and configure it
Restart=on-failure
UMask=0007

; exec
WorkingDirectory=/usr/local/freeswitch/bin
User=root
Group=daemon
LimitCORE=infinity
LimitNOFILE=100000
LimitNPROC=60000
;LimitSTACK=240
LimitRTPRIO=infinity
LimitRTTIME=7000000
IOSchedulingClass=realtime
IOSchedulingPriority=2
; See https://man7.org/linux/man-pages/man7/sched.7.html for scheduler settings that vary by O/S distribution
; the following 2 lines are recommended for bare-metal machines
CPUSchedulingPolicy=rr
CPUSchedulingPriority=89
; the following 3 lines were found by a user to work on a MacOS VM
CPUSchedulingPolicy=fifo
CPUSchedulingPriority=1
Nice=-19

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service via systemd.
systemctl daemon-reload
systemctl start freeswitch
systemctl enable freeswitch

Integration

To simplify the setup, we provide a configuration package specifically prepared for integration with JeraSoft Billing – download the config pack.

The package includes only the essential configuration files required for:

• General operation of FreeSWITCH
• RADIUS AAA
  • Authentication (of users)
  • Authorization (of calls)
  • Accounting
• Dynamic routing – based on SIP 300 redirect
• CDR files writing – for added reliability and backup

All unrelated modules and settings have been removed or disabled to keep the configuration clean and focused.

note

If you need additional features or wish to extend beyond this integration scope, please refer to the official FreeSWITCH documentation or consult their support team.

How to use the config pack

You can use the provided configuration in one of two ways:

• Option 1: Quick start (recommended)
  Fully replace the existing FreeSWITCH configuration with the provided package. This is ideal for new installations.

• Option 2: As a reference
  Use the package as a starting point or example when configuring an existing or custom FreeSWITCH setup.

Option 1: Quick start

Follow these steps to quickly set up FreeSWITCH for integration with JeraSoft Billing:

1. Install FreeSWITCH
   Perform a clean installation of FreeSWITCH with mod_xml_radius enabled.
   Refer to the Installation section above for detailed instructions.

2. Download the configuration package
   Get the JeraSoft-compatible config pack.

3. Replace existing configuration
   On your FreeSWITCH server, move the original /usr/local/freeswitch/conf config folder to a backup location, then copy in the new configuration:

   # Move the original config folder to a backup location
   mv /usr/local/freeswitch/conf /usr/local/freeswitch/conf.backup
   
   # Copy in the provided configuration
   cp -r /path/to/unzipped-config/conf /usr/local/freeswitch/
   
   # Set correct file ownership
   chown -R freeswitch:freeswitch /usr/local/freeswitch/conf

4. Edit integration variables
   Open /usr/local/freeswitch/conf/vars.xml and update the following placeholders:

   1. Replace all instances of JERASOFT_IP_ADDRESS with the IP address of your JeraSoft Billing server.
   2. Replace all instances of RADIUS_SECRET with your desired shared secret for RADIUS.

5. Configure CDR file rotation
   Create the file /etc/cron.d/freeswitch-cdr-rotate with the following content to enable regular rotation (this example rotates CDR files every 30 minutes):

   0,30 * * * * root /usr/local/freeswitch/bin/fs_cli -p ClueCon -x 'cdr_csv rotate'

6. Restart FreeSWITCH
   

   systemctl restart freeswitch

7. Finalize in JeraSoft
   Once parties, rates, and routes are configured in your JeraSoft Billing system, run test calls to verify integration.

JeraSoft collectors

For this integration, use the following collectors in your JeraSoft system:

• Files collector: "FreeSWITCH v1.10"
• RADIUS collector: "JeraSoft Billing Common"
• SIP collector: "Default RFC (with Src info)"

Option 2: As a reference

You can also use the provided configuration package as a reference to adapt your own FreeSWITCH setup. This is especially useful if you already have a customized configuration or cannot fully replace your existing setup.

The package includes only the necessary files for enabling RADIUS authentication, authorization, accounting, SIP redirect routing, and CDR file generation. The core parts of this integration are:

• ./autoload_configs/xml_radius.conf.xml
  Configuration for the mod_xml_radius module. This file defines how FreeSWITCH communicates with the RADIUS server and formats requests in a way expected by JeraSoft Billing.
• ./autoload_configs/cdr_csv.conf.xml
  Configuration for generating CDR files. While your system may already include this file, you must ensure that the template and settings exactly match the configuration provided.
• ./dialplan/jerasoft.xml
  A critical dialplan file that handles RADIUS responses and enables dynamic routing via SIP 300 Redirect. It forms the logic layer that connects FreeSWITCH call flow with billing authorization.
• ./dictionaries
  A set of RADIUS dictionary files required by mod_xml_radius to correctly interpret attributes used in communication with the JeraSoft RADIUS server.

Below is a summary of key files that should be reviewed and updated in your configuration:

<conf>/vars.xml

Defines FreeSWITCH environment variables. Ensure the following lines are present, replacing placeholders with your actual values:

<X-PRE-PROCESS cmd="set" data="radiusauth=JERASOFT_IP_ADDRESS:1812:RADIUS_SECRET"/>
<X-PRE-PROCESS cmd="set" data="radiusacct=JERASOFT_IP_ADDRESS:1813:RADIUS_SECRET"/>
<X-PRE-PROCESS cmd="set" data="sipredirect=JERASOFT_IP_ADDRESS"/>

Replace JERASOFT_IP_ADDRESS with the IP address of your JeraSoft Billing server and RADIUS_SECRET with your chosen RADIUS shared secret.

<conf>/autoload_configs/cdr_csv.conf.xml

Defines the CDR file format used for integration with JeraSoft Billing. Ensure the config includes the following structure:

<configuration name="cdr_csv.conf" description="CDR CSV Format">
  <settings>
    <!-- 'cdr-csv' will always be appended to log-base -->
    <!--<param name="log-base" value="/var/log"/>-->
    <param name="default-template" value="jerasoft"/>
    <!-- This is like the info app but after the call is hung up -->
    <!--<param name="debug" value="true"/>-->
    <param name="rotate-on-hup" value="true"/>
    <!-- may be a b or ab -->
    <param name="legs" value="ab"/>
    <!-- Only log in Master.csv -->
    <param name="master-file-only" value="true"/>
  </settings>
  <templates>
    <template name="jerasoft">"${billuuid}","${uuid}","${src-gw-ip}","${src-gw-name}","${dst-gw-ip}",
    "${dst-gw-name}","${src-number-in}","${src-number-translated}","${dst-number-in}","${dst-number-out}",
    "${start_stamp}","${answer_stamp}","${end_stamp}","${billsec}","${hangup_cause}","${progresssec}",
    "${read_codec}","${write_codec}","${call-origin}"</template>
  </templates>
</configuration>

<conf>/autoload_configs/modules.conf.xml

Specifies which modules FreeSWITCH loads at startup. Confirm that mod_xml_radius is enabled:

<load module=“mod_xml_radius”/>

<conf>/sip_profiles/internal.xml and external.xml

These files define internal and external SIP profiles. Ensure they include the following parameter to support dynamic routing via SIP 300 Redirect:

<param name=“manual-redirect” value=“true”/>