By :  John Stile
Title:  An overview of Qmail and vpopmail --->
===========================================================================
  Qmail was writen by Dan Bernstein <http://cr.yp.to/djb.html> to make a mailserer that was secure, 
modular, reliable, easy to configure, and efficent. 

  Qmail differs from sendmail in that it uses several non-root users, who run small simple programs, that create small
files, representing a message's stage of delivery.  

Below I have noted:
	the qmail user accounts and function, 
	file structure, progrmas, and configuration files, what they do.  
	the delivery process, and 
	the instalation process + vpopmail (non /etc/passwd accounts, and virtual domains)

Inspecting the home directories, and you will see that it is shared. 
How ever, if one system account is compromised, the entire mail system is not.  
#------------------------
Main user accounts for qmail:
#--------------------------------------------------------------------------
Account	UID	 GID		Description				HomeDir		Shell
#--------------------------------------------------------------------------
alias		nofiles	 nofiles		non-real users				/var/qmail/alias		/bin/bash
qmaild		qmail	 nofiles		daemon account 			/var/qmail		/bin/bash
qmaill		510	 nofiles		logging account - runs splogger		/var/qmail		/bin/bash
qmailp		511	 nofiles		password account - runs qmail-clean	/var/qmail		/bin/bash
qmailq		512	 qmail		queue user account - runs uqmail-clean	/var/qmail		/bin/bash
qmailr		513	 qmail		remote user account - runs qmail-rspawn /var/qmail		/bin/bash
qmails		514	 qmail		send user account - runs qmail-send 	/var/qmail		/bin/bash
#-------------------------------------------------------------------------

Qmail reads ".qmail-*" text files for aliasing mail to non real users, or forwarding to different programs.
Note: any user can create thier own .qmail-* files in their own directory.
The user alias has this default layout:
	 alias - mail for accounts that are not handled by a real user are handled by rules in .qmail-* files
	 	  in ~alias home directory
  	   	.qmail-postmaster  	<- people often mail errors or problems to these addresses.
		.qmail-help		<- ...
		.qmail-MAILER-DAEMON	<- ...
	 	.qmail-root   		<- root is not considered a real user account, it is 
	 	.qmail-default
		.qmail-what-ever-else	<- 
		The format in these files is quite simple:
		  Each delivery rule in the file is on one line.
#============================
#.qmail files
#============================
.qmail files exist in $HOME/ for users.
The file contains one command per line, contains a program that will act on the message.
Options:   # 		= comment
	   |		= pipe message into a program.
	   / or .	= deliver to user's mailbox (/Mailbox or /Maildir/)
	   &		= forward to 
	   address 	= forward to address	
#==========================================================================
The file structure of qmail is something to get used to, to understand where all your config files,
what the programs do, and files to check.

Since the home directoy is shared the file permissions must be correct or unpredictable errors will be encoutnerd.
The home directory and it's permissions are below.

|-- alias/				<- mail for accounts that are not handled by a real user are handled by rules in .qmail-* files
|  	|-- .qmail-postmaster  		<- people often mail errors or problems to these addresses.
|  	|-- .qmail-help			<- ...
|  	|-- .qmail-MAILER-DAEMON	<- ...
|  	|-- .qmail-root   		<- root is not considered a real user account, it is 
|  	|-- .qmail-default		
|  	|-- .qmail-what-ever-else	<- what ever else you want to alias.
|
|-- bin/  
|  	|--  bouncesaying*	<-Help- Appends an error to errored message and returns to sender (used in .qmail files).
|	|				i.e. |bouncesaying <error message> <program> [args] ]	
|	|				Bouncesaying feeds <program> email,
|	|				- Exit status 0, error is prepended, and the  message is bounced.					
|  	|--  condredirect*	<-Help- Redirects mail for one address to another (used in .qmail files).
|	|				i.e. |condredirect <newaddress> <program> [ args ]
|	|				Condredirect feeds <program> email,
|	|				- Exit status 0, mail is forwarded to <newaddress>
|	|				- Exit status 111, mail is tried again later.
|  	|--  datemail*	 	<-????- works with semdmail alias to date new messages with bin/predate
|  	|--  elq*		<-????- can't find reference or man pages
|  	|--  except*		<-Help- Changes the effective exit status of a program (used in .qmail files).
|	|				i.e. except <program> [ args ]	
|	|				- Exit status 0, changed to exit status 100
|	|				- Exit status 111, unchanged.
|	|				- Exit status anything else, changed to exit status 0
|  	|--  forward*		<-Help- Redirects mail for one address to another (used in .qmail files).
|	|				i.e. |forward <address>				
|  	|--  maildir2mbox*	<-Admn- Convert /Maildir/ mailbox to Mailbox for MUA compatability.
|	|				i.e.
|  	|--  maildirmake*	<-Admn- Create a new Maildir mailbox.
|	|				i.e. maildir <user name>
|  	|--  maildirwatch*	<-????-
|  	|--  mailsubj*		<-????-	
|  	|--  pinq*		<-????-
|  	|--  predate*		<-????- No docs. but I think it dates mail.
|  	|--  preline*		<-Help- Used for procmail and ELM filters and (used in .qmail files).
|	|				Prepends message with Delivered-To:, From:, Return-Path:
|  	| 				i.e. | preline [-dfr ] command
|	|				-d  <- Don't include Delivered-To:
|	|				-f  <- Don't include From:
|	|				-r  <- Don't include Return-Path:
|  	|--  qail*		<-????-
|  	|--  qbiff*		<-Helper- Writes to the consol when a new message is recieved (used in .qmail files).			
|  	|--  qmail-clean*	<-Core- Clears the mail in a dammaged state messages.
|  	|--  qmail-getpw*	<-????-
|  	|--  qmail-inject*	<-Core- Inserts mail into the queue.
|  	|--  qmail-local*	<-Core- Delivers mail to local accounts
|  	|--  qmail-lspawn*	<-Core- Scheduler for local mail delivery
|  	|--  qmail-newmrh*	<-Admn- 
|  	|--  qmail-newu*	<-Admn- Read the user/assign file, and create a new cdb database
|  	|--  qmail-pop3d*	<-Core- POP3 server program allowing access to Maildir mailboxes
|  	|--  qmail-popup*	<-Core- Checks user to password with POP or APOP autentiation.
|  	|--  qmail-pw2u*	<-Help- Uses /etc/passwd to creates the user/assign delivery control file
|  	|--  qmail-qmqpc*	<-Core- Sends messages diretly to a QMQP server for delvery.
|  	|--  qmail-qmqpd*	<-Core- Listens for mail over Quick Mail Queueing  Protocol  (QMQP).
|	|			  	 and deposits the message directly into the outgoing queue.
|  	|--  qmail-qmtpd*	<-Core- accepts QMTP connections (QMTP is Dan's replacement for SMTP)
|  	|--  qmail-qread*	<-Admn- Prints a detailed report of messages in the queue.
|  	|--  qmail-qstat*	<-Admn- Prints a report of the queue status (#pending delivery and # queued).
|  	|--  qmail-queue*	<-Core- Inserts mail into the queue (gets from qmail-inject and qmail-smtp)
|  	|--  qmail-remote*	<-Core- Delivers mail to remote accounts
|  	|--  qmail-rspawn*	<-Core- Scheduler for remote mail delivery
|  	|--  qmail-send*	<-Core- Processe the queued messages
|  	|--  qmail-showctl*	<-Admn- Dump of the current config files (runnin state of server).
|  	|--  qmail-smtpd*	<-Core- Listens for SMTP (port 25/tcp) connection requests.
|  	|--  qmail-start*	<-Core- Starts qmail process.
|  	|--  qmail-tcpok*	<-Help- Clears qmail-remote's timeout table. 
|	|				Mail is reprocessed as a new message in the queue.
|  	|--  qmail-tcpto*	<-Help- Lists all failed SMTP conneciton Timeouts.
|  	|--  qreceipt*		<-Help- Returns receipt to peope who send this account mail (used in .qmail files).
|  	|				i.e. |qreceipt <youraddress>
|	|				If mail arrives with a header, "Notice-Requested-Upon-Delivery-To, and 
|	|				the .qmail file has qreceipt <youraddress>, the sender will get a notice.
|  	|--  qsmhook*		
|  	|--  sendmail*		<-Core- mails uses sendmail for outgoing mail, so this is a wrapper to qmail-inject
|  	|--  splogger*		<-Core- logs the processing of mail
|  	|--  tcp-env*		
|
|-- boot/			root     qmail    
|	|-- 
|
|-- control/ 			Changes the behavior of qmail
|             |                                           For a full expalnation, see http://www.qmail.org/qmail-manual-html/man5/qmail-control.html
|	|-- me	 		<--bare minimum file, containing a FQDN for the local machine.
|
|-- doc/ 			<-- Docs on install, and configuration
|-- man/ 			<-- man pages for all of qmail 
|
|-- queue/			<-- this is where mail is processed
|	|-- bounce/		<-- files containing new mail responding to bounced mail.
|	|-- info/		<-- files containing From: and To:  fields for an email.
|	|-- intd/		<-- files conatining all header information for a mail.
|	|-- local/		<-- files contianing the To: fields for maild with local account destinations.
|	|-- lock/		<--  not sure.
|	|-- mess/		<-- files containing a copy of the origninal mail. It's name = the inode where the message is store.
|	|-- pid/			<-- files contianing the origninal message, with a long name for the message.
|	|-- remote/		<-- files containing To: fields for mail with remote account destinations. 
|	|-- todo/		<-- soft links to files in intd/
|
|-- rc*				<- starts qmail
|
|-- users/			root     qmail
	|--  assign		<-- ascii rules for handleing user/domain to files on the server
	|				must run qmail-newu after editing. Backup before editing.
	|--  cdb		<-- the compled version of the assign file.  
#==========================
#/var/qmail/users/assign
#==========================
	#  File is used to maps qmail addresses to Unix system accounts
	#  2 fromats, one with a +, one with a =
	#  First, mapping qmail address to user account.
	#   =address:user:uid:gid:directory:dash:extension:
	#  Second, mapping wilde cards to map lots of users to an address.
	#  +address:user:uid:gid:directory:dash:extention:
	examples:
	Map all mail for the domain stilen.com to a directory  under vopmail's home direcoty.
	 +stilen.com-:stilen.com:30002:30002:/home/vpopmail/domains/stilen.com:-::
	Map all mail for the domain  420worldwide.com to a different under vopmail's home direcoty.
	 +420worldwide.com-:420worldwide.com:30002:30002:/home/vpopmail/domains/420worldwide.com:-::
	Map all mail for ken@localhost to a directory under 
	=ken:ken:30002:30002:/home/ken:::
	 .  # <-  A single perioud marks end of the file, or it will not parse correctly.
#============================
#cdb file
#============================
   This is the binary db creaed with the qmail-newu command.
#============================
#Startup script
#============================
#!/bin/sh
export PATH=/var/qmail/bin:/bin:/usr/bin:$PATH
# if qmail is runing exit
[ -f /var/qmail/bin/qmail-start ] || exit 0
case "$1" in
	start	)
		echo -n "Starting qmail..."
		/bin/csh -cf `/var/qmail/rc &`
		exit 0
		;;
		
	stop	)
		echo -n "Stopping qmail..."
		/usr/bin/killall qmail-send
		;;	

	restart	)
		$0 stop
		$0 start
		;;	
	*	)
		echo -n "Usage: $0 {start|stop|restart}"
		exit 1
		;;
esac
exit 0
============================
/var/qmail/rc file
============================
#!/bin/sh

# Using splogger to send the log through syslog.
# Using qmail-local to deliver messages to ~/Mailbox by default.

exec env - PATH="/var/qmail/bin:$PATH" \
qmail-start ./Maildir/ splogger qmail
============================
 ======================================================
  The Qmail Queue porocess
======================================================
One can look at  messages in queue with the following command:  ls -alFR /var/qmail/queue/*/*/*
------------------------------------------------------
Qmail queue (/var/qmail/queue/) contains 8 directories:
 Pid/          (origmsg), 
  mess/       (inodeorig), 
   intd/      (headerinfo), 
   todo/      (lnkintd), 
    info/     (from), local(to), remote(to), 
     bounce/  (newmsg)
-------------------------------------------------------
APPLICATION: qmail-inject or qmail-smtpd
| 	deliver the message 
|	
|		message file is stored in: 
|		pid/<long name for message in queue>
V
APPLICATION: qmail-queue
|
|
| Insertion:
|	copy message to mess/, naming the file after its inode location on the disk.
|	(from this point on, the file names all relate to the messages location on the disk.)
|
|		message file is stored in:
|		pid/<long name for message in queue, with date,and time of delivery> 
|		mess/<inode>
|
| Storage: 
|	creat a file in intd/ of the same name from mess/
|
|		message file is stored in:
|		pid/<long name for message in queue> 
|		mess/<inode>
|		intd/<inode>			<<--empty
|
| Sequester Header:
|	copy headder info from the file in /mess to the file in /intd
|
|		message file is stored in:
|		pid/<long name for message in queue> 
|		mess/<inode>
|		intd/<inode>	#header information 		F<address>T<address>
V
APPLICATION: qmail-send
|
|
| Identify Recipiants:
|	 soft link in todo/ to the file in intd/ 
| 
| 		message file is stored in:
|		pid/<long name for message in queue> 
|		mess/<inode>
|		intd/<inode>            #header information			F<address>T<address>
|		todo/<inode> --> ../intd/<inode>			F<address>T<address>
| 
| 	 remove any files of the same name from info/ local/ and remote/
|	 
|	 	message file are cleared from:
|		info/ <inode>
|		local/<inode>
|		remote/<inode>
|	 
|	 copy sender info from file in todo/ to a file in info/
| 		message file is stored in:
|		pid/<long name for message in queue> 
|		mess/<inode>
|		intd/<inode>	#header information 		F<address>T<address>
|		todo/<inode> --> ../intd/<inode>
|
|	 copy recipiant info from file in todo/ to a file in local/ or remote/
|
| 		message file is stored in:
|		pid/<long name for message in queue> 
|		mess/<inode>
|		intd/<inode>	#header information 		F<address>T<address>
|		todo/<inode> --> ../intd/<inode>			F<address>T<address>
|		info/<inode>	#sender information 		F<address> 
|		local/<inode>	#recipiant information for local	T<address> 
|		remote/<inode>	#recipiant information for remote	T<address> 
|
| Delivery:
|	 Deliver the body of the file in mess/ to recipiants listed in files from local/ and /remote/
|
|--->APPLICATION: qmail-rspon ---> qmail-remote (verifys SMTP integrety and sends) ---> 
|--->APPLICATION: qmail-lspon 
|
V
|	 Return code will be:
|		DONE 		if successful or perminant failure.
|		NOT DONE	if temporary failure.
| Bounce:
|	 If the status is DONE due to a perminant failure, 
|	 a file is created in bounce/ with a bounce note in it.	 
|
| 		message file is stored in:
|		pid/<long name for message in queue> 
|		mess/<inode>
|		intd/<inode>	#header information 			F<address>T<address>
|		todo/<inode> --> ../intd/<inode>			F<address>T<address>
|		info/<inode>	#sender information 			F<address> 
|		local/<inode>	#recipiant information for local	T<address> 
|		remote/<inode>	#recipiant information for remote	T<address> 
|		bounce/<inode>  #recipinats
|
|	 The files are combined from bounce/<inode> and mess/<inode>, and reinserted into the queue. 
|
| 		message file is stored in:
|		pid/<long name for message in queue> 
|		mess/<inode>
|		intd/<inode>	#header information 			F<address>T<address>
|		todo/<inode> --> ../intd/<inode>			F<address>T<address>
|		info/<inode>	#sender information 			F<address> 
|		local/<inode>	#recipiant information for local	T<address> 
|		remote/<inode>	#recipiant information for remote	T<address> 
|		bounce/<inode>  #recipinats				Bounce note.
|		pid/<long name for new message in queue> 		Addressed to the sender of the original.
| Cleanup:
|	 When messages are maked as DONE, they are deleted in the following order:
|		local/<inode> and remote/<inode>
|		 bounce/<inode>
|		  info/<inode>
|		   mess/<inode>
V
APPLICATION: qmail-clean
|
|  every 36Hrs: find files that are older than 36 hours, (i.e. find ./intd ./mess -cmin +3780 -type f )
|		deletes intd/<inode>    (i.e. rm -rf `find /var/qmail/queue/intd/ -cmin +3780 -type f` )
|		deletes mess/<inode>	(i.e. rm -rf `find /var/qmail/queue/mess/ -cmin +3780 -type f` )
|		deletes pid/<inode>	(i.e. rm -rf `find /var/qmail/queue/pid/ -cmin +3780 -type f` )
V
===============================================================================================================
Quick install of 
# Backup the old stuff if you are doing an upgrade.
mkdir ../vpopmail_backup
 cp -Rp /home/vpopmail/bin ../vpopmail_backup
 cp -Rp /home/vpopmail/lib ../vpopmail_backup
 cp -Rp /home/vpopmail/include ../vpopmail_backup

tar -zxvpf vpopmail-4.9.10.tar.gz
cd vpopmail-4.9.10
 su
./configure --enable-roaming-users=y
            Current settings
           ---------------------------------------
 vpopmail directory = /home/vpopmail
                                uid = 30002
                              gid = 30002
         roaming users = ON
                user quota = OFF
           tcpserver file = /etc/tcp.smtp
        open_smtp file = /home/vpopmail/etc/open-smtp
              auth module = cdb
              auth logging = OFF
                  pop syslog = show only failure attempts
         default domain = 
==========================================
[root@mother vpopmail-4.9.10]#  make
[root@mother vpopmail-4.9.10]# make install-strip
====================
# I see something stragne here.
# /home/vpopmail/.bashrc sets the path to PATH=$PATH:$HOME/bin
#
#  The following 2 ls's show that the programs in /usr/bin are executed before
# the ones in the /home/vpopmail/bin.
####
#### So Im going to backup the old ones, 
####  and copy the new ones in.
####
#  Also note that the executables are differet sizes.
#
ls -alF /home/vpopmail/bin/
total 588
drwxr-xr-x    2 vpopmail vchkpw       4096 Apr 30 19:28 ./
drwxr-xr-x   12 vpopmail vchkpw       4096 Apr 30 19:25 ../
-rwxr-xr-x    1 vpopmail vchkpw      34880 Apr 30 19:28 clearopensmtp*
-rwxr-xr-x    1 vpopmail vchkpw      35424 Apr 30 19:28 vaddaliasdomain*
-rwxr-xr-x    1 vpopmail vchkpw      37024 Apr 30 19:28 vadddomain*
-rwxr-xr-x    1 vpopmail vchkpw      35904 Apr 30 19:28 vadduser*
-rwxr-xr-x    1 vpopmail vchkpw      38080 Apr 30 19:28 vchkpw*
-rwxr-xr-x    1 vpopmail vchkpw      37696 Apr 30 19:28 vconvert*
-rwxr-xr-x    1 vpopmail vchkpw      35008 Apr 30 19:28 vdeldomain*
-rwxr-xr-x    1 vpopmail vchkpw      41792 Apr 30 19:28 vdelivermail*
-rwxr-xr-x    1 vpopmail vchkpw      35072 Apr 30 19:28 vdeluser*
-rwxr-xr-x    1 vpopmail vchkpw       4740 Apr 30 19:28 vipmap*
-rwxr-xr-x    1 vpopmail vchkpw      34656 Apr 30 19:28 vmkpasswd*
-rwxr-xr-x    1 vpopmail vchkpw      37440 Apr 30 19:28 vmoduser*
-rwxr-xr-x    1 vpopmail vchkpw      35264 Apr 30 19:28 vpasswd*
-rwxr-xr-x    1 vpopmail vchkpw      36960 Apr 30 19:28 vpopbull*
-rwxr-xr-x    1 vpopmail vchkpw      35296 Apr 30 19:28 vsetuserquota*
-rwxr-xr-x    1 vpopmail vchkpw      37312 Apr 30 19:28 vuserinfo*

ls -laF /usr/bin/vpopbull /usr/bin/vpasswd /usr/bin/vdeluser /usr/bin/vadduser 
-rwxr-xr-x    1 root     root        56016 Apr 13  2000 /usr/bin/vadduser*
-rwxr-xr-x    1 root     root        37284 Apr 13  2000 /usr/bin/vdeluser*
-rwxr-xr-x    1 root     root        49648 Apr 13  2000 /usr/bin/vpasswd*
-rwxr-xr-x    1 root     root        26908 Apr 13  2000 /usr/bin/vpopbull*
==================================================================
# try to put the right executables in place.
cp /usr/bin/vpopbull /usr/bin/vpopbull.old
cp -f /home/vpopmail/bin/vpopbull /usr/bin/
cp /usr/bin/vpasswd /usr/bin/vpasswd.old
cp -f /home/vpopmail/bin/vpasswd /usr/bin/
cp /usr/bin/vdeluser /usr/bin/vdeluser.old
cp -f /home/vpopmail/bin/vdeluser /usr/bin/
cp /usr/bin/vadduser /usr/bin/vadduser.old
cp -f /home/vpopmail/bin/vadduser /usr/bin/
=================================================================
Courier IMAP
=================================================================
tar -zxvpf courier
cd courier	
# read imap/FAQ
# read INSTALL

CPPFLAGS="-I/usr/local/ssl/include"
LDFLAGS="-L/usr/local/ssl/lib"
export CPPFLAGS
export LDFLAGS
./configure 
make 
make check
#If make check fails, something is wrong, 
#and Courier-IMAP may not work for you reliably.
su
make install-strip
make install-configure 

#modify /usr/lib/courier-imap/etc/imapd
# only use vpopmail module i.e. AUTHMODULES="authvchkpw"

sed 's/^AUTHMODULES/#AUTHMODULES/' imapd > imapd.new
mv imapd imapd.orig
mv imapd.new imapd
cat <<- EOT >> imapd
AUTHMODULES="authvchkpw"
EOT
-------------------------
 Startup/shutdow Scripts
-------------------------
/usr/lib/courier-imap/libexec/imapd.rc start
/usr/lib/courier-imap/libexec/imapd.rc stop

-------------------------
  IMAP over SSL
-------------------------
 #edit the config file
 vi /usr/lib/courier-imap/lib/imapd-ssl 
 
#start it up.
 /usr/lib/courier-imap/libexec/imapd-ssl.rc
 
 #X.509 certificat must be in:
 /usr/lib/courier-imap/share/imapd.pem
 
 # This command will generate a self-signed cert if you can't steal one.
 # /usr/lib/courier-imap/share/mkimapdcert

 # This file sets several parameters for the authdaemond process.  
 ##  /usr/lib/courier-imap/etc/authdaemonrc 
 ## i dont have it.