QMail Mail Server

From Webmin Documentation
Jump to: navigation, search
The module QMail Mail Server is currently unmaintained.

Either the feature is obsolete, or the feature is updated such way that webmin no longer interfaces correctly.

This page explains how to configure the Qmail mail server on your system, and compares it to the other popular server Sendmail.

Introduction to Qmail

Qmail is probably the second-most popular Unix mail server on the Internet, behind Sendmail and in competition with Postfix. Because Sendmail uses a single server process that runs as root, any security hole in that process can allow an attacker to take over an entire system. Qmail was designed to avoid this problem, by using multiple server processes and programs each of which only has the privileges that it needs.

Before you can configure Qmail, you need to understand how Internet email work. The first section of the page on Sendmail Configuration explains pretty much everything you need to know, so read it now if you are unfamiliar with SMTP, MX records and so on. All the same principals apply to Qmail as well.

The biggest difference between Qmail and Sendmail is the location and format of the user mail file directories. Even though Qmail usually has a one-to-one mapping between Unix users and email accounts, it does not store user email in a directory like /var/mail. Instead, the file Mailbox or the directory Maildir in each user's home directory is used, depending on the Qmail configuration. The Mailbox file has the same standard format as the normal user mail files created by Sendmail, but the Maildir directory is quite different. It contains three subdirectories under which each message is stored in its own separate file. This mail storage system makes delivery of new mail much more reliable, and avoids the need to re-write a large file when deleting a message.

All of the Qmail programs, configuration files and queued messages are stored under the directory /var/qmail. There is no single master file- instead, numerous small files in the control and alias subdirectories tell the server what to do. Because they are re-read for each incoming message, any changes to these files take effect immediately.

Unlike Sendmail, Qmail does not have a permanently running server process to accept SMTP connections. Instead, it depends on a super-server like tcpserver, inetd or xinetd (covered in chapter 15) to run a small program when a mail client or other MTA connects to the SMTP port. As soon as the email has been accepted and added to the queue, this program exits. A separate Qmail daemon process periodically scans the mail queue and attempts delivery of messages in it to remote systems or local mailboxes.

Email can also be added to the Qmail queue by feeding it as input to the appropriately named program qmail-queue, which is found in the /var/qmail/bin directory. Also in that directory is a program named sendmail, which takes the same input and parameters as the real Sendmail command but is actually just a wrapper for qmail-queue. On most systems that have Qmail installed, symbolic links exist from /usr/lib/sendmail and/or /usr/sbin/sendmail to this program so that other scripts or programs that expect Sendmail to be installed still work.

The Qmail Configuration module

Webmin's module for configuring Qmail can be found under the Servers category. Assuming you have Qmail installed, clicking on its icon will take you to the module's main page shown in Figure 38-1. Each of the icons on the main page page is a link to a page for one of the module's features, such as aliases or local domains. Under the name of each is the Qmail file or program name related to the feature, so that experienced administrators can see what each icon page is really configuring.

At the bottom of the page is a button labelled either *Start Qmail Processes* or Stop Qmail Processes. As their names suggest, they start the queue-processing daemon if it is not running, or stop it if it is running respectively. Because the Qmail SMTP listener is run from inetd, other hosts will always be able to connect to your system - however, any email that they send will not be delivered to local mailboxes or other servers if the queue-processing server is down.

The Qmail Configuration module

If you do not have Qmail installed, the error message The QMail base directory */var/qmail does not exi*st will appear on the main page instead. Unfortunately, very few operating systems include a Qmail package, so you will almost certainly need to download it from www.qmail.org, compile and install it manually. The installation process involves the creation of several Unix users and an inetd or xinetd service, both of which can be done using Webmin. It should be possible to compile Qmail on any Unix system, and its behaviour and installation location is the same on all of them. As you would expect, this module behaves identically on all operating systems as well.

If you install Qmail, you should also configure the POP3 server program qmail-pop3d that is included in the package. The standard POP3 server that comes with most Unix variants is written to look for Sendmail-style mail files in /var/mail, and will not work with Qmail's ~/Mailbox files or ~/Maildir directories - users will be able to login, but will not see their email!

At the time of writing, only MSC and Debian Linux included Qmail packages as standard. These can be easily installed using the Software Packages module, and will set up all the required users and Internet services for you. The developer of Qmail is reluctant to allow it to be packaged in formats other than the source .tar.gz file, which is why it is not as commonly included with Linux distributions as other MTAs.

Before you can install Qmail, you will need to shut down or uninstall any other mail server installed on your system, such as Sendmail or Postfix. This is necessary because only one program can listed on the SMTP port, and you want to be sure that the listener is always Qmail. Un-installation is the best option, because it ensures that all start-up scripts that might re-start Sendmail are deleted, and that the sendmail command can be linked to Qmail's wrapper program.

Editing local domains

When Qmail receives an email message via SMTP or one of its programs, it needs to work out if it should be delivered locally or forwarded to another server. This is done by looking at the message's To address, specifically the domain part after the @. The domain is compared a list of local domains, and if a match is found the email is delivered to the mailbox of the user whose name is to the left of the @ in the To address (if it exists).

If the domain is not local, Qmail will look up the mail server for the domain and attempt to connect to it in order to transfer the message. This is what usually happens when a client on the same network connects to send out email. However, a problem will occur if your server attempts to connect back to itself, which can happen if the DNS says that it is the mail server for a domain which is not on its local domains list. If this happens, a bounce message will be returned to the sender, containing text like that domain isn't in my list of allowed rcpthosts or too many hops.

To edit Qmail's list of local domains, follow these steps :

  1. On the module's main page, click on the Local Domains icon. A page containing a text box for entering domain or hostnames will be displayed.
  2. Select the Domains listed below radio button. If you leave Only local hostname selected, Qmail will only accept email to addresses at the system's hostname (such as mailserver.example.com).
  3. Enter all the domains that your system should accept mail for into the text box.
  4. Click the Save button to activate them. It is a good idea at this point to send a test email to any new domains to make sure that everything works properly.

Managing email aliases

A mail alias tells your server that mail for a particular address should be forwarded to a different destination instead. That destination can be another email address, a local file, a directory or even the input to a program. They can be useful for setting up pseudo mailboxes that actually send email to a real person, such as sales@example.com or webmaster@example.com. An alias can have the same name as a Unix user, in which case it will intercept all mail to that user and forward it to a different destination instead.

To create a mail alias using Webmin, the steps to follow are :

  1. On the module's main page, click on the Mail Aliases icon. You will be taken to a page listing all existing aliases and their destinations, with a form at the top for adding a new one. The screenshot below shows an example.
  2. In the Address field of the form, enter a name for your new alias such as sales. Leave the menu set to <All domains> for now - its use is explained in the *Managing virtual address mappings* section. The special alias named default will be used for any email that does not match any other alias or user mailbox. It can be useful for forwarding all message that would otherwise bounce to some address.
  3. The Alias to field determines where email to this alias will be sent. The following options are available from the menu :
    Nothing at all will be done with received email. It makes no sense to select this option when creating a new alias.
    Email address
    Email will be forwarded to the user or address entered into the adjacent field. Be careful not to set up a forwarding loop by sending email back to the alias's address again! If you are creating an alias that has the same name as a Unix user and really do want email to be delivered to his mailbox as well as some other destinations, enter the username preceded by a backslash (like \jcameron) into this field. The backslash tells Sendmail to bypass alias checking.
    Mail directory
    Email to the alias will be added to the Qmail mail directory whose path is entered into the text box. It must contain subdirectories named cur, tmp and new to be valid.
    Mail file
    Email received by the alias will be appended to the file whose path is entered into the text box. This should be a standard Sendmail-style mail file.
    Feed to program
    The program whose path and parameters are entered into the text box will be run, and the full text including all headers of email received by the alias will be fed to it as input. This kind of alias is most useful to programmers who want to perform their own custom processing or filtering of email messages. The program is usually run as the Qmail Unix user alias, not root or the user with the same name as the alias.
    Autoreply from file
    When email is sent to the alias, the contents of the file specified in the adjacent text box will be sent back to the original sender. The section *Creating autoreply aliases* on SendmailConfiguration explains how autoreply files work in the Sendmail module, and they have exactly the same functionality in this module as well.
    Apply filter file
    Email sent to the alias will be processed according to the rules in the filter file entered into the text box, which can forward to different destinations depending on the message contents. See the Creating filter aliases section in SendmailConfiguration for more details. It is possible for an alias to have multiple destinations. To add more than one, you will need to re-edit this alias after saving it and fill in the row with <None> selected at the bottom of the Alias to table.
  4. Click Save to have the alias added to Qmail's configuration and activated.

    The mail aliases list

As is usual in Webmin, you can edit an existing alias by clicking on its name in the list on the Mail Aliases page. This will bring up an editing form that contains all the same fields as the creation form, but has Save and Delete buttons at the bottom instead. The first of these will update the alias with any changes that you have made, while the second will permanently delete it.

If a Unix user has a file named .qmail in his home directory, email that would normally be delivered to its mail file will be sent to the addresses listed in the .qmail file instead. If a file named .qmail-_suffix_ exists, email to username-_suffix_ at your server will be send to the addresses in that file. These .qmail files have exactly the same format as those in the /var/qmail/alias directory that Webmin creates when you follow the instructions above, and thus can be used to deliver to files, directories or programs too.

This module does not support the editing of per-user .qmail files though. However, Usermin) does allow normal users to edit their own forwarding files using a web-based interface almost identical to the one described in this section.

Configuring relaying

Qmail can be configured to restrict the destination domains to which it will relay email. This is typically done to stop spammers using your system as an open mail relay, which allows them to hide their true addresses. However, there is no support in Qmail for allowing clients from certain addresses to relay, so setting up relay domain restrictions will make the server useless for sending outgoing email. One solution to this problem is to run two SMTP servers - one for incoming messages that only relays mail for local domains, and another for outgoing email that uses TCP-wrapper or xinetd restrictions to limit access to trusted clients.

The solution recommended by the Qmail website is to use the tcpserver daemon to run the Qmail SMTP program, and have it set the RELAYCLIENT environment variable for certain clients. This tells the latter program to allow relaying no matter what is in the relay domains list, which achieves the desired objective of giving trusted clients full relay privileges. However, it is complex to set up and does not work with inetd or xinetd. At the time of writing, Webmin does not support the configuration of this kind of relaying access control.

By default, Qmail will allow relaying to any domain. The steps to follow to change this are :

  1. On the module's main page, click on the Accepted Domains icon. A page listing domain and hostnames to which relaying is allowed will be displayed.
  2. Select the Domains listed below radio button.
  3. Enter domains to which relaying should be allowed into the first text box on the page. All local domains (discussed in the Editing local domains section) must be included as well, or mail to them will bounce.
  4. You can also enter less frequently used relay domains into the second text box. The only difference between the two is that email to domains in the first box will be processed faster.
  5. Click the Save button to make the relaying restrictions active.

To turn off relay domain limitations, select the Any domain checkbox on the Accepted Domains page and hit Save. Any domains that you have entered will be lost.

Managing virtual mappings

Qmail can be configured to treat email to the same mailbox at different domains differently, so that sales@example.com and sales@foo.com are not delivered to the same user or alias. This is vital if you are hosting multiple mail domains, as there are certain to be clashing mailbox names (like sales or webmaster) in several of them. This is done by creating an alias that only applies to a certain domain, rather than to all domains as the aliases created by following the instructions in the Managing email aliases section do.

Before you can add domain-specific aliases, Qmail must first be configured treat the domain specially. Internally, it adds a suffix like example- or foo- to the To address of any email sent to the domain, so that you can create aliases like example-sales or foo-sales. Fortunately, Webmin does most of the work of adding these prefixes for you where appropriate.

To designate a domain as special for aliases, follow these steps:

  1. On the module's main page, click on the Virtual Mappings icon. A page listing all existing domains and their prefixes will be displayed, with a form at the top for adding a new one.
  2. In the Mail for address field, select Addresses with domain and enter the domain name (like example.com) into the text box next to it. If the *Any address not matching another virtual mapping* option is chosen, the suffix entered in the next step will be added to all To addresses that do not match another virtual domain. This is not normally very useful. If Address is selected and an mailbox name and domain entered into the two text fields next to it, the mapping will apply only to that specific address. The suffix will be prepended to the username part of the address, for example transforming fred@example.com to example-fred@example.com. This is less useful than mapping an entire domain, but can be done to give the user fred the ability to create personal .qmail files for different domains.
  3. In the Prepend to username field, it is simplest to leave Automatically chosen prefix selected. This tells the module to take the first part of the domain name (like example in the case of example.com) as the prefix, which almost always works fine. If you prefer to select your own prefix, choose the Specified prefix option and enter it into the adjacent text box. It should consist of only letters, numbers and the - character. If you enter a Unix username as the prefix, mail to the domain will be effected by the .qmail- files in his home directory. For example, if the prefix is bob and email is received for fred@bob.com, then ~bob/.qmail-fred will control where it is forwarded to. If Nothing is chosen, no prefix will be added for the domain at all. This can be useful if a parent domain does have virtual mapping enabled.
  4. Hit the Create button to add the new virtual domain mapping to the list.
  5. Go back to the main page, and click on the Local Domains icon.
  6. Remove the domain you have just added from the list - otherwise, any email to it will be delivered normally as though the virtual mapping did not exist.
  7. Click Save to update the local domains list.

As is usual in Webmin, you can edit or delete a virtual mapping after it has been created by clicking on the domain name on the list in the Virtual Mappings page. Either change any of the fields and click Save to activate the new prefix, or hit the Delete button to remove it altogether. Be careful changing the prefix or deleting a mapping, as any existing aliases that use that prefix will not be updated and thus will stop working.

Once you have configured Qmail to perform virtual mapping for a domain, you can add aliases that are specific to it. To do this, follow the instructions in the Managing email aliases section earlier in the chapter, but in step 2 select the domain that the alias should be in from the menu. After it has been added, the alias will appear in the list with its prefix, like example-sales rather than as the actual address that it really matches, like sales@example.com.

Be aware that an alias that is not specific to any domain will not apply to email send to that mailbox name at other domains. This is unlike the behaviour of Sendmail aliases, and can be confusing if you have just added a virtual mapping for a domain and are wondering why all your old aliases have stopped working.

Configuring domain routing

Normally, Qmail delivers email for non-local domains by looking up the appropriate mail server in the DNS and connecting to it. However, you can use this module to configure the MTA to connect to a different server for certain domains instead, or to send all outgoing mail via a single server. This can be useful if your system is a gateway for several internal mail servers that cannot be reached directly from the rest of the Internet, or if you want all outgoing email to be sent via your ISP's or company's server.

To specify an alternate mail server for a domain, the steps to follow are :

  1. On the module's main page, click on the Domain Routing icon to go to a page containing a list of all existing routings (if there are any) with a form at the top for adding a new one.
  2. In the Create Domain Route form, enter the domain name that you want routed via a different server into the *Mail for host or domain* field.
  3. In the Send via SMTP server field, select the second radio button and enter a hostname or IP address into the field next to it. If the Delivery directly option is chosen, Qmail will perform a DNS lookup for the domain and deliver mail to the resulting server manually, even if it has been configured to send all outgoing mail via another server.
  4. Normally, the SMTP port field should be left set to Default. However, if you choose the second option Qmail will connect to the port number entered into its text field instead of the SMTP default of 25. This can be useful if for some reason a particular mail server is not using the normal port.
  5. Click the Create button to save and activate the new domain routing rule.

Once a routing has been added, it will appear below the creation form on the Domain Routing page. You can edit or delete it by clicking on the domain name, changing the details and hitting the Save or Delete button respectively. Once again, any changes will be immediately made active.

To tell Qmail to send all outgoing email via a specified mail server, do the following :

  1. Click on the Domain Routing icon on the main page.
  2. Scroll down to the Deliver all other outgoing mail via field and select the second radio button. Then enter the hostname or address of the server into the text box next to it.
  3. Click Save to activate the new setting.

To have Qmail lookup and deliver normally to destination servers again, select Deliver directly in step 2 instead.

Editing global Qmail options

Qmail has several settings that apply to all email messages that it processes, related to the hostname that it uses, SMTP timeouts and the maximum message size. The steps below explain how to set them and what they mean:

  1. On the main page of the module, click on the QMail Options icon to bring up a form showing and allowing the editing of global options.
  2. The Local host name field can be used to tell Qmail your system's hostname. It should be set to the Internet domain or hostname, such as example.com.
  3. To set the hostname that Qmail will send to remote SMTP servers, select the second option for the Hostname for SMTP HELO field and fill in its text box. If Default is selected, the hostname from the previous field will be used.
  4. To change the amount of time that your server will wait for a remote MTA to accept an SMTP connection, fill in the *SMTP connection timeout* field. If Default is selected, a timeout of 60 seconds will be used. It may be useful to lower this to prevent your system wasting too much time trying to contact down servers - 60 seconds is usually far too long to wait.
  5. To set the number of seconds that Qmail will wait for a response to each SMTP command send to a remote server, modify the *SMTP outgoing response timeout* field. If Default is chosen, a 20 minute timeout is used.
  6. To stop your MTA accepting large emails, select the second button in the Maximum message size field and enter the maximum number of bytes that an email can contain into the text box next to it. If Unlimited is chosen, mail of any size will be accepted. Setting a limit can be useful on systems with limited disk space or network bandwidth.
  7. To set the amount of time that Qmail will wait for new data from a remote mail server connecting to your system, fill in the SMTP incoming data timeout field. The default is 20 minutes.
  8. When your server accepts a message to an address like fred@ where is one of the system's local IP addresses, it will convert that address into the hostname specified in the Hostname for email to local IP address field. Even though email is not supposed to be addressed like this, it can sometimes happen and Qmail can deal with it. If Default is selected, the host or domain name from the Local host name field is used instead.
  9. To change the greeting that Qmail will present to SMTP clients when they connect, choose the second radio button in the *SMTP greeting message* field and enter some text into the adjacent text box. This message should start with the system's hostname, and if Default is selected that is all it will contain.
  10. Click the Save button to update the Qmail configuration files with the new settings.

Editing mail user assignments

Qmail's mail user assignments feature allow you to create 'fake' mailboxes that can receive email just like real Unix users. Each user assignment defines an additional mailbox, and has an associated Unix username, UID, GID and home directory in which the mail file and .qmail files are located. They are most useful if you want to avoid having to create a Unix account for every mailbox on your system, or if you want to direct mail to multiple users into the mailbox of a single real Unix user.

To create a new mail user, the steps to follow are :

  1. On the module's main page, click on the Mail User Assignments icon. A page listing existing assignments will be displayed, with a form at the top for creating a new one - the image below shows an example.
  2. In the Address username field, select Exact username and enter a name (like fred or joe) into its text box. Alternately, you can choose Usernames starting with and enter a prefix into the box next to this option to have the mail user receive email addressed to any mailbox whose name starts with the prefix. This can be useful if you want to have email for an entire domain delivered to a single user, for later retrieval and separation by a program like Fetchmail (covered on FetchmailConfiguration). For example, if the domain foo.com was mapped to the prefix foo on the Virtual Mappings page, you could select this section option and enter foo- here.
  3. In the Unix user field, enter or select the name of a user who will own the destination mail file or directory.
  4. In the Home directory field, enter a directory that delivery will be made into. This does not have to be the home directory of the user from the Unix user field, but must be writable by him.
  5. In the UID box, enter the ID of the user from the Unix user field.
  6. In the GID box, enter the primary group ID of the user from the Unix user field.
  7. Hit the Create button to add and activate the new mail user assignment. It will now appear on the list on this page.

    The mail user assignments list

As usual, you can edit existing mail users by clicking on their names in the list, making changes on the form that appears and clicking the Save button. Similarly, you can delete a user with the Delete button located next to Save. Again, any such changes take effect immediately.

One problem with mail users created by following the steps above is that the standard Qmail POP3 server setup does not recognize them. However, there are instructions and programs on the www.qmail.org for setting up a POP3 server to support 'fake' users and virtual domains, where they are most useful.

Viewing the mail queue

When Qmail receives a message, it is placed into the mail queue. If it can be send to its destination immediately, then it will be removed from the queue almost at once - however, if some temporary error occurs when sending then it will remain queued for later processing. The Qmail server process makes periodic checks of messages in the queue, re-trying each one at longer and longer intervals until it eventually gives up.

Most messages that are in the queue for a long time are there because the destination mail server is down or unreachable. Another common cause is a temporary error reported by the remote MTA, such as a lack of disk space. Webmin allows you to view messages in the queue and even delete them by following these steps:

  1. On the module's main page, click on the Mail Queue icon to go to a page listing the details of queued messages. The number of emails in the queue is displayed below the icon, so that you can see how long it is at a glance.
  2. On the mail queue page the ID, sent date, sender and destination of all queued messages are displayed in a table. If the queue contains more than 20 messages, only the first 20 will be displayed. To page through the rest, use the left and right arrow buttons that appear above the list.
  3. To view the actual contents of an email, click on its ID in the queue listing. All headers, the text body and any attachments will be displayed. To view an attachment, just click on its icon. To remove just this message from the queue, hit the Delete button at the bottom of the page.
  4. To remove multiple messages from the queue, first select them using checkboxes next to their IDs and the Select all and Invert selection links on the queue list page. Then click the Delete selected messages button to get rid of those that you have chosen.

Unlike in the Sendmail module, there is no button on the queue page to force an immediately delivery attempt for all queued messages.

Reading users' email

As the introduction explains, Qmail can be configured to store email in Mailbox files or Maildir directories in user home directories, or even under /var/mail like Sendmail does. Webmin allows you to read users' email, but before it can do that you must properly configure the module so that it knows where to look. See the section on Configuring the Qmail Configuration module later in the chapter for details on which fields need to be changed. By default, the ~/Maildir directories will be used as this is the most common Qmail configuration.

The read mail in users' mailboxes, the steps to follow are :

  1. On the module's main page, click on the User Mailboxes icon. A page listing all of the users on your system and the sizes of their mailboxes will be displayed, unless you have more than 200 users. In that case, a small form for entering a username will appear instead.
  2. Click on the name of a user to bring up a list of messages in his mailbox. By default, the most recent messages are shown first, even though they are actually at the end of the actual mail file. If the mailbox contains more than 20 emails, only the first 20 will be displayed. To page though the rest, use the left and right arrow buttons above the list.
  3. To view an actual message, click on the sender's name in the From column. A page showing the important headers, body text and attachments will appear. Click on an attachment icon to view it, assuming that the data type is supported by your browser or some external program. To remove just this email from the user's mailbox, click the Delete button at the bottom of the page.
  4. To delete multiple messages, first select them using the checkboxes and Select all and Invert selection links on the mail list page, then click the Delete button.
  5. To search the user's mailbox for messages matching some criteria, use the Find messages where form below the list. The following types of search can be selected from the menu : From: matches, Subject: matches, To: matches or Cc: matches Finds messages in which the From, Subject, To or Cc field contains the text entered into the adjacent text box. The comparison is case-insensitive, but regular expression characters cannot be used. Date: matches Finds messages in which the sending date header contains the entered text. This header will not be converted to local format, so whatever you enter must match the date format used by the sender. Body matches Finds messages whose body contains the entered text. The body includes all attachments in their un-encoded form, not just the text that is shown when you read an email. *Size is greater than* Finds messages whose total size is greater than the number of bytes entered into the adjacent field. For each of the above search types, an inverse type is also available, such as From: doesn't match or *Size is less than*. After choosing your search type and entering text to match, hit the Search button. A page listing all matching messages will be displayed, from which you can view the contents of emails or select some or all to delete, just like in the normal mail list.

The mail reading interface even allows you to compose, forward and reply to messages in a user's mailbox. However, it was not designed to be a general-purpose web mail client - instead, you should use a program like Usermin which has a nicer interface and supports Qmail mail directories just as well.

Configuring the Qmail Configuration module

Like most other modules, this one has several settings that apply to the operation of module itself rather than to Qmail. They are divided into two groups - those that effect the user interface, and those that specify the paths to Qmail configuration files and programs. When you click on the Module Config link on the main page, the first group of settings is listed under *Configurable options* while the second appears under System configuration.

The two most common Qmail configurations are delivery to the Mailbox file or Maildir directory in users' home directories. By default, the module is set up to read mail from ~/Maildir, but if you have set up Qmail to use the ~/Mailbox file instead you must change the Mailbox format field to Single file.