Provided by:
messagewall_1.0.8-3_i386 
NAME
messagewall.conf - configuration file for messagewall
SYNOPSIS
vi /usr/local/etc/messagewall.conf
DESCRIPTION
messagewall.conf controls the functioning of the messagewall SMTP
filtering proxy software.
This file is in the format:
variable_name="value"
variable_name2="value2"
------------- IMPORTANT --------------
In order to provide maximum speed, MessageWall allocates all needed
memory at startup. The vast majority of this memory is the client and
backend message buffers. The pseudo-expression for the amount of
memory allocated is:
processes * (max_clients + max_backends) * max_message_size
This means that with processes=1, max_clients=100, max_backends=50, and
max_message_size=10485760 (10MB), MessageWall will allocate over 1.5GB
of memory on startup.
If you get carried away with any of the variables listed above, it is
very easy to exhaust all memory on your system during MessageWall
startup, which will cause it to print an error and fail to start.
------------- IMPORTANT --------------
Program variables:
processes
Example:
processes=1
The number of processes to create at startup. This option is
provided to fully utilize machines with multiple processors; it
should never be set higher than the number of processors in your
system. Several of the scaling variables (max_clients,
max_backends, max_per_ip) are per process.
max_clients
Example:
max_clients=10
The maximum number of clients that messagewall should accept per
process. Any clients attempting to connect over this limit will
receive a temporary error instead of a greeting.
max_backends
Example:
max_backends=5
The number of connections to the backend server to try to keep
open per process. If no connections are free when we receive a
message from a client, MessageWall sends the client a temporary
error indicating that they should try again later.
max_per_ip
Example:
max_per_ip=5
The number of client connections to accept from a certain IP per
process. Any clients attempting to connect that would go over
this limit are sent a temporary error instead of a greeting.
This is a security measure to prevent one user from overwhelming
the server; it should be set to a small fraction of max_clients
so that many IPs would be required to deny access to the server.
max_message_size
Example:
max_message_size=10485760
The maximum size, in bytes, of message to accept. This size is
announcing in the ESMTP SIZE parameter, and messages larger than
this size are refused.
max_rcpt
Example:
max_rcpt=25
The maximum number of recipients for a given message. According
to RFC 2821, this should be at least 100. It is usually
practical, however, to keep it much smaller than this. Users
trying to send to more recipients will receive a permanent
error.
max_errors
Example:
max_errors=3
The maximum number of permanent errors (usually for issuing
unrecognized commands) that will be sent to a client before they
are disconnected. This prevents the reception of mail via such
tricks as HTTP proxy header SMTP commands. It should be set
fairly low (3-5) in order to be effective. Setting this value
too low can cause clients attempting to use SMTP extensions to
fail.
max_idle
Example:
max_idle=60
The maximum amount of time, in seconds, that a client may keep a
connection idle. RFC 2821 indicates that this should be at
least 300 (5 minutes). It seems to be more practical to set it
around 60 seconds.
max_parts
Example:
max_parts=25
The maximum number of MIME parts allowed in a message. This is
used for memory scaling and to prevent a client from sending
many MIME parts to waste CPU time in MessageWall. Most users
seem to expect this to be at least 25.
max_depth
Example:
max_depth=5
The maximum depth of nested MIME parts allowed in the message.
This is used as a safety check against attacks causing the
recursive MIME parsing algorithm to exhaust the stack space
inside MessageWall. 5 seems to be a good value for most
installations.
listen_ip
Example:
listen_ip=1.2.3.4
The IP address, in dotted quad notation, that MessageWall should
listen on. As MessageWall will bind to port 25 on this address,
it will need to be run as root.
backend_ip
Example:
backend_ip=127.0.0.1
The IP address, in dotted quad notation, that MessageWall should
connect to in order to deliver messages that have passed
filtering. MessageWall will connect to this IP address on port
25 and speak ESMTP or SMTP . The server running on this IP
should support ESMTP, PIPELINING and 8BITMIME, but does not need
to. You may chain MessageWall installations in order to spread
filtering across different systems, although this is highly
inefficient.
domain
Example:
domain=example.com
The primary domain name that MessageWall is serving. This is
used in several SMTP responses.
path_charset
Example:
path_charset="abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-_+=@"
The characters to accept in the envelope forward and reverse
paths. According to RFC 2821, all 7bit characters except line
feeds, carriage returns and nils are allowed. However,
restricting the allowed character set further can often stop
relaying holes in the backend server from being exploited by
outsiders. If you are aware of such a hole in your backend
server, please upgrade immediately and do not rely on
MessageWall as a bandaid.
dnsbl_timeout
Example:
dnsbl_timeout=5
The timeout, in seconds, of DNS-based blacklist queries (which
are sent at the start of the SMTP conversation). If an answer
has not been received in half this time, the queries are resent.
If an answer has not been received after this time elapses,
MessageWall "fails open" and assumes that the IP address in
question is not listed. This timeout should be set fairly low
to prevent message slowdown and max_clients exhaustion when DNS
servers stop responding.
dnsbl_domain_timeout
Example:
dnsbl_domain_timeout=5
The timeout, in seconds, of domain DNS-based blacklist queries
(which are sent after the MAIL FROM is received). If an answer
has not been received in half this time, the queries are resent.
If an answer has not been received after this time elapses,
MessageWall "fails open" and assumes that the domain in question
is not listed. This timeout should be set fairly low to prevent
message slowdown and max_clients exhaustion when DNS servers
stop responding.
dnsdcc_timeout
Example:
dnsdcc_timeout=5
The timeout, in seconds, of DNS-based distributed checksum
queries (which are sent after the full message is received). If
an answer has not been received in half this time, the queries
are resent. If an answer has not been received after this time
elapses, MessageWall "fails open" and assumes that the checksum
in question is not listed. This timeout should be set fairly
low to prevent message slowdown and max_clients exhaustion when
DNS servers stop responding.
rmx_timeout
Example:
rmx_timeout=10
The timeout, in seconds, of reverse path MX/A lookups (which are
sent after the MAIL FROM is received). If an answer has not
been received in half this time, the queries are resent. If an
answer has not been received after this time elapses,
MessageWall "fails closed" and returns a temporary error to the
client. This timeout should be set fairly low to prevent
message slowdown and max_clients exhaustion when DNS servers
stop responding.
rdns_timeout
Example:
rdns_timeout=10
The timeout, in seconds, of reverse DNS queries (which are sent
at the start of the SMTP conversation). If an answer has not
been received in half this time, the queries are resent. If an
answer has not been received after this time elapses,
MessageWall "fails closed" and returns a temporary error to the
client. This timeout should be set fairly low to prevent
message slowdown and max_clients exhaustion when DNS servers
stop responding.
profile_dir
Example:
profile_dir=/usr/local/etc/profiles/
The directory to be scanned for profiles. Each regular file in
the directory should be parsable as a MessageWall profile.
Profile names are taken from the filenames, and are case
sensitive. This directory should be outside root, as profiles
are not reloaded on SIGHUP.
pid_dir
Example:
pid_dir=/pids/
The directory, relative to root and auth_root, in which to store
process ID files that are used by messagewallctl to signal
messagewall at runtime.
relay_profile
Example:
relay_profile=Relay
The profile that should be used for clients listed in the
relay_ips file. Clients accessing MessageWall from IPs in this
file always utilize this profile, regardless of what address
(local or remote) they are sending to.
default_profile
Example:
default_profile=Medium
The profile to use for all messages not coming from an IP in
relay_ips and not going to an address or domain listed in
special_users.
root
Example:
root=/home/mwall
The directory to chroot to for normal operation of the program.
This directory should contain the files specified in
local_domains, relay_ips and special_users, and nothing else.
Any other files in this directory may be accessible by users
that compromise the server.
user
Example:
user=mwall
The username to run as for normal program functioning.
MessageWall will setuid to this username before accepting any
clients. This username should have as little privilege as
possible; it needs to be able to open TCP connections to
backend_ip and to read local_domains, relay_ips and
special_users from the chroot directory.
group
Example:
group=mwall
The group to run as for normal program functioning. MessageWall
will setgid to this group before accepting any clients. It will
also drop any supplemental groups. This group should have as
little privilege as possible.
auth_root
Example:
auth_root=/home/mwalla
The directory to chroot to for authentication operations. This
directory should contain the file specified in relay_auth, and
nothing else. Any other files in this directory may be
accessible by users that compromise the server. This variable
is optional only if relay_auth is not set.
auth_user
Example:
auth_user=mwalla
The username to run as for authentication operations.
MessageWall will setuid to this username in the authentication
processes. This username should have as little privilege as
possible; it needs to be able to read relay_auth from the chroot
directory. This variable is optional only if relay_auth is not
set.
auth_group
Example:
auth_group=mwalla
The group to run as for authentication operators. MessageWall
will setgid to this group in the authentication processes. It
will also drop any supplemental groups. This group should have
as little privilege as possible. This variable is optional only
if relay_auth is not set.
lockfile
Example:
lockfile=/var/lock/messagewallctl
This file to use for locking in messagewallctl(1). This file is
used to ensure that only one copy of messagewallctl(1) is
writing to shared resources at a time.
Optional variables:
local_domains
Example:
local_domains=local_domains
File contents example:
example1.com
example2.com
The location, relative to the chroot directory root specified in
the config file, of a file containing a newline-seperated list
of domains whose mail is delivered locally. If a MessageWall
client’s IP address is not listed in relay_ips, they may only
send mail to addresses at these domains. This file is reloaded
on messagewallctl reload-db.
relay_ips
Example:
relay_ips=relay_ips
File contents example:
1.2.3.4/24
5.6.7.8/255.255.255.248
The location, relative to the chroot directory root specified in
the config file, of a file containing a newline-seperated list
of IP/subnet mask pairs indicating IP addresses that are allowed
to send mail to any domain. The subnet mask may not be larger
than /16, and may be in either CIDR or dotted-quad notation.
This file is reloaded on messagewallctl reload-db.
special_users
Example:
special_users=special_users
File contents example:
ian@example.com:Extreme
example2.com:None
The location, relative to the chroot directory root specified in
the config file, of a file containing a newline-seperated list
of email address:profile and domain:profile entries. Each entry
specifies the profile to be used for mail going to that email
address, or the profile to used for mail going to that domain in
the case that a specific email address rule doesn’t exist.
Profile names are case sensitive and should correspond exactly
to files in profile_dir. This file is reloaded on
messagewallctl reload-db.
relay_auth
Example:
relay_auth=relay_auth
File contents example:
ian@example.com:HT5Oe.CR.pfTg
The location, relative to the chroot directory auth_root
specified in the config file, of a file containing a newline-
seperated list of username:hash entries for users that are
allowed to relay. Users can authenticate with MessageWall via
SMTP AUTH when not inside the relay_ips space and still relay,
if their credentials are present in this file. Any hash that is
supported by your system crypt(3) routine may be used. This
file is reloaded on messagewallctl reload-auth.
greeting
Example:
greeting="Use of this server implies willingness to be scanned
for open relay and other vulnerabilities."
The greeting to send at the beginning of the SMTP conversation.
This parameter is completely optional; not setting it causes
MessageWall to send its version number and information on the
relaying ability of the client.
backend_port
Example:
backend_port=2025
The port to connect to the backend server on. This parameter is
completely optional; not setting it causes MessageWall to
connect on the standard port 25.
listen_port
Example:
listen_port=2025
The port to listen for incoming connections on. This parameter
is completely optional; not setting it causes MessageWall to
listen on the standard port 25.
7bit
Example:
7bit=1
Setting 7bit to 1 (default is 0) causes MessageWall to not
advertise 8BITMIME support publicly, and to ignore the lack of
8BITMIME on the backend server. It also causes MessageWall to
scan messages for any data that is not 7bit and to reject the
message in this case. This option slows down MessageWall and
causes legitimate mail to bounce. A much better solution to a
non-8BITMIME backend server is to upgrade to one that is (see
http://qmail.org/).
certificate
Example:
certificate=/usr/local/etc/cert.pem
The path of the combined private key/certificate file to be
announced to clients. To be useful on an ISP server, this
certificate must be signed by a certificate authority.
backend_certificate
Example:
backend_certificate=/usr/local/etc/cert.pem
The path of the combined private key/certificate file to be used
to connect to the backend server.
EXAMPLES
See the file conf/messagewall.conf from the distribution, which is
installed to /usr/local/etc/messagewall.conf by default, for a sample
configuration.
AUTHOR
Ian Gulliver <ian@penguinhosting.net>
SEE ALSO
messagewall(1),
messagewall_profiles(5)
2002-06-08 messagewall.conf(5)