$OpenBSD: patch-bin_smtp-vilter_smtp-vilter_8,v 1.2 2010/04/03 20:07:06 naddy Exp $
--- bin/smtp-vilter/smtp-vilter.8.orig	Sun Nov 12 12:39:17 2006
+++ bin/smtp-vilter/smtp-vilter.8	Sat Apr  3 21:43:06 2010
@@ -68,6 +68,9 @@
 .Bk -words
 .Op Fl a Ar spam-subject-prefix
 .Ek
+.Bk -words
+.Op Fl H Ar header-options
+.Ek
 .\" .Bk -words
 .\" .Op Fl D Ar binddn
 .\" .Ek
@@ -122,6 +125,9 @@ Start in verbose mode.
 .Nm
 will run in foreground and some diagnostic messages are displayed on the
 console.  Watch the system log for additional messages.
+.It Fl vv
+Enable a few additional messages relating to SASL authentication,
+and display data sent to and from backend sockets.
 .It Fl m
 Mark all messages with
 .Dq X-SMTP-Vilter
@@ -174,6 +180,9 @@ to set a maximum number of open file descriptors.
 .It Fl a Ar spam-subject-prefix
 Specify a prefix that will be put in from of the Subject-line if a
 message is considered spam.
+.It Fl H Ar header-options
+Control various features of the internally generated header used to
+forward messages to a spam detection backend (see "Header Options" below).
 .\" .It Fl D Ar binddn
 .\" Specify the  distinguished name to use when binding to the LDAP server.
 .\" .It Fl h Ar ldaphost
@@ -194,12 +203,50 @@ socket file is in /var/run):
 INPUT_MAIL_FILTER(`smtp-vilter', `S=unix:/var/run/smtp-vilter.sock, F=T, T=S:10s;R:120s')
 define(`confINPUT_MAIL_FILTERS', `smtp-vilter')
 .Ed
-
 Configure your timeouts to sane values.  If you use Spamassassin make
 them long enough.  Remember you have to set timeouts not only in the
 smtp-vilter and backend config files, but in your sendmail .mc config
 file a s well as shown in the example above which configures a sending
 timeout of 10 seconds and a receiving timeout of 120 seconds.
+.Sh Using Postfix
+.Nm
+can be used with recent versions of Postfix that include milter support.
+Postfix needs access to smtp-vilter.sock by making it a member of
+the owning group and setting umask 002 before running smtp-vilter
+.Pp
+Postfix does not automatically set the _ macro, this must be added
+to main.cf manually:
+.Bd -literal
+milter_connect_macros = j {daemon_name} v _
+.Ed
+.Sh Header Options
+As
+.Nm
+receives messages directly via the milter interface, it doesn't have access to
+headers that are added downstream by the MTA.  So in order pass a message to a
+spam detection backend
+.Nm
+must generate and add its own artificial header.
+Note that this header is entirely internal and is NOT visible to the MTA or
+the end recipent.
+.Pp
+The
+.Aq header-options
+parameter provides control over various features of this header.
+.Pp
+At present there is only one option, which is to indicate the sender's SASL
+authentication status as reported by the MTA:
+.Bl -tag -width "header-options=xxx"
+.It Pa header-options=0
+ignore SASL authentication status (default)
+.It Pa header-options=1
+if the sender successfully signed in then insert a tag of the form
+"(Authenticated sender: user@domain)" in the received header.
+.El
+.Pp
+The latter behaviour emulates Postfix's "smtpd_sasl_authenticated_header"
+option. It enables a (suitably configured) spam detection backend to apply
+different rules for trusted senders.
 .Sh FILES
 .Bl -tag -width "/etc/smtp-vilter/smtp-vilter.conf" -COMPACT
 .It Pa /etc/smtp-vilter/smtp-vilter.conf
@@ -265,15 +312,6 @@ based scanning.  If both
 .Nm
 and the scan engine are chrooted to different directories, they must
 communicate using TCP/IP sockets.
-.Sh USING POSTFIX
-.Nm
-can be used with recent versions of Postfix that include milter support.
-Postfix needs access to smtp-vilter.sock by making it a member of
-the owning group and setting umask 002 before running smtp-vilter
-.Pp
-Postfix does not automatically set the _ macro, this must be added
-to main.cf manuall:
-milter_connect_macros = j {daemon_name} v _
 .\" .Sh BUGS
 .\" .Ss LDAP functionality
 .\" LDAP functionality is only available when