-------------------------------------------------------------------------
dirqmail patch - README file
Pawel Foremski <pjf@asn.pl> 2004-2005
-------------------------------------------------------------------------

1.  What`s that?

  dirqmail is a qmail patch which adds simple and fast virtual users
  support based on directories.

  dirqmail puts users in /var/qmail/mail/<domain>/<login> directories,
  so for instance if /var/qmail/mail/example.org/example directory
  exists, qmail will treat example.org as a local domain, will accept
  mail for it via SMTP and QMTP daemons and will deliver mail to
  example@example.org as 'alias' user using
  /var/qmail/mail/example.org/example as the home directory.


2.  Features.

  * simple - you can just "see" and administer your domains and users
  from the command line or any file manager

  * fast - checking for user of domain existence is just stat'ing the
  correct directory

  * atomic - all changes do not need any restarts/etc - everything just
  work in the "real-time"

  * simple and fast aliases - just use symbolic links!

  * works out of the box - just create /var/qmail/mail/domain.org/user
  to create user@domain.org user - permissions, ownership and Maildir
  creation will be handled automatically

  * does not remove any of qmail features - dirqmail can coexist with
  any existent qmail installation - for example you can have some
  domains and users handled by system users (using /etc/passwd), some by
  qmail-users (/var/qmail/users), some by vpopmail and some by dirqmail
  (/var/qmail/mail)

  * includes patch for checkpassword with support for POP3 (PASS and APOP) and
  SMTP (LOGIN, PLAIN, CRAM-MD5) - both for Krzysztof Dabrowski's and
  Erwin Hoffmann's SMTP AUTH patches


3.  How it works.

  dirqmail makes changes to the following qmail programs:

    - qmail-smtpd and qmail-qmtpd (in fact rcpthosts.c): while checking
    if the envelope recipient domain is in allowed rcpthosts, check
    whether mail/<domain> directory exists before looking at
    control/rcpthosts entries - if it exists, treat the domain as
    allowed to be relayed through this mail server

      NOTE: you still need control/rcpthosts file (even empty) if you
      don't want to be an open-relay

    - qmail-send: while deciding whether the message should be
    considered local or remote, check if mail/<domain> directory exists
    before looking at control/locals entries - if it exists, treat
    message as local

    - qmail-lspawn: while searching for the recipient user in the
    system, check whether mail/<domain>/<user> directory exists before
    looking at qmail-users and system users (/etc/passwd); if it exists:

      * set correct permissions if needed (owner: alias, group: nofiles,
      mode: 0700) - you can disable this by defining NOAUTOMAILDIR

      * perform delivery as the alias user (with it's UID and GID) and
      /var/qmail/mail/<domain>/<user> as the home directory

    if such directory does not exist, try the same with
    mail/<domain>/alias; of course if this fails too, qmail will
    continue with the standard procedure, if you want not to check for
    system users, compile qmail with -DNOSYSPWD

    - qmail-local - while doing a maildir delivery, try to create a
    maildir folder if it does not exist before triggering a temporary
    error - you can disable this by defining NOAUTOMAILDIR

    - qmail-pop3d - while getting mail from a maildir, try to create it
    if it does not exist before triggering an error - you can disable
    this by defining NOAUTOMAILDIR


4.  Passwords / Authentication.

  You can implement any checkpassword program for your installation if
  you want, but the dirqmail package bundles with a checkpassword 0.90
  patch which supports PASS, APOP, LOGIN, PLAIN and CRAM-MD5
  authentication methods. It needs _plain_ passwords in files called
  "password" in users' home directories to work correctly. The patch
  does not remove any of original checkpassword functionality.

  If you need to use dirqmail with other system with own checkpassword
  implementation (like vpopmail), consider using multichkpwds by Andreas
  Aardal Hanssen.

  If you want to use SMTP AUTH, you need to apply such patch first
  (Dabrowski's or Hoffmann's one) and then dirqmail-smtpauth.diff.

  To disable checks of system users, compile checkpassword with
  -DNOSYSPWD.


5.  Important notes.

  * you still need control/rcpthosts file (even empty) if you don't want
  to be an open-relay

  * if you're using bundled checkpassword patch, don't crypt user
  passwords and authenticate using full username, e.g. login@domain.com

  * use -DNOSYSPWD (add in conf-cc) to disable checks for system users

  * user and domain names mustn't contain "/" and ".." strings

  * if you want ext_todo with dirqmail, first apply ext_todo and then
  dirqmail-ext_todo


6.  Downloads, support, forums.

  See project page on SourceForge.


7.  Related.

  * dqd is a dirqmail distribution with lots of features

project hosted by