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

About

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

 Click to expand Table of Contents

 

Diagram of default config files

Click to enlarge diagram

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 Stash source code repository supersedes this document.

Most of the FreeSWITCH configuration files are formatted in XML

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.

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.

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

Config Files

conf/

This is the main configuration directory. 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/java.conf.xml
conf/autoload_configs/limit.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/openmrcp.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/spidermonkey.conf.xml
conf/autoload_configs/switch.conf.xml
conf/autoload_configs/syslog.conf.xml
conf/autoload_configs/voicemail.conf.xml
conf/autoload_configs/wanpipe.conf.xml
conf/autoload_configs/woomera.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

usw.

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 Sofia-SIP profiles (or endpoints) are defined.

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:

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

If you look in the directory config files (conf/directory/default/*.xml) you'll notice that the context is overridden there like so:

 <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 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 i.e. toll fraud.

conf/ssl/

This directory will hold keys and certs for doing TLS/SRTP