Documentation Index
Fetch the complete documentation index at: https://mintlify.com/signalwire/freeswitch/llms.txt
Use this file to discover all available pages before exploring further.
vars.xml is the first file included by freeswitch.xml and is loaded before any module configuration or dialplan. It defines global preprocessor variables using X-PRE-PROCESS cmd="set" directives. Because these variables are resolved by the preprocessor — not at runtime — their values are baked into the compiled configuration at startup. Changing a value in vars.xml requires either a full restart or a reloadxml command, after which modules that re-read their configuration will pick up the new values.
vars.xml (abbreviated)
The following is an abbreviated view of the vanilla vars.xml showing the most important settings. The full file ships with extensive inline comments explaining every option.
<include>
<!-- Change this! Default password used for all demo extensions. -->
<X-PRE-PROCESS cmd="set" data="default_password=1234"/>
<!-- Sound file path prefix -->
<X-PRE-PROCESS cmd="set" data="sound_prefix=$${sounds_dir}/en/us/callie"/>
<!-- Default SIP domain — defaults to the machine's local IPv4 address -->
<X-PRE-PROCESS cmd="set" data="domain=$${local_ip_v4}"/>
<X-PRE-PROCESS cmd="set" data="domain_name=$${domain}"/>
<!-- Hold music source -->
<X-PRE-PROCESS cmd="set" data="hold_music=local_stream://moh"/>
<!-- Public (NAT) IP addresses resolved via STUN at startup -->
<X-PRE-PROCESS cmd="stun-set" data="external_rtp_ip=stun:stun.freeswitch.org"/>
<X-PRE-PROCESS cmd="stun-set" data="external_sip_ip=stun:stun.freeswitch.org"/>
<!-- Codec preferences (applied globally to both SIP profiles) -->
<X-PRE-PROCESS cmd="set" data="global_codec_prefs=OPUS,G722,PCMU,PCMA,H264,VP8"/>
<X-PRE-PROCESS cmd="set" data="outbound_codec_prefs=OPUS,G722,PCMU,PCMA,H264,VP8"/>
<!-- Internal SIP profile (registered phones) -->
<X-PRE-PROCESS cmd="set" data="internal_auth_calls=true"/>
<X-PRE-PROCESS cmd="set" data="internal_sip_port=5060"/>
<X-PRE-PROCESS cmd="set" data="internal_tls_port=5061"/>
<X-PRE-PROCESS cmd="set" data="internal_ssl_enable=false"/>
<!-- External SIP profile (trunks / gateways) -->
<X-PRE-PROCESS cmd="set" data="external_auth_calls=false"/>
<X-PRE-PROCESS cmd="set" data="external_sip_port=5080"/>
<X-PRE-PROCESS cmd="set" data="external_tls_port=5081"/>
<X-PRE-PROCESS cmd="set" data="external_ssl_enable=false"/>
<!-- Outbound caller ID defaults -->
<X-PRE-PROCESS cmd="set" data="outbound_caller_name=FreeSWITCH"/>
<X-PRE-PROCESS cmd="set" data="outbound_caller_id=0000000000"/>
<!-- Locale / debug -->
<X-PRE-PROCESS cmd="set" data="default_areacode=918"/>
<X-PRE-PROCESS cmd="set" data="default_country=US"/>
<X-PRE-PROCESS cmd="set" data="console_loglevel=info"/>
<!-- TLS version and cipher suite -->
<X-PRE-PROCESS cmd="set" data="sip_tls_version=tlsv1,tlsv1.1,tlsv1.2"/>
<X-PRE-PROCESS cmd="set" data="sip_tls_ciphers=ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH"/>
</include>
Core Variables
These variables establish the identity and network addressing of the FreeSWITCH instance. Several (local_ip_v4, hostname, etc.) are calculated dynamically by FreeSWITCH itself and made available before vars.xml is processed.
| Variable | Default | Description |
|---|
domain | $${local_ip_v4} | Default SIP domain. Used for authentication lookups and presence. |
domain_name | $${domain} | Alias for domain; used in dialplan and directory. |
local_ip_v4 | (auto-detected) | Primary local IPv4 address of the host. |
local_mask_v4 | (auto-detected) | Subnet mask corresponding to local_ip_v4. |
local_ip_v6 | (auto-detected) | Primary local IPv6 address, if available. |
external_rtp_ip | stun:stun.freeswitch.org | Public IP used in SDP for RTP media (NAT traversal). |
external_sip_ip | stun:stun.freeswitch.org | Public IP advertised in SIP Contact/Via headers. |
hostname | (auto-detected) | System hostname; available as $${hostname}. |
Codec Variables
Codec preference strings are comma-separated lists of codec names. They are referenced by both SIP profiles via $${global_codec_prefs} and $${outbound_codec_prefs}.
| Variable | Default | Description |
|---|
global_codec_prefs | OPUS,G722,PCMU,PCMA,H264,VP8 | Preferred codecs for inbound and general negotiation. |
outbound_codec_prefs | OPUS,G722,PCMU,PCMA,H264,VP8 | Preferred codecs for outbound (originated) calls. |
G722, PCMU, iLBC@30i, or speex@16000h@20i. FreeSWITCH evaluates the list left-to-right and selects the first codec that both endpoints support.
Port Variables
| Variable | Default | Description |
|---|
internal_sip_port | 5060 | UDP/TCP port for the internal SIP profile (registered phones). |
internal_tls_port | 5061 | TLS port for the internal SIP profile. |
internal_ssl_enable | false | Set to true to enable TLS on the internal profile. |
external_sip_port | 5080 | UDP/TCP port for the external SIP profile (trunks). |
external_tls_port | 5081 | TLS port for the external SIP profile. |
external_ssl_enable | false | Set to true to enable TLS on the external profile. |
Sound Variables
| Variable | Default | Description |
|---|
sound_prefix | $${sounds_dir}/en/us/callie | Base path for all sound file references. Used by voicemail, IVR, and say applications. |
hold_music | local_stream://moh | Default music-on-hold stream. Can be a local_stream:// source or a file path. |
sounds_dir variable is calculated at compile time (typically /usr/share/freeswitch/sounds). The sound_prefix variable can be overridden to point to a different voice pack — for example, uncomment the Allison voice line in vars.xml:
<!-- Switch from Callie to Allison voice pack -->
<X-PRE-PROCESS cmd="set" data="sound_prefix=$${sounds_dir}/en/us/allison"/>
Using Variables
Preprocessor variables are referenced with double-dollar syntax ($${variable_name}) anywhere in any XML file that is included by the preprocessor. The substitution happens before the XML is parsed, so the variable value is literally inserted into the text:
<!-- In sip_profiles/internal.xml -->
<param name="sip-port" value="$${internal_sip_port}"/>
<!-- Resolves to: <param name="sip-port" value="5060"/> -->
<!-- In dialplan/default.xml -->
<action application="set" data="sound_prefix=$${sound_prefix}"/>
vars.xml and reference them anywhere downstream:
<!-- Define in vars.xml -->
<X-PRE-PROCESS cmd="set" data="my_pbx_name=Acme PBX"/>
<!-- Use in autoload_configs/ivr.conf.xml -->
<param name="greeting" value="Welcome to $${my_pbx_name}"/>
Channel Variables vs. Global Variables
This is one of the most common points of confusion for new FreeSWITCH administrators. There are two completely separate variable systems:
| Global / Preprocessor Variables | Channel Variables |
|---|
| Syntax | $${variable} (double $) | ${variable} (single $) |
| When resolved | At startup, by the preprocessor | At call time, by the dialplan engine |
| Scope | Entire configuration file tree | Per-call channel |
| Set with | X-PRE-PROCESS cmd="set" in vars.xml | <action application="set" data="key=value"/> in dialplan |
| Example | $${domain} → 192.0.2.1 | ${caller_id_number} → +15551234567 |
When you see $${...} (two dollar signs), the value comes from vars.xml and is fixed at the time FreeSWITCH starts. When you see ${...} (one dollar sign), the value is read from the active call’s channel at the moment that dialplan action executes — it can change for every call. Mixing them up is the most frequent source of configuration bugs.To inspect the current value of a preprocessor variable from the fs_cli console, use:eval $${domain}
eval $${sound_prefix}
