The whole of the DMail server is based around the email address domain.
All you have to do is tell the DMail servers which email domain or domains you want it to recognize as being 'local'.
You do this by using two settings - host_domain and vdomain in The configuration file - dmail.conf.
If you want to support just one domain, use a host_domain setting.
If you want to support multiple domains, use a host_domain setting plus a number of vdomain settings.
If you are planning to add many domains, we suggest that you pick one of these domains to be your 'main' domain.
Use DMSetup to add only this domain and get it working so that you can send and receive email. Only then should you set about adding the other domains.
The other domains that you add are refered to in this manual as 'virtual domains', although there is very little difference between them and your main domain.
NB: if you don't tell DMail about a domain with a host_domain or vdomain setting then the SMTP server DSMTP will think that that domain is not 'local', and try to send on or 'relay' that mail to an outside world server.
On this page...
Related links (not on this page)
The first (top) host_domain setting found in the dmail.conf file specifies the 'main domain' of the server.
This is the most important setting in your dmail.conf configuration file.
This domain should be what the outside work knows your domain as,
Your first host_domain therefore must be resolvable to an IP address if you are using DSMTP on the internet rather than on an intranet. It is often the A Name in your DNS record.
NB: your first host_domain setting should almost never be your machine name, e.g.
do not make your first host_domain setting any of the following,
You can set multiple host_domain settings.
The second, third, fourth ... settings are all 'domain
aliases' of your main domain. So you can enter your machine name as one of the lower host_domain
settings. Because the domains are aliases, a particular username points to the same
user on all of the domains,e.g.,
NB: if you add a host_domain setting then in most cases you should ensure that you have also added a DNS entry for that domain to the Internet DNS server system, i.e. your own DNS server or your ISP's DNS server. See the Domain Name Resolution (DNS) section towards the end of this page for details.
For further details on the host_domain setting, see the reference section.
If you require the same username to be used for different users on each domain, you will need to setup what we call 'virtual domains'. Please read on ...
Virtual domains allow you to provide email server support for several distinct groups of users who collect their email from supposedly different mail servers.
Such users typically have different domain information in their email address, e.g one group have addresses on the domain, domain1.com and another group have addresses on domain2.com.
DSMTP accomodates these groups by dividing them based on their domain.
The first domain that you set up should be thought of as your 'main domain'.
So you pick one of your domains that is going to be the default, and call that the main domain. Referring to the section above, you add a host_domain setting for it. Then all of the other domains that you add will be virtual domains.
Note: there isn't really any difference between a main domain and a virtual domain, except for how you tell DMail about them.
The biggest difficulty for virtual domains is the POP server login usernames. For example, there may be two distinct users, both with username fred. Let us call them fred1 and fred2
The DPOP server has to have a method to tell these two users apart when they login, as presumably they both want the login username of simply 'fred'.
DMail provides two ways to do this,
A third method also exists, where every login username is unique and you use aliases or a
lookup table to create mail addresses. This method is common in products like Sendmail, but
it is not recommended by us. See the section
So how do you add a virtual domain . . .?
You need to manually add (or use the windows GUI DMAdmin) the virtual domains to the configuration file, dmail.conf - see The Configuration File for how to locate and edit this file. The following links to this page take you through the options. (It can be tricky to get your head around, so we have provided two explanations of IP based virtual domains.)
Adding an IP based Virtual domain - Explanation 1
Both domain1.com and domain2.com point to a single machine with multiple IP numbers running one copy of DPOP. In order to handle these two 'virtual-domains' and not mix up fred1 and fred2, even though they have the same username, DPOP must keep them separate. When a connection is made to DPOP, it checks the IP number that the connection was made to. This is then matched against entries in the dmail.conf file of the form;
vdomain Btwo 22.214.171.124 mail.domain.one /var/spool/mail/BThese are used to enable the username passed to the authentication process to contain enough information to allow the two users to be distinguished and assigned different drop file paths and passwords.
From the above, it might appear that virtual domains can only be supported when an external authentication process is used, as two different passwords for user fred are required. This is not the case, as virtual domains can also be supported using normal UNIX user/passwords or Windows passwords by using the following scheme:
Adding an IP based Virtual domain - Explanation 2
Basically, in order to add a virtual domain domain2.com which has IP address 126.96.36.199, you should add a line like,
vdomain dom2 188.8.131.52 domain2.com c:\dmail\in\domain2
In the line above I have chosen a vdomain 'prefix' of dom2. This prefix is used by DMail to refer to users of this domain, so the user bob from the domain, domain2 is referred to by DMail as dom2_bob - never to his face, only when it is talking to the authentication programs (a system one or an external one).
The last entry on the line is the path for mail drop files to go for that domain - so that you can keep the mail for each domain separate.
You should notice that all of the entries in the vdomain line, except for the vdomain prefix, are already in your dmail.conf file for your main domain - e.g. the main domain has a setting called drop_path. Note: the main domain does not have a prefix, as usernames without a prefix in your password list are assumed to be for the main domain.
So, to add a user bob to your main domain, you simply add the user
'bob' to your authentication database, and to add a user bob to the
domain domain2 above you add a user 'dom2_bob' to your authentication
Adding a Suffix based Virtual domain
As an alternative to having multiple IP numbers, virtual domains can be
set up by asking users of the virtual domain to connect to the POP server with
a suffix on the end of their username. E.g. using POP login usernames
of the form,
To make a virtual domain a 'suffix based vdomain', you add a vdomain line to dmail.conf as with an IP based vdomain, but replace the IP Address with the unique suffix for that domain.
For example, we might have:
vdomain johns /jds johns.server.com /var/spool/mail/johnsusers
where '/jds' is the suffix.
If DPOP finds this suffix on any user POP login name, it will remove the suffix and treat the user as belonging to the vdomain of the vdomain line that it matches.
DPOP will do this no matter what IP address the user connects to.
See IP Address based virtual domains for explanations of the other values of the vdomain setting beside the suffix.
Note: the suffix includes any separator character, in the example above it was '/'.
Making suffixes more convenient:
Obviously, this form of virtual domains can be an inconvenience to users if they have to change their client software settings to connect as 'username_suffix' instead of just 'username'. It can also be a little confusing to customers.
1. One common way to get around this is to make the suffix, '@domain' so that the user can use their email address as their POP login, e.g. if we changed the vdomain line above to,
vdomain johns @johns.server.com johns.server.com /var/spool/mail/johnsusers
Then the suffix is now, '@johns.server.com', so the user fred would login to the POP server with,
NB: The only problem with this is that some email clients won't let you enter a username with an @ in it. The notable example is Netscape Mail, although the word is that they have realised their mistake and will change that in an upcoming version.
We have just been given instructions on how to allow the @ character to be used in netscape.
So, if you are going to do this, and have users connecting directly to the POP server with any client, then we suggest you create a second vdomain line for the same domain. The second vdomain line must come after the main vdomain line in dmail.conf. It differs from the first only in that it specifies a different suffix.
So using our example above, you can change,
vdomain johns /jds johns.server.com /var/spool/mail/johnsusers
vdomain johns /jds johns.server.com /var/spool/mail/johnsusers
2. Another common way to make suffixes more 'transparent' is to hide them all together. If you are using any of our Web to EMail gateway products like CWMail or WebMail, they have an ini setting called 'suffix'. You can use that setting to make them automatically add the suffix to the username given by the user on login. So if the user always collects their mail with the web interface, they don't ever need to know about the suffix.
We recommend the use of suffix based vdomains when using the web interfaces.
Remember that whether a vdomain is IP address based or suffix based, the form of the username in the
database is independent. So you can easily change a domain from one to another at a later date. For some changes
you would need to alter your DNS entries as well.
This config setting determines how the drop file name is constructed when virtual domains are being used. Drop_prefix can be set to true or false. The default is true. When this setting is true, the drop file name will include the virtual domain prefix. For example, consider the case when the following vdomain line is being used and a user fred is connecting to abc.com which maps to ip number 184.108.40.206
It is fairly easy to add multiple IP numbers for a single machine - up to 255 per interface is fairly straightforward. 1024 is usually possible with minor patches. The exact method varies from one form of UNIX to another - see http://www.nethelp.no/net/vif/readme.html for more information.
For example, on Linux you would do the following:
su - rootto add a second ip number 9220.127.116.11. The number :2 can be anything between :1 and :255
The following discuss some common situations, and provide DMail Domain setup options...
One of DSMTP's main functions as an SMTP server is to send mail which is addressed to non-local users, i.e. outgoing mail from local users and messages being 'relayed' through DSMTP.
Before DSMTP can send mail out, it has to resolve the domain name in the destination email address to the IP address of the destination email server.
In normal operation it does this 'resolving' by sending a lookup request for the domain to a DNS server.
Yes, you need to set up either an Mail eXchange (MX) DNS entry for your domain, OR an 'A' or 'C name' DNS entry.
Your service provider should be able to help you with this if you do not run your own DNS server. Feel free to ask DMail Support, if you want to clarify anything on this before talking to your service provider.
The use of the DNS server can be by-passed by setting a gateway setting for the domain in dmail.conf.
By default, DSMTP will use the DNS lookup procedures setup in your operating system for your machine - so basically if you can ping a domain then DSMTP should be able to resolve that IP address too. Your operating system probably uses a list of DNS servers for domain to IP address resolution, as well as the 'hosts' file for resolution of some local domains, e.g. /etc/hosts on UNIX systems and \winnt\system32\drivers\etc\hosts on Windows NT.
If you want to specify a particular list of DNS servers for DSMTP to use then you can enter multiple, dns_host settings in dmail.conf. These will be used by DSMTP instead of any system DNS lists or hosts file.
DSMTP caches the last 1000 DNS lookups that it has done and clears this cache every 2 hours or when the server is restarted.
DNS Caching to Disk - Unique New Feature in version 2.8i
Many DNS servers on the internet have a bug where they incorrectly report a domain as unresolvable when a short time before they could resolve that domain. So we have added a unique feature to DSMTP. By default, it now caches to disk successfull DNS lookups, and checks that cache if a DNS server reports a domain as unresolvable.
This does mean that if someone removes a domain DSMTP will continue to try to deliver to that domain's old IP Address. However, this is not a common situation whereas the very real problems caused by false 'invalid domain' responses can cause a huge administration problem.
The DNS caching feature can be disabled with the setting, dns_disk_disable true.
In what order does DSMTP do lookups? (MX Priorities)
DSMTP will first do an MX lookup and use any IP addresses that it finds in the priority order in which they are given. If none of those are successful then the message is queued for a later retry.
If the MX lookup fails, DSMTP will do a DNS (A) lookup for a straight IP address and use it if it finds one. If it does not find one then it will bounce the message.
So, if there is a record in either lookup then DSMTP will not
bounce the message, even if no SMTP server responds at the IP address
that it has found. Instead it will queue
the message and retry to send it later. There is a limit to the
number of retries that it does, after which it will bounce the
message. This limit is set by
Do I have to register a URL for the DMail server?
If you are asking this question then we presume that you are planning to run one of our Web to email gateway products, e.g. CWMail which is a CGI, in order to provide web access to email on the DMail server.
These require that you set them up on a web server.
Yes, you do need to register a DNS entry for your domain, e.g. supposing you wanted DMail to
handle mail addresses with the domain, big.com you might have an A or main record for,
(this would match your first host_domain setting in dmail.conf)
Such an entry would allow URLs starting,
Commonly, people then add a 'C name' or alias DNS entry for www.domain.com, so continuing the
example above, maybe...
Talk to us if you want them - but basically DSMTP will always look for the lower case form of the domain in settings in dmail.conf.
So if a message comes in for bob@Domain99.com, DSMTP will look
for a host_domain or vdomain setting for the domain, domain99.com - NOT
Domain99.com. Similarly, all forward rules etc should specify the domain
in a lower case form.
When moving to DMail, you might already have a database of unique
usernames for users across multiple domains. E.g. you may have the the addresses,
These two addresses deliver to two users, bob on domain1.com who has the login username,
Basically, such a system does not tie a username to a domain.
DMail's virtual domains do tie a username to a specific domain.
In order to take advantage of a number of features, you will have to change your domains to DMail's style of virtual domains.
We recommend that you take this opportunity to change, as there will probably be future features which you will want to take advantage of, which require that you have DMail style virtual domains. Ways in which you can change are detailed in option 1 below.
However, it is possible to setup DMail to continue functioning with your user database in the format that it is currently in. Options 2 and 3 below cover this.
You may also want to setup DMail to continue functioning with your old user database for your existing domains, but then add DMail style virtual domains for any domains that you add in the future, or even move your existing domains over one at a time at a later date.
Here then are all of the options for dealing with this situation:
1. make the two domains separate virtual domains ...
1a. by moving each of the domains onto separate IP addresses.
1b. by making bob on the second domain log in using a suffix , e.g. his login username changes from bob2 to email@example.com (i.e. domain2.com becomes a vdomain)
1c. by making both bobs login using a suffix, e.g. bob changes to a username of firstname.lastname@example.org, and bob2 changes to a login of email@example.com
2. make the two domains aliases of each other with two host_domain settings,
2a. create alias for bob2 in alias_file_domain setting
2b. create alias for bob2 in fwd="" field of user lookup response.
3. create aliases without having to add host_domain settings for second (or further domains)
3a. use virt_user_pre setting to create a Sendmail style 'virtusertable', where firstname.lastname@example.org redirects to bob2(@domain1.com).
3b. use forward settings in dmail.conf to redirect email@example.com to bob2(@domain1.com).
Our Recommendations (in order)