Use this file to discover all available pages before exploring further.
FreeSWITCH is configured entirely through XML files that are assembled by a built-in preprocessor before being parsed. At startup, the preprocessor reads freeswitch.xml — the root configuration file — resolves all X-PRE-PROCESS directives, expands $$variable references, and inlines every included file into a single, unified XML document. This design lets you split configuration across many small files while keeping the final structure well-defined and predictable.
The canonical configuration directory is /etc/freeswitch/ on most Linux installations (the path is set at compile time via --sysconfdir). The vanilla configuration tree looks like this:
/etc/freeswitch/├── freeswitch.xml # Root document — the preprocessor entry point├── vars.xml # Global preprocessor variable definitions├── autoload_configs/ # One XML file per loadable module│ ├── modules.conf.xml # Controls which modules load at startup│ ├── switch.conf.xml # Core switch settings (sessions, logging, etc.)│ ├── sofia.conf.xml # mod_sofia (SIP stack) global settings│ └── ...├── dialplan/ # Call routing logic│ ├── default.xml # Authenticated-user context│ └── public.xml # Unauthenticated inbound context├── directory/ # User accounts and SIP credentials│ ├── default.xml # Domain definition and group memberships│ └── default/ # Individual user files (1000.xml … 1019.xml)├── sip_profiles/ # mod_sofia SIP profile definitions│ ├── internal.xml # Port 5060 — for registered phones│ └── external.xml # Port 5080 — for trunks and outbound gateways├── chatplan/ # Regex/XML chat routing (analogous to dialplan)└── lang/ # Phrase macros and TTS language packs
freeswitch.xml is the single entry point that the preprocessor reads. It contains no call-routing logic of its own — its job is to pull in vars.xml and then declare the four top-level sections, each of which includes its own subdirectory of XML files.
<?xml version="1.0"?><document type="freeswitch/xml"> <!-- vars.xml contains all the #set directives for the preprocessor. --> <X-PRE-PROCESS cmd="include" data="vars.xml"/> <section name="configuration" description="Various Configuration"> <X-PRE-PROCESS cmd="include" data="autoload_configs/*.xml"/> </section> <section name="dialplan" description="Regex/XML Dialplan"> <X-PRE-PROCESS cmd="include" data="dialplan/*.xml"/> </section> <section name="chatplan" description="Regex/XML Chatplan"> <X-PRE-PROCESS cmd="include" data="chatplan/*.xml"/> </section> <!-- mod_sofia uses user data in "directory" for authorization --> <section name="directory" description="User Directory"> <X-PRE-PROCESS cmd="include" data="directory/*.xml"/> </section> <!-- languages section (under development still) --> <section name="languages" description="Language Management"> <X-PRE-PROCESS cmd="include" data="lang/de/*.xml"/> <X-PRE-PROCESS cmd="include" data="lang/en/*.xml"/> <X-PRE-PROCESS cmd="include" data="lang/fr/*.xml"/> <X-PRE-PROCESS cmd="include" data="lang/ru/*.xml"/> <X-PRE-PROCESS cmd="include" data="lang/he/*.xml"/> <X-PRE-PROCESS cmd="include" data="lang/es/es_ES.xml"/> <X-PRE-PROCESS cmd="include" data="lang/pt/pt_BR.xml"/> </section></document>
The FreeSWITCH preprocessor runs before the XML parser, expanding directives written either as XML processing instructions (X-PRE-PROCESS tags) or as comment-style commands (<!--#set ...-->). The two syntaxes are equivalent; the tag form is recommended because it is easier to validate.
#set / cmd="set"
Define a preprocessor variable. The value is available everywhere in the configuration as $${variable_name}.
A preprocessor-level comment. The entire directive is stripped before the XML parser sees the document.
<!--#comment This line never reaches the XML parser -->
You cannot comment out an X-PRE-PROCESS tag using an XML comment (<!-- … -->). The preprocessor strips these directives before the XML parser runs, so wrapping one in a comment has no effect. To disable a directive you must delete or rename the tag (e.g., change X-PRE-PROCESS to X-NO-PRE-PROCESS).
Every module that FreeSWITCH loads at startup can optionally have a configuration file in autoload_configs/. The special file modules.conf.xml controls which modules are loaded — every <load module="…"/> line causes FreeSWITCH to load that shared library on start.
Lines that are commented out (<!-- <load module="…"/> -->) are not loaded. To add a module, uncomment the relevant line (or add a new one) and run reloadxml followed by reload <module_name> at the FreeSWITCH console — or restart the process.
At startup, the preprocessor compiles the entire configuration tree into a single file at $${base_dir}/log/freeswitch.xml.fsxml (typically /var/log/freeswitch/freeswitch.xml.fsxml). This file is memory-mapped by the running process. Do not edit it directly while FreeSWITCH is running. To inspect the fully expanded configuration, read this file or use the xml_locate API from the fs_cli console.
For a reference of every global preprocessor variable — including IP addresses, codec preferences, and port numbers — see Global Variables (vars.xml).
