path: root/INSTALL

Configuration and Installation of s/qmail
-----------------------------------------

HOW TO INSTALL:
- s/qmail uses D.J.B's slashpackage convention
  for installing while trying to conserve the
  standard qmail installations:
  * untar the sqmail tar file under '/package'
  * Move to /package/mail/sqmail/sqmail-V.R.F
  and go on with installation
- Set up the s/qmail package with the following
  step-by-step options or simple run (as 'root'):
  * package/install -- does it all

A) REQUIREMENTS 

1. Compiler & make utilities.
2. fehQlibs are installed (typically as /usr/local/qlibs)
3. The directory /package is in place.
4. Header files and libs for *SSL.
5. Header files and libraries for IDN2 support.
6. The UCSPI-SSL package to be installed.
7. Header files and libraries for IDN2 support (optional).

Optional but very useful:

8. The UCSPI-TCP6 package (tcprules, rblsmtpd).
9. DJB's Daemontools installed and working.
10. MRTG to display logging.


B) CONFIGURATION

1. Configuration is done by means of the 
   `conf-XX` files in this main directory.

2. Short description:

   conf-break -- the character for VERP addresses [-]
   conf-cc -- compiler (no change required)
   conf-delivery -- qmail-start default-delivery
   conf-djbdns -- DJBNDS libs (not supported yet)
   conf-groups*) -- s/qmail groups
   conf-home -- home dir of s/qmail [/var/qmail]
   conf-idn2 -- include optional path for libidn2
   conf-ids*) -- Unix ids for s/qmail
   conf-instances -- QMQ instances to be raised
   conf-ld -- loader options to be adjusted (for i386; AMD64 default)
   conf-log -- target dir of s/qmail logs [/var/log]
   conf-man -- target dir of man pages, usually automatically recognized
   conf-patrn -- s/qmail paternalism [002]
   conf-qmq -- QMQ environment settings
   conf-spawn -- silent concurrency limit [120]
   conf-split -- depth of s/qmail dirs [23]
   conf-svcdir -- supervise's directory [/service]
   conf-ssl -- path to *SSL header files [empty for defaults]
   conf-ucspissl -- path to UCSPI-SSL dirs
   conf-users*) -- user names

   Configurations labeled with *) need to be treated together.
   
3. Depending on your settings, you may need to 
   adjust the following:

   a) conf-cc:    Perhaps remove the -DIDN2 option
                  if libidn2 is not installed.
                  Other options are: 
                  -DHIDEVIRTUALUSER
                  -DDEFERREDBOUNCES
                  -DSHOWLOG
   b) conf-ld:    Adjust architecture of executables.
                  If you use OpenSSL/LibreSSL from sources outside the
                  default, you need to include the link path (-L).
   c) conf-idn2:  Include optional path to 'libidn2'. 

4. s/qmail user settings:

   a) conf-ids:   The UIDs and GIDs
   b) conf-groups:The s/qmail group names. 
   c) conf-users: The s/qmail user names.

5. Directories and system interaction:

   a) conf-home
   b) conf-qlibs 
   c) conf-ssl
   d) conf-ucspissl
   e) conf-log
   f) conf-man
   g) conf-svcdir

6. Run-time issues:

   a) conf-break
   b) conf-patrn
   c) conf-split
   d) conf-delivery
   e) conf-instances (still not working yet)
   f) conf-qmq (still not uptodate jet) 


C) INSTALLATION 

1. Upon configuration and verification
   to meet requirements, simply do

   package/install

2. Detail description of installation steps:

   package/dir -- sets up the directories
   package/ids -- sets up the s/qmail users
   package/ucspissl -- hooks up the required sources and libs with package ucspi-ssl
   package/compile -- compiles the sources
   package/upgrade -- potentially does the upgrade
   package/legacy -- installs the binaries in the qmail directory
   package/man -- installes the man pages

   All done be package/install. Additional (initial) settings:

   package/control -- populates the mininmal required control files for running
   package/sslenv -- sets up the SSL/TLS environments together with X.509 certs and key files (from ucspi-ssl)
   package/service -- sets up the run script for daemontools' /service and additionally the logging
   package/scripts setup optional, undocumented and unmaintained scripts
   package/run -- touches qmail/alias/ files and sets default-delivery

3. Installation on OpenBSD

  s/qmail should be placed under
    /usr/local/qmail
  -- or --
   mount -u -o suid /var

4. Upgrade from an existing Qmail

  s/qmail will keep your current qmail setup (except for the binaries):

  * Make sure, to have ucspi-ssl installed
  * Extract s/qmail under /package
  * cd /package/mail/sqmail-V.R.F
  * package/ucspissl
  * package/compile
  * package/legacy
  * package/man
  * package/upgrade

  In case your qmail installation is out of default, use the conf-* settings (ie. ids).
  Make sure, that your qmail 'todo' queue and the 'tcpto' table is empty (qmail-tcpto, qmail-tcpok).

  You need to change the port separator in the control files from ':' to ';' - if applicable.

5. Deinstallation and re-do installation

   Within s/qmail's installation directory (where this file resides)
   simply do:

   rm -r compile 

   Alternatively, you can do

   cd compile; make clean

   To re-install man-pages:
  
   cd man; rm *.gz; make clean
    
   Now you can continue with re-installation. 

6. Additional compile-time options

   conf-cc allows you to customize compilation for the following needs:

   - Internationalization: Include the option -IDN2.
     Be sure, to have IDN2 installed prior of compilation.

   - Virtual user obfuscation: Include the option -DHIDEVRITUALUSER.
     Now, the virtual user extension is excluded in the mail header
     for the displayed addresses. Vpopmail, however, requires this!

  -  Delayed bounces: Use -DDEFERREDBOUNCES.
     Now, qmail-remote will retry mail delivery even for not DNS
     resolveable host names and IP addresses until queue lifetime
     expires.

  -  DKIM private key names used for signing are shown
     in qmail-remote logs via optin -DSHOWLOG.

   - Check conf-cc for more restrictive settings.


D) DKIM CONFIGURATION

1. Key generation:
   You need to generate a public/private key pair.
   The private key is used to sign outgoing mails.
   The public key needs to be in the DNS as DKIM TXT record.
   Use the script mkdkimkey (after make in that directory)
   to generate RSA/Ed25519 key pairs in the required format.

2. Signing operation:
   Populate the private key in the directory
     ssl/domainkeys/<domain>
   and symlink it as 'default' (= selector).
   Key roll-over is easily supported with different selectors.
   Create
     control/dkimdomains
   with the entry '=:' defaulting to your domain/MTA.
   Several domain entries with different attributes can be used.
   Upon raising the file 'control/dkimdomains' all outgoing
   emails will be automatically DKIM signed in case the
   sending domains are listed therein.

3. Verification operation:
   Use qmail-dkverify as paramater in your 'smtpd.tcpd' file:
   :allow,QMAILQUEUE="bin/qmail-qmail-dkverify"
   Usually, qmail-dkverify works in annotation mode only, thus
   simply inlcudes a header for further message processing like this:
     X-Authentication-Results: piplus.fehcom.de; dkim=pass; bigchief.fehcom.de

   If you however set 'DKIM=+' as environment variable, mails
   failing DKIM verification (wrong signature) will be rejected upon receipt.
   This is not recommended, since mails may be subject of re-writing
   by mail-scanning MTAs.

Note: DKIM is inappropriate with QMTP(S) delivery. 

E) MISCELLANEOUS

1. s/qmail comes with a full set of updated man-pages.

2. s/qmail supports SPF and SRS natively without additional libs.

3. qmail-postgrey requires postgrey: [https://postgrey.schweikert.ch/]

4. Further documentation can be found in ./doc

5. Convenience files can be found in ./etc

6. Samples for control files are provided in ./ctl

7. Additional scripts are located in ./scripts

8. Start-scripts (for Daemontools) reside in ./service


Visit https://www.fehcom.de/sqmail/sqmail.html to
access online man-pages and documentation.

Date: June, 18th 2023 (feh)