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. The UCSPI-SSL package to be installed.
6. Header files and libraries for IDN2 support (optional).
7. Header files and libraries for LDAP support (optional).

Optional but very useful:

1. The UCSPI-TCP6 package (tcprules, rblsmtpd).
2. DJB's Daemontools installed and working.
3. 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-home – home dir of s/qmail [/var/qmail]
   • conf-queue – separate queue directory [/var/qmail]
   • 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-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) ==> adjustsments for OmniOS required
   • 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). In conf-ld you find further samples for other OS.

   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-queue c) conf-qlibs d) conf-ssl e) conf-ucspissl f) conf-log g) conf-man h) 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 can be placed under /usr/local/sqmail (binaries, contol, and others) and queue at /var/sqmail/(queue) not requiring 'mount -u -o suid /var' any more.

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 option -DSHOWLOG.
  • Check conf-cc for more restrictive settings.

Splitted installation directories

s/qmail can be be splitted up two separate main directories as givin in

• conf-home: followed by ./bin, ./user, ./alias, ./ssl, and others. A typical place would be '/usr/bin/sqmail'.
• conf-queue: followed by ./queue and all required subdirectories. A typical place would be '/var/sqmail/'.

Note: The legacy directory is however still '/var/qmail'. Usage of a splitted directory setup is mainly forseen for integrators providing binary packages of s/qmail with the requirement to obey their particular installation paths.

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; read README.md
8. A patch for ClamAV logging to STDERR can be found at ./addons
9. Start-scripts (for Daemontools) reside in ./service

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

Date: September, 5th 2024 (feh)