Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (
Help us improve Python packaging - Donate today!

A Python API that makes configuring FreeSWITCH a lunch break

Project Description

sandswitches is a Python API for configuring FreeSWITCH by modifying it’s XML configuration.

Client code can for the most part modify the configuration using standard Python data structures like lists and dictionaries.


pip install sandswitches


The API is low-level and straightforward; mutating the configuration is the same as modifying a standard data structure:

import os
import sandswitches

# connect remote; you'll need ssh access and may have to unlock your key
confmng = sandswitches.manage(
    'megatron', keyfile=os.path.expanduser('~') + '/.ssh/id_rsa')

confmng.sofia['profiles']['internal']['settings']['sip-port'] = '5069'

# restart the profile to bind the new port

If you were to run this in an interactive shell you can get an idea of the data formatting:

>>> import pprint
# convert and pprint as dict
>>> pprint.pprint(dict(confmng.sofia['profiles']['internal']['settings']))
{'apply-inbound-acl': 'domains',
'apply-nat-acl': '',
'auth-all-packets': 'false',
'auth-calls': 'true',
'challenge-realm': 'auto_from',
'context': 'public',
'debug': '0',
'dialplan': 'XML',
'dtmf-duration': '2000',
'ext-rtp-ip': 'auto-nat',
'ext-sip-ip': 'auto-nat',
'force-register-db-domain': '',
'force-register-domain': '',
'force-subscription-domain': '',
'forward-unsolicited-mwi-notify': 'false',
'hold-music': 'local_stream://moh',
'inbound-codec-negotiation': 'generous',
'inbound-codec-prefs': 'OPUS,G722,PCMU,PCMA,GSM',
'inbound-late-negotiation': 'true',
'inbound-reg-force-matching-username': 'true',
'inbound-zrtp-passthru': 'true',
'local-network-acl': '',
'log-auth-failures': 'false',
'manage-presence': 'true',
'nonce-ttl': '60',
'presence-hosts': ',',
'presence-privacy': 'false',
'record-path': '/root/sng_fs_runtime/recordings',
'record-template': '${caller_id_number}.${target_domain}.${strftime(%Y-%m-%d-%H-%M-%S)}.wav',
'rfc2833-pt': '101',
'rtp-hold-timeout-sec': '1800',
'rtp-ip': '',
'rtp-timeout-sec': '300',
'rtp-timer-name': 'soft',
'sip-capture': 'no',
'sip-ip': '',
'sip-port': '5069',
'sip-trace': 'no',
'tls': 'false',
'tls-bind-params': 'transport=tls',
'tls-ciphers': 'ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH',
'tls-only': 'false',
'tls-passphrase': '',
'tls-sip-port': '5061',
'tls-verify-date': 'true',
'tls-verify-depth': '2',
'tls-verify-in-subjects': '',
'tls-verify-policy': 'none',
'tls-version': 'tlsv1,tlsv1.1,tlsv1.2',
'watchdog-enabled': 'no',
'watchdog-event-timeout': '30000',
'watchdog-step-timeout': '30000'}

# object form
>>> confmng.event_socket
    'settings': settings({
        'listen-ip': '::', 'password': 'ClueCon', 'listen-port': '8021', 'nat-map': 'false'

# print the XML contents
>>> confmng.event_socket.printxml()
<configuration name="event_socket.conf" description="Socket Client">
    <param name="nat-map" value="false"/>
      <param name="listen-ip" value="::"/>
      <param name="listen-port" value="8021"/>
      <param name="password" value="ClueCon"/>


There is currently no error checking of any sort implemented other then what fs_cli commands like reloadxml and profile starting/stopping return (which is not very much sadly).

Supported config sections

sandswitches uses object-relational mappings to transform XML patterns in the FreeSWITCH config files into simple data structures. Since each section uses a heterogeneous (read not consistent) set of patterns, object relations need to be manually specified through a small schema system;

Since the relations need to explicit not all of the XML document has been fully mapped, yet. Currently there is support for the following sections:

  • sofia
  • directory
  • event_socket

The dialplan section will probably never be supported as it’s far to complex (and convoluted) to map to a reasonable set of data structures.

Instead we recommend using switchy, another one of our projects which let’s you orchestrate sophisticated call control using FreeSWITCH’s built in event system.

Extending to more sections

We’d absolutely love to see the entire core config mapped out for use in sandswitches. Currently we’ve only added what we’ve needed. If there’s a section missing that you need please feel free to open an issue.

If you want to extend sandswitches to include your section of choice take a look at the sandswitches.schema module and see if you can figure out how to write your own section schema. We’ll hopefully have a better write up on this in the near future.


In order to simplify XML processing sandswitches collapses the target FreeSWITCH server’s XML config to a single master freeswitch.xml. The original will be backed up with an appropriate time-date suffix which can renamed back to freeswitch.xml at any time if you want to revert to the original multi-file state.

Release History

Release History

This version
History Node


Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting