Provided by: messagewall_1.0.8-3_i386 bug

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)