It took me like an hour to compose this explanation.....I hope it at least gives you an idea.
"domain" is a core variable its used as a fallback in certain situations when its defined and no other value is specified for domain.
It's also used in the default configuration as a pre-processor substitution with the $${domain} notation which is substituted into the sofia profiles and conference etc.
"domain_name" is a variable that only exists in the scope of the demo dialplan. Its set initially as a global in vars.xml to whatever domain is set to as a base value.
From there its only set on a per-call basis to override and used in per call dialplan logic.
Its is not true that domain must be an IP. It defaults to the same value as local_ip_v4 to make sure the system works on any box without any configuration.
If you have a working FQHN that points to your box, you should set that value in your domain var instead of the ip if you want things to reference the actual domain name.
I think once you learn that way the config files are setup in the default distribution are purely arbitrary the more sense it may begin to make.
The thing that made your head hurt is trying to explain that in SIP there is a separation from the host portion of a URI and the IP its sending the packet to.
Because of PROXIES etc you can easily send a SIP packet to a specific address that contains a request URI or To: header with a different host name or ip.
think of domain as referring to the host portion of a user@host concept. The same notion of a REALM in radius. In SIP and in FS that can be an IP or a FQHN and it need not exist in the TLD dns on the internet or it can match one that exists and function on its own because it's not directly tied to dns. (For the sake of sanity do not use a real domain name that is not yours even if it works).
Basically the path of least resistance is to keep all these names aligned.. This is what the default config does for you because you set the domain variable once and its pre-processed into all the key places in the config that have domains so they are the same everywhere.
* The default directory will have a domain defined called
example.com with the default 1000-1019 extensions.
* The internal sip profile will associate the internal profile with
example.com and force any registrations etc to find that domain for auth.
* The conferences will use
example.com for presence etc.
Then it uses domain_name in the extensions etc as a clone of that
example.com domain that you can change at runtime on a per call basis. Most likely in the default config with no changes this value will remain
example.com the whole time and there is no difference.
Why?
Because people love multi-home stuff and they want to configure all of these things separately and once they start doing this, the config still is usable.
So:
FS never resolves domains to the IP and vice versa for you like it might in your unix environment or in a web browser. IP and FQHN have the same significance in sip packets as a unique realm string. It's only because you are binding the SIP UA to ${local_ip_v4} that your sip works on the IP.
The way SIP was designed to work, you would define a SRV record for the host name used in your sip uri and then that IP would be used in place of a default A record lookup. We can just as easily override that in a client by forcing the fields for the proxy address and domains.
Say you used
example.com like I mentioned above and your valid IP was 200.8.8.8
You could change domain=
example.com and restart FS and it would still come up.
Then you could go take a sip soft phone and play with the advanced settings and set the proxy addr to 200.8.8.8 and set the host or domain field to
example.com and configure it to always send calls to the proxy addr.
Now you can use
example.com in your phones all day long even though its not really your domain because its just saying that in the packets and you explicitly showed it what server to use.
Next, instead of
example.com you could use 1.2.3.4 (or some real ip) as the domain even though it's obviously silly.
If you turn on the siptrace you'll see the packets hit your box and using those values like 1.2.3.4 and
example.com in the host portion and talk to your client over the actual IP of the server.