Call Us Today! 877.742.2583

Page tree
Skip to end of metadata
Go to start of metadata


FreeSWITCH uses XML files to configure the core as well as all modules. As you can imagine the configuration can grow quite big and complex. The default configuration provides a good starting point for new users. If you would like to just jump in and starting using FreeSWITCH see Configuring FreeSWITCH for a quick overview of the default configuration and the changes you need to make when you start.  However if you would like to do any serious project with FreeSWITCH we would strongly recommend you take the time to get a deeper understanding of how the configuration files work. In this page we will do an in-depth overview of the configuration system. If you are feeling brave, you might want to completely remove the default configuration and start from scratch.


 Click here to expand Table of Contents


The configuration files are written in XML, check out the XML Basics page if you are new to XML. If you are new to XML, take the time to read up.  See the Configuration Modules section below for more advanced ways of doing configuration. The configuration is named freeswitch.xml and by default it's located at /etc/freeswitch, although you can specify an alternate file path as a command line argument.

The XML file is divided into multiple sections, as you can see below in the basic schema of the configuration file. Each section has it's own subsections and schema, in the following sections we will explore the schema of each individual section.

Configuration Schema
<document type="freeswitch/xml">
  <section name="configuration" description="Various Configuration">
    <!-- Module configuration goes here -->
  <section name="dialplan" description="Regex/XML Dialplan">
    <!-- Instructions on how to route incoming calls goes here -->
  <section name="chatplan" description="Regex/XML Chatplan">
    <!-- Instructions on how to route incoming SMS messages -->
  <section name="directory" description="User Directory">
    <!-- User configuration goes here -->  
  <section name="languages" description="Language Management">
    <!-- Here you can configure support for playing the system prompts in different languages -->


In the configuration section you can configure the FreeSWITCH core and most modules. Within the configuration section are many configuration elements, usually one for each module. Most configuration elements use the following XML schema.

Configuration Example
<section name="configuration" description="Various Configuration">
	<configuration Name="mymodule.conf" Description="My Module Configuration">
			<param name="my_param" value="my value" />
	<configuration Name="another_module.conf" Description="Other Module Configuration">
			<param name="my_param" value="my value" />

Some modules use different XML elements and/or additional XML attributes, refer to each module's confluence page for details on the specific parameters, elements and attributes it uses. 

In addition to the configuration elements for individual modules, there are 2 special configuration elements that are used to configure the FreeSWITCH core itself.


This is where you configure settings for the FreeSWITCH core. The full list of parameters is documented on the XML Switch Configuration page.


This section tells FreeSWITCH which modules to load at startup. You can always load other modules from the command line at a later time. For more info see the module configuration page. When FreeSWITCH starts up, it first loads switch.conf, then modules.conf. As each module is loaded, FreeSWITCH will parse and load the configuration element used by that module.


The Dialplan section is where you setup all your call-routing rules. See the Dialplan page for more information.


Here you setup routing rules for SMS and other chatting platorms. See mod_sms for more.





Pre Process Directives

XML files are plain text, there are no programming logic functionalities built-in to XML. While it has the advantage of being easy to read, there are some drawbacks too.

  1. For such a large and flexible system such as FreeSWITCH, the configuration file can be huge. The default configuration runs close to 15,000 lines in total.
  2. If you have special values you want to use in many places in the configuration, you have to duplicate it by hand. This can cause problems when you want to change it.
  3. You can't run scripts to dynamically calculate values for the configuration

To address these issues, FreeSWITCH uses custom pre-processor directives that. There is a pre-processor engine that runs on the original configuration file and creates a new configuration file using the results of the pre-processor directives. The processed file is stored in the log directory (by default /var/log/freeswitch) and is named freeswitch.xml.fsxml, this is the file that's actually loaded by FreeSWITCH. The pre-processor is run at startup as well  as when you reload the configuration file. If you are running into issues with pre-processor directives, it can be helpful to review the processed file.

There are 2 ways you can specify pre-processor directives.

  1. The custom X-PRE-PROCESS XML tag
  2. Within an XML comment you can prefix the directive with a #.
Pre-Process example
<!--Using the X-PRE-PROCESS custom XML tag-->
<X-PRE-PROCESS cmd="set" data="my_variable='value'"/>
<!--Using an XML comment with a #-->
<!--#set my_variable='value'-->

Commenting Pre-Process commands

Standard XML comments have no effect on Pre-Process commands. If you do want to comment out a Pre-Process Command you can replace X-PRE-PROCESS with X-NO-PRE-PROCESS

<!--This is a standard XML comment, the Pre-Process command WILL be processed-->	
<!--<X-PRE-PROCESS cmd="set" data="my_global_var='some value'"/>-->
<!--This pre-process command will NOT run-->
<X-NO-PRE-PROCESS cmd="set" data="my_global_var='some value'"/>

Following are all the available pre-process directives. Include and Set are by far the most commonly used.


This pre-process command allows us to break up the configuration into multiple files. The include directive specifies the path of the additional files and the pre-processor will replace the included directive with the contents of the specified file(s). The path can be a single file, or it can be a wildcard, by using a wildcard you can pull in all files in a directory. In the default configuration, the main configuration file (freeswitch.xml) is just a set of include directives, one for vars.xml (more on that soon) and one for each of the configuration sections. This allows us to build a clean directory hierarchy for the various system configurations.

Include Examples
<!--This include is used by the default configuration to load the vars.xml file into the main configuration file-->
<X-PRE-PROCESS cmd="include" data="vars.xml"/>
	This include directive is used by the default configuration to load all the module configuration files from the autoload_configs directory, this allows us to use a separate configuration file for each module.
<section name="configuration" description="Various Configuration">
	<X-PRE-PROCESS cmd="include" data="autoload_configs/*.xml"/>

In the included file, the pre-process will only include XML that's enclosed in an include tag as seen in this example

Include tag
	<!--content to be included goes here-->


The set directive allows us to setup a variable name with a value, then we can reference the variable throughout the configuration file using the syntax $${variable_name}. When the pre-processor runs it will create a global variable using the name and value specified. The global variable is stored by the FreeSWITCH engine and can be retrieved anywhere in the confguration as well as dynamically from the API or a script. In addition to setting the global variable, the pre-processor will also do a static replacement of all text in the configuration files that use the $${variable_name} syntax. The text will be replaced with the value of the variable at the time the pro-processor runs. Since it is a static replacement, you must place the set directive before using the variable. Also, if you change the value of the global variable at runtime the configuration will still have the old value.

The set directive is useful for values that are duplicated in many places in the configuration but are not expected to change often such as IP addresses and domains.

By combining the set and include directives we can create a single file where all variables are set, now we can share the same set of configuration files on many servers and only need to change this one file to include the server specific settings. In fact this is how the default configuration is set up, there is a file called vars.xml where values such as IP address and domain are set.

Using the Set directive
<!--Use the Set directive to set the valuable of a global variable-->
<X-PRE-PROCESS cmd="set" data=""/>
<!--Use the $${variable_name} syntax to retrieve the value of the variable-->
<action application="bridge" data="sofia/$${domain}/"/>
<!-- This is how the previous line will actually appear in the processed configuration file (freeswitch.xml.fsxml) -->
<!-- Note that the reference to the variable is gone -->
<action application="bridge" data="sofia/"/>

For more information about variables see the Variables page.


If you have some really complicated configuration rules you can have a script that generates parts of the configuration files. The exec directive will run a a shell command  and include the output in the configuration file.

exec example
<X-PRE-PROCESS cmd="exec" data="/path/to/"/>


This is similar to exec, but instead of including the output in the configuration file it will set a global variable with the output.

exec-set example
<!-- Set local_ip_v4 to eth1 address -->
<X-PRE-PROCESS cmd="exec-set" data="local_ip_v4=ip addr show eth1 | awk '/inet /{print $2}' | head -n 1 | cut -d '/' -f 1"/>


A pre-process comment can be used if you don't want the comment to appear in the final XML file.

comment example
<X-PRE-PROCESS cmd="comment" data="This text will be removed by the pre-processor" />


How the configuration files are processed


Configuration Modules

We will see later that there are alternatives to using plain XML files, however you would still need some XML to start up FreeSWITCH and instruct it to load a different configuration provider.

XML Curl





  • No labels