Page tree
Skip to end of metadata
Go to start of metadata


The FreeSWITCH $FS_ROOT/conf/directory/ contains accounts (i.e., XML files) for all users (i.e., SIP phone extensions) that may register to FS.

Note: This is not the same syntax which is used in the Dialplan

 Click to expand Table of Contents

User settings

Basic User

The basic configuration is quite simple, you just need to add user names and passwords.

In the file $FS_ROOT/conf/directory/mike_x2239.xml, for example, add:

The domain tag tells FS to which domain this user belongs. Note that all users should be in the same domain tag, unless you are using multiple domains. The user name is the part left of @ in the sip address (in this case "mike" in ""). $${sip_profile} will be replaced with the domain that is specified in vars.xml.


A plaintext password may replaced with an "a1-hash". An a1-hash is generated by applying the MD5 digest function to the string "username:domain:password" (sans quotes). In Linux, the encoded password may be generated thusly: openssl dgst -md5 < filename, or echo -n "username:domain:password" | openssl dgst -md5.

reverse authentication

Some endpoints require authentication for certain types of requests (ex. SIP NOTIFY for resync). You can specify the credentials used for this digest authentication.


You can also add support for vcards if you are using mod_dingaling. Then you add information in the following format:


A group is a logical collection of users that FreeSWITCH can use to bridge calls in a serial or parallel fashion, depending on the arguments to the group_call application. Using groups is optional -- you can put your users straight into the domain section if you desire.

This is specially useful if you use mod_xml_curl to provide the user directory to FreeSWITCH and want to group some users in a logical structure. The following group '200' groups four users. It's interesting to notice the "dial-string" param, which is used to bridge the calls to those users. Users 1000 and 1001 will use the default "dial-string" while user 2014 uses a loopback channel so FreeSWITCH can actually query the dialplan to figure out how to reach that user (this also works for external numbers through OpenZAP and gateways):

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.

The dialplan for the above group can be defined like this:

The extension 200 will ring all the users defined in the user directory for group 200 in a serial fashion (specified by the +F argument, if you want to ring all the users at once use the +A argument) for 15 seconds, then it will transfer the call to the same group again so the call will ring the group infinitely.

To explain the variables set prior to the bridge:

The hangup_after_bridge is set to true for this effect: if the bridge is successfully answered and the B-leg later hangs up, the A-leg will also be hung up.

The continue_on_fail is set to true for this: if the bridge fails, dialplan execution will continue and the transfer will be executed.

The originate_continue_on_timeout is set to true for this: if the bridge's dial string specifies several destinations separated by the "|" (this is for failover), the bridge will time out on an unanswered destination and will attempt the next specified destination. Without originate_continue_on_timeout set to true, the bridge will time out on the first destination it tries and the bridge itself will fail. (In the example above, the bridge string is generated by group_call with the +F option; this specifies a dial string with all the group's destinations separated by "|". So originate_continue_on_timeout needs to be set to true for serial calling behavior.)

The call_timeout is set so that the bridge attempt to a destination that goes unanswered will time out. NOTE: If the destination sends early media, the bridge will be answered (pre-answered) and will NOT time out! To time out a bridge attempt to a destination sending early media, set ignore_early_media to true.

The dialplan for user 2014, which in this example happens to be terminated through a gateway defined via mod_lcr, can be defined like this:

Alphanumeric to numeric user mapping

Say you want a user's id to be alphanumeric (like an email username), such as These users have alphanumeric usernames in their sip phone config, but you want to map them from their sip username to a numeric extension, and vice versa.

As of version 1.0.4, FreeSWITCH makes this trivial to accomplish. A user's ID can be any alphanumeric string, and this can be simply tied to an extension number using the 'number-alias' property. This property creates an aliased directory entry that points to the alphanumeric user entry.

NOTE: When using this attribute, you must be careful not to create a directory collision by having another user whose ID is the same as another user's alias

Here is an example from the user directory:

So when a user dials extension number 1001, your dialplan can use the 'user_data' function to look up the ID attribute associated with that number alias. In the default dialplan, the 'Local Extension' section can be made to work with a small change to the 'bridge' line:

NOTE: Using this user_data function in combination with mod_xml_curl will generate an additional request each time the user_data function is called. Note that it is already called once in the Local Extension section to determine the callgroup. Beware of performance implications of this with high-volume systems.

NOTE: Be sure to edit your dialplan/default.xml file to also include the user id (johnsmith in our example) as well as the number-alias (1001). Keep in mine user IDs are case sensitive.

More Complex Examples

Each <user> can also have it's own variables and gateways with their own [semi-]complex configurations.

User-Specific Gateways

The <register-gateway> variable can be set to the name of a specific gateway, a comma delimited list of multiple gateways, or "all". Setting it to one or more gateways will register the named gateway(s) when the <user> registers with FreeSWITCH.(whether they're in the <user>'s <gateways> or some other <user>'s <gateways> or anywhere). Setting the variable to "all" will register all of the particular <user>'s gateways.

Group call with answer confirmation

The following example makes the user reachable at multiple phone numbers in SIP and PSTN networks. A call to a mobile phone may usually be answered with a message that a mobile user is unreachable, or end up in a voicemail. In order to avoid such situations, group_confirm_key is used to request the user to press "1" for call confirmation.

Loopback endpoint duplicates all channel variables, so if group_confirm_key is set globally, the confirmation key would be asked twice. So it needs to be applied with [] to limit to one leg only. The loopback endpoint is used to route the call to a PSTN number, assuming that users in the default context are allowed to dial international numbers and they are routed to an appropriate gateway.

Domains & Users Parameters

<params> and <variables> tags are valid inside <user>, <group> and <domain> tags.

Parameters and variables set on the domain will apply to all users in the domain, and parameters and variables set in a group will apply to all users in the group.

Priority will be given to identical parameters and variables in the following order: users, groups, domain.


Do Not Allow Empty Passwords

If you do not include the above 'password' parameter, anybody can register as the user without using a password. It is always wise to include this parameter in the directory section in case a user does not set their password.

Dial String

The dial string MUST be defined and will control the behavior of the call when a user is dialed. The dial-string parameter is used by the user/ endpoint.

Default value goes as follows:

Channel variables useful for the dial-string

  • transfer_fallback_extension
  • presence_id


Include Pickup Endpoints

Advanced dial-string

  • Sets presence and creates pickup endpoint




Any variables defined in the domain or user will be defined as channel variables when there is a call to user or when there is an inbound calls from that user.

Forcing a particular user to a particular extension

In a PABX environment, an authenticated user can specify that they are at an arbitrary extension. This behavior can be restricted in two ways.

To force a user to use a specified extension, add

to that user's directory entry.

Alternatively, to check that users authenticate with the same username as that in their contact field for an entire profile, add

to that profile's definition.

Additionally look at [1] - easy way of registration user with different SIP ID (Contact header) and username (Authorization header).

Force Registrations to Expire

To help prevent stale registrations you are able to override the client specified registration expiry. You do this in the clients directory profile, by simply adding the variable