chiark - git - mdw - qmail/blob - INSTALL

   1 SAVE COPIES OF YOUR OUTGOING MAIL! Like any other piece of software (and
   2 information generally), the qmail system comes with NO WARRANTY. It's
   3 much more secure and reliable than sendmail, but that's not saying much.
   4
   5
   6 Things you have to decide before starting:
   7
   8 * The qmail home directory, normally /var/qmail. To change this
   9 directory, edit conf-qmail now.
  10
  11 * The names of the qmail users and the qmail groups. To change these
  12 names, edit conf-users and conf-groups now.
  13
  14
  15 Installation steps that won't interfere with sendmail:
  16
  17  1. Create the qmail home directory:
  18        # mkdir /var/qmail
  19  2. Read INSTALL.ids. You must set up the qmail group and the qmail
  20     users before compiling the programs.
  21  3. Compile the programs:
  22        # make
  23  4. Create the formatted man pages, *.0:
  24        # make man
  25  5. Create the qmail directory tree:
  26        # make setup
  27  6. Run instcheck to make sure it doesn't print any warnings:
  28        # make check
  29  7. Read INSTALL.ctl and FAQ. Minimal survival command:
  30        # ./qmail-config
  31  8. Read INSTALL.alias. Minimal survival command:
  32        # (cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root)
  33        # chmod 644 ~alias/.qmail*
  34  9. Read INSTALL.mbox.
  35 10. Read qmail-upgrade.0. This is what your users will need to know
  36     about the switch from sendmail to qmail.
  37
  38
  39 Pre-upgrade tests:
  40
  41 11. Enable deliveries of messages injected into qmail:
  42        # env - PATH="/var/qmail/bin:$PATH" \
  43        qmail-start ./Mailbox splogger qmail &
  44     Make sure to include the ./ in ./Mailbox.
  45 12. Look for a
  46             qmail: running
  47     line in syslog. qmail-send always prints either ``cannot start'' or
  48     ``running''. (The big number is a splogger timestamp.)
  49 13. Do a ps and look for the qmail daemons. There should be four of
  50     them, all idle: qmail-send, running as qmails; qmail-lspawn, running
  51     as root; qmail-rspawn, running as qmailr; and qmail-clean, running
  52     as qmailq. You will also see the splogger process.
  53 14. Local-local test: Send yourself an empty message. (Replace ``me''
  54     with your username. Make sure to include the ``to:'' colon.)
  55        % echo to: me | /var/qmail/bin/qmail-inject
  56     The message will show up immediately in ~/Mailbox, and syslog will
  57     show something like this:
  58             qmail: new msg 53
  59             qmail: info msg 53: bytes 246 from <me@domain> qp 20345 uid 666
  60             qmail: starting delivery 1: msg 53 to local me@domain
  61             qmail: delivery 1: success: did_1+0+0/
  62             qmail: end msg 53
  63     (53 is an inode number; 20345 is a process ID; your numbers will
  64     probably be different.)
  65 15. Local-error test: Send a message to a nonexistent local address.
  66        % echo to: nonexistent | /var/qmail/bin/qmail-inject
  67             qmail: new msg 53
  68             qmail: info msg 53: bytes 246 from <me@domain> qp 20351 uid 666
  69             qmail: starting delivery 2: msg 53 to local nonexistent@domain
  70             qmail: delivery 2: failure: No_such_address.__#5.1.1_/
  71             qmail: bounce msg 53 qp 20357
  72             qmail: end msg 53
  73             qmail: new msg 54
  74             qmail: info msg 54: bytes 743 from <> qp 20357 uid 666
  75             qmail: starting delivery 3: msg 54 to local me@domain
  76             qmail: delivery 3: success: did_1+0+0/
  77             qmail: end msg 54
  78     You will now have a bounce message in ~/Mailbox.
  79 16. Local-remote test: Send an empty message to your account on another
  80     machine.
  81        % echo to: me@wherever | /var/qmail/bin/qmail-inject
  82             qmail: new msg 53
  83             qmail: info msg 53: bytes 246 from <me@domain> qp 20372 uid 666
  84             qmail: starting delivery 4: msg 53 to remote me@wherever
  85             qmail: delivery 4: success: 1.2.3.4_accepted_message./...
  86             qmail: end msg 53
  87     There will be a pause between ``starting delivery'' and ``success'';
  88     SMTP is slow. Check that the message is in your mailbox on the other
  89     machine.
  90 17. Local-postmaster test: Send mail to postmaster, any capitalization.
  91        % echo to: POSTmaster | /var/qmail/bin/qmail-inject
  92     Look for the message in ~alias/Mailbox.
  93 18. Double-bounce test: Send a message with a completely bad envelope.
  94        % /var/qmail/bin/qmail-inject -f nonexistent
  95        To: unknownuser
  96        Subject: testing
  97
  98        This is a test. This is only a test.
  99        %
 100     (Use end-of-file, not dot, to end the message.) Look for the double
 101     bounce in ~alias/Mailbox.
 102 19. Group membership test:
 103        % cat > ~me/.qmail-groups
 104        |groups >> MYGROUPS; exit 0
 105        % /var/qmail/bin/qmail-inject me-groups < /dev/null
 106        % cat ~me/MYGROUPS
 107     MYGROUPS will show your normal gid and nothing else. (Under Solaris,
 108     make sure to use /usr/ucb/groups; /usr/bin/groups is broken.)
 109
 110
 111 Upgrading from sendmail to qmail:
 112
 113 20. Read INSTALL.boot. You must replace the sendmail invocation in your
 114     boot scripts with an appropriate qmail invocation.
 115 21. Kill the sendmail daemon. You should first kill -STOP the daemon; if
 116     any children are running, you should kill -CONT, wait, kill -STOP
 117     again, and repeat ad nauseam. If there aren't any children, kill
 118     -TERM and then kill -CONT.
 119 22. Replace sendmail with a link to qmail's ``sendmail'' wrapper:
 120        # mv /usr/lib/sendmail /usr/lib/sendmail.bak
 121        # ln -s /var/qmail/bin/sendmail /usr/lib/sendmail
 122 23. Set up qmail-smtpd in /etc/inetd.conf (all on one line):
 123             smtp stream tcp nowait qmaild /var/qmail/bin/tcp-env
 124             tcp-env /var/qmail/bin/qmail-smtpd
 125     Also comment out comsat in /etc/inetd.conf.
 126 24. Reboot. (Or kill -HUP your inetd and make sure the qmail daemons
 127     are running.)
 128 25. Try to flush the sendmail queue:
 129        # /usr/lib/sendmail.bak -q
 130     You can safely run sendmail.bak -q (or even sendmail.bak -q15m)
 131     while qmail is running. Do this until the sendmail queue is empty.
 132     This may take several days.
 133 26. Disable all the sendmail and binmail programs in your system. The
 134     safest approach is to chmod 0 everything. Some locations to check:
 135     /usr/sbin/sendmail, /usr/lib/sendmail.bak, /usr/lib/sendmail.mx,
 136     /bin/mail, /usr/libexec/mail.local.
 137 27. Make sure that ``mail'' still invokes a reasonable mailer. Under
 138     SVR4 you may want to link mail to mailx.
 139
 140
 141 Post-upgrade tests (can be done immediately after step 24):
 142
 143 28. SMTP server test: Forge some mail locally via SMTP.
 144        % telnet 127.0.0.1 25
 145        Trying 127.0.0.1...
 146        Connected to 127.0.0.1.
 147        Escape character is '^]'.
 148        220 domain ESMTP
 149        helo dude
 150        250-domain
 151        250-PIPELINING
 152        250 8BITMIME
 153        mail <me@domain>
 154        250 ok
 155        rcpt <me@domain>
 156        250 ok
 157        data
 158        354 go ahead
 159        Subject: testing
 160
 161        This is a test.
 162        .
 163        250 ok 812345679 qp 12345
 164        quit
 165        221 domain
 166        Connection closed by foreign host.
 167        %
 168     Look for the message in your mailbox.
 169 29. Remote-local test: Send yourself some mail from another machine.
 170 30. Remote-error test: I think you can figure this one out.
 171 31. UA test: Try sending mail, first to a local account, then to a
 172     remote account, with your normal user agent.
 173 32. Remote-postmaster test: Send mail from another machine to
 174     PoStMaStEr@domain. Look for the message in ~alias/Mailbox.
 175
 176
 177 That's it! To report success:
 178        % ( echo 'First M. Last'; cat `cat SYSDEPS` ) \
 179          | mail djb-qst@koobera.math.uic.edu
 180 Replace First M. Last with your name. If you have questions about qmail,
 181 contact qmail@pobox.com.