Linux Magic SMTP Daemon Compilation
-----------------------------------

READ FULL INSTRUCTIONS (to be safe)

QUICK INSTALL:
After unpacking the source tarball, simply change into the main directory
and type 'make'.  This will compile the project and it's required
libraries, which are included in the source tarball.

	`tar zxfv magic-smtpd-<version>.tar.gz` -OR-
		`gzip -cd magic-smtpd-<version>.tar.gz | tar xvf -`
	`cd magic-smtpd-<version>`
	`make`

	TODO: make install, in the mean time follow the FULL INSTALL
	instructions below.
	

FULL INSTALL:
The following installation steps depend on the default installation
directory for qmail to be /var/qmail.

This also assumes that you have a working qmail installation and that
you are using tcpserver to execute qmail-smtpd for oncoming connections.
This program has only been tested with tcp server, but other super servers
may also work (inetd, etc).

1) Unpack the source:
	tar zxfv magic-smtpd-<version>.tar.gz

2) Change to the source directory and build:
	cd magic-smtpd-<version>
	make

The following steps must be performed as root:

4) Shut down qmail (optional, but safer)

5) Make a safety copy of your existing qmail-smtpd program.
	cp -a /var/qmail/bin/qmail-smtpd /var/qmail/bin/qmail-smtpd.bak

6) Copy the linux magic smtpd executable into the binary directory
	cp ./magic-smtpd /var/qmail/bin

7a) Set the owner and group for the executable:
	chown root.qmail /var/qmail/bin/magic-smtpd

7b) Remove the existing qmail-smtpd binary, note that mail WILL fail
    that's why it is safer to stop qmail first eg. /etc/init.d/qmail stop
	mv /var/qmail/bin/qmail-smtpd /var/qmail/bin/qmail-smtpd.ori

7c) Create a symbolic link to the executable named qmail-smtpd:
	ln -s /var/qmail/bin/magic-smtpd /var/qmail/bin/qmail-smtpd 
or optionally a hard link:
	ln /var/qmail/bin/magic-smtpd /var/qmail/bin/qmail-smtpd

If you chose to install the program with a symbolic link, set the user and group permissions:
	chown root.qmail /var/qmail/bin/qmail-smtpd

8) Look at the following section and setup any control files you would
like to have different from the program defaults.  The default control
directory is /etc/magic-mail/control.

	mkdir /etc/magic-mail
	mkdir /etc/magic-mail/control

You will want to set the qmailcontroldir and qmailqueue if your
distribution installs qmail outside of /var/qmail.   

All other control files are optional and the program will run if the
are not set.  The defaults are to act as much like qmail as possible
without any extra features.   

Other common control files which you will probably use are listed in this
next section, however these instructions are for ease of use only, and you
should read the full DOCS ./docs/controlfiles?? or below, as to what each
does and whether these control settings are suitable for you.

	# Set Log level to only log message with importance of WARN or better
	echo 4 > /etc/magic-mail/control/log_level

	# Set the default qmail control file location, (DEFAULT,SEE DOCS)
	echo '/var/qmail/control' > /etc/magic-mail/control/qmailcontroldir

	# Location of the qmail-queue binary (DEFAULT)
	echo '/var/qmail/bin/qmail-queue' > /etc/magic-mail/control/qmail-queue

	# LOTS of options to rate limit spammers, see docs for their usage

	# If using virtual domains, you certainly want to change this, 
	# if you want valid user checking, otherwise we assume all addresses
	# are true. (DEFAULT)
	echo '/bin/true' > /etc/magic-mail/control/vdomain_checkuser_prog

	# You definitely want to change this if you want to enable SMTP auth
	# otherwise, every password will fail (DEFAULT)
	echo '/bin/false' > /etc/magic-mail/control/ext_check_passwd_prog

	# Do valid user checking, REALLY lowers the bounces you handle
	echo 1 > /etc/magic-mail/control/check_valid_users

	# We have lots of requests for SMTP AUTH, for roaming users
	# Remember, you need to have the AUTH password program
	# enabled above, for vpopmail style users (DEFAULT)
	echo 1 > /etc/magic-mail/control/auth_enable

RELEASE NOTE: 0.7.2rc1
	We should offer some logical suggestions for default RCPT
	rate limiting
END RELEASE NOTE: 0.7.2rc1

And of course there are many other options available, so please see all the
docs, but the above should get you up and running. If you have any problems
getting it up and running, with the instructions above, we should improve
something. :) Please join the mailing list at magicmail-users@linuxmagic.com

10) Restart qmail

If something goes wrong, you should always be able to get to your old 
qmail installation, by removing the symlink, and copying your original 
qmail-smtpd back into place.

Now your server should already be blocking mail to non-users, and using
SMTP AUTH, (if you used the control file suggestions above) and you can
tweak it further by looking at some of the rate limiting options, in the
control file docs.

But the best part is that you can now setup your Spam Blocking Rules.
Continue on with that (The Spam Rules)documentation from here, 
if you are doing a typical default install as described above.


Make Options
------------

NOTE: These should not be needed by mere mortals..

The following options can be passed to make on the command line to
customize the build process:

__GCC32__ - build the program and libraries with gcc-3.2
_LMDEBUG - build in debug mode with full library debugging and assertion code.
_LMRELEASE - build in release mode (DEFAULT)
_LMPROFILE - build for profiling (not tested)

These variables can be passed to make as follows:

	make __GCC32__=1 clean all

Other configuration options and default programs can be found in
lmlibs/Makefile.default.

Compile Time Options
--------------------

See the file lmlibs/config.h, config.h and magic-smtpd.h for other
compile time configuration options.

Environment Variables and Control Files
---------------------------------------

RELEASE NOTE: 0.7.2rc1
	Please NOTE that NOT all environment variables have been
	tested if passed as environment.  Suggest you ONLY use
	the control files as defined below, in /etc/magicmail/control
END RELEASE NOTE: 0.7.2rc1

All run time options are passed to the program using environment
variables.  All environment variables used by qmail-smtpd are used in
the same way, and the following are added:

All of these variables can also be control files, stored in the
default control directory /etc/magic-mail/control.  The name of the
control file is the environment variable name without the MSD_ prefix
and all lowercase (ie MSD_COMPAT_TYPE becomes compat_type).

Control files are loaded first at program startup then environment
variables.  Control files will override program defaults, and
environment variables will override control file values. 

Env: MSD_COMPAT_TYPE
Control: compat_type
Type: number
Default: 0
	 This sets the application compatibility of the smtp
	 daemon. This is an internal flag which can be set to the
	 following:

	 0 - Qmail compatibility. Does valid user checking using
	 .qmail files and aliases.  This should be the setting for
	 almost everyone and will provide valid user checking for
	 people with a working qmail installation.  Spam rules are
	 loaded from spamdir control directories which start with
	 .magicspam and follow the same naming conventions as .qmail
	 files for matching to email addresses.

	 1 - Vpop checking.  This performs valid user checking for
	 virtual domain vpop setups.  This is not tested and is pretty
	 much guaranteed not to work in any way that is expected at
	 the moment.

	 2 - Magic compatibility.  This system uses a database for
	 valid user checking and spam rule loading.  This is pretty
	 much undocumented at the moment but you might be able to
	 figure it out if you look through the code.

	 There is essentially no difference between 1 and 2.  Regular
	 users should leave this at 0 (or just not set it) as the
	 database spec is not complete and is for internal use only
	 at the moment.

Env: MSD_LOG_LEVEL
Control: log_level
Type: number 
Default: 6 (LOG_NOTICE) 
Logging level for the program which goes from 0-7 (emergency to
debug). This has changed since later versions and now matches syslog's
logging levels as follows (taken  from /usr/include/sys/syslog.h):
Name:		log_level value Description
LOG_EMERG	0		/* system is unusable */
LOG_ALERT	1		/* action must be taken immediately */
LOG_CRIT	2		/* critical conditions */
LOG_ERR		3		/* error conditions */
LOG_WARNING	4		/* warning conditions */
LOG_NOTICE	5		/* normal but significant condition */
LOG_INFO	6		/* informational */
LOG_DEBUG	7		/* debug-level messages */

Env: MSD_CONTROLDIR
Control: controldir
Type: string (directory path)
Default: /etc/magic-mail/control
	 Location for the configuration control files specific to
	 magic-smtpd.
	 There really is not point to setting this as a control file
	 and is only included for completeness.

Env: MSD_QMAILCONTROLDIR
Control: qmailcontroldir
Type: string (directory path)
Default: /var/qmail/control
	Location of qmail's control files if qmail was not installed
	in /var/qmail.

Env: MSD_QMAIL_QUEUE
Control: qmail_queue
Type: string (directory path)
Default: /var/qmail/bin/qmail-queue
	The full path to the qmail-queue executable on the system.
	Qmail's default install directory is in /var/qmail, but
	some distributions move it from there so you will have to set
	this.

Env: MSD_RFC_ADDR_ONLY
Control: rfc_addr_only
Type: boolean number (0/1)
Default: 0 (false)
	 Accept only RFC2821 compliant addresses in MAIL and RCPT
	 commands. eg:
	 MAIL From: <user@host.org>
	      and not
	 MAIL From: user@host.org
	 Returns syntax error if not in this format.
	 
Env: MSD_MAX_LINE_LENGTH
Control: max_line_length
Type: number
Default: 1024
	Maximum length of a command string or message line that will be
	read before returning an error message to the sending client.

Env: MSD_MAX_SMTP_CMDS
Control: max_smtp_cmds
Type: number
Default: LONGMAX-1
	 This is the maximum number of SMTP command that will be
	 processed per individual connection.  Exceeding this amount
	 will return a 552 error code to the client and disconnect.
	 
Env: MSD_MAX_RCPT
Control: max_rcpt
Type: number
Default: LONGMAX-1
	Maximum number of RCPT's allowed per client connection.  This
	is independent of MSD_MAX_SMTP_CMDS.

Env: MSD_MAX_INVALID_RCPT
Control: max_invalid_rcpt
Type: number
Default: LONGMAX-1
	Maximum number of RCPT's which contain non-existent users
	that will be accepted per connection before printing a 550
	message and exiting.

Env: MSD_RCPT_DELAY_AT
Control: rcpt_delay_at
Type: number
Default: 10
	The number of RCPT's to allow before imposing the RCPT delay
	penalty for a client.

Env: MSD_RCPT_DELAY_INC
Control: rcpt_delay_inc
Type: number
Default: 1
	The number of seconds to increment the value of RCPT delay for
	each RCPT after MSD_RCPT_DELAY_AT RCPT's are met.

Env: MSD_RCPT_DELAY_MAX
Control: rcpt_delay_max
Type: number
Default: 10
	The maximum number of seconds to raise RCPT delay to.

Env: MSD_MAX_HOPS
Control: max_hops
Type: number
Default: 100
	The maximum number of Received: and Delivered: allowed in a header
	before error flagging a message for being in a mail delivery loop.

Env: MSD_VDOMAIN_CHECK_USER_PROG
Control: vdomain_checkuser_prog
Type: string (full path to executable program)
Default: /bin/true
	The program that will be used to check the validity of virtual
	domain users if vdomains
	See README.virtual for more information.

Env: MSD_EXT_CHECK_PASSWD_PROG
Control: ext_check_passwd_prog
THIS IS NOT USED AT THE MOMENT BUT WILL BE IN A FUTURE RELEASE.
Type: string (full path to executable program)
Default: /bin/false
	 Path to the checkpassword compatible program (http://cr.yp.to
	 for details) for verifying passwords during AUTH.

Env: MSD_COUNTRY_CODE_PROG (DEPRECATED, Version 0.7.2rc1)
Control: country_code_prog
Type: string (full path to executable program)
Default: "echo **"
	 This is the path to a program which takes an IP address as
	 input and returns its 2 digit country code as output.  We
	 include a script which uses the CPAN IP::Country module,
	 which must be installed for this functionality to work.

Env: MSD_PER_USER_SPAM_ENABLE
Control: per_user_spam_enable
Type: boolean (0/1)
Default: 0
	If this variable is set, only allow users which have authorization
	to use spam checking functions.  Users are specified by having
	a file in the $MSD_CONTROLDIR/spam_users/ directory that
	matches the username of the system user that a given email
	address maps to.

Env: MSD_CHECK_VALID_USERS
Control: check_valid_users
Type: boolean (0/1)
Default: 1
	Perform checks after the program receives a RCPT command to see
	if the user that the mail is being sent to exists on the
	system.

Env: MSD_STRAY_NEWLINE_DETECTION
Control: stray_newline_detection
Type: boolean (0/1)
Default: 1
	 Check for stray newlines in message data.  See
	 http://pobox.com/~djb/docs/smtplf.html for details.

Env: MSD_ADD_CHECK_FLAGS
Control: add_check_flags
Type: boolean (0/1)
Default: 0
	 Add MSD_CHECK_FLAG_SEP and v or s for virus or spam checking
	 at the delivery stage. eg. for a message to someone@host.com,
	 and "someone" has virus and spam checking enabled, and
	 MSD_CHECK_FLAG_SEP is set to "-%-" deliver the message to
	 someone-%-vs@host.com.  Use this only if you have installed
	 magic-local as a replacement for qmail-local on your
	 system. These flags tell magic-local what type of processing
	 to do on messages before they are passed to the real
	 qmail-local for delivery.

Env: MSD_CHECK_FLAG_SEP
Control: check_flag_sep
Type: string
Default: "-%-"
	 Separator string added to the end of mailbox names but before
	 spam and virus check flags. See MSD_ADD_CHECK_FLAGS for details.

The following are for the proprietary version only:

Env: MSD_AUTH_ENABLE
Control: auth_enable
Type: Boolean (0/1)
Default: 1
	Enable authorization using an external database which holds the
	crypt'd password.

Env: MSD_DBNAME
Control: dbname
Env: MSD_DBHOST
Control: dbhost
Env: MSD_DBPORT
Control: dbport
Env: MSD_DBUSER
Control: dbuser
Env: MSD_DBPWD
Control: dbpwd
Type: string
Default: not what you would want for your setup
	The connection options for the configuration/authorization database.  

Env: MSD_CONF_TABLE
Control: conf_table
Type: string
Default: config
	Table in the database which is used to store the control files for
	the program.  They are exactly the same as regular control files
	only acessed in this table using the columns 'key' and 'value'.

Env: MSD_SPAM_TABLE
Control: spam_table
Type: string
Default: spamtable
	Table holding the spam rules.

Control: always_virus_check
Type: boolean
Default: false
    If this is set to true, magic-local will send every message to virus_local

Control: virus_local
Type: string
Default: /var/qmail/bin/qmail-local
    Magic-local will use this program (must accept qmail-local style arguments) 
    as the local delivery agent after doing it's spam checks if virus checking
    is enabled.

Control: qmail_local
Type: string
Default: /var/qmail/bin/qmail-local
    Magic-local will use this program (must accept qmail-local style arguments) 
    as the local delivery agent after doing it's spam checks if virus checking
    is not enabled.


Qmail Control Files
-------------------

All qmail-smtpd control files are used and recognized except for the following exceptions:

morercpthosts.cdb - this file is not read but
instead we read morercpthosts and append that to the
contents of the rcpthosts control file.

