removed top level directory

1 files changed, 253 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..a51c6d7
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,253 @@
+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. 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:
+
+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
+                  -DBARELF
+   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 option -DSHOWLOG.
+
+  -  Strict RF 5821 conformance for <CRLF.CRLF> can be 
+     relaxed by -DBARELF (=> 'SMTP smuggling' still not possible).
+
+   - 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: January, 14th 2024 (feh)