Default Configuration

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)