messagewall.conf - configuration file for messagewall

vi /usr/local/etc/messagewall.conf

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 --------------

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.

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.

See the file conf/messagewall.conf from the distribution, which is installed to /usr/local/etc/messagewall.conf by default, for a sample configuration.

Ian Gulliver <ian@penguinhosting.net>

messagewall(1),

messagewall_profiles(5)