Domains

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)


Host Domains

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,
e.g. for us, our domain is netwinsite.com so on our server we have set,
host_domain netwinsite.com

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,
host_domain mail1.domain.com    (bad - do not use as first host_domain)
host_domain smtp.domain.com    (bad - do not use as first host_domain)

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.,
bob@host_domain1
bob@host_domain2
bob@host_domain3
are all the same user, as host_domain1, host_domain2 and host_domain3 are all aliases of each other.

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

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.

( Repeating our message from the overview ...

The setup program DMSetup will only ask you about one domain, so forget about the virtual domains until you have your first main domain set up and tested, i.e. so that you can send and receive mail. Then set about adding the other domains, with the vdomain configuration file setting. )

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

  • Fred1 has the email address, fred@domain1.com
  • Fred2 has the email address, fred@domain2.com

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,

  1. IP Address based domains:

    Pop users on each domain login to a different IP Address.

    So, for example, fred@domain1.com might login to ip address 1.1.1.1 with username fred and fred@domain2.com might login to ip address 1.1.1.2 also with username fred.

     

  2. Suffix based domains:

    Pop users on each domain login with a different suffix to their username.

    For example, fred@domain1.com logs on to any IP Address with the username,
    fred
    and fred@domain2.com logs on to any IP Address with the username,
    fred@domain2.com

     

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
Unique Usernames Method for Semi Virtual Domains for details.

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.)

  1. Adding an IP based Virtual domain - Explanation 1
  2. Adding an IP based Virtual domain - Explanation 2
  3. Adding a Suffix based Virtual domain

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 161.33.44.55 mail.domain.one /var/spool/mail/B

vdomain C 222.33.44.22 mail.domain.two /var/spool/mail/domaintwo

The entries in these virtual domain lines are as follows:

vdomain <1> <2> <3> <4>

     
  1. Prefix string used to identify this domain (by default prepended to drop file name)
  2. IP number users reading from this domain will connect to
  3. domain name which translates to number in part 2 above 
  4. path for drop files for users of this domain.
These 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:

     
  • User fred from domain one is 'known' by the DMail servers as A_fred and user fred from domain B is known as B_fred. So their drop files will be a_fred and b_fred respectively (if drop_prefix is true, which is the default) and their user database names will also be a_fred and b_fred.

    The usernames and uid's use the form A_fred and B_fred in order to keep them separate.

    The user does not need to change their email client login username settings, as the translation from fred to A_fred is done by DPOP. The vdomain prefix can be a string rather than a single letter, e.g. 'domaina'. 

  • Connections to IP numbers not listed in vdomain settings, but listed in host_domain settings will use the normal drop_path form and will have normal usernames, dropfile and binfile names.
  • The drop file path for for each virtual domain is specified in the vdomain setting
  • If a bin path has been specified for bin files then this is used for all domains, BUT a prefix of A_ B_ etc. is used to distinguish files for users from different virtual domains (If drop_prefix is true, which is the default).
  • If bin files are stored in the same place as drop files then the drop paths from vdomain settings are used.

Adding an IP based Virtual domain - Explanation 2

Basically, in order to add a virtual domain domain2.com which has IP address 1.1.1.2, you should add a line like,

vdomain dom2 1.1.1.2 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 database.

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,
    fred/jds

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,
    fred@johns.server.com

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.
1. Close Netscape
2. Edit /program files/netscape/user/prefs.js (right click - open with notepad)
3. Add new line:
user_pref("mail.allow_at_sign_in_user_name", true);
4. Save file
5. Open 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

to,

vdomain johns /jds johns.server.com /var/spool/mail/johnsusers

vdomain johns @johns.server.com johns.server.com /var/spool/mail/johnsusers

NOTE: The above example defines ONE virtual domain, so the same PREFIX 'johns' is used for all three, the prefix must not be the same for different virtual domains, and must not include an underscore character

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.

Domain Prefix: drop_prefix setting

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 1.2.3.4
     
  • vdomain abc 1.2.3.4 abc.com /mail/abc_com
If drop_prefix is true, the drop file used will be /mail/abc_com/abc_fred

while if drop_prefix is false, the drop file used will be /mail/abc_com/fred

NOTE: The prefix 'abc' must not be the same for different virtual domains, and must not include an underscore character


Multiple IP numbers on a single machine:

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 - root
ifconfig eth0:2 999.59.4.31 up
to add a second ip number 999.59.4.31. The number :2 can be anything between :1 and :255


Common Domain Options

The following discuss some common situations, and provide DMail Domain setup options...

  1. One domain (-link to Domain Examples section)
  2. One domain with a few domain alises (-link to Domain Examples Section)
  3. Multiple Domains, Existing User Database of Unique Login Usernames
  1. Multiple Domains, Existing User Database of Unique Login Usernames:

    Please see the section on this later in this page,
    Unique Usernames Method for Semi Virtual Domains.


Domain Examples

  1. One domain
  2. One domain with a few domain alises
  3. Adding virtual domains to UNIX single domain system
  1. One Domain:

    Assuming your one domain is frog.com, you will need to set,
    host_domain frog.com
    in dmail.conf and remove all of the following settings in dmail.conf,
    vdomain
    dpop_host
    any other host_domain lines.

    NB: most people running DMail with one domain have at least their machine name as a domain alias. See the next Example, One domain with a few domain aliases.

  2. One Domain with a few domain aliases:

    Assuming your one domain is frog.com, you will need to set,
    host_domain frog.com
    in dmail.conf

    Most people then need to make DMail receive mail addressed to their machine name, e.g.
    mail1.frog.com
    in case someone accidently addresses mail to, for example,
    bob@mail1.frog.com
    instead of,
    bob@frog.com

    So you should add a host_domain line to dmail.conf for your machine name.

    Ensure that you add it AFTER your FIRST host_domain line. Using the above domain name examples you should end up with just the following two lines,

    host_domain frog.com
    host_domain mail1.frog.com

    (Remember to remove any vdomain or dpop_host settings in dmail.conf)

    Similarly, you might need to add aliases for,
    pop.frog.com
    smtp.frog.com
    etc.

    In order to do this, just keep adding host_domain lines onto the end of your list in dmail.conf, i.e.

    host_domain frog.com
    host_domain mail1.frog.com
    host_domain pop.frog.com
    host_domain smtp.frog.com

    These result in the user bob having ALL of the following addresses,
    bob@frog.com
    bob@mail1.frog.com
    bob@pop.frog.com
    bob@smtp.frog.com

    Normally, bob would only use the first one.

  3. Adding virtual domains to UNIX single domain system:

    Imagine the scenario below:

       
    • You currently have a DPOP server running on machine my.server.domain at ip address 100.2.3.1 
    • Your email clients connect using addresses such as fred@my.server.domain
    • Their drop files are stored in a directory /var/spool/mail
    • You provide no virtual domain support
    • You use simple UNIX user/passwords for authentication
    Then you are asked to take over (or add) email server support for a second group of users who used to get their email from johns server using addresses such as fred@johns.server.domain What do you need to do to provide a service for this second group...?
       
    • Arrange for the DNS to point johns.server.domain at a second IP number assigned to your DPOP machine. Let's say that this new IP number is 100.2.3.2 (Setting up multiple IP numbers on a single interface)
    • Setup a directory for the drop file to arrive in. Let's say /var/spool/mail/johnsusers, for example
    • Setup an SMTP server which will deliver mail sent to user@johns.server.domain to this directory. DSMTP could do this for you.
    • Choose a letter or short string to prefix users from johns group. Let's say J
    • Create usernames and passwords for Johns users. J_fred, J_JSmith etc.
    • Add the following line to your file:

      • vdomain J 100.2.3.2 johns.server.domain /var/spool/mail/johnsusers 

    • Restart DPOP

Domain Name Resolution (DNS)

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.

So to answer the question, "Do I need a DNS entry for the DMAIL 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
max_retrytime x
where x (in hours) is the length of time which it keeps retrying for.
The time between retries is fixed at 2 hours, but you can use the
tellsmtp tryall
command to initiate a retry for all queued messages if you have a backlog to clear.

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,
     big.com --> ip_address_of_dmail

(this would match your first host_domain setting in dmail.conf)

Such an entry would allow URLs starting,
     http://big.com/...
to reach the web server on your machine.

Commonly, people then add a 'C name' or alias DNS entry for www.domain.com, so continuing the example above, maybe...
     www.big.com --> big.com --> DMail_ip_address which would then make URLs starting, http://www.big.com/... reach your web server.


Upper Case Domains

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.

Unique Usernames Method for Semi Virtual Domains

  • Multiple Domains, Existing User Database of Unique Login Usernames:

    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,
    bob@domain1.com
    bob@domain2.com

    These two addresses deliver to two users, bob on domain1.com who has the login username,
    bob and bob on domain2.com who has the pop login username of,
    bob2
    (or some other unique username, e.g. xyz.fred)

    Answer:

    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:
    (notes and our recommendations follow this list)

    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 bob@domain2.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 bob@domain1.com, and bob2 changes to a login of bob@domain2.com

    2. make the two domains aliases of each other with two host_domain settings,
        host_domain domain1.com
        host_domain domain2.com
        authent_domain false
    and add an address alias that points,
        bob@domain2.com to bob2@domain1.com

       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 bob@domain2.com redirects to bob2(@domain1.com).

       3b. use forward settings in dmail.conf to redirect bob@domain2.cmo to bob2(@domain1.com).

    Notes:

    1. Options 2 and 3 mean that you cannot later add a user, bob2@domain1.com, as that address belongs to bob2 on domain2.com even if he does not use it.

      This is probably not an issue if your users currently use weird login usernames that are not likely to be wanted to be repeated e.g. xyz.fred. There is also the option to make your first host_domain a dummy domain that is not actually used in email addresses.

    2. Options 1b and 1c, can be made more bearable if the users will be using CWMail (or any other of the Web to email gateways) to read mail, because they can automatically add the suffix for the user on login to the web site.

    Our Recommendations (in order)

    1. If you have excess ip addresses ...

      definitely choose option 1a, because you can run our style of domains without having to change the login username.

    2. If you are willing to force users to change their login username ...

      choose option 1b, because only the users on domain2.com have to change their login username.

    3. If you are not willing to force users to change their login username ...

      choose option 2b, because it allows you to administer aliases in the user database, which also means that you will be able to alter them using the Web based user admin tool, NetAuth.

      Also remember that if you add further domains in the future, you should try to add suffix based virtual domains.



     

    •