sys/man/1/filter

   1 .TH FILTER 1
   2 .SH NAME
   3 filter, list, deliver, token, vf \-  filtering mail
   4 .SH SYNOPSIS
   5 .B upas/filter
   6 [
   7 .B -bh
   8 ]
   9 .I rcvr
  10 .I mailbox
  11 [
  12 .I "regexp file
  13 ] ...
  14 .PP
  15 .B upas/list
  16 [
  17 .B -d
  18 ]
  19 .B add|check
  20 .I patternfile
  21 .I addressfile ...
  22 .PP
  23 .B upas/deliver
  24 .I recipient
  25 .I fromfile
  26 .I mbox
  27 .PP
  28 .B upas/token
  29 .I key
  30 [
  31 .I tokenfile
  32 ]
  33 .PP
  34 .B upas/vf
  35 [
  36 .B -r
  37 ]
  38 [
  39 .B -s
  40 .I savefile
  41 ]
  42 .SH DESCRIPTION
  43 A user may filter all incoming mail by creating
  44 a world readable/executable file
  45 .BI /mail/box/ username /pipeto.
  46 If the file is a shell script, it can use the
  47 commands described here to implement a filter.
  48 .PP
  49 .I Filter
  50 provides simple mail filtering.
  51 The first two arguments are the recipient's address and mailbox, that is,
  52 the same arguments provided to
  53 .BR pipeto .
  54 The remaining arguments are all pairs of a regular expression and a file name.
  55 With no flags, the sender's address is matched against each
  56 regular expression starting with the first.  If the expression
  57 matches, then the message is delivered to the file whose name
  58 follows the expression.  The file must be world writable and should
  59 be append only.
  60 A message that matches none of the expressions is delivered into
  61 the user's standard mail box.
  62 .PP
  63 By default,
  64 .I filter
  65 matches each regular expression against the message's sender.
  66 The
  67 .B -h
  68 flag causes
  69 .I filter
  70 to match against the entire header,
  71 and the
  72 .B -b
  73 flag causes
  74 .I filter
  75 to match against the entire message (header and body).
  76 .PP
  77 For example, to delete any messages of precedence bulk, place in
  78 your
  79 .B pipeto
  80 file:
  81 .IP
  82 .EX
  83 /bin/upas/filter -h $1 $2 'Precedence: bulk' /dev/null
  84 .EE
  85 .PP
  86 Three other commands exist which, combined by an
  87 .IR rc (1)
  88 script, allow you to build your own filter.
  89 .PP
  90 .I List
  91 takes two verbs;
  92 .B check
  93 and
  94 .BR add .
  95 .B Check
  96 directs
  97 .I list
  98 to check each address contained in the
  99 .IR addressfile s
 100 against a list of patterns in
 101 .IR patternfile .
 102 Patterns come in four forms:
 103 .TF ~\fIregular-expression\fP
 104 .PD
 105 .TP
 106 .B ~\fIregular-expression\fP
 107 If any address matches the regular expression,
 108 .I list
 109 returns successfully.
 110 .TP
 111 .BR =\fIstring\fP .
 112 If any address exactly matches
 113 .IR string ,
 114 .I list
 115 returns successfully.
 116 .TP
 117 .B !~\fIregular-expression\fP
 118 If any address matches the regular expression
 119 and no other address matches a non `!' rule,
 120 .I list
 121 returns error status "!match".
 122 .TP
 123 .B !=\fIstring\fP
 124 If any address exactly matches
 125 .I string
 126 and no other address matches a non `!' rule,
 127 .I list
 128 returns error status "!match".
 129 .PP
 130 If no addresses match a pattern,
 131 .I list
 132 returns "no match".
 133 .PP
 134 The pattern file may also contain lines of the form
 135 .IP
 136 .EX
 137 #include filename
 138 .EE
 139 .LP
 140 to allow pattern files to include other pattern files.
 141 All pattern matches are case insensitive.
 142 .I List
 143 searches the pattern file (and its includes) in order.
 144 The first matching pattern determines the action.
 145 .PP
 146 .I List
 147 .B add
 148 directs
 149 .I list
 150 to add a pattern to
 151 .I patternfile
 152 for each address in the
 153 .I addressfiles
 154 that doesn't already match a pattern.
 155 .PP
 156 .IR Token ,
 157 with only one argument, prints to standard output a unique token
 158 created from the current date and
 159 .IR key .
 160 With two arguments, it checks
 161 .I token
 162 against tokens created over the last 10 days with
 163 .IR key .
 164 If a match is found, it returns successfully.
 165 .PP
 166 .I Deliver
 167 delivers into mail box
 168 .I mbox
 169 the message read from standard input.
 170 It obeys standard mail file locking and logging
 171 conventions.
 172 .PP
 173 .B /sys/src/cmd/upas/filterkit/pipeto.sample
 174 is a sample
 175 .B pipeto
 176 using the filter kit.
 177 .PP
 178 A sample
 179 .BR pipefrom ,
 180 .BR /sys/src/cmd/upas/filterkit/pipefrom.sample ,
 181 is provided which adds all addresses of your outgoing
 182 mail to your pattern file.
 183 You should copy it into a directory that normally gets
 184 bound by your profile onto
 185 .BR /bin .
 186 .PP
 187 .I Vf
 188 (virus filter)
 189 takes a mail message as standard input
 190 and searches for executable MIME attachments,
 191 either rewriting them to be non-executable or
 192 rejecting the message.
 193 The behavior depends on the attachment's file name
 194 extension and MIME content type.
 195 .B /sys/lib/mimetype
 196 contains the list of known extensions and MIME content types.
 197 The fifth field of each line specifies the
 198 safety of a particular file type:
 199 .B y
 200 (yes),
 201 .B m
 202 (maybe; treated same as yes),
 203 .B n
 204 (no),
 205 .B p
 206 (previous),
 207 or
 208 .B r
 209 (reject).
 210 .I Vf
 211 allows attachments with safety
 212 .B y
 213 or
 214 .B m
 215 to pass through unaltered.
 216 Attachments with safety
 217 .B n
 218 both are wrapped in extra MIME headers
 219 and have
 220 .B .suspect
 221 appended to their file names, to avoid
 222 automatic execution by mail readers.
 223 Attachments with safety
 224 .B r
 225 (currently,
 226 .BR .bat ,
 227 .BR .com ,
 228 .BR .exe ,
 229 and
 230 .BR .scr ,
 231 all Microsoft executable extensions)
 232 are taken as
 233 cause for the entire message to be rejected.
 234 A safety of
 235 .B p
 236 (used for the
 237 .B x-gunzip
 238 mime type)
 239 causes the previous extension to be tested,
 240 so that
 241 .B x.tar.gz
 242 is treated the same as
 243 .BR x.tar .
 244 .PP
 245 If
 246 .B /mail/lib/validateattachment
 247 exists and is executable,
 248 .B vf
 249 runs it on all attachments with safety
 250 .B n
 251 (attachments it would normally sanitize).
 252 If
 253 .IR validateattachment 's
 254 exit status contains the string
 255 .LR discard ,
 256 .I vf
 257 rejects the entire message.
 258 If the status contains the string
 259 .LR accept ,
 260 .I vf
 261 does not sanitize the attachment.
 262 Otherwise,
 263 .I vf
 264 sanitizes the attachment as before.
 265 The standard
 266 .I validateattachment
 267 uses
 268 .IR file (1)
 269 to determine the file type.
 270 It accepts text and image files
 271 and discards messages containing
 272 executables or
 273 .I zip
 274 (see
 275 .IR gzip (1))
 276 archives of executables.
 277 .PP
 278 The
 279 .B -r
 280 option causes
 281 .I vf
 282 not to sanitize MIME attachments, but instead to
 283 reject messages it determines to be viruses.
 284 The
 285 .B -s
 286 option causes
 287 .I vf
 288 to log all attachments of safety
 289 .B r
 290 in the mail box
 291 .IR savefile .
 292 .SH FILES
 293 .TF /mail/lib/validateattachment
 294 .TP
 295 .B /mail/box/*/pipeto
 296 mail filter
 297 .TP
 298 .B /sys/lib/mimetype
 299 MIME content types
 300 .TP
 301 .B /mail/lib/validateattachment
 302 attachment checker
 303 .SH SOURCE
 304 .B /sys/src/cmd/upas/send
 305 .br
 306 .B /sys/src/cmd/upas/filterkit
 307 .br
 308 .B /sys/src/cmd/upas/vf
 309 .SH "SEE ALSO"
 310 .IR aliasmail (8),
 311 .IR faces (1),
 312 .IR mail (1),
 313 .IR marshal (1),
 314 .IR mlmgr (1),
 315 .IR nedmail (1),
 316 .IR qer (8),
 317 .IR rewrite (6),
 318 .IR send (8),
 319 .IR smtp (8),
 320 .IR upasfs (4)