.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "asmtpd 8" .TH asmtpd 8 "2013-07-13" "Mail Avenger 0.8.4" "Mail Avenger 0.8.4" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" asmtpd \- Avenger SMTP Daemon .SH "SYNOPSIS" .IX Header "SYNOPSIS" asmtpd [\-d] [\-\-verbose] [\-f \fIconfig-file\fR] .PP asmtpd [\-\-spf] [\-f \fIconfig-file\fR] .PP asmtpd [\-\-rbl] [\-f \fIconfig-file\fR] .PP asmtpd [\-\-avenge] [\-f \fIconfig-file\fR] \fIrecipient\fR [\fIsender\fR [\fIIP-address\fR]] .PP asmtpd [\-\-synfp] [\fItcp-port\fR [\fIIP-address\fR [\fIinterface\fR ...]]] .PP asmtpd [\-\-netpath] \fIIP-address\fR [\fInetwork-hops\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIasmtpd\fR is the central server daemon for Mail Avanger. Mail Avenger is a highly-configurable MTA-independent \s-1SMTP \s0(Simple Mail Transport Protocol) server designed to let you filter and fight \s-1SPAM \s0\fIbefore\fR accepting incoming mail from a client machine. Filtering spam before accepting a message from a remote machine offers a number of benefits. First, while mail is in the process of being sent over the network, more information is available about the client machine, allowing the possibility of more accurate decisions about spam. (For example, machines infected with viruses may be able to be detected by probing.) .PP Second, filtering during mail transfer allows more options for what to do with potential spam. For instance, one can defer the mail\*(--essentially asking the client to send it again later\*(--which legitimate mail clients will do automatically, but \*(L"spam 'bots\*(R" typically won't. Moreover, it is much safer to reject spam before accepting a message. With typical after-delivery spam checkers, the only options are to discard spam silently (risking false positives that completely disappear), or to notify the sender, but if the sender is forged, this causes more unwanted mail. By rejecting mail during an \s-1SMTP\s0 transaction, this ensures legitimate mail gets bounced to the sender, while most spam will simply disappear. .PP Finally, filtering during an \s-1SMTP\s0 transaction saves resources, since spam messages need never to be spooled in the mail queue. .PP There are many ways of fighting and detecting spam. Though Mail Avenger has a few basic mechanisms built-in, the philosophy of the system is to let system administrators and individual users plug in their own filtering criteria. The intent is for Mail Avenger to do the hard part\*(--talk the \s-1SMTP\s0 network protocol, handle asynchronous \s-1DNS\s0 resolution, \s-1SPF\s0 rule checking, probing of remote \s-1SMTP\s0 servers for legitimacy, etc.\-\-while users can set policy through configuration files with simple shell commands. .PP The basic approach is for users to create scripts in a directory called \fI\f(CI$HOME\fI/.avenger\fR that specify policies for what mail to accept and what to reject or defer. System-wide fallback policies can also be specified by files in \fI/etc/avenger/\fR. The program that executes these scripts is called \fIavenger\fR, and is described more fully in its own manual page. .PP asmtpd can be configured to map different email addresses and domains to different local users, in addition to a large number of other configurable features. These are described more fully in the \&\fIasmtpd.conf\fR\|(5) manual page. .PP asmtpd also adds a new header field to messages, \f(CW\*(C`X\-Avenger:\*(C'\fR, containing information that may be of use to spam filters. \&\f(CW\*(C`X\-Avenger:\*(C'\fR contains a list of semi-colon-separated tokens, which if present mean the following: .IP "\fBversion=\fR\fInumber\fR" 4 .IX Item "version=number" Specifies the version of Mail Avenger that received the message. .IP "\fBreceiver=\fR\fIhostname\fR" 4 .IX Item "receiver=hostname" Specifies that asmtpd was running on \fIhostname\fR when it received the message. .IP "\fBclient\-ip=\fR\fIIP-address\fR" 4 .IX Item "client-ip=IP-address" .PD 0 .IP "\fBclient\-port=\fR\fIport-number\fR" 4 .IX Item "client-port=port-number" .PD These specify that the client end of the \s-1TCP\s0 connection from which the mail came used \s-1IP\s0 address \fIIP-address\fR and port \fIport-number\fR. .IP "\fBclient\-dnsfail=\fR\fIerror\fR" 4 .IX Item "client-dnsfail=error" Specifies that a reverse lookup on the client's \s-1IP\s0 address (to determine the client's hostname) resulted in \fIerror\fR. .IP "\fBbounce\-res=\fR\fIcode\fR" 4 .IX Item "bounce-res=code" Specifies that attempts to send bounces to the bounce address of the sender result in \s-1SMTP\s0 error \fIcode\fR. (This is the same value as the \&\fB\s-1SENDER_BOUNCERES\s0\fR environment variable described in the \&\fIavenger\fR\|(1) manual page.) .IP "\fBsyn\-fingerprint=\fR\fIfingerprint\fR" 4 .IX Item "syn-fingerprint=fingerprint" Contains a description of the initial \s-1TCP SYN\s0 packet used by the client to initiate the \s-1TCP\s0 connection over which the mail was sent. See the description of \fB\s-1CLIENT_SYNFP\s0\fR in the \fIavenger\fR\|(1) manual page for an explanation of the format. .IP "\fBcolon-space\fR" 4 .IX Item "colon-space" If present, means the client included a space between the colon in the command \*(L"\s-1MAIL FROM:\*(R"\s0 or \*(L"\s-1RCPT TO:\*(R"\s0 and the subsequent \*(L"<\*(R" that begins an email address. .IP "\fBeager-pipelining\fR" 4 .IX Item "eager-pipelining" If present, means that the client attempted to pipeline \s-1SMTP\s0 commands before receiving the \f(CW\*(C`250 PIPELINING\*(C'\fR response to the \s-1SMTP \s0\f(CW\*(C`HELO\*(C'\fR or \&\f(CW\*(C`EHLO\*(C'\fR command. This field has the same meaning as the \&\fB\s-1CLIENT_PIPELINING\s0\fR environment variable in \fIavenger\fR\|(1). .IP "\fBpost\fR" 4 .IX Item "post" If present, means the client issued the invalid \s-1SMTP\s0 command \fB\s-1POST\s0\fR. See \fB\s-1CLIENT_POST\s0\fR in \fIavenger\fR\|(1). .IP "\fBnetwork\-hops=\fR\fInhops\fR" 4 .IX Item "network-hops=nhops" This is the number of network hops from the server to the client that sent this mail (if Mail Avenger can figure this out). See \&\fB\s-1CLIENT_NETHOPS\s0\fR in \fIavenger\fR\|(1). .IP "\fBnetwork\-path=\fR\fIIP-list\fR" 4 .IX Item "network-path=IP-list" Set to a space-separated list of as many intermediary network hops as Mail Avenger can efficiently discover on the way from the server to the client that send the mail. See \fB\s-1CLIENT_NETHOPS\s0\fR in \&\fIavenger\fR\|(1). .IP "\fBnetwork\-path\-time=\fR\fItime\fR" 4 .IX Item "network-path-time=time" To save network traffic, Mail Avenger briefly caches routes to a particular client. \fBnetwork-path-time\fR specifies the precise time at which the information in \fBnetwork-path\fR was discovered. The time is expressed as a standard Unix time (number of seconds since Jan 1, 1970). .IP "\fBRBL=\fR\fIdomain (IP-addrs)\fR\fB[,\fR \fIdomain (IP-addrs)\fR\fB, ...]\fR" 4 .IX Item "RBL=domain (IP-addrs)[, domain (IP-addrs), ...]" For the each real-time blackhole list (\s-1RBL\s0) domain specified in \&\fIasmtpd.conf\fR (see the \fB\s-1RBL\s0\fR directive in the \&\fIasmtpd.conf\fR\|(5) man page), if the client shows up in the \s-1RBL, \s0\fIIP-addrs\fR specifies what the \s-1RBL\s0 returns. .Sp Usually, RBLs just return 127.0.0.1 to specify that a client is present in the blacklist. However, some services use different \s-1IP\s0 addresses to encode some information about why the client is listed. If an \s-1RBL\s0 returns multiple \s-1IP\s0 addresses, asmtpd includes them all, separated by spaces. .IP "\fBRBL\-errors=\fR\fIdomain\fR \fB(\fR\fIerror\fR\fB)[,\fR \fIdomain\fR \fB(\fR\fIerror\fR\fB), ...]\fR" 4 .IX Item "RBL-errors=domain (error)[, domain (error), ...]" Lists any \s-1RBL\s0 domains Mail Avenger was unable to query at the time of receipt of the message. .SS "\s-1GETTING STARTED\s0" .IX Subsection "GETTING STARTED" The following is a brief description of how to get started with asmtpd. More information is available in the installation guide \&\fI/usr/local/share/avenger/INSTALL\fR, as well as the \&\fIasmtpd.conf\fR\|(5) and \fIavenger\fR\|(1) manual pages. .IP "\(bu" 4 If you haven't already, create a user called \fIavenger\fR on your system. This is the user \s-1ID\s0 under which system-wide avenger scripts will run. (If you wish to use a name other than \*(L"avenger\*(R", you can put the directive "\fBAvengerUser\fR \fIuser\fR" in the asmtpd.conf configuration file when you create that.) .IP "\(bu" 4 Create the directory \fI/etc/avenger\fR. .IP "\(bu" 4 Create a file \fI/etc/avenger/asmtpd.conf\fR. Copy the sample file in \&\fI/usr/local/share/avenger/asmtpd.conf\fR and edit to taste. .IP "\(bu" 4 Create a file \fI/etc/avenger/domains\fR. List each domain for which you would like to receive mail, followed by a colon, one per line. For example: .Sp .Vb 2 \& my.first.domain: \& my.second.domain: .Ve .IP "\(bu" 4 Fire it up! Run the command \*(L"asmtpd\*(R" as root. You may also want to set things up to run this command automatically on system startup. .IP "\(bu" 4 Play with scripts. Read the man page for \fIavenger\fR\|(1), create a \fI.avenger/rcpt\fR file in your home directory, and maybe create a site-wide default file \fI/etc/avenger/default\fR. You will also very likely want to create a script \fI/etc/avenger/unknown\fR to reject mail to unknown users. See the man page for \fIaliascheck\fR\|(1) and the sample \fI/usr/local/share/avenger/unknown\fR for an example of how to do this. .IP "\(bu" 4 Finally, you may want to try the avenger.local delivery agent. See the \fIavenger.local\fR\|(8) man page for more information. .SS "\s-1OPTIONS\s0" .IX Subsection "OPTIONS" Normally, when started, asmtpd runs as a daemon, sends its output to the system log, and looks for its configuration file in \&\fI/etc/avenger/asmtpd.conf\fR. The following options change this behavior: .IP "\fB\-d\fR" 4 .IX Item "-d" Tells asmtpd to stay in the foreground and send its diagnostic messages to standard error, rather than to the system log. .IP "\fB\-\-verbose\fR" 4 .IX Item "--verbose" Ordinarily, asmtpd will attempt to avoid sending overly many duplicate copies of a message to the system log file. The \fB\-\-verbose\fR option changes this behavior, so that certain error conditions (such as missing directories) get reported each time they affect a piece of mail. .IP "\fB\-f\fR \fIconfig-file\fR" 4 .IX Item "-f config-file" Specifies an alternate location for the configuration file. .PP In addition, several other options are available to run asmtpd in various test modes, for making use of or debugging features. .IP "\fB\-\-spf\fR [\fB\-f\fR \fIconfig-file\fR]" 4 .IX Item "--spf [-f config-file]" Runs in a mode where asmtpd simply performs \s-1SPF\s0 tests on pairs it reads from standard input. Can be used to validate asmtpd's \s-1SPF\s0 implementation against a different implementation, or to debug \s-1SPF\s0 records (particularly in conjunction with the \fB\s-1SPF_TRACE\s0\fR environment variable discussed below). .IP "\fB\-\-rbl\fR [\fB\-f\fR \fIconfig-file\fR]" 4 .IX Item "--rbl [-f config-file]" Tests asmtpd's \s-1RBL \s0(realtime black hole) list implementation. The configuration file should contain one or more \fB\s-1RBL\s0\fR directives (see the manual page for \fIasmtpd.conf\fR\|(5)). In this mode, asmtpd will simply read \s-1IP\s0 addresses from its input and output the result of \s-1RBL\s0 checks. .IP "\fB\-\-avenge\fR [\fB\-f\fR \fIconfig-file\fR] \fIrecipient\fR [\fIsender\fR [\fIIP-address\fR]]" 4 .IX Item "--avenge [-f config-file] recipient [sender [IP-address]]" Tests the avenger script for \fIrecipient\fR, which must be a fully-qualified email address with a domain. This simulates an \s-1SMTP\s0 transaction in which client \fIIP-address\fR tries to send mail from \&\fIsender\fR to \fIrecipient\fR. If \fIrecipient\fR is not specified, it defaults to \fBpostmaster@HostName\fR (where \fBHostname\fR is the local hostname, as specified in \fIasmtpd.conf\fR). If is not specified, the local address is used. .Sp With this option, asmtpd will log a transcript of avenger's requests to standard error, regardless of the actual \fBDebugAvenger\fR setting. At the end, outputs the \s-1SMTP\s0 response asmtpd would give to the \f(CW\*(C`RCPT\*(C'\fR command. .IP "\fB\-\-synfp\fR [\fItcp-port\fR [\fIIP-address\fR [\fIinterface\fR ...]]]" 4 .IX Item "--synfp [tcp-port [IP-address [interface ...]]]" Tests asmtpd's \s-1SYN\s0 fingerprinting implementation. Listens to the network and for each incoming \s-1TCP\s0 connection, prints the \s-1IP\s0 address and port of the client, along with a fingerprint describing the characteristics of the initial \s-1SYN\s0 packet from the \s-1TCP\s0 connection. (For a description of the \s-1SYN\s0 fingerprint format, see the description of \fB\s-1CLIENT_SYNFP\s0\fR in the man page for \fIavenger\fR\|(1).) .Sp By default, asmtpd will print the fingerprints of any incoming \s-1TCP\s0 connection. If \fItcp-port\fR is non-zero, however, asmtpd will only consider \s-1SYN\s0 packets sent to that \s-1TCP\s0 port number. If \fIIP-address\fR is supplied and is not 0.0.0.0, asmtpd will only took at \s-1TCP\s0 packets for that particular \s-1IP\s0 address (useful if your local machine has multiple \s-1IP\s0 addresses). Finally, by default asmtpd will listen to whatever network interfaces correspond to \fIIP-address\fR (or all active non-loopback interfaces for 0.0.0.0 or unspecified). You can alternatively specify explicitly which network interfaces asmtpd should listen on (e.g., \*(L"eth0 eth1\*(R"). .Sp To use this option, you must be root (or at least have permission to open the \fI/dev/bpf*\fR packet filter devices on your machine). .IP "\fB\-\-netpath\fR \fIIP-address\fR [\fInetwork-hops\fR]" 4 .IX Item "--netpath IP-address [network-hops]" asmtpd records the network path to mail clients using a technique similar to the \fBtraceroute\fR utility found on many operating systems. The \fB\-\-netpath\fR option tests asmtpd's implementation of this functionality. If \fInetwork-hops\fR is positive, asmtpd will record only the first \fInetwork-hops\fR hops on the way to \fIIP-address\fR. If \&\fInetwork-hops\fR is negative, asmtpd will output only the last \&\fInetwork-hops\fR hops on the way to \fIIP-address\fR. If \fInetwork-hops\fR is zero, or is not supplied, asmtpd will output the entire route (or as much as it can discover, firewall permitting). .Sp To use this option, you must run asmtpd as root for it to use raw sockets. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" .IP "\fB\s-1SPF_TRACE\s0\fR" 4 .IX Item "SPF_TRACE" When set to a positive integer, causes asmtpd to send to standard error a trace of the checks it is performing while processing \s-1SPF\s0 records. If set to 1, simply records which \s-1SPF\s0 traces are happening. Setting it to 2 provides more information, while setting it to 3 provides a complete trace. (Setting the value to 4 or higher additionally causes asmtpd to send the results of all SPF-related \s-1DNS\s0 queries to its standard output, a feature mostly useful to the implementor.) .IP "\fB\s-1TMPDIR\s0\fR" 4 .IX Item "TMPDIR" asmtpd creates temporary files to hold incoming mail messages before injecting them into the mail system. It usually creates a temporary subdirectory of \fI/var/tmp\fR to hold these files (and cleans up the directory on exit). If \fB\s-1TMPDIR\s0\fR is set, its value will be used in place of \fI/var/tmp\fR. .SH "FILES" .IX Header "FILES" \&\fI/etc/avenger/asmtpd.conf\fR, \&\fI/etc/avenger/domains\fR, \&\fI/etc/avenger/aliases\fR, \&\fI/etc/avenger/unknown\fR, \&\fI/etc/avenger/default\fR, \&\fI\f(CI$HOME\fI/.avenger/rcpt*\fR \&\fI/usr/local/share/avenger/*\fR .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIasmtpd.conf\fR\|(5), \&\fIavenger\fR\|(1) .PP The Mail Avenger home page: . .SH "BUGS" .IX Header "BUGS" If the packet capture library (libpcap) header files were not available at compile time, asmtpd will not support \s-1TCP SYN\s0 fingerprints and the \fB\-\-synfp\fR option will not be available. You may be able to fix this by installing a package for your \s-1OS\s0 called pcap, libpcap, or libpcap-devel (depending on the distribution), then re-running ./configure and re-compiling Mail Avenger. .SH "AUTHOR" .IX Header "AUTHOR" David Mazie\*`res