FreeSWITCH User Directory - Omid-Mohajerani/freeswitch GitHub Wiki

The User Directory is an XML document that is accessed by FreeSWITCH and all of its modules whenever they need to know about users' attributes. It is in the User Directory that the user's password, which groups (if any) the user belongs to, various and arbitrary variables and parameters related to the user or to the group, and so on are defined.

FreeSwitch default Directory contains default.xml and sample configuration in the default folder

https://github.com/Omid-Mohajerani/freeswitch/tree/main/FreeSWITCH/conf/directory

.
├── default
│   ├── 1000.xml
│   ├── 1001.xml
│   ├── 1002.xml
│   ├── 1003.xml
│   ├── 1004.xml
│   ├── 1005.xml
│   ├── 1006.xml
│   ├── 1007.xml
│   ├── 1008.xml
│   ├── 1009.xml
│   ├── 1010.xml
│   ├── 1011.xml
│   ├── 1012.xml
│   ├── 1013.xml
│   ├── 1014.xml
│   ├── 1015.xml
│   ├── 1016.xml
│   ├── 1017.xml
│   ├── 1018.xml
│   ├── 1019.xml
│   ├── brian.xml
│   ├── default.xml
│   ├── example.com.xml
│   └── skinny-example.xml
└── default.xml

User Directory schema

<section name="directory">
  <domain name="mydomain.com">
    <groups>
      <group name ="sales">
        <users>
          <user id="1001">
            <params>
              <param name="password" value="1234"/>
            </params>
          </user>
        </users>
      </group>
    </groups>
  </domain>
</section>
  • It contains one or more "domain".
  • each "domain" contains "groups".
  • each "groups" contains one or more "group" items.
  • Each "group" contains the "users" item, which contains one or more "user" item.
  • The "user" item contains the "params" item, which contains one or more "param" items.

the only required XML items are "domain" and "user"

<section name="directory">
  <domain name="mydomain.com">
    <user id="1001">
      <params>
        <param name="password" value="1234"/>
      </params>
    </user>
   </domain>
</section>

default.xml

After a fresh install, out of the box, you'll find the "directory" main XML file located at /usr/local/freeswitch/conf/directory/default.xml That main file will then include many other files.

<include>
  <!--the domain or ip (the right hand side of the @ in the addr-->
  <domain name="$${domain}">
    <params>
      <param name="dial-string" value="{^^:sip_invite_domain=${dialed_domain}:presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(*/${dialed_user}@${dialed_domain})},${verto_contact(${dialed_user}@${dialed_domain})}"/>
      <!-- These are required for Verto to function properly -->
      <param name="jsonrpc-allowed-methods" value="verto"/>
      <!-- <param name="jsonrpc-allowed-event-channels" value="demo,conference,presence"/> -->
    </params>

    <variables>
      <variable name="record_stereo" value="true"/>
      <variable name="default_gateway" value="$${default_provider}"/>
      <variable name="default_areacode" value="$${default_areacode}"/>
      <variable name="transfer_fallback_extension" value="operator"/>
    </variables>

    <groups>
      <group name="default">
	<users>
	  <X-PRE-PROCESS cmd="include" data="default/*.xml"/>
	</users>
      </group>

      <group name="sales">
	<users>
	  <!--
	      type="pointer" is a pointer so you can have the
	      same user in multiple groups.  It basically means
	      to keep searching for the user in the directory.
	  -->
	  <user id="1000" type="pointer"/>
	  <user id="1001" type="pointer"/>
	  <user id="1002" type="pointer"/>
	  <user id="1003" type="pointer"/>
	  <user id="1004" type="pointer"/>
	</users>
      </group>

      <group name="billing">
	<users>
	  <user id="1005" type="pointer"/>
	  <user id="1006" type="pointer"/>
	  <user id="1007" type="pointer"/>
	  <user id="1008" type="pointer"/>
	  <user id="1009" type="pointer"/>
	</users>
      </group>

      <group name="support">
	<users>
	  <user id="1010" type="pointer"/>
	  <user id="1011" type="pointer"/>
	  <user id="1012" type="pointer"/>
	  <user id="1013" type="pointer"/>
	  <user id="1014" type="pointer"/>
	</users>
      </group>
    </groups>

  </domain>
</include>

In SIP and in Verto, addresses are in the form "userid@domain", very much like in email. We can have multiple "domain" items, they would be added after the closing XML tag

 <domain name="$${domain}">

The "param" named "dial-string" defines the way the user will be reached, both the protocol(s) (sip and verto, in this case) to be used, and the specific addresses to send the call(s).As you can see, it sets both a sip and a verto address, actually using internal APIs to know whether the user is registered in those protocols, and if it is registered, at which addresses.

 <param name="dial-string" value="{^^:sip_invite_domain=${dialed_domain}:presence_id=${dialed_user}@${dialed_domain}}${sofia_contact(*/${dialed_user}@${dialed_domain})},${verto_contact(${dialed_user}@${dialed_domain})}"/>

Then there is another param, to allow the verto protocol to interact with procedure calls, for conference management and such.

  <param name="jsonrpc-allowed-methods" value="verto"/>

Then, we have a container of "variables" that will be created or set for users in this domain. Here we set many useful defaults, to be overridden both in dialplan and/or in the user or group definitions.

Then the "groups" container, and its "group" items. One of those "group" items is named "default", and inside it we can find a "users" container that includes all the XML files in the default/ subdirectory (relative to the User Directory location, eg: /usr/local/freeswitch/conf/directory/default/*.xml ). Those XML files would reasonably contain XML snippets defining "user" items.

<group name="default">
 <users>
  <X-PRE-PROCESS cmd="include" data="default/*.xml"/>
 </users>
</group>

We then can see other "group" items, each of them with a "users" item that actually contains some "user" items. But in this case those "user" items are not defining user's data and variables, instead they just indicate to look into the rest of the domain's XML definition for a user with a particular "id". This is useful to assign users to more than a group. Eg: they all belong to group "default", but some of them belong to the "sales" group too, while other belong both to "default" and to "billing" groups.

      <group name="sales">
	<users>
	  <!--
	      type="pointer" is a pointer so you can have the
	      same user in multiple groups.  It basically means
	      to keep searching for the user in the directory.
	  -->
	  <user id="1000" type="pointer"/>
	  <user id="1001" type="pointer"/>
	  <user id="1002" type="pointer"/>
	  <user id="1003" type="pointer"/>
	  <user id="1004" type="pointer"/>
	</users>
      </group>

      <group name="billing">
	<users>
	  <user id="1005" type="pointer"/>
	  <user id="1006" type="pointer"/>
	  <user id="1007" type="pointer"/>
	  <user id="1008" type="pointer"/>
	  <user id="1009" type="pointer"/>
	</users>
      </group>

      <group name="support">
	<users>
	  <user id="1010" type="pointer"/>
	  <user id="1011" type="pointer"/>
	  <user id="1012" type="pointer"/>
	  <user id="1013" type="pointer"/>
	  <user id="1014" type="pointer"/>
	</users>
      </group>
    </groups>

Users

Located by default in /usr/local/freeswitch/conf/directory/default/ folder when you install freeswitch from sourcecode

<include>
  <user id="1000">
    <params>
      <param name="password" value="$${default_password}"/>
      <param name="vm-password" value="1000"/>
    </params>
    <variables>
      <variable name="toll_allow" value="domestic,international,local"/>
      <variable name="accountcode" value="1000"/>
      <variable name="user_context" value="default"/>
      <variable name="effective_caller_id_name" value="Extension 1000"/>
      <variable name="effective_caller_id_number" value="1000"/>
      <variable name="outbound_caller_id_name" value="$${outbound_caller_name}"/>
      <variable name="outbound_caller_id_number" value="$${outbound_caller_id}"/>
      <variable name="callgroup" value="techsupport"/>
    </variables>
  </user>
</include>

At the beginning, inside the very same "user" tag, is declared the "id" of the user (this is the same "id" that will be looked upon by the "pointer" kind of "user" item we saw in previous section).

<user id="1000">

Inside the "user" container item, in this example we find both a "params" and a "variables" container item. Inside the "params" container there are "param" items that define the parameters that belongs exclusively to this user. Possibly those "param" items override the ones set in the "domain" container, or in the "group" container. For example probably want to modify are "password", obviously, so to set a specific password for this user (instead of inheriting the default one set into vars.xml file), and "vm-password".

   <params>
     <param name="password" value="$${default_password}"/>
     <param name="vm-password" value="1000"/>
   </params>

Exactly the same happens for the "variables" container, with "variable" items. Here, you may want to override "default_gateway", so to use a specific SIP gateway for this user. And very often you want to personalize some of the "*id_name" and "*id_number" variable items. Also, you may want to set your own variables. There are some already set in the demo example user definitions 1000.xml...1019.xml. All of them can then be referenced in dialplan and scripts, for example you want to check what kind of call a user is allowed to originate, and you choose to test the content of the variable ${toll_allow} for this purpose. Remember, all those variables are available both to core FreeSWITCH and to all modules. So, the modules generating CDRs will be able to reference them, you can have the content of the ${callgroup} reported into your Call Detail Records (for accounting purposes):

    <variables>
      <variable name="toll_allow" value="domestic,international,local"/>
      <variable name="accountcode" value="1000"/>
      <variable name="user_context" value="default"/>
      <variable name="effective_caller_id_name" value="Extension 1000"/>
      <variable name="effective_caller_id_number" value="1000"/>
      <variable name="outbound_caller_id_name" value="$${outbound_caller_name}"/>
      <variable name="outbound_caller_id_number" value="$${outbound_caller_id}"/>
      <variable name="callgroup" value="techsupport"/>
    </variables>

The following table lists each variable and what it is used for:

Variable Purpose.
toll_allow Specifies which types of calls the user can make
accountcode Arbitrary value that shows up in CDR data
user_context The dialplan context that is used when this person makes a call
effective_caller_id_name Caller ID name displayed on called party's phone when calling another registered user
effective_caller_id_number Caller ID number displayed on called party's phone when calling another registered user
outbound_caller_id_name Caller ID name sent to provider on outbound calls
outbound_caller_id_number Caller ID number sent to provider on outbound calls
callgroup Arbitrary value that can be used in dialplan or CDR

Reference: https://www.packtpub.com/product/freeswitch-1-8/9781785889134

⚠️ **GitHub.com Fallback** ⚠️