For now, just start with the README file and follow the directions in the INSTALL file included with the source!
This is basically your POP server. This server needs lots of disk space to store the incoming mail. Here is where you would filter out spam. Given a message sent from friend@hisdomain.com to you@yourdomain.com, here is the roadmap:
| DNS visibility | Can your friend reach see your mail server? On hisdomain.com:nslookupIf the "MX" record with the lowest number points to your mailserver, say mail.yourdomain.com, then you're fine. Next, make sure: nslookup mail.yourdomain.compoints to the IP address of your mailserver. If either of these fails, your domain is not properly registered or configured. Read up on DNS :) |
| IP reachability | Can your friend reach your mail server? On hisdomain.com:ping mail.yourdomain.comIf you get a reply, you're fine. If not, you probably have either a cabling or a routing problem. |
| IP filtering | Is your friend's IP permitted to send you mail? Assuming your SMTP daemon on mail.yourdomain.com is running in the form of:tcpserver -c 600 -x /etc/tcp.smtp.cdb -u 1002 -g 1001 0 smtp qmail-smtpdlook in /etc/tcp.smtp. If he's blocked (such as "147.46.59.226:deny"; "man tcprules" for details) then he will never get mail through to you from that machine. |
| Receiving Domains | Is mail to yourdomain.com being accepted by qmail? Look in:/var/qmail/control/rcpthostsyourdomain.com must be listed there if you want qmail to accept mail for that domain. |
| Locals and VirtualDomains | Besides rcpthosts, your domain must be listed in one of the following:/var/qmail/control/locals"man qmail-send" for details and syntax. If using a virtualdomains entry such as: yourdomain.com:yourdomain-comqmail will translate the destination email address as follows: From: you@yourdomain.comThat will be the "Delivered To:" header. From now on, everything after the "@" is ignored. This is the "local" part of the email address. |
| Recipient | Is there a recipient defined that matches the local part? Look in:/var/qmail/users/assign"man qmail-users" for details and syntax. Basically, look for a line beginning with: =yourdomain-com-you:If it exists, this person will receive the message. If it doesn't exist, look for a line beginning with: +yourdomain-com:or a right-truncated form of "yourdomain-com"; this "wildcard" person will receive the message. If neither exists, the message will bounce back to the sender. |
| Home Directory | Does the recipient have a home directory with valid permissions? Given an /var/qmail/users/assign entry of the form:=yourdomain-com-you:popuser:888:888:/u1/qmail/popboxes/yourdomain-com/you:::
(or a wildcard variant), mail to recipient "yourdomain-com-you" will be delivered to the directory: /u1/qmail/popboxes/yourdomain-com/you/Permissions for this home directory that look like the following seem to work for me, although I don't think this matters too much since qmail-lspawn, the local delivery man, runs as root:drwxr-xr-x 3 popuser popuser 512 Jul 6 02:12 you |
| Mail Box | Does the recipient have a valid Mail Box? Given that you've chosen to use Maildir rather than Mailbox for your qmail installion ("man maildir" for details), you must create the mail box by running the following command from their home directory:/var/qmail/bin/maildirmake MaildirThe following permissions work well on this directory and all the subdirectories it creates, although, again, I don't think this matters too much since qmail-lspawn runs as root:drwx------ 5 popuser popuser 512 Jul 6 02:12 Maildir |
| .qmail | Does the recipient have a .qmail file with valid permissions and syntax? Given that your qmail installion is using Maildir rather than Mailbox, a .qmail file of some variety is required ("man dot-qmail" for details). Create an new file with a single entry:/u1/qmail/popboxes/yourdomain-com/you/Maildir/(don't forget the trailing "/"!) The following permissions on .qmail seem to work well for me: -rw-r--r-- 1 popuser popuser 67 Jul 6 02:12 .qmailIf using a "wildcard" recipient (see Recipient section above), the only difference is in the name of the .qmail file. Given the wildcard recipient entry "+yourdomain-com:", all mail to "yourdomain.com" will come to this directory. To put yours in its mail box properly, you need to create a .qmail file of the name: .qmailyouOr, to put all mail delivered to this recipient in a single mail box, create a .qmail file of the name: .qmaildefault |
| Message! | If the message delivered successfully, you'll see a file under the directory:/u1/qmail/popboxes/yourdomain-com/you/Maildir/new/The file will have attributes similar to: -rw------- 1 popuser popuser 1997 Sep 22 22:02 938052158.9268.mail.yourdomain.comRead the message with a command like "more *". After the message is read by a POP server, if it's "left on the server", it will move under the "cur" directory, and have attributes like: -rw------- 1 popuser popuser 859 Aug 3 12:57 933699469.71176.mail.yourdomain.com:2,Congratulations! You've got mail! |
This is your SMTP server. Here is where you block access to SMTP based on IP address to prevent being used as an open relay for spammers. Let's call this machine smtp.yourdomain.com. Given a message sent from you@yourdomain.com to friend@hisdomain.com, here is the roadmap:
| DNS visibility (local) | Can you see your SMTP server? From your PC:nslookup smtp.yourdomain.comDoes it return the IP address of smtp.yourdomain.com? It should. Otherwise, your domain is not properly registered or configured. Read up on DNS :) |
| IP reachability (local) | Can you reach your SMTP server? From your PC:ping smtp.yourdomain.comIf you get a reply, you're fine. If not, you have a networking problem. Could be either a cabling or a routing problem. |
| IP filtering | Is the IP address of your PC permitted to relay (ie, send) mail through smtp.yourdomain.com? Assuming your SMTP daemon on smtp.yourdomain.com is running in the form of:tcpserver -c 600 -x /etc/tcp.smtp.cdb -u 1002 -g 1001 0 smtp qmail-smtpdlook in /etc/tcp.smtp (on smtp.yourdomain.com). If your PC hasn't been given explicit relay privileges (such as "249.141.79.:allow,RELAYCLIENT="" "; "man tcprules" for details) then you are not permitted to send mail through that machine. |
| Receiving Domains | As long as the RELAYCLIENT environment variable is set (as stated above), then /var/qmail/control/rcpthostsis ignored (on smtp.yourdomain.com), and you can send mail to whomever you like. |
| Locals and VirtualDomains | ??? |
| DNS/MX Overrides | If the file /var/qmail/control/smtphostsexists and contains an entry for hisdomain.com, qmail will not perform a DNS MX-lookup to figure out the mail server for hisdomain.com; it will use the one specified there, such as:.hisdomain.com:pop2.hisdomain.comOtherwise, qmail will perform a DNS/MX lookup. |
| DNS visibility (remote) | Can smtp.yourdomain.com see pop.hisdomain.com? From smtp.yourdomain.com:nslookupFind the "MX" record with the lowest number, say pop.hisdomain.com. That is the server qmail will deliver to. |
| IP reachability (remote) | Can smtp.yourdomain.com reach pop.hisdomain.com? From smtp.yourdomain.com:ping pop.hisdomain.comIf you get a reply, you're fine. If not, you (or the Internet) have a networking problem. |
| Log file | At this point, it's out of your hands! Assuming you started qmail (on smtp.yourdomain.com) asexec env - PATH="/var/qmail/bin:$PATH" qmail-start ./Mailbox splogger qmail(see /var/qmail/rc) logging info should be present in syslog. Now, check the file: /etc/syslog.conffor "mail.*" or similar entries. It will show you the path of where the log is located. A simple "success", such as: Sep 24 15:09:01 web5 qmail: 938200141.799326 delivery 368764: success: 245.188.156.200_accepted_message./Remote_host_said:_250_OK/means it's delivered as far as you can tell. If there are problems downstream, you may get a bounce message. |
This section assumes that you have successfully received an email message per the "Receiving Mail" section above. Your POP server is often the same as your server to which you Receive Mail (ie, mail.yourdomain.com). However, it will often have a separate TCP/IP "name", such as "pop.yourdomain.com".
| Message | If the message delivered successfully, you'll see a file under the directory:/u1/qmail/popboxes/yourdomain-com/you/Maildir/new/The file will have attributes similar to: -rw------- 1 popuser popuser 1997 Sep 22 22:02 938052158.9268.mail.yourdomain.comWe'll now try to retrieve the message via POP. |
| DNS visibility | Can you see your POP server? From your PC:nslookup pop.yourdomain.comDoes it return the IP address of pop.yourdomain.com? It should. If not, your domain is not properly registered or configured. Read up on DNS :) |
| IP reachability | Can you reach your POP server? From your PC:ping pop.yourdomain.comIf you get a reply, you're fine. If not, you have a networking problem that is probably related to either cabling or routing. |
| IP filtering | Is the IP address of your PC permitted to pop (ie, retrieve) mail from pop.yourdomain.com? Assuming your POP daemon on pop.yourdomain.com is running in the form of:tcpserver -c 600 -x /etc/tcp.pop.cdb -u 1002 -g 1001 0 pop3 qmail-popup `hostname` /bin/checkpassword qmail-pop3d ./Maildirlook in /etc/tcp.pop (on pop.yourdomain.com). If your PC hasn't been given explicit privileges (such as "249.141.79.:allow "; "man tcprules" for details) then you are not permitted to pop mail from that machine. Fortunately, most people run POP without the "-x /etc/tcp.pop.cdb" part, since POP has its own authentication method, in which case you don't have to worry about IP Filtering. |
| Telnet | From this point on, can your email program and do all your debugging from Telnet; it's easier to figure out what's going on. From your PC prompt, run:telnet pop.yourdomain.com 110If all of the above stuff is working properly, you will get a response such as: +OK <17435.938463719@pop.yourdomain.com>If not, check your /etc/services file for the port entry for POP3; it should be 110. Also, restart POP via tcpserver as above, but don't "background" it. Also, add the "-v" option. It will give helpful debugging info. Finally, you might want to turn on "Local Echo" in your telnet program's settings since POP will not echo (ie, show you) anything you type. |
| Authentication | Here's where the variety begins. qmail lets you use any authentication module you like at this point. The standard "checkpassword" add-on to qmail is the default. Personally, I use the version by Pedro Melo that offers CDB support. Look back at your command line:tcpserver -c 600 -u 1002 -g 1001 0 pop3 qmail-popup `hostname` /bin/checkpassword qmail-pop3d ./MaildirIn this case, /bin/checkpassword is what you're using. You may have specified at compile time where the password file would be (and now is) located on the disk. |
| POP Id | At this point, the next thing to type is:USER youand then hit [ENTER]. Regardless of whether the user "you" exists, it will come back with the reponse: +OK |
| POP Password | Then type:PASS yourpass(where "yourpass" is your POP password) and then hit [ENTER]. At this point, "checkpassword" takes over to authenticate, in which case you will get one of two possible responses: +OKmeans that you authorized successfully. (In this case, you can skip right down to the "STAT" step below). Otherwise, you will get: -ERR authorization failedIn case of the latter, it means that something failed. Typically, either the POP id doesn't exist or the password isn't correct for that id. To confirm the username, look in the password file. It might be found at: /var/qmail/users/poppasswdEach line has one entry. The first token on each line is the POP Id, and the second is the encrypted password. The poor man's way to create an encrypted password is to set it via Unix' "passwd" command on a regular Unix account, and cut-and-paste it into this file from /etc/passwd or /etc/shadow. Assuming the name and password is correct, you can move on. |
| Home Directory Existence & Permissions | If you followed the above direction regarding "Receiving Mail", you shouldn't have to adjust anything here regarding the Home Directory or below, regarding the Mail Box. But just to reiterate, the following permissions work well:drwxr-xr-x 3 popuser popuser 512 Jul 6 02:12 youNote that I use the "Single-UID" approach, so that rather than authenticating against /etc/passwd, all internal popping is carried out by a single, internal user, popuser. This user needs to have an entry such as:popuser:*:888:888:One Account for all POP Clients:/home/popuser:/bin/sh |
| Mail Box Existence & Permissions | The following permissions work well on this directory and all the subdirectories below it:drwx------ 5 popuser popuser 512 Jul 6 02:12 Maildir |
| STAT | Hey, if you've gotten this far, congrats! The end is in sight. In your POP session, simply type:STATand then hit [ENTER]. If you get a reply resembling: +OK 0 0then you have no new messages in your mailbox. However, if you get a reply such as: +OK 4 5138then you have 4 new messages in your mailbox totalling 5138 bytes in size. |
| LIST | If you see at least one new message via STAT, then you have succeeded and can quit. But since you've gotten this far, you might as well milk this a bit more. If you follow the above commands by typing:LISTand then hit [ENTER], POP will enumerate your messages and show the size of each in bytes, as follows: +OK |
| TOP | If you then want to see the contents of the message to confirm that this was, indeed, the test message you are seeking, then type:TOP Nand then hit [ENTER], where "N" is the number of the message from the LIST command that you want to see. The message will then scroll by! |
email Dave with corrections and suggestions.
Q-Cards are copyright (c) 1999-2021, Dave Kitabjian