Summary on domains and profiles in FreeSWITCH

A brief and very useful summary of FreeSWITCH’s author in the mailing list:

[Freeswitch-users] Domains and profiles
Anthony Minessale
Mon Nov 12 22:16:50 MSK 2012

The best thing to do is take a look at these things from a step back.

The domains inside the xml registry are completely different from the
domains on the internet and again completely different from domains in sip
packets.  The profiles are again entirely different from any of the above.
 Its up to you to align them if you so choose.

The default configuration distributed with FreeSWITCH sets up the scenario
most likely to load on any machine and work out of the box.  That is the
primary goal of that configuration, so, It sets the domain in both the
directory, the global default domain variable and the name of the internal
profile to be identical to the ip on the box that can reach the internet.
 Then it sets the sip to force everything to that value.  When you want to
detach from this behavior, you are probably on a venture to do some kind of
multi-home setup.

Aliases in the <aliases> tag are a list of keys you want to use to use that
lead to the current profile your are configuring.  Think of it as the
/etc/hosts file in unix only for profiles.   When you define aliases to
match all of the possible domains hosted on a particular profile, then when
you try to take a user at notation and decide which profile it came
from, you can use the aliases to find it providing you have added <alias
name=""/> to that profile.

The <domains> tag is an indicator telling the profile to open the xml
registry in FreeSWITCH and run through any domains defined therein.
The 2 key attributes are:

alias: [true/false]  (automatically create an alias for this domain as
mentioned above)
parse: [true/false] (scan the domain for gateway entries and include them
into this profile)
name: [<string>] (either the name of a specific domain or 'all' to denote
parsing every domain in the directory)

As you showed in your question the default config has

<domain name="all" alias="true" parse="false"/>

If you apply what you have learned above, it will scan for every domain
(there is only one by default) and add an alias for it and not parse it for
gateways.  The default directory uses global config vars to set the domain
to match the local ip on the box.  So now you will have a domain in your
config that is your ip, and the internal profile will attach to it and add
an alias so that value expands to match it.

This is explained in a comment at the top of directory/default.xml

    FreeSWITCH works off the concept of users and domains just like email.

    You have users that are in domains for example 1000 at

    When freeswitch gets a register packet it looks for the user in the

    based on the from or to domain in the packet depending on how your
sofia profile

    is configured.  Out of the box the default domain will be the IP
address of the

    machine running FreeSWITCH.  This IP can be found by typing "sofia
status" at the

    CLI.  You will register your phones to the IP and not the hostname by

    If you wish to register using the domain please open vars.xml in the
root conf

    directory and set the default domain to the hostname you desire.  Then
you would

    use the domain name in the client instead of the IP address to register

    with FreeSWITCH.

So having more than one profile with the default of

<domain name="all" alias="true" parse="false"/>

is going to end up aliasing the same domains into all profiles who call it
and cause an overwrite in the lookup table and probably an error in your
logs somewhere.  If you had parse="true" on all of them, they would all try
and register to the gateways in all of your domains.

If you look at the stock config, external.xml is a good example of
a secondary profile, it has

<domain name="all" alias="false" parse="true"/>

so no aliases, and yes parse ... the exact opposite of the internal so that
all the gateways would register from external and internal would bind to
the local ip.

So, you probably want to use separate <domain name=""/> per domain
per profile you want to bind it to in more complicated setups.

On Sun, Nov 11, 2012 at 9:09 PM, Emrah <lists at> wrote:

> Bless you!
> Thanks for putting this together. You've beautifully summed up all my
> questions.
> On Nov 11, 2012, at 8:09 AM, Lawrence Conroy <lconroy at>
> wrote:
> > Hi Folks,
> > I've started a new thread as it's not quite the same issue, and domains
> & profiles have confused the heck out of me every time I have developed a
> new setup for fS.
> > I have sometimes had to hack/hard-doce the dialstring to make multiple
> domains in one profile work, had hours of fun with presence, db and force
> register settings, and have still had some odd gotchas that have required
> extensive meditation.
> > [... and yes, I have read the 1.0.6 bridge book; I'm trying to abstract
> these elements ]
> >
> > Coming at this from standards/specs and rolling my own SIP stacks,
> sofia/fS seems to use the term "domain" differently from sipdomain, and
> alias seems to be tied to the directory (and thus to the profile listed in
> a directory file), but I'm not sure.
> > so ...
> > Before I capture to the sofia conf xml wiki page, I have a couple of
> questions on the sip-profile XML setup;
> >
> > Q: Is there a particular reason why there's a parameter called alias and
> an (entirely different) setting also called alias?
> > The sofia conf xml wiki's comment on the setting "alias" shows I'm not
> alone.
> > I agree that's what it appears to be doing, but can we nail this down
> please (and what happens if an external client uses this connection to
> register and call)?
> >
> > In the current sofia conf xml wiki page, the domain setting is not
> exactly well documented :).
> > The current internal.xml vanilla example from git (as of time of
> writing) has the following lines:
> > -------------------------
> > ...
> > <!-- -->
> > <!--aliases are other names that will work as a valid profile name for
> this profile-->
> > <aliases>
> >   <!--
> >        <alias name="default"/>
> >    -->
> > </aliases>
> > <!-- Outbound Registrations -->
> > <gateways>
> >   <X-PRE-PROCESS cmd="include" data="internal/*.xml"/>
> > </gateways>
> >
> > <domains>
> >   <!-- indicator to parse the directory for domains with parse="true" to
> get gateways-->
> >   <!--<domain name="$${domain}" parse="true"/>-->
> >   <!-- indicator to parse the directory for domains with parse="true" to
> get gateways and alias every domain to this profile -->
> >   <!--<domain name="all" alias="true" parse="true"/>-->
> >   <domain name="all" alias="true" parse="false"/>
> > </domains>
> > ...
> > -------------------------
> >
> > This stuff is entirely missing from the sofia.conf.xml wiki page, and it
> IS really important.
> >
> >
> > Q: what's the default value for the alias parameter in the domain
> element? -- it is missing from the first example.
> > Q: if there is more than one profile, what's the impact of setting parse
> = true in one (or all) of the profiles' XML files?
> >   (or parse = false, or missing the parameter altogether)?
> > AFAICT, the gateways get pulled in via the pre-process directive just
> fine, regardless of the value of the parse parameter -- it works for me, at
> least.
> >
> > Q: if there is more than one profile, what's the impact of putting
> domain name="all" into one (or all) of the profiles' XML files?
> >
> > Ideally, having more than one sipdomain tied to one profile "would be
> good", but aliases doesn't do that -- as the git file says, these are
> aliases for the profile name.
> >
> > Before I start scribbling, Answers on a postcard to this ML, please.
> >
> > all the best,
> >  Lawrence

, ,

  1. Leave a comment

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: