XMail Web Administration Interface

version 2.1.0
Altair Software Production

Index

What is XMail WAI

XMail Web Administration Interface (alias WAI) is web-based management system for XMail mail server. XMail is free and open source SMTP/POP3 mail server for Win32 and Unix platforms.

WAI offers simple, comfortable and secure way for ISPs, if they need e-mail system for their customers. WAI uses hierarchical architecture, which allows to system administrator (ISP) to delegate some rights to smaller, domain administrators (customers).

My idea is, so an ISP will create new domain (ie. company.com). Postmaster of that domain (postmaster@company.com) has the right to create, modify and delete users and aliases under its domain. So system administrator is not overloaded by requests from customers (teoretically).

WAI also contains webmail interface, so users can read and write their mail using web browser.

It is also possible for WAI to cooperate with XMail Simple List Manager (SLIM) to allow list management trough web interface.

If you need help when installing or configuring WAI, please see the Support page.

Requirements

Xmail WAI is standard web application using the Active Server Pages technology. To run it, you will need:

Where to get the components

By users, the WAI is accessed trough WWW interface. As client you may use any frame and cookies enabled browser. JavaScript function is recommended, but not required. The interface has been developed and tested for Microsoft Internet Explorer 5.0 or later, but in older version or other brousers it should be functional too.

Installing and configuring

If you're upgrading, please read Upgrade notes file.

Warning: Installation seems to be complicated, but if you will follow the instruction and know little bit about your server, it would be okay. I will try to write some kind of setup script in the future.

  1. Unzip the distribution archive (if you're reading this document, you have probably it done).
  2. Download and install all the components stated above.
  3. Copy the folder config to hard drive of desired server, outside the WWW root (ie. to C:\xmwconfig)
  4. Copy the folder xmadmin to hard drive of desired server.
  5. Map that folder as virtual directory /xmadmin of some virtual web server.
  6. Using the Internet Service Manager create new separate application for this folder (the /xmadmin/global.asa file must be functional).
  7. In the /xmadmin/global.asa change value of Application("App.ConfigPath") to folder created in step 3.
  8. Set IIS permission to folder /xmadmin/attachments to read (disable script and binary execution).
  9. Set NTFS permission to folder /xmadmin/attachments to "Full control" for web anonymous user (typicaly IUSR_YOURSERVERNAME).
  10. Change configuration files in the directory specified in step 3 to reflect your situation (see the section below).
  11. Set NTFS permission to allow XMail's ctrlclnt.exe to be run by your web server user.
  12. In XMail's SMTPRELAY.TAB file enable relay for the web server's IP address.
  13. Using Task Scheduler or simillar method set the script frozcache.vbs in config folder to be executed regularly using CSCRIPT.EXE. Interval of execution should be something between five minutes and one day - I recommend to be about two hours. For explanation, see the "Backgrounds" section.

Configuration files

XMail WAI is using two kind of configuration files. First is config.xml, which contains information about configurations. Second are files *.msg containing templates for welcome e-mails.

File config.xml

This file is in XML format and contains information about connection to XMail etc.

Element <xmail>

Contains information about the XMail server we are connecting to. Has the following attributes:

Element <web>

Contains information about the web interface itself. Has the following attributes:

NOTE: The charset attribute is obsolete and not used anymore.

Element <language>

Child element of <web>. Contains informations about registered language files. Has the following attributes:

Element <smtp>

Contains information about the outgoing messages. Has the following attributes:

Element <templates>

Info about message templates. There is no need to edit this section.

Element <external>

Optional, info about external programs installed (such as list managers etc). Can contain <program> elements.

Element <program>

Optional, info about some external program installed. Has the following attributes:

Files *.msg

These files are containing messages sent when creating new domain, account or resending mailbox access information. Modify these files and enter your server names, contacts etc.

First line of file contains subject of the message, subsequent lines are message body. Tokens {USER}, {DOMAIN} and {PASSWORD} would be replaced by the user name, domain name and password of the requested user.

Restarting application

When application is not running in debug mode, you must restart it every time configuration changes. Restarting application would log off all currently logged users.

Application restarting may be performed either by restarting web server or by making some change in global.asa file. Ie. you may open this file in Notepad, add and then back delete single characted and save the file. Application would restart in next request.

Using WAI

Before you can use WAI, you must log in. Navigate your server to http://yourserver/xmadmin/. Then choose requested login type, enter your login and password.

System administrator

Your login name and password is the one, which you set in the config.xml file. After login, you may manage domains handled by your server and also modify users in them in any way.

Beside this, you may manage frozen messages (list, view, resubmit, delete) and mailing list if SLIM support is installed and enabled. You may also define enabled mailproc directives for your users.

You may also set mail blocking options (ie. blocked e-mail address or networks).

Domain administrator

Your login name is postmaster@yourdomain. Your password is your POP3 password. You may manage users in your domain only. Webmail access to your mailbox is available. You may manage mailing lists in your domain.

Regular user

Your login name is your primary e-mail address (not alias). Your passwoord is your POP3 password. You may view your addressing info and change your password. Webmail access to your mailbox is available.

Backgrounds

This section contains some intimate informations about WAI's privacy and interior. You necessarily don't need to know them, but if you want to be informed about how the system works (and why is something acting in seemingly strange ways), you should.

About attachments

Attachment handling is a little bit complicated. All message attachments are temporarilly stored in the /attachments virtual directory. The files are created when user clicks to "download attachment" link and deleted by any other actions.

This arrangement is not optimal, I'll try to make something better in future time. This implementation has problems when the filename is containing some special characters (such as Czech diactiric) and you shouldn't use the WAI while downloading the file.

In some strange cases (unexpected end of script execution etc.) some temporary files are leaved in the /attachments folder. All such files are deleted on application restart.

About frozcache

XMail's implementation of handling frozen messages is pretty slow. Getting list of frozen messages from server may take dozens of seconds. And that is very, very long time for web application and makes on-line handling of frozen messages amost impossible.

So, I established institution I call FrozCache. There is Windows Script Host script called frozcache.vbs in the config folder. This script is designed to be run regularly using task scheduler. Its purpose is to create XML file (called frozcache.xml), containing all unhandled frozen messages.

That script execution can take as time as needed -- it's asynchronous operation, do not loading the web application. The application works only with the cache file, and this operation is very quick.

The darker side of this solution is, so informations about frozen messages are not always up-to-date. It's important to set the execution time of FrozCache script to be proportional to your needs.

If you have small server and are doing maintenance twice a week, you can execute the script once a day. If you have a high-load server and are checking for frozen messages twice a day, you'll probably consider to have this script executed hourly or maybe even frequently.

About mailprocs

Until version 1.9.0, WAI allows the user MAILPROC.TAB to be edited in some way. Allowing users to directly edit these files may be dangerous -- they may setup some malicious file or script to be executed etc.

So, the process has two levels. At first, the system administrator must establish some templates to be executed. Templates are combination of commands and parameters, some of which can be entered by end users. They can only choose which one from the predefined commands want to be used.

By default, all XMail commands, except of invoking external file, are specified and thus enabled. You may define additional commands (if they would be added to XMail) or specify some trusted scripts to be executed.

But there is a little problem: WAI needs more information about MAILPROC directives, than XMail stored by default. So it uses pack of XML files, stored in the config\mailproc folder. Currently I don't have energy to describe internal format of these files, so please treat them as undocumented black box. The only thing you really need to know about them is not to modify them in any way -- the WAI will do everything you need.

Warning: WAI expects to be the only application working with user MAILPROC files. So if you would modify these files by hand, all changes may be lost, because WAI would restore the files to last known state.

About SLIM integration

WAI also allows integration with my other program for XMail, the Simple List Manager (SLIM). You may get SLIM at no cost at my website: http://www.altair2000.net/software/xmail-slim/.

If you want to enable WAI-SLIM cooperation, you must enable it in the config.xml file by adding the program element to external section. The path attribute must point to SLIM folder, withound the ending slash. Example part of config file may be:

	<external>
		<program name='slim' enabled='yes' path='C:\SYS\Scripts\Xmail\SLIM'/>
	</external>

Known bugs and limitations

Problems has been reported when using XMail WAI on Chinese version of Windows. Sorry, I cannot solve them. As MSDN Universal subscriber I have Chinese Windows, but I am unable to install and use them.

The following functions are intended to be in the next versions:

If you have other ideas and/or want to participate, please contact me.

Licensing

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Acknowledgements

I would like to thank to the following people:

Contact author

WARNING: I wouldn't answer technical support questions at the following address. Please see the Support section!

Please mail comments, ideas, development help etc. to author: