Virtual Domains - a guide

Unlike web servers there are two basic types of virtual domains for a mail server:

Real IP based virtual domains, where you have allocated an IP address to each virtual domain, the server can use this information to figure out which domain it should 'pretend' to be.
Fake ones, where you only use a single IP address, then the user must login as 'user@domain.name' when fetching their Email via POP so that the server can figure out which domain they belong to.

SurgeMail supports both of these methods or even combinations of them and any number of virtual domains. However, it supports some other systems too :-). For example, you can tell SurgeMail to respond to all domains matching a specific wild card eg: *.mydomain.com You can also use a virtual user table where each user is in a 'domain of their own' (this is useful if you want to sell users their own domain names).

In addition, some mail clients do not allow a user to specify user@domain.name as their 'username'. In this case you can define a domain separator like '/' and then the user can login as 'user/domain.name'

How to create a virtual domain

Simply click on 'domains' 'add' in the web admin tool. Then fill out the details.

In addition if you are using WebMail you may need to add these domains to webmail.ini as described.

Note: SurgeMail will not create the directory structure until a message is received for the new domain, so don't panic if you can't see the domains directory right away.

You can define default settings for new domain by creating/editing the domain_defaults.txt file in the SurgeMail "web" directory (if you create/change this file manually copy it to the mirror too). This file contains only basic settings in the form:

<setting_name><space><setting_value>

one setting per line. It cannot handle the more complex settings eg.

setting label="value" label2="value2"

Adding IP numbers to your operating system

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. On NT just specify extra numbers in the networking control panel.

For UNIX, see http://www.nethelp.no/net/vif/readme.html for more information.

As an 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

Virtual Domain User (domuser.dat)

If every user on your system is in their own domain, e.g. bob@jones.mail.com, john@smith.mail.com then you probably don't want to create a virtual domain entry in surgemail.ini for all 200,000 users. Instead you can use the file domuser.dat to list each user so that SurgeMail knows what virtual domains exist on your system.

The format is:

delivery_user_domain user_database_lookup_name

e.g.

xxx@bob.com  xxx@bob.com
yyy@yyy.com yyy@bob.com
*@ccc.com ccc@bob.com

So with the above file, if a user 'fred@ccc.com' logged in they would be looked up in the userdatabase as 'ccc@bob.com' and yyy@yyy.com would be looked up as 'yyy@bob.com'

This file is very efficient and can support millions of virtual domains on a single server.

MX records DNS entries etc...

DNS stands for "Distributed Name Server", and it is the mechanism whereby your.domain.name is translated into your IP number (e.g. 13.2.44.2 etc). When you setup a mail server you will need to add a DNS entry. Normally this is done when you register a domain. Your domain registration service should also let you specify the IP number that your computer uses.

In addition, they may let you specify MX records. These are used as an over-ride, as a mail server for xxx.com may not run on the same computer that handles web pages for xxx.com. Also for redundancy you can specify 2 or more computers to receive Email for your domain, so if one system is down the other will accept the mail and hold it until your main system is up.

All the following examples really only apply to you if you run your own DNS server. Most likely someone else is running one for you (your ISP or domain registrar), so they will be adding these entries, but you still need to understand these entries so you know what to ask them to add to their DNS server.

For your mail server to work you must at least have a DNS or MX entry for your system e.g. typical entries look like this:

mail.freemail.com. in a 10.0.0.12

Alternatively, or as well, you can use MX records. Typically these are used to give a backup mail server address, e.g.

mail.freemail.com. mx 10 mail1.freemail.com.
mail.freemail.com. mx 20 mail2.freemail.com.
mail1.freemail.com. in a 10.0.0.12
mail2.freemai.com. in a 10.0.0.13
mail.freemail.com. cname mail1.freemail.com.

This says send all Email to mail1.freemail.com if possible. Failing that, send to mail2.freemail.com. Then the next two lines give the IP addresses of those two systems, and the last line is for dumb systems that don't know how to do MX lookups so they will find the primary system anyway.

Often you would setup the low priority MX entry to point to a system outside your local LAN, but if so, you must ensure they are configured to allow forwarding of Email to your system. Then while your system is down they will collect incoming Email for you.

Lastly you may want to configure wild card entries if you have lots of virtual domains all under a primary domain name, e.g.

*.freemail.com. mx 10 mail1.freemail.com
*.freemail.com. cname mail1.freemail.com

Beware - wild card entries are not as simple as they look. In particular, it cannot be guaranteed if the MX or IN entry will be used.

You should also specify a reverse DNS entry for your mail server. If you don't some other mail servers might treat you as a spammer and block or ignore all your Emails.

When mail.your.domain and your.domain are NOT the same system

The basic problem is you want user@your.domain to go to your mail server, but you want http://your.domain to go to your web server, and they are different systems.

This is achieved by the following magic incantations.

Add MX records to point your.domain to mail.your.domain
Add aliases for the domain in surgemail.ini so it will accept mail for mail.your.domain as well as your.domain, host_alias "mail.your.domain" (in each domain)
Add g_server_name url="*.domain.com" name="domain.com" so that web connections will figure out the right domain
In webmail.ini the imap server etc should be defined as 'mail.your.domain' not 'your.domain'

So in your DNS you have:

mail.your.domain --> x.x.x.x (your mail server)
your.domain --> y.y.y.y (your web server)
your.domain MX --> mail.your.domain

When you add a domain in SurgeMail it will ask you about your 'DNS' and 'MX' names, if you specify them as different, it will correctly setup your webmail.ini and surgemail.ini to cope, but you still need to setup the correcdt DNS/MX records in your DNS server.

Domain identification using WebMail with SurgeMail

Webmail combined with surgemail can host multiple domains on one server. There are several options for having webmail identify the correct domain.

Web browser URL based(most commonly used)

Domain dopdown list

Fully specified login

Using IP address

1. Using the web browser URL

The normal way of handling multiple domains is to login to webmail using your web browser on a URL of http://mydomain.com/scripts/webmail.exe. Webmail will then display a login page that has the domain correctly identified. For this to work this domain needs to be configured in several places in surgemail and webmail.

The vdomain in question must be defined in surgemail:

surgemail.ini:
  vdomain address="" name="mydomain.com"
  	mailbox_path "C:\surgemail\mbox\mydomain.com"
	{... other settings}

and in webmail:

surgemail/web_work/surgehost.ini:
  vhost mydomain.com
	  domain mydomain.com
	  suffix @mydomain.com
	  imaphost 127.0.0.1
	  smtphost 127.0.0.1
  vend

The definition of the domain in both places is generally done automatically by surgemail when you create this domain using the surgemail web admin interface or tellmail commands, but can be manually added if required.

When the browser connects to surgemail on the url http://mydomain.com/scripts/webmail.exe, it passes "Host: mydomain.com". SurgeMail matches this host value against g_server_name settings, domain names, url_host values and also compares the ip address of the domain to the ip being connected to. When it finds a match it passes a SERVER_NAME enviroment variable to WebMail with the appropriate value. WebMail matches this value against the vhost sections, identifying the domain.

If your url does not match your vdomain name eg you want your users to connect to http://webmail.mydomain.com/scripts/webmail.exe to send email of user@mydomain.com, surgemail will need to do this name translation. If the domain has a unique ip, and the url domain resolves to that ip then it should automatically work (surgemail 3.7a-21 onward). If you have only 1 such url domain name then you can set the domain url_host setting to this value (this has the side effect that SurgeMail will also use this value in any url it generates internally). If you have several values you can use a g_server_name rule, this rule may contain a wildcard. eg.

surgemail.ini:
  g_server_name url="*.mydomain.com" name="mydomain.com"

2. Domain dropdown list

An alternative to having webmail identify the domain using the web browser URL is to always display a dropdown list of all domains. This has the disadvantage that all users will see all domains that your server hosts. To display a dropdown in the webmail and user.cgi pages use the following settings:

surgemail.ini:
  g_user_domainlist "user"

webmail.ini:
  domain_select true

3. Fully specified login

An alternative to 1) and 2) above is to display an edit box allowing a fully specified login. To setup webmail this way remove the thext "@||domain||" from the login.tpl file for the template set that you are using.

Automatic Webmail login

If you wish to automatically login to webmail from another web page / application you have three options:.

Pass username and password (not generally a good idea)

Pop based autologin (surgemail only)

File based autologin

1. Pass username and password

You can just pass the username and password as fields to webmail login page. This means the password gets sent to the web browser before submission so the password is sent unencrypted across the (possibly unsecure) network. This could even get stored in web server referrer logs if you are unlucky.

2. Pop based autologin

Use POP based autologin (surgemail mailserver only) This is the default that surgemail uses when logging in to webmail and entails surgemail remembering the encoded password and serving this when webmail asks for it as an extended POP command.

This requires:

surgemail.ini:
  g_autologin_pop "true"
webmail.ini:
  use_id_autologin true

3. File based autologin

Using file based autologin allows arbitrary applications to login directly to webmail without sending the password in plaintext to the web browser.

The application that is doing the auto login to surgemail stores the password as an encoded file and sends a token to this file in the url it sends the web browser. Webmail reads this file, stores the password and removes this temporary autologin file. This means the password is not sent across the (possibly unsecure) network.

This requires:

webmail.ini:
  use_id_autologin false

and if surgemail autologin is also required:


surgemail.ini:
  g_autologin_pop "false"

1- The "central login" application saves the encoded password in a file (encoded as per following logic) in the webmail work folder:
In file 22413.tmp (where 22413 is arbitrary random integer) store the password passed through the auto_login_encode function.

    char *auto_login_encode(char *name,char *pass,char *enc,int bfsz) {
       // bfsz = size of enc buffer. (Typically 1000 bytes)
       char *n;
       int i;

       for (i = 0,n = name; i < bfsz-1 && pass[i]; i++) {
          enc[i] = pass[i] + *n++;
          if (!*n) n = name;
       }
       enc[i] = '\0';
       return enc;
    }

2 - The following url is then passed to the browser, where the critical fields are user, id and auto_login:
http://myserver.com/scripts/webmail.exe?cmd=auto_login&user=marijn&select_domain=mydomain.com&id=22413&frames=true
3 - Webmail uses the password from the 22413.tmp autologin temp file and removes the 22413.tmp file.


Search website:

Help Index

Virtual Domains - a guide

How to create a virtual domain

Adding IP numbers to your operating system

Virtual Domain User (domuser.dat)

MX records DNS entries etc...

When mail.your.domain and your.domain are NOT the same system

Domain identification using WebMail with SurgeMail

1. Using the web browser URL

2. Domain dropdown list

3. Fully specified login

Automatic Webmail login

1. Pass username and password

2. Pop based autologin

3. File based autologin