If you are running Debian-Sarge instead of Debian-Woody please use the Postfix 2.x tutorial.
Important: This tutorial is up since 17.7.2004 and is a complete rewrite of the first tutorial. If you find typos, wrong language or b0rked configuration I would be happy if you dropped me an email. Just don't fear to follow these instructions. I have checked everything twice.
As some of you may have noticed there have been some problems in the first version of this tutorial that may have led to error messages like "user not found" although all information was entered properly into the database. I read a lot of documentation and spent weeks on IRC until I completely understood the quirks of virtual domains in Postfix 1.x. That does not mean that you should not use Postfix 1.x (as shipped with Woody). Just some things behave differently. I decided to completely rewrite my first tutorial. I have added a few paragraphs that describe virtual domains, the general function of mappings and how MySQL can be used in Postfix. As a downside I decided to change the database structure fundamentally. Thus my good old Perl script (ispmailadmin) does not work with this database structure any more. I'm planning to rewrite the Postfix 2.x tutorial (for Sarge) too to adopt the structure. After that I'll probably help the phpmywebhosting project to make it use this structure. Thanks for your patience and the many feedback emails I received. Have fun with the new version.
You have probably already seen web hosters who allow you to rent domains and receive email on these domains. Have you ever wondered how they actually handle these thousands of domains? There is surely nobody entering all these domains and aliases into a 'main.cf' configuration file manually. Postfix offers two nice features that simplify such tasks:
In addition to your local domain (which is probably the domain that is configured in /etc/defaultdomain) you may receive email for other domains that are called virtual domains. There is no limitation on the number of domains you receive email for.
You do not need to store all the information about your users and valid email addresses in text files. Postfix supports database lookups to common DBMSs like MySQL or PostgreSQL. This approach is especially charming as you may write a web administration GUI to manage the database. You may even allow your users to take care of their email accounts themselves.
This tutorial will introduce you to the basics of this kind of configuration. If you carefully follow all the steps in this document you will end up with a mail server that can handle thousands of domains and user accounts. These are some features you will get:
Although I will try to get you going quickly you will need to know a few things already:
If I couldn't scare you by now then you are sincerely invited. Make yourself a good pot of vanilla tea, lure a cat onto your lap and let us start with just a little theory.
In short a mapping assigns one value to another. You probably know the file /etc/aliases where you define forwardings for your local domain. A line there looks like this:
postmaster: root
This makes all mail to postmaster@your-domain be redirected to root@your-domain. The left side (here: "postmaster") is commonly called LHS (left-hand side) and the right side (here: "root") is called RHS (right-hand side) accordingly. You will find that these are common abbreviation when talking about mappings.
Hint: Usually mapping files do not have colons (':') on the left side. This is special to the aliases table for historical reasons.
If you are setting up Postfix the quick and dirty way you will typically start with text files like the one above. You just write the mappings into it and run "postmap filename" on it to convert the text file into a hash file called "filename.db". Then you can access this mapping using "hash:filename" in your Postfix configuration. You may notice that the default alias maps configuration looks like "alias_maps = hash:/etc/aliases" - just as an example. The "hash:" is called the lookup method.
In my setup I replace the text files by MySQL tables. This makes data handling a lot more flexible. But as database tables usually contain more than just two columns you will need to tell Postfix which column is meant to be the LHS and which is the RHS. This definition is stored in a text file like this:
user = service
password = DomAKg07
dbname = provider
table = virtual_mailboxes
select_field = email
where_field = mailbox
hosts = localhost
If a file like this would be saved as /etc/postfix/mysql_virtual_mailboxes.cf you could use a mapping of "virtual_mailbox_maps=mysql:/etc/postfix/mysql_virtual_mailboxes.cf". The LHS of the mapping is defined as 'select_field' and the RHS is defined as 'where_field'. In this example it would be a mapping of the `email` column to the `mailbox` column. The other fields in this definition file are user (the username that connects to the DBMS), password (the password for that user), dbname (the name of the database), table (the name of the table in that database) and hosts (the name of the server where the DBMS runs).
Let me begin with a brief introduction to virtual domains in Postfix 1.x (the newer Postfix 2.x handles them differently) because misconfiguration will cost you hair and time. There are two types of domains:
Your default domain (/etc/defaultdomain) is usually configured as a local domain. All domains listed as mydestination in your main.cf are treated as local domains. Emails for local domains are delivered to system users.
Example: your local domain is myowndomain.com. This means that email for joe@myowndomain.com will be delivered to the mailbox of the system user "joe". System users are configured in the /etc/passwd.
Your mail server can receive emails for additional domains called "virtual domains". Virtual domains are very flexible. You do not need system accounts for every mail user (so users do not need to be configured in the /etc/passwd). So your system can handle thousands of users easily.
Important: a domain can either be virtual or local - never both! So if you decide you want your default domain be a virtual domain then remove it from the mydestination definition. Just leave it blank or set it to "mydestination=localhost".
Four steps are run when you receive an email for a user in a virtual domain:
I recommend you also betimes read the original documentation about virtual domains in the VIRTUAL_README that shipped with the postfix-doc package and is found in /usr/share/doc/postfix/VIRTUAL_README.gz.
Packages you will absolutely need:
If you intend to run the MySQL server on the same machine:
If you want to offer mail access using POP3/IMAP you need:
If you want to allow road-warriors to send email through your server using authenticated SMTP you also need:
If you want to scan incoming email for viruses and spam:
If you want to offer webmail for your users:
Optional but useful packages:
You need to create a database first which holds the tables. If you are experienced in using MySQL you can of course do this work on the command line. However I would rather use 'phpmyadmin' for MySQL database management. It is up to you.
Hint: when the mysql-server is first run you can access the database as user 'root' with no password. You need to create a new database user for Postfix that has read-only access to just the provider database. If you are stuck here please read the appropriate documentation at mysql.com.
First create a database. I call it 'provider' because I intend to do more than just email. Either do this in phpmyadmin or run this shell command.:
mysqladmin -u [username] -p -h [hostname] create provider
After you have created the database you will need to create the database tables that will contain the control information for Postfix.
The first table will contain just one boring column containing the virtual domain name. This table will need to have a row for each virtual domain. Just run this SQL statement to create it:
CREATE TABLE domains (
domain varchar(50) NOT NULL,
PRIMARY KEY (domain),
UNIQUE KEY domain (domain)
)
TYPE=MyISAM;
The table 'forwardings' will be used to alias one email address to another. You can use this table for general redirections. (Hint: this even works for your local domain.) This is the SQL statement to create the table:
CREATE TABLE forwardings (
source varchar(80) NOT NULL,
destination varchar(80) NOT NULL,
PRIMARY KEY (source)
)
TYPE=MyISAM;
Finally the 'users' table contains information about your user accounts. Every user has a username and password for accessing the mailbox by POP3 or IMAP. As users tend to forget things (just look under the keyboard of your father-in-law for his password) I decided to use the email address also as a login username. And last there is the 'mailbox' field that defines where email for this user shall be saved on your hard disk. Just another SQL query to copy and paste:
CREATE TABLE users (
email varchar(80) NOT NULL,
password varchar(20) NOT NULL,
UNIQUE KEY email (email)
) TYPE=MyISAM;
As specified earlier in this document you need to tell Postfix where the control information is stored in the database. You need to create three text files in /etc/postfix for that reason.
Important: Postfix runs in a chroot directory (/var/spool/postfix) and cannot access any files outside that directory. Usually you talk to the MySQL database via its socket file /var/run/mysqld/mysqld.sock. As you can see this file is out of reach for Postfix. So you can either try to move the socket file (which may lead to other problems) or use TCP networking. The latter means you are talking to MySQL through your network stack. Advantage: you do not need to care about the chroot restrictions. Disadvantage: everybody can talk to your MySQL server. So you are strongly recommended to take measures to limit access to your database server (e.g. by using netfilter rules). You have been warned. To enable TCP networking just comment out the line "skip-networking" from your /etc/mysql/my.cnf file and restart MySQL.
This is a simple mapping of your virtual domain name (LHS) to the string 'virtual' (RHS). This mapping is used for the transport table as it maps each virtual domain to the string 'virtual' (which tells Postfix that this is a virtual domain). It is also used for the virtual_maps and virtual_mailbox_maps definition where just the LHS matters.
Create the file and fill the '...' with the information of your database user and database server name. Do not use "localhost" as the server name because Postfix would try to use the MySQL socket for communication. Instead use the name or IP address that belongs to your ethernet interface.
user = ...
password = ...
dbname = provider
table = domains
select_field = 'virtual'
where_field = domain
hosts = ...
This mapping reads the 'forwardings' table to provide a way to redirect email addresses. It simply maps the 'source' column to the 'destination' column. We will use it for the virtual_maps mapping.
user = ...
password = ...
dbname = provider
table = forwardings
select_field = destination
where_field = source
hosts = ...
The last definition file deals with user mailboxes. It tells Postfix where to store email for a specific email address. We will use it later in the virtual_mailbox_maps mapping. Postfix will search the 'mailbox' column (RHS) for a given 'email' address (LHS). I just add a '/' to the mailbox field so Postfix will create a maildir structure instead of a mailbox file. This is needed for the Courier POP3 and IMAP services later.
user = ...
password = ...
dbname = provider
table = users
select_field = concat(email,'/')
where_field = email
hosts = ...
Security warning: Make sure nobody but root can read these files. Otherwise everybody on your system could read your database access password in plain text. Run "chmod o= /etc/postfix/mysql-virtual_*.cf" to steal others the privileges. You also need to set the group of these files to postfix by running "chgrp postfix /etc/postfix/mysql-virtual_*.cf".
Your system can hold mailboxes for thousands of users. You probably do not want to assign a unique UID (user ID) to every user. So I recommend you create a pseudo-user who will become the owner of all mailboxes.
Just enter these lines in a root shell:
groupadd -g 5000 vmail
useradd -g vmail -u 5000 vmail -d /home/vmail -m
The /etc/postfix/main.cf is the main configuration file for Postfix. I will describe the basic settings needed for virtual domains. Do not wipe away your main.cf and paste these lines into it. You will probably want to customise the configuration in other ways so I cannot be complete here.
| Setting | Meaning |
|---|---|
| myhostname = ... | Make sure this is set to your fully qualified domain name. |
| mydestination = ... | List your local domains here seperated by commas. Do not list any virtual domain here. |
| mynetworks = ... | List the IP ranges here that are allowed to send email through your mail server. This is most likely your local network. |
| transport_maps = mysql:/etc/postfix/mysql-virtual_domains.cf | The transport mapping is used to determine how to handle a domain. We are just using the 'domains' table from the database that maps virtual domain names to the string 'virtual'. This is needed to tell Postfix this is a virtual domain. |
| virtual_maps = mysql:/etc/postfix/mysql-virtual_forwardings.cf | This is a general purpose redirection table. You can redirect one email address to another or even catch all mail for a domain and redirect it to one specific email address. The information is stored in the 'forwardings' table. Every LHS email address is rewritten to the addresses on the RHS. If you have multiple destination addresses you can comma-seperate them in one entry. (Hint: the virtual domains must not be listed here or they would become 'virtual alias domains'. This kind of virtual domains is just used for aliasing - you cannot receive email for such domains in a mailbox.) |
| virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual_domains.cf mysql:/etc/postfix/mysql-virtual_mailboxes.cf | Another important mapping is the virtual mailbox maps. First it is a list of virtual mailbox domains (that is a domain that has user mailboxes on this server). Second it maps email addresses (LHS) to the location of the mailbox on your hard disk (RHS) relative to the virtual_mailbox_base. |
| virtual_mailbox_base = /home/vmail | This is the base path where the mailboxes of the users will be stored on your hard disk (see above). |
| virtual_uid_maps = static:5000 | You should tell Postfix who shall be the owner of the mailboxes. This is the UID (user ID) of the owner (taken from /etc/passwd). Set it to the UID of the "vmail" user you just created. |
| virtual_gid_maps = static:5000 | The same for the GID (group ID). |
| smtpd_sasl_auth_enable = yes | Enable the authenticated SMTP feature. |
| smtpd_sasl_security_options = noanonymous | Users need to provide valid credentials for authenticated SMTP. Anonymous access is not allowed. |
| broken_sasl_auth_clients = yes | Some broken mail clients like Microsoft Outlook use a deprecated way to detect if a mail server speaks authenticated SMTP. Make them happy. |
| smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, check_relay_domains | These restrictions are checked whenever a new email arrives at your mail server to check who is allowed to relay email. permit_mynetworks will allow everybody you configured in mynetworks. permit_sasl_authenticated will allow everybody from everywhere as long as they use authenticated SMTP. And finally relaying is allowed if the user wants to send email to one of the domains listed in relay_domains. |
| smtpd_use_tls = yes | Encrypt the authenticated SMTP session using SSL |
| smtpd_tls_cert_file = /etc/postfix/smtpd.cert | The location of the SSL certificate for TLS (we will create it later) |
| smtpd_tls_key_file = /etc/postfix/smtpd.key | The location of the SSL private key for TLS |
Run "postfix reload" and "postfix check". If you did not get any warnings this part is complete.
Imagine your users fetch their email using POP3. Now they need a way to send mails back through your mail server. For security reasons Postfix allows users defined in mynetworks to send emails. Usually your mail server will only accept mails for its own domains. If you allowed everybody to send email to every other domain you would provide a so called "open relay" that spammers abuse to send out their digital trash. So the logical way is to make remove users trusted by letting them provide their username and password. If the credentials are correct the user will be trusted like he has an IP an mynetworks. Most email cilents have this feature included.
Setting up authenticated SMTP is quite easy. The only pitfall is that Debian runs Postfix in a chroot'ed environment in /var/spool/postfix by default.
Postfix cannot directly access MySQL tables in version 1.x. So using MySQL tables for SMTP authentication means using PAM (pluggable authentication modules). PAM is used for about everything that needs authentication - even loggin into your system from the console. The second step is to make SASL use PAM for authentication. This is easy. Create a directory /etc/postfix/sasl and set the password check method to PAM::
mkdir /etc/postfix/sasl
echo "pwcheck_method: pam" > /etc/postfix/sasl/smtpd.conf
mkdir /var/spool/postfix/lib/security
cp /lib/security/pam_mysql.so /var/spool/postfix/lib/security/
All authentication configurations are stored in "/etc/pam.d". As Postfix runs chroot'ed the configuration is searched for in "/var/spool/postfix/etc/pam.d". You need to create that directory first. Then go there and put the following lines into a file called "smtp":
auth required pam_mysql.so user=[database admin user] passwd=[database admin password] host=[database server hostname] db=provider table=users usercolumn=email passwdcolumn=password![]()
account sufficient pam_mysql.so user=[database admin user] passwd=[database admin password] host=[database server hostname] db=provider table=users usercolumn=email passwdcolumn=password
An important step is to encrypt the SMTP session. Otherwise the username and password would be transmitted in a very insecure way. So I encourage you to encrypt that communication using TLS. TLS is short for Transport Layer Security (RFC2246) and in short terms uses SSL (Secure Socket Layer) which encrypts the mail connection between the road-warrior and the mail server.
First you will need an SSL certificate. If you don't want to pay for one from your favorite trustcenter you can well use a self-signed one. (Personal note: I wonder how paying for something makes it more trusted.) The only drawback: the mail clients does not know about your CA (certificate authority) and will spit out a warning to the user. Either tell the users to ignore the warning or let them install the certificate on their computers.
For a certificate that is valid for one year for the hostname smtp.domain.tld you would type this:
openssl req -new -outform PEM -out smtpd.cert -newkey rsa:2048 -nodes -keyout smtpd.key -keyform PEM -days 365 -x509
You will then be asked a few question about the fields of the certificate. It does not matter what you enter. Just fill the fields. One exception though - the "Common Name" must be the hostname of your mail server. Example session:
Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Hamburg
Locality Name (eg, city) []:Hamburg
Organization Name (eg, company) [Internet Widgits Pty Ltd]:workaround.org email services
Organizational Unit Name (eg, section) []:Master of Disaster
Common Name (eg, YOUR name) []:mailtest.workaround.org
Email Address []:postmaster@workaround.org
After a short moment you will get two files: "smtpd.key" (the private key file) and "smtpd.cert" (the certificate). Move these two files into /etc/postfix.
Security warning: Make sure at least the key file is not readable for the whole wide world:
chmod o= /etc/postfix/smtpd.key
Run "postfix reload" to restart Postfix. Run telnet localhost 25" and enter "EHLO anywhere.org". You should find a line reading "250-STARTTLS". Bingo - TLS is running.
You already set up a large part of the configuration. However your users will still be unhappy as they cannot reach they mailboxes. So it is time to configure the POP3 or IMAP service. First you need to edit the file /etc/courier/authdaemonrc and change the directive authmodulelist to "authmysql" like this:
authmodulelist="authmysql"
Then you need to define the fields of the MySQL database table in /etc/courier/authmysqlrc like this:
MYSQL_SERVER ...
MYSQL_USERNAME ...
MYSQL_PASSWORD ...
MYSQL_PORT 0
MYSQL_DATABASE provider
MYSQL_USER_TABLE users
#MYSQL_CRYPT_PWFIELD (comment this out)
MYSQL_CLEAR_PWFIELD password
MYSQL_UID_FIELD ""
MYSQL_GID_FIELD ""
MYSQL_LOGIN_FIELD email
MYSQL_HOME_FIELD "/home/vmail"
MYSQL_MAILDIR_FIELD concat(email,'/')
Do not forget to restart the authdaemon process using "/etc/init.d/courier-authdaemon restart".
Try to reach the POP3 service by running "telnet localhost pop3". You should get a "+OK Hello there.". Voilà - your users should be happy now. :)
Hint: you cannot fetch emails from a mailbox unless at least one mail has been sent there. Users would get cryptic error messages. So I recommend sending a welcome email to new users.
Congratulations. The configuration part is done. Now comes the more practical part. We will now create the database entries for your first domain so you can test to receive an email for the virtual domain. Please create these rows in the appropriate database tables:
| Column | Value |
|---|---|
| domain | virtual.test |
| Column | Value |
|---|---|
| user@virtual.test | |
| password | secret |
This means we have one domain called "virtual.test" and one user whose email address (and also the username) is "user@virtual.test". The password for this user is "secret". As you do not have an MX entry (mail exchanger - part of the DNS zone) you need to 'deliver' the emai manually. Establish an SMTP connection to your mail server (telnet servername 25) and enter the SMTP commands written on the right side:
| Server | You |
|---|---|
| 220 myserver ESMTP Postfix (Debian/GNU) | |
| ehlo workaround.org | |
| 250-mailtest 250-PIPELINING 250-SIZE 10240000 250-VRFY 250-ETRN 250-STARTTLS 250-AUTH LOGIN PLAIN GSSAPI 250-AUTH=LOGIN PLAIN GSSAPI 250-XVERP 250 8BITMIME |
|
| mail from:<test@workaround.org> | |
| 250 Ok |
|
| rcpt to:<user@virtual.test> | |
| 250 Ok |
|
| data | |
| 354 End data with <CR><LF>.<CR><LF> |
|
| This is a test email. . |
|
| 250 Ok: queued as ABC1D1C123 | |
quit |
|
| 221 Bye |
If the server responded like in the example dialog above then the email was at least received. In the log file /var/log/mail.log you should find a section like this:
Jul 16 20:03:06 myserver postfix/smtpd[2692]: EBC1D1C202: client=mailtest[127.0.0.1]
Jul 16 20:04:04 myserver postfix/cleanup[2697]: EBC1D1C202: message-id=<20040716180306.EBC1D1C202@mailtest>
Jul 16 20:04:05 myserver postfix/qmgr[2567]: EBC1D1C202: from=<test@workaround.org>, size=347, nrcpt=1 (queue active)
Jul 16 20:04:05 myserver postfix/virtual[2704]: EBC1D1C202: to=<user@virtual.test>, relay=virtual, delay=59, status=sent (maildir)
Jul 16 20:04:39 myserver postfix/smtpd[2692]: disconnect from mailtest[127.0.0.1]
If you read "status=sent (maildir)" then the email has been successfully delivered. Run the command "find /home/vmail" to see all directories and files there. It should look like this:
/home/vmail/user@virtual.test
/home/vmail/user@virtual.test/tmp
/home/vmail/user@virtual.test/cur
/home/vmail/user@virtual.test/new
/home/vmail/user@virtual.test/new/1090001045.2704_0.myserver.workaround.org
Everyting worked like I described? Great. Then as a last test you may try to fetch the email from your mail client via POP3 or IMAP (depending on what service you installed). The username for fetching email is always the email address ("user@virtual.test") and the password is "secret" in this test case.
Now that the first test has succeeded you will want to configure the datase for your own domains and users. Let me explain what you need to insert into the database:
One of the two most annoying things when using email is spam and viruses. Fortunately you can fight both using a software called AMaViS (A Mail Virus Scanner). AMaViS is an interface between Postfix, spamassassin (famous for its bayesian spam filtering capabilities) and any virus scanner (like ClamAV which is freely available). Do not get confused: AMaViS contains the spam filtering part but has no virus scanner built in. I suggest you install ClamAV, too. It is a free virus scanner that gets updates frequently.
AMaViS has a huge advantage over even most of the commercial solutions. It is called while someone is sending you an email - not just after the delivery is done. If a virus is found or the spam probability is high enough then the email will be rejected while you have the sending system still on the hook. You have probably noticed that most spam and virus emails are sent with faked sender addresses. So instead of first receiving the email and then bothering the wrong sender you stop unwanted mails on the door step.
Woody ships with a very outdates version of AMaViS that I discourage to use. Instead you should get the backport of amavis-new. Using a backport means installing a special software package that is designed for Woody but contains a newer version of the software. If you are running Debian on the i386 platform then you can use the backports from backports.org just first need to add this line to your /etc/apt/sources.list:
deb http://www.backports.org/debian/ woody amavisd-new clamav
This enables you to install these two packages from the backports web site. Then run "apt-get update" and "apt-get install amavisd-new clamav clamav-daemon zoo bzip2 unrar". (Hint: "unrar" and "zoo" can only be installed if you have "non-free" in your sources.list.) The software packages should be installed now.
Info: If you completely dislike backports you may instead use the "postfix-amavis" package.
Please take a look at the /etc/amavis/amavisd.conf file. These settings need to be taken care of:
Do not forget to restart the amavis service after you have changed the configuration file.
Now that the amavis daemon is hopefully running in the background you still nedd to tell Postfix that you want to have all your emails scanned. Edit the /etc/postfix/main.cf and add the following line:
content_filter = amavis:[127.0.0.1]:10024
Now you have all emails run through the "amavis:" service that is listening on port 10024 on your system. You also need to add the amavis filter to Postfix's configuration. Add these two sections to the /etc/postfix/master.cf:
amavis unix - - n - 2 smtp
-o smtp_data_done_timeout=1200
-o disable_dns_lookups=yes
127.0.0.1:10025 inet n - n - - smtpd
-o content_filter=
-o local_recipient_maps=
-o relay_recipient_maps=
-o smtpd_restriction_classes=
-o smtpd_client_restrictions=
-o smtpd_helo_restrictions=
-o smtpd_sender_restrictions=
-o smtpd_recipient_restrictions=permit_mynetworks,reject
-o mynetworks=127.0.0.0/8
-o strict_rfc821_envelopes=yes
Due to quirks in the file permissions you also need to add the user "clamav" to the group "amavis":
adduser clamav amavis
/etc/init.d/clamav-daemon restart
Finally run a "postfix reload" and "postfix check" to make sure you have still no errors in your Postfix configuration. All incoming emails should now be tested for viruses and spam. Look at your /var/log/mail.log file for details. A great service for checking AMaViS is testvirus.org. They are sending you innocuous test mails with the EICAR virus test signature.
A last word to explain how Amavis works. Postfix receives your mail and pipes the email as defined in your "amavis" filter. AMaViS will then use the configured virus scanner to scan all attachments. If the attachments are archives it will even use the archive tools to unpack them. After scanning the files it will contact Postfix on localhost's port 10025 and re-inject the email into the delivery process. But this time it sets the "content_filter" option to nothing and thus bypasses further content scanning. You will also see this behaviour in your /var/log/mail.log file. First you will see a "relay=amavis" and then a "relay=virtual". If everything worked you will see a line like this in the /var/log/mail.log:
amavis[677]: (00677-02) Passed, <my@test.address> -> <user@virtual.test>, Message-ID: <20040716231708.8717C1C21E@myserver>, Hits: -
Now that you know how your users can get and send their emails via POP3, IMAP and SMTP you may wonder if there is a comfy way to give your users access to their mailbox using webmail. Luckily this is easy. The package you need is called "sqwebmail" - a web mail system that uses the Courier services and can be told (via PAMs) to use any authentication scheme. Install it using "apt-get install sqwebmail". You will be asked if you want to run the "webmail" binary chroot. Yes you do!
To make sqwebmail use your MySQL database you need to change the /etc/pam.d/webmail file like this:
auth required pam_mysql.so user=<dbuser> passwd=<dbpassword> host=<dbhost>
db=provider table=users usercolumn=email passwdcolumn=password
account sufficient pam_permit.so
Now access your web server like http://<hostname>/cgi-bin/sqwebmail and you should get a login dialog.
Perhaps you have a typo in your setup or just missed to read a part of this tutorial. Don't panic! Let me show you some common error messages and how you can fix them:
| Log file | Error message | Meaning |
|---|---|---|
| /var/log/mail.log | ...to=<user2@my.testdomain>, relay=none, delay=0, status=bounced (unknown user: "user2@my.testdomain") | Postfix knows that my.testdomain is a virtual domain. But the user account "user2@my.testdomain" was not found in the 'users' table. |
| /var/log/mail.log | ...to=<foobar@local.test>, relay=none, delay=0, status=bounced (Name service error for domain.com: Host not found) | Postfix could not find an MX entry for the domain "domain.com". |
| /var/log/mail.log | ...warning: connect to mysql server mailtest: Access denied for user: 'service@myserver' (Using password: YES) |
Postfix tried to read from the MySQL database using the user service@myserver. However the combination of username and password have been rejected by MySQL. |
| Output from "postfix check" | postfix/postfix-script: warning: /var/spool/postfix/etc/hosts and /etc/hosts differ |
A file in the chroot jail in /var/spool/postfix/etc differ from the files in /etc. Just restart the postfix service and these files will be copied into the jail. |
| /var/log/mail.log | amavis[677]: (00677-01) Clam Antivirus-clamd FAILED - unknown status: /var/lib/amavis/amavis-20040717T011641-00677/parts: Can't access the file ERROR\n | You probably did not run "adduser clamav amavis". |
In some cases it may happen that Postfix cannot even read from the MySQL database. If you suspect this you may want to take a look at the /var/log/mysql.log file. It contains all SQL queries to the database..
A lot of smart users can be found on the IRC channel #postfix in the freenode.net network. You are invited to join us. I usually attend there as "ChrisH". Please do not message me privately. Just join the channel and ask your question as precisely as possible. And though I am flattered that so many people use my tutorial I cannot guarantee any reaction times if you send me an email.
If you are looking for other tutorials on related topics you may try these links:
Christoph Haas (last change: 17.07.2004 ) ( 275 hits since 25.6.2007 )