bump standards version; extra is now optional
[deb_pkgs/spamass-milter.git] / 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