SYNONYM - The Mail ARCHiver (http://www.modulo.ro/synonym)

1. What is Synonym?

Synonym is a Milter extension that offers message archiving capabilities. It runs on top of Sendmail via the Milter extension and copies all incoming and outgoing email to a predefined mailbox.
The rest of the document offers a step-by-step guide to installing Synonym.

2. Installing Synonym

2.1 Dependencies
	- Sendmail ( >8.11, older versions may work too, I'm not sure I did not check)
	- Sendmail 'cf' (the configuration file needs to be altered and compiling sendmail.mc relies on this) 
	- Sendmail development (the milter headers and libraries)
	- GNU Make

2.2 Compiling the Synonym source files
	Untar synonym:
	# tar zxvf synonym-x.y.z.tar.gz

	Enter the Synonym directory:
	# cd Synonym

	Compile Synonym
	# make

2.3 Installing Synonym
	From the synonym directory, do a 
	# make install
	This will copy the synonym binary to the /usr/local/bin directory, create the rundir (default /var/run/synonym) and install the service control script (/etc/rc.d/init.d/synonym).

2.4 Configuring sendmail
	Please make sure to backup your sendmail.cf file prior to this.
	Add the following two lines to your (/etc/mail/ or /etc/)sendmail.mc file:

	define(`_FFR_MILTER', `true')
	INPUT_MAIL_FILTER(`Synonym', `S=local:/var/run/synonym/synonym.sock, T=C:10m;S:1s;R:1s;E:5m')

	Generate the sendmail.cf in the same directory:
	# m4 < sendmail.mc > sendmail.cf

	Restart sendmail.

2.5 Configure Synonym

	Synonym runs as user 'mail' group 'mail' by default (on linux). Changing this should be done in the startup script (the -u cmd line option). The ownership of the run directory (default /var/run/synonym) should also be changed to match the user Synonym runs as.
	Edit /etc/synonym.conf to change the configuration for wilter.
	The configuration file must be xml compliant and must contain the following sections (each section being defined by an XML element):

	- Rules: This is the main rules section, all the rules will be defined underneath it. Only one Rules section per config file may exist. Only 'Rule' sections (one or more - at least one) may be defined in the 'Rules' section.
	- Rule: Defines one rule. A rule is a complete conditions/action set. A rule section may contain one or more (at least one) 'Condition' element (described below). A rule must also contain exactly one 'Action' element.
	- Condition: Elements defined underneath the 'Rule' section. Each 'Condition' element must contain exactly one 'Header' element and exactly one 'Match' element. The header element defines the header name whose value will be compared (via regular expression) to the content of the 'Match' element.
	- Header: The text value in this element is the header name that is looked for in the email. The header name is case-insensitive and must not contain the trailing column (':').
	- Match: The text value in this element should be a regular expression (basic, not extended) and is matched against the value of the header from the 'Header' element. Matching is case insensitive.
	- Action: States what Synonym will do if all the conditions of the 'Rule' section matched. An action must contain exactly one 'ActionType' element. In some cases, an 'Address' element must also be added in the 'Action' section. 
	- ActionType : only one element of this kind may be defined per 'Action' section. The text specifies which action should be taken if all the conditions in the rule matched. The following action may currently be defined: 
		- 'Copy' : adds the recipient defined in the 'Address' element. No recipient headers will be added
		- 'Delete' : silently discard the email
		- 'Reject' : bounce the email, the text value on the 'Address' element is used as the SMTP error reply. The SMTP result code given is 550 (extended 5.7.1)
		- 'Disclaimer' : not implemented yet - ignored
	- Address: if the ActionType is 'Copy', this element contains the email address to add as recipient (no recipient headers will be added); if the 'ActionType' element is 'Reject', the 'Address' element defines the string that is returned as SMTP error

	Following is a config file example:

	-- cut here - begin --
	<Rules>
		<Rule>
			<Condition>
				<Header>Subject</Header>
				<Match>money</Match>
			</Condition>
			<Condition>
				<Header>Subject</Header>
				<Match>business</Match>
			</Condition>
			<Action>
				<ActionType>Copy</ActionType>
				<Address>copy@somewhere.com</Address>
			</Action>
		</Rule>
		<Rule>
			<Condition>
				<Header>From</Header>
				<Match>spammer@.*\.com</Match>
			</Condition>
			<Action>
				<ActionType>Reject</ActionType>
				<Address>We do not accept emails from spammers</Address>
			</Action>
		</Rule>
		<Rule>
			<Condition>
				<Header>Subject</Header>
				<Match>dropme</Match>
			</Condition>
			<Action>
				<ActionType>Delete</ActionType>
				<Address></Address>
			</Action>
		</Rule>
	</Rules>
	-- cut here - end --

3. Running Synonym

3.1 Starting the daemon
	Synonym may be started directly (via the binary) or by using the startup script (we provide scripts for Linux and FreeBSD). Please make sure you are running Synonym as superuser(root). Synoynm will drop privileges to the configured user (see the configuration section) before starting the operations.

3.1.1 Starting synonym directly
	# /usr/local/sbin/synonym -d
	Synonym will register as a milter and then fork to background.

3.1.2 Starting synoynm using the startup script
	On Linux, use:

	# service synonym start

	This will start Synonym as a daemon. This script may also be used to stop synonym or to restart it (see the usage of the SYSV init scripts).

3.2 Stopping the daemon
	To stop Synonym on Linux if the script is used:

	# service synonym stop

	Once Synonym is stopped, message copying is stopped. Restarting sendmail is not required. However, if you wish to stop using synonym, you should also remove the configuration lines added to sendmail.mc, recompile sendmail.cf and restart sendmail.
	If you wish to stop synonym and do not want to use the script (or you are using an environment for which a script was not provided), please use:

	# kill `cat /var/run/synoynm/synonym.pid`

	Synonym will take a few seconds (up to 6) to stop due to the milter libraries.

3.3 Command line parameters
	Synoynm provides a couple of options having default values (hence may be omitted). Following is a description of each of the accepted parameters
	-s <socket name> 	The socket used by Synonym to communicate with sendmail. Default: "local:/var/run/synonym/synonym.sock" 
				By this parameter the administrator can change the socket location (if desired) or even configure Synonym to run on a different machine. Please check the Milter documentation for more details.
	-c <config file>	The name of the configuration file. Default: /etc/synonym.conf
	-u <username>		Synonym will run as the user (and promary group of the user) specified here. The privileges will be dropped right after the configuration is loaded. Default: mail
				Please note that this user must have read-write access to the run-time directory (/var/run/synonym/).
	-l <log level>		The max log-level that will reach the logging system. Messages with a log level higher then this will not be logged. Default: LOG_ERR
				The following values may be used (in order): LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO and LOG_DEBUG.
				Please note that using a level higher then LOG_WARNING in a heavily loaded environment may overflow the log. 
	-f <log facility>	The facility that will be used by Synonym when 'syslogging' the log messages (check the syslog manpage for more information on 'facility'). Default: LOG_MAIL
				The following values may be used: LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7, LOG_DAEMON, LOG_MAIL and LOG_USER.
	-d			Run synonym as daemon (fork into background). Default is for Synonym to stay attached to the console.
	-h			Display a help message (a summary of the options described here).

4. Uninstalling Synonym
	To uninstall synonym you'll have to stop the daemon (3.2) and remove the binary, the configuration file, the runtime directory and the documentation (i.e. this readme, in /usr/share/doc). Also, please remove the configuration lines added to sendmail.mc, recompile sendmail.cf and restart it.
	Please note that the location of various files may be different depending on the platform.

4.1 Removing the Milter extension
	Edit your sendmail.mc file and delete the following two lines:

	define(`_FFR_MILTER', `true')
	INPUT_MAIL_FILTER(`Synonym', `S=local:/var/run/synonym/synonym.sock, T=C:10m;S:1s;R:1s;E:5m')

	Regenerate the sendmail.cf:
	# m4 < sendmail.mc > sendmail.cf
	
	Restart Sendmail

4.2 Removing the binary
	# rm /usr/local/sbin/synonym
4.3 Removing the run-time directory
	# rm -rf /var/run/synonym
4.4 Removing the control script
	# rm /etc/rc.d/init.d/synonym
4.5 Removing the documentation
	# rm -rf /usr/share/doc/synonym
4.6 Removing the sources
	Remove the directory used to unpack Synonym and the .tar.gz archive.

5. Notes for FreeBSD users (thanks to Stephane Lentz for contributing)
The GNU Make utility (gmake) should be used for compiling Synonym instead of the default make tool. The Makefile is only compatible with gmake.
FreeBSD does not include by default the sendmail development headers and libraries so they should be available (installing the 'sendmail' package should be enough).
The startup script is invoked from /usr/local/etc/rc.d/synonym.sh
Synonym runs by default as user 'daemon' group 'daemon'. If changing this is desired, please check the 'Configure Synonym' section.
The libxml2 development library must be installed in order for Synonym to be able to properly compile. This library is usually included on the FreeBSD distribution CDs but not installed by default.

6. Notes for Solaris users
The GNU Make utility (gmake) should be used for compiling Synonym instead of the default make tool. The Makefile is only com
patible with gmake.
Sendmail development package must be installed (at least the milter headers and library). Please make sure the sendmail headers are located in /usr/local/include/libmilter, otherwise change the Makefile to reflect the location of these headers.
Synonym will run as user 'daemon' group 'daemon' on Solaris. This may be changed via the startup script (synonym.sh).
Make sure that the libxml2 and libiconv libraries are installed prior to compilind Synonym on Solaris. These can be obrained as packages from http://www.sunfreeware.com.

7. Licensing
Synonym is licensed under the Modulo Consulting Software License.
See the License file that was bundled along with Synonym's source.

