SAVE COPIES OF YOUR OUTGOING MAIL! Like any other piece of software (and
information generally), the qmail system comes with NO WARRANTY. It's
much more secure and reliable than sendmail, but that's not saying much.


Things you have to decide before starting:

* The qmail home directory, normally /var/qmail. This directory must be
a local directory, not shared among machines; it is where qmail queues
all mail messages. (To change this directory, edit conf-home.h now.)

* The names of the qmail users and the qmail groups: normally alias,
qmaild, qmailq, qmailr, qmails, qmail, and nofiles. The qmail system is
heavily partitioned for security; it does almost nothing as root. (To
change any of these names, edit conf-user.h now.)


Installation steps that won't interfere with sendmail:

 1. Create the formatted man pages, *.0:
       # make man
 2. Create the qmail home directory:
       # mkdir /var/qmail; chmod 755 /var/qmail
 3. Read INSTALL.ids. You must set up the qmail group and the qmail
    users before compiling the programs.
 4. Compile the programs:
       # make
 5. Create the qmail directory tree:
       # ./qmail-setup
 6. Run qmail-check to make sure it doesn't print any warnings:
       # ./qmail-check
 7. Read INSTALL.ctl and HOWTO. Minimal survival command:
       # ./qmail-makectl
 8. Read INSTALL.alias. Minimal survival command:
       # (cd ~alias; touch .qmailpostmaster .qmailmailer-daemon .qmailroot)
       # chmod 644 ~alias/.qmail*
 9. Read INSTALL.mbox.
10. Read qmail-upgrade.0. This is what your users will need to know
    about the switch from sendmail to qmail.


Pre-upgrade tests:

11. Enable deliveries of messages injected into qmail:
       # /var/qmail/bin/qmail-start | logger -p mail.info -t qmail &
12. Look for a
            qmail: running
    line in syslog. qmail-send always prints either ``cannot start'' or
    ``running''.
13. Do a ps and look for the qmail daemons. There should be four of
    them, all idle: qmail-send, running as qmails; qmail-lspawn, running
    as root; qmail-rspawn, running as qmailr; and qmail-clean, running
    as qmailq. You will also see the logger process.
14. Local-local test: Send yourself an empty message. (Replace ``me''
    with your username. Make sure to include the ``to:'' colon.)
       % echo to: me | /var/qmail/bin/qmail-inject
    The message will show up immediately in ~/Mailbox, and syslog will
    show something like this:
            qmail: new msg 53 
            qmail: info msg 53: bytes 246 from <me@domain> 
            qmail: starting delivery 1: msg 53 to local me@domain 
            qmail: delivery 1: success 
            qmail: end msg 53 
    (53 is an inode number; your number will probably be different.)
15. Local-error test: Send a message to a nonexistent local address.
       % echo to: nonexistent | /var/qmail/bin/qmail-inject
            qmail: new msg 53 
            qmail: info msg 53: bytes 246 from <me@domain> 
            qmail: starting delivery 2: msg 53 to local nonexistent@domain
            qmail: delivery 2: failure 
            qmail: end msg 53 
            qmail: new msg 54 
            qmail: info msg 54: bytes 743 from <> 
            qmail: starting delivery 3: msg 54 to local me@domain
            qmail: delivery 3: success 
            qmail: end msg 54 
    You will now have a bounce message in ~/Mailbox.
16. Local-remote test: Send an empty message to your account on another
    machine.
       % echo to: me@wherever | /var/qmail/bin/qmail-inject
            qmail: new msg 53 
            qmail: info msg 53: bytes 246 from <me@domain>
            qmail: starting delivery 4: msg 53 to remote me@wherever
            qmail: delivery 4: success 
            qmail: end msg 53 
    There will be a pause between ``starting delivery'' and ``success'';
    SMTP is slow. Check that the message is in your mailbox on the other
    machine.
17. Local-postmaster test: Send mail to postmaster, any capitalization.
       % echo to: POSTmaster | /var/qmail/bin/qmail-inject
    Look for the message in ~alias/Mailbox.
18. Double-bounce test: Send a message with a completely bad envelope.
       % /var/qmail/bin/qmail-inject -f nonexistent
       To: unknownuser
       Subject: testing

       This is a test. This is only a test.
       %
    (Use end-of-file, not dot, to end the message.) Look for the double
    bounce in ~alias/Mailbox.
19. Group membership test:
       % cat > ~me/.qmail-groups
       |groups >> MYGROUPS; exit 0
       % /var/qmail/bin/qmail-inject me-groups < /dev/null
       % cat ~me/MYGROUPS
    MYGROUPS will show your normal gid and nothing else.


Upgrading from sendmail to qmail:

20. Comment out
            sendmail -bd -q15m
    in /etc/rc or /etc/init.d/sendmail, and replace it with
            /var/qmail/bin/qmail-start | logger -p mail.info -t qmail &
21. Kill the sendmail daemon. You should first kill -STOP the daemon; if
    any children are running, you should kill -CONT, wait, kill -STOP
    again, and repeat ad nauseam. If there aren't any children, kill
    -TERM and then kill -CONT.
22. Replace sendmail with a link to qmail's ``sendmail'' wrapper:
       # mv /usr/lib/sendmail /usr/lib/sendmail.bak
       # ln -s /var/qmail/bin/sendmail /usr/lib/sendmail
23. Set up qmail-smtpd in /etc/inetd.conf (all on one line):
            smtp stream tcp nowait qmaild /var/qmail/bin/tcp-env
	    tcp-env /var/qmail/bin/qmail-smtpd
    Also comment out comsat in /etc/inetd.conf.
24. Reboot. (Or kill -HUP your inetd and make sure the qmail daemons
    are running.)
25. Try to flush the sendmail queue:
       # /usr/lib/sendmail.bak -q
    You can safely run sendmail.bak -q (or even sendmail.bak -q15m)
    while qmail is running. Do this until the sendmail queue is empty.
    This may take several days.
26. Disable all the sendmail and binmail programs in your system. The
    safest approach is to chmod 0 everything. Some locations to check:
    /usr/sbin/sendmail, /usr/lib/sendmail.bak, /usr/lib/sendmail.mx,
    /bin/mail, /usr/libexec/mail.local.
27. Make sure that ``mail'' still invokes a reasonable mailer. Under
    SVR4 you may want to link mail to mailx.


Post-upgrade tests (can be done immediately after step 24):

28. SMTP server test: Forge some mail locally via SMTP.
       % telnet 127.0.0.1 25
       Trying 127.0.0.1...
       Connected to 127.0.0.1.
       Escape character is '^]'.
       220 domain
       helo dude
       250 domain
       mail <me@domain>
       250 ok
       rcpt <me@domain>
       250 ok
       data
       354 go ahead
       Subject: testing
       
       This is a test.
       .
       250 ok
       quit
       221 domain
       Connection closed by foreign host.
       %
    Look for the message in your mailbox.
29. Remote-local test: Send yourself some mail from another machine.
30. Remote-error test: I think you can figure this one out.
31. UA test: Try sending mail, first to a local account, then to a
    remote account, with your normal user agent.
32. Remote-postmaster test: Send mail from another machine to
    PoStMaStEr@domain. Look for the message in ~alias/Mailbox.


That's it! If you want to report success:
       % cat `cat SYSDEPS` | mail djb-qst@koobera.math.uic.edu
