spamass-milter.1.in

   1 .\" $Id: spamass-milter.1.in,v 1.21 2014/08/15 02:25:31 kovert Exp $
   2 .Dd July 25, 2001
   3 .Os
   4 .Dt SPAMASS_MILTER 8
   5 .Sh NAME
   6 .Nm spamass-milter
   7 .Nd sendmail milter for passing emails through SpamAssassin
   8 .Sh SYNOPSIS
   9 .Nm
  10 .Fl p Ar socket
  11 .Op Fl b Ns | Ns Fl B Ar spamaddress
  12 .Op Fl C rejectcode
  13 .Op Fl d Ar debugflags
  14 .Op Fl D Ar host
  15 .Op Fl e Ar defaultdomain
  16 .Op Fl f
  17 .Op Fl i Ar networks
  18 .Op Fl m
  19 .Op Fl M
  20 .Op Fl P Ar pidfile
  21 .Op Fl r Ar nn
  22 .Op Fl r rejectmsg
  23 .Op Fl u Ar defaultuser
  24 .Op Fl x
  25 .Op Fl S /path/to/sendmail
  26 .Op Fl - Ar spamc flags ...
  27 .Sh DESCRIPTION
  28 The
  29 .Nm
  30 utility is a sendmail milter that checks and modifies incoming email
  31 messages with SpamAssassin.
  32 .Pp
  33 The following options are available:
  34 .Bl -tag -width "indent"
  35 .It Fl p Ar socket
  36 Specifies the pathname of a socket to create for communication with
  37 .Nm sendmail .
  38 If it is removed,
  39 .Nm sendmail
  40 will not be able to access the milter.
  41 This may cause messages to bounce, queue, or be passed through
  42 unmiltered, depending on the parameters in
  43 .Nm sendmail Ns 's .cf file.
  44 .It Fl b Ar spamaddress
  45 Redirects tagged spam to the specified email address.
  46 All envelope recipients are removed, and inserted into the message as
  47 .Ql X-Spam-Orig-To:
  48 headers.
  49 .It Fl B Ar spamaddress
  50 Same as
  51 .Fl b ,
  52 except the original recipients are retained.
  53 Only one of
  54 .Fl b
  55 and
  56 .Fl B
  57 may be used.
  58 .It Fl C Ar rejectcode
  59 Mail that is rejected is rejected by default with a 5.7.1 code.  This option
  60 allows that to be overridden.  See also, -R
  61 .Fl S
  62 option.
  63 .It Fl d Ar debugflags
  64 Enables logging.
  65 .Ar debugflags
  66 is a comma-separated list of tokens:
  67 .Bl -tag -width "indent"
  68 .It func
  69 Entry and exit of internal functions.
  70 .It misc
  71 Other non-verbose logging.
  72 .It net
  73 Lookups of the ignored netblocks list.
  74 .It poll
  75 Low-level I/O to the child spamc process.
  76 .It rcpt
  77 Recipient processing.
  78 .It spamc
  79 High-level I/O to the child spamc process.
  80 .It str
  81 Calls to field lookup and string comparison functions.
  82 .It uori
  83 Calls to the update_or_insert function.
  84 .It 1
  85 (historical) Same as
  86 .Ar func,misc .
  87 .It 2
  88 (historical) Same as
  89 .Ar func,misc,poll .
  90 .It 3
  91 (historical) Same as
  92 .Ar func,misc,poll,str,uori .
  93 .El
  94 .It Fl D Ar host
  95 Connects to a remote spamd server on
  96 .Ar host ,
  97 instead of using one on localhost.
  98 This option is deprecated; use
  99 .Fl - Fl d Ar host
 100 instead.
 101 .It Fl e Ar defaultdomain
 102 Pass the full user@domain address to spamc.
 103 The default is to pass only the username part on the assumption that
 104 all users are local.
 105 This flag is useful if you are using an SQL (or other username) backend
 106 with spamassassin and have listed the full address there.
 107 If the recipient name has no domain part (if the recipient is on the
 108 local machine for example),
 109 .Ar defaultdomain
 110 is added.
 111 Requires the
 112 .Fl u
 113 flag.
 114 .It Fl f
 115 Causes
 116 .Nm
 117 to fork into the background.
 118 .It Fl i Ar networks
 119 Ignores messages if the originating IP is in the network(s) listed.
 120 The message will be passed through without calling SpamAssassin at all.
 121 .Ar networks
 122 is a comma-separated list, where each element can be either an IP address
 123 (nnn.nnn.nnn.nnn), a CIDR network (nnn.nnn.nnn.nnn/nn), or a network/netmask
 124 pair (nnn.nnn.nnn.nnn/nnn.nnn.nnn.nnn).
 125 Multiple
 126 .Fl i
 127 flags will append to the list.
 128 For example, if you list all your internal networks, no outgoing emails
 129 will be filtered.
 130 .It Fl m
 131 Disables modification of the
 132 .Ql Subject:
 133 and
 134 .Ql Content-Type:
 135 headers and
 136 message body.
 137 This is useful when SpamAssassin is configured with
 138 .Ql "defang_mime 0"
 139 and
 140 .Ql "report_header 1" ,
 141 or when SA is simply used to add headers for postprocessing later.
 142 Updating the body through the milter interface can be slow for large
 143 messages.
 144 .It Fl M
 145 Like
 146 .Fl m ,
 147 but also disables creation of any SpamAssassin
 148 .Ql X-Spam-*
 149 headers as well.
 150 Both tagged and untagged mail gets passed through unchanged.
 151 To be useful, this option should be used with the
 152 .Fl r ,
 153 .Fl b ,
 154 or
 155 .Fl B
 156 flags.
 157 If
 158 .Fl b
 159 is used, the
 160 .Ql X-Spam-Orig-To:
 161 headers will still be added.
 162 .It Fl P Ar pidfile
 163 Create the file
 164 .Ar pidfile ,
 165 containing the processid of the milter.
 166 .It Fl r Ar nn
 167 Reject scanned email if it greater than or equal to
 168 .Ar nn .
 169 If
 170 .Ar -1 ,
 171 reject scanned email if SpamAssassin tags it as spam (useful if you
 172 are also using the
 173 .Fl u
 174 flag, and users have changed their required_hits value).
 175 .Pp
 176 For example, if you usually use procmail to redirect tagged email into
 177 a separate folder just in case of false positives, you can use
 178 .Fl r Ar 15
 179 and reject flagrant spam outright while still receiving low-scoring
 180 messages.
 181 .It Fl R Ar rejecttext
 182 Mail that is rejected is rejected with the message "Blocked by SpamAssassin".
 183 This option allows the user to call with a different message, instead.   See
 184 also, the
 185 .Fl C
 186 option
 187 .It Fl S Ar /path/to/sendmail
 188 This option is used in conjunction with the -x option to specify a path
 189 to sendmail if the default compiled in choice is not satisfactory.
 190 .It Fl u Ar defaultuser
 191 Pass the username part of the first recipient to spamc with the
 192 .Fl u
 193 flag.
 194 This allows user preferences files to be used.
 195 If the message is addressed to multiple recipients, the username
 196 .Ar defaultuser
 197 is passed instead.
 198 .Pp
 199 Note that
 200 .Nm
 201 does not know whether an email is incoming or outgoing, so a message
 202 from
 203 .Aq user1@localdomain.com
 204 to
 205 .Aq user2@yahoo.com
 206 will make
 207 .Nm
 208 pass
 209 .Fl u Ar user2
 210 to spamc.
 211 .It Fl x
 212 Pass the recipient address through
 213 .Nm sendmail Fl bv ,
 214 which will perform virtusertable and alias expansion.
 215 The resulting username is then passed to spamc.
 216 Requires the
 217 .Fl u
 218 flag.  The spamass-milter configuration process does its
 219 best to find sendmail, but it is possible to override this compiled-in
 220 setting via the
 221 .It Fl - Ar spamc flags ...
 222 Pass all remaining options to spamc.
 223 This allows you to connect to a remote spamd with
 224 .Fl d
 225 or
 226 .Fl p .
 227 .El
 228 .Sh FILES
 229 .Bl -tag -width "indent"
 230 .It Pa @SPAMC@
 231 client interface to SpamAssassin
 232 .El
 233 .Sh SEE ALSO
 234 .Xr spamassassin 1 ,
 235 .Xr spamd 1
 236 .Sh AUTHORS
 237 .An "Georg C. F. Greve" Aq greve@gnu.org
 238 .An "Dan Nelson" Aq dnelson@allantgroup.com
 239 .An "Todd Kover" Aq kovert@omniscient.com