Skip to main content

Default Configuration

Table of Contents (click to expand)

0. About​

A discussion of the default configuration files and how they interact.

TODO See TODOs in Vanilla installation files.

1. Overview of default configuration files​

Diagram of default config files

Click to enlarge diagram

2. Introduction​

FreeSWITCH ships with a large number of configuration files. This page will help explain the various configuration files and their default contents along with the standard modules, but in every case the Github repository supersedes this document.

Most of the FreeSWITCH configuration files are formatted in XML

When FreeSWITCH starts or when the reloadxml command is issued to the API, FreeSWITCH compiles all configuration files into one huge file that is kept in memory.

log/freeswitch.xml.fsxml contains all the individual configuration files concatenated together into one huge file. When FreeSWITCH reports a configuration file error, the line number in the error message refers to this file, which can have more than 10 thousand lines.

3. Dialplans​

A dialplan is a series of actions, and the conditions upon which they are executed. A dialplan tells FreeSWITCH how to behave, what to do, and when to do it. FreeSWITCH supports 3 Dialplans.

Dialplan XML​

Dialplan.xml is the primary dialplan of FreeSWITCH. As its name suggests, it's an XML formatted file.

mod_dialplan_asterisk​

Actually, this file is called extensions.conf, it is a compatibility file that supports Asterisk style dialplans.

ENUM​

ENUM is a translation system from PSTN numbers to VoIP uri.

4. Codecs​

These modules provide codecs - support for various ways of COding and DECoding speech audio.

mod_g723_1​

mod_g723_1 is the G.723.1 pass-through implementation.

mod_g729​

The G.729 Codec. See the commercial G.729 version for licensing information.

mod_amr​

The AMR Codec.

mod_h26x​

Video codec.

mod_opus​

WebRTC codec.

mod_vp8​

Google video codec.

5. Modules​

These modules provide additional functionality to FreeSWITCH.

mod_cdr_csv​

The Call Detail Record module

mod_commands​

A module that contains various commands.

mod_conference​

The conferencing module.

mod_console​

The module that reads and writes to the console.

mod_dialplan_asterisk​

The module responsible for parsing extensions.conf to provide a limited Asterisk-compatible configuration.

mod_dialplan_xml​

The module responsible for parsing and implementing the Dialplan.xml file.

mod_dptools​

The Dial Plan Tools module, includes various functions to deal with dialplans.

mod_enum​

ENUM numbers lookup module (E.164) format

mod_esf​

Extra SIP Functionality module, provides multicast paging support.

mod_event_socket​

Event Socket module, provides for script control of FreeSWITCH™.

mod_expr​

Expression Evaluation Library module.

mod_fifo​

Basic call queuing module, for call centers.

mod_fsv​

Video File Format Module, for FreeSWITCH Video.

mod_limit​

Limit the number of calls to or from an arbitrary resource; also implements db and group API functions and dialplan applications.

mod_limit is deprecated and has been integrated into the core.

See also:

mod_local_stream​

Local streaming module.

mod_logfile​

Module that controls logging to a file.

mod_loopback​

Local dialplan loopback module. Use with caution.

mod_native_file​

Native sounds playback module.

mod_say_en​

TTS (text-to-speech) services for English.

mod_sndfile​

Sound file playback framework demo module.

mod_sofia​

FreeSWITCH SIP endpoint module.

mod_v8​

FreeSWITCH uses the Google V8 JavaScript (ECMAScript) engine, which supersedes mod_spidermonkey. See the Javascript page for more information and examples.

mod_tone_stream​

Module for tone generation. See more under TGML.

mod_voicemail​

FreeSWITCH Voicemail Module

mod_spandsp​

The family of FreeSWITCH modules including mod_fax, mod_t38gateway, and the mod_voipcodecs have been merged into one module called mod_spandsp which takes advantage of all the DSP features found in the SpanDSP library including T.38 endpoint and gateway functionality.

mod_file_string​

Function of this module are now part of mod_dptools

Play strings of files

6. Configuration files​

conf/​

This is the main configuration directory.

To find it, issue the following inside fs_cli ,

freeswitch@tr2> eval $${conf_dir}
/etc/freeswitch

or on your terminal:

$ fs_cli -x 'eval $${conf_dir}'

Anything that defines how the switch works is in a file in this directory or a sub-directory. The FreeSWITCH program itself loads only one single config file (i.e., conf/freeswitch.xml); that single config file contains directives to cause the loading of all other config files, making it theoretically possible to put all config options into one config file or to more sensibly use multiple config files from as many directories as desired (note that config files can include other config files or entire directories with glob wildcarding -- see the conf/freeswitch.xml for example). The default config structure (as of FS 1.0.4pre6) presents the following config files and directories:

conf/extensions.conf conf/freeswitch.xml conf/fur_elise.ttml conf/mime.types conf/tetris.ttml conf/vars.xml conf/voicemail.tpl conf/web-vm.tpl

conf/autoload_configs/​

conf/autoload_configs/alsa.conf.xml conf/autoload_configs/cdr_csv.conf.xml conf/autoload_configs/conference.conf.xml conf/autoload_configs/console.conf.xml conf/autoload_configs/dialplan_directory.conf.xml conf/autoload_configs/dingaling.conf.xml conf/autoload_configs/enum.conf.xml conf/autoload_configs/erlang_event.conf.xml conf/autoload_configs/event_multicast.conf.xml conf/autoload_configs/event_socket.conf.xml conf/autoload_configs/ivr.conf.xml conf/autoload_configs/local_stream.conf.xml conf/autoload_configs/logfile.conf.xml conf/autoload_configs/lua.conf.xml conf/autoload_configs/modules.conf.xml conf/autoload_configs/perl.conf.xml conf/autoload_configs/portaudio.conf.xml conf/autoload_configs/post_load_modules.conf.xml conf/autoload_configs/rss.conf.xml conf/autoload_configs/sofia.conf.xml conf/autoload_configs/switch.conf.xml conf/autoload_configs/syslog.conf.xml
conf/autoload_configs/v8.conf.xml
conf/autoload_configs/voicemail.conf.xml conf/autoload_configs/xml_cdr.conf.xml conf/autoload_configs/xml_curl.conf.xml conf/autoload_configs/xml_rpc.conf.xml conf/autoload_configs/zeroconf.conf.xml

conf/dialplan/​

conf/dialplan/default.xml conf/dialplan/features.xml conf/dialplan/public.xml

conf/directory/​

This is the sub–directory that will hold all of the users allowed access to make calls via FreeSWITCH.

It's possible to define all extensions in one single XML file. In practice, especially if your FS server is providing PBX or other telephony services for multiple companies (multi-tenancy), it's advisable to create multiple sub–directories (one per company) to contain the user config files.

For example:

  • conf/directory/default.xml — contains directive that causes loading of conf/directory/default/*.xml files
  • conf/directory/default/4411.xml — contains config info for extension 4411.xml in the default-global context, meaning extension 4411 is shared across all companies; this could be useful for, say, a universal "help desk" service that could ring your FS help desk for all your clients.
    • conf/directory/companyA.xml — contains directive that causes loading of conf/directory/companyA/*.xml child files
      • conf/directory/companyA/1000.xml — contains config info for extension 1000.xml in companyA
        • conf/directory/companyA/1001.xml — contains config info for extension 1001.xml in companyA
    • conf/directory/companyB.xml — contains directive that causes loading of conf/directory/companyB/*.xml child files
      • conf/directory/companyB/1000.xml — contains config info for extension 1000.xml in companyB
        • conf/directory/companyB/1001.xml — contains config info for extension 1001.xml in companyB

conf/lang/​

Configuration for multiple language support. Used by mod_say_xx, such as mod_say_en.

Example list of language files for English:

conf/lang/en conf/lang/en/vm conf/lang/en/vm/sounds.xml conf/lang/en/vm/tts.xml conf/lang/en/en.xml conf/lang/en/demo conf/lang/en/demo/demo.xml conf/lang/en/demo/demo-ivr.xml

Default configs includes de, en, fr, and ru.

Useful in Speech Phrase Management.

conf/jingle_profiles​

This is where the different profiles for mod_dingaling get placed.

conf/mrcp_profiles/​

Profiles for Media Resource Control Protocol (MRCP) via mod_unimrcp.

Default profiles included:

conf/mrcp_profiles/nuance-5.0-mrcp-v2.xml conf/mrcp_profiles/loquendo-7-mrcp-v2.xml conf/mrcp_profiles/nuance-1.0.0-mrcp-v1.xml conf/mrcp_profiles/unimrcpserver-mrcp-v1.xml conf/mrcp_profiles/nuance-5.0-mrcp-v1.xml conf/mrcp_profiles/voxeo-prophecy-8.0-mrcp-v1.xml

conf/sip_profiles/​

This is where the different SIP profiles (or endpoints) are defined. (See Sofia SIP Stack and Configuring FreeSWITCH.)

Public Context for Security

You'll notice that all the SIP profiles in the default configuration use the public context for their dialplan, including the internal profile:

conf/sip_profiles/*.xml

<param name="context" value="public"/>

If you look in the directory config files, conf/directory/default/*.xml (see Introduction in Dialplan), you'll notice that the SIP profile's context is overridden there like so:

conf/directory/default/*.xml

<variable name="user_context" value="default"/>

When a user registers and places a call, their context is set to whatever is in their user_context variable, thus default .

The reasoning behind all of this is that if you manage to turn off authentication or otherwise open up the internal profile then you won't by default expose your private dialplan to the world (e.g., for toll fraud).

Attachments:​

fs_default_config.jpg (image/jpeg)