postoffice.cf.5.in

.\" Copyright (c) 1988, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd February 4, 2006
.Dt POSTOFFICE.CF 5
.Os Mastodon
.Sh NAME
.Nm postoffice.cf
.Nd configuration file for
.Nm postoffice
.Sh SYNOPSIS
.Nm @confdir@/postoffice.cf
.Sh DESCRIPTION
This file contains various configuration
settings for the 
.Sy postoffice
mail server.   All of the settings listed here can also be passed
directly to the
.Sy postoffice
server via the 
.Fl o
command line argument.
.Pp
The format of the configuration file is one setting per line, with
blank lines and lines beginning with # ignored as comment lines.
The settings are:
.Bl -tag -width Fl
.It Li audit
Enable session auditing.
.It Li forbidden Ns = Ns Ar option
Configure how 
.Nm postoffice
deals with forbidden sites.
.Bl -tag -width Fl
.It Li forbidden=accept
Let them connect and treat them as if they were
a normal site.
.It Li forbidden=bounce 
Refuse connections.
.It Li forbidden=folder Ns : Ns Ar path
Accept the mail and place it in the users
forbidden mail folder.  If
.Ql path
begins with
.Ql ~/ Ns ,
it will be expanded to that file in the user's home directory.
If it does not begin with 
.Ql ~/ Ns ,
it will be expanded to a folder in the maildir named
.Li username Ns : Ns Ar path Ns .
Non-local users (and users in a virtual domain) will have mail
delivered as if you had configured
.Ql forbidden=accept Ns .
.El
.It Li checkhelo
Check the arguments passed with the 
.Em HELO
and
.Em EHLO
SMTP command and refuse to do an SMTP conversation with the
client if they claim to be the mail server.
.It Li clients Ns = Ns Ar N
Allow only 
.Ar N
clients at a time to connect to the server.
.It Li debug
Enable the ESMTP
.Ql DEBUG
command, which displays various compile and runtime settings,
as well as the current state of the mail envelope.  This is useful
for some types of debugging, but it may expose internal information
to the public.
.It Li delay Ns = Ns Ar N
Set the
.Em greylist Ns ing
delay to
.Ar N
seconds.
The 
.Xr delay
may be specified as a tagged number,
with
.Ql m
being minutes.
and
.Ql h
being hours.
.It Li escape-from Ns = Ns Ar N
If nonzero, all lines beginning with 'From ' in the body of the
message will be prefixed by '>'.   Some mail readers can't handle raw
\&'From ' lines in the middle of a message and will treat them as
the start of a new message, so mangling the message like this will
stop them from getting confused.
@MILTERMAN@.It Li filter Ns = Ns Ar socket
@MILTERMAN@Defines a sendmail filter that will scan incoming mail
@MILTERMAN@before
@MILTERMAN@.Em postoffice
@MILTERMAN@accepts it.    The 
@MILTERMAN@.Ar socket
@MILTERMAN@can be either a Unix-domain socket on the local machine
@MILTERMAN@or a tcp socket on any machine.
@MILTERMAN@Note that postoffice uses the dns 
@MILTERMAN@.Em exclusively Ns ,
@MILTERMAN@so you need to give the fully qualified domain name of
@MILTERMAN@the machine that the filter is running on.  If you don't,
@MILTERMAN@the filter just won't be called.
@MILTERMAN@If enabled, the
@MILTERMAN@.Em DEBUG
@MILTERMAN@smtp command lists all of the currently configured filters
@MILTERMAN@and their status.  A status of 00h or 0h1 means that the
@MILTERMAN@filter is active; anything else indicates an error.
.It Li forward-all
When set, forward all unknown mail to the configured
.Sy relay-host .
.It Li hops Ns = Ns Ar N
Set the hop count to
.Ar N .
The hop count is incremented every time the mail is
processed.
When it reaches this limit,
the mail is returned with an error message (the default is 100 hops).
.It Li hostname Ns = Ns Ar name
Set the local host name.   Normally,
.Nm
find the local hostname by first getting the machine name, then looking
that name up in the DNS (defaulting to "localhost" if either of these
steps fail.)   You can tell
.Nm
to just use the machine name by setting 
.Ar hostname Ns = Ns Ar literal Ns ,
or to use 
.Ar name
by setting
.Ar hostname Ns = Ns Ar name Ns .
.It Li immediate
Attempt to deliver mail to remote machines immediately instead of waiting
for the next queue run.
.It Li load Ns = Ns Ar N
When the load average is above
.Ar N ,
.Sy postoffice
will not accept SMTP connections (the default is 4).
.It Li localmx
Treat connections from sites that use this machine as an MX
as if they were local, and give them the permissions that
local clients have.
@STATFS@.It Li minfree Ns = Ns Ar N
@STATFS@Stop accepting mail when there are less than
@STATFS@.Ar N 
@STATFS@kilobytes available on the mail spool volume.
@STATFS@.Xr minfree
@STATFS@is given as a tagged number,
@STATFS@with
@STATFS@.Ql m
@STATFS@being megabytes,
@STATFS@and
@STATFS@.Ql g
@STATFS@being gigabytes
.It Li msp
If set,
.Sy postoffice
accepts connections on port
.Em 587
as well as the normal port
.Em 25 .
This allows access from mail clients that
live behind firewalls which block port 25.
.It Li nodaemon
Do not accept mail from
.Em <> .
This can be useful for blocking spammers and viruses, but
it also violates
.%T RFC821 ,
and means that nobody at your site (including mailing lists)
will ever get bounce messages when mail cannot be delivered.
If your machine is connected to a public network,
.Em DON'T
.Em SET
.Em THIS
.Em OPTION
unless you're under attack from a malicious spammer.
.It Li paranoid
Do not accept mail from sites unless we can resolve their dns address.
.It Li qreturn Ns = Ns Ar N
Bounce undeliverable mail after 
.Ar N 
seconds.
The 
.Xr qreturn
may be specified as a tagged number,
with
.Ql m
being minutes,
.Ql h
being hours,
and
.Ql d
being days.
.It Li relay
Allow all clients to relay mail through this
server.   If your machine is connected to a public network,
.Em DON'T
.Em SET
.Em THIS
.Em OPTION ,
unless you really want to end up on every antispam list on
the planet.
.It Li relay-host Ns = Ns Ar host
Send all mail destined for remote hosts via this
.Ar host .
The superuser is the only user that can use this setting on the
command line or in a configuration file other than
.Pa /etc/postoffice.cf
.It Li self Ns = Ns Ar host
Set our hostname to
.Ar host .
.Sy Postoffice
normally uses the uname() system call to determine the machine name,
but you can set it to just about anything here.
.It Li size Ns = Ns Ar size
Sets the 
largest message size that 
.Sy postoffice
will accept.
.Xr size
is given as a tagged number,
with
.Ql k
being kilobytes,
and
.Ql m
being megabytes.
.It Li spam Ns = Ns Ar option
Configure how 
.Nm postoffice
deals with spam.
.Bl -tag -width Fl
.It Li spam=accept
Accept the spam-infested message and deliver it like a normal message.
.Nm postoffice
will add an
.Ql X-Spam
header to the message to warn the user that this message might be
spam.
.It Li spam=bounce Ns : Ns Ar why
Refuse to accept the spam-infested message with a 5xx error during 
the
.Ql DATA
phase of the smtp session.
.Ar why
is the explanation for why it's being bounced.  It is optional and
if not supplied the message will be bounced with a default message
why.
.It Li spam=folder Ns : Ns Ar path
Accept the spam-infested message and deliver it to the users
spam mail folder.   If
.Ql path
begins with
.Ql ~/ Ns ,
it will be expanded to that file in the user's home directory.
If it does not begin with 
.Ql ~/ Ns ,
it will be expanded to a folder in the maildir named
.Li username Ns : Ns Ar path Ns .
Non-local users (and users in a virtual domain) will have the
spam-infested mail delivered as if you configured
.Ql spam=accept Ns .
.El
.It Li timeout Ns = Ns Ar timeout
Drop the connection to a client if they are idle
longer than
.Ar timeout .
This setting violates the word (if not the intent) of the SMTP
specification,
so the timeout should probably be fairly large.
The 
.Xr timeout
may be specified as a tagged number,
with
.Ql m
being minutes,
.Ql h
being hours,
and
.Ql d
being days.
For example,
.Ql timeout=60m
or 
.Ql timeout=1h
both set the timeout to one hour.
.It Li trusted Ns = Ns Ar host
Treat connections from
.Ar host
as if they were local, and give them the permissions that
local clients have.
.Ar Host
may be a hostname or an ip address quoted with square
brackets (ie: [10.0.10.5])
.It Li usermap Ns = Ns Ar pattern:target(s)
Define personal aliases
(the format is described in the
.Xr usermap 7
manpage.)
.It Li verify-from Ns = Ns Ar flag
Check the validity of MAIL FROM addresses.  If
nonzero (the default), the address will be rejected if it's
from an unresolvable domain or if a remote client attempts to
give a local address, and if zero, anything the client gives is
okay with 
.Sy postoffice .
.El
.Sh SECURITY CONSIDERATIONS
.Nm Postoffice
will not run if
.Pa postoffice.cf
is not a file, is not owned by root, is world writable, or lives in a
.Pa @confdir@
that has any elements that are not owned by root, are world writable,
or are not directories.
.Sh SEE ALSO
.Xr usermap 7 ,
.Xr postoffice 8