Skip to main content

Basic Configurations

This section provides a comprehensive guide for configuring FreeSWITCH.

Configuring FreeSWITCH can initially seem overwhelming, especially for beginners, due to the vast number of configuration options available. However, understanding some basic, essential settings can help demystify the process and allow you to tailor FreeSWITCH to your specific needs.

When configuring FreeSWITCH, there are several core configurations you should address for a functional and scalable system. These configurations will ensure the system can handle telephony services efficiently. Below are some of the essential configuration steps and theory behind them:

SIP Profiles Configuration​

FreeSWITCH uses SIP (Session Initiation Protocol) profiles to handle communication with SIP endpoints. SIP profiles are one of the most critical elements of FreeSWITCH. They define how FreeSWITCH interacts with the devices and servers using the Session Initiation Protocol (SIP).

FreeSWITCH uses two primary SIP profiles by default:

  • Internal SIP Profile: Handles communication with devices inside your network, such as softphones, IP phones, or other local SIP clients.
  • External SIP Profile: Manages communication with external entities such as VoIP providers (SIP trunks) and remote clients.

Each profile defines the following parameters:

  • IP Address and Port: Where FreeSWITCH listens for SIP/RTP traffic.
  • NAT Settings: To handle users behind firewalls or routers.
  • Codec Preferences: The media codecs used for encoding voice or video data.

File Locations​

  • Internal SIP Profile: internal.xml

    /etc/freeswitch/sip_profiles/internal.xml

  • External SIP Profile: external.xml

    /etc/freeswitch/sip_profiles/external.xml

Key Configurations​

For each SIP profile, we need to define:

  1. IP Address and Port: Specify the IP address or interface FreeSWITCH should bind to for internal or external communications. The default SIP port is 5060, but it can be customized.

    Example configuration in internal.xml:

    <param name="sip-ip" value="$${local_ip_v4}"/>
    <param name="rtp-ip" value="$${local_ip_v4}"/>
    <param name="sip-port" value="5060"/>

    In the external.xml file, the parameters are similar, but you can specify a different interface or IP for external communications, which is useful in multi-homed environments.

  2. Configuring RTP Ports in FreeSWITCH: The RTP (Real-time Transport Protocol) port range is configured in the FreeSWITCH configuration file /etc/freeswitch/autoload_configs/switch.conf.xml. By default, the RTP port settings are commented out. To enable and configure the RTP port range, follow these steps:

    • Open the /etc/freeswitch/autoload_configs/switch.conf.xml file in a text editor.

      vim /etc/freeswitch/autoload_configs/switch.conf.xml

    • Find the following lines (they are commented by default):

      <!--<param name="rtp-start-port" value="16384"/>-->
      <!--<param name="rtp-end-port" value="32768"/>-->

      Uncomment these lines by removing the comment tags, and modify the values as needed.

      <param name="rtp-start-port" value="16384"/>
      <param name="rtp-end-port" value="32768"/>
      note

      rtp-start-port specifies the first RTP port in the range.
      rtp-end-port specifies the last RTP port in the range.

    • Save the file and restart freeSWITCH to apply the changes:

      sudo systemctl restart freeswitch

  3. NAT Traversal: If your users are behind a firewall or NAT, you need to set up NAT traversal. FreeSWITCH can work with STUN and TURN servers for this purpose.

    Example NAT setting (used for both SIP and RTP) in vars.xml:

    <X-PRE-PROCESS cmd="stun-set" data="external_sip_ip=stun:stun.l.google.com:19302"/>
    <X-PRE-PROCESS cmd="stun-set" data="external_rtp_ip=stun:stun.l.google.com:19302"/>

    You can also configure static external IPs if you're operating behind NAT or there are some custom IP routings incorporated:

    <X-PRE-PROCESS cmd="set" data="external_sip_ip=your_external_ip"/>
    <X-PRE-PROCESS cmd="set" data="external_rtp_ip=your_external_ip"/>

  4. Codec Preferences: Define the preferred audio codecs to use during call sessions. Codecs like G.711 (PCMU/PCMA) are commonly used for good quality over high-bandwidth networks, while G.729 (paid) and Opus are used in bandwidth-constrained environments.

    In FreeSWITCH, you can configure codec preferences globally across all SIP profiles or customize them for specific profiles. Codecs are essential for determining how audio and video streams are encoded and decoded during SIP communication. This document outlines how to configure global codec preferences using the vars.xml file and how to override these settings per SIP profile in the profile.xml file.

    • Global Codec Configuration (vars.xml): To define the codec preferences for all SIP profiles globally, you can set the global_codec_prefs and outbound_codec_prefs variables in the vars.xml file. These variables dictate which codecs will be used in inbound and outbound SIP calls across all profiles unless overridden.

      Example vars.xml configuration:

      <X-PRE-PROCESS cmd="set" data="global_codec_prefs=OPUS,G722,PCMU,PCMA,H264,VP8"/>
      <X-PRE-PROCESS cmd="set" data="outbound_codec_prefs=OPUS,G722,PCMU,PCMA,H264,VP8"/>
      • global_codec_prefs: This variable defines the preferred codecs for incoming (inbound) calls. The codecs are prioritized in the order they are listed.
      • outbound_codec_prefs: This variable defines the preferred codecs for outgoing (outbound) calls. Like global_codec_prefs, the order of codecs determines their priority.

      In the above example, codecs like OPUS, G722, and PCMU (audio codecs), and H264 and VP8 (video codecs) are configured globally.

    • Overriding Codec Preferences for Specific SIP Profiles: If you need to configure codec preferences for a particular SIP profile (for example, if one profile needs different codec preferences due to network or hardware limitations), you can override the global settings by modifying the profile’s profile.xml file.

      Example internal.xml configuration:

      <param name="inbound-codec-prefs" value="$${global_codec_prefs}"/>
      <param name="outbound-codec-prefs" value="$${global_codec_prefs}"/>

      In this configuration:

      inbound-codec-prefs: Specifies the codec preferences for incoming calls on this profile. The value attribute references the global_codec_prefs variable using $${global_codec_prefs}, meaning it inherits the global setting from vars.xml.

      outbound-codec-prefs: Specifies the codec preferences for outgoing calls on this profile. Similar to the inbound codec preferences, it inherits the global codec preferences defined in vars.xml.

      Customizing Codec Preferences per SIP Profile: You can manually configure codec preferences by setting a custom list of codecs in the profile.xml file instead of using the global variables:

      Example internal.xml configuration:

      <param name="inbound-codec-prefs" value="PCMU,PCMA"/>
      <param name="outbound-codec-prefs" value="PCMU,PCMA"/>

      In this case, for this specific profile internal.xml, only the PCMU and PCMA codecs will be used for both inbound and outbound calls, regardless of the global settings.

Dialplan Configuration​

The dialplan is responsible for determining how calls are handled and routed. The dialplan defines call processing logic: how to route incoming calls, what actions to take, and where to send calls.

Dialplan Basics​

The dialplan is defined in the following directory:

/etc/freeswitch/dialplan/

The dialplan is made up of:

  • Extensions: Logical entities that group a set of rules and actions. Extensions define how to handle a specific call or group of calls.
  • Conditions: Criteria that must be matched to process a call. For example, match calls based on the destination number or caller ID or may be caller IP address.
  • Actions: Instructions to FreeSWITCH on what to do when a condition is met. Examples include bridging a call to another endpoint, playing audio files, or rejecting a call.

Example Dialplan Entry​

This FreeSWITCH dialplan processes calls to number 2318, disables audio interruptions, opens a real-time socket connection to a local service at port 8765, and then hangs up the call.

<extension name="my_extension">
    <condition field="destination_number" expression="2318">
        <action application="set" data="playback_terminators=none"/>
        <action application="set" data="playback_delimiter=&"/>
        <action application="socket" data="127.0.0.1:8765 async full" />
        <action application="hangup"/>
    </condition>
</extension>

In this dialplan:

  • The condition checks if the destination_number matches 2318.
  • If it does, playback settings are configured, a real-time socket connection is opened to 127.0.0.1:8765, and the call is then hung up when socket terminates.

For a comprehensive guide on creating and managing dialplans, refer to the official FreeSWITCH Dialplan documentation docs.

User Directory Configuration​

Users in FreeSWITCH are defined in the directory. Each user represents an extension on the system, complete with credentials, permissions, and other settings.

Directory Configuration​

The directory for defining users is found here:

/etc/freeswitch/directory/default/

Each user is assigned a separate XML file. The file defines:

  1. User ID: Typically the extension number, such as 1001.
  2. Password: The SIP authentication password.
  3. Caller ID settings: What caller ID name/number is shown during outbound calls.
  4. Voicemail: Whether the user has voicemail enabled.

Example User Definition​

Here is a basic user configuration for extension 1001:

<user id="1001">
   <params>
      <param name="password" value="securepassword123"/>
      <param name="vm-enabled" value="true"/>
   </params>
   <variables>
      <variable name="effective_caller_id_name" value="John Doe"/>
      <variable name="effective_caller_id_number" value="1001"/>
      <variable name="accountcode" value="1001"/>
   </variables>
</user>

In this file:

  • The user ID is 1001.
  • The password is securepassword123.
  • The caller ID name displayed is "John Doe", and the caller ID number is 1001.

Each user file can be customized with additional settings, including voicemail, call forwarding, and SIP configurations.

SIP Trunk Configuration​

If you are connecting to the Public Switched Telephone Network (PSTN) or other external VoIP networks, you need to configure a SIP Trunk. This allows FreeSWITCH to send and receive calls through a VoIP provider.

Key SIP Trunk Parameters​

  • Username and Password: Credentials provided by the SIP trunk provider.
  • Proxy or SIP Server: The VoIP provider’s server address.
  • Caller ID: The number displayed to the recipient of the call.
  • Registration: Whether FreeSWITCH needs to register with the provider.

Configuration File​

The SIP trunk configuration is usually done in the external.xml or internal.xml:

/etc/freeswitch/sip_profiles/external.xml

Example SIP Trunk Configuration​

<gateway name="voip_provider">
   <param name="username" value="your_username"/>
   <param name="password" value="your_password"/>
   <param name="proxy" value="sip.voipprovider.com"/>
   <param name="register" value="true"/>
</gateway>

In this example:

  • FreeSWITCH will authenticate using your_username and your_password.
  • Calls will be sent to the provider at sip.voipprovider.com.

Firewall and NAT Settings​

Proper firewall and NAT configuration is critical to ensuring FreeSWITCH works correctly, especially in a remote or cloud-hosted environment.

Open Ports​

For FreeSWITCH to work correctly behind a firewall, the following ports must be open:

  1. SIP Traffic:
    • Port 5060: This is the default port for SIP traffic over UDP. However, FreeSWITCH can also use TCP or TLS (for encrypted SIP).
    • Alternate SIP Ports: If you've configured SIP to run on a different port, ensure those ports are open as well.
  2. RTP Traffic:
    • Port Range (16384 - 32768): FreeSWITCH uses RTP (Real-Time Transport Protocol) for audio and video streams. The port range for RTP needs to be open for bidirectional communication (usually UDP).
    • This range can be customized in FreeSWITCH, but make sure it matches the range set in your firewall.

Logging and Monitoring Configuration​

Proper logging and monitoring are essential to maintain a stable FreeSWITCH system, troubleshoot issues, and track call behavior.

Log Settings​

The primary logging configuration is located here:

/etc/freeswitch/autoload_configs/logfile.conf.xml

Key log parameters to configure:

  1. Log Levels:

    • Set the logging verbosity level to control how much information is captured.
    • Common log levels are ERROR, WARNING, INFO, DEBUG, and NOTICE.

    Example:

    <param name="loglevel" value="INFO"/>

  2. Log Output: Define where log files are stored and how they are rotated. By default, logs are stored in /usr/local/freeswitch/log/freeswitch.log when nothing is configured.

    Example:

    <param name="logfile" value="/var/log/freeswitch/freeswitch.log"/>
    <param name="rotate-on-signal" value="true"/>

    You can also configure FreeSWITCH to output logs to remote logging servers (e.g., using syslog) if you're managing a distributed system.

Conclusion​

Configuring FreeSWITCH requires careful consideration of SIP profiles, user directory, dialplans, codec settings, firewall/NAT handling, and logging. Properly configuring these ensures reliable, scalable, and secure communication. Always test your configurations in different network scenarios (local, remote, behind NAT) to ensure expected behavior.

If your setup becomes more complex, you may also explore advanced features like high-availability clustering, load balancing, or connecting to multiple SIP providers for redundancy.

For a comprehensive and detailed guide on configuring FreeSWITCH, refer to the official FreeSWITCH Configuration docs.