Understanding the FreeSWITCH user directory

The FreeSWITCH user directory is based on a centralized XML document, comprising of one or more <domain> elements. Each <domain> can contain either <users> elements or <groups> elements. A <groups> element contains one or more <group> elements, each of which contains one or more <users> elements. In turn, a <users> element contains one or more <user> elements. A small, simple example would look like the following:

<section name="directory">
  <domain name="example.com">
    <groups>
      <group name= "default">
        <users>
          <user id="1001">
            <params>
              <param name="password" value="1234"/>
          </params>
          </users>
        </user>
      </group>
    </groups>
  </domain>
</section>

Some more basic configurations may not have a need to organize the users in groups so it is possible to omit the <groups> element completely, and just insert several <user> elements into the top <domain> element.

The important thing is that each user@domain derived from this directory is available to all components in the system—it's a single centralized directory for storing all FreeSWITCH user information. If you register as a user with a SIP phone or if you try to leave a voicemail message for a user, FreeSWITCH looks in the same place for user data. This is important because it limits duplication of data, and makes it more efficient than it would be if each component kept track of its users separately.

This system should work well for a small system with a few users in it, but what about a large system with thousands of users? What if a user wants to connect his or her existing database to FreeSWITCH to provide the user directory? Well, using mod_xml_curl that we discussed in Chapter 1, Architecture of FreeSWITCH, we can create a web service that gets the request for the entries in the user directory, in much the same way a web page sends the results of an HTML form submission. In turn, that web service can query an existing database of users regardless of the format, and construct the XML records in the format that the FreeSWITCH registry expects. mod_xml_curl returns the data to the module requesting the lookup. This means that instant, seamless integration with your existing setup is possible; your data is still kept in its original, central location.

The user directory can be accessed by any subsystem within FreeSWITCH. This includes modules, scripts, and the FSAPI interface among others. In this chapter, we are going to learn how the Sofia SIP module employs the user directory to authenticate your soft phone or hardware SIP phone. If you are a developer, you may appreciate some nifty things you can do with your user directory, such as adding a <variables> element to either the <domain>, the <group>, or the <user> element. In this element you can set many <variable> elements, allowing you to set channel variables that will apply to every call made by a particular authenticated user. This can come in very handy in the Dialplan because it allows you to make user-specific routing decisions. It is also possible to define IP address ranges using CIDR notation, which can be used to authenticate particular users based on what remote network address they connect from. This removes the need for a login and password, if your user always logs in from the same remote IP address.

The directory is implemented in pure XML. This is advantageous for several reasons, not least of which is the X in XML: Extensible . Since XML is, by definition, extensible, the directory structure is also extensible. If we need to add a new element to the directory, we can do so simply by adding to the existing XML structure.