Skip to main content

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.

The vanilla configuration that ships with FreeSWITCH is a fully functional PBX out of the box. It includes 20 pre-provisioned SIP users (1000–1019), a demo IVR, a music-on-hold stream, conference rooms, and a voicemail system — everything you need to explore FreeSWITCH’s capabilities without writing a single line of configuration. This guide walks you from a fresh install to your first live call in under ten minutes.
1

Install FreeSWITCH

Follow the Installation guide to get FreeSWITCH onto your system using the SignalWire package repository (Debian/Ubuntu recommended) or by building from source.Once installed, confirm the binary is available:
freeswitch -version
2

Start FreeSWITCH

As a systemd service (recommended for package installs):
systemctl start freeswitch
In the foreground with an interactive console (useful for development):
freeswitch -c
The -c flag keeps FreeSWITCH in the foreground and attaches an interactive console directly. You will see the startup log scroll by, ending with a freeswitch@hostname> prompt when the switch is ready.To run as a background daemon:
freeswitch -nc
3

Connect with fs_cli

fs_cli is the FreeSWITCH command-line interface. It connects to the running switch via the Event Socket (port 8021) and gives you access to all API commands and real-time event streams.
fs_cli -H 127.0.0.1 -P 8021 -p ClueCon
FlagValueDescription
-H127.0.0.1Host where FreeSWITCH is running
-P8021Event Socket port
-pClueConEvent Socket password (vanilla default)
You should see the freeswitch@hostname> prompt. Type status and press Enter to confirm the switch is operational.
The default Event Socket password is ClueCon. This is a well-known default — change it before exposing your switch to any network. Edit autoload_configs/event_socket.conf.xml and set a strong password in the <param name="password"> field, then reload the module with reload mod_event_socket.
4

Register a SIP softphone

Open your SIP softphone (Zoiper, Linphone, MicroSIP, Bria, or any standards-compliant client) and create a new account with these settings:
SettingValue
SIP Server / DomainYour server’s IP address (e.g. 192.168.1.10)
SIP Port5060
Username1000
Password1234
TransportUDP
The vanilla configuration pre-provisions users 1000 through 1019 in conf/directory/default/. The SIP domain defaults to the server’s detected local IPv4 address ($${local_ip_v4} in vars.xml) — use that same IP as the SIP server in your softphone. Once registered, your softphone should show a green “registered” indicator.To register a second softphone for two-party calling, repeat the process with username 1001 and the same password 1234.
5

Make your first test call

With your softphone registered as extension 1000, dial one of the built-in test destinations:
  • 9664 — Music on hold. Plays the default MOH stream (local_stream://moh). Hang up when done.
  • 9386 — “Laugh break.” Plays a funny audio phrase and hangs up.
  • 5000 — Demo IVR. Answers and launches the interactive demo_ivr menu.
  • 4000 (or *98) — Voicemail main menu. Lets you check messages for your extension.
  • 1001 — Dial another registered user directly (if you have a second softphone registered as 1001).
You should hear audio within a second or two of the call being answered. If not, check the FreeSWITCH console for errors and confirm your SIP registration succeeded.

​
Default Users

The vanilla configuration ships with 20 pre-configured SIP users: 1000 through 1019. Each user’s credentials are defined in a separate XML file under conf/directory/default/: 
/etc/freeswitch/directory/default/1000.xml
/etc/freeswitch/directory/default/1001.xml
...
/etc/freeswitch/directory/default/1019.xml
All 20 users share the same default password defined in vars.xml: 
<X-PRE-PROCESS cmd="set" data="default_password=1234"/>
In a production environment you must change this password. You can either edit vars.xml to set a global password and reload, or edit individual user XML files to assign unique passwords per extension.

​
Default Extensions

The vanilla dialplan (conf/dialplan/default.xml) exposes a rich set of built-in test extensions:
ExtensionNameDescription
1000–1019User extensionsRing the registered SIP device for that user; falls through to voicemail after 30 seconds.
4000 / *98Voicemail mainCheck voicemail for any extension.
5000IVR demoLaunches the demo_ivr interactive voice response menu.
5900Call parkTransfer a call here to park it in a queue.
9664Music on holdPlays the local_stream://moh music stream until you hang up.
9386Laugh breakPlays the phrase:funny_prompts audio and disconnects.
3000–3999ConferencesNarrowband (8 kHz) conference rooms — dial any extension in this range to create or join that room.
3500–3599Wideband conferences16 kHz wideband conference rooms.

​
Console Commands

Once connected with fs_cli, these commands are most useful when getting started: 
freeswitch@hostname> status
Shows uptime, session counts, and whether the switch is running normally. 
freeswitch@hostname> sofia status
Displays all SIP profiles (internal, external) and their bound IP/port. Use sofia status profile internal for per-profile detail including registrations. 
freeswitch@hostname> show channels
Lists all active calls with UUID, caller ID, destination, and duration. 
freeswitch@hostname> show registrations
Lists all currently registered SIP endpoints — useful to confirm your softphone registered successfully. 
freeswitch@hostname> originate sofia/internal/1001@127.0.0.1 9664
Originates a call from extension 1001 to the music-on-hold extension. A general originate command takes the form originate <call-url> <destination-extension>.

​
Sample fs_cli session

$ fs_cli -H 127.0.0.1 -P 8021 -p ClueCon

                    Type /help <ENTER> to see a list of commands


+OK

freeswitch@hostname> status
UP 0 years, 0 days, 0 hours, 4 minutes, 23 seconds, 612 milliseconds, 504 microseconds
FreeSWITCH (Version 1.10.x -release ) is ready
3 session(s) since startup
1 session(s) - peak 1, last 5min 1
0 session(s) per Sec out of max 30, peak 1, last 5min 1
1000 session(s) max
min idle cpu 0.00/6.50
Current Stack Size (reserved/inuse): 240K/16K

freeswitch@hostname> sofia status
                     Name    Type                                        Data      State
=================================================================================================
                 internal profile                sip:mod_sofia@192.168.1.10:5060      RUNNING (0)
                 external profile                sip:mod_sofia@192.168.1.10:5080      RUNNING (0)
=================================================================================================
2 profiles 0 aliases

freeswitch@hostname> show registrations
reg_user,realm,token,url,expires,network_ip,network_port,network_proto,hostname,metadata
1000,192.168.1.10,..,...,3600,...,...,udp,hostname,
Total items returned: 1

freeswitch@hostname> /exit
+BYE

Build docs developers (and LLMs) love

Get started for freeTalk to us