System Vars Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Categories
Settings Reference
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Is System Vars?

System Vars is a FreeSWITCH global configuration module that manages the vars.xml file. These are system-wide variables that control core FreeSWITCH behavior including codecs, security, paths, debugging, and WebRTC settings.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  System Vars Architecture                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        System Vars                                       │   │
│  │                                                          │   │
│  │  Categories:                                             │   │
│  │  ├─ General Configuration                               │   │
│  │  ├─ Codecs & Media                                      │   │
│  │  ├─ Caller ID & Regional                                │   │
│  │  ├─ Security & TLS                                      │   │
│  │  ├─ WebRTC & Video                                      │   │
│  │  ├─ Debug & Logs                                        │   │
│  │  └─ FreeSWITCH Paths                                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Generates XML                                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        vars.xml                                          │   │
│  │                                                          │   │
│  │  <X-PRE-PROCESS cmd="set" data="var=value"/>            │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Loaded by FreeSWITCH                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        FreeSWITCH Core                                   │   │
│  │                                                          │   │
│  │  Global variables available:                             │   │
│  │  ${global_codec_prefs}                                  │   │
│  │  ${hold_music}                                          │   │
│  │  ${recordings_dir}                                       │   │
│  │  ...                                                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Files

File	Description
`modules/systemVars/`	Frontend module
`vars.xml`	Generated FreeSWITCH configuration

---

2. Module Overview (Commercial/Business)

Business Value

System Vars provides centralized FreeSWITCH configuration:

Without System Vars	With System Vars
Edit XML files	Web interface
SSH to server	Browser-based
Error-prone	Validated
Expert only	Admin-friendly

Use Cases

Codec Configuration

- Set global codec preferences

- Configure SRTP settings

Path Management

- Configure recording locations

- Set voicemail directories

Security Settings

- TLS version/ciphers

- SRTP encryption

WebRTC/Video

- ICE servers

- Video bandwidth

Feature Highlights

Feature	Benefit
Web Interface	No SSH needed
Categories	Organized settings
XML Preview	See before applying
Reset Option	Restore defaults
Validation	Prevent errors
Documentation	Tooltips explain each

---

3. Module Overview (End User/Administrator)

What Can You Do?

Configure global codec preferences
Set default caller ID
Configure TLS/security settings
Set WebRTC ICE servers
Define system paths
Enable debugging
Preview generated XML

System Vars Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              System Vars                                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Configure FreeSWITCH system variables                          │
│                                                                 │
│  [Preview XML] [Download XML] [Reset All] [Save]               │
│                                                                 │
│  ▼ General Configuration                                        │
│  ├─ Language Sound Path: [/usr/share/freeswitch/sounds/en]    │
│  ├─ Hold Music: [local_stream://moh                  ]        │
│  ├─ Use SIP Profile: [internal ▼]                              │
│  └─ Enable Cache: ✓                                            │
│                                                                 │
│  ▼ Codecs & Media                                               │
│  ├─ Global Codec Prefs: [OPUS,PCMU,PCMA,G722         ]        │
│  ├─ Outbound Codec Prefs: [PCMU,PCMA,G722            ]        │
│  ├─ Secure RTP Mode: [optional ▼]                              │
│  ├─ RTP Timeout: [300                                ]        │
│  └─ RTP Hold Timeout: [1800                          ]        │
│                                                                 │
│  ▶ Caller ID & Regional Settings                                │
│  ▶ Security & TLS                                               │
│  ▶ WebRTC & Video                                               │
│  ▶ Debug & Logs                                                 │
│  ▶ FreeSWITCH Paths                                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

XML Preview

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              XML Preview                                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Generated vars.xml configuration for FreeSWITCH               │
│                                                                 │
│  <include>                                                      │
│    <X-PRE-PROCESS cmd="set" data="hold_music=local_stream://moh"/>│
│    <X-PRE-PROCESS cmd="set" data="global_codec_prefs=OPUS,PCMU"/>│
│    <X-PRE-PROCESS cmd="set" data="recordings_dir=/var/recordings"/>│
│    ...                                                          │
│  </include>                                                     │
│                                                                 │
│  [Download XML] [Close]                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Preview First: Use XML Preview before saving.

TIP

Modified Indicator: Yellow dot shows changed values.

CAUTION

Restart Required: Changes require FreeSWITCH restart.

---

4. Configuration Categories

General Configuration

Setting	Description
Language Sound Path	Audio prompts location
Hold Music	Default MOH stream
Use SIP Profile	Default SIP profile
Enable Cache	Cache global vars

Codecs & Media

Setting	Description
Global Codec Prefs	Inbound codec order
Outbound Codec Prefs	Outbound codec order
Secure RTP Mode	SRTP enforcement
RTP Timeout	Inactivity timeout
RTP Hold Timeout	Hold timeout
RTP Liberal DTMF	Allow both DTMF methods

Caller ID & Regional

Setting	Description
Caller ID Name	Default outbound name
Caller ID Number	Default outbound number
Country Code	Dialing country code
Default Country	Dialplan country
Default Area Code	Local area code

Security & TLS

Setting	Description
SIP TLS Version	Allowed TLS versions
SIP TLS Ciphers	Cipher list
RTP Secure Media Suites	SRTP ciphers
RTP SDES Suites	SDES ciphers

WebRTC & Video

Setting	Description
WebRTC ICE Servers	STUN/TURN servers
WebRTC ICE Timeout	ICE gathering timeout
Suppress Comfort Noise	CNG for WebRTC
Max Video Bandwidth In	Inbound video limit
Max Video Bandwidth Out	Outbound video limit
Video Mute Image	Muted video PNG
No Avatar Image	Missing avatar PNG

Debug & Logs

Setting	Description
Console Log Level	Log verbosity
Call Debug	Verbose call debug

FreeSWITCH Paths

Setting	Description
Base Directory	FS installation root
Configuration Directory	XML configs
Logs Directory	Log files
Recordings Directory	Call recordings
Storage Directory	General storage
Voicemail Directory	Voicemail files
Scripts Directory	Lua scripts
Sounds Base	Audio prompts
Certificates Directory	TLS certs

---

5. Settings Reference

Common Global Variables

Variable	Example	Purpose
`global_codec_prefs`	OPUS,PCMU,PCMA	Inbound codecs
`outbound_codec_prefs`	PCMU,PCMA	Outbound codecs
`hold_music`	local_stream://moh	Default MOH
`recordings_dir`	/var/recordings	Recording path
`rtp_secure_media`	optional	SRTP mode
`media_timeout`	300	RTP timeout

SRTP Modes

Mode	Behavior
true	Always require SRTP
optional	Use if available
false	Never use SRTP

Log Levels

Level	Description
0	Console only
1	Alert
2	Critical
3	Error
4	Warning
5	Notice
6	Info
7	Debug

---

6. Common Scenarios & Examples

Scenario 1: Configure Codecs

Expand "Codecs & Media"
Set Global Codec Prefs = OPUS,PCMU,PCMA,G722
Set Outbound Codec Prefs = PCMU,PCMA
Save and restart FS

Scenario 2: Enable SRTP

Expand "Codecs & Media"
Set Secure RTP Mode = true
Expand "Security & TLS"
Set RTP Secure Media Suites
Save and restart

Scenario 3: WebRTC Setup

Expand "WebRTC & Video"
Set WebRTC ICE Servers = stun:stun.l.google.com:19302
Set ICE Timeout = 5000
Enable Suppress Comfort Noise
Save and restart

NOTE

WebRTC TLS termination is handled by Nginx on port 443 (wss://domain/ws). These ICE/STUN settings affect media negotiation only.

Scenario 4: Enable Debug

Expand "Debug & Logs"
Set Console Log Level = 7 (Debug)
Enable Call Debug
Save and restart
Check logs

---

7. Limitations & Important Notes

Technical Notes

NOTE

vars.xml: This generates the FreeSWITCH vars.xml file.

NOTE

Global Scope: These are system-wide variables.

WARNING

Restart Required: Most changes require FreeSWITCH restart.

Best Practices

Preview First: Always preview XML before saving
Backup: Download XML before major changes
Test Changes: Verify after restart
Document Changes: Note what you changed
Minimal Changes: Only change what you need

Path Variables

IMPORTANT

Path variables must point to valid directories. Invalid paths can prevent FreeSWITCH from starting.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
FS won't start	Invalid path	Check path variables
Codec issues	Wrong prefs	Verify codec list
No SRTP	Mode = false	Set rtp_secure_media
WebRTC fails	No ICE servers	Configure ICE servers
No audio	Wrong codecs	Check codec compatibility

Validate Configuration

Bash

# Check vars.xml syntax
fs_cli -x "global_getvar all"

# Verify specific variable
fs_cli -x "global_getvar global_codec_prefs"

# Reload XML
fs_cli -x "reloadxml"

Check Paths

Bash

# Verify directories exist
ls -la ${recordings_dir}
ls -la ${voicemail_dir}
ls -la ${sounds_base}

---

9. Glossary

Term	Definition
vars.xml	FreeSWITCH global variables file
Global Variable	System-wide configuration value
Codec Prefs	Ordered codec preference list
SRTP	Secure Real-time Transport Protocol
ICE	Interactive Connectivity Establishment
SDES	Session Description Protocol Security
X-PRE-PROCESS	FreeSWITCH preprocessor directive

---

Lua Script Status ℹ️

No Lua Handler Required

Component	Status
System Vars	ℹ️ Configuration module - generates vars.xml for FreeSWITCH

System Vars is a configuration module. Settings are stored and used to generate the FreeSWITCH vars.xml file. No Lua handlers are used - variables are loaded by FreeSWITCH core.

---

Documentation last updated: January 2026

System Vars Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is System Vars?

Architecture

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

System Vars Interface

XML Preview

Quick Tips

4. Configuration Categories

General Configuration

Codecs & Media

Caller ID & Regional

Security & TLS

WebRTC & Video

Debug & Logs

FreeSWITCH Paths

5. Settings Reference

Common Global Variables

SRTP Modes

Log Levels

6. Common Scenarios & Examples

Scenario 1: Configure Codecs

Scenario 2: Enable SRTP

Scenario 3: WebRTC Setup

Scenario 4: Enable Debug

7. Limitations & Important Notes

Technical Notes

Best Practices

Path Variables

8. Troubleshooting Tips

Common Issues

Validate Configuration

Check Paths

9. Glossary

Lua Script Status ℹ️

No Lua Handler Required