Default Configuration | FreeSWITCH Documentation
FreeSWITCH Office Hours
Talk to the experts on the first and third Tuesday of every month.
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
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:
limit
mod_hash
mod_db
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)
0. About
1. Overview of default configuration files
2. Introduction
3. Dialplans
Dialplan XML
mod_dialplan_asterisk
ENUM
4. Codecs
mod_g723_1
mod_g729
mod_amr
mod_h26x
mod_opus
mod_vp8
5. Modules
mod_cdr_csv
mod_commands
mod_conference
mod_console
mod_dialplan_asterisk
mod_dialplan_xml
mod_dptools
mod_enum
mod_esf
mod_event_socket
mod_expr
mod_fifo
mod_fsv
mod_limit
mod_local_stream
mod_logfile
mod_loopback
mod_native_file
mod_say_en
mod_sndfile
mod_sofia
mod_v8
mod_tone_stream
mod_voicemail
mod_spandsp
mod_file_string
6. Configuration-Files
conf/
conf/autoload_configs/
conf/dialplan/
conf/directory/
conf/lang/
conf/jingle_profiles
conf/mrcp_profiles/
conf/sip_profiles/
Attachments: