mod_xml_ldap — LDAP-Backed XML Configuration

mod_xml_ldap is an XML-interface module in the src/mod/xml_int category. It registers a search callback with FreeSWITCH's XML-fetch system so that directory and configuration lookups are answered by querying an LDAP server rather than reading flat XML files. When FreeSWITCH needs a section—directory, configuration, dialplan, or phrases—the module connects to the configured LDAP URL, executes a parametric filter, and synthesizes the resulting XML document in memory.

Reach for this module when user accounts already live in an LDAP/Active-Directory tree and you want FreeSWITCH to look up SIP credentials, voicemail settings, and caller-ID values directly from that source of truth, without exporting or duplicating the data into flat directory/*.xml files.

Loading the Module

The module name for modules.conf.xml and fs_cli is mod_xml_ldap. It is not present in the vanilla autoload_configs/modules.conf.xml and must be added manually:

<load module="mod_xml_ldap"/>

The module requires OpenLDAP client libraries (lber.h, ldap.h) at compile time. Pass --enable-mod_xml_ldap to ./configure, or add the module to modules.conf before building.

Configuration: xml_ldap.conf.xml

mod_xml_ldap reads autoload_configs/xml_ldap.conf.xml on load. The file contains a <bindings> block with one or more <binding> elements. Each binding names the FreeSWITCH section it serves, provides LDAP connection credentials, and (for directory bindings) lists attribute translation rules.

Binding Parameters

Parameter	Purpose	Accepted Values	Default
filter (with bindings attr)	LDAP search filter; %s is replaced with the extension (directory) or the key name/value (configuration). The FreeSWITCH section answered is derived from the <binding> element's name attribute (via switch_xml_parse_section_string); the bindings attribute on this param only sets the internal query type.	Any valid LDAP filter string; bindings = directory, configuration, dialplan, or phrases	None — required
basedn	Base DN for the LDAP search; %s is replaced with the domain (directory) or the tag name (configuration).	Any LDAP DN string	None — required
url	LDAP server URL.	ldap://host, ldaps://host, or any URI accepted by ldap_initialize(3)	None — required
binddn	DN used to bind to the LDAP server.	Any LDAP DN string	None (anonymous bind if omitted)
bindpass	Password for the bind DN.	Plain-text string	None

Directory Attribute Translation (<trans>)

For directory bindings, a <trans> block maps LDAP attribute names to FreeSWITCH user fields. Each <tran> element carries:

• name — the FreeSWITCH field name (see table below)
• mapfrom — the LDAP attribute whose value is read

Recognised name values and their roles in the synthesized XML:

name	Role in FreeSWITCH directory XML
id	User id attribute
cidr	User cidr attribute
number-alias	User number-alias param
dial-string	User dial-string param
password	User password param
a1-hash	User a1-hash param
reverse-auth-user	User reverse-auth-user param
reverse-auth-pass	User reverse-auth-pass param
vm-password	User vm-password param
vm-enabled	User vm-enabled param
vm-mailfrom	User vm-mailfrom param
vm-mailto	User vm-mailto param
vm-notify-mailto	User vm-notify-mailto param
vm-attach-file	User vm-attach-file param
vm-message-ext	User vm-message-ext param
vm-email-all-messages	User vm-email-all-messages param
vm-keep-local-after-mail	User vm-keep-local-after-mail param
vm-notify-email-all-messages	User vm-notify-email-all-messages param
vm-skip-instructions	User vm-skip-instructions param
vm-cc	User vm-cc param
vm-disk-quota	User vm-disk-quota param
accountcode	User accountcode variable
user_context	User user_context variable
vm_mailbox	User vm_mailbox variable
callgroup	User callgroup variable
toll_allow	User toll_allow variable
effective_caller_id_number	User effective_caller_id_number variable
effective_caller_id_name	User effective_caller_id_name variable
outbound_caller_id_number	User outbound_caller_id_number variable
outbound_caller_id_name	User outbound_caller_id_name variable

Example Configuration

The following is a trimmed excerpt from the shipped xml_ldap.conf.xml showing a directory binding:

<configuration name="xml_ldap.conf" description="XML LDAP Gateway">
  <bindings>
    <binding name="directory">
      <!-- %s in filter is replaced with the extension being looked up -->
      <param name="filter" value="(&amp;(objectClass=FSAccount)(fsuid=%s))" bindings="directory"/>
      <!-- %s in basedn is replaced with the SIP domain -->
      <param name="basedn" value="ou=%s,ou=customers,o=example" />
      <param name="url" value="ldap://1.2.3.4" />
      <param name="binddn" value="cn=admin,o=example" />
      <param name="bindpass" value="secret" />
      <trans>
        <tran name="id"                          mapfrom="fsUid" />
        <tran name="password"                    mapfrom="fsPassword" />
        <tran name="a1-hash"                     mapfrom="fsA1Hash" />
        <tran name="dial-string"                 mapfrom="fsDialString" />
        <tran name="vm-enabled"                  mapfrom="fsVmEnabled" />
        <tran name="vm-password"                 mapfrom="fsVmPassword" />
        <tran name="effective_caller_id_number"  mapfrom="fsEffectiveCallerIDNumber" />
        <tran name="effective_caller_id_name"    mapfrom="fsEffectiveCallerIDName" />
      </trans>
    </binding>
  </bindings>
</configuration>

A commented-out configuration binding example is also present in the shipped file; uncomment and adapt it to serve configuration section lookups from LDAP.

API Commands

Command	Purpose	Syntax
xml_ldap	Registered API stub — currently returns SWITCH_STATUS_FALSE and performs no action.	xml_ldap

freeswitch@> xml_ldap

Dependencies

mod_xml_ldap requires the OpenLDAP client library (libldap and liblber). Install the development package for your distribution (e.g., libldap2-dev on Debian/Ubuntu, openldap-devel on RHEL/CentOS) before compiling.

Source: src/mod/xml_int/mod_xml_ldap, src/mod/xml_int/mod_xml_ldap/conf/autoload_configs/xml_ldap.conf.xml