diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 249 |
1 files changed, 249 insertions, 0 deletions
@@ -0,0 +1,249 @@ +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) |