Advanced Installation
The following cover more complex setups of WebMail. The first section explains the main setups that are possible. There are other methods of setting up WebMail, and this only explains the main ones.
 
If you have any questions or need to know more about any aspect of WebMail, please Email:
 
support-webmail@netwinsite.com
Setup Options

If you are using SurgeMail, all the below has been taken care of for you. When you add a new domain to SurgeMail it will pass on the information to WebMail. Only if you set up WebMail outside SurgeMail do you need to consider the options below.

WebMail can be set up in many different ways. It all depends on how you want your users to login to WebMail. Here is a list of things that you need to consider:

  • How many domains do you wish to support?
  • How many mail servers do you have?
  • How many URL's to WebMail are you wanting?

If you have only 1 domain the base installation should be what you are after.

The following is presuming that you have multiple domains (2 or more) that you want your users to access via WebMail. The list that follows is not a complete list, but shows the most common options that are available. Throughout this section I am going to be using 2 domains, 'domain.com' and 'this.com'

The list below is not a complete list of setup options within WebMail. If none of the below suit your options please email support at support-webmail@netwinsite.com. Please provide the setup options or solution you require.

Multiple WebMail CGI's

This is the easiest to set up, as you just copy/rename the CGI and INI file and setup each CGI to control each domain. The CGI's do not need to be on the same machine, but if they are not, more WebMail licenses will need to by purchased.

For example the URLs would be:

domain.com: http://your.domain.com/cgi-bin/domain.cgi
this.com: http://your.domain.com/cgi-bin/this.cgi

Multiple URL's but 1 CGI

This is were you set up your Web Server so that you have different URL's, one for each domain, but all pointing to the same CGI.

ie.
domain.com: http://domain.com/cgi-bin/webmail.cgi
this.com: http://test.com/cgi-bin/webmail.cgi

What you do is setup the webmail.ini file to do a lookup on the 'domain.com' or 'test.com' part of the URL, and set up the necessary settings for that domain.

WebMail.ini

vhost domain.com
      domain domain.com
      imaphost domain.com
vhost test.com
      domain test.com
      imaphost test.com
vend

Single URL with 1 Mail Server

With this setup all your users of every domain all go to the same URL:

http://your.domain.com/cgi-bin/webmail.cgi

And your users are expected to login using the full user@domain layout.

lynden@domain.com
lynden@test.com

This does mean that your mail server MUST support the capability to pass in the user as user@domain and correctly determine the user emails. You should also setup the following WebMail ini settings:

WebMail.ini

valid_user *@*

Single URL with User Stated Mail Server

With this setup it is presumed that each domain has their separate mail server, or DNS/MX records are setup correctly. This can also be set up to access other mail servers that you do not control, like yahoo.com, as long as WebMail can get access to the POP or IMAP server. Keep in mind the distance between webmail and the mail server will greatly determine speed of access.

With this setup, all your users of every domain all go to the same URL:

http://your.domain.com/cgi-bin/webmail.cgi

But you set up on the login.tpl someway to tell the CGI which mail server they are using. This can be done in one of the following ways:

1.

Set up on the login page, a text field called:

<input type="text" name="host" value="">

Where the user enters the mail server they are using. This can confuse users with some sites, as they prefix their mail server with 'mail.', 'pop.' etc. So that the correct input would be:

mail.domain.com
pop.domain.com

To extend this a little, instead of having the user enter this information , you can set up a select list like this:

<select name="host">
<option name="mail.domain.com">domain.com</option>
<option name="test.com">test.com</option>
</select>

So that the user can select the domain they are using but WebMail receives the correct mail name.

2.

The second option is to set up WebMail so that the user MUST enter the mail server as part of their username:

lynden@domain.com
lynden@test.com

For this the admin adds one of the following webmail.ini settings:

@pop true
@imap true

The problem with this is that the domain part must match the valid mail server address, so if the mail server was mail.domain.com the user will need to enter: lynden@mail.domain.com

Another method below will fix this problem.

Single URL with Mail server specified by Domain Suffix

This is default setup of WebMail when set up with SurgeMail. This is very simular to the above two setups. The user is expected to login using the full user@domain layout.

lynden@domain.com
lynden@test.com

The next step is to set up WebMail to grab the domain part of the user name and use this to determine what WebMail settings to set up. For this to correctly work WebMail has 2 extra ini files available that you can set up to use. These are called:

vhost.ini

This is the main file that you should use to add your domain settings. This works in a very similar way to the webmail.ini, with a few differences.

surgehost.ini

This file should not be changed if it exists, as it is updated by SurgeMail. Any time you change any domain settings in SurgeMail, it will request WebMail to update this file with the necessary changes. This file overrides any settings from vhost.ini if there are matching settings.

Both files are stored in the webmail workarea (ie /var/spool/webmail).

In our example, you would create/add to the vhost.ini file the settings:

vhost domain.com
      domain domain.com
      imaphost domain.com
vhost test.com
      domain test.com
      imaphost test.com
vend

You should also setup the following WebMail ini settings:

WebMail.ini

valid_user *@*

Single URL with Mail server specified by Domain Suffix using Sub Domains

If you are using SurgeMail this is not a problem, since Surgemail will tell WebMail about it's domains and subdomains. This is more for a site that is using other mail servers in which they have setup sub domains.

Let's say you have 2 domains and each has 2 subdomains.

domain.com
sub1.domain.com
sub2.domain.com
test.com
sub1.test.com
sub2.test.com

Now you could set up each domain and subdomain with various settings just like the above option were you have a vhost field for each domain/subdomain. This isn't a major problem if you have very few domains, but if you have say 300+ domain/subdomains, having to maintain the files would be a lot of work.

This options allows you to set up agent lines within the vhost.ini file where you can set up all subdomains to use the same settings as the main domain.

vhost.ini

vagent_reverse true
vagent domain.com
      domain domain.com
      imaphost domain.com
vagent test.com
      domain test.com
      imaphost test.com
vend

Also if you wanted to create a subdomain called:

lynden.test.com

Where this is pointing to a completely different mail server, but you still wanted to use WebMail to access their accounts, all you need to do is set up the vhost.ini like this:

vagent_reverse true
vagent domain.com
      domain domain.com
      imaphost domain.com
vagent test.com
      domain test.com
      imaphost test.com
vagent lynden.test.com
      domain lynden.test.com
      imaphost lynden.test.com
vend

Doing this, you can set up the default for most cases, and you would only need to set up different vagent lines for the domains that are different :-)

Setup Large Sites

When setting up WebMail for a large system including multiple computers, there are a few things that need to be checked.

    1. The max number of POP/IMAP connections allowed (ie 400+)
       
    2. Verify that the times of all computer including any filesystems (ie NFS, Samba) are within 1sec of each other.
      If you are using nfs ensure that you have the ini setting 'nfs_server true' setup in your ini file.
       
    3. INode limit on harddrives. The number of files can be limited by the number of INodes the harddrive has been formatted to. In Redhat the default worst case is that you fill up only half of your disk space before you run out of inodes.

      It is suggested that you setup the '/var/' location like this:
      umount /var
      mke2fs /dev/sda3 -b 1024 -i 1024
      mount /var
      Warning: Doing this you will looses all data on '/var/'

When you are setting up WebMail on mutiple machines the workarea of each computer MUST point to the same location. This is to ensure that no matter what computer the user is going to, the CGI will still have access to the users' information.

The WebMail templates and images do not have to be set up on a network drive and we suggest that, since these are accessed often, to have these local to each machine. This will save network load.

There are also a few ini setting that you should also set up whch will help with large systems.

max_download 200
max_imap_download 200
mylock_timeout 60
mylock_wait 30

The first two settings are to reduce the amount of email 1 CGI cycle will download. If the user accesses a folder that hasn't been downloaded before and there are 1000 emails, the CGI will ONLY download the lastest 200 emails. Next time the folder is accessed the next 200 emails will be will downloaded and so forth. This helps ensure that the user gets a faster response back.

The next 2 ini settings are to do with WebMail locking, which is very important on large systems. More noticeable with nfs serves, but if two CGI processor were run at the same time without locking, both could be reading and changing the same file, which can cause data to become lost or damaged. The locking ensures that each user has only 1 CGI at a time processing data. The 'mylock_wait' is the time in seconds that the CGI will attempt to get the lock before giving up and displaying a 'Server Busy' error to the user. The 'mylock_timeout' is the time that any lock will expire automatically.

NOTE: The locking ini settings have no effect on Windows systems.

NFS Server Setup

When using WebMail on an NFS server, you should be using v3.1a or greater and will need to add the following to your ini file:

nfs_server true

This will ensure that only one CGI at any time will have access to the user information..

You should also see server farming (running WebMail on more than 1 machine).

Another webmail.ini setting that you might need to setup for nfs servers is:

lock_force_wait 1

On some nfs server setups the above setting is required to ensure that the creating and deleting files within 1 CGI call don't happen too fast for the nsf caching. If you have no nfs caching then this setting is not needed.
 
WARNING: This setting can affect performance, it is much better to disable nfs cache for webmail directories.