.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "amavisd-milter" "8" "" "Version 1.7.2-1" "System Manager\[cq]s Manual"
.hy
.SH NAME
.PP
\f[B]amavisd-milter\f[R] - sendmail milter for amavis
.SH SYNOPSIS
.PP
\f[B]amavisd-milter\f[R] [\f[B]-Bfhv\f[R]]
[\f[B]-d\f[R]\ \f[I]debug-level\f[R]]
[\f[B]-D\f[R]\ \f[I]delivery-care-of\f[R]]
[\f[B]-m\f[R]\ \f[I]max-conns\f[R]] [\f[B]-M\f[R]\ \f[I]max-wait\f[R]]
[\f[B]-p\f[R]\ \f[I]pidfile\f[R]] [\f[B]-P\f[R]]
[\f[B]-q\f[R]\ \f[I]backlog\f[R]] [\f[B]-s\f[R]\ \f[I]socket\f[R]]
[\f[B]-t\f[R]\ \f[I]timeout\f[R]] [\f[B]-S\f[R]\ \f[I]socket\f[R]]
[\f[B]-T\f[R]\ \f[I]timeout\f[R]] [\f[B]-w\f[R]\ \f[I]directory\f[R]]
.SH DESCRIPTION
.PP
The amavisd-milter is a sendmail milter (mail filter) for amavis 2.4.3
and above and sendmail 8.13 and above.
.PP
With the amavisd-milter, a full amavis functionality is available,
including adding spam and virus information header fields, modifying the
Subject, adding address extensions and removing certain recipients from
delivery, while delivering the same message to the rest.
.PP
For more information you can visit amavisd-milter website:
.RS
.PP
https://github.com/prehor/amavisd-milter
.RE
.SS Options
.PP
The options are as follows:
.TP
\f[B]-B\f[R]
Uses the milter macro \f[I]{daemon_name}\f[R] as the policy bank name
(see POLICY BANKS below).
.TP
\f[B]-d\f[R] \f[I]debug-level\f[R]
Set the debug level.
The debugging traces become more detailed as the debug level increases.
Maximum is 9.
.TP
\f[B]-D\f[R] \f[I]delivery-care-of\f[R]
Set AM.PDP request attribute \f[I]delivery_care_of\f[R] to
\f[I]client\f[R] (default) or \f[I]server\f[R].
.PP
When the \f[I]client\f[R] method is used, then amavisd-milter is
responsible for forwarding the message to the recipients.
This method does not allow personalized header or body modification.
.PP
When the \f[I]server\f[R] method is used, then amavis is responsible for
forwarding the message to the recipients and may personalize the headers
and the body of the messages.
\f[I]$forward_method\f[R] variable in \f[B]amavisd.conf\f[R] must point
to a place willing to accept the message without further checking in
amavis.
.TP
\f[B]-f\f[R]
Run amavisd-milter in the foreground (i.e.\ do not daemonize).
Print debugging messages to the terminal.
.TP
\f[B]-h\f[R]
Print the help page and exit.
.TP
\f[B]-m\f[R] \f[I]max-conns\f[R]
Maximum concurrent amavis connections (default 0 = unlimited number of
connections).
It must be the same as the \f[I]$max_servers\f[R] variable in
\f[B]amavisd.conf\f[R].
.TP
\f[B]-M\f[R] \f[I]timeout\f[R]
Timeout for message processing in seconds (default 300 seconds = 5
minutes).
Must be less then timeout for a response to the final \[lq].\[rq] that
terminates a message on sending MTA.
\f[B]Sendmail\f[R] uses default value 1 hour, \f[B]postfix\f[R] 10
minutes and \f[B]qmail\f[R] 20 minutes.
Recommended value is less than 10 minutes.
.PP
If you use other milters (especially time-consuming), the timeout must
be sufficient to process message in all milters.
.TP
\f[B]-p\f[R] \f[I]pidfile\f[R]
Use this pid file.
.TP
\f[B]-P\f[R]
When the amavis fails, the message will be passed through unchecked.
.TP
\f[B]-q\f[R] \f[I]backlog\f[R]
Sets the incoming socket backlog used by \f[B]listen(2)\f[R].
If it is not set or set to zero, the operating system default is used.
.TP
\f[B]-s\f[R] \f[I]socket\f[R]
Communication socket between sendmail and amavisd-milter.
The protocol spoken over this socket is \f[I]MILTER\f[R] (Mail FILTER).
It must have the same vale as the \f[I]INPUT_MAIL_FILTER\f[R] macro in
\f[B]sendmail.mc\f[R].
.PP
The \f[I]socket\f[R] must be in format \f[I]proto:address\f[R]:
.RS
.IP \[bu] 2
\f[I]{unix|local}:/path/to/file\f[R] - A named pipe.
.IP \[bu] 2
\f[I]inet:port\[at]{hostname|ip-address}\f[R] - An IPV4 socket.
.IP \[bu] 2
\f[I]inet6:port\[at]{hostname|ip-address}\f[R] - An IPV6 socket.
.RE
.TP
\f[B]-S\f[R] \f[I]socket\f[R]
Communication socket between amavisd-milter and amavis.
The protocol spoken over this socket is \f[I]AM.PDP\f[R] (AMavis Policy
Delegation Protocol).
It must have the same value as the \f[I]$unix_socketname\f[R] variable
in \f[B]amavisd.conf\f[R].
.PP
The \f[I]socket\f[R] must be in format \f[I]proto:address\f[R]:
.RS
.IP \[bu] 2
\f[I]{unix|local}:/path/to/file\f[R] - A named pipe.
.IP \[bu] 2
\f[I]inet:port\[at]{hostname|ip-address}\f[R] - An IPV4 socket.
.IP \[bu] 2
\f[I]inet6:port\[at]{hostname|ip-address}\f[R] - An IPV6 socket.
.RE
.TP
\f[B]-t\f[R] \f[I]timeout\f[R]
Sendmail connection timeout in seconds (default 600 = 10 minutes).
It must have the same vale as the \f[I]INPUT_MAIL_FILTER\f[R] macro in
\f[B]sendmail.mc\f[R] and must be greater than or equal to the amavis
connection timeout.
.PP
If you use other milters (especially time-consuming), the timeout must
be sufficient to process message in all milters.
.TP
\f[B]-T\f[R] \f[I]timeout\f[R]
Amavis connection timeout in seconds (default 600 = 10 minutes).
Must be sufficient to process message in amavis.
Usually, it is a good idea to set them to the same value as sendmail
connection timeout.
.TP
\f[B]-v\f[R]
Report the version number and exit.
.TP
\f[B]-w\f[R] \f[I]directory\f[R]
Set working directory.
.SH POLICY BANKS
.PP
If the option \f[B]-B\f[R] is enabled, amavisd-milter uses the value of
the milter macro \f[I]{daemon_name}\f[R] as the name of the amavis
policy bank.
Usually, this milter macro is set to name of the MTA.
.PP
When remote client is authenticated, amavisd-milter uses authentication
information as the name of the amavis policy banks:
.TP
\f[B]\f[VB]SMTP_AUTH\f[B]\f[R]
Remote client has been authenticated.
.TP
\f[B]\f[VB]SMTP_AUTH_<MECH>\f[B]\f[R]
The remote client authentication mechanism.
.TP
\f[B]\f[VB]SMTP_AUTH_<MECH>_<BITS>\f[B]\f[R]
The number of bits used for the key of the symmetric cipher when
authentication mechanism uses it.
.SH EXAMPLES
.SS Configuring amavis
.PP
In the \f[B]amavisd.conf\f[R] file set protocol and amavis socket to:
.IP
.nf
\f[C]
$protocol = \[dq]AM.PDP\[dq];                      # Use AM.PDP protocol
$unix_socketname = \[dq]$MYHOME/amavisd.sock\[dq]; # Listen on Unix socket
### $inet_socket_port = 10024;             # Do not listen on TCP port
\f[R]
.fi
.PP
Then (re)start the amavisd daemon.
.SS Configuring Postfix
.PP
Add the following entries to Postfix \f[B]main.cf\f[R]*:
.IP
.nf
\f[C]
smtpd_milters = local:<AMAVISD_MILTER.SOCK>
milter_connect_macros = j {client_name} {daemon_name} v
milter_protocol = 6
\f[R]
.fi
.PP
Then (re)start the Postfix daemon.
.SS Configuring sendmail
.PP
Add the following entries to file \f[B]sendmail.mc\f[R]:
.IP
.nf
\f[C]
define(\[ga]confMILTER_MACROS_CONNECT\[aq],
  confMILTER_MACROS_CONNECT\[ga], {client_resolve}\[aq])
define(\[ga]confMILTER_MACROS_ENVFROM\[aq],
  confMILTER_MACROS_ENVFROM\[ga], r, b\[aq])
INPUT_MAIL_FILTER(\[ga]amavisd-milter\[aq],
  \[ga]S=local:<AMAVISD_MILTER.SOCK>, F=T, T=S:10m;R:10m;E:10m\[aq])
\f[R]
.fi
.PP
Then rebuild \f[B]sendmail.cf\f[R] file, install it and (re)start the
sendmail daemon.
.SS Running amavisd-milter
.PP
This examples assumes that amavis is running as user \f[I]vscan\f[R].
The actual name is shown in the \f[I]$daemon_user\f[R] variable in
\f[B]amavisd.conf\f[R].
.SS Limiting maximum concurrent connections to amavisd
.PP
To limit the maximum concurrent connections to amavis, run
amavisd-milter with this options:
.IP
.nf
\f[C]
su - amavis -c \[dq]amavisd-milter -m 4\[dq]
\f[R]
.fi
.SS Troubleshooting
.PP
For troubleshooting, run amavisd-milter on the foreground and set the
debug level to the appropriate value:
.IP
.nf
\f[C]
su - amavis -c \[dq]amavisd-milter -f -d 4\[dq]
\f[R]
.fi
.PP
Debug levels are:
.IP \[bu] 2
1 - Not errors but unexpected states (connection abort etc).
.IP \[bu] 2
2 - Main states in message processing.
.IP \[bu] 2
3 - All amavisd-milter debug messages.
.IP \[bu] 2
4-9 - Milter communication debugging (set \f[B]smfi_setdbg\f[R] to 1-6).
.SH SEE ALSO
.IP \[bu] 2
https://github.com/prehor/amavisd-milter
.IP \[bu] 2
https://www.ijs.si/software/amavisd/
.IP \[bu] 2
https://www.sendmail.org
.SH AUTHORS
.PP
This manual page was written by Petr Rehor and is based on Jerzy Sakol
initial work.
.SH BUGS
.PP
Issues can be reported by using GitHub at:
.RS
.PP
https://github.com/prehor/amavisd-milter/issues
.RE
.PP
Full detailed information on how to report issues, please see the
Contribution Guidelines at:
.RS
.PP
https://github.com/prehor/amavisd-milter/blob/master/CONTRIBUTING.md
.RE
.PP
Enhancements, requests and problem reports are welcome.
.PP
If you run into problems, first check the GitHub issues before creating
a new one.
It is very likely that someone has encountered the same problem and it
has already been solved.