Installing FreeSWITCH Core

This page offers detailed, step-by-step instructions for installing FreeSWITCH version 1.10.12 or any other version on a Linux machine directly from source code. The installation process is generally similar for Windows and other platforms. For platform-specific instructions, please refer to the official FreeSWITCH documentation.

Note

This tutorial was created and tested on a freshly installed Linux system with the following OS configuration running on Azure Cloud:

Operating System: Ubuntu 22.04.4 LTS (Jammy Jellyfish)
Version ID: 22.04
Codename: Jammy
Kernel Version: Linux EVADemoUS 6.5.0-1024-azure #25~22.04.1-Ubuntu SMP Mon Jun 17 18:38:57 UTC 2024

This guide has been verified to ensure compatibility and accuracy on the specified environment. If you are using a different OS or version, you might need to make adjustments accordingly.

disclaimer

This guide assumes that you are installing FreeSWITCH as the root user and will be using FreeSWITCH exclusively from the root account. If you are installing for a non-root user, please make the necessary adjustments to the installation process. For simplicity and to avoid permission issues, it is strongly recommended to install FreeSWITCH using the root user.

Pre-Requisites

Install following packages and libraries in your system:

sudo apt install --yes build-essential pkg-config uuid-dev zlib1g-dev libjpeg-dev libsqlite3-dev libcurl4-openssl-dev libpcre3-dev libspeexdsp-dev libldns-dev libedit-dev libtiff5-dev yasm libopus-dev libsndfile1-dev unzip libavformat-dev libswscale-dev liblua5.2-dev liblua5.2-0 cmake libpq-dev unixodbc-dev autoconf automake ntpdate libxml2-dev libpq-dev libpq5 sngrep lua5.2 lua5.2-doc libreadline-dev

Install spandsp library using this guide (Mandatory Step)
Install sofia-sip using this guide (Mandatory Step)
Install libks2 library using this guide (Mandatory Step)
Install soundtouch library using this guide (Mandatory Step)

Install libshout3-dev, libmpg123-dev, libmp3lame-dev required by mod_shout (Mandatory Step)

sudo apt-get install libshout3-dev
sudo apt-get install libmpg123-dev
sudo apt-get install libmp3lame-dev

Alert!!

Ensure you are installing all dependencies before installing FreeSWITCH

Installation Steps

Navigate to /usr/local/src directory:
```
cd /usr/local/src
```

Navigate to FreeSWITCH Releases page and download freeswitch-1.10.12.-release.tar.gz:

wget https://files.freeswitch.org/releases/freeswitch/freeswitch-1.10.12.-release.tar.gz

Extract tar file:

tar -xzvf freeswitch-1.10.12.-release.tar.gz

Navigate to extracted source code directory:
```
cd freeswitch-1.10.12.-release
```
Edit modules.conf file to include important modules and disable some unnecessary modules:
- comment module applications/mod_av (mandatory)
- comment module applications/mod_signalwire (mandatory)
- uncomment module applications/mod_soundtouch (mandatory)
- uncomment module endpoints/mod_rtmp (not mandatory)
- uncomment module formats/mod_shout (not mandatory)
Run the following commands to set up the build environment and compile FreeSWITCH for your system:
- Executing the following command prepares the build environment by checking system dependencies and generating the necessary configuration files:
```
./configure
```
  warning
  Running ./configure command may result in errors related to missing dependencies and libraries. Ensure that all required prerequisites are correctly installed and compatible with your system and operating system.
- Executing the following command compiles the source code into executable binaries:
```
make
```
  warning
  Running the make command may produce errors if there are issues with linking or dependencies. Ensure that you are using compatible versions of all dependencies and libraries. Additionally, if you have installed or updated any dependencies or libs, be sure to clean the build using before running make again to avoid persistent errors. Below is the sequence of commands to execute for a clean build:
  make clean ./configure make
  This ensures that any updates to libraries, dependencies, or configuration changes are properly incorporated by the ./configure command.
- Executing the following command will install the compiled binaries and files into the appropriate system directories:
```
sudo make install
```
After successfully completing the above steps, FreeSWITCH will be installed on your system. If you wish to install sound packs (which are not typically required in most production environments), execute the following commands. Note that an internet connection is required for this process:
```
sudo make cd-sounds-install
sudo make cd-moh-install
```

Configure FreeSWITCH

If you are reinstalling FreeSWITCH or have installed it previously, execute the following commands. Otherwise, you can skip these commands:

sudo rm -rf /etc/freeswitch
sudo rm -rf /usr/bin/fs_cli
sudo rm -rf /usr/sbin/freeswitch

Create the necessary symbolic links to ensure proper file and directory references for FreeSWITCH:
```
sudo ln -s /usr/local/freeswitch/conf /etc/freeswitch
sudo ln -s /usr/local/freeswitch/bin/fs_cli /usr/bin/fs_cli
sudo ln -s /usr/local/freeswitch/bin/freeswitch /usr/sbin/freeswitch
```
- sudo ln -s /usr/local/freeswitch/conf /etc/freeswitch link the FreeSWITCH configuration directory to a standard location.
- sudo ln -s /usr/local/freeswitch/bin/fs_cli /usr/bin/fs_cli create a link to the FreeSWITCH command-line interface tool.
- sudo ln -s /usr/local/freeswitch/bin/freeswitch /usr/sbin/freeswitch link the FreeSWITCH executable to a common system directory.

If you want to create a dedicated user named 'freeswitch' for FreeSWITCH, use the following commands. Note that this step is optional.

sudo groupadd freeswitch
sudo adduser --quiet --system --home /usr/local/freeswitch --gecos 'FreeSWITCH open source softswitch' --ingroup freeswitch freeswitch --disabled-password
sudo chown -R freeswitch:freeswitch /usr/local/freeswitch/
sudo chmod -R ug=rwX,o= /usr/local/freeswitch/
sudo chmod -R u=rwx,g=rx /usr/local/freeswitch/bin/*

Configure the systemd service for FreeSWITCH:

Disclaimer
systemctl might not be available in docker environment based on the image used (using Ubuntu as default image)
1. Use the following command to open a new systemd service file for FreeSWITCH:
```
sudo vi /etc/systemd/system/freeswitch.service
```
  This command opens the vi editor (or you can use any text editor of your choice) to create and edit the freeswitch.service file.
2. Add the service configuration:
  
  Copy and paste the following configuration into the file:
```
[Unit]
Description=FreeSWITCH
Wants=network-online.target
Requires=network.target local-fs.target
After=network.target network-online.target local-fs.target

[Service]
Type=forking
PIDFile=/usr/local/freeswitch/run/freeswitch.pid
Environment="DAEMON_OPTS=-nonat"
Environment="USER=root"
Environment="GROUP=root"
EnvironmentFile=-/etc/default/freeswitch
ExecStartPre=/bin/chown -R ${USER}:${GROUP} /usr/local/freeswitch
ExecStart=/usr/local/freeswitch/bin/freeswitch -u ${USER} -g ${GROUP} -ncwait ${DAEMON_OPTS}
TimeoutSec=45s
Restart=always

[Install]
WantedBy=multi-user.target
```
  - [Unit]: Defines the service’s metadata and dependencies. It specifies that FreeSWITCH should start after network and filesystem targets are ready.
  - [Service]: Configures how the service is managed. This includes starting the service, handling environment variables, and defining the behavior for service restarts.
  - [Install]: Defines how the service should be enabled and started at boot.
3. Reload the systemd daemon:
```
sudo systemctl daemon-reload
```
  This command refreshes systemd to recognize the new or updated service file.
4. Enable and start the FreeSWITCH service:
```
sudo systemctl enable freeswitch.service
sudo systemctl start freeswitch.service
```
  - enable sets up the service to start automatically when the system boots.
  - start initiates the service right away.
5. Verify service status:
```
sudo systemctl status freeswitch.service
```
This command provides a detailed report of the service's current state, including any potential errors or issues.

🎉 Congratulations! 🎉

You've done an incredible job following the tutorial and getting FreeSWITCH up and running. Your dedication and attention to detail have truly paid off! 👏

Thank you for your hard work and perseverance throughout the installation process. We hope FreeSWITCH serves you well and meets all your communication needs.

Welcome aboard and best of luck with your FreeSWITCH setup! 🚀

Pre-Requisites​

Installation Steps​

Configure FreeSWITCH​

🎉 Congratulations! 🎉​

Pre-Requisites

Installation Steps

Configure FreeSWITCH

🎉 Congratulations! 🎉