v2.4

ChangeLog

@@ -1,11 +1,18 @@
 E-MailRelay Change Log
 ======================
 
-2.3 -> 2.3.1
+2.3 -> 2.4
-------------
+----------
-* Hourly log file rotation using "%h" (eg. "--log-file=log.%d.%h").
+* Multiple "--filter" and "--client-filter" options allowed.
 * TLS key and certificate files can be specified separately.
-* Fixed error handling for network client filters ("--client-filter=net:...") [bug-id #50].
+* Finer control when using "--anonymous" (eg. "--anonymous=server").
+* The "auth-config" options can distinguish between TLS and non-TLS authentication.
+* Hourly log file rotation using "%h" (eg. "--log-file=log.%d.%h").
+* Listening file descriptors can be inherited from the parent process (see "--interface").
+* Listening ports on Windows use exclusive binding.
+* The Linux event loop uses "epoll" by default rather than "select".
+* Some support for message routing (see NEWS).
+* Fix of error handling in network client filters ("--client-filter=net:...") [bug-id #50].
 
 2.2 -> 2.3
 ----------

Makefile.am

@@ -1,5 +1,5 @@
 #
-## Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+## Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 ## 
 ## This program is free software: you can redistribute it and/or modify
 ## it under the terms of the GNU General Public License as published by
@@ -61,7 +61,7 @@ EXTRA_DIST = \
 	winbuild.pl \
 	runperl.bat
 
-SUBDIRS = bin src etc doc debian test m4 bsd po
+SUBDIRS = bin src etc doc debian test m4 bsd po unity
 
 # work-round PKG_CHECK_MODULES if no pkg-config
 ACLOCAL_AMFLAGS = -I m4
@@ -76,6 +76,7 @@ RPM_ROOT ?= ${HOME}/rpmbuild
 ARCH ?= x86_64
 RPM=$(RPM_ROOT)/RPMS/$(ARCH)/emailrelay-$(VERSION)-1.$(ARCH).rpm
 TAR=emailrelay-$(VERSION).tar.gz
+ZIP=emailrelay-$(VERSION)-src.zip
 DEB=emailrelay_$(VERSION)_$(ARCH).deb
 
 .PHONY: strip
@@ -102,21 +103,25 @@ deb: $(DEB)
 
 $(DEB): dist
 	-mv emailrelay-$(VERSION) emailrelay-$(VERSION).old.$$$$ || true
-	tar xzf $(TAR)
+	tar -xzf $(TAR)
 	cd emailrelay-$(VERSION) && fakeroot debian/rules binary
 	mkdir emailrelay-$(VERSION)/debian/source
 
 .PHONY: deb-src
 deb-src: dist
 	-mv emailrelay-$(VERSION) emailrelay-$(VERSION).old.$$$$ || true
-	tar xzf $(TAR)
+	tar -xzf $(TAR)
 	mkdir emailrelay-$(VERSION)/debian/source
 	echo 1.0 > emailrelay-$(VERSION)/debian/source/format
 	dpkg-source --build emailrelay-$(VERSION)
 
 .PHONY: tidy
 tidy:
-	$(MAKE) -C src tidy
+	$(MAKE) -C unity tidy
+
+.PHONY: unitybuild
+unitybuild:
+	$(MAKE) -C unity programs
 
 .PHONY: format
 format:
@@ -130,3 +135,22 @@ cmake:
 	cd build && cmake -DCMAKE_MAKE_PROGRAM:FILEPATH=/usr/bin/make -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
 	@echo now run make from the '"build"' directory
 
+.PHONY: tar
+tar: $(TAR)
+
+$(TAR):
+	$(MAKE) dist
+
+.PHONY: zip
+zip: $(ZIP)
+
+$(ZIP): $(TAR)
+	tar -xzf $(TAR)
+	sh -c "cd emailrelay-$(VERSION) && zip -r ../$(ZIP) ."
+
+.PHONY: mbedtls
+mbedtls:
+	test -d mbedtls || git clone https://salsa.debian.org/debian/mbedtls.git
+	make -C mbedtls/library WINDOWS=0
+	-@echo now run ./configure.sh
+

Makefile.in

@@ -406,13 +406,14 @@ EXTRA_DIST = \
 	winbuild.pl \
 	runperl.bat
 
-SUBDIRS = bin src etc doc debian test m4 bsd po
+SUBDIRS = bin src etc doc debian test m4 bsd po unity
 
 # work-round PKG_CHECK_MODULES if no pkg-config
 ACLOCAL_AMFLAGS = -I m4
 e_doc_DATA = COPYING AUTHORS INSTALL NEWS README ChangeLog
 RPM = $(RPM_ROOT)/RPMS/$(ARCH)/emailrelay-$(VERSION)-1.$(ARCH).rpm
 TAR = emailrelay-$(VERSION).tar.gz
+ZIP = emailrelay-$(VERSION)-src.zip
 DEB = emailrelay_$(VERSION)_$(ARCH).deb
 all: all-recursive
 
@@ -928,21 +929,25 @@ deb: $(DEB)
 
 $(DEB): dist
 	-mv emailrelay-$(VERSION) emailrelay-$(VERSION).old.$$$$ || true
-	tar xzf $(TAR)
+	tar -xzf $(TAR)
 	cd emailrelay-$(VERSION) && fakeroot debian/rules binary
 	mkdir emailrelay-$(VERSION)/debian/source
 
 .PHONY: deb-src
 deb-src: dist
 	-mv emailrelay-$(VERSION) emailrelay-$(VERSION).old.$$$$ || true
-	tar xzf $(TAR)
+	tar -xzf $(TAR)
 	mkdir emailrelay-$(VERSION)/debian/source
 	echo 1.0 > emailrelay-$(VERSION)/debian/source/format
 	dpkg-source --build emailrelay-$(VERSION)
 
 .PHONY: tidy
 tidy:
-	$(MAKE) -C src tidy
+	$(MAKE) -C unity tidy
+
+.PHONY: unitybuild
+unitybuild:
+	$(MAKE) -C unity programs
 
 .PHONY: format
 format:
@@ -956,6 +961,25 @@ cmake:
 	cd build && cmake -DCMAKE_MAKE_PROGRAM:FILEPATH=/usr/bin/make -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
 	@echo now run make from the '"build"' directory
 
+.PHONY: tar
+tar: $(TAR)
+
+$(TAR):
+	$(MAKE) dist
+
+.PHONY: zip
+zip: $(ZIP)
+
+$(ZIP): $(TAR)
+	tar -xzf $(TAR)
+	sh -c "cd emailrelay-$(VERSION) && zip -r ../$(ZIP) ."
+
+.PHONY: mbedtls
+mbedtls:
+	test -d mbedtls || git clone https://salsa.debian.org/debian/mbedtls.git
+	make -C mbedtls/library WINDOWS=0
+	-@echo now run ./configure.sh
+
 # Tell versions [3.59,3.63) of GNU make to not export all variables.
 # Otherwise a system limit (for SysV at least) may be exceeded.
 .NOEXPORT:

NEWS

@@ -1,7 +1,34 @@
 News
 ----
-Version 2.3 is a relatively minor release. The main functional change is to
+Low-level changes include a rework of the event-loops. The Unix event loop
-support unix domain sockets. Non-functional code changes include better
+defaults to an epoll() implementation.
-separation of interface and implementation in the SMTP message store.
 
-Version 2.3.1 is a point release principally to fix bug-id #50.
+The i18n of the main server (not the gui) has been extended somewhat by marking
+for translation the text of most C++ exceptions. This is only relevant if
+building "--with-gettext" and running with "--localedir".
+
+The "--anonyous" option has changed slightly in v2.4 so that it will now force
+the AUTH parameter on the MAIL command to be "AUTH=<>". Replace "--anonymous"
+with "--anonymous=vrfy,server,content" to keep the same behaviour as before.
+
+The "emailrelay-submit" utility's "--content" option no longer suppresses
+reading of the standard input stream; there is a new "--no-stdin" option
+instead. A dot on its own does not terminate the input any more, so use ^D or
+^Z to stop reading from the terminal. Header-only content with no body text is
+now permitted.
+
+Authentication using PAM no longer insists on TLS encryption because the
+"--server-auth-config" option can be used to disable password authentication
+over an unencypted connection.
+
+Limited support for routing is included. The envelope files have two new fields:
+ForwardTo and ForwardToAddress. A filter script can examine the message content
+and deposit the appropriate domain name and port number in the ForwardTo field.
+If the SMTP client sees a ForwardTo value then it runs the client-filter early
+allowing the client filter to do a DNS MX lookup of the ForwardTo value and
+deposit the address into the ForwardToAddress field. If the SMTP client sees a
+ForwardToAddress it will initiate a connection to that address to send the
+message. The client-filter is run a second time in the normal way once the SMTP
+session has been established. A connection to the main "--forward-to" address
+will always be made even if all the messages are routed elsewhere, and each
+routed connection will carry only one message.

README

@@ -73,6 +73,30 @@ or run:
 
 	emailrelay --help --verbose
 
+Packages
+--------
+To install on Linux from a RPM or DEB package:
+
+	sudo $SHELL # or 'su'
+	rpm -i emailrelay*.rpm  # if RPM
+	dpkg -i emailrelay*.deb  # if DEB
+
+If your Linux system uses "systemd" then you should check the E-MailRelay
+configuration file "/etc/emailrelay.conf" is as you want it and then run:
+
+	systemctl enable emailrelay
+	systemctl start emailrelay
+	systemctl status emailrelay
+
+On other systems try these commands:
+
+	cp /usr/lib/emailrelay/init/emailrelay /etc/init.d/
+	update-rc.d emailrelay enable || rc-update add emailrelay
+	invoke-rc.d emailrelay start || service emailrelay start
+	tail /var/log/messages /var/log/syslog 2>/dev/null
+
+On Windows run the setup program.
+
 Documentation
 -------------
 The following documentation is provided:
@@ -87,7 +111,3 @@ The following documentation is provided:
 Source code documentation will be generated when building from source if
 "doxygen" is available.
 
-Feedback
---------
-Please feel free to e-mail the author at "mailto:graeme_walker@users.sourceforge.net".
-

README.md

@@ -79,6 +79,30 @@ or run:
 
         emailrelay --help --verbose
 
+Packages
+--------
+To install on Linux from a RPM or DEB package:
+
+        sudo $SHELL # or 'su'
+        rpm -i emailrelay*.rpm  # if RPM
+        dpkg -i emailrelay*.deb  # if DEB
+
+If your Linux system uses `systemd` then you should check the E-MailRelay
+configuration file `/etc/emailrelay.conf` is as you want it and then run:
+
+        systemctl enable emailrelay
+        systemctl start emailrelay
+        systemctl status emailrelay
+
+On other systems try these commands:
+
+        cp /usr/lib/emailrelay/init/emailrelay /etc/init.d/
+        update-rc.d emailrelay enable || rc-update add emailrelay
+        invoke-rc.d emailrelay start || service emailrelay start
+        tail /var/log/messages /var/log/syslog 2>/dev/null
+
+On Windows run the setup program.
+
 Documentation
 -------------
 The following documentation is provided:
@@ -94,10 +118,6 @@ The following documentation is provided:
 Source code documentation will be generated when building from source if
 `doxygen` is available.
 
-Feedback
---------
-Please feel free to e-mail the author at `mailto:graeme_walker@users.sourceforge.net`.
-
 
 [POP]: https://en.wikipedia.org/wiki/Post_Office_Protocol
 [SMTP]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol

README.rst

@@ -100,6 +100,36 @@ or run:
 
     emailrelay --help --verbose
 
+Packages
+========
+To install on Linux from a RPM or DEB package:
+
+::
+
+    sudo $SHELL # or 'su'
+    rpm -i emailrelay*.rpm  # if RPM
+    dpkg -i emailrelay*.deb  # if DEB
+
+If your Linux system uses *systemd* then you should check the E-MailRelay
+configuration file */etc/emailrelay.conf* is as you want it and then run:
+
+::
+
+    systemctl enable emailrelay
+    systemctl start emailrelay
+    systemctl status emailrelay
+
+On other systems try these commands:
+
+::
+
+    cp /usr/lib/emailrelay/init/emailrelay /etc/init.d/
+    update-rc.d emailrelay enable || rc-update add emailrelay
+    invoke-rc.d emailrelay start || service emailrelay start
+    tail /var/log/messages /var/log/syslog 2>/dev/null
+
+On Windows run the setup program.
+
 Documentation
 =============
 The following documentation is provided:
@@ -115,10 +145,6 @@ The following documentation is provided:
 Source code documentation will be generated when building from source if
 *doxygen* is available.
 
-Feedback
-========
-Please feel free to e-mail the author at *mailto:graeme_walker@users.sourceforge.net*.
-
 
 .. _POP: https://en.wikipedia.org/wiki/Post_Office_Protocol
 .. _SMTP: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol

VERSION

@@ -1 +1 @@
-2.3.1
+2.4

bin/AutoMakeParser.pm

@@ -1,6 +1,6 @@
 #!/usr/bin/perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -40,6 +40,24 @@
 #  $makefile->our_libs('foo') ;
 #  $makefile->sys_libs('foo') ;
 #
+# Typical directories in a autoconf vpath build (see includes()):
+#
+#    project <-- $(top_srcdir)        <-------+-+ "base_to_top"
+#       |                                     | |
+#       +----src  <-- readall() base        --+ | <---+ base()
+#       |     |                                 |     |
+#       |     +-- sub1  <-- path()              | ----+
+#       |                                       |
+#       +----bin                                |
+#       |                                       |
+#       +--build <-- $(top_builddir)            |  <-- $(top_builddir)
+#            |                                  |
+#            +-- src                          --+  <--+ base()
+#                 |                                   |
+#                 +-- sub1  <-- c++ cwd         ------+
+#
+# See also ConfigStatus.pm.
+#
 
 use strict ;
 use FileHandle ;
@@ -104,11 +122,11 @@ sub depth
 	return $this->{m_depth} ;
 }
 
-sub top
+sub base
 {
 	# Returns the relative path up to the first readall()
-	# makefile, which might be different from $(top_srcdir).
+	# makefile. The returned value will be something like
-	# The returned value will be something like "../../../".
+	# "../../../". See also includes().
 	#
 	my ( $this ) = @_ ;
 	my $depth = $this->{m_depth} ;
@@ -237,46 +255,47 @@ sub _definitions_imp
 
 sub includes
 {
-	# Returns a list of include directories, so for example
+	# Returns a list of include directories derived from the
-	# "-I$(top_srcdir)/one/two -I$(top_srcdir)/three"
+	# AM_CPPFLAGS and CXXFLAGS macros. The returned list also
-	# with the 'top_srcdir' variable defined as "." gives
+	# optionally starts with the autoconf header directory,
-	# ("./one/two","./three").
+	# obtained by expanding top_srcdir.
 	#
-	# However, since the 'top_srcdir' expansion is fixed, and
+	# Include paths need to vary through the source tree,
-	# relative include paths need to vary through the source
+	# so a 'base' parameter is provided here which is used
-	# tree, a prefix parameter ('top') should be passed in as
+	# as a prefix for all relative paths from the AM_CPPFLAGS
-	# the current value for expanding "$(top_srcdir)". So then
+	# and CXXFLAGS expansions and as a suffix for the
-	# "-I$(top_srcdir)/one/two" becomes "<top>/./one/two".
+	# autoconf header directory.
-	# (Absolute paths do not get the 'top' prefixed by 'top'.)
 	#
-	# The "top()" method provides a candidate for the 'top'
+	# For example, if CXXFLAGS is "-I$(top_srcdir)/src/sub"
-	# parameter but will only work if readall() started at the
+	# and top_srcdir is "." then includes(base()) will
-	# 'top_srcdir' directory and the 'top_srcdir' variable is
+	# will yield ("./..",".././src/sub") for one makefile and
-	# defined as ".". Otherwise, a simple approach is to still
+	# ("./../..","../.././src/sub") for another.
-	# use top() for the 'top' parameter but define the 'top_srcdir'
-	# variable as the difference between the readall() base and
-	# the actual 'top_srcdir' directory.
 	#
-	my ( $this , $top , $full_paths , $no_top_dir ) = @_ ;
+	# In practice the value for top_srcdir should be carefully
-	$top ||= "" ;
+	# chosen as some "base-to-top" relative path that makes things
-	my $add_top = !$no_top_dir ;
+	# work correctly if readall() was not based at top_srcdir
-	my $real_top = simplepath( join( "/" , $this->value("top_srcdir") , $top ) ) ;
+	# or when targeting vpath builds. See above.
-	my @a = $this->_includes_imp( $top , "AM_CPPFLAGS" , $this->{m_vars} , $full_paths ) ;
+	#
-	my @b = $this->_includes_imp( $top , "CXXFLAGS" , $this->{m_vars} , $full_paths ) ;
+	my ( $this , $base , $full_paths , $no_autoconf_dir ) = @_ ;
-	my @c = ( $real_top && $add_top ) ? ( $real_top ) : () ;
+	$base ||= "" ;
+	my $add_autoconf_dir = !$no_autoconf_dir ;
+	my $autoconf_dir = simplepath( join( "/" , $this->value("top_srcdir") , $base ) ) ;
+	my @a = $this->_includes_imp( $base , "AM_CPPFLAGS" , $this->{m_vars} , $full_paths ) ;
+	my @b = $this->_includes_imp( $base , "CXXFLAGS" , $this->{m_vars} , $full_paths ) ;
+	my @c = ( $autoconf_dir && $add_autoconf_dir ) ? ( $autoconf_dir ) : () ;
 	my @incs = ( @c , @a , @b ) ;
 	return wantarray ? @incs : join(" ",@incs) ;
 }
 
 sub _includes_imp
 {
-	my ( $this , $top , $var , $vars , $full_paths ) = @_ ;
+	my ( $this , $base , $var , $vars , $full_paths ) = @_ ;
 	my $s = protect_quoted_spaces( simple_spaces( $vars->{$var} ) ) ;
 	$s =~ s/-I /-I/g ;
 	return
 		map { $full_paths?$this->fullpath($_):$_ }
 		map { simplepath($_) }
-		map { my $p=$_ ; ($top&&($p!~m;^/;))?join("/",$top,$p):$p }
+		map { my $p=$_ ; ($base&&($p!~m;^/;))?join("/",$base,$p):$p }
 		map { s/\t/ /g ; $_ }
 		map { s:-I:: ; $_ } grep { m/-I\S+/ }
 		split( " " , $s ) ;

bin/CompilationDatabase.pm

@@ -1,6 +1,6 @@
 #!/usr/bin/perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -26,7 +26,9 @@
 # Synopsis:
 #
 #    use CompilationDatabase ;
-#    my $cdb = new CompilationDatabase( $src_dir , {WINDOWS=>0,...} , {top_srcdir=>'..'} , {} ) ;
+#    my @makefiles = AutoMakeParser::readall( ... ) ;
+#    my $cdb = new CompilationDatabase( \@makefiles , {full_paths=>1} ) ;
+#    my $cdb = new CompilationDatabase( $src_dir , {WINDOWS=>0,...} , {top_srcdir=>'..'} , {full_paths=>1} ) ;
 #    my @files = $cdb->list() ;
 #    my @stanzas = $cdb->stanzas() ;
 #    $cdb->print() ;
@@ -41,28 +43,50 @@ our $debug = 0 ;
 
 sub new
 {
-	my ( $classname , $base_makefile_dir , $switches , $ro_vars , $config ) = @_ ;
+	if( ref($_[1]) )
-	$AutoMakeParser::debug = 1 if $debug > 1 ;
+	{
-	$config ||= {} ;
+		# Parses a set of makefiles as given by an array of Makefile
-	$config->{test_mode} ||= 0 ;
+		# objects obtained from AutoMakeParser::readall().
-	$config->{full_paths} ||= 0 ;
+		#
-	my %me = (
+		my ( $classname , $makefiles_ref , $config ) = @_ ;
-		m_base_dir => $base_makefile_dir ,
+		$config ||= {} ;
-		m_switches => $switches ,
+		$config->{test_mode} ||= 0 ;
-		m_ro_vars => $ro_vars ,
+		$config->{full_paths} ||= 0 ;
-		m_config => $config ,
+		my %me = (
-	) ;
+			m_makefiles => $makefiles_ref ,
-	return bless \%me , $classname ;
+			m_config => $config ,
+		) ;
+		return bless \%me , $classname ;
+	}
+	else
+	{
+		# Finds makefiles under the given base directory and parses
+		# them. The switches and read-only expansion variables can
+		# be hard-coded or extracted from a config.status file
+		# (see ConfigStatus).
+		#
+		my ( $classname , $base_makefile_dir , $switches , $ro_vars , $config ) = @_ ;
+		$AutoMakeParser::debug = 1 if $debug > 1 ;
+		$config ||= {} ;
+		$config->{test_mode} ||= 0 ;
+		$config->{full_paths} ||= 0 ;
+		my @makefiles = AutoMakeParser::readall( $base_makefile_dir , $switches , $ro_vars ) ;
+		my %me = (
+			m_makefiles => \@makefiles ,
+			m_config => $config ,
+		) ;
+		return bless \%me , $classname ;
+	}
 }
 
 sub list
 {
+	# Returns a list of all the source files in all the makefiles found under base-dir.
 	my ( $this ) = @_ ;
 
 	my @list = () ;
 	my $verbose = $debug ;
-	my @makefiles = AutoMakeParser::readall( $this->{m_base_dir} , $this->{m_switches} , $this->{m_ro_vars} , $verbose ) ;
+	for my $m ( @{$this->{m_makefiles}} )
-	for my $m ( @makefiles )
 	{
 		my $sub_dir = File::Basename::dirname( $m->path() ) ;
 		for my $library ( $m->libraries() )
@@ -79,6 +103,7 @@ sub list
 
 sub print
 {
+	# Prints the complete compilation database json structure to stdout.
 	my ( $this ) = @_ ;
 	print "[\n" ;
 	print join( ",\n" , $this->stanzas() ) ;
@@ -87,14 +112,15 @@ sub print
 
 sub stanzas
 {
+	# Returns a list of separate compilation database stanzas for all the source files
+	# in all the makefiles found under base-dir.
 	my ( $this ) = @_ ;
 
-	my @makefiles = AutoMakeParser::readall( $this->{m_base_dir} , $this->{m_switches} , $this->{m_ro_vars} ) ;
 	my @output = () ;
-	for my $m ( @makefiles )
+	for my $m ( @{$this->{m_makefiles}} )
 	{
 		my $dir = File::Basename::dirname( $m->path() ) ;
-		my @includes = map { "-I$_" } $m->includes( $m->top() , undef , undef , $this->{m_config}->{full_paths} ) ;
+		my @includes = map { "-I$_" } $m->includes( $m->base() , undef , undef , $this->{m_config}->{full_paths} ) ;
 		my @definitions = map { "-D$_" } $m->definitions() ;
 		my @compile_options = $m->compile_options() ;
 		my @link_options = $m->link_options() ;
@@ -102,7 +128,7 @@ sub stanzas
 		if( $debug )
 		{
 			print "cdb: makefile=" , $m->path() , "\n" ;
-			print "cdb:  top=",$m->top(),"\n" ;
+			print "cdb:  base=",$m->base(),"\n" ;
 			print "cdb:  \@includes=" , join("|",@includes) , "\n" ;
 			print "cdb:  \@definitions=" , join("|",@definitions) , "\n" ;
 			print "cdb:  \@compile_options=" , join("|",@compile_options) , "\n" ;

bin/ConfigStatus.pm

@@ -1,6 +1,6 @@
 #!/usr/bin/perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -23,7 +23,9 @@
 #
 # Synopsis:
 #  use ConfigStatus ;
-#  my $cs = new ConfigStatus( "config.status" ) ;
+#  my $cs = new ConfigStatus() ;
+#  my $cs = new ConfigStatus( "./config.status" ) ;
+#  my $cs = new ConfigStatus("") ; $cs->parse( "/tmp/config.status" ) ;
 #  my %vars = $cs->vars() ;
 #  my %switches = $cs->switches() ;
 #
@@ -42,6 +44,18 @@ sub new
 		m_vars => {} ,
 		m_switches => {} ,
 	} , $classname ;
+	if( !defined($filename) )
+	{
+		for my $dir ( "." , ".." , "../.." )
+		{
+			if( -e "$dir/config.status" )
+			{
+				$filename = "$dir/config.status" ;
+				last ;
+			}
+		}
+		$filename or die ;
+	}
 	$this->parse( $filename ) if $filename ;
 	return $this ;
 }

bin/Makefile.am

@@ -1,5 +1,5 @@
 #
-## Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+## Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 ## 
 ## This program is free software: you can redistribute it and/or modify
 ## it under the terms of the GNU General Public License as published by
@@ -19,6 +19,7 @@ example_scripts_static = \
 	emailrelay-bcc-check.pl \
 	emailrelay-check-ipaddress.js \
 	emailrelay-check-ipaddress.pl \
+	emailrelay-dkim-signer.pl \
 	emailrelay-ldap-verify.py \
 	emailrelay-multicast.sh \
 	emailrelay-rot13.pl \
@@ -52,6 +53,7 @@ work_scripts = \
 	make-format \
 	make2cmake \
 	make2cdb \
+	make2unity \
 	AutoMakeParser.pm \
 	CompilationDatabase.pm \
 	ConfigStatus.pm \

bin/Makefile.in

@@ -286,6 +286,7 @@ example_scripts_static = \
 	emailrelay-bcc-check.pl \
 	emailrelay-check-ipaddress.js \
 	emailrelay-check-ipaddress.pl \
+	emailrelay-dkim-signer.pl \
 	emailrelay-ldap-verify.py \
 	emailrelay-multicast.sh \
 	emailrelay-rot13.pl \
@@ -319,6 +320,7 @@ work_scripts = \
 	make-format \
 	make2cmake \
 	make2cdb \
+	make2unity \
 	AutoMakeParser.pm \
 	CompilationDatabase.pm \
 	ConfigStatus.pm \

bin/doxygen.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

bin/emailrelay-bcc-check.pl

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-deliver.sh.in

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-dkim-signer.pl

@@ -0,0 +1,65 @@
+#!/usr/bin/env perl
+#
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
+# 
+# Copying and distribution of this file, with or without modification,
+# are permitted in any medium without royalty provided the copyright
+# notice and this notice are preserved.  This file is offered as-is,
+# without any warranty.
+# ===
+#
+# emailrelay-dkim-signer.pl
+#
+# An example E-MailRelay filter script for DKIM signing.
+#
+# To generate a key pair:
+#   $ openssl genrsa -out example.com.pk 2048
+#   $ openssl rsa -in example.com.pk -pubout -out example.com.pub
+#
+# Serve up the public key via DNS, eg:
+#   $ grep -v PUBLIC example.com.pub | tr -d '\n'
+#   upload default._domainkey TXT "p=Q8AMIIB...."
+#   $ nslookup -query=TXT default._domainkey.example.com
+#   text = "p=Q8AMIIB...."
+#
+# Test with spamassassin:
+#   $ c=`emailrelay-submit -v -s \`pwd\` -C DQo= -C aGVsbG8sIHdvcmxkIQ== -d -F -t -f me@example.com you@example.com`
+#   $ emailrelay-dkim-signer.pl $c
+#   $ spamassassin --debug=dkim --test-mode < $c
+#
+# Requires debian package 'libmail-dkim-perl'.
+#
+
+use strict ;
+use FileHandle ;
+use File::Copy ;
+use Mail::DKIM::Signer ;
+use Mail::DKIM::TextWrap ;
+
+$SIG{__DIE__} = sub { (my $e = join(" ",@_)) =~ s/\n/ /g ; print "<<error: $e>>\n" ; exit 99 } ;
+
+my $content = $ARGV[0] or die "usage error\n" ;
+my $fh = new FileHandle( $content ) or die "cannot open content file\n" ;
+
+my $dkim = new Mail::DKIM::Signer(
+	Algorithm => 'rsa-sha1' ,
+	Method => 'relaxed' ,
+	Domain => 'example.com' ,
+	Selector => 'default' , # => default._domainkey.example.com
+	KeyFile => '/etc/dkim/private/example.com.pk' ,
+	Headers => '' , # 'x-header:x-header2'
+);
+
+$dkim->load( $fh ) ; # includes CLOSE()
+$fh->close() or die ;
+
+my $signature = $dkim->signature->as_string() ;
+
+$fh = new FileHandle( $content.".tmp" , "w" ) or die ;
+print $fh $signature , "\r\n" ;
+$fh->flush() ;
+File::Copy::copy( $content , $fh ) or die ;
+$fh->close() or die ;
+File::Copy::move( $content.".tmp" , $content ) or die ;
+
+exit 0 ;

bin/emailrelay-edit-content.js

@@ -1,5 +1,5 @@
 //
-// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+// Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 // 
 // Copying and distribution of this file, with or without modification,
 // are permitted in any medium without royalty provided the copyright

bin/emailrelay-edit-envelope.js

@@ -1,5 +1,5 @@
 //
-// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+// Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 // 
 // Copying and distribution of this file, with or without modification,
 // are permitted in any medium without royalty provided the copyright

bin/emailrelay-ldap-verify.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 #
-# Copyright (C) 2020-2021 <richardwvm@users.sourceforge.net>
+# Copyright (C) 2020-2022 <richardwvm@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-multicast.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-notify.sh.in

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-resubmit.js

@@ -1,5 +1,5 @@
 //
-// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+// Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 // 
 // Copying and distribution of this file, with or without modification,
 // are permitted in any medium without royalty provided the copyright

bin/emailrelay-resubmit.sh.in

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-rot13.pl

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-sendmail.pl

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-service-install.js

@@ -1,5 +1,5 @@
 //
-// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+// Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 // 
 // This program is free software: you can redistribute it and/or modify
 // it under the terms of the GNU General Public License as published by

bin/emailrelay-set-from.js

@@ -1,5 +1,5 @@
 //
-// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+// Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 // 
 // Copying and distribution of this file, with or without modification,
 // are permitted in any medium without royalty provided the copyright

bin/emailrelay-set-from.pl

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay-submit.sh.in

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # Copying and distribution of this file, with or without modification,
 # are permitted in any medium without royalty provided the copyright

bin/emailrelay.sh.in

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

bin/make-format

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

bin/make-manifest.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

bin/make-setup.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

bin/make2cdb

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

bin/make2cmake

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -100,7 +100,7 @@ sub create_cmake_file
 	}
 
 	my $definitions = join( " " , $m->definitions() ) ;
-	my $includes = join( " " , "." , ".." , $m->includes($m->top()) ) ;
+	my $includes = join( " " , "." , ".." , $m->includes($m->base()) ) ;
 
 	my @libraries = $m->libraries() ;
 	for my $library ( @libraries )

bin/make2unity

@@ -0,0 +1,171 @@
+#!/usr/bin/env perl
+#
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# ===
+#
+# make2unity
+#
+# Generates "unity build" source files by parsing autoconf/automake
+# artifacts throughout the source tree. Also optionally creates a
+# compilation database ("compile_commands.json") for running
+# clang-tidy.
+#
+# usage:
+#   make2unity --out=<output> [options] <program>
+#   make2unity [options] [<program> [<program> ...]]
+#      --base=<dir>            -- base directory for makefile search
+#      --config-status=<file>  -- path of config.status file
+#      --out=<file>            -- output source file (if one <program>)
+#      --cdb                   -- create a compilation database
+#      --cdb-top=<dir>         -- top_srcdir (needed if --cdb)
+#      --cdb-cxx=<exe>         -- compiler (needed if --cdb)
+#
+# The <program> arguments are allowed to have a ".cpp" suffix.
+#
+# Eg:
+#     $ cd src
+#     $ ../bin/make2unity emailrelay.cpp
+#     $ g++ -pthread -I.... -c emailrelay.cpp
+#     $ g++ -pthread -o emailrelay emailrelay.o -lpam -lssl -lcrypto
+#
+
+use strict ;
+use warnings ;
+use FileHandle ;
+use File::Basename ;
+use Getopt::Long ;
+use Data::Dumper ;
+use lib dirname($0) ;
+use CompilationDatabase ;
+use ConfigStatus ;
+use AutoMakeParser ;
+$AutoMakeParser::debug = 0 ;
+
+my %opt = () ;
+GetOptions( \%opt , "out=s" , "cdb" , "cdb-cxx=s" , "cdb-top=s" , "base=s" , "config-status=s" ) or die "make2unity: usage error" ;
+die "make2unity: usage error" if scalar(@ARGV) == 0 ;
+die "make2unity: usage error" if ( $opt{out} && scalar(@ARGV) != 1 ) ;
+
+my $cfg_out = $opt{out} ;
+my $cfg_cdb = exists $opt{cdb} ;
+my $cfg_top_srcdir = $opt{'cdb-top'} ;
+my $cfg_base_dir = exists $opt{base} ? $opt{base} : File::Basename::dirname($0)."/../src" ;
+my $cfg_config_status = $opt{'config-status'} ;
+my @cfg_programs = @ARGV ;
+push @cfg_programs , "emailrelay" if !@cfg_programs ;
+my $cfg_cxx = $opt{'cdb-cxx'} || "/usr/bin/c++" ;
+
+my $cs = new ConfigStatus( $cfg_config_status ) ;
+my %switches = $cs->switches() ;
+my %vars = $cs->vars() ;
+
+$vars{top_srcdir} = "." ;
+$vars{top_builddir} = "." ;
+
+my @makefiles = AutoMakeParser::readall( $cfg_base_dir , \%switches , \%vars ) ;
+
+my $fh_cdb ;
+if( $cfg_cdb )
+{
+	$fh_cdb = new FileHandle( "compile_commands.json" , "w" ) or die ;
+	print $fh_cdb "[\n" ;
+}
+
+for my $cfg_program ( @cfg_programs )
+{
+	my $program = File::Basename::basename( $cfg_program , ".cpp" ) ;
+	my $out = $cfg_out ? $cfg_out : "${program}.cpp" ;
+
+	my $fh_out = new FileHandle( $out , "w" ) or die ;
+	print $fh_out "/* autogenerated by make2unity */\n" ;
+	my $stanza = undef ;
+	my %libs = () ;
+	my @out_lines = () ;
+	for my $m ( @makefiles )
+	{
+		my $dir = File::Basename::dirname( $m->path() ) ;
+		for my $p ( $m->programs() )
+		{
+			if( $p eq $program || ($p eq "$program.real") )
+			{
+				map { $libs{"lib".$_.".a"} = 1 } $m->our_libs( $p ) ;
+				push @out_lines , "/* exe [$dir] */\n" ;
+				print $fh_out "/* c++ -pthread".join(" -I ../",("",$m->includes("",0,0)))." -o $p $p.cpp ".join(" -l",("",$m->sys_libs($p)))." */\n" ;
+				for my $src ( $m->sources($p) )
+				{
+					push @out_lines , "#include \"$src\"\n" ;
+				}
+				$stanza = stanza( $program , $m ) ;
+			}
+		}
+	}
+	for my $m ( @makefiles )
+	{
+		my $dir = File::Basename::dirname( $m->path() ) ;
+
+		print $fh_out "/* lib [$dir] */\n" ;
+		for my $library ( $m->libraries() )
+		{
+			if( exists($libs{$library}) ) # ignore this library if not linked in to $program
+			{
+				for my $src ( $m->sources($library) )
+				{
+					print $fh_out "#include \"$src\"\n" ;
+				}
+			}
+			else
+			{
+				print $fh_out "/* (not linked) */\n" ;
+			}
+		}
+	}
+	print $fh_out @out_lines ; # (after all the library sources)
+	$fh_out->close() or die ;
+	print $fh_cdb $stanza , "\n" if ( $fh_cdb && defined($stanza) ) ;
+}
+
+if( $fh_cdb )
+{
+	print $fh_cdb "]\n" ;
+	$fh_cdb->close() or die ;
+}
+
+sub stanza
+{
+	my ( $program , $m ) = @_ ;
+
+	my $dir = cwd() ;
+	my $src = "$program.cpp" ;
+	my $autoconf_dir = "../src" ;
+	my $program_dir = File::Basename::dirname( $m->path() ) ;
+	my $moc_dir = "." ;
+	my @includes = ( $autoconf_dir , $program_dir , $moc_dir , $m->includes($cfg_top_srcdir,0,1) ) ;
+	my $includes = join( " -I" , ("",@includes) ) ;
+	my $options = $m->compile_options() ;
+	my $cmd = "$cfg_cxx $options $includes -c $program.cpp" ;
+
+	my $s = '{
+		 "directory" : "__DIR__" ,
+		 "command" : "__CMD__" ,
+		 "file" : "__SRC__" ,
+		},' ;
+	$s =~ s/\t//gm ;
+	$s =~ s/__DIR__/$dir/m ;
+	$s =~ s/__CMD__/$cmd/m ;
+	$s =~ s/__SRC__/$src/m ;
+	return $s ;
+}
+

bin/winbuild.pm

@@ -1,6 +1,6 @@
 #!/usr/bin/perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

bsd/Makefile.am

@@ -1,5 +1,5 @@
 #
-## Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+## Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 ## 
 ## This program is free software: you can redistribute it and/or modify
 ## it under the terms of the GNU General Public License as published by

bsd/emailrelay-bsd.sh.in

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

configure

@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for E-MailRelay 2.3.1.
+# Generated by GNU Autoconf 2.69 for E-MailRelay 2.4.
 #
 #
 # Copyright (C) 1992-1996, 1998-2012 Free Software Foundation, Inc.
@@ -577,8 +577,8 @@ MAKEFLAGS=
 # Identity of this package.
 PACKAGE_NAME='E-MailRelay'
 PACKAGE_TARNAME='emailrelay'
-PACKAGE_VERSION='2.3.1'
+PACKAGE_VERSION='2.4'
-PACKAGE_STRING='E-MailRelay 2.3.1'
+PACKAGE_STRING='E-MailRelay 2.4'
 PACKAGE_BUGREPORT=''
 PACKAGE_URL=''
 
@@ -636,8 +636,6 @@ e_icondir
 e_bsdinitdir
 e_initdir
 e_docdir
-GCONFIG_UDS_FALSE
-GCONFIG_UDS_TRUE
 GCONFIG_PAM_FALSE
 GCONFIG_PAM_TRUE
 GCONFIG_TLS_USE_NONE_FALSE
@@ -651,6 +649,10 @@ GCONFIG_TLS_USE_BOTH_TRUE
 GCONFIG_TLS_LIBS
 GCONFIG_GETTEXT_FALSE
 GCONFIG_GETTEXT_TRUE
+GCONFIG_DNSBL_FALSE
+GCONFIG_DNSBL_TRUE
+GCONFIG_UDS_FALSE
+GCONFIG_UDS_TRUE
 GCONFIG_WINDOWS_FALSE
 GCONFIG_WINDOWS_TRUE
 GCONFIG_TESTING_FALSE
@@ -799,13 +801,14 @@ enable_std_thread
 enable_testing
 enable_verbose
 enable_windows
+enable_uds
+enable_dnsbl
 with_doxygen
 with_gettext
 with_man2html
 with_openssl
 with_mbedtls
 with_pam
-with_uds
 '
       ac_precious_vars='build_alias
 host_alias
@@ -1375,7 +1378,7 @@ if test "$ac_init_help" = "long"; then
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures E-MailRelay 2.3.1 to adapt to many kinds of systems.
+\`configure' configures E-MailRelay 2.4 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -1442,7 +1445,7 @@ fi
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of E-MailRelay 2.3.1:";;
+     short | recursive ) echo "Configuration of E-MailRelay 2.4:";;
    esac
   cat <<\_ACEOF
 
@@ -1462,7 +1465,7 @@ Optional Features:
   --enable-bsd            enable building for bsd (default auto)
   --enable-debug          enable extra debug messages at compile-time (default
                           no)
-  --enable-epoll          enable epoll (default no)
+  --enable-epoll          enable epoll (default auto)
   --enable-gui            enable configuration gui (requires Qt) (default
                           auto)
   --enable-install-hook   enable fixing up the start/stop configuration file
@@ -1475,6 +1478,8 @@ Optional Features:
   --enable-testing        enable make check tests (default yes)
   --enable-verbose        enable verbose logging (default yes)
   --enable-windows        enable building for windows (default auto)
+  --enable-uds            enable unix domain sockets (default auto)
+  --enable-dnsbl          enable DNSBL (default yes)
 
 Optional Packages:
   --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
@@ -1487,7 +1492,6 @@ Optional Packages:
   --with-openssl          use openssl for tls layer (default auto)
   --with-mbedtls          use mbedtls for tls layer (default auto)
   --with-pam              use linux pam for authentication (default auto)
-  --with-uds              enable unix domain sockets (default auto)
 
 Some influential environment variables:
   CC          C compiler command
@@ -1575,7 +1579,7 @@ fi
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
   cat <<\_ACEOF
-E-MailRelay configure 2.3.1
+E-MailRelay configure 2.4
 generated by GNU Autoconf 2.69
 
 Copyright (C) 2012 Free Software Foundation, Inc.
@@ -2011,7 +2015,7 @@ cat >config.log <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by E-MailRelay $as_me 2.3.1, which was
+It was created by E-MailRelay $as_me 2.4, which was
 generated by GNU Autoconf 2.69.  Invocation command line was
 
   $ $0 $@
@@ -2876,7 +2880,7 @@ fi
 
 # Define the identity of the package.
  PACKAGE='emailrelay'
- VERSION='2.3.1'
+ VERSION='2.4'
 
 
 # Some tools Automake needs.
@@ -7283,6 +7287,61 @@ $as_echo "#define GCONFIG_HAVE_IFNAMETOLUID 0" >>confdefs.h
 
 	fi
 
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for ifreq ifr_index" >&5
+$as_echo_n "checking for ifreq ifr_index... " >&6; }
+if ${gconfig_cv_ifindex+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+
+	cat confdefs.h - <<_ACEOF >conftest.$ac_ext
+/* end confdefs.h.  */
+
+			#ifdef _WIN32
+				#include <winsock2.h>
+				#include <windows.h>
+				#include <ws2tcpip.h>
+				#include <iphlpapi.h>
+			#else
+				#include <sys/types.h>
+				#include <sys/socket.h>
+				#include <arpa/inet.h>
+				#include <net/if.h>
+				#include <sys/ioctl.h>
+			#endif
+			struct ifreq req ;
+			int i = 0 ;
+
+int
+main ()
+{
+
+			(void) ioctl( i , SIOCGIFINDEX , &req , sizeof(req) );
+			i = req.ifr_ifindex ;
+
+  ;
+  return 0;
+}
+_ACEOF
+if ac_fn_cxx_try_compile "$LINENO"; then :
+  gconfig_cv_ifindex=yes
+else
+  gconfig_cv_ifindex=no
+fi
+rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext
+
+fi
+{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $gconfig_cv_ifindex" >&5
+$as_echo "$gconfig_cv_ifindex" >&6; }
+	if test "$gconfig_cv_ifindex" = "yes" ; then
+
+$as_echo "#define GCONFIG_HAVE_IFINDEX 1" >>confdefs.h
+
+	else
+
+$as_echo "#define GCONFIG_HAVE_IFINDEX 0" >>confdefs.h
+
+	fi
+
 { $as_echo "$as_me:${as_lineno-$LINENO}: checking for gai_strerror()" >&5
 $as_echo_n "checking for gai_strerror()... " >&6; }
 if ${gconfig_cv_gaistrerror+:} false; then :
@@ -7380,6 +7439,55 @@ $as_echo "#define GCONFIG_HAVE_UDS 0" >>confdefs.h
 
 	fi
 
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for unix domain sockets" >&5
+$as_echo_n "checking for unix domain sockets... " >&6; }
+if ${gconfig_cv_uds_len+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+
+	cat confdefs.h - <<_ACEOF >conftest.$ac_ext
+/* end confdefs.h.  */
+
+			#include <sys/types.h>
+			#include <sys/socket.h>
+			#include <sys/un.h>
+			struct sockaddr_un a ;
+
+int
+main ()
+{
+
+			a.sun_len = 2U ;
+			a.sun_family = AF_UNIX | PF_UNIX ;
+			a.sun_path[0] = '\0' ;
+
+  ;
+  return 0;
+}
+_ACEOF
+if ac_fn_cxx_try_compile "$LINENO"; then :
+  gconfig_cv_uds_len=yes
+else
+  gconfig_cv_uds_len=no
+fi
+rm -f core conftest.err conftest.$ac_objext conftest.$ac_ext
+
+fi
+{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $gconfig_cv_uds_len" >&5
+$as_echo "$gconfig_cv_uds_len" >&6; }
+	if test "$gconfig_cv_uds_len" = "yes"
+	then
+
+$as_echo "#define GCONFIG_HAVE_UDS_LEN 1" >>confdefs.h
+
+	else
+
+$as_echo "#define GCONFIG_HAVE_UDS_LEN 0" >>confdefs.h
+
+	fi
+
+
+
 
 
 
@@ -8039,6 +8147,7 @@ main ()
 {
 
 			errno_t e = _sopen_s(&fd,"foo",_O_WRONLY,_SH_DENYNO,_S_IWRITE) ;
+			if( e ) return 1 ;
 
   ;
   return 0;
@@ -8954,7 +9063,7 @@ if ${gconfig_cv_qt_build+:} false; then :
   $as_echo_n "(cached) " >&6
 else
 
-	if test "$gconfig_have_qt" = "yes"
+	if test "$gconfig_have_qt" = "yes" -a "$enable_gui" != "no"
 	then
 		gconfig_save_LIBS="$LIBS"
 		gconfig_save_CXXFLAGS="$CXXFLAGS"
@@ -9207,7 +9316,6 @@ $as_echo "#define GCONFIG_HAVE_MBEDTLS_NET_H 0" >>confdefs.h
 	fi
 
 
-
 # Check whether --enable-bsd was given.
 if test "${enable_bsd+set}" = set; then :
   enableval=$enable_bsd;
@@ -9245,7 +9353,7 @@ if test "${enable_epoll+set}" = set; then :
 fi
 
 
-	if test "$enable_epoll" = "yes"
+	if test "$enable_epoll" != "no"
 	then
 		if test "$gconfig_cv_epoll" = "no"
 		then
@@ -9479,6 +9587,66 @@ else
 fi
 
 
+# Check whether --enable-uds was given.
+if test "${enable_uds+set}" = set; then :
+  enableval=$enable_uds;
+fi
+
+
+
+	if test "$enable_uds" = "no"
+	then
+		 if false; then
+  GCONFIG_UDS_TRUE=
+  GCONFIG_UDS_FALSE='#'
+else
+  GCONFIG_UDS_TRUE='#'
+  GCONFIG_UDS_FALSE=
+fi
+
+	else
+		if test "$enable_uds" = "yes" -a "$gconfig_cv_uds" = "no"
+		then
+			{ $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: forcing use of unix domain sockets even though not detected" >&5
+$as_echo "$as_me: WARNING: forcing use of unix domain sockets even though not detected" >&2;}
+		fi
+		 if true; then
+  GCONFIG_UDS_TRUE=
+  GCONFIG_UDS_FALSE='#'
+else
+  GCONFIG_UDS_TRUE='#'
+  GCONFIG_UDS_FALSE=
+fi
+
+	fi
+
+# Check whether --enable-dnsbl was given.
+if test "${enable_dnsbl+set}" = set; then :
+  enableval=$enable_dnsbl;
+fi
+
+
+	if test "$enable_dnsbl" = "no"
+	then
+		 if false; then
+  GCONFIG_DNSBL_TRUE=
+  GCONFIG_DNSBL_FALSE='#'
+else
+  GCONFIG_DNSBL_TRUE='#'
+  GCONFIG_DNSBL_FALSE=
+fi
+
+	else
+		 if true; then
+  GCONFIG_DNSBL_TRUE=
+  GCONFIG_DNSBL_FALSE='#'
+else
+  GCONFIG_DNSBL_TRUE='#'
+  GCONFIG_DNSBL_FALSE=
+fi
+
+	fi
+
 
 
 # Check whether --with-doxygen was given.
@@ -9505,11 +9673,7 @@ if test "${with_gettext+set}" = set; then :
 fi
 
 
-	if test "$with_gettext" = "no"
+	if test "$with_gettext" = "yes"
-	then
-		gconfig_cv_gettext="no"
-	:
-	elif test "$with_gettext" = "yes"
 	then
 		if test "$gconfig_cv_gettext" = "no"
 		then
@@ -9517,6 +9681,8 @@ fi
 $as_echo "$as_me: WARNING: forcing use of gettext even though not detected" >&2;}
 			gconfig_cv_gettext="yes"
 		fi
+	else
+		gconfig_cv_gettext="no"
 	fi
 
 	if test "$gconfig_cv_gettext" = "yes" ; then
@@ -9627,7 +9793,7 @@ fi
 		GCONFIG_TLS_LIBS=""
 	fi
 
-	if test "$gconfig_ssl_use_none" = "yes" -a "$with_openssl" != "no"
+	if test "$gconfig_ssl_use_none" = "yes"
 	then
 		gconfig_warnings="$gconfig_warnings openssl/mbedtls_transport_layer_security"
 	fi
@@ -10014,40 +10180,6 @@ fi
 
 
 
-# Check whether --with-uds was given.
-if test "${with_uds+set}" = set; then :
-  withval=$with_uds;
-fi
-
-
-
-	if test "$with_uds" = "no"
-	then
-		 if false; then
-  GCONFIG_UDS_TRUE=
-  GCONFIG_UDS_FALSE='#'
-else
-  GCONFIG_UDS_TRUE='#'
-  GCONFIG_UDS_FALSE=
-fi
-
-	else
-		if test "$with_uds" = "yes" -a "$gconfig_cv_uds" = "no"
-		then
-			{ $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: forcing use of unix domain sockets even though not detected" >&5
-$as_echo "$as_me: WARNING: forcing use of unix domain sockets even though not detected" >&2;}
-		fi
-		 if true; then
-  GCONFIG_UDS_TRUE=
-  GCONFIG_UDS_FALSE='#'
-else
-  GCONFIG_UDS_TRUE='#'
-  GCONFIG_UDS_FALSE=
-fi
-
-	fi
-
-
 
 	if test "$e_libexecdir" = ""
 	then
@@ -10124,7 +10256,7 @@ fi
 
 
 
-ac_config_files="$ac_config_files Makefile src/Makefile src/glib/Makefile src/gssl/Makefile src/gnet/Makefile src/gauth/Makefile src/gsmtp/Makefile src/gpop/Makefile src/main/Makefile src/main/icon/Makefile src/win32/Makefile src/gui/Makefile bin/Makefile doc/Makefile etc/Makefile test/Makefile test/certificates/Makefile m4/Makefile bsd/Makefile debian/Makefile po/Makefile"
+ac_config_files="$ac_config_files Makefile src/Makefile src/glib/Makefile src/gssl/Makefile src/gnet/Makefile src/gauth/Makefile src/gsmtp/Makefile src/gpop/Makefile src/main/Makefile src/main/icon/Makefile src/win32/Makefile src/gui/Makefile bin/Makefile doc/Makefile etc/Makefile test/Makefile test/certificates/Makefile m4/Makefile bsd/Makefile debian/Makefile po/Makefile unity/Makefile"
 
 cat >confcache <<\_ACEOF
 # This file is a shell script that caches the results of configure
@@ -10299,6 +10431,22 @@ if test -z "${GCONFIG_WINDOWS_TRUE}" && test -z "${GCONFIG_WINDOWS_FALSE}"; then
   as_fn_error $? "conditional \"GCONFIG_WINDOWS\" was never defined.
 Usually this means the macro was only invoked conditionally." "$LINENO" 5
 fi
+if test -z "${GCONFIG_UDS_TRUE}" && test -z "${GCONFIG_UDS_FALSE}"; then
+  as_fn_error $? "conditional \"GCONFIG_UDS\" was never defined.
+Usually this means the macro was only invoked conditionally." "$LINENO" 5
+fi
+if test -z "${GCONFIG_UDS_TRUE}" && test -z "${GCONFIG_UDS_FALSE}"; then
+  as_fn_error $? "conditional \"GCONFIG_UDS\" was never defined.
+Usually this means the macro was only invoked conditionally." "$LINENO" 5
+fi
+if test -z "${GCONFIG_DNSBL_TRUE}" && test -z "${GCONFIG_DNSBL_FALSE}"; then
+  as_fn_error $? "conditional \"GCONFIG_DNSBL\" was never defined.
+Usually this means the macro was only invoked conditionally." "$LINENO" 5
+fi
+if test -z "${GCONFIG_DNSBL_TRUE}" && test -z "${GCONFIG_DNSBL_FALSE}"; then
+  as_fn_error $? "conditional \"GCONFIG_DNSBL\" was never defined.
+Usually this means the macro was only invoked conditionally." "$LINENO" 5
+fi
 if test -z "${GCONFIG_GETTEXT_TRUE}" && test -z "${GCONFIG_GETTEXT_FALSE}"; then
   as_fn_error $? "conditional \"GCONFIG_GETTEXT\" was never defined.
 Usually this means the macro was only invoked conditionally." "$LINENO" 5
@@ -10323,14 +10471,6 @@ if test -z "${GCONFIG_PAM_TRUE}" && test -z "${GCONFIG_PAM_FALSE}"; then
   as_fn_error $? "conditional \"GCONFIG_PAM\" was never defined.
 Usually this means the macro was only invoked conditionally." "$LINENO" 5
 fi
-if test -z "${GCONFIG_UDS_TRUE}" && test -z "${GCONFIG_UDS_FALSE}"; then
-  as_fn_error $? "conditional \"GCONFIG_UDS\" was never defined.
-Usually this means the macro was only invoked conditionally." "$LINENO" 5
-fi
-if test -z "${GCONFIG_UDS_TRUE}" && test -z "${GCONFIG_UDS_FALSE}"; then
-  as_fn_error $? "conditional \"GCONFIG_UDS\" was never defined.
-Usually this means the macro was only invoked conditionally." "$LINENO" 5
-fi
 
 : "${CONFIG_STATUS=./config.status}"
 ac_write_fail=0
@@ -10728,7 +10868,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by E-MailRelay $as_me 2.3.1, which was
+This file was extended by E-MailRelay $as_me 2.4, which was
 generated by GNU Autoconf 2.69.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -10794,7 +10934,7 @@ _ACEOF
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
 ac_cs_version="\\
-E-MailRelay config.status 2.3.1
+E-MailRelay config.status 2.4
 configured by $0, generated by GNU Autoconf 2.69,
   with options \\"\$ac_cs_config\\"
 
@@ -10946,6 +11086,7 @@ do
     "bsd/Makefile") CONFIG_FILES="$CONFIG_FILES bsd/Makefile" ;;
     "debian/Makefile") CONFIG_FILES="$CONFIG_FILES debian/Makefile" ;;
     "po/Makefile") CONFIG_FILES="$CONFIG_FILES po/Makefile" ;;
+    "unity/Makefile") CONFIG_FILES="$CONFIG_FILES unity/Makefile" ;;
 
   *) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;;
   esac

configure.ac

@@ -1,4 +1,4 @@
-dnl Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+dnl Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 dnl 
 dnl This program is free software: you can redistribute it and/or modify
 dnl it under the terms of the GNU General Public License as published by
@@ -19,7 +19,7 @@ dnl
 dnl Process this file with autoconf to produce a configure script.
 dnl
 
-AC_INIT([E-MailRelay],[2.3.1],[],[emailrelay])
+AC_INIT([E-MailRelay],[2.4],[],[emailrelay])
 AC_CONFIG_SRCDIR([src/glib/gdef.h])
 AC_CONFIG_MACRO_DIR([m4])
 AM_INIT_AUTOMAKE([no-define])
@@ -71,18 +71,13 @@ GCONFIG_FN_QT_BUILD
 GCONFIG_FN_TLS_OPENSSL
 GCONFIG_FN_TLS_MBEDTLS
 
-dnl possibly enable full gettext support -- uncomment this after running
-dnl 'gettextize' and remove the other gettext lines below
-dnl
-dnl AM_GNU_GETTEXT([external])
-
 dnl "--enable-whatever"
 dnl
 AC_ARG_ENABLE([bsd],AS_HELP_STRING([--enable-bsd],[enable building for bsd (default auto)]))
 GCONFIG_FN_ENABLE_BSD
 AC_ARG_ENABLE([debug],AS_HELP_STRING([--enable-debug],[enable extra debug messages at compile-time (default no)]))
 GCONFIG_FN_ENABLE_DEBUG
-AC_ARG_ENABLE([epoll],AS_HELP_STRING([--enable-epoll],[enable epoll (default no)]))
+AC_ARG_ENABLE([epoll],AS_HELP_STRING([--enable-epoll],[enable epoll (default auto)]))
 GCONFIG_FN_ENABLE_EPOLL
 AC_ARG_ENABLE([gui],AS_HELP_STRING([--enable-gui],[enable configuration gui (requires Qt) (default auto)]))
 GCONFIG_FN_ENABLE_GUI
@@ -100,6 +95,10 @@ AC_ARG_ENABLE([verbose],AS_HELP_STRING([--enable-verbose],[enable verbose loggin
 GCONFIG_FN_ENABLE_VERBOSE
 AC_ARG_ENABLE([windows],AS_HELP_STRING([--enable-windows],[enable building for windows (default auto)]))
 GCONFIG_FN_ENABLE_WINDOWS
+AC_ARG_ENABLE([uds],AS_HELP_STRING([--enable-uds],[enable unix domain sockets (default auto)]))
+GCONFIG_FN_ENABLE_UDS
+AC_ARG_ENABLE([dnsbl],AS_HELP_STRING([--enable-dnsbl],[enable DNSBL (default yes)]))
+GCONFIG_FN_ENABLE_DNSBL
 
 dnl "--with-whatever"
 dnl
@@ -114,8 +113,6 @@ AC_ARG_WITH([mbedtls],AS_HELP_STRING([--with-mbedtls],[use mbedtls for tls layer
 GCONFIG_FN_TLS
 AC_ARG_WITH([pam],AS_HELP_STRING([--with-pam],[use linux pam for authentication (default auto)]))
 GCONFIG_FN_WITH_PAM
-AC_ARG_WITH([uds],AS_HELP_STRING([--with-uds],[enable unix domain sockets (default auto)]))
-GCONFIG_FN_WITH_UDS
 
 dnl directory tweaking -- define e_ prefixed directory variables
 dnl
@@ -124,7 +121,7 @@ GCONFIG_FN_SET_DIRECTORIES_E
 
 dnl generate files
 dnl
-AC_CONFIG_FILES([Makefile src/Makefile src/glib/Makefile src/gssl/Makefile src/gnet/Makefile src/gauth/Makefile src/gsmtp/Makefile src/gpop/Makefile src/main/Makefile src/main/icon/Makefile src/win32/Makefile src/gui/Makefile bin/Makefile doc/Makefile etc/Makefile test/Makefile test/certificates/Makefile m4/Makefile bsd/Makefile debian/Makefile po/Makefile])
+AC_CONFIG_FILES([Makefile src/Makefile src/glib/Makefile src/gssl/Makefile src/gnet/Makefile src/gauth/Makefile src/gsmtp/Makefile src/gpop/Makefile src/main/Makefile src/main/icon/Makefile src/win32/Makefile src/gui/Makefile bin/Makefile doc/Makefile etc/Makefile test/Makefile test/certificates/Makefile m4/Makefile bsd/Makefile debian/Makefile po/Makefile unity/Makefile])
 AC_OUTPUT
 
 dnl final warnings

configure.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -31,8 +31,8 @@
 #         -w64 cross-compile for windows 64-bit with mingw-w64
 #         -p   cross-compile for rpi
 #         -g   git-clone mbedtls and exit
-#
+#         -S   force e_systemddir for systemd
-# For systemd add "e_systemddir=/usr/lib/systemd/system".
+#         -X   suppress e_systemddir for systemd
 #
 # When cross-compiling with mbedtls the mbedtls source should be unpacked
 # into this base directory (see MBEDTLS_DIR below), or use '-g' to
@@ -42,6 +42,7 @@
 thisdir="`cd \`dirname $0\` && pwd`"
 
 usage="[-g] [{-d|-s <>}] [{-o|-w|-p}] -- <configure-args>"
+opt_systemd=0 ; if test "`systemctl is-system-running 2>/dev/null | sed 's/offline//'`" != "" ; then opt_systemd=1 ; fi
 while expr "x$1" : "x-" >/dev/null
 do
 	valued=0
@@ -54,6 +55,8 @@ do
 		w32) opt_mingw=1 ; opt_win=32 ;;
 		w64) opt_mingw=1 ; opt_win=64 ;;
 		p) opt_rpi=1 ;;
+		S) opt_systemd=1 ;;
+		X) opt_systemd=0 ;;
 		h) echo usage: `basename $0` $usage "..." ; $thisdir/configure --help=short ; exit 0 ;;
 		#\?) echo usage: `basename $0` $usage >&2 ; exit 2 ;;
 		*) opt_passthrough="$opt_passthrough $1" ;;
@@ -90,7 +93,7 @@ if test "0$opt_debug" -eq 1
 then
 	export CFLAGS="-O0 -g"
 	export CXXFLAGS="-O0 -g"
-	if expr "x$*" : '.*enable.debug' ; then : ; else enable_debug="--enable-debug" ; fi
+	if expr "x$*" : '.*enable.debug' >/dev/null ; then : ; else enable_debug="--enable-debug" ; fi
 :
 elif expr "x$*" : '.*enable.debug' >/dev/null
 then
@@ -241,6 +244,15 @@ then
 	$thisdir/configure $enable_debug $with_mbedtls \
 		--prefix=/opt/local --mandir=/opt/local/man $opt_passthrough "$@"
 :
+elif test "`uname`" = "Linux" -a "$opt_systemd" -eq 1
+then
+	export CXXFLAGS
+	export LDFLAGS
+	$thisdir/configure $enable_debug $with_mbedtls \
+		--prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc \
+		--localstatedir=/var e_systemddir=/usr/lib/systemd/system \
+		$opt_passthrough e_rundir=/run/emailrelay "$@"
+:
 elif test "`uname`" = "Linux"
 then
 	export CXXFLAGS

debian/Makefile.am

@@ -1,5 +1,5 @@
 #
-## Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+## Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 ## 
 ## This program is free software: you can redistribute it and/or modify
 ## it under the terms of the GNU General Public License as published by

debian/changelog

@@ -1,16 +1,23 @@
-emailrelay (2.3.1) unstable; urgency=low
+emailrelay (2.4) unstable; urgency=low
-  * Hourly log file rotation using "%h" (eg. "--log-file=log.%d.%h").
+  * Multiple "--filter" and "--client-filter" options allowed.
   * TLS key and certificate files can be specified separately.
-  * Fixed error handling for network client filters ("--client-filter=net:...") [bug-id 50].
+  * Finer control when using "--anonymous" (eg. "--anonymous=server").
- -- maintainer graeme_walker <graeme_walker@users.sourceforge.net>  Thu, 30 Jun 2022 00:00:00 +0000
+  * The "auth-config" options can distinguish between TLS and non-TLS authentication.
+  * Hourly log file rotation using "%h" (eg. "--log-file=log.%d.%h").
+  * Listening file descriptors can be inherited from the parent process (see "--interface").
+  * Listening ports on Windows use exclusive binding.
+  * The Linux event loop uses "epoll" by default rather than "select".
+  * Some support for message routing (see NEWS).
+  * Fix of error handling in network client filters ("--client-filter=net:...") [bug-id #50].
+ -- maintainer graeme_walker <graeme_walker@users.sourceforge.net>  Fri, 28 Oct 2022 00:00:00 +0000
 
 emailrelay (2.3) unstable; urgency=low
   * Unix domain sockets supported (eg. "--interface=/tmp/smtp.s").
   * Windows event log not used for verbose logging (prefer "--log-file").
-  * New admin 'forward' command to trigger forwarding without waiting.
+  * New admin "forward" command to trigger forwarding without waiting.
   * Optional base64 encoding of passwords in secrets files ("plain:b").
   * Support for MbedTLS version 3.
- -- maintainer graeme_walker <graeme_walker@users.sourceforge.net>  Tue, 14 Feb 2022 00:00:00 +0000
+ -- maintainer graeme_walker <graeme_walker@users.sourceforge.net>  Sun, 10 Apr 2022 00:00:00 +0000
 
 emailrelay (2.2) unstable; urgency=low
   * Connections from IPv4 'private use' addresses are allowed by default (see "--remote-clients").

debian/control

@@ -2,7 +2,7 @@ Source: emailrelay
 Section: mail
 Priority: optional
 Maintainer: Graeme Walker <graeme_walker@users.sourceforge.net>
-Build-Depends: debhelper (>= 9), autotools-dev
+Build-Depends: debhelper (>= 9), autotools-dev, libssl-dev, libpam0g-dev
 Standards-Version: 3.9.8
 Homepage: http://emailrelay.sourceforge.net
 

debian/copyright

@@ -1,6 +1,6 @@
 Copyright
 =========
-Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 
 Refer to the file COPYING (included), /usr/share/common-licenses/GPL-3, or
 <http://www.gnu.org/licenses/> for the terms of the GNU General Public License.

debian/emailrelay.init

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

debian/emailrelay.service

@@ -8,10 +8,9 @@ Wants=network-online.target
 Type=forking
 Restart=on-success
 KillMode=control-group
-ExecStart=/etc/init.d/emailrelay start
+ExecStart=/usr/sbin/emailrelay --as-server --syslog --pid-file /run/emailrelay/emailrelay.pid /etc/emailrelay.conf
-ExecStop=/etc/init.d/emailrelay stop
+ExecStop=/bin/kill -15 $MAINPID
 PIDFile=/run/emailrelay/emailrelay.pid
-SuccessExitStatus=0 143
 
 [Install]
 WantedBy=multi-user.target

doc/Makefile.am

@@ -1,5 +1,5 @@
 #
-## Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+## Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 ## 
 ## This program is free software: you can redistribute it and/or modify
 ## it under the terms of the GNU General Public License as published by

doc/authentication.svg

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
 
 <svg
    xmlns:dc="http://purl.org/dc/elements/1.1/"

doc/changelog.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "%-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay Change Log</title>
@@ -9,21 +9,28 @@
   <!-- index:0::::E-MailRelay Change Log -->
  <div class="div-main">
   <h1><a class="a-header" name="H_1">E-MailRelay Change Log</a></h1> <!-- index:1:H:E-MailRelay Change Log -->
-   <h2><a class="a-header" name="SH_1_0">2.3 -> 2.3.1</a></h2> <!-- index:2:SH:1:0:2.3 -> 2.3.1 -->
+   <h2><a class="a-header" name="SH_1_1">2.3 -> 2.4</a></h2> <!-- index:2:SH:1:1:2.3 -> 2.4 -->
     <ul>
-     <li>Hourly log file rotation using <em>%h</em> (eg. <em>--log-file=log.%d.%h</em>).</li>
+     <li>Multiple <em>--filter</em> and <em>--client-filter</em> options allowed.</li>
      <li>TLS key and certificate files can be specified separately.</li>
-     <li>Fixed error handling for network client filters (<em>--client-filter=net:...</em>) [bug-id #50].</li>
+     <li>Finer control when using <em>--anonymous</em> (eg. <em>--anonymous=server</em>).</li>
+     <li>The <em>auth-config</em> options can distinguish between TLS and non-TLS authentication.</li>
+     <li>Hourly log file rotation using <em>%h</em> (eg. <em>--log-file=log.%d.%h</em>).</li>
+     <li>Listening file descriptors can be inherited from the parent process (see <em>--interface</em>).</li>
+     <li>Listening ports on Windows use exclusive binding.</li>
+     <li>The Linux event loop uses <em>epoll</em> by default rather than <em>select</em>.</li>
+     <li>Some support for message routing (see NEWS).</li>
+     <li>Fix of error handling in network client filters (<em>--client-filter=net:...</em>) [bug-id #50].</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_1">2.2 -> 2.3</a></h2> <!-- index:2:SH:1:1:2.2 -> 2.3 -->
+   <h2><a class="a-header" name="SH_1_2">2.2 -> 2.3</a></h2> <!-- index:2:SH:1:2:2.2 -> 2.3 -->
     <ul>
-     <li>Unix domain sockets supported (eg. <em>--interface=/tmp/smtp.s</em>.</li>
+     <li>Unix domain sockets supported (eg. <em>--interface=/tmp/smtp.s</em>).</li>
      <li>Windows event log not used for verbose logging (prefer <em>--log-file</em>).</li>
      <li>New admin <em>forward</em> command to trigger forwarding without waiting.</li>
      <li>Optional base64 encoding of passwords in secrets files (<em>plain:b</em>).</li>
      <li>Support for MbedTLS version 3.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_2">2.1 -> 2.2</a></h2> <!-- index:2:SH:1:2:2.1 -> 2.2 -->
+   <h2><a class="a-header" name="SH_1_3">2.1 -> 2.2</a></h2> <!-- index:2:SH:1:3:2.1 -> 2.2 -->
     <ul>
      <li>Connections from IPv4 'private use' addresses are allowed by default (see <em>--remote-clients</em>).</li>
      <li>Interface names can be used with <em>--interface</em> (eg. <em>--interface=eth0</em>).</li>
@@ -39,7 +46,7 @@
      <li>Support for Windows XP restored when built with mingw-w64.</li>
      <li>C++ 2011 compiler is required.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_3">2.0.1 -> 2.1</a></h2> <!-- index:2:SH:1:3:2.0.1 -> 2.1 -->
+   <h2><a class="a-header" name="SH_1_4">2.0.1 -> 2.1</a></h2> <!-- index:2:SH:1:4:2.0.1 -> 2.1 -->
     <ul>
      <li>Backwards compatibility features for 1.9-to-2.0 transition removed.</li>
      <li>Better handling of too-many-connections on Windows.</li>
@@ -56,11 +63,11 @@
      <li>Certificate contents are not logged.</li>
      <li>Timestamp parts of spool filenames no longer limited to six digits.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_4">2.0 -> 2.0.1</a></h2> <!-- index:2:SH:1:4:2.0 -> 2.0.1 -->
+   <h2><a class="a-header" name="SH_1_5">2.0 -> 2.0.1</a></h2> <!-- index:2:SH:1:5:2.0 -> 2.0.1 -->
     <ul>
      <li>Make PLAIN client authentication work against servers with broken 334 responses.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_5">1.9.2 -> 2.0</a></h2> <!-- index:2:SH:1:5:1.9.2 -> 2.0 -->
+   <h2><a class="a-header" name="SH_1_6">1.9.2 -> 2.0</a></h2> <!-- index:2:SH:1:6:1.9.2 -> 2.0 -->
     <ul>
      <li>Improved IPv6 support, with IPv4 and IPv6 used independently at run-time (see <em>--interface</em>).</li>
      <li>Server process is not blocked during <em>--filter</em> or <em>--address-verifier</em> execution, if multi-threaded.</li>
@@ -91,7 +98,7 @@
      <li>C++ 2011 is preferred, and required for multi-threading.</li>
      <li>Support for very old versions of Windows is dropped.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_6">1.9.1 -> 1.9.2</a></h2> <!-- index:2:SH:1:6:1.9.1 -> 1.9.2 -->
+   <h2><a class="a-header" name="SH_1_7">1.9.1 -> 1.9.2</a></h2> <!-- index:2:SH:1:7:1.9.1 -> 1.9.2 -->
     <ul>
      <li>Fixed a leak in the event-loop garbage collection.</li>
      <li>A local hostname that fails to resolve is not an error.</li>
@@ -107,11 +114,11 @@
      <li>Qt4 or Qt5 selected by the <em>configure</em> script.</li>
      <li>Improved the RPM spec file.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_7">1.9 -> 1.9.1</a></h2> <!-- index:2:SH:1:7:1.9 -> 1.9.1 -->
+   <h2><a class="a-header" name="SH_1_8">1.9 -> 1.9.1</a></h2> <!-- index:2:SH:1:8:1.9 -> 1.9.1 -->
     <ul>
      <li>Updated OpenSSL from 1.0.1e to 1.0.1g in the Windows build.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_8">1.8.2 -> 1.9</a></h2> <!-- index:2:SH:1:8:1.8.2 -> 1.9 -->
+   <h2><a class="a-header" name="SH_1_9">1.8.2 -> 1.9</a></h2> <!-- index:2:SH:1:9:1.8.2 -> 1.9 -->
     <ul>
      <li>Added negotiated TLS/SSL for POP (ie. <em>STLS</em>).</li>
      <li>The first two fields in the secrets files are reordered (with backwards compatibility).</li>
@@ -136,17 +143,17 @@
      <li>Added Windows <em>--peer-lookup</em> option.</li>
      <li>Fix for MD5 code in 64-bit builds.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_9">1.8.1 -> 1.8.2</a></h2> <!-- index:2:SH:1:9:1.8.1 -> 1.8.2 -->
+   <h2><a class="a-header" name="SH_1_10">1.8.1 -> 1.8.2</a></h2> <!-- index:2:SH:1:10:1.8.1 -> 1.8.2 -->
     <ul>
      <li>Fix namespaces for gcc 3.4.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_10">1.8 -> 1.8.1</a></h2> <!-- index:2:SH:1:10:1.8 -> 1.8.1 -->
+   <h2><a class="a-header" name="SH_1_11">1.8 -> 1.8.1</a></h2> <!-- index:2:SH:1:11:1.8 -> 1.8.1 -->
     <ul>
      <li>Changed the definition of <em>--as-proxy</em> to use <em>--poll 0</em> rather than <em>--immediate</em> [bug-id 1961652].</li>
      <li>Fixed stalling bug when using server-side TLS/SSL (<em>--server-tls</em>) [bug-id 1961655].</li>
      <li>Improved Debian packaging for Linux (<em>make deb</em>).</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_11">1.7 -> 1.8</a></h2> <!-- index:2:SH:1:11:1.7 -> 1.8 -->
+   <h2><a class="a-header" name="SH_1_12">1.7 -> 1.8</a></h2> <!-- index:2:SH:1:12:1.7 -> 1.8 -->
     <ul>
      <li>Speed optimisations (as identified by KCachegrind/valgrind in KDevelop).</li>
      <li>Build-time size optimisations (eg. <em>./configure --disable-exec --enable-small-exceptions ...</em>).</li>
@@ -162,7 +169,7 @@
      <li>Improved native support for Mac OS X (10.5) with graphical installation from disk image.</li>
      <li>Compatibility with gcc 2.95 restored.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_12">1.6 -> 1.7</a></h2> <!-- index:2:SH:1:12:1.6 -> 1.7 -->
+   <h2><a class="a-header" name="SH_1_13">1.6 -> 1.7</a></h2> <!-- index:2:SH:1:13:1.6 -> 1.7 -->
     <ul>
      <li>TLS/SSL support for SMTP using OpenSSL (<em>./configure --with-openssl</em> with <em>--client-tls</em> and <em>--server-tls</em>).</li>
      <li>Authentication mechanism <em>PLAIN</em> added.</li>
@@ -170,7 +177,7 @@
      <li>Windows service wrapper has an <em>--uninstall</em> option.</li>
      <li>Windows installation GUI uninstalls the service before reinstalling it.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_13">1.5 -> 1.6</a></h2> <!-- index:2:SH:1:13:1.5 -> 1.6 -->
+   <h2><a class="a-header" name="SH_1_14">1.5 -> 1.6</a></h2> <!-- index:2:SH:1:14:1.5 -> 1.6 -->
     <ul>
      <li>GPLv3 licence (see <em>http://gplv3.fsf.org</em>).</li>
      <li>New <em>--prompt-timeout</em> switch for the timeout when waiting for the initial 220 prompt from the SMTP server.</li>
@@ -190,7 +197,7 @@
      <li>Experimental SpamAssassin spamc/spamd protocol support.</li>
      <li>Acceptance tests added to the distribution.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_14">1.4 -> 1.5</a></h2> <!-- index:2:SH:1:14:1.4 -> 1.5 -->
+   <h2><a class="a-header" name="SH_1_15">1.4 -> 1.5</a></h2> <!-- index:2:SH:1:15:1.4 -> 1.5 -->
     <ul>
      <li>New installation and configuration GUI using TrollTech Qt 4.x (<em>./configure --enable-gui</em>)</li>
      <li>Default address verifier accepts all addresses as valid and never treats them as local mailboxes.</li>
@@ -205,7 +212,7 @@
      <li>Documentation also created in docbook format (requires xmlto).</li>
      <li>Windows installation document revised.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_15">1.3.3 -> 1.4</a></h2> <!-- index:2:SH:1:15:1.3.3 -> 1.4 -->
+   <h2><a class="a-header" name="SH_1_16">1.3.3 -> 1.4</a></h2> <!-- index:2:SH:1:16:1.3.3 -> 1.4 -->
     <ul>
      <li>POP3 server (enable with <em>--pop</em>, disable at build-time with <em>./configure --disable-pop</em>).</li>
      <li>Fix for logging reentrancy bug (affects <em>./configure --enable-debug</em> with <em>--debug</em>).</li>
@@ -219,7 +226,7 @@
      <li>The <em>--dont-listen</em> switch is now <em>--no-smtp</em>.</li>
      <li>Better IPv6 support (Linux only).</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_16">1.3.2 -> 1.3.3</a></h2> <!-- index:2:SH:1:16:1.3.2 -> 1.3.3 -->
+   <h2><a class="a-header" name="SH_1_17">1.3.2 -> 1.3.3</a></h2> <!-- index:2:SH:1:17:1.3.2 -> 1.3.3 -->
     <ul>
      <li>No bind() for outgoing connections [bug-id 1051689].</li>
      <li>Updated rpm spec file [bug-id 1224850].</li>
@@ -228,21 +235,21 @@
      <li>Documentation of <em>auth</em> switches corrected.</li>
      <li>State-machine template type declaration modernised, possibly breaking older compilers.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_17">1.3.1 -> 1.3.2</a></h2> <!-- index:2:SH:1:17:1.3.1 -> 1.3.2 -->
+   <h2><a class="a-header" name="SH_1_18">1.3.1 -> 1.3.2</a></h2> <!-- index:2:SH:1:18:1.3.1 -> 1.3.2 -->
     <ul>
      <li>Fix for core dump when <em>--client-filter</em> pre-processing fails.</li>
      <li>Revised code structure to prepare for asynchronous pre-processing.</li>
      <li>Better diagnostics when pre-processor exec() fails.</li>
      <li>Better cleanup of empty and orphaned files.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_18">1.3 -> 1.3.1</a></h2> <!-- index:2:SH:1:18:1.3 -> 1.3.1 -->
+   <h2><a class="a-header" name="SH_1_19">1.3 -> 1.3.1</a></h2> <!-- index:2:SH:1:19:1.3 -> 1.3.1 -->
     <ul>
      <li>Windows resource leak from CreateProcess() fixed.</li>
      <li>Windows dialog box double-close fix.</li>
      <li>Some documentation for the <em>--scanner</em> switch.</li>
      <li>New usage patterns section in the user guide.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_19">1.2 -> 1.3</a></h2> <!-- index:2:SH:1:19:1.2 -> 1.3 -->
+   <h2><a class="a-header" name="SH_1_20">1.2 -> 1.3</a></h2> <!-- index:2:SH:1:20:1.2 -> 1.3 -->
     <ul>
      <li>Client protocol waits for a greeting from the server on startup [bug-id 842156].</li>
      <li>Fix for incorrect backslash normalisation on <em>--verifier</em> command-lines containing spaces [bug-id 890646].</li>
@@ -255,7 +262,7 @@
      <li>New switches for the <em>configure</em> script.</li>
      <li>More JavaScript example scripts.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_20">1.1.2 -> 1.2</a></h2> <!-- index:2:SH:1:20:1.1.2 -> 1.2 -->
+   <h2><a class="a-header" name="SH_1_21">1.1.2 -> 1.2</a></h2> <!-- index:2:SH:1:21:1.1.2 -> 1.2 -->
     <ul>
      <li>The <em>--filter</em> and <em>--verifier</em> arguments interpreted as command-lines; spaces in executable paths now need escaping.</li>
      <li>The <em>--interface</em> switch applies to outgoing connections too.</li>
@@ -264,7 +271,7 @@
      <li>Fix for dangling reference bug, seen after <em>quit</em> command on Windows.</li>
      <li>JavaScript examples in the documentation.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_21">1.1.1 -> 1.1.2</a></h2> <!-- index:2:SH:1:21:1.1.1 -> 1.1.2 -->
+   <h2><a class="a-header" name="SH_1_22">1.1.1 -> 1.1.2</a></h2> <!-- index:2:SH:1:22:1.1.1 -> 1.1.2 -->
     <ul>
      <li>Earlier check for un-bindable ports on startup, and later fork()ing [bug-id 776972].</li>
      <li>Resolved the file-descriptor kludge for <em>--verifier</em> on Windows.</li>
@@ -273,7 +280,7 @@
      <li>Pre-processor (<em>--filter</em>) program's standard output searched for a failure reason string.</li>
      <li>Undocumented <em>--scanner</em> switch added for asynchronous processing by a separate network server.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_22">1.1.0 -> 1.1.1</a></h2> <!-- index:2:SH:1:22:1.1.0 -> 1.1.1 -->
+   <h2><a class="a-header" name="SH_1_23">1.1.0 -> 1.1.1</a></h2> <!-- index:2:SH:1:23:1.1.0 -> 1.1.1 -->
     <ul>
      <li>Restored the fix for building with gcc2.96.</li>
      <li>Support for MinGW builds on Windows.</li>
@@ -283,7 +290,7 @@
      <li>Fix for <em>make install</em> when <em>man2html</em> is not available.</li>
      <li>Updated init script.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_23">1.0.2 -> 1.1.0</a></h2> <!-- index:2:SH:1:23:1.0.2 -> 1.1.0 -->
+   <h2><a class="a-header" name="SH_1_24">1.0.2 -> 1.1.0</a></h2> <!-- index:2:SH:1:24:1.0.2 -> 1.1.0 -->
     <ul>
      <li>In proxy mode unexpected client-side disconnects and timeouts do not leave <em>.bad</em> files [see also bug-id 659039].</li>
      <li>By default proxy mode does not interpret addresses for local delivery (<em>--postmaster</em>).</li>
@@ -298,14 +305,14 @@
      <li>Support for Sun WorkShop 5.0 added.</li>
      <li>Documentation overhaul.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_24">1.0.0 -> 1.0.2</a></h2> <!-- index:2:SH:1:24:1.0.0 -> 1.0.2 -->
+   <h2><a class="a-header" name="SH_1_25">1.0.0 -> 1.0.2</a></h2> <!-- index:2:SH:1:25:1.0.0 -> 1.0.2 -->
     <ul>
      <li>Support for trusted IP addresses, allowing certain clients to avoid authentication.</li>
      <li>Address verifier interface extended to include authentication information.</li>
      <li>New public mail relay section added to the user guide.</li>
      <li>Example verifier scripts etc. added to the reference guide.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_25">1.0.0 -> 1.0.1</a></h2> <!-- index:2:SH:1:25:1.0.0 -> 1.0.1 -->
+   <h2><a class="a-header" name="SH_1_26">1.0.0 -> 1.0.1</a></h2> <!-- index:2:SH:1:26:1.0.0 -> 1.0.1 -->
     <ul>
      <li>In proxy mode unexpected client-side disconnects and timeouts result in <em>.bad</em> files [bug-id 659039].</li>
      <li>Require successful <em>AUTH</em> before <em>MAIL FROM</em> when using <em>--server-auth</em>.</li>
@@ -318,7 +325,7 @@
      <li>Fix build when using gcc2.96 rather than gcc2.95 (1.0.0-pl1).</li>
      <li>Fix default spool directory in example scripts (1.0.0-pl1).</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_26">0.9.9 -> 1.0.0</a></h2> <!-- index:2:SH:1:26:0.9.9 -> 1.0.0 -->
+   <h2><a class="a-header" name="SH_1_27">0.9.9 -> 1.0.0</a></h2> <!-- index:2:SH:1:27:0.9.9 -> 1.0.0 -->
     <ul>
      <li>Briefer <em>--help</em> output; works with <em>--verbose</em>.</li>
      <li>Option to listen on a specific network interface (<em>--interface</em>).</li>
@@ -331,7 +338,7 @@
      <li>EHLO response parsing is now case-insensitive [bug-id 561522].</li>
      <li>Fewer missing-secrets warnings [bug-id 564987].</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_27">0.9.8 -> 0.9.9</a></h2> <!-- index:2:SH:1:27:0.9.8 -> 0.9.9 -->
+   <h2><a class="a-header" name="SH_1_28">0.9.8 -> 0.9.9</a></h2> <!-- index:2:SH:1:28:0.9.8 -> 0.9.9 -->
     <ul>
      <li>More flexible logging options (<em>--verbose</em> and <em>--debug</em> work better).</li>
      <li>File Hierarchy Standard (FHS) option for <em>configure</em> (<em>--enable-fhs</em>).</li>
@@ -347,14 +354,14 @@
      <li>Submit utility works under Windows. [rc2]</li>
      <li>Improved Windows project files. [rc2]</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_28">0.9.7 -> 0.9.8</a></h2> <!-- index:2:SH:1:28:0.9.7 -> 0.9.8 -->
+   <h2><a class="a-header" name="SH_1_29">0.9.7 -> 0.9.8</a></h2> <!-- index:2:SH:1:29:0.9.7 -> 0.9.8 -->
     <ul>
      <li>Fix for running pre-processor (<em>--filter</em>) as root.</li>
      <li>Ignore bogus <em>AUTH=LOGIN</em> lines in EHLO response.</li>
      <li>Submit utility improved to work with mutt.</li>
      <li>Installation of submit man page.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_29">0.9.6 -> 0.9.7</a></h2> <!-- index:2:SH:1:29:0.9.6 -> 0.9.7 -->
+   <h2><a class="a-header" name="SH_1_30">0.9.6 -> 0.9.7</a></h2> <!-- index:2:SH:1:30:0.9.6 -> 0.9.7 -->
     <ul>
      <li>CRAM-MD5 authentication mechanism added.</li>
      <li>Revoke root permissions at start up, and reclaim them when needed.</li>
@@ -370,7 +377,7 @@
      <li>Submission utility <em>emailrelay-submit</em> added.</li>
      <li>HTML4.0 compliant HTML documentation, using CSS.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_30">0.9.5 -> 0.9.6</a></h2> <!-- index:2:SH:1:30:0.9.5 -> 0.9.6 -->
+   <h2><a class="a-header" name="SH_1_31">0.9.5 -> 0.9.6</a></h2> <!-- index:2:SH:1:31:0.9.5 -> 0.9.6 -->
     <ul>
      <li>SMTP AUTHentication extension -- LOGIN mechanism only.</li>
      <li>Client-side protocol timeout.</li>
@@ -380,7 +387,7 @@
      <li>Multiple hard-coded listening addresses supported at compile-time.</li>
      <li>Fix for automatic reopening of stderr stream.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_31">0.9.4 -> 0.9.5</a></h2> <!-- index:2:SH:1:31:0.9.4 -> 0.9.5 -->
+   <h2><a class="a-header" name="SH_1_32">0.9.4 -> 0.9.5</a></h2> <!-- index:2:SH:1:32:0.9.4 -> 0.9.5 -->
     <p>
      Windows fixes and improvements...
     </p>
@@ -390,14 +397,14 @@
      <li>fix for content file deletion</li>
      <li>fix for directory iterator</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_32">0.9.3 -> 0.9.4</a></h2> <!-- index:2:SH:1:32:0.9.3 -> 0.9.4 -->
+   <h2><a class="a-header" name="SH_1_33">0.9.3 -> 0.9.4</a></h2> <!-- index:2:SH:1:33:0.9.3 -> 0.9.4 -->
     <ul>
      <li>Fixed memory leak when no <em>--log</em> switch.</li>
      <li>Windows build is more <em>gui</em> and less <em>command-line</em>.</li>
      <li><em>Info</em> command added to the administration interface.</li>
      <li>Doxygen files removed from binary RPM.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_33">0.9.2 -> 0.9.3</a></h2> <!-- index:2:SH:1:33:0.9.2 -> 0.9.3 -->
+   <h2><a class="a-header" name="SH_1_34">0.9.2 -> 0.9.3</a></h2> <!-- index:2:SH:1:34:0.9.2 -> 0.9.3 -->
     <ul>
      <li>Proxy mode (<em>--immediate</em> and <em>--as-proxy</em>).</li>
      <li>Message pre-processing (<em>--filter</em>).</li>
@@ -405,7 +412,7 @@
      <li>Improved notification script, with MIME encoding.</li>
      <li>Builds with old 2.91 version of gcc.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_34">0.9.1 -> 0.9.2</a></h2> <!-- index:2:SH:1:34:0.9.1 -> 0.9.2 -->
+   <h2><a class="a-header" name="SH_1_35">0.9.1 -> 0.9.2</a></h2> <!-- index:2:SH:1:35:0.9.1 -> 0.9.2 -->
     <ul>
      <li>Better autoconf detection.</li>
      <li>Workround for FreeBSD uname() feature.</li>
@@ -413,7 +420,7 @@
      <li>Fixed a benign directory iterator bug.</li>
      <li>Use of gcc's <em>exception</em> header.</li>
     </ul>
-   <h2><a class="a-header" name="SH_1_35">0.9 -> 0.9.1</a></h2> <!-- index:2:SH:1:35:0.9 -> 0.9.1 -->
+   <h2><a class="a-header" name="SH_1_36">0.9 -> 0.9.1</a></h2> <!-- index:2:SH:1:36:0.9 -> 0.9.1 -->
     <ul>
      <li>Improved documentation from doxygen.</li>
      <li>More complete use of namespaces.</li>
@@ -423,4 +430,4 @@
  </div> <!-- div-main -->
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/changelog.md

@@ -1,12 +1,19 @@
 E-MailRelay Change Log
 ======================
 
-2.3 -> 2.3.1
+2.3 -> 2.4
-------------
+----------
 
+* Multiple `--filter` and `--client-filter` options allowed.
+* [TLS][] key and certificate files can be specified separately.
+* Finer control when using `--anonymous` (eg. `--anonymous=server`).
+* The `auth-config` options can distinguish between TLS and non-TLS authentication.
 * Hourly log file rotation using `%h` (eg. `--log-file=log.%d.%h`).
-* TLS key and certificate files can be specified separately.
+* Listening file descriptors can be inherited from the parent process (see `--interface`).
-* Fixed error handling for network client filters (`--client-filter=net:...`) [bug-id #50].
+* Listening ports on Windows use exclusive binding.
+* The Linux event loop uses `epoll` by default rather than `select`.
+* Some support for message routing (see NEWS).
+* Fix of error handling in network client filters (`--client-filter=net:...`) [bug-id #50].
 
 2.2 -> 2.3
 ----------
@@ -22,7 +29,7 @@ E-MailRelay Change Log
 
 * Connections from IPv4 'private use' addresses are allowed by default (see `--remote-clients`).
 * Interface names can be used with `--interface` (eg. `--interface=eth0`).
-* New `--server-tls-connection` option for server-side implicit [TLS][].
+* New `--server-tls-connection` option for server-side implicit TLS.
 * New `--forward-to-some` option to permit some message recipients to be rejected.
 * New `--log-address` option to aid adaptive firewalling.
 * Dynamic log file rolling when using `--log-file=%d`.

doc/changelog.rst

@@ -2,12 +2,19 @@
 E-MailRelay Change Log
 **********************
 
-2.3 -> 2.3.1
+2.3 -> 2.4
-============
+==========
 
+* Multiple *--filter* and *--client-filter* options allowed.
+* TLS_ key and certificate files can be specified separately.
+* Finer control when using *--anonymous* (eg. *--anonymous=server*).
+* The *auth-config* options can distinguish between TLS and non-TLS authentication.
 * Hourly log file rotation using *%h* (eg. *--log-file=log.%d.%h*).
-* TLS key and certificate files can be specified separately.
+* Listening file descriptors can be inherited from the parent process (see *--interface*).
-* Fixed error handling for network client filters (*--client-filter=net:...*) [bug-id #50].
+* Listening ports on Windows use exclusive binding.
+* The Linux event loop uses *epoll* by default rather than *select*.
+* Some support for message routing (see NEWS).
+* Fix of error handling in network client filters (\ *--client-filter=net:...*\ ) [bug-id #50].
 
 2.2 -> 2.3
 ==========
@@ -15,7 +22,7 @@ E-MailRelay Change Log
 * Unix domain sockets supported (eg. *--interface=/tmp/smtp.s*).
 * Windows event log not used for verbose logging (prefer *--log-file*).
 * New admin *forward* command to trigger forwarding without waiting.
-* Optional base64 encoding of passwords in secrets files (*plain:b*).
+* Optional base64 encoding of passwords in secrets files (\ *plain:b*\ ).
 * Support for MbedTLS version 3.
 
 2.1 -> 2.2
@@ -23,7 +30,7 @@ E-MailRelay Change Log
 
 * Connections from IPv4 'private use' addresses are allowed by default (see *--remote-clients*).
 * Interface names can be used with *--interface* (eg. *--interface=eth0*).
-* New *--server-tls-connection* option for server-side implicit TLS_.
+* New *--server-tls-connection* option for server-side implicit TLS.
 * New *--forward-to-some* option to permit some message recipients to be rejected.
 * New *--log-address* option to aid adaptive firewalling.
 * Dynamic log file rolling when using *--log-file=%d*.

doc/changelog.txt

@@ -1,11 +1,18 @@
 E-MailRelay Change Log
 ======================
 
-2.3 -> 2.3.1
+2.3 -> 2.4
-------------
+----------
-* Hourly log file rotation using "%h" (eg. "--log-file=log.%d.%h").
+* Multiple "--filter" and "--client-filter" options allowed.
 * TLS key and certificate files can be specified separately.
-* Fixed error handling for network client filters ("--client-filter=net:...") [bug-id #50].
+* Finer control when using "--anonymous" (eg. "--anonymous=server").
+* The "auth-config" options can distinguish between TLS and non-TLS authentication.
+* Hourly log file rotation using "%h" (eg. "--log-file=log.%d.%h").
+* Listening file descriptors can be inherited from the parent process (see "--interface").
+* Listening ports on Windows use exclusive binding.
+* The Linux event loop uses "epoll" by default rather than "select".
+* Some support for message routing (see NEWS).
+* Fix of error handling in network client filters ("--client-filter=net:...") [bug-id #50].
 
 2.2 -> 2.3
 ----------

doc/conf.py.sphinx

@@ -9,8 +9,8 @@ master_doc = 'index'
 project = u'E-MailRelay'
 copyright = u'2022, Graeme Walker'
 author = u'Graeme Walker'
-version = u'2.3'
+version = u'2.4'
-release = u'2.3'
+release = u'2.4'
 language = None
 today_fmt = '%Y-%m-%d'
 exclude_patterns = []

doc/developer.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "%-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay Developer Guide</title>
@@ -8,7 +8,7 @@
  <body>
   <!-- index:0::::E-MailRelay Developer Guide -->
  <div class="div-main">
-  <h1><a class="a-header" name="H_1">E-MailRelay Developer Guide</a></h1> <!-- index:1:H:1::E-MailRelay Developer Guide -->
+  <h1><a class="a-header" name="H_1">E-MailRelay Developer Guide</a></h1> <!-- index:1:H:E-MailRelay Developer Guide -->
    <h2><a class="a-header" name="SH_1_1">Principles</a></h2> <!-- index:2:SH:1:1:Principles -->
     <p>
      The main principles in the design of E-MailRelay can be summarised as:
@@ -102,34 +102,31 @@
     <p>
      The main C++ libraries in the E-MailRelay code base are as follows:
     </p>
-
+   <h3><a class="a-header"><em>glib</em></a></h3>
-    <dl>
-     <dt><em>glib</em></dt>
       <dd>
        Low-level classes for file-system abstraction, date and time representation,
        string utility functions, logging, command line parsing etc.
       </dd>
-     <dt><em>gssl</em></dt>
+   <h3><a class="a-header"><em>gssl</em></a></h3>
       <dd>
        A thin layer over the third-party TLS libraries.
       </dd>
-     <dt><em>gnet</em></dt>
+   <h3><a class="a-header"><em>gnet</em></a></h3>
       <dd>
        Network and event-loop classes.
       </dd>
-     <dt><em>gauth</em></dt>
+   <h3><a class="a-header"><em>gauth</em></a></h3>
       <dd>
        Implements various authentication mechanisms.
       </dd>
-     <dt><em>gsmtp</em></dt>
+   <h3><a class="a-header"><em>gsmtp</em></a></h3>
       <dd>
        SMTP protocol and message-store classes.
       </dd>
-     <dt><em>gpop</em></dt>
+   <h3><a class="a-header"><em>gpop</em></a></h3>
       <dd>
        POP3 protocol classes.
       </dd>
-    </dl>
     <p>
      All of these libraries are portable between Unix-like systems and Windows.
     </p>
@@ -353,10 +350,10 @@
 
     <div class="div-footer">
      <p>
-      Copyright (C) 2001-2021 Graeme Walker
+      Copyright (C) 2001-2022 Graeme Walker
      </p>
     </div><!-- div-footer -->
  </div> <!-- div-main -->
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/developer.md

@@ -77,28 +77,33 @@ Module structure
 ----------------
 The main C++ libraries in the E-MailRelay code base are as follows:
 
-*   `glib`
+### "glib" ###
 
     Low-level classes for file-system abstraction, date and time representation,
     string utility functions, logging, command line parsing etc.
 
-*   `gssl`
+
+### "gssl" ###
 
     A thin layer over the third-party TLS libraries.
 
-*   `gnet`
+
+### "gnet" ###
 
     Network and event-loop classes.
 
-*   `gauth`
+
+### "gauth" ###
 
     Implements various authentication mechanisms.
 
-*   `gsmtp`
+
+### "gsmtp" ###
 
     SMTP protocol and message-store classes.
 
-*   `gpop`
+
+### "gpop" ###
 
     POP3 protocol classes.
 
@@ -287,4 +292,4 @@ Use `./configure --help` to see a complete list of options.
 [TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker

doc/developer.rst

@@ -77,30 +77,17 @@ required.
 Module structure
 ================
 The main C++ libraries in the E-MailRelay code base are as follows:
-
-*   \ *glib*\
-
     Low-level classes for file-system abstraction, date and time representation,
     string utility functions, logging, command line parsing etc.
 
-*   \ *gssl*\
-
     A thin layer over the third-party TLS libraries.
 
-*   \ *gnet*\
-
     Network and event-loop classes.
 
-*   \ *gauth*\
-
     Implements various authentication mechanisms.
 
-*   \ *gsmtp*\
-
     SMTP protocol and message-store classes.
 
-*   \ *gpop*\
-
     POP3 protocol classes.
 
 All of these libraries are portable between Unix-like systems and Windows.
@@ -290,4 +277,4 @@ Use *./configure --help* to see a complete list of options.
 .. _SMTP: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 .. _TLS: https://en.wikipedia.org/wiki/Transport_Layer_Security
 
-.. footer:: Copyright (C) 2001-2021 Graeme Walker
+.. footer:: Copyright (C) 2001-2022 Graeme Walker

doc/developer.txt

@@ -275,4 +275,4 @@ Use "./configure --help" to see a complete list of options.
 
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker

doc/doxygen-missing.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay source code documentation missing</title>
@@ -11,4 +11,4 @@
   </div>
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/doxygen.cfg.in

@@ -838,51 +838,7 @@ INPUT_ENCODING         = UTF-8
 # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
 # *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice.
 
-FILE_PATTERNS          = *.c \
+FILE_PATTERNS = *.h *.cpp
-                         *.cc \
-                         *.cxx \
-                         *.cpp \
-                         *.c++ \
-                         *.java \
-                         *.ii \
-                         *.ixx \
-                         *.ipp \
-                         *.i++ \
-                         *.inl \
-                         *.idl \
-                         *.ddl \
-                         *.odl \
-                         *.h \
-                         *.hh \
-                         *.hxx \
-                         *.hpp \
-                         *.h++ \
-                         *.cs \
-                         *.d \
-                         *.php \
-                         *.php4 \
-                         *.php5 \
-                         *.phtml \
-                         *.inc \
-                         *.m \
-                         *.markdown \
-                         *.md \
-                         *.mm \
-                         *.dox \
-                         *.py \
-                         *.pyw \
-                         *.f90 \
-                         *.f95 \
-                         *.f03 \
-                         *.f08 \
-                         *.f \
-                         *.for \
-                         *.tcl \
-                         *.vhd \
-                         *.vhdl \
-                         *.ucf \
-                         *.qsf \
-                         *.ice
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -913,7 +869,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS = *_none* *_win32* *_basic* *_mac* *_mbedtls* *_ipv4* *_ip.cpp *_both* *_epoll*
+EXCLUDE_PATTERNS = *handles.h *_*cpp
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

doc/emailrelay-doxygen.css

@@ -1,5 +1,5 @@
 /*
-  Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+  Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 */
 
 /*

doc/emailrelay-filter-copy.1

@@ -1,4 +1,4 @@
-.\" Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+.\" Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 .\" 
 .\" This program is free software: you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
@@ -47,7 +47,7 @@ forwarding.
 When using
 .I "-d"
 all envelope files in the spool directory are copied to all
-sub-directories. This should be used after using
+sub-directories. This can be used after
 .B emailrelay-submit
 has deposited an envelope file into the main spool
 directory, or perhaps periodically from cron.

doc/emailrelay-man.html

@@ -1,5 +1,4 @@
-
+<!DOCTYPE html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <HTML><HEAD><TITLE>Man page of EMAILRELAY</TITLE>
 </HEAD><BODY>
 <H1>EMAILRELAY</H1>
@@ -67,23 +66,10 @@ disconnects.
 <A NAME="lbAE">&nbsp;</A>
 <H2>OPTIONS</H2>
 
+<A NAME="lbAF">&nbsp;</A>
+<H3>Basic options</H3>
+
 <DL COMPACT>
-<DT><B>--address-verifier </B><I>&lt;program&gt;</I>
-
-<DD>
-Runs the specified external program to verify a message recipent's e-mail address. A network verifier can be specified as <I>net:&lt;transport-address&gt;</I>.
-<DT><B>-a, --admin </B><I>&lt;admin-port&gt;</I>
-
-<DD>
-Enables an administration interface on the specified listening port number. Use telnet or something similar to connect. The administration interface can be used to trigger forwarding of spooled mail messages if the <I>--forward-to</I> option is used.
-<DT><B>-Q, --admin-terminate</B>
-
-<DD>
-Enables the <I>terminate</I> command in the administration interface.
-<DT><B>-A, --anonymous</B>
-
-<DD>
-Disables the server's SMTP VRFY command, sends less verbose SMTP responses and SMTP greeting, and stops <I>Received</I> lines being added to mail message content files.
 <DT><B>-q, --as-client </B><I>&lt;host:port&gt;</I>
 
 <DD>
@@ -96,6 +82,155 @@ This is equivalent to <I>--log</I>, <I>--close-stderr</I>, <I>--forward-on-disco
 
 <DD>
 This is equivalent to <I>--log</I> and <I>--close-stderr</I>. It is a convenient way of running a background storage daemon that accepts mail messages and spools them. Use <I>--log</I> instead of <I>--as-server</I> to keep standard error stream open.
+<DT><B>-s, --spool-dir </B><I>&lt;dir&gt;</I>
+
+<DD>
+Specifies the directory used for holding mail messages that have been received but not yet forwarded.
+<DT><B>-h, --help</B>
+
+<DD>
+Displays help text and then exits. Use with <I>--verbose</I> for more complete output.
+<DT><B>-V, --version</B>
+
+<DD>
+Displays version information and then exits.
+</DL>
+<A NAME="lbAG">&nbsp;</A>
+<H3>SMTP client options</H3>
+
+<DL COMPACT>
+<DT><B>-f, --forward</B>
+
+<DD>
+Causes spooled mail messages to be forwarded when the program first starts.
+<DT><B>-1, --forward-on-disconnect</B>
+
+<DD>
+Causes spooled mail messages to be forwarded whenever a SMTP client connection disconnects.
+<DT><B>-o, --forward-to </B><I>&lt;host:port&gt;</I>
+
+<DD>
+Specifies the transport address of the remote SMTP server that spooled mail messages are forwarded to.
+<DT><B>-O, --poll </B><I>&lt;period&gt;</I>
+
+<DD>
+Causes forwarding of spooled mail messages to happen at regular intervals (with the time given in seconds).
+<DT><B>-Y, --client-filter </B><I>&lt;program&gt;</I>
+
+<DD>
+Runs the specified external filter program whenever a mail message is forwarded. The filter is passed the name of the message file in the spool directory so that it can edit it as required. A network filter can be specified as <I>net:&lt;tcp-address&gt;</I> and prefixes of <I>spam:</I>, <I>spam-edit:</I> and <I>exit:</I> are also allowed. The <I>spam:</I> and <I>spam-edit:</I> prefixes require a SpamAssassin daemon to be running. For store-and-forward applications the <I>--filter</I> option is normally more useful than <I>--client-filter</I>.
+<DT><B>-6, --client-interface </B><I>&lt;ip-address&gt;</I>
+
+<DD>
+Specifies the IP network address to be used to bind the local end of outgoing SMTP connections. By default the address will depend on the routing tables in the normal way. Use <I>0.0.0.0</I> to use only IPv4 addresses returned from DNS lookups of the <I>--forward-to</I> address, or <I>::</I> for IPv6.
+<DT><B>-U, --connection-timeout </B><I>&lt;time&gt;</I>
+
+<DD>
+Specifies a timeout (in seconds) for establishing a TCP connection to remote SMTP servers. The default is 40 seconds.
+<DT><B>--idle-timeout </B><I>&lt;time&gt;</I>
+
+<DD>
+Specifies a timeout (in seconds) for receiving network traffic from remote SMTP and POP clients. The default is 60 seconds.
+<DT><B>-T, --response-timeout </B><I>&lt;time&gt;</I>
+
+<DD>
+Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 60 seconds.
+<DT><B>--forward-to-some</B>
+
+<DD>
+Allow forwarding to continue even if some recipient addresses on an e-mail envelope are rejected by the remote server.
+<DT><B>-m, --immediate</B>
+
+<DD>
+Causes mail messages to be forwarded as they are received, even before they have been accepted. This can be used to do proxying without store-and-forward, but in practice clients tend to to time out while waiting for their mail message to be accepted.
+</DL>
+<A NAME="lbAH">&nbsp;</A>
+<H3>SMTP server options</H3>
+
+<DL COMPACT>
+<DT><B>-p, --port </B><I>&lt;port&gt;</I>
+
+<DD>
+Sets the port number used for listening for incoming SMTP connections.
+<DT><B>-r, --remote-clients</B>
+
+<DD>
+Allows incoming connections from addresses that are not local. The default behaviour is to reject connections that are not local in order to prevent accidental exposure to the public internet, although a firewall should also be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
+<DT><B>--address-verifier </B><I>&lt;program&gt;</I>
+
+<DD>
+Runs the specified external program to verify a message recipent's e-mail address. A network verifier can be specified as <I>net:&lt;tcp-address&gt;</I>.
+<DT><B>-A, --anonymous, --anonymous=</B><I>&lt;scope&gt;</I>
+
+<DD>
+Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and responses, stops <I>Received</I> lines being added to mail message content files, and stops the SMTP client protocol adding <I>AUTH=</I> to the <I>MAIL</I> command. For finer control use a comma-separated list of things to anonymise: <I>vrfy</I>, <I>server</I>, <I>content</I> and/or <I>client</I>, eg. <I>--anonymous</I>=server,content.
+<DT><B>--dnsbl </B><I>&lt;config&gt;</I>
+
+<DD>
+Specifies a list of DNSBL servers that are used to reject SMTP connections from blocked addresses. The configuration string is made up of comma-separated fields: the DNS server's transport address, a timeout in milliseconds, a rejection threshold, and then the list of DNSBL servers.
+<DT><B>-D, --domain </B><I>&lt;fqdn&gt;</I>
+
+<DD>
+Specifies the network name that is used in SMTP EHLO commands, <I>Received</I> lines, and for generating authentication challenges. The default is derived from a DNS lookup of the local hostname.
+<DT><B>-z, --filter </B><I>&lt;program&gt;</I>
+
+<DD>
+Runs the specified external filter program whenever a mail message is stored. The filter is passed the name of the message file in the spool directory so that it can edit it as required. The mail message is rejected if the filter program terminates with an exit code between 1 and 99. Use <I>net:&lt;tcp-address&gt;</I> to communicate with a filter daemon over the network, or <I>spam:&lt;tcp-address&gt;</I> for a spamassassin spamd daemon to accept or reject mail messages, or <I>spam-edit:&lt;tcp-address&gt;</I> to have spamassassin edit the message content without rejecting it, or <I>exit:&lt;number&gt;</I> to emulate a filter program that just exits.
+<DT><B>-W, --filter-timeout </B><I>&lt;time&gt;</I>
+
+<DD>
+Specifies a timeout (in seconds) for running a <I>--filter</I> program. The default is 60 seconds.
+<DT><B>-I, --interface </B><I>&lt;ip-address-list&gt;</I>
+
+<DD>
+Specifies the IP network addresses or interface names used to bind listening ports. By default listening ports for incoming SMTP, POP and administration connections will bind the 'any' address for IPv4 and for IPv6, ie. <I>0.0.0.0</I> and <I>::</I>. Multiple addresses can be specified by using the option more than once or by using a comma-separated list. Use a prefix of <I>smtp=</I>, <I>pop=</I> or <I>admin=</I> on addresses that should apply only to those types of listening port. Any link-local IPv6 addresses must include a zone name or scope id.  Interface names can be used instead of addresses, in which case all the addresses associated with that interface at startup will used for listening. When an interface name is decorated with a <I>-ipv4</I> or <I>-ipv6</I> suffix only their IPv4 or IPv6 addresses will be used (eg. <I>ppp0-ipv4</I>).  To inherit listening file descriptors from the parent process on unix use a syntax like this: <I>--interface</I>=smtp=fd#3,smtp=fd#4,pop=fd#5.
+<DT><B>-w, --prompt-timeout </B><I>&lt;time&gt;</I>
+
+<DD>
+Specifies a timeout (in seconds) for getting the initial prompt from a remote SMTP server. If no prompt is received after this time then the SMTP dialog goes ahead without it.
+<DT><B>-M, --size </B><I>&lt;bytes&gt;</I>
+
+<DD>
+Limits the size of mail messages that can be submitted over SMTP.
+</DL>
+<A NAME="lbAI">&nbsp;</A>
+<H3>POP server options</H3>
+
+<DL COMPACT>
+<DT><B>-B, --pop</B>
+
+<DD>
+Enables the POP server, listening by default on port 110, providing access to spooled mail messages. Negotiated TLS using the POP <I>STLS</I> command will be enabled if the <I>--server-tls</I> option is also given.
+<DT><B>-J, --pop-by-name</B>
+
+<DD>
+Modifies the spool directory used by the POP server to be a sub-directory with the same name as the POP authentication user-id. This allows multiple POP clients to read the spooled mail messages without interfering with each other, particularly when also using <I>--pop-no-delete</I>. Content files can stay in the main spool directory with only the envelope files copied into user-specific sub-directories. The <I>emailrelay-filter-copy</I> program is a convenient way of doing this when run via <I>--filter</I>.
+<DT><B>-G, --pop-no-delete</B>
+
+<DD>
+Disables the POP DELE command so that the command appears to succeed but mail messages are not deleted from the spool directory.
+<DT><B>-E, --pop-port </B><I>&lt;port&gt;</I>
+
+<DD>
+Sets the POP server's listening port number.
+</DL>
+<A NAME="lbAJ">&nbsp;</A>
+<H3>Admin server options</H3>
+
+<DL COMPACT>
+<DT><B>-a, --admin </B><I>&lt;port&gt;</I>
+
+<DD>
+Enables an administration interface on the specified listening port number. Use telnet or something similar to connect. The administration interface can be used to trigger forwarding of spooled mail messages if the <I>--forward-to</I> option is used.
+<DT><B>-Q, --admin-terminate</B>
+
+<DD>
+Enables the <I>terminate</I> command in the administration interface.
+</DL>
+<A NAME="lbAK">&nbsp;</A>
+<H3>Authentication options</H3>
+
+<DL COMPACT>
 <DT><B>-C, --client-auth </B><I>&lt;file&gt;</I>
 
 <DD>
@@ -103,15 +238,24 @@ Enables SMTP client authentication with the remote server, using the client acco
 <DT><B>--client-auth-config </B><I>&lt;config&gt;</I>
 
 <DD>
-Configures the SMTP client authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of authentication mechanisms, and an 'x' is used for blocklisted mechanisms.
+Configures the SMTP client authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of preferred authentication mechanisms and an 'x' introduces a list of mechanisms to avoid. An 'a' list and a 'd' list can be used similarly to prefer and avoid certain mechanisms once the session is encrypted with TLS.
-<DT><B>-Y, --client-filter </B><I>&lt;program&gt;</I>
+<DT><B>-S, --server-auth </B><I>&lt;file&gt;</I>
 
 <DD>
-Runs the specified external filter program whenever a mail message is forwarded. The filter is passed the name of the message file in the spool directory so that it can edit it as required. A network filter can be specified as <I>net:&lt;transport-address&gt;</I> and prefixes of <I>spam:</I>, <I>spam-edit:</I> and <I>exit:</I> are also allowed. The <I>spam:</I> and <I>spam-edit:</I> prefixes require a SpamAssassin daemon to be running. For store-and-forward applications the <I>--filter</I> option is normally more useful than <I>--client-filter</I>.
+Enables SMTP server authentication of remote SMTP clients. Account names and passwords are taken from the specified secrets file. The secrets file should contain lines that have four space-separated fields, starting with <I>server</I> in the first field; the second field is the password encoding (<I>plain</I> or <I>md5</I>), the third is the client user-id and the fourth is the password. The user-id is RFC-1891 xtext encoded, and the password is either xtext encoded or generated by <I>emailrelay-passwd</I>. A special value of <I>/pam</I> can be used for authentication using linux PAM.
-<DT><B>-6, --client-interface </B><I>&lt;ip-address&gt;</I>
+<DT><B>--server-auth-config </B><I>&lt;config&gt;</I>
 
 <DD>
-Specifies the IP network address to be used to bind the local end of outgoing SMTP connections. By default the address will depend on the routing tables in the normal way. Use <I>0.0.0.0</I> to use only IPv4 addresses returned from DNS lookups of the <I>--forward-to</I> address, or <I>::</I> for IPv6.
+Configures the SMTP server authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of allowed authentication mechanisms and an 'x' introduces a list of mechanisms to deny. An 'a' list and a 'd' list can be used similarly to allow and deny mechanisms once the session is encrypted with TLS. In typical usage you might have an empty allow list for an unencrypted session and a single preferred mechanism once encrypted, <I>m:;a:plain</I>.
+<DT><B>-F, --pop-auth </B><I>&lt;file&gt;</I>
+
+<DD>
+Specifies a file containing valid POP account details. The file format is the same as for the SMTP server secrets file, ie. lines starting with <I>server</I>, with user-id and password in the third and fourth fields. A special value of <I>/pam</I> can be used for authentication using linux PAM.
+</DL>
+<A NAME="lbAL">&nbsp;</A>
+<H3>TLS options</H3>
+
+<DL COMPACT>
 <DT><B>-j, --client-tls</B>
 
 <DD>
@@ -140,158 +284,6 @@ Enables verification of the remote SMTP server's certificate against any of the
 
 <DD>
 Enables verification of the CNAME within the remote SMTP server's certificate.
-<DT><B>-e, --close-stderr</B>
-
-<DD>
-Causes the standard error stream to be closed soon after start-up. This is useful when operating as a background daemon and it is therefore implied by <I>--as-server</I> and <I>--as-proxy</I>.
-<DT><B>-U, --connection-timeout </B><I>&lt;time&gt;</I>
-
-<DD>
-Specifies a timeout (in seconds) for establishing a TCP connection to remote SMTP servers. The default is 40 seconds.
-<DT><B>-g, --debug</B>
-
-<DD>
-Enables debug level logging, if built in. Debug messages are usually only useful when cross-referenced with the source code and they may expose plaintext passwords and mail message content.
-<DT><B>--dnsbl </B><I>&lt;config&gt;</I>
-
-<DD>
-Specifies a list of DNSBL servers that are used to reject SMTP connections from blocked addresses. The configuration string is made up of comma-separated fields: the DNS server's transport address, a timeout in milliseconds, a rejection threshold, and then the list of DNSBL servers.
-<DT><B>-D, --domain </B><I>&lt;fqdn&gt;</I>
-
-<DD>
-Specifies the network name that is used in SMTP EHLO commands, <I>Received</I> lines, and for generating authentication challenges. The default is derived from a DNS lookup of the local hostname.
-<DT><B>-x, --dont-serve</B>
-
-<DD>
-Disables all network serving, including SMTP, POP and administration interfaces. The program will terminate as soon as any initial forwarding is complete.
-<DT><B>-z, --filter </B><I>&lt;program&gt;</I>
-
-<DD>
-Runs the specified external filter program whenever a mail message is stored. The filter is passed the name of the message file in the spool directory so that it can edit it as required. The mail message is rejected if the filter program terminates with an exit code between 1 and 99. Use <I>net:&lt;transport-address&gt;</I> to communicate with a filter daemon over the network, or <I>spam:&lt;transport-address&gt;</I> for a spamassassin spamd daemon to accept or reject mail messages, or <I>spam-edit:&lt;transport-address&gt;</I> to have spamassassin edit the message content without rejecting it, or <I>exit:&lt;number&gt;</I> to emulate a filter program that just exits.
-<DT><B>-W, --filter-timeout </B><I>&lt;time&gt;</I>
-
-<DD>
-Specifies a timeout (in seconds) for running a <I>--filter</I> program. The default is 300 seconds.
-<DT><B>-f, --forward</B>
-
-<DD>
-Causes spooled mail messages to be forwarded when the program first starts.
-<DT><B>-1, --forward-on-disconnect</B>
-
-<DD>
-Causes spooled mail messages to be forwarded whenever a SMTP client connection disconnects.
-<DT><B>-o, --forward-to </B><I>&lt;host:port&gt;</I>
-
-<DD>
-Specifies the transport address of the remote SMTP server that is use for mail message forwarding.
-<DT><B>--forward-to-some</B>
-
-<DD>
-Allow forwarding to continue even if some recipient addresses on an e-mail envelope are rejected by the remote server.
-<DT><B>-h, --help</B>
-
-<DD>
-Displays help text and then exits. Use with <I>--verbose</I> for more complete output.
-<DT><B>-H, --hidden</B>
-
-<DD>
-Windows only. Hides the application window and disables all message boxes, overriding any <I>--show</I> option. This is useful when running as a windows service.
-<DT><B>--idle-timeout </B><I>&lt;time&gt;</I>
-
-<DD>
-Specifies a timeout (in seconds) for receiving network traffic from remote SMTP and POP clients. The default is 1800 seconds.
-<DT><B>-m, --immediate</B>
-
-<DD>
-Causes mail messages to be forwarded as they are received, even before they have been accepted. This can be used to do proxying without store-and-forward, but in practice clients tend to to time out while waiting for their mail message to be accepted.
-<DT><B>-I, --interface </B><I>&lt;ip-address-list&gt;</I>
-
-<DD>
-Specifies the IP network addresses or interface names used to bind listening ports. By default listening ports for incoming SMTP, POP and administration connections will bind the 'any' address for IPv4 and for IPv6, ie. <I>0.0.0.0</I> and <I>::</I>. Multiple addresses can be specified by using the option more than once or by using a comma-separated list. Use a prefix of <I>smtp=</I>, <I>pop=</I> or <I>admin=</I> on addresses that should apply only to those types of listening port. Any link-local IPv6 addresses must include a zone name or scope id.  Interface names can be used instead of addresses, in which case all the addresses associated with that interface at startup will used for listening. When an interface name is decorated with a <I>-ipv4</I> or <I>-ipv6</I> suffix only their IPv4 or IPv6 addresses will be used (eg. <I>ppp0-ipv4</I>).
-<DT><B>--localedir </B><I>&lt;dir&gt;</I>
-
-<DD>
-Enables localisation and specifies the locale base directory where message catalogues can be found. An empty directory can be used for the built-in default.
-<DT><B>-l, --log</B>
-
-<DD>
-Enables logging to the standard error stream and to the syslog. The <I>--close-stderr</I> and <I>--no-syslog</I> options can be used to disable output to standard error stream and the syslog separately. Note that <I>--as-server</I>, <I>--as-client</I> and <I>--as-proxy</I> imply <I>--log</I>, and <I>--as-server</I> and <I>--as-proxy</I> also imply <I>--close-stderr</I>.
-<DT><B>--log-address</B>
-
-<DD>
-Adds the network address of remote clients to the logging output.
-<DT><B>-N, --log-file </B><I>&lt;file&gt;</I>
-
-<DD>
-Redirects standard-error logging to the specified file. Logging to the log file is not affected by <I>--close-stderr</I>. The filename can include <I>%d</I> to get daily log files; the <I>%d</I> is replaced by the current date in the local timezone using a <I>YYYYMMDD</I> format.
-<DT><B>-L, --log-time</B>
-
-<DD>
-Adds a timestamp to the logging output using the local timezone.
-<DT><B>-t, --no-daemon</B>
-
-<DD>
-Disables the normal backgrounding at startup so that the program runs in the foreground, without forking or detaching from the terminal.  On Windows this disables the system tray icon so the program uses a normal window; when the window is closed the program terminates.
-<DT><B>-X, --no-smtp</B>
-
-<DD>
-Disables listening for incoming SMTP connections.
-<DT><B>-n, --no-syslog</B>
-
-<DD>
-Disables logging to the syslog. Note that <I>--as-client</I> implies <I>--no-syslog</I>.
-<DT><B>-i, --pid-file </B><I>&lt;pid-file&gt;</I>
-
-<DD>
-Causes the process-id to be written into the specified file when the program starts up, typically after it has become a background daemon.
-<DT><B>-O, --poll </B><I>&lt;period&gt;</I>
-
-<DD>
-Causes forwarding of spooled mail messages to happen at regular intervals (with the time given in seconds).
-<DT><B>-B, --pop</B>
-
-<DD>
-Enables the POP server listening, by default on port 110, providing access to spooled mail messages. Negotiated TLS using the POP <I>STLS</I> command will be enabled if the <I>--server-tls</I> option is also given.
-<DT><B>-F, --pop-auth </B><I>&lt;file&gt;</I>
-
-<DD>
-Specifies a file containing valid POP account details. The file format is the same as for the SMTP server secrets file, ie. lines starting with <I>server</I>, with user-id and password in the third and fourth fields. A special value of <I>/pam</I> can be used for authentication using linux PAM.
-<DT><B>-J, --pop-by-name</B>
-
-<DD>
-Modifies the spool directory used by the POP server to be a sub-directory with the same name as the POP authentication user-id. This allows multiple POP clients to read the spooled messages without interfering with each other, particularly when also using <I>--pop-no-delete</I>. Content files can stay in the main spool directory with only the envelope files copied into user-specific sub-directories. The <I>emailrelay-filter-copy</I> program is a convenient way of doing this when run via <I>--filter</I>.
-<DT><B>-G, --pop-no-delete</B>
-
-<DD>
-Disables the POP DELE command so that the command appears to succeed but mail messages are not deleted from the spool directory.
-<DT><B>-E, --pop-port </B><I>&lt;port&gt;</I>
-
-<DD>
-Sets the POP server's listening port number.
-<DT><B>-p, --port </B><I>&lt;port&gt;</I>
-
-<DD>
-Sets the port number used for listening for incoming SMTP connections.
-<DT><B>-w, --prompt-timeout </B><I>&lt;time&gt;</I>
-
-<DD>
-Specifies a timeout (in seconds) for getting the initial prompt from a remote SMTP server. If no prompt is received after this time then the SMTP dialog goes ahead without it.
-<DT><B>-r, --remote-clients</B>
-
-<DD>
-Allows incoming connections from addresses that are not local. The default behaviour is to reject connections that are not local in order to prevent accidental exposure to the public internet, although a firewall should also be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
-<DT><B>-T, --response-timeout </B><I>&lt;time&gt;</I>
-
-<DD>
-Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 1800 seconds.
-<DT><B>-S, --server-auth </B><I>&lt;file&gt;</I>
-
-<DD>
-Enables SMTP server authentication of remote SMTP clients. Account names and passwords are taken from the specified secrets file. The secrets file should contain lines that have four space-separated fields, starting with <I>server</I> in the first field; the second field is the password encoding (<I>plain</I> or <I>md5</I>), the third is the client user-id and the fourth is the password. The user-id is RFC-1891 xtext encoded, and the password is either xtext encoded or generated by <I>emailrelay-passwd</I>. A special value of <I>/pam</I> can be used for authentication using linux PAM.
-<DT><B>--server-auth-config </B><I>&lt;config&gt;</I>
-
-<DD>
-Configures the SMTP server authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces a preferred sub-set of the built-in authentication mechanisms, and an 'x' is used for blocklisted mechanisms.
 <DT><B>-K, --server-tls</B>
 
 <DD>
@@ -312,43 +304,93 @@ Makes the use of TLS mandatory for any incoming SMTP and POP connections. SMTP c
 
 <DD>
 Enables verification of remote SMTP and POP clients' certificates against any of the trusted CA certificates in the specified file or directory. In many use cases this should be a file containing just your self-signed root certificate. Specify <I>&lt;default&gt;</I> for the TLS library's default set of trusted CAs.
-<DT><B>-M, --size </B><I>&lt;bytes&gt;</I>
-
-<DD>
-Limits the size of mail messages that can be submitted over SMTP.
-<DT><B>-s, --spool-dir </B><I>&lt;dir&gt;</I>
-
-<DD>
-Specifies the directory used for holding mail messages that have been received but not yet forwarded.
-<DT><B>-k, --syslog, --syslog=</B><I>&lt;facility&gt;</I>
-
-<DD>
-When used with <I>--log</I> this option enables logging to the syslog even if the <I>--no-syslog</I> option is also used. This is typically used as a convenient override when using <I>--as-client</I>.
 <DT><B>-9, --tls-config </B><I>&lt;options&gt;</I>
 
 <DD>
 Selects and configures the low-level TLS library, using a comma-separated list of keywords. If OpenSSL and mbedTLS are both built in then keywords of <I>openssl</I> and <I>mbedtls</I> will select one or the other. Keywords like <I>tlsv1.0</I> can be used to set a minimum TLS protocol version, or <I>-tlsv1.2</I> to set a maximum version.
+</DL>
+<A NAME="lbAM">&nbsp;</A>
+<H3>Process options</H3>
+
+<DL COMPACT>
+<DT><B>-x, --dont-serve</B>
+
+<DD>
+Disables all network serving, including SMTP, POP and administration interfaces. The program will terminate as soon as any initial forwarding is complete.
+<DT><B>-H, --hidden</B>
+
+<DD>
+Windows only. Hides the application window and disables all message boxes, overriding any <I>--show</I> option. This is useful when running as a windows service.
+<DT><B>--localedir </B><I>&lt;dir&gt;</I>
+
+<DD>
+Enables localisation and specifies the locale base directory where message catalogues can be found. An empty directory can be used for the built-in default.
+<DT><B>-t, --no-daemon</B>
+
+<DD>
+Disables the normal backgrounding at startup so that the program runs in the foreground, without forking or detaching from the terminal.  On Windows this disables the system tray icon so the program uses a normal window; when the window is closed the program terminates.
+<DT><B>-X, --no-smtp</B>
+
+<DD>
+Disables listening for incoming SMTP connections.
+<DT><B>-i, --pid-file </B><I>&lt;path&gt;</I>
+
+<DD>
+Causes the process-id to be written into the specified file when the program starts up, typically after it has become a background daemon. The immediate parent directory is created if necessary.
 <DT><B>-u, --user </B><I>&lt;username&gt;</I>
 
 <DD>
-When started as root the program switches to a non-privileged effective user-id when idle. This option can be used to define the idle user-id and also the group ownership of new files and sockets. Specify <I>root</I> to  disable all user-id switching. Ignored on Windows.
+When started as root the program switches to a non-privileged effective user-id when idle. This option can be used to define the idle user-id and also the group ownership of new files and sockets. Specify <I>root</I> to disable all user-id switching. Ignored on Windows.
+</DL>
+<A NAME="lbAN">&nbsp;</A>
+<H3>Logging options</H3>
+
+<DL COMPACT>
 <DT><B>-v, --verbose</B>
 
 <DD>
 Enables more verbose logging when used with <I>--log</I>, and more verbose help when used with <I>--help</I>.
-<DT><B>-V, --version</B>
+<DT><B>-l, --log</B>
 
 <DD>
-Displays version information and then exits.
+Enables logging to the standard error stream and to the syslog. The <I>--close-stderr</I> and <I>--no-syslog</I> options can be used to disable output to standard error stream and the syslog separately. Note that <I>--as-server</I>, <I>--as-client</I> and <I>--as-proxy</I> imply <I>--log</I>, and <I>--as-server</I> and <I>--as-proxy</I> also imply <I>--close-stderr</I>.
+<DT><B>-g, --debug</B>
+
+<DD>
+Enables debug level logging, if built in. Debug messages are usually only useful when cross-referenced with the source code and they may expose plaintext passwords and mail message content.
+<DT><B>--log-address</B>
+
+<DD>
+Adds the network address of remote clients to the logging output.
+<DT><B>-N, --log-file </B><I>&lt;file&gt;</I>
+
+<DD>
+Redirects standard-error logging to the specified file. Logging to the log file is not affected by <I>--close-stderr</I>. The filename can include <I>%d</I> to get daily log files; the <I>%d</I> is replaced by the current date in the local timezone using a <I>YYYYMMDD</I> format.
+<DT><B>-L, --log-time</B>
+
+<DD>
+Adds a timestamp to the logging output using the local timezone.
+<DT><B>-n, --no-syslog</B>
+
+<DD>
+Disables logging to the syslog. Note that <I>--as-client</I> implies <I>--no-syslog</I>.
+<DT><B>-k, --syslog, --syslog=</B><I>&lt;facility&gt;</I>
+
+<DD>
+When used with <I>--log</I> this option enables logging to the syslog even if the <I>--no-syslog</I> option is also used. This is typically used as a convenient override when using <I>--as-client</I>.
+<DT><B>-e, --close-stderr</B>
+
+<DD>
+Causes the standard error stream to be closed soon after start-up. This is useful when operating as a background daemon and it is therefore implied by <I>--as-server</I> and <I>--as-proxy</I>.
 </DL>
-<A NAME="lbAF">&nbsp;</A>
+<A NAME="lbAO">&nbsp;</A>
 <H2>SEE ALSO</H2>
 
 <B><A HREF="../man1/emailrelay-submit.1.html">emailrelay-submit</A></B>(1),
 
 <B><A HREF="../man1/emailrelay-passwd.1.html">emailrelay-passwd</A></B>(1),
 
-<A NAME="lbAG">&nbsp;</A>
+<A NAME="lbAP">&nbsp;</A>
 <H2>AUTHOR</H2>
 
 Graeme Walker, mailto:<A HREF="mailto:graeme_walker@users.sourceforge.net">graeme_walker@users.sourceforge.net</A>
@@ -361,8 +403,19 @@ Graeme Walker, mailto:<A HREF="mailto:graeme_walker@users.sourceforge.net">graem
 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 <DT><A HREF="#lbAE">OPTIONS</A><DD>
-<DT><A HREF="#lbAF">SEE ALSO</A><DD>
+<DL>
-<DT><A HREF="#lbAG">AUTHOR</A><DD>
+<DT><A HREF="#lbAF">Basic options</A><DD>
+<DT><A HREF="#lbAG">SMTP client options</A><DD>
+<DT><A HREF="#lbAH">SMTP server options</A><DD>
+<DT><A HREF="#lbAI">POP server options</A><DD>
+<DT><A HREF="#lbAJ">Admin server options</A><DD>
+<DT><A HREF="#lbAK">Authentication options</A><DD>
+<DT><A HREF="#lbAL">TLS options</A><DD>
+<DT><A HREF="#lbAM">Process options</A><DD>
+<DT><A HREF="#lbAN">Logging options</A><DD>
+</DL>
+<DT><A HREF="#lbAO">SEE ALSO</A><DD>
+<DT><A HREF="#lbAP">AUTHOR</A><DD>
 </DL>
 <HR>
 This document was created by
@@ -370,3 +423,4 @@ This document was created by
 using the manual pages.<BR>
 </BODY>
 </HTML>
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/emailrelay-passwd.1

@@ -1,4 +1,4 @@
-.\" Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+.\" Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 .\" 
 .\" This program is free software: you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
@@ -39,6 +39,21 @@ server md5 alice Oqng9/H7wAyKgbuqw5VzG1bNO6feqtblyiNEi6QuN5dH
 .br
 server md5 bob Ot6SDdGj23eWjdEuKICgN8Nj9z/Vx9IV3ISz9VvmnaUB
 .SH OPTIONS
+.TP
+.B \-H, --hash \fI<function>\fR
+Specifies the hash function, such as MD5 or SHA1. MD5 is the default, and a hash function of NONE does simple xtext encoding. Other hash function may or may not be available, depending on the build.
+.TP
+.B \-h, --help
+Shows help text and exits.
+.TP
+.B \-b, --base64
+The input password is interpreted as being base-64 encoded.
+.TP
+.B \-d, --dotted
+Generates a dotted decimal format, for backwards compatibility.
+.TP
+.B \-p, --password \fI<pwd>\fR
+Specifies the password to be hashed. Beware of leaking sensitive passwords via command-line history or the process-table when using this option.
 .SH SEE ALSO
 .BR emailrelay (1),
 .BR emailrelay-submit (1),

doc/emailrelay-submit.1

@@ -1,4 +1,4 @@
-.\" Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+.\" Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 .\" 
 .\" This program is free software: you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
@@ -33,6 +33,52 @@ spool directory.
 .LP
 The verbose option causes the path of the new content file
 to be printed.
+.SH OPTIONS
+.TP
+.B \-f, --from \fI<name>\fR
+Sets the envelope 'from' address.
+.TP
+.B \-h, --help
+Shows help text and exits.
+.TP
+.B \-s, --spool-dir \fI<dir>\fR
+Specifies the spool directory.
+.TP
+.B \-v, --verbose
+Prints the full path of the content file.
+.TP
+.B \-d, --content-date
+Adds a \fIDate:\fR content header if there is none.
+.TP
+.B \-F, --content-from
+Adds the envelope 'from' addresses as a \fIFrom:\fR content header.
+.TP
+.B \-t, --content-to
+Adds the envelope 'to' addresses as \fITo:\fR content headers.
+.TP
+.B \-c, --copy
+Copies the envelope file into all sub-directories of the main spool directory.
+.TP
+.B \-n, --filename
+Prints the name of the content file.
+.TP
+.B \-V, --version
+Prints the version number and exits.
+.TP
+.B \-a, --auth \fI<name>\fR
+Sets the authentication value in the envelope file.
+.TP
+.B \-C, --content \fI<base64>\fR
+Sets a line of content. This can be a header line, a blank line or a line of the body text. The first blank line separates headers  from the body. The option value should be base64 encoded.
+.TP
+.B \-i, --from-auth-in \fI<name>\fR
+Sets the 'from-auth-in' value in the envelope file.
+.TP
+.B \-o, --from-auth-out \fI<name>\fR
+Sets the 'from-auth-out' value in the envelope file.
+.TP
+.B \-N, --no-stdin
+Ignores the standard-input. Typically used with \fI\fR\fI--content\fR\fI\fR.
 .SH SEE ALSO
 .BR emailrelay (1),
 .BR emailrelay-passwd (1)

doc/emailrelay.1

@@ -1,4 +1,4 @@
-.\" Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+.\" Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 .\" 
 .\" This program is free software: you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
@@ -51,18 +51,7 @@ In this mode all e-mail messages are spooled temporarily while the
 client is connected and forwarded as soon as the client
 disconnects.
 .SH OPTIONS
-.TP
+.SS Basic options
-.B --address-verifier \fI<program>\fR
-Runs the specified external program to verify a message recipent's e-mail address. A network verifier can be specified as \fInet:<transport-address>\fR.
-.TP
-.B \-a, --admin \fI<admin-port>\fR
-Enables an administration interface on the specified listening port number. Use telnet or something similar to connect. The administration interface can be used to trigger forwarding of spooled mail messages if the \fI--forward-to\fR option is used.
-.TP
-.B \-Q, --admin-terminate
-Enables the \fIterminate\fR command in the administration interface.
-.TP
-.B \-A, --anonymous
-Disables the server's SMTP VRFY command, sends less verbose SMTP responses and SMTP greeting, and stops \fIReceived\fR lines being added to mail message content files.
 .TP
 .B \-q, --as-client \fI<host:port>\fR
 This is equivalent to \fI--log\fR, \fI--no-syslog\fR, \fI--no-daemon\fR, \fI--dont-serve\fR, \fI--forward\fR and \fI--forward-to\fR. It is a convenient way of running a forwarding agent that forwards spooled mail messages and then terminates.
@@ -73,17 +62,119 @@ This is equivalent to \fI--log\fR, \fI--close-stderr\fR, \fI--forward-on-disconn
 .B \-d, --as-server
 This is equivalent to \fI--log\fR and \fI--close-stderr\fR. It is a convenient way of running a background storage daemon that accepts mail messages and spools them. Use \fI--log\fR instead of \fI--as-server\fR to keep standard error stream open.
 .TP
+.B \-s, --spool-dir \fI<dir>\fR
+Specifies the directory used for holding mail messages that have been received but not yet forwarded.
+.TP
+.B \-h, --help
+Displays help text and then exits. Use with \fI--verbose\fR for more complete output.
+.TP
+.B \-V, --version
+Displays version information and then exits.
+.SS SMTP client options
+.TP
+.B \-f, --forward
+Causes spooled mail messages to be forwarded when the program first starts.
+.TP
+.B \-1, --forward-on-disconnect
+Causes spooled mail messages to be forwarded whenever a SMTP client connection disconnects.
+.TP
+.B \-o, --forward-to \fI<host:port>\fR
+Specifies the transport address of the remote SMTP server that spooled mail messages are forwarded to.
+.TP
+.B \-O, --poll \fI<period>\fR
+Causes forwarding of spooled mail messages to happen at regular intervals (with the time given in seconds).
+.TP
+.B \-Y, --client-filter \fI<program>\fR
+Runs the specified external filter program whenever a mail message is forwarded. The filter is passed the name of the message file in the spool directory so that it can edit it as required. A network filter can be specified as \fInet:<tcp-address>\fR and prefixes of \fIspam:\fR, \fIspam-edit:\fR and \fIexit:\fR are also allowed. The \fIspam:\fR and \fIspam-edit:\fR prefixes require a SpamAssassin daemon to be running. For store-and-forward applications the \fI--filter\fR option is normally more useful than \fI--client-filter\fR.
+.TP
+.B \-6, --client-interface \fI<ip-address>\fR
+Specifies the IP network address to be used to bind the local end of outgoing SMTP connections. By default the address will depend on the routing tables in the normal way. Use \fI0.0.0.0\fR to use only IPv4 addresses returned from DNS lookups of the \fI--forward-to\fR address, or \fI::\fR for IPv6.
+.TP
+.B \-U, --connection-timeout \fI<time>\fR
+Specifies a timeout (in seconds) for establishing a TCP connection to remote SMTP servers. The default is 40 seconds.
+.TP
+.B --idle-timeout \fI<time>\fR
+Specifies a timeout (in seconds) for receiving network traffic from remote SMTP and POP clients. The default is 60 seconds.
+.TP
+.B \-T, --response-timeout \fI<time>\fR
+Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 60 seconds.
+.TP
+.B --forward-to-some
+Allow forwarding to continue even if some recipient addresses on an e-mail envelope are rejected by the remote server.
+.TP
+.B \-m, --immediate
+Causes mail messages to be forwarded as they are received, even before they have been accepted. This can be used to do proxying without store-and-forward, but in practice clients tend to to time out while waiting for their mail message to be accepted.
+.SS SMTP server options
+.TP
+.B \-p, --port \fI<port>\fR
+Sets the port number used for listening for incoming SMTP connections.
+.TP
+.B \-r, --remote-clients
+Allows incoming connections from addresses that are not local. The default behaviour is to reject connections that are not local in order to prevent accidental exposure to the public internet, although a firewall should also be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
+.TP
+.B --address-verifier \fI<program>\fR
+Runs the specified external program to verify a message recipent's e-mail address. A network verifier can be specified as \fInet:<tcp-address>\fR.
+.TP
+.B \-A, --anonymous, --anonymous=\fI<scope>\fR
+Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and responses, stops \fIReceived\fR lines being added to mail message content files, and stops the SMTP client protocol adding \fIAUTH=\fR to the \fIMAIL\fR command. For finer control use a comma-separated list of things to anonymise: \fIvrfy\fR, \fIserver\fR, \fIcontent\fR and/or \fIclient\fR, eg. \fI--anonymous\fR=server,content.
+.TP
+.B --dnsbl \fI<config>\fR
+Specifies a list of DNSBL servers that are used to reject SMTP connections from blocked addresses. The configuration string is made up of comma-separated fields: the DNS server's transport address, a timeout in milliseconds, a rejection threshold, and then the list of DNSBL servers.
+.TP
+.B \-D, --domain \fI<fqdn>\fR
+Specifies the network name that is used in SMTP EHLO commands, \fIReceived\fR lines, and for generating authentication challenges. The default is derived from a DNS lookup of the local hostname.
+.TP
+.B \-z, --filter \fI<program>\fR
+Runs the specified external filter program whenever a mail message is stored. The filter is passed the name of the message file in the spool directory so that it can edit it as required. The mail message is rejected if the filter program terminates with an exit code between 1 and 99. Use \fInet:<tcp-address>\fR to communicate with a filter daemon over the network, or \fIspam:<tcp-address>\fR for a spamassassin spamd daemon to accept or reject mail messages, or \fIspam-edit:<tcp-address>\fR to have spamassassin edit the message content without rejecting it, or \fIexit:<number>\fR to emulate a filter program that just exits.
+.TP
+.B \-W, --filter-timeout \fI<time>\fR
+Specifies a timeout (in seconds) for running a \fI--filter\fR program. The default is 60 seconds.
+.TP
+.B \-I, --interface \fI<ip-address-list>\fR
+Specifies the IP network addresses or interface names used to bind listening ports. By default listening ports for incoming SMTP, POP and administration connections will bind the 'any' address for IPv4 and for IPv6, ie. \fI0.0.0.0\fR and \fI::\fR. Multiple addresses can be specified by using the option more than once or by using a comma-separated list. Use a prefix of \fIsmtp=\fR, \fIpop=\fR or \fIadmin=\fR on addresses that should apply only to those types of listening port. Any link-local IPv6 addresses must include a zone name or scope id.  Interface names can be used instead of addresses, in which case all the addresses associated with that interface at startup will used for listening. When an interface name is decorated with a \fI-ipv4\fR or \fI-ipv6\fR suffix only their IPv4 or IPv6 addresses will be used (eg. \fIppp0-ipv4\fR).  To inherit listening file descriptors from the parent process on unix use a syntax like this: \fI--interface\fR=smtp=fd#3,smtp=fd#4,pop=fd#5.
+.TP
+.B \-w, --prompt-timeout \fI<time>\fR
+Specifies a timeout (in seconds) for getting the initial prompt from a remote SMTP server. If no prompt is received after this time then the SMTP dialog goes ahead without it.
+.TP
+.B \-M, --size \fI<bytes>\fR
+Limits the size of mail messages that can be submitted over SMTP.
+.SS POP server options
+.TP
+.B \-B, --pop
+Enables the POP server, listening by default on port 110, providing access to spooled mail messages. Negotiated TLS using the POP \fISTLS\fR command will be enabled if the \fI--server-tls\fR option is also given.
+.TP
+.B \-J, --pop-by-name
+Modifies the spool directory used by the POP server to be a sub-directory with the same name as the POP authentication user-id. This allows multiple POP clients to read the spooled mail messages without interfering with each other, particularly when also using \fI--pop-no-delete\fR. Content files can stay in the main spool directory with only the envelope files copied into user-specific sub-directories. The \fIemailrelay-filter-copy\fR program is a convenient way of doing this when run via \fI--filter\fR.
+.TP
+.B \-G, --pop-no-delete
+Disables the POP DELE command so that the command appears to succeed but mail messages are not deleted from the spool directory.
+.TP
+.B \-E, --pop-port \fI<port>\fR
+Sets the POP server's listening port number.
+.SS Admin server options
+.TP
+.B \-a, --admin \fI<port>\fR
+Enables an administration interface on the specified listening port number. Use telnet or something similar to connect. The administration interface can be used to trigger forwarding of spooled mail messages if the \fI--forward-to\fR option is used.
+.TP
+.B \-Q, --admin-terminate
+Enables the \fIterminate\fR command in the administration interface.
+.SS Authentication options
+.TP
 .B \-C, --client-auth \fI<file>\fR
 Enables SMTP client authentication with the remote server, using the client account details taken from the specified secrets file. The secrets file should normally contain one line that starts with \fIclient\fR and that line should have between four and five space-separated fields; the second field is the password encoding (\fIplain\fR or \fImd5\fR), the third is the user-id and the fourth is the password. The user-id is RFC-1891 xtext encoded, and the password is either xtext encoded or generated by \fIemailrelay-passwd\fR. If the remote server does not support SMTP authentication then the SMTP connection will fail.
 .TP
 .B --client-auth-config \fI<config>\fR
-Configures the SMTP client authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of authentication mechanisms, and an 'x' is used for blocklisted mechanisms.
+Configures the SMTP client authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of preferred authentication mechanisms and an 'x' introduces a list of mechanisms to avoid. An 'a' list and a 'd' list can be used similarly to prefer and avoid certain mechanisms once the session is encrypted with TLS.
 .TP
-.B \-Y, --client-filter \fI<program>\fR
+.B \-S, --server-auth \fI<file>\fR
-Runs the specified external filter program whenever a mail message is forwarded. The filter is passed the name of the message file in the spool directory so that it can edit it as required. A network filter can be specified as \fInet:<transport-address>\fR and prefixes of \fIspam:\fR, \fIspam-edit:\fR and \fIexit:\fR are also allowed. The \fIspam:\fR and \fIspam-edit:\fR prefixes require a SpamAssassin daemon to be running. For store-and-forward applications the \fI--filter\fR option is normally more useful than \fI--client-filter\fR.
+Enables SMTP server authentication of remote SMTP clients. Account names and passwords are taken from the specified secrets file. The secrets file should contain lines that have four space-separated fields, starting with \fIserver\fR in the first field; the second field is the password encoding (\fIplain\fR or \fImd5\fR), the third is the client user-id and the fourth is the password. The user-id is RFC-1891 xtext encoded, and the password is either xtext encoded or generated by \fIemailrelay-passwd\fR. A special value of \fI/pam\fR can be used for authentication using linux PAM.
 .TP
-.B \-6, --client-interface \fI<ip-address>\fR
+.B --server-auth-config \fI<config>\fR
-Specifies the IP network address to be used to bind the local end of outgoing SMTP connections. By default the address will depend on the routing tables in the normal way. Use \fI0.0.0.0\fR to use only IPv4 addresses returned from DNS lookups of the \fI--forward-to\fR address, or \fI::\fR for IPv6.
+Configures the SMTP server authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces an ordered list of allowed authentication mechanisms and an 'x' introduces a list of mechanisms to deny. An 'a' list and a 'd' list can be used similarly to allow and deny mechanisms once the session is encrypted with TLS. In typical usage you might have an empty allow list for an unencrypted session and a single preferred mechanism once encrypted, \fIm:;a:plain\fR.
+.TP
+.B \-F, --pop-auth \fI<file>\fR
+Specifies a file containing valid POP account details. The file format is the same as for the SMTP server secrets file, ie. lines starting with \fIserver\fR, with user-id and password in the third and fourth fields. A special value of \fI/pam\fR can be used for authentication using linux PAM.
+.SS TLS options
 .TP
 .B \-j, --client-tls
 Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS command will be issued if the remote server supports it.
@@ -106,120 +197,6 @@ Enables verification of the remote SMTP server's certificate against any of the
 .B --client-tls-verify-name \fI<cname>\fR
 Enables verification of the CNAME within the remote SMTP server's certificate.
 .TP
-.B \-e, --close-stderr
-Causes the standard error stream to be closed soon after start-up. This is useful when operating as a background daemon and it is therefore implied by \fI--as-server\fR and \fI--as-proxy\fR.
-.TP
-.B \-U, --connection-timeout \fI<time>\fR
-Specifies a timeout (in seconds) for establishing a TCP connection to remote SMTP servers. The default is 40 seconds.
-.TP
-.B \-g, --debug
-Enables debug level logging, if built in. Debug messages are usually only useful when cross-referenced with the source code and they may expose plaintext passwords and mail message content.
-.TP
-.B --dnsbl \fI<config>\fR
-Specifies a list of DNSBL servers that are used to reject SMTP connections from blocked addresses. The configuration string is made up of comma-separated fields: the DNS server's transport address, a timeout in milliseconds, a rejection threshold, and then the list of DNSBL servers.
-.TP
-.B \-D, --domain \fI<fqdn>\fR
-Specifies the network name that is used in SMTP EHLO commands, \fIReceived\fR lines, and for generating authentication challenges. The default is derived from a DNS lookup of the local hostname.
-.TP
-.B \-x, --dont-serve
-Disables all network serving, including SMTP, POP and administration interfaces. The program will terminate as soon as any initial forwarding is complete.
-.TP
-.B \-z, --filter \fI<program>\fR
-Runs the specified external filter program whenever a mail message is stored. The filter is passed the name of the message file in the spool directory so that it can edit it as required. The mail message is rejected if the filter program terminates with an exit code between 1 and 99. Use \fInet:<transport-address>\fR to communicate with a filter daemon over the network, or \fIspam:<transport-address>\fR for a spamassassin spamd daemon to accept or reject mail messages, or \fIspam-edit:<transport-address>\fR to have spamassassin edit the message content without rejecting it, or \fIexit:<number>\fR to emulate a filter program that just exits.
-.TP
-.B \-W, --filter-timeout \fI<time>\fR
-Specifies a timeout (in seconds) for running a \fI--filter\fR program. The default is 300 seconds.
-.TP
-.B \-f, --forward
-Causes spooled mail messages to be forwarded when the program first starts.
-.TP
-.B \-1, --forward-on-disconnect
-Causes spooled mail messages to be forwarded whenever a SMTP client connection disconnects.
-.TP
-.B \-o, --forward-to \fI<host:port>\fR
-Specifies the transport address of the remote SMTP server that is use for mail message forwarding.
-.TP
-.B --forward-to-some
-Allow forwarding to continue even if some recipient addresses on an e-mail envelope are rejected by the remote server.
-.TP
-.B \-h, --help
-Displays help text and then exits. Use with \fI--verbose\fR for more complete output.
-.TP
-.B \-H, --hidden
-Windows only. Hides the application window and disables all message boxes, overriding any \fI--show\fR option. This is useful when running as a windows service.
-.TP
-.B --idle-timeout \fI<time>\fR
-Specifies a timeout (in seconds) for receiving network traffic from remote SMTP and POP clients. The default is 1800 seconds.
-.TP
-.B \-m, --immediate
-Causes mail messages to be forwarded as they are received, even before they have been accepted. This can be used to do proxying without store-and-forward, but in practice clients tend to to time out while waiting for their mail message to be accepted.
-.TP
-.B \-I, --interface \fI<ip-address-list>\fR
-Specifies the IP network addresses or interface names used to bind listening ports. By default listening ports for incoming SMTP, POP and administration connections will bind the 'any' address for IPv4 and for IPv6, ie. \fI0.0.0.0\fR and \fI::\fR. Multiple addresses can be specified by using the option more than once or by using a comma-separated list. Use a prefix of \fIsmtp=\fR, \fIpop=\fR or \fIadmin=\fR on addresses that should apply only to those types of listening port. Any link-local IPv6 addresses must include a zone name or scope id.  Interface names can be used instead of addresses, in which case all the addresses associated with that interface at startup will used for listening. When an interface name is decorated with a \fI-ipv4\fR or \fI-ipv6\fR suffix only their IPv4 or IPv6 addresses will be used (eg. \fIppp0-ipv4\fR).
-.TP
-.B --localedir \fI<dir>\fR
-Enables localisation and specifies the locale base directory where message catalogues can be found. An empty directory can be used for the built-in default.
-.TP
-.B \-l, --log
-Enables logging to the standard error stream and to the syslog. The \fI--close-stderr\fR and \fI--no-syslog\fR options can be used to disable output to standard error stream and the syslog separately. Note that \fI--as-server\fR, \fI--as-client\fR and \fI--as-proxy\fR imply \fI--log\fR, and \fI--as-server\fR and \fI--as-proxy\fR also imply \fI--close-stderr\fR.
-.TP
-.B --log-address
-Adds the network address of remote clients to the logging output.
-.TP
-.B \-N, --log-file \fI<file>\fR
-Redirects standard-error logging to the specified file. Logging to the log file is not affected by \fI--close-stderr\fR. The filename can include \fI%d\fR to get daily log files; the \fI%d\fR is replaced by the current date in the local timezone using a \fIYYYYMMDD\fR format.
-.TP
-.B \-L, --log-time
-Adds a timestamp to the logging output using the local timezone.
-.TP
-.B \-t, --no-daemon
-Disables the normal backgrounding at startup so that the program runs in the foreground, without forking or detaching from the terminal.  On Windows this disables the system tray icon so the program uses a normal window; when the window is closed the program terminates.
-.TP
-.B \-X, --no-smtp
-Disables listening for incoming SMTP connections.
-.TP
-.B \-n, --no-syslog
-Disables logging to the syslog. Note that \fI--as-client\fR implies \fI--no-syslog\fR.
-.TP
-.B \-i, --pid-file \fI<pid-file>\fR
-Causes the process-id to be written into the specified file when the program starts up, typically after it has become a background daemon.
-.TP
-.B \-O, --poll \fI<period>\fR
-Causes forwarding of spooled mail messages to happen at regular intervals (with the time given in seconds).
-.TP
-.B \-B, --pop
-Enables the POP server listening, by default on port 110, providing access to spooled mail messages. Negotiated TLS using the POP \fISTLS\fR command will be enabled if the \fI--server-tls\fR option is also given.
-.TP
-.B \-F, --pop-auth \fI<file>\fR
-Specifies a file containing valid POP account details. The file format is the same as for the SMTP server secrets file, ie. lines starting with \fIserver\fR, with user-id and password in the third and fourth fields. A special value of \fI/pam\fR can be used for authentication using linux PAM.
-.TP
-.B \-J, --pop-by-name
-Modifies the spool directory used by the POP server to be a sub-directory with the same name as the POP authentication user-id. This allows multiple POP clients to read the spooled messages without interfering with each other, particularly when also using \fI--pop-no-delete\fR. Content files can stay in the main spool directory with only the envelope files copied into user-specific sub-directories. The \fIemailrelay-filter-copy\fR program is a convenient way of doing this when run via \fI--filter\fR.
-.TP
-.B \-G, --pop-no-delete
-Disables the POP DELE command so that the command appears to succeed but mail messages are not deleted from the spool directory.
-.TP
-.B \-E, --pop-port \fI<port>\fR
-Sets the POP server's listening port number.
-.TP
-.B \-p, --port \fI<port>\fR
-Sets the port number used for listening for incoming SMTP connections.
-.TP
-.B \-w, --prompt-timeout \fI<time>\fR
-Specifies a timeout (in seconds) for getting the initial prompt from a remote SMTP server. If no prompt is received after this time then the SMTP dialog goes ahead without it.
-.TP
-.B \-r, --remote-clients
-Allows incoming connections from addresses that are not local. The default behaviour is to reject connections that are not local in order to prevent accidental exposure to the public internet, although a firewall should also be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
-.TP
-.B \-T, --response-timeout \fI<time>\fR
-Specifies a timeout (in seconds) for getting responses from remote SMTP servers. The default is 1800 seconds.
-.TP
-.B \-S, --server-auth \fI<file>\fR
-Enables SMTP server authentication of remote SMTP clients. Account names and passwords are taken from the specified secrets file. The secrets file should contain lines that have four space-separated fields, starting with \fIserver\fR in the first field; the second field is the password encoding (\fIplain\fR or \fImd5\fR), the third is the client user-id and the fourth is the password. The user-id is RFC-1891 xtext encoded, and the password is either xtext encoded or generated by \fIemailrelay-passwd\fR. A special value of \fI/pam\fR can be used for authentication using linux PAM.
-.TP
-.B --server-auth-config \fI<config>\fR
-Configures the SMTP server authentication module using a semicolon-separated list of configuration items. Each item is a single-character key, followed by a colon and then a comma-separated list. A 'm' character introduces a preferred sub-set of the built-in authentication mechanisms, and an 'x' is used for blocklisted mechanisms.
-.TP
 .B \-K, --server-tls
 Enables TLS for incoming SMTP and POP connections. SMTP clients can then request TLS encryption by issuing the STARTTLS command. The \fI--server-tls-certificate\fR option must be used to define the server certificate.
 .TP
@@ -235,26 +212,58 @@ Makes the use of TLS mandatory for any incoming SMTP and POP connections. SMTP c
 .B --server-tls-verify \fI<ca-list>\fR
 Enables verification of remote SMTP and POP clients' certificates against any of the trusted CA certificates in the specified file or directory. In many use cases this should be a file containing just your self-signed root certificate. Specify \fI<default>\fR for the TLS library's default set of trusted CAs.
 .TP
-.B \-M, --size \fI<bytes>\fR
-Limits the size of mail messages that can be submitted over SMTP.
-.TP
-.B \-s, --spool-dir \fI<dir>\fR
-Specifies the directory used for holding mail messages that have been received but not yet forwarded.
-.TP
-.B \-k, --syslog, --syslog=\fI<facility>\fR
-When used with \fI--log\fR this option enables logging to the syslog even if the \fI--no-syslog\fR option is also used. This is typically used as a convenient override when using \fI--as-client\fR.
-.TP
 .B \-9, --tls-config \fI<options>\fR
 Selects and configures the low-level TLS library, using a comma-separated list of keywords. If OpenSSL and mbedTLS are both built in then keywords of \fIopenssl\fR and \fImbedtls\fR will select one or the other. Keywords like \fItlsv1.0\fR can be used to set a minimum TLS protocol version, or \fI-tlsv1.2\fR to set a maximum version.
+.SS Process options
+.TP
+.B \-x, --dont-serve
+Disables all network serving, including SMTP, POP and administration interfaces. The program will terminate as soon as any initial forwarding is complete.
+.TP
+.B \-H, --hidden
+Windows only. Hides the application window and disables all message boxes, overriding any \fI--show\fR option. This is useful when running as a windows service.
+.TP
+.B --localedir \fI<dir>\fR
+Enables localisation and specifies the locale base directory where message catalogues can be found. An empty directory can be used for the built-in default.
+.TP
+.B \-t, --no-daemon
+Disables the normal backgrounding at startup so that the program runs in the foreground, without forking or detaching from the terminal.  On Windows this disables the system tray icon so the program uses a normal window; when the window is closed the program terminates.
+.TP
+.B \-X, --no-smtp
+Disables listening for incoming SMTP connections.
+.TP
+.B \-i, --pid-file \fI<path>\fR
+Causes the process-id to be written into the specified file when the program starts up, typically after it has become a background daemon. The immediate parent directory is created if necessary.
 .TP
 .B \-u, --user \fI<username>\fR
-When started as root the program switches to a non-privileged effective user-id when idle. This option can be used to define the idle user-id and also the group ownership of new files and sockets. Specify \fIroot\fR to  disable all user-id switching. Ignored on Windows.
+When started as root the program switches to a non-privileged effective user-id when idle. This option can be used to define the idle user-id and also the group ownership of new files and sockets. Specify \fIroot\fR to disable all user-id switching. Ignored on Windows.
+.SS Logging options
 .TP
 .B \-v, --verbose
 Enables more verbose logging when used with \fI--log\fR, and more verbose help when used with \fI--help\fR.
 .TP
-.B \-V, --version
+.B \-l, --log
-Displays version information and then exits.
+Enables logging to the standard error stream and to the syslog. The \fI--close-stderr\fR and \fI--no-syslog\fR options can be used to disable output to standard error stream and the syslog separately. Note that \fI--as-server\fR, \fI--as-client\fR and \fI--as-proxy\fR imply \fI--log\fR, and \fI--as-server\fR and \fI--as-proxy\fR also imply \fI--close-stderr\fR.
+.TP
+.B \-g, --debug
+Enables debug level logging, if built in. Debug messages are usually only useful when cross-referenced with the source code and they may expose plaintext passwords and mail message content.
+.TP
+.B --log-address
+Adds the network address of remote clients to the logging output.
+.TP
+.B \-N, --log-file \fI<file>\fR
+Redirects standard-error logging to the specified file. Logging to the log file is not affected by \fI--close-stderr\fR. The filename can include \fI%d\fR to get daily log files; the \fI%d\fR is replaced by the current date in the local timezone using a \fIYYYYMMDD\fR format.
+.TP
+.B \-L, --log-time
+Adds a timestamp to the logging output using the local timezone.
+.TP
+.B \-n, --no-syslog
+Disables logging to the syslog. Note that \fI--as-client\fR implies \fI--no-syslog\fR.
+.TP
+.B \-k, --syslog, --syslog=\fI<facility>\fR
+When used with \fI--log\fR this option enables logging to the syslog even if the \fI--no-syslog\fR option is also used. This is typically used as a convenient override when using \fI--as-client\fR.
+.TP
+.B \-e, --close-stderr
+Causes the standard error stream to be closed soon after start-up. This is useful when operating as a background daemon and it is therefore implied by \fI--as-server\fR and \fI--as-proxy\fR.
 .SH SEE ALSO
 .BR emailrelay-submit (1),
 .BR emailrelay-passwd (1),

doc/emailrelay.css

@@ -1,5 +1,5 @@
 /*
-  Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+  Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 */
 
 /*
@@ -26,6 +26,12 @@ h2
 	color: #09c ;
 }
 
+h3
+{
+	font-size: smaller ;
+	color: #09c ;
+}
+
 div.div-main
 {
 	margin-left: 10% ;

doc/forwardto.svg

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
 
 <svg
    xmlns:dc="http://purl.org/dc/elements/1.1/"

doc/index.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay index</title>
@@ -20,4 +20,4 @@
    </div>
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/make-website

@@ -1,6 +1,6 @@
 #!/usr/bin/env perl
 #
-# Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
+# Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>
 # 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -175,11 +175,11 @@ sub make_mainpage_md
 		my $line_number = 0 ;
 		while( $line_number < $lines )
 		{
-			my $line = @lines[$line_number++] ;
+			my $line = $lines[$line_number++] ;
-			my $next_line = @lines[$line_number] ;
+			my $next_line = $lines[$line_number] ;
 			if( $next_line =~ m/^=====+$/ )
 			{
-				@lines[$line_number] = undef ;
+				$lines[$line_number] = undef ;
 				$line =~ s/E-MailRelay // ;
 				( my $id = basename($fname) . "_$line" ) =~ s/[- '?.]/_/g ;
 				print $fh "\\section $id $line\n" ;
@@ -191,14 +191,14 @@ sub make_mainpage_md
 			}
 			elsif( $next_line =~ m/^-----+$/ )
 			{
-				@lines[$line_number] = undef ;
+				$lines[$line_number] = undef ;
 				$line =~ s/^E-MailRelay // ;
 				( my $id = basename($fname) . "_$line" ) =~ s/[- '?.]/_/g ;
 				print $fh "\\subsection $id $line\n" ;
 			}
 			elsif( $line =~ m/^______+$/ )
 			{
-				@lines[$line_number] = undef ; # no footer text
+				$lines[$line_number] = undef ; # no footer text
 			}
 			elsif( defined($line) )
 			{
@@ -262,15 +262,15 @@ sub make_pages_md
 		my $line_number = 0 ;
 		while( $line_number < $lines )
 		{
-			my $line = @lines[$line_number++] ;
+			my $line = $lines[$line_number++] ;
-			my $next_line = @lines[$line_number] ;
+			my $next_line = $lines[$line_number] ;
 			if( $next_line =~ m/^=====+$/ )
 			{
-				@lines[$line_number] = undef ;
+				$lines[$line_number] = undef ;
 			}
 			elsif( $next_line =~ m/^---+$/ )
 			{
-				@lines[$line_number] = undef ;
+				$lines[$line_number] = undef ;
 				( my $id = "changelog_$line" ) =~ s/[- '?.>]/_/g ;
 				print $fh_out "\\section $id $line\n" ;
 			}

doc/man2html-missing.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay man page unavailable</title>
@@ -12,4 +12,4 @@
   </div>
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/readme.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "%-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay Readme</title>
@@ -8,7 +8,7 @@
  <body>
   <!-- index:0::::E-MailRelay Readme -->
  <div class="div-main">
-  <h1><a class="a-header" name="H_1">E-MailRelay Readme</a></h1> <!-- index:1:H:1::E-MailRelay Readme -->
+  <h1><a class="a-header" name="H_1">E-MailRelay Readme</a></h1> <!-- index:1:H:E-MailRelay Readme -->
    <h2><a class="a-header" name="SH_1_1">Abstract</a></h2> <!-- index:2:SH:1:1:Abstract -->
     <p>
      E-MailRelay is an e-mail store-and-forward message transfer agent and proxy
@@ -132,7 +132,43 @@
       <div class="div-pre">
        <pre>emailrelay --help --verbose</pre>
       </div><!-- div-pre -->
-   <h2><a class="a-header" name="SH_1_3">Documentation</a></h2> <!-- index:2:SH:1:3:Documentation -->
+   <h2><a class="a-header" name="SH_1_3">Packages</a></h2> <!-- index:2:SH:1:3:Packages -->
+    <p>
+     To install on Linux from a RPM or DEB package:
+    </p>
+
+      <div class="div-pre">
+       <pre>sudo $SHELL # or 'su'
+rpm -i emailrelay*.rpm  # if RPM
+dpkg -i emailrelay*.deb  # if DEB
+</pre>
+      </div><!-- div-pre -->
+    <p>
+     If your Linux system uses <em>systemd</em> then you should check the E-MailRelay
+     configuration file <em>/etc/emailrelay.conf</em> is as you want it and then run:
+    </p>
+
+      <div class="div-pre">
+       <pre>systemctl enable emailrelay
+systemctl start emailrelay
+systemctl status emailrelay
+</pre>
+      </div><!-- div-pre -->
+    <p>
+     On other systems try these commands:
+    </p>
+
+      <div class="div-pre">
+       <pre>cp /usr/lib/emailrelay/init/emailrelay /etc/init.d/
+update-rc.d emailrelay enable || rc-update add emailrelay
+invoke-rc.d emailrelay start || service emailrelay start
+tail /var/log/messages /var/log/syslog 2&gt;/dev/null
+</pre>
+      </div><!-- div-pre -->
+    <p>
+     On Windows run the setup program.
+    </p>
+   <h2><a class="a-header" name="SH_1_4">Documentation</a></h2> <!-- index:2:SH:1:4:Documentation -->
     <p>
      The following documentation is provided:
     </p>
@@ -150,12 +186,8 @@
      Source code documentation will be generated when building from source if
      <em>doxygen</em> is available.
     </p>
-   <h2><a class="a-header" name="SH_1_4">Feedback</a></h2> <!-- index:2:SH:1:4:Feedback -->
-    <p>
-     Please feel free to e-mail the author at <em>mailto:graeme_walker@users.sourceforge.net</em>.
-    </p>
 
  </div> <!-- div-main -->
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/readme.md

@@ -79,6 +79,30 @@ or run:
 
         emailrelay --help --verbose
 
+Packages
+--------
+To install on Linux from a RPM or DEB package:
+
+        sudo $SHELL # or 'su'
+        rpm -i emailrelay*.rpm  # if RPM
+        dpkg -i emailrelay*.deb  # if DEB
+
+If your Linux system uses `systemd` then you should check the E-MailRelay
+configuration file `/etc/emailrelay.conf` is as you want it and then run:
+
+        systemctl enable emailrelay
+        systemctl start emailrelay
+        systemctl status emailrelay
+
+On other systems try these commands:
+
+        cp /usr/lib/emailrelay/init/emailrelay /etc/init.d/
+        update-rc.d emailrelay enable || rc-update add emailrelay
+        invoke-rc.d emailrelay start || service emailrelay start
+        tail /var/log/messages /var/log/syslog 2>/dev/null
+
+On Windows run the setup program.
+
 Documentation
 -------------
 The following documentation is provided:
@@ -94,10 +118,6 @@ The following documentation is provided:
 Source code documentation will be generated when building from source if
 `doxygen` is available.
 
-Feedback
---------
-Please feel free to e-mail the author at `mailto:graeme_walker@users.sourceforge.net`.
-
 
 [POP]: https://en.wikipedia.org/wiki/Post_Office_Protocol
 [SMTP]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol

doc/readme.rst

@@ -100,6 +100,36 @@ or run:
 
     emailrelay --help --verbose
 
+Packages
+========
+To install on Linux from a RPM or DEB package:
+
+::
+
+    sudo $SHELL # or 'su'
+    rpm -i emailrelay*.rpm  # if RPM
+    dpkg -i emailrelay*.deb  # if DEB
+
+If your Linux system uses *systemd* then you should check the E-MailRelay
+configuration file */etc/emailrelay.conf* is as you want it and then run:
+
+::
+
+    systemctl enable emailrelay
+    systemctl start emailrelay
+    systemctl status emailrelay
+
+On other systems try these commands:
+
+::
+
+    cp /usr/lib/emailrelay/init/emailrelay /etc/init.d/
+    update-rc.d emailrelay enable || rc-update add emailrelay
+    invoke-rc.d emailrelay start || service emailrelay start
+    tail /var/log/messages /var/log/syslog 2>/dev/null
+
+On Windows run the setup program.
+
 Documentation
 =============
 The following documentation is provided:
@@ -115,10 +145,6 @@ The following documentation is provided:
 Source code documentation will be generated when building from source if
 *doxygen* is available.
 
-Feedback
-========
-Please feel free to e-mail the author at *mailto:graeme_walker@users.sourceforge.net*.
-
 
 .. _POP: https://en.wikipedia.org/wiki/Post_Office_Protocol
 .. _SMTP: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol

doc/readme.txt

@@ -73,6 +73,30 @@ or run:
 
 	emailrelay --help --verbose
 
+Packages
+--------
+To install on Linux from a RPM or DEB package:
+
+	sudo $SHELL # or 'su'
+	rpm -i emailrelay*.rpm  # if RPM
+	dpkg -i emailrelay*.deb  # if DEB
+
+If your Linux system uses "systemd" then you should check the E-MailRelay
+configuration file "/etc/emailrelay.conf" is as you want it and then run:
+
+	systemctl enable emailrelay
+	systemctl start emailrelay
+	systemctl status emailrelay
+
+On other systems try these commands:
+
+	cp /usr/lib/emailrelay/init/emailrelay /etc/init.d/
+	update-rc.d emailrelay enable || rc-update add emailrelay
+	invoke-rc.d emailrelay start || service emailrelay start
+	tail /var/log/messages /var/log/syslog 2>/dev/null
+
+On Windows run the setup program.
+
 Documentation
 -------------
 The following documentation is provided:
@@ -87,7 +111,3 @@ The following documentation is provided:
 Source code documentation will be generated when building from source if
 "doxygen" is available.
 
-Feedback
---------
-Please feel free to e-mail the author at "mailto:graeme_walker@users.sourceforge.net".
-

doc/reference.html

@@ -15,36 +15,10 @@
     </p>
 
       <div class="div-pre">
-       <pre>emailrelay [&lt;option&gt; [&lt;option&gt; ...]] [&lt;config-file&gt;]
+       <pre>emailrelay [&lt;option&gt; [&lt;option&gt; ...]] [&lt;config-file&gt;]</pre>
-</pre>
       </div><!-- div-pre -->
-    <p>
+   <h3><a class="a-header">Basic options</a></h3>
-     where &lt;option&gt; is:
-    </p>
-
     <dl>
-     <dt>--address-verifier &lt;program&gt;</dt>
-      <dd>
-       Runs the specified external program to verify a message recipent's e-mail
-       address. A network verifier can be specified as <em>net:<transport-address></em>.
-      </dd>
-     <dt>--admin &lt;admin-port&gt; (-a)</dt>
-      <dd>
-       Enables an administration interface on the specified listening port number.
-       Use telnet or something similar to connect. The administration interface
-       can be used to trigger forwarding of spooled mail messages if the
-       <em>--forward-to</em> option is used.
-      </dd>
-     <dt>--admin-terminate (-Q)</dt>
-      <dd>
-       Enables the <em>terminate</em> command in the administration interface.
-      </dd>
-     <dt>--anonymous (-A)</dt>
-      <dd>
-       Disables the server's SMTP VRFY command, sends less verbose SMTP responses
-       and SMTP greeting, and stops <em>Received</em> lines being added to mail message
-       content files.
-      </dd>
      <dt>--as-client &lt;host:port&gt; (-q)</dt>
       <dd>
        This is equivalent to <em>--log</em>, <em>--no-syslog</em>, <em>--no-daemon</em>, <em>--dont-serve</em>,
@@ -65,6 +39,215 @@
        them. Use <em>--log</em> instead of <em>--as-server</em> to keep standard error stream
        open.
       </dd>
+     <dt>--spool-dir &lt;dir&gt; (-s)</dt>
+      <dd>
+       Specifies the directory used for holding mail messages that have been
+       received but not yet forwarded.
+      </dd>
+     <dt>--help (-h)</dt>
+      <dd>
+       Displays help text and then exits. Use with <em>--verbose</em> for more complete
+       output.
+      </dd>
+     <dt>--version (-V)</dt>
+      <dd>
+       Displays version information and then exits.
+      </dd>
+    </dl>
+   <h3><a class="a-header">SMTP client options</a></h3>
+    <dl>
+     <dt>--forward (-f)</dt>
+      <dd>
+       Causes spooled mail messages to be forwarded when the program first starts.
+      </dd>
+     <dt>--forward-on-disconnect (-1)</dt>
+      <dd>
+       Causes spooled mail messages to be forwarded whenever a SMTP client
+       connection disconnects.
+      </dd>
+     <dt>--forward-to &lt;host:port&gt; (-o)</dt>
+      <dd>
+       Specifies the transport address of the remote SMTP server that spooled mail
+       messages are forwarded to.
+      </dd>
+     <dt>--poll &lt;period&gt; (-O)</dt>
+      <dd>
+       Causes forwarding of spooled mail messages to happen at regular intervals
+       (with the time given in seconds).
+      </dd>
+     <dt>--client-filter &lt;program&gt; (-Y)</dt>
+      <dd>
+       Runs the specified external filter program whenever a mail message is
+       forwarded. The filter is passed the name of the message file in the spool
+       directory so that it can edit it as required. A network filter can be
+       specified as <em>net:<tcp-address></em> and prefixes of <em>spam:</em>, <em>spam-edit:</em> and
+       <em>exit:</em> are also allowed. The <em>spam:</em> and <em>spam-edit:</em> prefixes require a
+       SpamAssassin daemon to be running. For store-and-forward applications the
+       <em>--filter</em> option is normally more useful than <em>--client-filter</em>.
+      </dd>
+     <dt>--client-interface &lt;ip-address&gt; (-6)</dt>
+      <dd>
+       Specifies the IP network address to be used to bind the local end of outgoing
+       SMTP connections. By default the address will depend on the routing tables
+       in the normal way. Use <em>0.0.0.0</em> to use only IPv4 addresses returned from
+       DNS lookups of the <em>--forward-to</em> address, or <em>::</em> for IPv6.
+      </dd>
+     <dt>--connection-timeout &lt;time&gt; (-U)</dt>
+      <dd>
+       Specifies a timeout (in seconds) for establishing a TCP connection to remote
+       SMTP servers. The default is 40 seconds.
+      </dd>
+     <dt>--idle-timeout &lt;time&gt;</dt>
+      <dd>
+       Specifies a timeout (in seconds) for receiving network traffic from remote
+       SMTP and POP clients. The default is 60 seconds.
+      </dd>
+     <dt>--response-timeout &lt;time&gt; (-T)</dt>
+      <dd>
+       Specifies a timeout (in seconds) for getting responses from remote SMTP
+       servers. The default is 60 seconds.
+      </dd>
+     <dt>--forward-to-some</dt>
+      <dd>
+       Allow forwarding to continue even if some recipient addresses on an e-mail
+       envelope are rejected by the remote server.
+      </dd>
+     <dt>--immediate (-m)</dt>
+      <dd>
+       Causes mail messages to be forwarded as they are received, even before they
+       have been accepted. This can be used to do proxying without
+       store-and-forward, but in practice clients tend to to time out while
+       waiting for their mail message to be accepted.
+      </dd>
+    </dl>
+   <h3><a class="a-header">SMTP server options</a></h3>
+    <dl>
+     <dt>--port &lt;port&gt; (-p)</dt>
+      <dd>
+       Sets the port number used for listening for incoming SMTP connections.
+      </dd>
+     <dt>--remote-clients (-r)</dt>
+      <dd>
+       Allows incoming connections from addresses that are not local. The default
+       behaviour is to reject connections that are not local in order to prevent
+       accidental exposure to the public internet, although a firewall should also
+       be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
+      </dd>
+     <dt>--address-verifier &lt;program&gt;</dt>
+      <dd>
+       Runs the specified external program to verify a message recipent's e-mail
+       address. A network verifier can be specified as <em>net:<tcp-address></em>.
+      </dd>
+     <dt>--anonymous[=&lt;scope&gt;] (-A)</dt>
+      <dd>
+       Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and
+       responses, stops <em>Received</em> lines being added to mail message content
+       files, and stops the SMTP client protocol adding <em>AUTH=</em> to the <em>MAIL</em>
+       command. For finer control use a comma-separated list of things to
+       anonymise: <em>vrfy</em>, <em>server</em>, <em>content</em> and/or <em>client</em>, eg.
+       <em>--anonymous</em>=server,content.
+      </dd>
+     <dt>--dnsbl &lt;config&gt;</dt>
+      <dd>
+       Specifies a list of DNSBL servers that are used to reject SMTP connections
+       from blocked addresses. The configuration string is made up of
+       comma-separated fields: the DNS server's transport address, a timeout in
+       milliseconds, a rejection threshold, and then the list of DNSBL servers.
+      </dd>
+     <dt>--domain &lt;fqdn&gt; (-D)</dt>
+      <dd>
+       Specifies the network name that is used in SMTP EHLO commands, <em>Received</em>
+       lines, and for generating authentication challenges. The default is derived
+       from a DNS lookup of the local hostname.
+      </dd>
+     <dt>--filter &lt;program&gt; (-z)</dt>
+      <dd>
+       Runs the specified external filter program whenever a mail message is stored.
+       The filter is passed the name of the message file in the spool directory so
+       that it can edit it as required. The mail message is rejected if the filter
+       program terminates with an exit code between 1 and 99. Use
+       <em>net:<tcp-address></em> to communicate with a filter daemon over the network,
+       or <em>spam:<tcp-address></em> for a spamassassin spamd daemon to accept or reject
+       mail messages, or <em>spam-edit:<tcp-address></em> to have spamassassin edit the
+       message content without rejecting it, or <em>exit:<number></em> to emulate a
+       filter program that just exits.
+      </dd>
+     <dt>--filter-timeout &lt;time&gt; (-W)</dt>
+      <dd>
+       Specifies a timeout (in seconds) for running a <em>--filter</em> program. The
+       default is 60 seconds.
+      </dd>
+     <dt>--interface &lt;ip-address-list&gt; (-I)</dt>
+      <dd>
+       Specifies the IP network addresses or interface names used to bind listening
+       ports. By default listening ports for incoming SMTP, POP and administration
+       connections will bind the 'any' address for IPv4 and for IPv6, ie.
+       <em>0.0.0.0</em> and <em>::</em>. Multiple addresses can be specified by using the option
+       more than once or by using a comma-separated list. Use a prefix of <em>smtp=</em>,
+       <em>pop=</em> or <em>admin=</em> on addresses that should apply only to those types of
+       listening port. Any link-local IPv6 addresses must include a zone name or
+       scope id.  Interface names can be used instead of addresses, in which case
+       all the addresses associated with that interface at startup will used for
+       listening. When an interface name is decorated with a <em>-ipv4</em> or <em>-ipv6</em>
+       suffix only their IPv4 or IPv6 addresses will be used (eg. <em>ppp0-ipv4</em>).
+       To inherit listening file descriptors from the parent process on unix use a
+       syntax like this: <em>--interface</em>=smtp=fd#3,smtp=fd#4,pop=fd#5.
+      </dd>
+     <dt>--prompt-timeout &lt;time&gt; (-w)</dt>
+      <dd>
+       Specifies a timeout (in seconds) for getting the initial prompt from a remote
+       SMTP server. If no prompt is received after this time then the SMTP dialog
+       goes ahead without it.
+      </dd>
+     <dt>--size &lt;bytes&gt; (-M)</dt>
+      <dd>
+       Limits the size of mail messages that can be submitted over SMTP.
+      </dd>
+    </dl>
+   <h3><a class="a-header">POP server options</a></h3>
+    <dl>
+     <dt>--pop (-B)</dt>
+      <dd>
+       Enables the POP server, listening by default on port 110, providing access to
+       spooled mail messages. Negotiated TLS using the POP <em>STLS</em> command will be
+       enabled if the <em>--server-tls</em> option is also given.
+      </dd>
+     <dt>--pop-by-name (-J)</dt>
+      <dd>
+       Modifies the spool directory used by the POP server to be a sub-directory
+       with the same name as the POP authentication user-id. This allows multiple
+       POP clients to read the spooled mail messages without interfering with each
+       other, particularly when also using <em>--pop-no-delete</em>. Content files can
+       stay in the main spool directory with only the envelope files copied into
+       user-specific sub-directories. The <em>emailrelay-filter-copy</em> program is a
+       convenient way of doing this when run via <em>--filter</em>.
+      </dd>
+     <dt>--pop-no-delete (-G)</dt>
+      <dd>
+       Disables the POP DELE command so that the command appears to succeed but mail
+       messages are not deleted from the spool directory.
+      </dd>
+     <dt>--pop-port &lt;port&gt; (-E)</dt>
+      <dd>
+       Sets the POP server's listening port number.
+      </dd>
+    </dl>
+   <h3><a class="a-header">Admin server options</a></h3>
+    <dl>
+     <dt>--admin &lt;port&gt; (-a)</dt>
+      <dd>
+       Enables an administration interface on the specified listening port number.
+       Use telnet or something similar to connect. The administration interface
+       can be used to trigger forwarding of spooled mail messages if the
+       <em>--forward-to</em> option is used.
+      </dd>
+     <dt>--admin-terminate (-Q)</dt>
+      <dd>
+       Enables the <em>terminate</em> command in the administration interface.
+      </dd>
+    </dl>
+   <h3><a class="a-header">Authentication options</a></h3>
+    <dl>
      <dt>--client-auth &lt;file&gt; (-C)</dt>
       <dd>
        Enables SMTP client authentication with the remote server, using the client
@@ -82,27 +265,43 @@
        Configures the SMTP client authentication module using a semicolon-separated
        list of configuration items. Each item is a single-character key, followed
        by a colon and then a comma-separated list. A 'm' character introduces an
-       ordered list of authentication mechanisms, and an 'x' is used for
+       ordered list of preferred authentication mechanisms and an 'x' introduces a
-       blocklisted mechanisms.
+       list of mechanisms to avoid. An 'a' list and a 'd' list can be used
+       similarly to prefer and avoid certain mechanisms once the session is
+       encrypted with TLS.
       </dd>
-     <dt>--client-filter &lt;program&gt; (-Y)</dt>
+     <dt>--server-auth &lt;file&gt; (-S)</dt>
       <dd>
-       Runs the specified external filter program whenever a mail message is
+       Enables SMTP server authentication of remote SMTP clients. Account names and
-       forwarded. The filter is passed the name of the message file in the spool
+       passwords are taken from the specified secrets file. The secrets file
-       directory so that it can edit it as required. A network filter can be
+       should contain lines that have four space-separated fields, starting with
-       specified as <em>net:<transport-address></em> and prefixes of <em>spam:</em>,
+       <em>server</em> in the first field; the second field is the password encoding
-       <em>spam-edit:</em> and <em>exit:</em> are also allowed. The <em>spam:</em> and <em>spam-edit:</em>
+       (<em>plain</em> or <em>md5</em>), the third is the client user-id and the fourth is the
-       prefixes require a SpamAssassin daemon to be running. For store-and-forward
+       password. The user-id is RFC-1891 xtext encoded, and the password is either
-       applications the <em>--filter</em> option is normally more useful than
+       xtext encoded or generated by <em>emailrelay-passwd</em>. A special value of
-       <em>--client-filter</em>.
+       <em>/pam</em> can be used for authentication using linux PAM.
       </dd>
-     <dt>--client-interface &lt;ip-address&gt; (-6)</dt>
+     <dt>--server-auth-config &lt;config&gt;</dt>
       <dd>
-       Specifies the IP network address to be used to bind the local end of outgoing
+       Configures the SMTP server authentication module using a semicolon-separated
-       SMTP connections. By default the address will depend on the routing tables
+       list of configuration items. Each item is a single-character key, followed
-       in the normal way. Use <em>0.0.0.0</em> to use only IPv4 addresses returned from
+       by a colon and then a comma-separated list. A 'm' character introduces an
-       DNS lookups of the <em>--forward-to</em> address, or <em>::</em> for IPv6.
+       ordered list of allowed authentication mechanisms and an 'x' introduces a
+       list of mechanisms to deny. An 'a' list and a 'd' list can be used
+       similarly to allow and deny mechanisms once the session is encrypted with
+       TLS. In typical usage you might have an empty allow list for an unencrypted
+       session and a single preferred mechanism once encrypted, <em>m:;a:plain</em>.
       </dd>
+     <dt>--pop-auth &lt;file&gt; (-F)</dt>
+      <dd>
+       Specifies a file containing valid POP account details. The file format is the
+       same as for the SMTP server secrets file, ie. lines starting with <em>server</em>,
+       with user-id and password in the third and fourth fields. A special value
+       of <em>/pam</em> can be used for authentication using linux PAM.
+      </dd>
+    </dl>
+   <h3><a class="a-header">TLS options</a></h3>
+    <dl>
      <dt>--client-tls (-j)</dt>
       <dd>
        Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS
@@ -138,7 +337,7 @@
        Enables verification of the remote SMTP server's certificate against any of
        the trusted CA certificates in the specified file or directory. In many use
        cases this should be a file containing just your self-signed root
-       certificate. Specify <em>&lt;default&gt;</em> for the TLS library's default set of
+       certificate. Specify <em><default></em> for the TLS library's default set of
        trusted CAs.
       </dd>
      <dt>--client-tls-verify-name &lt;cname&gt;</dt>
@@ -146,243 +345,6 @@
        Enables verification of the CNAME within the remote SMTP server's
        certificate.
       </dd>
-     <dt>--close-stderr (-e)</dt>
-      <dd>
-       Causes the standard error stream to be closed soon after start-up. This is
-       useful when operating as a background daemon and it is therefore implied by
-       <em>--as-server</em> and <em>--as-proxy</em>.
-      </dd>
-     <dt>--connection-timeout &lt;time&gt; (-U)</dt>
-      <dd>
-       Specifies a timeout (in seconds) for establishing a TCP connection to remote
-       SMTP servers. The default is 40 seconds.
-      </dd>
-     <dt>--debug (-g)</dt>
-      <dd>
-       Enables debug level logging, if built in. Debug messages are usually only
-       useful when cross-referenced with the source code and they may expose
-       plaintext passwords and mail message content.
-      </dd>
-     <dt>--dnsbl &lt;config&gt;</dt>
-      <dd>
-       Specifies a list of DNSBL servers that are used to reject SMTP connections
-       from blocked addresses. The configuration string is made up of
-       comma-separated fields: the DNS server's transport address, a timeout in
-       milliseconds, a rejection threshold, and then the list of DNSBL servers.
-      </dd>
-     <dt>--domain &lt;fqdn&gt; (-D)</dt>
-      <dd>
-       Specifies the network name that is used in SMTP EHLO commands, <em>Received</em>
-       lines, and for generating authentication challenges. The default is derived
-       from a DNS lookup of the local hostname.
-      </dd>
-     <dt>--dont-serve (-x)</dt>
-      <dd>
-       Disables all network serving, including SMTP, POP and administration
-       interfaces. The program will terminate as soon as any initial forwarding is
-       complete.
-      </dd>
-     <dt>--filter &lt;program&gt; (-z)</dt>
-      <dd>
-       Runs the specified external filter program whenever a mail message is stored.
-       The filter is passed the name of the message file in the spool directory so
-       that it can edit it as required. The mail message is rejected if the filter
-       program terminates with an exit code between 1 and 99. Use
-       <em>net:<transport-address></em> to communicate with a filter daemon over the
-       network, or <em>spam:<transport-address></em> for a spamassassin spamd daemon to
-       accept or reject mail messages, or <em>spam-edit:<transport-address></em> to have
-       spamassassin edit the message content without rejecting it, or
-       <em>exit:<number></em> to emulate a filter program that just exits.
-      </dd>
-     <dt>--filter-timeout &lt;time&gt; (-W)</dt>
-      <dd>
-       Specifies a timeout (in seconds) for running a <em>--filter</em> program. The
-       default is 300 seconds.
-      </dd>
-     <dt>--forward (-f)</dt>
-      <dd>
-       Causes spooled mail messages to be forwarded when the program first starts.
-      </dd>
-     <dt>--forward-on-disconnect (-1)</dt>
-      <dd>
-       Causes spooled mail messages to be forwarded whenever a SMTP client
-       connection disconnects.
-      </dd>
-     <dt>--forward-to &lt;host:port&gt; (-o)</dt>
-      <dd>
-       Specifies the transport address of the remote SMTP server that is use for
-       mail message forwarding.
-      </dd>
-     <dt>--forward-to-some</dt>
-      <dd>
-       Allow forwarding to continue even if some recipient addresses on an e-mail
-       envelope are rejected by the remote server.
-      </dd>
-     <dt>--help (-h)</dt>
-      <dd>
-       Displays help text and then exits. Use with <em>--verbose</em> for more complete
-       output.
-      </dd>
-     <dt>--hidden (-H)</dt>
-      <dd>
-       Windows only. Hides the application window and disables all message boxes,
-       overriding any <em>--show</em> option. This is useful when running as a windows
-       service.
-      </dd>
-     <dt>--idle-timeout &lt;time&gt;</dt>
-      <dd>
-       Specifies a timeout (in seconds) for receiving network traffic from remote
-       SMTP and POP clients. The default is 1800 seconds.
-      </dd>
-     <dt>--immediate (-m)</dt>
-      <dd>
-       Causes mail messages to be forwarded as they are received, even before they
-       have been accepted. This can be used to do proxying without
-       store-and-forward, but in practice clients tend to to time out while
-       waiting for their mail message to be accepted.
-      </dd>
-     <dt>--interface &lt;ip-address-list&gt; (-I)</dt>
-      <dd>
-       Specifies the IP network addresses or interface names used to bind listening
-       ports. By default listening ports for incoming SMTP, POP and administration
-       connections will bind the 'any' address for IPv4 and for IPv6, ie.
-       <em>0.0.0.0</em> and <em>::</em>. Multiple addresses can be specified by using the option
-       more than once or by using a comma-separated list. Use a prefix of <em>smtp=</em>,
-       <em>pop=</em> or <em>admin=</em> on addresses that should apply only to those types of
-       listening port. Any link-local IPv6 addresses must include a zone name or
-       scope id.  Interface names can be used instead of addresses, in which case
-       all the addresses associated with that interface at startup will used for
-       listening. When an interface name is decorated with a <em>-ipv4</em> or <em>-ipv6</em>
-       suffix only their IPv4 or IPv6 addresses will be used (eg. <em>ppp0-ipv4</em>).
-      </dd>
-     <dt>--localedir &lt;dir&gt;</dt>
-      <dd>
-       Enables localisation and specifies the locale base directory where message
-       catalogues can be found. An empty directory can be used for the built-in
-       default.
-      </dd>
-     <dt>--log (-l)</dt>
-      <dd>
-       Enables logging to the standard error stream and to the syslog. The
-       <em>--close-stderr</em> and <em>--no-syslog</em> options can be used to disable output to
-       standard error stream and the syslog separately. Note that <em>--as-server</em>,
-       <em>--as-client</em> and <em>--as-proxy</em> imply <em>--log</em>, and <em>--as-server</em> and
-       <em>--as-proxy</em> also imply <em>--close-stderr</em>.
-      </dd>
-     <dt>--log-address</dt>
-      <dd>
-       Adds the network address of remote clients to the logging output.
-      </dd>
-     <dt>--log-file &lt;file&gt; (-N)</dt>
-      <dd>
-       Redirects standard-error logging to the specified file. Logging to the log
-       file is not affected by <em>--close-stderr</em>. The filename can include <em>%d</em> to
-       get daily log files; the <em>%d</em> is replaced by the current date in the local
-       timezone using a <em>YYYYMMDD</em> format.
-      </dd>
-     <dt>--log-time (-L)</dt>
-      <dd>
-       Adds a timestamp to the logging output using the local timezone.
-      </dd>
-     <dt>--no-daemon (-t)</dt>
-      <dd>
-       Disables the normal backgrounding at startup so that the program runs in the
-       foreground, without forking or detaching from the terminal.  On Windows
-       this disables the system tray icon so the program uses a normal window;
-       when the window is closed the program terminates.
-      </dd>
-     <dt>--no-smtp (-X)</dt>
-      <dd>
-       Disables listening for incoming SMTP connections.
-      </dd>
-     <dt>--no-syslog (-n)</dt>
-      <dd>
-       Disables logging to the syslog. Note that <em>--as-client</em> implies
-       <em>--no-syslog</em>.
-      </dd>
-     <dt>--pid-file &lt;pid-file&gt; (-i)</dt>
-      <dd>
-       Causes the process-id to be written into the specified file when the program
-       starts up, typically after it has become a background daemon.
-      </dd>
-     <dt>--poll &lt;period&gt; (-O)</dt>
-      <dd>
-       Causes forwarding of spooled mail messages to happen at regular intervals
-       (with the time given in seconds).
-      </dd>
-     <dt>--pop (-B)</dt>
-      <dd>
-       Enables the POP server listening, by default on port 110, providing access to
-       spooled mail messages. Negotiated TLS using the POP <em>STLS</em> command will be
-       enabled if the <em>--server-tls</em> option is also given.
-      </dd>
-     <dt>--pop-auth &lt;file&gt; (-F)</dt>
-      <dd>
-       Specifies a file containing valid POP account details. The file format is the
-       same as for the SMTP server secrets file, ie. lines starting with <em>server</em>,
-       with user-id and password in the third and fourth fields. A special value
-       of <em>/pam</em> can be used for authentication using linux PAM.
-      </dd>
-     <dt>--pop-by-name (-J)</dt>
-      <dd>
-       Modifies the spool directory used by the POP server to be a sub-directory
-       with the same name as the POP authentication user-id. This allows multiple
-       POP clients to read the spooled messages without interfering with each
-       other, particularly when also using <em>--pop-no-delete</em>. Content files can
-       stay in the main spool directory with only the envelope files copied into
-       user-specific sub-directories. The <em>emailrelay-filter-copy</em> program is a
-       convenient way of doing this when run via <em>--filter</em>.
-      </dd>
-     <dt>--pop-no-delete (-G)</dt>
-      <dd>
-       Disables the POP DELE command so that the command appears to succeed but mail
-       messages are not deleted from the spool directory.
-      </dd>
-     <dt>--pop-port &lt;port&gt; (-E)</dt>
-      <dd>
-       Sets the POP server's listening port number.
-      </dd>
-     <dt>--port &lt;port&gt; (-p)</dt>
-      <dd>
-       Sets the port number used for listening for incoming SMTP connections.
-      </dd>
-     <dt>--prompt-timeout &lt;time&gt; (-w)</dt>
-      <dd>
-       Specifies a timeout (in seconds) for getting the initial prompt from a remote
-       SMTP server. If no prompt is received after this time then the SMTP dialog
-       goes ahead without it.
-      </dd>
-     <dt>--remote-clients (-r)</dt>
-      <dd>
-       Allows incoming connections from addresses that are not local. The default
-       behaviour is to reject connections that are not local in order to prevent
-       accidental exposure to the public internet, although a firewall should also
-       be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
-      </dd>
-     <dt>--response-timeout &lt;time&gt; (-T)</dt>
-      <dd>
-       Specifies a timeout (in seconds) for getting responses from remote SMTP
-       servers. The default is 1800 seconds.
-      </dd>
-     <dt>--server-auth &lt;file&gt; (-S)</dt>
-      <dd>
-       Enables SMTP server authentication of remote SMTP clients. Account names and
-       passwords are taken from the specified secrets file. The secrets file
-       should contain lines that have four space-separated fields, starting with
-       <em>server</em> in the first field; the second field is the password encoding
-       (<em>plain</em> or <em>md5</em>), the third is the client user-id and the fourth is the
-       password. The user-id is RFC-1891 xtext encoded, and the password is either
-       xtext encoded or generated by <em>emailrelay-passwd</em>. A special value of
-       <em>/pam</em> can be used for authentication using linux PAM.
-      </dd>
-     <dt>--server-auth-config &lt;config&gt;</dt>
-      <dd>
-       Configures the SMTP server authentication module using a semicolon-separated
-       list of configuration items. Each item is a single-character key, followed
-       by a colon and then a comma-separated list. A 'm' character introduces a
-       preferred sub-set of the built-in authentication mechanisms, and an 'x' is
-       used for blocklisted mechanisms.
-      </dd>
      <dt>--server-tls (-K)</dt>
       <dd>
        Enables TLS for incoming SMTP and POP connections. SMTP clients can then
@@ -414,24 +376,9 @@
        Enables verification of remote SMTP and POP clients' certificates against any
        of the trusted CA certificates in the specified file or directory. In many
        use cases this should be a file containing just your self-signed root
-       certificate. Specify <em>&lt;default&gt;</em> for the TLS library's default set of
+       certificate. Specify <em><default></em> for the TLS library's default set of
        trusted CAs.
       </dd>
-     <dt>--size &lt;bytes&gt; (-M)</dt>
-      <dd>
-       Limits the size of mail messages that can be submitted over SMTP.
-      </dd>
-     <dt>--spool-dir &lt;dir&gt; (-s)</dt>
-      <dd>
-       Specifies the directory used for holding mail messages that have been
-       received but not yet forwarded.
-      </dd>
-     <dt>--syslog[=&lt;facility&gt;] (-k)</dt>
-      <dd>
-       When used with <em>--log</em> this option enables logging to the syslog even if the
-       <em>--no-syslog</em> option is also used. This is typically used as a convenient
-       override when using <em>--as-client</em>.
-      </dd>
      <dt>--tls-config &lt;options&gt; (-9)</dt>
       <dd>
        Selects and configures the low-level TLS library, using a comma-separated
@@ -440,6 +387,44 @@
        <em>tlsv1.0</em> can be used to set a minimum TLS protocol version, or <em>-tlsv1.2</em>
        to set a maximum version.
       </dd>
+    </dl>
+   <h3><a class="a-header">Process options</a></h3>
+    <dl>
+     <dt>--dont-serve (-x)</dt>
+      <dd>
+       Disables all network serving, including SMTP, POP and administration
+       interfaces. The program will terminate as soon as any initial forwarding is
+       complete.
+      </dd>
+     <dt>--hidden (-H)</dt>
+      <dd>
+       Windows only. Hides the application window and disables all message boxes,
+       overriding any <em>--show</em> option. This is useful when running as a windows
+       service.
+      </dd>
+     <dt>--localedir &lt;dir&gt;</dt>
+      <dd>
+       Enables localisation and specifies the locale base directory where message
+       catalogues can be found. An empty directory can be used for the built-in
+       default.
+      </dd>
+     <dt>--no-daemon (-t)</dt>
+      <dd>
+       Disables the normal backgrounding at startup so that the program runs in the
+       foreground, without forking or detaching from the terminal.  On Windows
+       this disables the system tray icon so the program uses a normal window;
+       when the window is closed the program terminates.
+      </dd>
+     <dt>--no-smtp (-X)</dt>
+      <dd>
+       Disables listening for incoming SMTP connections.
+      </dd>
+     <dt>--pid-file &lt;path&gt; (-i)</dt>
+      <dd>
+       Causes the process-id to be written into the specified file when the program
+       starts up, typically after it has become a background daemon. The immediate
+       parent directory is created if necessary.
+      </dd>
      <dt>--user &lt;username&gt; (-u)</dt>
       <dd>
        When started as root the program switches to a non-privileged effective
@@ -447,14 +432,59 @@
        also the group ownership of new files and sockets. Specify <em>root</em> to
        disable all user-id switching. Ignored on Windows.
       </dd>
+    </dl>
+   <h3><a class="a-header">Logging options</a></h3>
+    <dl>
      <dt>--verbose (-v)</dt>
       <dd>
        Enables more verbose logging when used with <em>--log</em>, and more verbose help
        when used with <em>--help</em>.
       </dd>
-     <dt>--version (-V)</dt>
+     <dt>--log (-l)</dt>
       <dd>
-       Displays version information and then exits.
+       Enables logging to the standard error stream and to the syslog. The
+       <em>--close-stderr</em> and <em>--no-syslog</em> options can be used to disable output to
+       standard error stream and the syslog separately. Note that <em>--as-server</em>,
+       <em>--as-client</em> and <em>--as-proxy</em> imply <em>--log</em>, and <em>--as-server</em> and
+       <em>--as-proxy</em> also imply <em>--close-stderr</em>.
+      </dd>
+     <dt>--debug (-g)</dt>
+      <dd>
+       Enables debug level logging, if built in. Debug messages are usually only
+       useful when cross-referenced with the source code and they may expose
+       plaintext passwords and mail message content.
+      </dd>
+     <dt>--log-address</dt>
+      <dd>
+       Adds the network address of remote clients to the logging output.
+      </dd>
+     <dt>--log-file &lt;file&gt; (-N)</dt>
+      <dd>
+       Redirects standard-error logging to the specified file. Logging to the log
+       file is not affected by <em>--close-stderr</em>. The filename can include <em>%d</em> to
+       get daily log files; the <em>%d</em> is replaced by the current date in the local
+       timezone using a <em>YYYYMMDD</em> format.
+      </dd>
+     <dt>--log-time (-L)</dt>
+      <dd>
+       Adds a timestamp to the logging output using the local timezone.
+      </dd>
+     <dt>--no-syslog (-n)</dt>
+      <dd>
+       Disables logging to the syslog. Note that <em>--as-client</em> implies
+       <em>--no-syslog</em>.
+      </dd>
+     <dt>--syslog[=&lt;facility&gt;] (-k)</dt>
+      <dd>
+       When used with <em>--log</em> this option enables logging to the syslog even if the
+       <em>--no-syslog</em> option is also used. This is typically used as a convenient
+       override when using <em>--as-client</em>.
+      </dd>
+     <dt>--close-stderr (-e)</dt>
+      <dd>
+       Causes the standard error stream to be closed soon after start-up. This is
+       useful when operating as a background daemon and it is therefore implied by
+       <em>--as-server</em> and <em>--as-proxy</em>.
       </dd>
     </dl>
     <p>
@@ -906,7 +936,7 @@ server plain carol my+20password
     </p>
 
       <div class="div-pre">
-       <pre>$ openssl req -x509 -nodes -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
+       <pre>$ openssl req -x509 -noenc -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
 </pre>
       </div><!-- div-pre -->
     <p>
@@ -957,21 +987,15 @@ server plain carol my+20password
 
       <div class="div-pre">
        <pre>auth requisite pam_unix.so nullok_secure
-session required pam_permit.so
-account required pam_permit.so
-password required pam_deny.so
 </pre>
       </div><!-- div-pre -->
     <p>
      With this configuration the E-MailRelay server will use normal unix system
      account names and passwords to authenticate remote clients. On some systems
      this will require special permissioning to allow the E-MailRelay server to
-     read the shadow password database.
+     read the shadow password database, so run the server as <em>root</em> and also add the
-    </p>
+     <em>--user=root</em> command-line option to make sure that the process's effective
-
+     user-id stays as <em>root</em> while it accesses the PAM system.
-    <p>
-     When using PAM authentication E-MailRelay requires that remote clients
-     establish an encrypted session using TLS before authentication can proceed.
     </p>
    <h2><a class="a-header" name="SH_1_8">IP addresses</a></h2> <!-- index:2:SH:1:8:IP addresses -->
     <p>
@@ -1413,9 +1437,7 @@ catch( e )
     <p>
      The following are some security issues that have been taken into consideration:
     </p>
-
+   <h3><a class="a-header">Effective userid</a></h3>
-    <dl>
-     <dt>Effective userid</dt>
       <dd>
        Suid privileges are revoked at start-up, switching the effective
        userid/groupid to be the real userid/groupid values. If started as <em>root</em>
@@ -1427,32 +1449,32 @@ catch( e )
        groupid, so that new files have group ownership corresponding to the
        <em>daemon</em> user.
       </dd>
-     <dt>Execution environment</dt>
+   <h3><a class="a-header">Execution environment</a></h3>
       <dd>
        The external filter programs are run with an almost empty set of environment
        variables (<em>PATH</em> and <em>IFS</em>), and with no open file descriptors other than
        <em>stdin</em> and <em>stderr</em> open onto <em>/dev/null</em>, and <em>stdout</em> open onto a pipe.
       </dd>
-     <dt>Umask</dt>
+   <h3><a class="a-header">Umask</a></h3>
       <dd>
-       The program runs for most of the time with a <em>umask</em> of 177, switching to 117
+       The program runs for most of the time with a <em>umask</em> of 077, switching to 007
        when creating spool files.
       </dd>
-     <dt>Remote clients</dt>
+   <h3><a class="a-header">Remote clients</a></h3>
       <dd>
        By default connections will be rejected if they come from remote machines.
       </dd>
-     <dt>Remote configuration</dt>
+   <h3><a class="a-header">Remote configuration</a></h3>
       <dd>
        No configuration parameters can be changed through the administrative
        interface.
       </dd>
-     <dt>Use of exec() and system()</dt>
+   <h3><a class="a-header">Use of exec() and system()</a></h3>
       <dd>
        No exec(), system() or popen() calls are used other than execve() to spawn the
        mail filter and/or address verifier.
       </dd>
-     <dt>File permissions</dt>
+   <h3><a class="a-header">File permissions</a></h3>
       <dd>
        After a normal installation the spool directory is has ownership of
        <em>root.daemon</em> with permissions of <em>-rwxrwxr-x</em> and messages files are created
@@ -1464,7 +1486,7 @@ catch( e )
        spool directory, and the files created end up owned by the submitter but with
        group ownership of <em>daemon</em>.
       </dd>
-     <dt>Logging</dt>
+   <h3><a class="a-header">Logging</a></h3>
       <dd>
        Logging output is conditioned so that ANSI escape sequences cannot appear
        in the log.
@@ -1472,17 +1494,16 @@ catch( e )
        Passwords and message content are not logged (except if using the <em>--debug</em>
        option at run time with debug logging enabled at build time).
       </dd>
-     <dt>Information leakage</dt>
+   <h3><a class="a-header">Information leakage</a></h3>
       <dd>
        The <em>--anonymous</em> option can be used to reduce the amount of information
        leaked to remote clients.
       </dd>
-     <dt>Mandatory encryption</dt>
+   <h3><a class="a-header">Mandatory encryption</a></h3>
       <dd>
        When using PAM for authentication all clients are required to use
        TLS/SSL encryption.
       </dd>
-    </dl>
     <p>
      Security issues which relate to the SMTP protocol itself are beyond the scope
      of this document, but RFC-2821 makes the following observation: "SMTP mail is
@@ -1551,7 +1572,39 @@ E-MailRelay&gt; quit
      An E-MailRelay <em>--filter</em> script can be used to reject messages with incorrect
      <em>Bcc:</em> headers, and an example script is included.
     </p>
-   <h2><a class="a-header" name="SH_1_16">Files and directories</a></h2> <!-- index:2:SH:1:16:Files and directories -->
+   <h2><a class="a-header" name="SH_1_16">Routing</a></h2> <!-- index:2:SH:1:16:Routing -->
+    <p>
+     E-MailRelay does not normally do any routing of e-mail messages; they are
+     all forwarded to a fixed <em>smarthost</em> address given by the <em>--forward-to</em> or
+     <em>--as-client</em> command-line options.
+    </p>
+
+    <p>
+     However, each message envelope file contains a <em>ForwardToAddress</em> field that
+     can be populated by filter scripts in order to route the message to some other
+     server.
+    </p>
+
+    <p>
+     If the <em>ForwardTo</em> field has any non-empty value then E-MailRelay runs its
+     client filter early to allow the client filter script to set or update the
+     <em>ForwardToAddress</em> before the outgoing connection is made. (The client filter is
+     run a second time as normal once the connection is made and the SMTP session has
+     been established.)
+    </p>
+
+    <p>
+     Typically a <em>--filter</em> script would be used to examine the message content and
+     populate the <em>ForwardTo</em> field, then a <em>--client-filter</em> script would use
+     the <em>ForwardTo</em> value to populate the <em>ForwardToAddress</em> field with an up-to-date
+     forwarding address.
+    </p>
+
+    <p>
+     Note that a successful connection to the smarthost is required even if a message
+     is routed elsewhere.
+    </p>
+   <h2><a class="a-header" name="SH_1_17">Files and directories</a></h2> <!-- index:2:SH:1:17:Files and directories -->
     <p>
      On Unix-like systems E-MailRelay installs by default under <em>/usr/local</em>, but
      binary distributions will probably have been built to install elsewhere.
@@ -1611,10 +1664,10 @@ E-MailRelay&gt; quit
 
     <div class="div-footer">
      <p>
-      Copyright (C) 2001-2021 Graeme Walker
+      Copyright (C) 2001-2022 Graeme Walker
      </p>
     </div><!-- div-footer -->
  </div> <!-- div-main -->
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/reference.md

@@ -7,29 +7,7 @@ The `emailrelay` program supports the following command-line usage:
 
         emailrelay [<option> [<option> ...]] [<config-file>]
 
-where &lt;option&gt; is:
+### Basic options ###
-
-*   \-\-address-verifier &lt;program&gt;
-
-    Runs the specified external program to verify a message recipent's e-mail
-    address. A network verifier can be specified as `net:<transport-address>`.
-
-*   \-\-admin &lt;admin-port&gt; (-a)
-
-    Enables an administration interface on the specified listening port number.
-    Use telnet or something similar to connect. The administration interface
-    can be used to trigger forwarding of spooled mail messages if the
-    `--forward-to` option is used.
-
-*   \-\-admin-terminate (-Q)
-
-    Enables the `terminate` command in the administration interface.
-
-*   \-\-anonymous (-A)
-
-    Disables the server's [SMTP][] VRFY command, sends less verbose SMTP responses
-    and SMTP greeting, and stops `Received` lines being added to mail message
-    content files.
 
 *   \-\-as-client &lt;host:port&gt; (-q)
 
@@ -51,6 +29,215 @@ where &lt;option&gt; is:
     them. Use `--log` instead of `--as-server` to keep standard error stream
     open.
 
+*   \-\-spool-dir &lt;dir&gt; (-s)
+
+    Specifies the directory used for holding mail messages that have been
+    received but not yet forwarded.
+
+*   \-\-help (-h)
+
+    Displays help text and then exits. Use with `--verbose` for more complete
+    output.
+
+*   \-\-version (-V)
+
+    Displays version information and then exits.
+
+
+### [SMTP][] client options ###
+
+*   \-\-forward (-f)
+
+    Causes spooled mail messages to be forwarded when the program first starts.
+
+*   \-\-forward-on-disconnect (-1)
+
+    Causes spooled mail messages to be forwarded whenever a SMTP client
+    connection disconnects.
+
+*   \-\-forward-to &lt;host:port&gt; (-o)
+
+    Specifies the transport address of the remote SMTP server that spooled mail
+    messages are forwarded to.
+
+*   \-\-poll &lt;period&gt; (-O)
+
+    Causes forwarding of spooled mail messages to happen at regular intervals
+    (with the time given in seconds).
+
+*   \-\-client-filter &lt;program&gt; (-Y)
+
+    Runs the specified external filter program whenever a mail message is
+    forwarded. The filter is passed the name of the message file in the spool
+    directory so that it can edit it as required. A network filter can be
+    specified as `net:<tcp-address>` and prefixes of `spam:`, `spam-edit:` and
+    `exit:` are also allowed. The `spam:` and `spam-edit:` prefixes require a
+    SpamAssassin daemon to be running. For store-and-forward applications the
+    `--filter` option is normally more useful than `--client-filter`.
+
+*   \-\-client-interface &lt;ip-address&gt; (-6)
+
+    Specifies the IP network address to be used to bind the local end of outgoing
+    SMTP connections. By default the address will depend on the routing tables
+    in the normal way. Use `0.0.0.0` to use only IPv4 addresses returned from
+    DNS lookups of the `--forward-to` address, or `::` for IPv6.
+
+*   \-\-connection-timeout &lt;time&gt; (-U)
+
+    Specifies a timeout (in seconds) for establishing a TCP connection to remote
+    SMTP servers. The default is 40 seconds.
+
+*   \-\-idle-timeout &lt;time&gt;
+
+    Specifies a timeout (in seconds) for receiving network traffic from remote
+    SMTP and [POP][] clients. The default is 60 seconds.
+
+*   \-\-response-timeout &lt;time&gt; (-T)
+
+    Specifies a timeout (in seconds) for getting responses from remote SMTP
+    servers. The default is 60 seconds.
+
+*   \-\-forward-to-some
+
+    Allow forwarding to continue even if some recipient addresses on an e-mail
+    envelope are rejected by the remote server.
+
+*   \-\-immediate (-m)
+
+    Causes mail messages to be forwarded as they are received, even before they
+    have been accepted. This can be used to do proxying without
+    store-and-forward, but in practice clients tend to to time out while
+    waiting for their mail message to be accepted.
+
+
+### SMTP server options ###
+
+*   \-\-port &lt;port&gt; (-p)
+
+    Sets the port number used for listening for incoming SMTP connections.
+
+*   \-\-remote-clients (-r)
+
+    Allows incoming connections from addresses that are not local. The default
+    behaviour is to reject connections that are not local in order to prevent
+    accidental exposure to the public internet, although a firewall should also
+    be used. Local address ranges are defined in [RFC-1918][], RFC-6890 etc.
+
+*   \-\-address-verifier &lt;program&gt;
+
+    Runs the specified external program to verify a message recipent's e-mail
+    address. A network verifier can be specified as `net:<tcp-address>`.
+
+*   \-\-anonymous[=&lt;scope&gt;] (-A)
+
+    Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and
+    responses, stops `Received` lines being added to mail message content
+    files, and stops the SMTP client protocol adding `AUTH=` to the `MAIL`
+    command. For finer control use a comma-separated list of things to
+    anonymise: `vrfy`, `server`, `content` and/or `client`, eg.
+    `--anonymous`=server,content.
+
+*   \-\-dnsbl &lt;config&gt;
+
+    Specifies a list of [DNSBL][] servers that are used to reject SMTP connections
+    from blocked addresses. The configuration string is made up of
+    comma-separated fields: the DNS server's transport address, a timeout in
+    milliseconds, a rejection threshold, and then the list of DNSBL servers.
+
+*   \-\-domain &lt;fqdn&gt; (-D)
+
+    Specifies the network name that is used in SMTP EHLO commands, `Received`
+    lines, and for generating authentication challenges. The default is derived
+    from a DNS lookup of the local hostname.
+
+*   \-\-filter &lt;program&gt; (-z)
+
+    Runs the specified external filter program whenever a mail message is stored.
+    The filter is passed the name of the message file in the spool directory so
+    that it can edit it as required. The mail message is rejected if the filter
+    program terminates with an exit code between 1 and 99. Use
+    `net:<tcp-address>` to communicate with a filter daemon over the network,
+    or `spam:<tcp-address>` for a spamassassin spamd daemon to accept or reject
+    mail messages, or `spam-edit:<tcp-address>` to have spamassassin edit the
+    message content without rejecting it, or `exit:<number>` to emulate a
+    filter program that just exits.
+
+*   \-\-filter-timeout &lt;time&gt; (-W)
+
+    Specifies a timeout (in seconds) for running a `--filter` program. The
+    default is 60 seconds.
+
+*   \-\-interface &lt;ip-address-list&gt; (-I)
+
+    Specifies the IP network addresses or interface names used to bind listening
+    ports. By default listening ports for incoming SMTP, POP and administration
+    connections will bind the 'any' address for IPv4 and for IPv6, ie.
+    `0.0.0.0` and `::`. Multiple addresses can be specified by using the option
+    more than once or by using a comma-separated list. Use a prefix of `smtp=`,
+    `pop=` or `admin=` on addresses that should apply only to those types of
+    listening port. Any link-local IPv6 addresses must include a zone name or
+    scope id.  Interface names can be used instead of addresses, in which case
+    all the addresses associated with that interface at startup will used for
+    listening. When an interface name is decorated with a `-ipv4` or `-ipv6`
+    suffix only their IPv4 or IPv6 addresses will be used (eg. `ppp0-ipv4`).
+    To inherit listening file descriptors from the parent process on unix use a
+    syntax like this: `--interface`=smtp=fd#3,smtp=fd#4,pop=fd#5.
+
+*   \-\-prompt-timeout &lt;time&gt; (-w)
+
+    Specifies a timeout (in seconds) for getting the initial prompt from a remote
+    SMTP server. If no prompt is received after this time then the SMTP dialog
+    goes ahead without it.
+
+*   \-\-size &lt;bytes&gt; (-M)
+
+    Limits the size of mail messages that can be submitted over SMTP.
+
+
+### POP server options ###
+
+*   \-\-pop (-B)
+
+    Enables the POP server, listening by default on port 110, providing access to
+    spooled mail messages. Negotiated [TLS][] using the POP `STLS` command will be
+    enabled if the `--server-tls` option is also given.
+
+*   \-\-pop-by-name (-J)
+
+    Modifies the spool directory used by the POP server to be a sub-directory
+    with the same name as the POP authentication user-id. This allows multiple
+    POP clients to read the spooled mail messages without interfering with each
+    other, particularly when also using `--pop-no-delete`. Content files can
+    stay in the main spool directory with only the envelope files copied into
+    user-specific sub-directories. The `emailrelay-filter-copy` program is a
+    convenient way of doing this when run via `--filter`.
+
+*   \-\-pop-no-delete (-G)
+
+    Disables the POP DELE command so that the command appears to succeed but mail
+    messages are not deleted from the spool directory.
+
+*   \-\-pop-port &lt;port&gt; (-E)
+
+    Sets the POP server's listening port number.
+
+
+### Admin server options ###
+
+*   \-\-admin &lt;port&gt; (-a)
+
+    Enables an administration interface on the specified listening port number.
+    Use telnet or something similar to connect. The administration interface
+    can be used to trigger forwarding of spooled mail messages if the
+    `--forward-to` option is used.
+
+*   \-\-admin-terminate (-Q)
+
+    Enables the `terminate` command in the administration interface.
+
+
+### Authentication options ###
+
 *   \-\-client-auth &lt;file&gt; (-C)
 
     Enables SMTP client authentication with the remote server, using the client
@@ -68,30 +255,46 @@ where &lt;option&gt; is:
     Configures the SMTP client authentication module using a semicolon-separated
     list of configuration items. Each item is a single-character key, followed
     by a colon and then a comma-separated list. A 'm' character introduces an
-    ordered list of authentication mechanisms, and an 'x' is used for
+    ordered list of preferred authentication mechanisms and an 'x' introduces a
-    blocklisted mechanisms.
+    list of mechanisms to avoid. An 'a' list and a 'd' list can be used
+    similarly to prefer and avoid certain mechanisms once the session is
+    encrypted with TLS.
 
-*   \-\-client-filter &lt;program&gt; (-Y)
+*   \-\-server-auth &lt;file&gt; (-S)
 
-    Runs the specified external filter program whenever a mail message is
+    Enables SMTP server authentication of remote SMTP clients. Account names and
-    forwarded. The filter is passed the name of the message file in the spool
+    passwords are taken from the specified secrets file. The secrets file
-    directory so that it can edit it as required. A network filter can be
+    should contain lines that have four space-separated fields, starting with
-    specified as `net:<transport-address>` and prefixes of `spam:`,
+    `server` in the first field; the second field is the password encoding
-    `spam-edit:` and `exit:` are also allowed. The `spam:` and `spam-edit:`
+    (`plain` or `md5`), the third is the client user-id and the fourth is the
-    prefixes require a SpamAssassin daemon to be running. For store-and-forward
+    password. The user-id is [RFC-1891][] xtext encoded, and the password is either
-    applications the `--filter` option is normally more useful than
+    xtext encoded or generated by `emailrelay-passwd`. A special value of
-    `--client-filter`.
+    `/pam` can be used for authentication using linux [PAM][].
 
-*   \-\-client-interface &lt;ip-address&gt; (-6)
+*   \-\-server-auth-config &lt;config&gt;
 
-    Specifies the IP network address to be used to bind the local end of outgoing
+    Configures the SMTP server authentication module using a semicolon-separated
-    SMTP connections. By default the address will depend on the routing tables
+    list of configuration items. Each item is a single-character key, followed
-    in the normal way. Use `0.0.0.0` to use only IPv4 addresses returned from
+    by a colon and then a comma-separated list. A 'm' character introduces an
-    DNS lookups of the `--forward-to` address, or `::` for IPv6.
+    ordered list of allowed authentication mechanisms and an 'x' introduces a
+    list of mechanisms to deny. An 'a' list and a 'd' list can be used
+    similarly to allow and deny mechanisms once the session is encrypted with
+    TLS. In typical usage you might have an empty allow list for an unencrypted
+    session and a single preferred mechanism once encrypted, `m:;a:plain`.
+
+*   \-\-pop-auth &lt;file&gt; (-F)
+
+    Specifies a file containing valid POP account details. The file format is the
+    same as for the SMTP server secrets file, ie. lines starting with `server`,
+    with user-id and password in the third and fourth fields. A special value
+    of `/pam` can be used for authentication using linux PAM.
+
+
+### TLS options ###
 
 *   \-\-client-tls (-j)
 
-    Enables negotiated [TLS][] for outgoing SMTP connections; the SMTP STARTTLS
+    Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS
     command will be issued if the remote server supports it.
 
 *   \-\-client-tls-certificate &lt;pem-file&gt;
@@ -132,243 +335,6 @@ where &lt;option&gt; is:
     Enables verification of the CNAME within the remote SMTP server's
     certificate.
 
-*   \-\-close-stderr (-e)
-
-    Causes the standard error stream to be closed soon after start-up. This is
-    useful when operating as a background daemon and it is therefore implied by
-    `--as-server` and `--as-proxy`.
-
-*   \-\-connection-timeout &lt;time&gt; (-U)
-
-    Specifies a timeout (in seconds) for establishing a TCP connection to remote
-    SMTP servers. The default is 40 seconds.
-
-*   \-\-debug (-g)
-
-    Enables debug level logging, if built in. Debug messages are usually only
-    useful when cross-referenced with the source code and they may expose
-    plaintext passwords and mail message content.
-
-*   \-\-dnsbl &lt;config&gt;
-
-    Specifies a list of [DNSBL][] servers that are used to reject SMTP connections
-    from blocked addresses. The configuration string is made up of
-    comma-separated fields: the DNS server's transport address, a timeout in
-    milliseconds, a rejection threshold, and then the list of DNSBL servers.
-
-*   \-\-domain &lt;fqdn&gt; (-D)
-
-    Specifies the network name that is used in SMTP EHLO commands, `Received`
-    lines, and for generating authentication challenges. The default is derived
-    from a DNS lookup of the local hostname.
-
-*   \-\-dont-serve (-x)
-
-    Disables all network serving, including SMTP, [POP][] and administration
-    interfaces. The program will terminate as soon as any initial forwarding is
-    complete.
-
-*   \-\-filter &lt;program&gt; (-z)
-
-    Runs the specified external filter program whenever a mail message is stored.
-    The filter is passed the name of the message file in the spool directory so
-    that it can edit it as required. The mail message is rejected if the filter
-    program terminates with an exit code between 1 and 99. Use
-    `net:<transport-address>` to communicate with a filter daemon over the
-    network, or `spam:<transport-address>` for a spamassassin spamd daemon to
-    accept or reject mail messages, or `spam-edit:<transport-address>` to have
-    spamassassin edit the message content without rejecting it, or
-    `exit:<number>` to emulate a filter program that just exits.
-
-*   \-\-filter-timeout &lt;time&gt; (-W)
-
-    Specifies a timeout (in seconds) for running a `--filter` program. The
-    default is 300 seconds.
-
-*   \-\-forward (-f)
-
-    Causes spooled mail messages to be forwarded when the program first starts.
-
-*   \-\-forward-on-disconnect (-1)
-
-    Causes spooled mail messages to be forwarded whenever a SMTP client
-    connection disconnects.
-
-*   \-\-forward-to &lt;host:port&gt; (-o)
-
-    Specifies the transport address of the remote SMTP server that is use for
-    mail message forwarding.
-
-*   \-\-forward-to-some
-
-    Allow forwarding to continue even if some recipient addresses on an e-mail
-    envelope are rejected by the remote server.
-
-*   \-\-help (-h)
-
-    Displays help text and then exits. Use with `--verbose` for more complete
-    output.
-
-*   \-\-hidden (-H)
-
-    Windows only. Hides the application window and disables all message boxes,
-    overriding any `--show` option. This is useful when running as a windows
-    service.
-
-*   \-\-idle-timeout &lt;time&gt;
-
-    Specifies a timeout (in seconds) for receiving network traffic from remote
-    SMTP and POP clients. The default is 1800 seconds.
-
-*   \-\-immediate (-m)
-
-    Causes mail messages to be forwarded as they are received, even before they
-    have been accepted. This can be used to do proxying without
-    store-and-forward, but in practice clients tend to to time out while
-    waiting for their mail message to be accepted.
-
-*   \-\-interface &lt;ip-address-list&gt; (-I)
-
-    Specifies the IP network addresses or interface names used to bind listening
-    ports. By default listening ports for incoming SMTP, POP and administration
-    connections will bind the 'any' address for IPv4 and for IPv6, ie.
-    `0.0.0.0` and `::`. Multiple addresses can be specified by using the option
-    more than once or by using a comma-separated list. Use a prefix of `smtp=`,
-    `pop=` or `admin=` on addresses that should apply only to those types of
-    listening port. Any link-local IPv6 addresses must include a zone name or
-    scope id.  Interface names can be used instead of addresses, in which case
-    all the addresses associated with that interface at startup will used for
-    listening. When an interface name is decorated with a `-ipv4` or `-ipv6`
-    suffix only their IPv4 or IPv6 addresses will be used (eg. `ppp0-ipv4`).
-
-*   \-\-localedir &lt;dir&gt;
-
-    Enables localisation and specifies the locale base directory where message
-    catalogues can be found. An empty directory can be used for the built-in
-    default.
-
-*   \-\-log (-l)
-
-    Enables logging to the standard error stream and to the syslog. The
-    `--close-stderr` and `--no-syslog` options can be used to disable output to
-    standard error stream and the syslog separately. Note that `--as-server`,
-    `--as-client` and `--as-proxy` imply `--log`, and `--as-server` and
-    `--as-proxy` also imply `--close-stderr`.
-
-*   \-\-log-address
-
-    Adds the network address of remote clients to the logging output.
-
-*   \-\-log-file &lt;file&gt; (-N)
-
-    Redirects standard-error logging to the specified file. Logging to the log
-    file is not affected by `--close-stderr`. The filename can include `%d` to
-    get daily log files; the `%d` is replaced by the current date in the local
-    timezone using a `YYYYMMDD` format.
-
-*   \-\-log-time (-L)
-
-    Adds a timestamp to the logging output using the local timezone.
-
-*   \-\-no-daemon (-t)
-
-    Disables the normal backgrounding at startup so that the program runs in the
-    foreground, without forking or detaching from the terminal.  On Windows
-    this disables the system tray icon so the program uses a normal window;
-    when the window is closed the program terminates.
-
-*   \-\-no-smtp (-X)
-
-    Disables listening for incoming SMTP connections.
-
-*   \-\-no-syslog (-n)
-
-    Disables logging to the syslog. Note that `--as-client` implies
-    `--no-syslog`.
-
-*   \-\-pid-file &lt;pid-file&gt; (-i)
-
-    Causes the process-id to be written into the specified file when the program
-    starts up, typically after it has become a background daemon.
-
-*   \-\-poll &lt;period&gt; (-O)
-
-    Causes forwarding of spooled mail messages to happen at regular intervals
-    (with the time given in seconds).
-
-*   \-\-pop (-B)
-
-    Enables the POP server listening, by default on port 110, providing access to
-    spooled mail messages. Negotiated TLS using the POP `STLS` command will be
-    enabled if the `--server-tls` option is also given.
-
-*   \-\-pop-auth &lt;file&gt; (-F)
-
-    Specifies a file containing valid POP account details. The file format is the
-    same as for the SMTP server secrets file, ie. lines starting with `server`,
-    with user-id and password in the third and fourth fields. A special value
-    of `/pam` can be used for authentication using linux [PAM][].
-
-*   \-\-pop-by-name (-J)
-
-    Modifies the spool directory used by the POP server to be a sub-directory
-    with the same name as the POP authentication user-id. This allows multiple
-    POP clients to read the spooled messages without interfering with each
-    other, particularly when also using `--pop-no-delete`. Content files can
-    stay in the main spool directory with only the envelope files copied into
-    user-specific sub-directories. The `emailrelay-filter-copy` program is a
-    convenient way of doing this when run via `--filter`.
-
-*   \-\-pop-no-delete (-G)
-
-    Disables the POP DELE command so that the command appears to succeed but mail
-    messages are not deleted from the spool directory.
-
-*   \-\-pop-port &lt;port&gt; (-E)
-
-    Sets the POP server's listening port number.
-
-*   \-\-port &lt;port&gt; (-p)
-
-    Sets the port number used for listening for incoming SMTP connections.
-
-*   \-\-prompt-timeout &lt;time&gt; (-w)
-
-    Specifies a timeout (in seconds) for getting the initial prompt from a remote
-    SMTP server. If no prompt is received after this time then the SMTP dialog
-    goes ahead without it.
-
-*   \-\-remote-clients (-r)
-
-    Allows incoming connections from addresses that are not local. The default
-    behaviour is to reject connections that are not local in order to prevent
-    accidental exposure to the public internet, although a firewall should also
-    be used. Local address ranges are defined in [RFC-1918][], RFC-6890 etc.
-
-*   \-\-response-timeout &lt;time&gt; (-T)
-
-    Specifies a timeout (in seconds) for getting responses from remote SMTP
-    servers. The default is 1800 seconds.
-
-*   \-\-server-auth &lt;file&gt; (-S)
-
-    Enables SMTP server authentication of remote SMTP clients. Account names and
-    passwords are taken from the specified secrets file. The secrets file
-    should contain lines that have four space-separated fields, starting with
-    `server` in the first field; the second field is the password encoding
-    (`plain` or `md5`), the third is the client user-id and the fourth is the
-    password. The user-id is [RFC-1891][] xtext encoded, and the password is either
-    xtext encoded or generated by `emailrelay-passwd`. A special value of
-    `/pam` can be used for authentication using linux PAM.
-
-*   \-\-server-auth-config &lt;config&gt;
-
-    Configures the SMTP server authentication module using a semicolon-separated
-    list of configuration items. Each item is a single-character key, followed
-    by a colon and then a comma-separated list. A 'm' character introduces a
-    preferred sub-set of the built-in authentication mechanisms, and an 'x' is
-    used for blocklisted mechanisms.
-
 *   \-\-server-tls (-K)
 
     Enables TLS for incoming SMTP and POP connections. SMTP clients can then
@@ -403,21 +369,6 @@ where &lt;option&gt; is:
     certificate. Specify `<default>` for the TLS library's default set of
     trusted CAs.
 
-*   \-\-size &lt;bytes&gt; (-M)
-
-    Limits the size of mail messages that can be submitted over SMTP.
-
-*   \-\-spool-dir &lt;dir&gt; (-s)
-
-    Specifies the directory used for holding mail messages that have been
-    received but not yet forwarded.
-
-*   \-\-syslog[=&lt;facility&gt;] (-k)
-
-    When used with `--log` this option enables logging to the syslog even if the
-    `--no-syslog` option is also used. This is typically used as a convenient
-    override when using `--as-client`.
-
 *   \-\-tls-config &lt;options&gt; (-9)
 
     Selects and configures the low-level TLS library, using a comma-separated
@@ -426,6 +377,44 @@ where &lt;option&gt; is:
     `tlsv1.0` can be used to set a minimum TLS protocol version, or `-tlsv1.2`
     to set a maximum version.
 
+
+### Process options ###
+
+*   \-\-dont-serve (-x)
+
+    Disables all network serving, including SMTP, POP and administration
+    interfaces. The program will terminate as soon as any initial forwarding is
+    complete.
+
+*   \-\-hidden (-H)
+
+    Windows only. Hides the application window and disables all message boxes,
+    overriding any `--show` option. This is useful when running as a windows
+    service.
+
+*   \-\-localedir &lt;dir&gt;
+
+    Enables localisation and specifies the locale base directory where message
+    catalogues can be found. An empty directory can be used for the built-in
+    default.
+
+*   \-\-no-daemon (-t)
+
+    Disables the normal backgrounding at startup so that the program runs in the
+    foreground, without forking or detaching from the terminal.  On Windows
+    this disables the system tray icon so the program uses a normal window;
+    when the window is closed the program terminates.
+
+*   \-\-no-smtp (-X)
+
+    Disables listening for incoming SMTP connections.
+
+*   \-\-pid-file &lt;path&gt; (-i)
+
+    Causes the process-id to be written into the specified file when the program
+    starts up, typically after it has become a background daemon. The immediate
+    parent directory is created if necessary.
+
 *   \-\-user &lt;username&gt; (-u)
 
     When started as root the program switches to a non-privileged effective
@@ -433,14 +422,59 @@ where &lt;option&gt; is:
     also the group ownership of new files and sockets. Specify `root` to
     disable all user-id switching. Ignored on Windows.
 
+
+### Logging options ###
+
 *   \-\-verbose (-v)
 
     Enables more verbose logging when used with `--log`, and more verbose help
     when used with `--help`.
 
-*   \-\-version (-V)
+*   \-\-log (-l)
 
-    Displays version information and then exits.
+    Enables logging to the standard error stream and to the syslog. The
+    `--close-stderr` and `--no-syslog` options can be used to disable output to
+    standard error stream and the syslog separately. Note that `--as-server`,
+    `--as-client` and `--as-proxy` imply `--log`, and `--as-server` and
+    `--as-proxy` also imply `--close-stderr`.
+
+*   \-\-debug (-g)
+
+    Enables debug level logging, if built in. Debug messages are usually only
+    useful when cross-referenced with the source code and they may expose
+    plaintext passwords and mail message content.
+
+*   \-\-log-address
+
+    Adds the network address of remote clients to the logging output.
+
+*   \-\-log-file &lt;file&gt; (-N)
+
+    Redirects standard-error logging to the specified file. Logging to the log
+    file is not affected by `--close-stderr`. The filename can include `%d` to
+    get daily log files; the `%d` is replaced by the current date in the local
+    timezone using a `YYYYMMDD` format.
+
+*   \-\-log-time (-L)
+
+    Adds a timestamp to the logging output using the local timezone.
+
+*   \-\-no-syslog (-n)
+
+    Disables logging to the syslog. Note that `--as-client` implies
+    `--no-syslog`.
+
+*   \-\-syslog[=&lt;facility&gt;] (-k)
+
+    When used with `--log` this option enables logging to the syslog even if the
+    `--no-syslog` option is also used. This is typically used as a convenient
+    override when using `--as-client`.
+
+*   \-\-close-stderr (-e)
+
+    Causes the standard error stream to be closed soon after start-up. This is
+    useful when operating as a background daemon and it is therefore implied by
+    `--as-server` and `--as-proxy`.
 
 A configuration file can be used to provide additional options; put each
 option on a separate line, use the long option names but without the double
@@ -777,7 +811,7 @@ key.
 This OpenSSL command can be used to create a self-signed certificate file
 suitable for testing:
 
-        $ openssl req -x509 -nodes -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
+        $ openssl req -x509 -noenc -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
 
 TLS performs encryption to prevent eavesdropping, but it does not necessarily
 do authentication to prevent man-in-the-middle attacks. For full TLS
@@ -814,17 +848,13 @@ normally involves creating a file `/etc/pam.d/emailrelay` containing something
 like the following:
 
         auth requisite pam_unix.so nullok_secure
-        session required pam_permit.so
-        account required pam_permit.so
-        password required pam_deny.so
 
 With this configuration the E-MailRelay server will use normal unix system
 account names and passwords to authenticate remote clients. On some systems
 this will require special permissioning to allow the E-MailRelay server to
-read the shadow password database.
+read the shadow password database, so run the server as `root` and also add the
-
+`--user=root` command-line option to make sure that the process's effective
-When using PAM authentication E-MailRelay requires that remote clients
+user-id stays as `root` while it accesses the PAM system.
-establish an encrypted session using TLS before authentication can proceed.
 
 IP addresses
 ------------
@@ -1135,7 +1165,7 @@ Security issues
 ---------------
 The following are some security issues that have been taken into consideration:
 
-*   Effective userid
+### Effective userid ###
 
     Suid privileges are revoked at start-up, switching the effective
     userid/groupid to be the real userid/groupid values. If started as `root`
@@ -1147,32 +1177,38 @@ The following are some security issues that have been taken into consideration:
     groupid, so that new files have group ownership corresponding to the
     `daemon` user.
 
-*   Execution environment
+
+### Execution environment ###
 
     The external filter programs are run with an almost empty set of environment
     variables (`PATH` and `IFS`), and with no open file descriptors other than
     `stdin` and `stderr` open onto `/dev/null`, and `stdout` open onto a pipe.
 
-*   Umask
 
-    The program runs for most of the time with a `umask` of 177, switching to 117
+### Umask ###
+
+    The program runs for most of the time with a `umask` of 077, switching to 007
     when creating spool files.
 
-*   Remote clients
+
+### Remote clients ###
 
     By default connections will be rejected if they come from remote machines.
 
-*   Remote configuration
+
+### Remote configuration ###
 
     No configuration parameters can be changed through the administrative
     interface.
 
-*   Use of exec() and system()
+
+### Use of exec() and system() ###
 
     No exec(), system() or popen() calls are used other than execve() to spawn the
     mail filter and/or address verifier.
 
-*   File permissions
+
+### File permissions ###
 
     After a normal installation the spool directory is has ownership of
     `root.daemon` with permissions of `-rwxrwxr-x` and messages files are created
@@ -1184,7 +1220,8 @@ The following are some security issues that have been taken into consideration:
     spool directory, and the files created end up owned by the submitter but with
     group ownership of `daemon`.
 
-*   Logging
+
+### Logging ###
 
     Logging output is conditioned so that ANSI escape sequences cannot appear
     in the log.
@@ -1192,12 +1229,14 @@ The following are some security issues that have been taken into consideration:
     Passwords and message content are not logged (except if using the `--debug`
     option at run time with debug logging enabled at build time).
 
-*   Information leakage
+
+### Information leakage ###
 
     The `--anonymous` option can be used to reduce the amount of information
     leaked to remote clients.
 
-*   Mandatory encryption
+
+### Mandatory encryption ###
 
     When using PAM for authentication all clients are required to use
     TLS/SSL encryption.
@@ -1253,6 +1292,30 @@ and `Cc` message recipients.
 An E-MailRelay `--filter` script can be used to reject messages with incorrect
 `Bcc:` headers, and an example script is included.
 
+Routing
+-------
+E-MailRelay does not normally do any routing of e-mail messages; they are
+all forwarded to a fixed `smarthost` address given by the `--forward-to` or
+`--as-client` command-line options.
+
+However, each message envelope file contains a `ForwardToAddress` field that
+can be populated by filter scripts in order to route the message to some other
+server.
+
+If the `ForwardTo` field has any non-empty value then E-MailRelay runs its
+client filter early to allow the client filter script to set or update the
+`ForwardToAddress` before the outgoing connection is made. (The client filter is
+run a second time as normal once the connection is made and the SMTP session has
+been established.)
+
+Typically a `--filter` script would be used to examine the message content and
+populate the `ForwardTo` field, then a `--client-filter` script would use
+the `ForwardTo` value to populate the `ForwardToAddress` field with an up-to-date
+forwarding address.
+
+Note that a successful connection to the smarthost is required even if a message
+is routed elsewhere.
+
 Files and directories
 ---------------------
 On Unix-like systems E-MailRelay installs by default under `/usr/local`, but
@@ -1314,4 +1377,4 @@ and these default to `%ProgramFiles%/E-MailRelay` for programs and
 [TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker

doc/reference.rst

@@ -10,30 +10,6 @@ The *emailrelay* program supports the following command-line usage:
 
     emailrelay [<option> [<option> ...]] [<config-file>]
 
-where \<option\> is:
-
-*   --address-verifier \<program\>
-
-    Runs the specified external program to verify a message recipent's e-mail
-    address. A network verifier can be specified as *net:<transport-address>*.
-
-*   --admin \<admin-port\> (-a)
-
-    Enables an administration interface on the specified listening port number.
-    Use telnet or something similar to connect. The administration interface
-    can be used to trigger forwarding of spooled mail messages if the
-    *--forward-to* option is used.
-
-*   --admin-terminate (-Q)
-
-    Enables the *terminate* command in the administration interface.
-
-*   --anonymous (-A)
-
-    Disables the server's SMTP_ VRFY command, sends less verbose SMTP responses
-    and SMTP greeting, and stops *Received* lines being added to mail message
-    content files.
-
 *   --as-client \<host:port\> (-q)
 
     This is equivalent to *--log*, *--no-syslog*, *--no-daemon*, *--dont-serve*,
@@ -54,6 +30,205 @@ where \<option\> is:
     them. Use *--log* instead of *--as-server* to keep standard error stream
     open.
 
+*   --spool-dir \<dir\> (-s)
+
+    Specifies the directory used for holding mail messages that have been
+    received but not yet forwarded.
+
+*   --help (-h)
+
+    Displays help text and then exits. Use with *--verbose* for more complete
+    output.
+
+*   --version (-V)
+
+    Displays version information and then exits.
+
+
+*   --forward (-f)
+
+    Causes spooled mail messages to be forwarded when the program first starts.
+
+*   --forward-on-disconnect (-1)
+
+    Causes spooled mail messages to be forwarded whenever a SMTP_ client
+    connection disconnects.
+
+*   --forward-to \<host:port\> (-o)
+
+    Specifies the transport address of the remote SMTP server that spooled mail
+    messages are forwarded to.
+
+*   --poll \<period\> (-O)
+
+    Causes forwarding of spooled mail messages to happen at regular intervals
+    (with the time given in seconds).
+
+*   --client-filter \<program\> (-Y)
+
+    Runs the specified external filter program whenever a mail message is
+    forwarded. The filter is passed the name of the message file in the spool
+    directory so that it can edit it as required. A network filter can be
+    specified as *net:<tcp-address>* and prefixes of *spam:*, *spam-edit:* and
+    *exit:* are also allowed. The *spam:* and *spam-edit:* prefixes require a
+    SpamAssassin daemon to be running. For store-and-forward applications the
+    *--filter* option is normally more useful than *--client-filter*.
+
+*   --client-interface \<ip-address\> (-6)
+
+    Specifies the IP network address to be used to bind the local end of outgoing
+    SMTP connections. By default the address will depend on the routing tables
+    in the normal way. Use *0.0.0.0* to use only IPv4 addresses returned from
+    DNS lookups of the *--forward-to* address, or *::* for IPv6.
+
+*   --connection-timeout \<time\> (-U)
+
+    Specifies a timeout (in seconds) for establishing a TCP connection to remote
+    SMTP servers. The default is 40 seconds.
+
+*   --idle-timeout \<time\>
+
+    Specifies a timeout (in seconds) for receiving network traffic from remote
+    SMTP and POP_ clients. The default is 60 seconds.
+
+*   --response-timeout \<time\> (-T)
+
+    Specifies a timeout (in seconds) for getting responses from remote SMTP
+    servers. The default is 60 seconds.
+
+*   --forward-to-some
+
+    Allow forwarding to continue even if some recipient addresses on an e-mail
+    envelope are rejected by the remote server.
+
+*   --immediate (-m)
+
+    Causes mail messages to be forwarded as they are received, even before they
+    have been accepted. This can be used to do proxying without
+    store-and-forward, but in practice clients tend to to time out while
+    waiting for their mail message to be accepted.
+
+
+*   --port \<port\> (-p)
+
+    Sets the port number used for listening for incoming SMTP connections.
+
+*   --remote-clients (-r)
+
+    Allows incoming connections from addresses that are not local. The default
+    behaviour is to reject connections that are not local in order to prevent
+    accidental exposure to the public internet, although a firewall should also
+    be used. Local address ranges are defined in RFC-1918_, RFC-6890 etc.
+
+*   --address-verifier \<program\>
+
+    Runs the specified external program to verify a message recipent's e-mail
+    address. A network verifier can be specified as *net:<tcp-address>*.
+
+*   --anonymous[=\<scope\>] (-A)
+
+    Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and
+    responses, stops *Received* lines being added to mail message content
+    files, and stops the SMTP client protocol adding *AUTH=* to the *MAIL*
+    command. For finer control use a comma-separated list of things to
+    anonymise: *vrfy*, *server*, *content* and/or *client*, eg.
+    \ *--anonymous*\ =server,content.
+
+*   --dnsbl \<config\>
+
+    Specifies a list of DNSBL_ servers that are used to reject SMTP connections
+    from blocked addresses. The configuration string is made up of
+    comma-separated fields: the DNS server's transport address, a timeout in
+    milliseconds, a rejection threshold, and then the list of DNSBL servers.
+
+*   --domain \<fqdn\> (-D)
+
+    Specifies the network name that is used in SMTP EHLO commands, *Received*
+    lines, and for generating authentication challenges. The default is derived
+    from a DNS lookup of the local hostname.
+
+*   --filter \<program\> (-z)
+
+    Runs the specified external filter program whenever a mail message is stored.
+    The filter is passed the name of the message file in the spool directory so
+    that it can edit it as required. The mail message is rejected if the filter
+    program terminates with an exit code between 1 and 99. Use
+    *net:<tcp-address>* to communicate with a filter daemon over the network,
+    or *spam:<tcp-address>* for a spamassassin spamd daemon to accept or reject
+    mail messages, or *spam-edit:<tcp-address>* to have spamassassin edit the
+    message content without rejecting it, or *exit:<number>* to emulate a
+    filter program that just exits.
+
+*   --filter-timeout \<time\> (-W)
+
+    Specifies a timeout (in seconds) for running a *--filter* program. The
+    default is 60 seconds.
+
+*   --interface \<ip-address-list\> (-I)
+
+    Specifies the IP network addresses or interface names used to bind listening
+    ports. By default listening ports for incoming SMTP, POP and administration
+    connections will bind the 'any' address for IPv4 and for IPv6, ie.
+    *0.0.0.0* and *::*. Multiple addresses can be specified by using the option
+    more than once or by using a comma-separated list. Use a prefix of *smtp=*,
+    *pop=* or *admin=* on addresses that should apply only to those types of
+    listening port. Any link-local IPv6 addresses must include a zone name or
+    scope id.  Interface names can be used instead of addresses, in which case
+    all the addresses associated with that interface at startup will used for
+    listening. When an interface name is decorated with a *-ipv4* or *-ipv6*
+    suffix only their IPv4 or IPv6 addresses will be used (eg. *ppp0-ipv4*).
+    To inherit listening file descriptors from the parent process on unix use a
+    syntax like this: *--interface*=smtp=fd#3,smtp=fd#4,pop=fd#5.
+
+*   --prompt-timeout \<time\> (-w)
+
+    Specifies a timeout (in seconds) for getting the initial prompt from a remote
+    SMTP server. If no prompt is received after this time then the SMTP dialog
+    goes ahead without it.
+
+*   --size \<bytes\> (-M)
+
+    Limits the size of mail messages that can be submitted over SMTP.
+
+
+*   --pop (-B)
+
+    Enables the POP server, listening by default on port 110, providing access to
+    spooled mail messages. Negotiated TLS_ using the POP *STLS* command will be
+    enabled if the *--server-tls* option is also given.
+
+*   --pop-by-name (-J)
+
+    Modifies the spool directory used by the POP server to be a sub-directory
+    with the same name as the POP authentication user-id. This allows multiple
+    POP clients to read the spooled mail messages without interfering with each
+    other, particularly when also using *--pop-no-delete*. Content files can
+    stay in the main spool directory with only the envelope files copied into
+    user-specific sub-directories. The *emailrelay-filter-copy* program is a
+    convenient way of doing this when run via *--filter*.
+
+*   --pop-no-delete (-G)
+
+    Disables the POP DELE command so that the command appears to succeed but mail
+    messages are not deleted from the spool directory.
+
+*   --pop-port \<port\> (-E)
+
+    Sets the POP server's listening port number.
+
+
+*   --admin \<port\> (-a)
+
+    Enables an administration interface on the specified listening port number.
+    Use telnet or something similar to connect. The administration interface
+    can be used to trigger forwarding of spooled mail messages if the
+    *--forward-to* option is used.
+
+*   --admin-terminate (-Q)
+
+    Enables the *terminate* command in the administration interface.
+
+
 *   --client-auth \<file\> (-C)
 
     Enables SMTP client authentication with the remote server, using the client
@@ -71,30 +246,44 @@ where \<option\> is:
     Configures the SMTP client authentication module using a semicolon-separated
     list of configuration items. Each item is a single-character key, followed
     by a colon and then a comma-separated list. A 'm' character introduces an
-    ordered list of authentication mechanisms, and an 'x' is used for
+    ordered list of preferred authentication mechanisms and an 'x' introduces a
-    blocklisted mechanisms.
+    list of mechanisms to avoid. An 'a' list and a 'd' list can be used
+    similarly to prefer and avoid certain mechanisms once the session is
+    encrypted with TLS.
 
-*   --client-filter \<program\> (-Y)
+*   --server-auth \<file\> (-S)
 
-    Runs the specified external filter program whenever a mail message is
+    Enables SMTP server authentication of remote SMTP clients. Account names and
-    forwarded. The filter is passed the name of the message file in the spool
+    passwords are taken from the specified secrets file. The secrets file
-    directory so that it can edit it as required. A network filter can be
+    should contain lines that have four space-separated fields, starting with
-    specified as *net:<transport-address>* and prefixes of *spam:*,
+    *server* in the first field; the second field is the password encoding
-    *spam-edit:* and *exit:* are also allowed. The *spam:* and *spam-edit:*
+    (*plain* or *md5*), the third is the client user-id and the fourth is the
-    prefixes require a SpamAssassin daemon to be running. For store-and-forward
+    password. The user-id is RFC-1891_ xtext encoded, and the password is either
-    applications the *--filter* option is normally more useful than
+    xtext encoded or generated by *emailrelay-passwd*. A special value of
-    \ *--client-filter*\ .
+    */pam* can be used for authentication using linux PAM_.
 
-*   --client-interface \<ip-address\> (-6)
+*   --server-auth-config \<config\>
+
+    Configures the SMTP server authentication module using a semicolon-separated
+    list of configuration items. Each item is a single-character key, followed
+    by a colon and then a comma-separated list. A 'm' character introduces an
+    ordered list of allowed authentication mechanisms and an 'x' introduces a
+    list of mechanisms to deny. An 'a' list and a 'd' list can be used
+    similarly to allow and deny mechanisms once the session is encrypted with
+    TLS. In typical usage you might have an empty allow list for an unencrypted
+    session and a single preferred mechanism once encrypted, *m:;a:plain*.
+
+*   --pop-auth \<file\> (-F)
+
+    Specifies a file containing valid POP account details. The file format is the
+    same as for the SMTP server secrets file, ie. lines starting with *server*,
+    with user-id and password in the third and fourth fields. A special value
+    of */pam* can be used for authentication using linux PAM.
 
-    Specifies the IP network address to be used to bind the local end of outgoing
-    SMTP connections. By default the address will depend on the routing tables
-    in the normal way. Use *0.0.0.0* to use only IPv4 addresses returned from
-    DNS lookups of the *--forward-to* address, or *::* for IPv6.
 
 *   --client-tls (-j)
 
-    Enables negotiated TLS_ for outgoing SMTP connections; the SMTP STARTTLS
+    Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS
     command will be issued if the remote server supports it.
 
 *   --client-tls-certificate \<pem-file\>
@@ -127,7 +316,7 @@ where \<option\> is:
     Enables verification of the remote SMTP server's certificate against any of
     the trusted CA certificates in the specified file or directory. In many use
     cases this should be a file containing just your self-signed root
-    certificate. Specify *\<default\>* for the TLS library's default set of
+    certificate. Specify *<default>* for the TLS library's default set of
     trusted CAs.
 
 *   --client-tls-verify-name \<cname\>
@@ -135,243 +324,6 @@ where \<option\> is:
     Enables verification of the CNAME within the remote SMTP server's
     certificate.
 
-*   --close-stderr (-e)
-
-    Causes the standard error stream to be closed soon after start-up. This is
-    useful when operating as a background daemon and it is therefore implied by
-    *--as-server* and *--as-proxy*.
-
-*   --connection-timeout \<time\> (-U)
-
-    Specifies a timeout (in seconds) for establishing a TCP connection to remote
-    SMTP servers. The default is 40 seconds.
-
-*   --debug (-g)
-
-    Enables debug level logging, if built in. Debug messages are usually only
-    useful when cross-referenced with the source code and they may expose
-    plaintext passwords and mail message content.
-
-*   --dnsbl \<config\>
-
-    Specifies a list of DNSBL_ servers that are used to reject SMTP connections
-    from blocked addresses. The configuration string is made up of
-    comma-separated fields: the DNS server's transport address, a timeout in
-    milliseconds, a rejection threshold, and then the list of DNSBL servers.
-
-*   --domain \<fqdn\> (-D)
-
-    Specifies the network name that is used in SMTP EHLO commands, *Received*
-    lines, and for generating authentication challenges. The default is derived
-    from a DNS lookup of the local hostname.
-
-*   --dont-serve (-x)
-
-    Disables all network serving, including SMTP, POP_ and administration
-    interfaces. The program will terminate as soon as any initial forwarding is
-    complete.
-
-*   --filter \<program\> (-z)
-
-    Runs the specified external filter program whenever a mail message is stored.
-    The filter is passed the name of the message file in the spool directory so
-    that it can edit it as required. The mail message is rejected if the filter
-    program terminates with an exit code between 1 and 99. Use
-    *net:<transport-address>* to communicate with a filter daemon over the
-    network, or *spam:<transport-address>* for a spamassassin spamd daemon to
-    accept or reject mail messages, or *spam-edit:<transport-address>* to have
-    spamassassin edit the message content without rejecting it, or
-    *exit:<number>* to emulate a filter program that just exits.
-
-*   --filter-timeout \<time\> (-W)
-
-    Specifies a timeout (in seconds) for running a *--filter* program. The
-    default is 300 seconds.
-
-*   --forward (-f)
-
-    Causes spooled mail messages to be forwarded when the program first starts.
-
-*   --forward-on-disconnect (-1)
-
-    Causes spooled mail messages to be forwarded whenever a SMTP client
-    connection disconnects.
-
-*   --forward-to \<host:port\> (-o)
-
-    Specifies the transport address of the remote SMTP server that is use for
-    mail message forwarding.
-
-*   --forward-to-some
-
-    Allow forwarding to continue even if some recipient addresses on an e-mail
-    envelope are rejected by the remote server.
-
-*   --help (-h)
-
-    Displays help text and then exits. Use with *--verbose* for more complete
-    output.
-
-*   --hidden (-H)
-
-    Windows only. Hides the application window and disables all message boxes,
-    overriding any *--show* option. This is useful when running as a windows
-    service.
-
-*   --idle-timeout \<time\>
-
-    Specifies a timeout (in seconds) for receiving network traffic from remote
-    SMTP and POP clients. The default is 1800 seconds.
-
-*   --immediate (-m)
-
-    Causes mail messages to be forwarded as they are received, even before they
-    have been accepted. This can be used to do proxying without
-    store-and-forward, but in practice clients tend to to time out while
-    waiting for their mail message to be accepted.
-
-*   --interface \<ip-address-list\> (-I)
-
-    Specifies the IP network addresses or interface names used to bind listening
-    ports. By default listening ports for incoming SMTP, POP and administration
-    connections will bind the 'any' address for IPv4 and for IPv6, ie.
-    *0.0.0.0* and *::*. Multiple addresses can be specified by using the option
-    more than once or by using a comma-separated list. Use a prefix of *smtp=*,
-    *pop=* or *admin=* on addresses that should apply only to those types of
-    listening port. Any link-local IPv6 addresses must include a zone name or
-    scope id.  Interface names can be used instead of addresses, in which case
-    all the addresses associated with that interface at startup will used for
-    listening. When an interface name is decorated with a *-ipv4* or *-ipv6*
-    suffix only their IPv4 or IPv6 addresses will be used (eg. *ppp0-ipv4*).
-
-*   --localedir \<dir\>
-
-    Enables localisation and specifies the locale base directory where message
-    catalogues can be found. An empty directory can be used for the built-in
-    default.
-
-*   --log (-l)
-
-    Enables logging to the standard error stream and to the syslog. The
-    *--close-stderr* and *--no-syslog* options can be used to disable output to
-    standard error stream and the syslog separately. Note that *--as-server*,
-    *--as-client* and *--as-proxy* imply *--log*, and *--as-server* and
-    *--as-proxy* also imply *--close-stderr*.
-
-*   --log-address
-
-    Adds the network address of remote clients to the logging output.
-
-*   --log-file \<file\> (-N)
-
-    Redirects standard-error logging to the specified file. Logging to the log
-    file is not affected by *--close-stderr*. The filename can include *%d* to
-    get daily log files; the *%d* is replaced by the current date in the local
-    timezone using a *YYYYMMDD* format.
-
-*   --log-time (-L)
-
-    Adds a timestamp to the logging output using the local timezone.
-
-*   --no-daemon (-t)
-
-    Disables the normal backgrounding at startup so that the program runs in the
-    foreground, without forking or detaching from the terminal.  On Windows
-    this disables the system tray icon so the program uses a normal window;
-    when the window is closed the program terminates.
-
-*   --no-smtp (-X)
-
-    Disables listening for incoming SMTP connections.
-
-*   --no-syslog (-n)
-
-    Disables logging to the syslog. Note that *--as-client* implies
-    \ *--no-syslog*\ .
-
-*   --pid-file \<pid-file\> (-i)
-
-    Causes the process-id to be written into the specified file when the program
-    starts up, typically after it has become a background daemon.
-
-*   --poll \<period\> (-O)
-
-    Causes forwarding of spooled mail messages to happen at regular intervals
-    (with the time given in seconds).
-
-*   --pop (-B)
-
-    Enables the POP server listening, by default on port 110, providing access to
-    spooled mail messages. Negotiated TLS using the POP *STLS* command will be
-    enabled if the *--server-tls* option is also given.
-
-*   --pop-auth \<file\> (-F)
-
-    Specifies a file containing valid POP account details. The file format is the
-    same as for the SMTP server secrets file, ie. lines starting with *server*,
-    with user-id and password in the third and fourth fields. A special value
-    of */pam* can be used for authentication using linux PAM_.
-
-*   --pop-by-name (-J)
-
-    Modifies the spool directory used by the POP server to be a sub-directory
-    with the same name as the POP authentication user-id. This allows multiple
-    POP clients to read the spooled messages without interfering with each
-    other, particularly when also using *--pop-no-delete*. Content files can
-    stay in the main spool directory with only the envelope files copied into
-    user-specific sub-directories. The *emailrelay-filter-copy* program is a
-    convenient way of doing this when run via *--filter*.
-
-*   --pop-no-delete (-G)
-
-    Disables the POP DELE command so that the command appears to succeed but mail
-    messages are not deleted from the spool directory.
-
-*   --pop-port \<port\> (-E)
-
-    Sets the POP server's listening port number.
-
-*   --port \<port\> (-p)
-
-    Sets the port number used for listening for incoming SMTP connections.
-
-*   --prompt-timeout \<time\> (-w)
-
-    Specifies a timeout (in seconds) for getting the initial prompt from a remote
-    SMTP server. If no prompt is received after this time then the SMTP dialog
-    goes ahead without it.
-
-*   --remote-clients (-r)
-
-    Allows incoming connections from addresses that are not local. The default
-    behaviour is to reject connections that are not local in order to prevent
-    accidental exposure to the public internet, although a firewall should also
-    be used. Local address ranges are defined in RFC-1918_, RFC-6890 etc.
-
-*   --response-timeout \<time\> (-T)
-
-    Specifies a timeout (in seconds) for getting responses from remote SMTP
-    servers. The default is 1800 seconds.
-
-*   --server-auth \<file\> (-S)
-
-    Enables SMTP server authentication of remote SMTP clients. Account names and
-    passwords are taken from the specified secrets file. The secrets file
-    should contain lines that have four space-separated fields, starting with
-    *server* in the first field; the second field is the password encoding
-    (*plain* or *md5*), the third is the client user-id and the fourth is the
-    password. The user-id is RFC-1891_ xtext encoded, and the password is either
-    xtext encoded or generated by *emailrelay-passwd*. A special value of
-    */pam* can be used for authentication using linux PAM.
-
-*   --server-auth-config \<config\>
-
-    Configures the SMTP server authentication module using a semicolon-separated
-    list of configuration items. Each item is a single-character key, followed
-    by a colon and then a comma-separated list. A 'm' character introduces a
-    preferred sub-set of the built-in authentication mechanisms, and an 'x' is
-    used for blocklisted mechanisms.
-
 *   --server-tls (-K)
 
     Enables TLS for incoming SMTP and POP connections. SMTP clients can then
@@ -403,24 +355,9 @@ where \<option\> is:
     Enables verification of remote SMTP and POP clients' certificates against any
     of the trusted CA certificates in the specified file or directory. In many
     use cases this should be a file containing just your self-signed root
-    certificate. Specify *\<default\>* for the TLS library's default  set of
+    certificate. Specify *<default>* for the TLS library's default set of
     trusted CAs.
 
-*   --size \<bytes\> (-M)
-
-    Limits the size of mail messages that can be submitted over SMTP.
-
-*   --spool-dir \<dir\> (-s)
-
-    Specifies the directory used for holding mail messages that have been
-    received but not yet forwarded.
-
-*   --syslog[=\<facility\>] (-k)
-
-    When used with *--log* this option enables logging to the syslog even if the
-    *--no-syslog* option is also used. This is typically used as a convenient
-    override when using *--as-client*.
-
 *   --tls-config \<options\> (-9)
 
     Selects and configures the low-level TLS library, using a comma-separated
@@ -429,6 +366,42 @@ where \<option\> is:
     *tlsv1.0* can be used to set a minimum TLS protocol version, or *-tlsv1.2*
     to set a maximum version.
 
+
+*   --dont-serve (-x)
+
+    Disables all network serving, including SMTP, POP and administration
+    interfaces. The program will terminate as soon as any initial forwarding is
+    complete.
+
+*   --hidden (-H)
+
+    Windows only. Hides the application window and disables all message boxes,
+    overriding any *--show* option. This is useful when running as a windows
+    service.
+
+*   --localedir \<dir\>
+
+    Enables localisation and specifies the locale base directory where message
+    catalogues can be found. An empty directory can be used for the built-in
+    default.
+
+*   --no-daemon (-t)
+
+    Disables the normal backgrounding at startup so that the program runs in the
+    foreground, without forking or detaching from the terminal.  On Windows
+    this disables the system tray icon so the program uses a normal window;
+    when the window is closed the program terminates.
+
+*   --no-smtp (-X)
+
+    Disables listening for incoming SMTP connections.
+
+*   --pid-file \<path\> (-i)
+
+    Causes the process-id to be written into the specified file when the program
+    starts up, typically after it has become a background daemon. The immediate
+    parent directory is created if necessary.
+
 *   --user \<username\> (-u)
 
     When started as root the program switches to a non-privileged effective
@@ -436,14 +409,57 @@ where \<option\> is:
     also the group ownership of new files and sockets. Specify *root* to
     disable all user-id switching. Ignored on Windows.
 
+
 *   --verbose (-v)
 
     Enables more verbose logging when used with *--log*, and more verbose help
     when used with *--help*.
 
-*   --version (-V)
+*   --log (-l)
 
-    Displays version information and then exits.
+    Enables logging to the standard error stream and to the syslog. The
+    *--close-stderr* and *--no-syslog* options can be used to disable output to
+    standard error stream and the syslog separately. Note that *--as-server*,
+    *--as-client* and *--as-proxy* imply *--log*, and *--as-server* and
+    *--as-proxy* also imply *--close-stderr*.
+
+*   --debug (-g)
+
+    Enables debug level logging, if built in. Debug messages are usually only
+    useful when cross-referenced with the source code and they may expose
+    plaintext passwords and mail message content.
+
+*   --log-address
+
+    Adds the network address of remote clients to the logging output.
+
+*   --log-file \<file\> (-N)
+
+    Redirects standard-error logging to the specified file. Logging to the log
+    file is not affected by *--close-stderr*. The filename can include *%d* to
+    get daily log files; the *%d* is replaced by the current date in the local
+    timezone using a *YYYYMMDD* format.
+
+*   --log-time (-L)
+
+    Adds a timestamp to the logging output using the local timezone.
+
+*   --no-syslog (-n)
+
+    Disables logging to the syslog. Note that *--as-client* implies
+    \ *--no-syslog*\ .
+
+*   --syslog[=\<facility\>] (-k)
+
+    When used with *--log* this option enables logging to the syslog even if the
+    *--no-syslog* option is also used. This is typically used as a convenient
+    override when using *--as-client*.
+
+*   --close-stderr (-e)
+
+    Causes the standard error stream to be closed soon after start-up. This is
+    useful when operating as a background daemon and it is therefore implied by
+    *--as-server* and *--as-proxy*.
 
 A configuration file can be used to provide additional options; put each
 option on a separate line, use the long option names but without the double
@@ -800,7 +816,7 @@ suitable for testing:
 
 ::
 
-    $ openssl req -x509 -nodes -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
+    $ openssl req -x509 -noenc -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
 
 TLS performs encryption to prevent eavesdropping, but it does not necessarily
 do authentication to prevent man-in-the-middle attacks. For full TLS
@@ -839,17 +855,13 @@ like the following:
 ::
 
     auth requisite pam_unix.so nullok_secure
-    session required pam_permit.so
-    account required pam_permit.so
-    password required pam_deny.so
 
 With this configuration the E-MailRelay server will use normal unix system
 account names and passwords to authenticate remote clients. On some systems
 this will require special permissioning to allow the E-MailRelay server to
-read the shadow password database.
+read the shadow password database, so run the server as *root* and also add the
-
+*--user=root* command-line option to make sure that the process's effective
-When using PAM authentication E-MailRelay requires that remote clients
+user-id stays as *root* while it accesses the PAM system.
-establish an encrypted session using TLS before authentication can proceed.
 
 IP addresses
 ============
@@ -1207,9 +1219,6 @@ checked.
 Security issues
 ===============
 The following are some security issues that have been taken into consideration:
-
-*   Effective userid
-
     Suid privileges are revoked at start-up, switching the effective
     userid/groupid to be the real userid/groupid values. If started as *root*
     then the effective userid/groupid are switched at start-up to those of user
@@ -1220,33 +1229,21 @@ The following are some security issues that have been taken into consideration:
     groupid, so that new files have group ownership corresponding to the
     *daemon* user.
 
-*   Execution environment
-
     The external filter programs are run with an almost empty set of environment
     variables (*PATH* and *IFS*), and with no open file descriptors other than
     *stdin* and *stderr* open onto */dev/null*, and *stdout* open onto a pipe.
 
-*   Umask
+    The program runs for most of the time with a *umask* of 077, switching to 007
-
-    The program runs for most of the time with a *umask* of 177, switching to 117
     when creating spool files.
 
-*   Remote clients
-
     By default connections will be rejected if they come from remote machines.
 
-*   Remote configuration
-
     No configuration parameters can be changed through the administrative
     interface.
 
-*   Use of exec() and system()
-
     No exec(), system() or popen() calls are used other than execve() to spawn the
     mail filter and/or address verifier.
 
-*   File permissions
-
     After a normal installation the spool directory is has ownership of
     *root.daemon* with permissions of *-rwxrwxr-x* and messages files are created
     with permissions of *-rw-rw----*. This allows normal users to list messages
@@ -1257,21 +1254,15 @@ The following are some security issues that have been taken into consideration:
     spool directory, and the files created end up owned by the submitter but with
     group ownership of *daemon*.
 
-*   Logging
-
     Logging output is conditioned so that ANSI escape sequences cannot appear
     in the log.
 
     Passwords and message content are not logged (except if using the *--debug*
     option at run time with debug logging enabled at build time).
 
-*   Information leakage
-
     The *--anonymous* option can be used to reduce the amount of information
     leaked to remote clients.
 
-*   Mandatory encryption
-
     When using PAM for authentication all clients are required to use
     TLS/SSL encryption.
 
@@ -1328,6 +1319,30 @@ and *Cc* message recipients.
 An E-MailRelay *--filter* script can be used to reject messages with incorrect
 *Bcc:* headers, and an example script is included.
 
+Routing
+=======
+E-MailRelay does not normally do any routing of e-mail messages; they are
+all forwarded to a fixed *smarthost* address given by the *--forward-to* or
+*--as-client* command-line options.
+
+However, each message envelope file contains a *ForwardToAddress* field that
+can be populated by filter scripts in order to route the message to some other
+server.
+
+If the *ForwardTo* field has any non-empty value then E-MailRelay runs its
+client filter early to allow the client filter script to set or update the
+*ForwardToAddress* before the outgoing connection is made. (The client filter is
+run a second time as normal once the connection is made and the SMTP session has
+been established.)
+
+Typically a *--filter* script would be used to examine the message content and
+populate the *ForwardTo* field, then a *--client-filter* script would use
+the *ForwardTo* value to populate the *ForwardToAddress* field with an up-to-date
+forwarding address.
+
+Note that a successful connection to the smarthost is required even if a message
+is routed elsewhere.
+
 Files and directories
 =====================
 On Unix-like systems E-MailRelay installs by default under */usr/local*, but
@@ -1391,4 +1406,4 @@ and these default to *%ProgramFiles%/E-MailRelay* for programs and
 .. _SOCKS: https://en.wikipedia.org/wiki/SOCKS
 .. _TLS: https://en.wikipedia.org/wiki/Transport_Layer_Security
 
-.. footer:: Copyright (C) 2001-2021 Graeme Walker
+.. footer:: Copyright (C) 2001-2022 Graeme Walker

doc/reference.txt

@@ -7,193 +7,117 @@ The "emailrelay" program supports the following command-line usage:
 
 	emailrelay [<option> [<option> ...]] [<config-file>]
 
-where <option> is:
+# Basic options
 
-# --address-verifier <program>
+* --as-client <host:port> (-q)
-  Runs the specified external program to verify a message recipent's e-mail
-  address. A network verifier can be specified as "net:<transport-address>".
-
-# --admin <admin-port> (-a)
-  Enables an administration interface on the specified listening port number.
-  Use telnet or something similar to connect. The administration interface
-  can be used to trigger forwarding of spooled mail messages if the
-  "--forward-to" option is used.
-
-# --admin-terminate (-Q)
-  Enables the "terminate" command in the administration interface.
-
-# --anonymous (-A)
-  Disables the server's SMTP VRFY command, sends less verbose SMTP responses
-  and SMTP greeting, and stops "Received" lines being added to mail message
-  content files.
-
-# --as-client <host:port> (-q)
   This is equivalent to "--log", "--no-syslog", "--no-daemon", "--dont-serve",
   "--forward" and "--forward-to". It is a convenient way of running a
   forwarding agent that forwards spooled mail messages and then terminates.
-
+* --as-proxy <host:port> (-y)
-# --as-proxy <host:port> (-y)
   This is equivalent to "--log", "--close-stderr", "--forward-on-disconnect"
   and "--forward-to". It is a convenient way of running a store-and-forward
   daemon. Use "--log", "--forward-on-disconnect" and "--forward-to" instead
   of "--as-proxy" to keep the standard error stream open.
-
+* --as-server (-d)
-# --as-server (-d)
   This is equivalent to "--log" and "--close-stderr". It is a convenient way of
   running a background storage daemon that accepts mail messages and spools
   them. Use "--log" instead of "--as-server" to keep standard error stream
   open.
+* --spool-dir <dir> (-s)
+  Specifies the directory used for holding mail messages that have been
+  received but not yet forwarded.
+* --help (-h)
+  Displays help text and then exits. Use with "--verbose" for more complete
+  output.
+* --version (-V)
+  Displays version information and then exits.
 
-# --client-auth <file> (-C)
+# SMTP client options
-  Enables SMTP client authentication with the remote server, using the client
-  account details taken from the specified secrets file. The secrets file
-  should normally contain one line that starts with "client" and that line
-  should have between four and five space-separated fields; the second field
-  is the password encoding ("plain" or "md5"), the third is the user-id and
-  the fourth is the password. The user-id is RFC-1891 xtext encoded, and the
-  password is either xtext encoded or generated by "emailrelay-passwd". If
-  the remote server does not support SMTP authentication then the SMTP
-  connection will fail.
 
-# --client-auth-config <config>
+* --forward (-f)
-  Configures the SMTP client authentication module using a semicolon-separated
+  Causes spooled mail messages to be forwarded when the program first starts.
-  list of configuration items. Each item is a single-character key, followed
+* --forward-on-disconnect (-1)
-  by a colon and then a comma-separated list. A 'm' character introduces an
+  Causes spooled mail messages to be forwarded whenever a SMTP client
-  ordered list of authentication mechanisms, and an 'x' is used for
+  connection disconnects.
-  blocklisted mechanisms.
+* --forward-to <host:port> (-o)
-
+  Specifies the transport address of the remote SMTP server that spooled mail
-# --client-filter <program> (-Y)
+  messages are forwarded to.
+* --poll <period> (-O)
+  Causes forwarding of spooled mail messages to happen at regular intervals
+  (with the time given in seconds).
+* --client-filter <program> (-Y)
   Runs the specified external filter program whenever a mail message is
   forwarded. The filter is passed the name of the message file in the spool
   directory so that it can edit it as required. A network filter can be
-  specified as "net:<transport-address>" and prefixes of "spam:",
+  specified as "net:<tcp-address>" and prefixes of "spam:", "spam-edit:" and
-  "spam-edit:" and "exit:" are also allowed. The "spam:" and "spam-edit:"
+  "exit:" are also allowed. The "spam:" and "spam-edit:" prefixes require a
-  prefixes require a SpamAssassin daemon to be running. For store-and-forward
+  SpamAssassin daemon to be running. For store-and-forward applications the
-  applications the "--filter" option is normally more useful than
+  "--filter" option is normally more useful than "--client-filter".
-  "--client-filter".
+* --client-interface <ip-address> (-6)
-
-# --client-interface <ip-address> (-6)
   Specifies the IP network address to be used to bind the local end of outgoing
   SMTP connections. By default the address will depend on the routing tables
   in the normal way. Use "0.0.0.0" to use only IPv4 addresses returned from
   DNS lookups of the "--forward-to" address, or "::" for IPv6.
-
+* --connection-timeout <time> (-U)
-# --client-tls (-j)
-  Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS
-  command will be issued if the remote server supports it.
-
-# --client-tls-certificate <pem-file>
-  Defines the TLS certificate file when acting as a SMTP client. This file must
-  contain the client's private key and certificate chain using the PEM file
-  format. Alternatively, use this option twice with the first one specifying
-  the key file and the second the certificate file. Keep the file permissions
-  tight to avoid accidental exposure of the private key.
-
-# --client-tls-connection (-b)
-  Enables the use of a TLS tunnel for outgoing SMTP connections. This is for
-  SMTP over TLS (SMTPS), not TLS negotiated within SMTP using STARTTLS.
-
-# --client-tls-required
-  Makes the use of TLS mandatory for outgoing SMTP connections. The SMTP
-  STARTTLS command will be used before mail messages are sent out. If the
-  remote server does not allow STARTTLS then the SMTP connection will fail.
-
-# --client-tls-server-name <hostname>
-  Defines the target server hostname in the TLS handshake. With
-  "--client-tls-connection" this can be used for SNI, allowing the remote
-  server to adopt an appropriate identity.
-
-# --client-tls-verify <ca-list>
-  Enables verification of the remote SMTP server's certificate against any of
-  the trusted CA certificates in the specified file or directory. In many use
-  cases this should be a file containing just your self-signed root
-  certificate. Specify "<default>" for the TLS library's default set of
-  trusted CAs.
-
-# --client-tls-verify-name <cname>
-  Enables verification of the CNAME within the remote SMTP server's
-  certificate.
-
-# --close-stderr (-e)
-  Causes the standard error stream to be closed soon after start-up. This is
-  useful when operating as a background daemon and it is therefore implied by
-  "--as-server" and "--as-proxy".
-
-# --connection-timeout <time> (-U)
   Specifies a timeout (in seconds) for establishing a TCP connection to remote
   SMTP servers. The default is 40 seconds.
-
+* --idle-timeout <time>
-# --debug (-g)
+  Specifies a timeout (in seconds) for receiving network traffic from remote
-  Enables debug level logging, if built in. Debug messages are usually only
+  SMTP and POP clients. The default is 60 seconds.
-  useful when cross-referenced with the source code and they may expose
+* --response-timeout <time> (-T)
-  plaintext passwords and mail message content.
+  Specifies a timeout (in seconds) for getting responses from remote SMTP
-
+  servers. The default is 60 seconds.
-# --dnsbl <config>
+* --forward-to-some
-  Specifies a list of DNSBL servers that are used to reject SMTP connections
-  from blocked addresses. The configuration string is made up of
-  comma-separated fields: the DNS server's transport address, a timeout in
-  milliseconds, a rejection threshold, and then the list of DNSBL servers.
-
-# --domain <fqdn> (-D)
-  Specifies the network name that is used in SMTP EHLO commands, "Received"
-  lines, and for generating authentication challenges. The default is derived
-  from a DNS lookup of the local hostname.
-
-# --dont-serve (-x)
-  Disables all network serving, including SMTP, POP and administration
-  interfaces. The program will terminate as soon as any initial forwarding is
-  complete.
-
-# --filter <program> (-z)
-  Runs the specified external filter program whenever a mail message is stored.
-  The filter is passed the name of the message file in the spool directory so
-  that it can edit it as required. The mail message is rejected if the filter
-  program terminates with an exit code between 1 and 99. Use
-  "net:<transport-address>" to communicate with a filter daemon over the
-  network, or "spam:<transport-address>" for a spamassassin spamd daemon to
-  accept or reject mail messages, or "spam-edit:<transport-address>" to have
-  spamassassin edit the message content without rejecting it, or
-  "exit:<number>" to emulate a filter program that just exits.
-
-# --filter-timeout <time> (-W)
-  Specifies a timeout (in seconds) for running a "--filter" program. The
-  default is 300 seconds.
-
-# --forward (-f)
-  Causes spooled mail messages to be forwarded when the program first starts.
-
-# --forward-on-disconnect (-1)
-  Causes spooled mail messages to be forwarded whenever a SMTP client
-  connection disconnects.
-
-# --forward-to <host:port> (-o)
-  Specifies the transport address of the remote SMTP server that is use for
-  mail message forwarding.
-
-# --forward-to-some
   Allow forwarding to continue even if some recipient addresses on an e-mail
   envelope are rejected by the remote server.
-
+* --immediate (-m)
-# --help (-h)
-  Displays help text and then exits. Use with "--verbose" for more complete
-  output.
-
-# --hidden (-H)
-  Windows only. Hides the application window and disables all message boxes,
-  overriding any "--show" option. This is useful when running as a windows
-  service.
-
-# --idle-timeout <time>
-  Specifies a timeout (in seconds) for receiving network traffic from remote
-  SMTP and POP clients. The default is 1800 seconds.
-
-# --immediate (-m)
   Causes mail messages to be forwarded as they are received, even before they
   have been accepted. This can be used to do proxying without
   store-and-forward, but in practice clients tend to to time out while
   waiting for their mail message to be accepted.
 
-# --interface <ip-address-list> (-I)
+# SMTP server options
+
+* --port <port> (-p)
+  Sets the port number used for listening for incoming SMTP connections.
+* --remote-clients (-r)
+  Allows incoming connections from addresses that are not local. The default
+  behaviour is to reject connections that are not local in order to prevent
+  accidental exposure to the public internet, although a firewall should also
+  be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
+* --address-verifier <program>
+  Runs the specified external program to verify a message recipent's e-mail
+  address. A network verifier can be specified as "net:<tcp-address>".
+* --anonymous[=<scope>] (-A)
+  Disables the server's SMTP VRFY command, sends less verbose SMTP greeting and
+  responses, stops "Received" lines being added to mail message content
+  files, and stops the SMTP client protocol adding "AUTH=" to the "MAIL"
+  command. For finer control use a comma-separated list of things to
+  anonymise: "vrfy", "server", "content" and/or "client", eg.
+  "--anonymous"=server,content.
+* --dnsbl <config>
+  Specifies a list of DNSBL servers that are used to reject SMTP connections
+  from blocked addresses. The configuration string is made up of
+  comma-separated fields: the DNS server's transport address, a timeout in
+  milliseconds, a rejection threshold, and then the list of DNSBL servers.
+* --domain <fqdn> (-D)
+  Specifies the network name that is used in SMTP EHLO commands, "Received"
+  lines, and for generating authentication challenges. The default is derived
+  from a DNS lookup of the local hostname.
+* --filter <program> (-z)
+  Runs the specified external filter program whenever a mail message is stored.
+  The filter is passed the name of the message file in the spool directory so
+  that it can edit it as required. The mail message is rejected if the filter
+  program terminates with an exit code between 1 and 99. Use
+  "net:<tcp-address>" to communicate with a filter daemon over the network,
+  or "spam:<tcp-address>" for a spamassassin spamd daemon to accept or reject
+  mail messages, or "spam-edit:<tcp-address>" to have spamassassin edit the
+  message content without rejecting it, or "exit:<number>" to emulate a
+  filter program that just exits.
+* --filter-timeout <time> (-W)
+  Specifies a timeout (in seconds) for running a "--filter" program. The
+  default is 60 seconds.
+* --interface <ip-address-list> (-I)
   Specifies the IP network addresses or interface names used to bind listening
   ports. By default listening ports for incoming SMTP, POP and administration
   connections will bind the 'any' address for IPv4 and for IPv6, ie.
@@ -205,98 +129,66 @@ where <option> is:
   all the addresses associated with that interface at startup will used for
   listening. When an interface name is decorated with a "-ipv4" or "-ipv6"
   suffix only their IPv4 or IPv6 addresses will be used (eg. "ppp0-ipv4").
+  To inherit listening file descriptors from the parent process on unix use a
+  syntax like this: "--interface"=smtp=fd#3,smtp=fd#4,pop=fd#5.
+* --prompt-timeout <time> (-w)
+  Specifies a timeout (in seconds) for getting the initial prompt from a remote
+  SMTP server. If no prompt is received after this time then the SMTP dialog
+  goes ahead without it.
+* --size <bytes> (-M)
+  Limits the size of mail messages that can be submitted over SMTP.
 
-# --localedir <dir>
+# POP server options
-  Enables localisation and specifies the locale base directory where message
-  catalogues can be found. An empty directory can be used for the built-in
-  default.
 
-# --log (-l)
+* --pop (-B)
-  Enables logging to the standard error stream and to the syslog. The
+  Enables the POP server, listening by default on port 110, providing access to
-  "--close-stderr" and "--no-syslog" options can be used to disable output to
-  standard error stream and the syslog separately. Note that "--as-server",
-  "--as-client" and "--as-proxy" imply "--log", and "--as-server" and
-  "--as-proxy" also imply "--close-stderr".
-
-# --log-address
-  Adds the network address of remote clients to the logging output.
-
-# --log-file <file> (-N)
-  Redirects standard-error logging to the specified file. Logging to the log
-  file is not affected by "--close-stderr". The filename can include "%d" to
-  get daily log files; the "%d" is replaced by the current date in the local
-  timezone using a "YYYYMMDD" format.
-
-# --log-time (-L)
-  Adds a timestamp to the logging output using the local timezone.
-
-# --no-daemon (-t)
-  Disables the normal backgrounding at startup so that the program runs in the
-  foreground, without forking or detaching from the terminal.  On Windows
-  this disables the system tray icon so the program uses a normal window;
-  when the window is closed the program terminates.
-
-# --no-smtp (-X)
-  Disables listening for incoming SMTP connections.
-
-# --no-syslog (-n)
-  Disables logging to the syslog. Note that "--as-client" implies
-  "--no-syslog".
-
-# --pid-file <pid-file> (-i)
-  Causes the process-id to be written into the specified file when the program
-  starts up, typically after it has become a background daemon.
-
-# --poll <period> (-O)
-  Causes forwarding of spooled mail messages to happen at regular intervals
-  (with the time given in seconds).
-
-# --pop (-B)
-  Enables the POP server listening, by default on port 110, providing access to
   spooled mail messages. Negotiated TLS using the POP "STLS" command will be
   enabled if the "--server-tls" option is also given.
-
+* --pop-by-name (-J)
-# --pop-auth <file> (-F)
-  Specifies a file containing valid POP account details. The file format is the
-  same as for the SMTP server secrets file, ie. lines starting with "server",
-  with user-id and password in the third and fourth fields. A special value
-  of "/pam" can be used for authentication using linux PAM.
-
-# --pop-by-name (-J)
   Modifies the spool directory used by the POP server to be a sub-directory
   with the same name as the POP authentication user-id. This allows multiple
-  POP clients to read the spooled messages without interfering with each
+  POP clients to read the spooled mail messages without interfering with each
   other, particularly when also using "--pop-no-delete". Content files can
   stay in the main spool directory with only the envelope files copied into
   user-specific sub-directories. The "emailrelay-filter-copy" program is a
   convenient way of doing this when run via "--filter".
-
+* --pop-no-delete (-G)
-# --pop-no-delete (-G)
   Disables the POP DELE command so that the command appears to succeed but mail
   messages are not deleted from the spool directory.
-
+* --pop-port <port> (-E)
-# --pop-port <port> (-E)
   Sets the POP server's listening port number.
 
-# --port <port> (-p)
+# Admin server options
-  Sets the port number used for listening for incoming SMTP connections.
 
-# --prompt-timeout <time> (-w)
+* --admin <port> (-a)
-  Specifies a timeout (in seconds) for getting the initial prompt from a remote
+  Enables an administration interface on the specified listening port number.
-  SMTP server. If no prompt is received after this time then the SMTP dialog
+  Use telnet or something similar to connect. The administration interface
-  goes ahead without it.
+  can be used to trigger forwarding of spooled mail messages if the
+  "--forward-to" option is used.
+* --admin-terminate (-Q)
+  Enables the "terminate" command in the administration interface.
 
-# --remote-clients (-r)
+# Authentication options
-  Allows incoming connections from addresses that are not local. The default
-  behaviour is to reject connections that are not local in order to prevent
-  accidental exposure to the public internet, although a firewall should also
-  be used. Local address ranges are defined in RFC-1918, RFC-6890 etc.
 
-# --response-timeout <time> (-T)
+* --client-auth <file> (-C)
-  Specifies a timeout (in seconds) for getting responses from remote SMTP
+  Enables SMTP client authentication with the remote server, using the client
-  servers. The default is 1800 seconds.
+  account details taken from the specified secrets file. The secrets file
-
+  should normally contain one line that starts with "client" and that line
-# --server-auth <file> (-S)
+  should have between four and five space-separated fields; the second field
+  is the password encoding ("plain" or "md5"), the third is the user-id and
+  the fourth is the password. The user-id is RFC-1891 xtext encoded, and the
+  password is either xtext encoded or generated by "emailrelay-passwd". If
+  the remote server does not support SMTP authentication then the SMTP
+  connection will fail.
+* --client-auth-config <config>
+  Configures the SMTP client authentication module using a semicolon-separated
+  list of configuration items. Each item is a single-character key, followed
+  by a colon and then a comma-separated list. A 'm' character introduces an
+  ordered list of preferred authentication mechanisms and an 'x' introduces a
+  list of mechanisms to avoid. An 'a' list and a 'd' list can be used
+  similarly to prefer and avoid certain mechanisms once the session is
+  encrypted with TLS.
+* --server-auth <file> (-S)
   Enables SMTP server authentication of remote SMTP clients. Account names and
   passwords are taken from the specified secrets file. The secrets file
   should contain lines that have four space-separated fields, starting with
@@ -305,74 +197,149 @@ where <option> is:
   password. The user-id is RFC-1891 xtext encoded, and the password is either
   xtext encoded or generated by "emailrelay-passwd". A special value of
   "/pam" can be used for authentication using linux PAM.
-
+* --server-auth-config <config>
-# --server-auth-config <config>
   Configures the SMTP server authentication module using a semicolon-separated
   list of configuration items. Each item is a single-character key, followed
-  by a colon and then a comma-separated list. A 'm' character introduces a
+  by a colon and then a comma-separated list. A 'm' character introduces an
-  preferred sub-set of the built-in authentication mechanisms, and an 'x' is
+  ordered list of allowed authentication mechanisms and an 'x' introduces a
-  used for blocklisted mechanisms.
+  list of mechanisms to deny. An 'a' list and a 'd' list can be used
+  similarly to allow and deny mechanisms once the session is encrypted with
+  TLS. In typical usage you might have an empty allow list for an unencrypted
+  session and a single preferred mechanism once encrypted, "m:;a:plain".
+* --pop-auth <file> (-F)
+  Specifies a file containing valid POP account details. The file format is the
+  same as for the SMTP server secrets file, ie. lines starting with "server",
+  with user-id and password in the third and fourth fields. A special value
+  of "/pam" can be used for authentication using linux PAM.
 
-# --server-tls (-K)
+# TLS options
+
+* --client-tls (-j)
+  Enables negotiated TLS for outgoing SMTP connections; the SMTP STARTTLS
+  command will be issued if the remote server supports it.
+* --client-tls-certificate <pem-file>
+  Defines the TLS certificate file when acting as a SMTP client. This file must
+  contain the client's private key and certificate chain using the PEM file
+  format. Alternatively, use this option twice with the first one specifying
+  the key file and the second the certificate file. Keep the file permissions
+  tight to avoid accidental exposure of the private key.
+* --client-tls-connection (-b)
+  Enables the use of a TLS tunnel for outgoing SMTP connections. This is for
+  SMTP over TLS (SMTPS), not TLS negotiated within SMTP using STARTTLS.
+* --client-tls-required
+  Makes the use of TLS mandatory for outgoing SMTP connections. The SMTP
+  STARTTLS command will be used before mail messages are sent out. If the
+  remote server does not allow STARTTLS then the SMTP connection will fail.
+* --client-tls-server-name <hostname>
+  Defines the target server hostname in the TLS handshake. With
+  "--client-tls-connection" this can be used for SNI, allowing the remote
+  server to adopt an appropriate identity.
+* --client-tls-verify <ca-list>
+  Enables verification of the remote SMTP server's certificate against any of
+  the trusted CA certificates in the specified file or directory. In many use
+  cases this should be a file containing just your self-signed root
+  certificate. Specify "<default>" for the TLS library's default set of
+  trusted CAs.
+* --client-tls-verify-name <cname>
+  Enables verification of the CNAME within the remote SMTP server's
+  certificate.
+* --server-tls (-K)
   Enables TLS for incoming SMTP and POP connections. SMTP clients can then
   request TLS encryption by issuing the STARTTLS command. The
   "--server-tls-certificate" option must be used to define the server
   certificate.
-
+* --server-tls-certificate <pem-file>
-# --server-tls-certificate <pem-file>
   Defines the TLS certificate file when acting as a SMTP or POP server. This
   file must contain the server's private key and certificate chain using the
   PEM file format. Alternatively, use this option twice with the first one
   specifying the key file and the second the certificate file. Keep the file
   permissions tight to avoid accidental exposure of the private key.
-
+* --server-tls-connection
-# --server-tls-connection
   Enables SMTP over TLS when acting as an SMTP server. This is for SMTP over
   TLS (SMTPS), not TLS negotiated within SMTP using STARTTLS.
-
+* --server-tls-required
-# --server-tls-required
   Makes the use of TLS mandatory for any incoming SMTP and POP connections.
   SMTP clients must use the STARTTLS command to establish a TLS session
   before they can issue SMTP AUTH or SMTP MAIL-TO commands.
-
+* --server-tls-verify <ca-list>
-# --server-tls-verify <ca-list>
   Enables verification of remote SMTP and POP clients' certificates against any
   of the trusted CA certificates in the specified file or directory. In many
   use cases this should be a file containing just your self-signed root
   certificate. Specify "<default>" for the TLS library's default set of
   trusted CAs.
-
+* --tls-config <options> (-9)
-# --size <bytes> (-M)
-  Limits the size of mail messages that can be submitted over SMTP.
-
-# --spool-dir <dir> (-s)
-  Specifies the directory used for holding mail messages that have been
-  received but not yet forwarded.
-
-# --syslog[=<facility>] (-k)
-  When used with "--log" this option enables logging to the syslog even if the
-  "--no-syslog" option is also used. This is typically used as a convenient
-  override when using "--as-client".
-
-# --tls-config <options> (-9)
   Selects and configures the low-level TLS library, using a comma-separated
   list of keywords. If OpenSSL and mbedTLS are both built in then keywords of
   "openssl" and "mbedtls" will select one or the other. Keywords like
   "tlsv1.0" can be used to set a minimum TLS protocol version, or "-tlsv1.2"
   to set a maximum version.
 
-# --user <username> (-u)
+# Process options
+
+* --dont-serve (-x)
+  Disables all network serving, including SMTP, POP and administration
+  interfaces. The program will terminate as soon as any initial forwarding is
+  complete.
+* --hidden (-H)
+  Windows only. Hides the application window and disables all message boxes,
+  overriding any "--show" option. This is useful when running as a windows
+  service.
+* --localedir <dir>
+  Enables localisation and specifies the locale base directory where message
+  catalogues can be found. An empty directory can be used for the built-in
+  default.
+* --no-daemon (-t)
+  Disables the normal backgrounding at startup so that the program runs in the
+  foreground, without forking or detaching from the terminal.  On Windows
+  this disables the system tray icon so the program uses a normal window;
+  when the window is closed the program terminates.
+* --no-smtp (-X)
+  Disables listening for incoming SMTP connections.
+* --pid-file <path> (-i)
+  Causes the process-id to be written into the specified file when the program
+  starts up, typically after it has become a background daemon. The immediate
+  parent directory is created if necessary.
+* --user <username> (-u)
   When started as root the program switches to a non-privileged effective
   user-id when idle. This option can be used to define the idle user-id and
   also the group ownership of new files and sockets. Specify "root" to
   disable all user-id switching. Ignored on Windows.
 
-# --verbose (-v)
+# Logging options
+
+* --verbose (-v)
   Enables more verbose logging when used with "--log", and more verbose help
   when used with "--help".
-
+* --log (-l)
-# --version (-V)
+  Enables logging to the standard error stream and to the syslog. The
-  Displays version information and then exits.
+  "--close-stderr" and "--no-syslog" options can be used to disable output to
+  standard error stream and the syslog separately. Note that "--as-server",
+  "--as-client" and "--as-proxy" imply "--log", and "--as-server" and
+  "--as-proxy" also imply "--close-stderr".
+* --debug (-g)
+  Enables debug level logging, if built in. Debug messages are usually only
+  useful when cross-referenced with the source code and they may expose
+  plaintext passwords and mail message content.
+* --log-address
+  Adds the network address of remote clients to the logging output.
+* --log-file <file> (-N)
+  Redirects standard-error logging to the specified file. Logging to the log
+  file is not affected by "--close-stderr". The filename can include "%d" to
+  get daily log files; the "%d" is replaced by the current date in the local
+  timezone using a "YYYYMMDD" format.
+* --log-time (-L)
+  Adds a timestamp to the logging output using the local timezone.
+* --no-syslog (-n)
+  Disables logging to the syslog. Note that "--as-client" implies
+  "--no-syslog".
+* --syslog[=<facility>] (-k)
+  When used with "--log" this option enables logging to the syslog even if the
+  "--no-syslog" option is also used. This is typically used as a convenient
+  override when using "--as-client".
+* --close-stderr (-e)
+  Causes the standard error stream to be closed soon after start-up. This is
+  useful when operating as a background daemon and it is therefore implied by
+  "--as-server" and "--as-proxy".
 
 A configuration file can be used to provide additional options; put each
 option on a separate line, use the long option names but without the double
@@ -709,7 +676,7 @@ key.
 This OpenSSL command can be used to create a self-signed certificate file
 suitable for testing:
 
-	$ openssl req -x509 -nodes -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
+	$ openssl req -x509 -noenc -subj "/CN=$USER" -newkey rsa:2048 -keyout emailrelay.pem  -out emailrelay.pem
 
 TLS performs encryption to prevent eavesdropping, but it does not necessarily
 do authentication to prevent man-in-the-middle attacks. For full TLS
@@ -746,17 +713,13 @@ normally involves creating a file "/etc/pam.d/emailrelay" containing something
 like the following:
 
 	auth requisite pam_unix.so nullok_secure
-	session required pam_permit.so
-	account required pam_permit.so
-	password required pam_deny.so
 
 With this configuration the E-MailRelay server will use normal unix system
 account names and passwords to authenticate remote clients. On some systems
 this will require special permissioning to allow the E-MailRelay server to
-read the shadow password database.
+read the shadow password database, so run the server as "root" and also add the
-
+"--user=root" command-line option to make sure that the process's effective
-When using PAM authentication E-MailRelay requires that remote clients
+user-id stays as "root" while it accesses the PAM system.
-establish an encrypted session using TLS before authentication can proceed.
 
 IP addresses
 ------------
@@ -1076,7 +1039,7 @@ The following are some security issues that have been taken into consideration:
 
 # Umask
 
-  The program runs for most of the time with a "umask" of 177, switching to 117
+  The program runs for most of the time with a "umask" of 077, switching to 007
   when creating spool files.
 
 # Remote clients
@@ -1174,6 +1137,30 @@ and "Cc" message recipients.
 An E-MailRelay "--filter" script can be used to reject messages with incorrect
 "Bcc:" headers, and an example script is included.
 
+Routing
+-------
+E-MailRelay does not normally do any routing of e-mail messages; they are
+all forwarded to a fixed "smarthost" address given by the "--forward-to" or
+"--as-client" command-line options.
+
+However, each message envelope file contains a "ForwardToAddress" field that
+can be populated by filter scripts in order to route the message to some other
+server.
+
+If the "ForwardTo" field has any non-empty value then E-MailRelay runs its
+client filter early to allow the client filter script to set or update the
+"ForwardToAddress" before the outgoing connection is made. (The client filter is
+run a second time as normal once the connection is made and the SMTP session has
+been established.)
+
+Typically a "--filter" script would be used to examine the message content and
+populate the "ForwardTo" field, then a "--client-filter" script would use
+the "ForwardTo" value to populate the "ForwardToAddress" field with an up-to-date
+forwarding address.
+
+Note that a successful connection to the smarthost is required even if a message
+is routed elsewhere.
+
 Files and directories
 ---------------------
 On Unix-like systems E-MailRelay installs by default under "/usr/local", but
@@ -1218,4 +1205,4 @@ and these default to "%ProgramFiles%/E-MailRelay" for programs and
 
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker

doc/serverclient.svg

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
 
 <svg
    xmlns:dc="http://purl.org/dc/elements/1.1/"

doc/userguide.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "%-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay User Guide</title>
@@ -8,7 +8,7 @@
  <body>
   <!-- index:0::::E-MailRelay User Guide -->
  <div class="div-main">
-  <h1><a class="a-header" name="H_1">E-MailRelay User Guide</a></h1> <!-- index:1:H:1::E-MailRelay User Guide -->
+  <h1><a class="a-header" name="H_1">E-MailRelay User Guide</a></h1> <!-- index:1:H:E-MailRelay User Guide -->
    <h2><a class="a-header" name="SH_1_1">What is it?</a></h2> <!-- index:2:SH:1:1:What is it? -->
     <p>
      E-MailRelay is an e-mail store-and-forward message transfer agent and proxy
@@ -44,9 +44,9 @@
     </p>
    <h2><a class="a-header" name="SH_1_2">What it's not</a></h2> <!-- index:2:SH:1:2:What it's not -->
     <p>
-     E-MailRelay does not do routing of individual messages; it is not a routing MTA.
+     E-MailRelay does not normally do routing of individual messages; it is not a
-     It forwards all e-mail messages to a pre-configured SMTP server, regardless of
+     routing MTA. It forwards all e-mail messages to a pre-configured SMTP server,
-     any message addressing or DNS redirects.
+     regardless of any message addressing or DNS redirects.
     </p>
    <h2><a class="a-header" name="SH_1_3">Why use it?</a></h2> <!-- index:2:SH:1:3:Why use it? -->
     <p>
@@ -447,32 +447,49 @@ exit 0</pre>
       </div><!-- div-pre -->
    <h2><a class="a-header" name="SH_1_14">Google mail</a></h2> <!-- index:2:SH:1:14:Google mail -->
     <p>
-     To send mail via Google mail's SMTP gateway you will need to create a client
+     To send mail via Google mail's SMTP gateway you will need to obtain a new
-     secrets file containing your account details and also enable TLS support in
+     <em>application password</em> from Google. Log in to your Google account and look for
-     E-MailRelay by using the <em>--client-tls</em> option.
+     the account's security settings and then <em>app passwords</em>. Create the password
+     for E-MailRelay as application type <em>other</em>.
     </p>
 
     <p>
-     The secrets file should contain one line of text something like this:
+     Then you need to create a client secrets file for E-MailRelay containing your
+     account name and the new application password. You may already have this file
+     on Windows as <em>C:\ProgramData\E-MailRelay\emailrelay.auth</em>.
+    </p>
+
+    <p>
+     You should edit the file to contain one <em>client</em> line, something like this:
     </p>
 
       <div class="div-pre">
-       <pre>client plain myname@gmail.com my+20password
+       <pre>client plain myname@gmail.com myapppassword
 </pre>
       </div><!-- div-pre -->
     <p>
-     If your password contains a space, equals or plus sign, or any control
+     Then change the E-MailRelay startup batch file or configuration file to refer
-     character then you will need to replace those characters with their
+     to your secrets file by using the <em>--client-auth</em> option. The <em>--as-proxy</em> or
-     corresponding hexadecimal ascii value, something like <em>+20</em> or <em>+2B</em>.
+     <em>--forward-to</em> options should be set to <em>smtp.gmail.com:587</em> and you will also
+     need to add the <em>--client-tls</em> option to enable TLS encryption.
     </p>
 
     <p>
-     Refer to your secrets file by using <em>--client-auth</em> on the E-MailRelay
+     On Windows the E-MailRelay startup batch file should contain something like this:
-     command-line, and also add in the <em>--client-tls</em> option:
     </p>
 
       <div class="div-pre">
-       <pre>emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=/etc/emailrelay.auth ...</pre>
+       <pre>emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=C:/ProgramData/E-MailRelay/emailrelay.auth ...
+</pre>
+      </div><!-- div-pre -->
+    <p>
+     Or in a configration file like this:
+    </p>
+
+      <div class="div-pre">
+       <pre>forward-to smtp.gmail.com:587
+client-tls
+client-auth C:/ProgramData/E-MailRelay/emailrelay.auth</pre>
       </div><!-- div-pre -->
    <h2><a class="a-header" name="SH_1_15">Connection tunnelling</a></h2> <!-- index:2:SH:1:15:Connection tunnelling -->
     <p>
@@ -509,10 +526,10 @@ exit 0</pre>
 
     <div class="div-footer">
      <p>
-      Copyright (C) 2001-2021 Graeme Walker
+      Copyright (C) 2001-2022 Graeme Walker
      </p>
     </div><!-- div-footer -->
  </div> <!-- div-main -->
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/userguide.md

@@ -27,9 +27,9 @@ General Public License V3.
 
 What it's not
 -------------
-E-MailRelay does not do routing of individual messages; it is not a routing [MTA][].
+E-MailRelay does not normally do routing of individual messages; it is not a
-It forwards all e-mail messages to a pre-configured SMTP server, regardless of
+routing [MTA][]. It forwards all e-mail messages to a pre-configured SMTP server,
-any message addressing or DNS redirects.
+regardless of any message addressing or DNS redirects.
 
 Why use it?
 -----------
@@ -317,22 +317,33 @@ On Windows an equivalent batch script would be:
 
 Google mail
 -----------
-To send mail via Google mail's SMTP gateway you will need to create a client
+To send mail via Google mail's SMTP gateway you will need to obtain a new
-secrets file containing your account details and also enable [TLS][] support in
+`application password` from Google. Log in to your Google account and look for
-E-MailRelay by using the `--client-tls` option.
+the account's security settings and then `app passwords`. Create the password
+for E-MailRelay as application type `other`.
 
-The secrets file should contain one line of text something like this:
+Then you need to create a client secrets file for E-MailRelay containing your
+account name and the new application password. You may already have this file
+on Windows as `C:\ProgramData\E-MailRelay\emailrelay.auth`.
 
-        client plain myname@gmail.com my+20password
+You should edit the file to contain one `client` line, something like this:
 
-If your password contains a space, equals or plus sign, or any control
+        client plain myname@gmail.com myapppassword
-character then you will need to replace those characters with their
-corresponding hexadecimal ascii value, something like `+20` or `+2B`.
 
-Refer to your secrets file by using `--client-auth` on the E-MailRelay
+Then change the E-MailRelay startup batch file or configuration file to refer
-command-line, and also add in the `--client-tls` option:
+to your secrets file by using the `--client-auth` option. The `--as-proxy` or
+`--forward-to` options should be set to `smtp.gmail.com:587` and you will also
+need to add the `--client-tls` option to enable [TLS][] encryption.
 
-        emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=/etc/emailrelay.auth ...
+On Windows the E-MailRelay startup batch file should contain something like this:
+
+        emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=C:/ProgramData/E-MailRelay/emailrelay.auth ...
+
+Or in a configration file like this:
+
+        forward-to smtp.gmail.com:587
+        client-tls
+        client-auth C:/ProgramData/E-MailRelay/emailrelay.auth
 
 Connection tunnelling
 ---------------------
@@ -369,4 +380,4 @@ to `fail2ban`.
 [TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker

doc/userguide.rst

@@ -30,9 +30,9 @@ General Public License V3.
 
 What it's not
 =============
-E-MailRelay does not do routing of individual messages; it is not a routing MTA_.
+E-MailRelay does not normally do routing of individual messages; it is not a
-It forwards all e-mail messages to a pre-configured SMTP server, regardless of
+routing MTA_. It forwards all e-mail messages to a pre-configured SMTP server,
-any message addressing or DNS redirects.
+regardless of any message addressing or DNS redirects.
 
 Why use it?
 ===========
@@ -354,26 +354,39 @@ On Windows an equivalent batch script would be:
 
 Google mail
 ===========
-To send mail via Google mail's SMTP gateway you will need to create a client
+To send mail via Google mail's SMTP gateway you will need to obtain a new
-secrets file containing your account details and also enable TLS_ support in
+*application password* from Google. Log in to your Google account and look for
-E-MailRelay by using the *--client-tls* option.
+the account's security settings and then *app passwords*. Create the password
+for E-MailRelay as application type *other*.
 
-The secrets file should contain one line of text something like this:
+Then you need to create a client secrets file for E-MailRelay containing your
+account name and the new application password. You may already have this file
+on Windows as *C:\\ProgramData\\E-MailRelay\\emailrelay.auth*.
+
+You should edit the file to contain one *client* line, something like this:
 
 ::
 
-    client plain myname@gmail.com my+20password
+    client plain myname@gmail.com myapppassword
 
-If your password contains a space, equals or plus sign, or any control
+Then change the E-MailRelay startup batch file or configuration file to refer
-character then you will need to replace those characters with their
+to your secrets file by using the *--client-auth* option. The *--as-proxy* or
-corresponding hexadecimal ascii value, something like *+20* or *+2B*.
+*--forward-to* options should be set to *smtp.gmail.com:587* and you will also
+need to add the *--client-tls* option to enable TLS_ encryption.
 
-Refer to your secrets file by using *--client-auth* on the E-MailRelay
+On Windows the E-MailRelay startup batch file should contain something like this:
-command-line, and also add in the *--client-tls* option:
 
 ::
 
-    emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=/etc/emailrelay.auth ...
+    emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=C:/ProgramData/E-MailRelay/emailrelay.auth ...
+
+Or in a configration file like this:
+
+::
+
+    forward-to smtp.gmail.com:587
+    client-tls
+    client-auth C:/ProgramData/E-MailRelay/emailrelay.auth
 
 Connection tunnelling
 =====================
@@ -412,4 +425,4 @@ to *fail2ban*.
 .. _SOCKS: https://en.wikipedia.org/wiki/SOCKS
 .. _TLS: https://en.wikipedia.org/wiki/Transport_Layer_Security
 
-.. footer:: Copyright (C) 2001-2021 Graeme Walker
+.. footer:: Copyright (C) 2001-2022 Graeme Walker

doc/userguide.txt

@@ -27,9 +27,9 @@ General Public License V3.
 
 What it's not
 -------------
-E-MailRelay does not do routing of individual messages; it is not a routing MTA.
+E-MailRelay does not normally do routing of individual messages; it is not a
-It forwards all e-mail messages to a pre-configured SMTP server, regardless of
+routing MTA. It forwards all e-mail messages to a pre-configured SMTP server,
-any message addressing or DNS redirects.
+regardless of any message addressing or DNS redirects.
 
 Why use it?
 -----------
@@ -316,22 +316,33 @@ On Windows an equivalent batch script would be:
 
 Google mail
 -----------
-To send mail via Google mail's SMTP gateway you will need to create a client
+To send mail via Google mail's SMTP gateway you will need to obtain a new
-secrets file containing your account details and also enable TLS support in
+"application password" from Google. Log in to your Google account and look for
-E-MailRelay by using the "--client-tls" option.
+the account's security settings and then "app passwords". Create the password
+for E-MailRelay as application type "other".
 
-The secrets file should contain one line of text something like this:
+Then you need to create a client secrets file for E-MailRelay containing your
+account name and the new application password. You may already have this file
+on Windows as "C:\ProgramData\E-MailRelay\emailrelay.auth".
 
-	client plain myname@gmail.com my+20password
+You should edit the file to contain one "client" line, something like this:
 
-If your password contains a space, equals or plus sign, or any control
+	client plain myname@gmail.com myapppassword
-character then you will need to replace those characters with their
-corresponding hexadecimal ascii value, something like "+20" or "+2B".
 
-Refer to your secrets file by using "--client-auth" on the E-MailRelay
+Then change the E-MailRelay startup batch file or configuration file to refer
-command-line, and also add in the "--client-tls" option:
+to your secrets file by using the "--client-auth" option. The "--as-proxy" or
+"--forward-to" options should be set to "smtp.gmail.com:587" and you will also
+need to add the "--client-tls" option to enable TLS encryption.
 
-	emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=/etc/emailrelay.auth ...
+On Windows the E-MailRelay startup batch file should contain something like this:
+
+	emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=C:/ProgramData/E-MailRelay/emailrelay.auth ...
+
+Or in a configration file like this:
+
+	forward-to smtp.gmail.com:587
+	client-tls
+	client-auth C:/ProgramData/E-MailRelay/emailrelay.auth
 
 Connection tunnelling
 ---------------------
@@ -360,4 +371,4 @@ to "fail2ban".
 
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker

doc/whatisit.svg

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
 
 <svg
    xmlns:dc="http://purl.org/dc/elements/1.1/"

doc/windows.html

@@ -1,4 +1,4 @@
-<!DOCTYPE HTML PUBLIC "%-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!DOCTYPE html>
 <html>
  <head>
   <title>E-MailRelay Windows</title>
@@ -8,7 +8,7 @@
  <body>
   <!-- index:0::::E-MailRelay Windows -->
  <div class="div-main">
-  <h1><a class="a-header" name="H_1">E-MailRelay Windows</a></h1> <!-- index:1:H:1::E-MailRelay Windows -->
+  <h1><a class="a-header" name="H_1">E-MailRelay Windows</a></h1> <!-- index:1:H:E-MailRelay Windows -->
    <h2><a class="a-header" name="SH_1_1">Setup program</a></h2> <!-- index:2:SH:1:1:Setup program -->
     <p>
      Installing E-MailRelay on Windows should be straightforward if you have the
@@ -45,9 +45,10 @@
     </p>
 
     <p>
-     Note that the <em>emailrelay-start.bat</em> file lives under <em>ProgramData</em>, and although
+     Note that the <em>emailrelay-start.bat</em> file lives under <em>ProgramData</em>, and
-     this might be a hidden directory you can still navigate there by right-clicking
+     although this might be a hidden directory you can still navigate there by
-     on the E-MailRelay link under <em>Program Files</em> and selecting <em>Open file location</em>.
+     right-clicking on the <em>E-MailRelay</em> link under <em>Program Files</em> and selecting
+     <em>Open file location</em>.
     </p>
    <h2><a class="a-header" name="SH_1_3">Configuration</a></h2> <!-- index:2:SH:1:3:Configuration -->
     <p>
@@ -200,10 +201,10 @@
 
     <div class="div-footer">
      <p>
-      Copyright (C) 2001-2021 Graeme Walker
+      Copyright (C) 2001-2022 Graeme Walker
      </p>
     </div><!-- div-footer -->
  </div> <!-- div-main -->
  </body>
 </html>
-<!-- Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->
+<!-- Copyright (C) 2001-2022 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved. -->

doc/windows.md

@@ -27,9 +27,10 @@ run the `emailrelay-start.bat` batch file to start the E-MailRelay server, and
 you should then see an icon appear in the Windows system tray under the "Show
 hidden icons" button.
 
-Note that the `emailrelay-start.bat` file lives under `ProgramData`, and although
+Note that the `emailrelay-start.bat` file lives under `ProgramData`, and
-this might be a hidden directory you can still navigate there by right-clicking
+although this might be a hidden directory you can still navigate there by
-on the E-MailRelay link under `Program Files` and selecting `Open file location`.
+right-clicking on the `E-MailRelay` link under `Program Files` and selecting
+`Open file location`.
 
 Configuration
 -------------
@@ -145,4 +146,4 @@ and `DATA`.
 [SMTP]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker

doc/windows.rst

@@ -28,9 +28,10 @@ run the *emailrelay-start.bat* batch file to start the E-MailRelay server, and
 you should then see an icon appear in the Windows system tray under the "Show
 hidden icons" button.
 
-Note that the *emailrelay-start.bat* file lives under *ProgramData*, and although
+Note that the *emailrelay-start.bat* file lives under *ProgramData*, and
-this might be a hidden directory you can still navigate there by right-clicking
+although this might be a hidden directory you can still navigate there by
-on the E-MailRelay link under *Program Files* and selecting *Open file location*.
+right-clicking on the *E-MailRelay* link under *Program Files* and selecting
+\ *Open file location*\ .
 
 Configuration
 =============
@@ -152,4 +153,4 @@ and *DATA*.
 
 .. _SMTP: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 
-.. footer:: Copyright (C) 2001-2021 Graeme Walker
+.. footer:: Copyright (C) 2001-2022 Graeme Walker

doc/windows.txt

@@ -141,4 +141,4 @@ and "DATA".
 
 
 _____________________________________
-Copyright (C) 2001-2021 Graeme Walker
+Copyright (C) 2001-2022 Graeme Walker