NAME

pmx.conf - The main PureMessage configuration file

SYNOPSIS

/opt/pmx6/etc/pmx.conf

 <milter Policy>
    port = inet:10025@127.0.0.1
    filter = PureMessage::Milter::Policy
    message_log = message_log
    smtp_talk_port = inet:10026@127.0.0.1
 </milter>

 <milter Name_B>
    port = local:/tmp/B.sock
    enabled = yes
 </milter>

 log_dir = __DEFAULT__
 run_dir = __DEFAULT__
 log_to = __DEFAULT__
 log_utc = __DEFAULT__
 stdout = __DEFAULT__
 stderr = __DEFAULT__
 quarantine_dir = __DEFAULT__
 umask = __DEFAULT__
 quarantine_secret = jSAnHoM4BHxYWfQS
 mail_sender = smtp:[127.0.0.1]:10026
 admin = PureMessage Admin <postmaster@DomainName.com>
 buffer_size = __DEFAULT__
 block_size = __DEFAULT__
 use_threads = __DEFAULT__
 max_pooled_procs = __DEFAULT__
 mime_max_part_headers = __DEFAULT__
 min_pooled_procs = __DEFAULT__
 pooled_proc_idle_limit = __DEFAULT__
 pooled_proc_connect_limit = __DEFAULT__
 preload_interpreters = __DEFAULT__
 thread_stack_size = __DEFAULT__
 reinit_limit = __DEFAULT__
 concurrency_limit = __DEFAULT__
 concurrency_limit_action = __DEFAULT__
 debug_level = 0
 time_connection = __DEFAULT__
 time_message = __DEFAULT__

 !include pmx.d/*.conf
 quarantine_type = pmdb
 pmx_db = postgres

DESCRIPTION

This configuration file consists of a sequence of named <milter> and possibly <filter> sections as well as numerous settings outside these blocks that configure various aspects of PureMessage. The names of both types of blocks must be unique. Milter names are important as they are used to refer back to the milters within the pmx-milter tool. The example shown above specifies two milters ('milter Policy' and 'milter Name B').

MILTER AND FILTER BLOCKS

milter

This maps to a multithreaded process that serves as a mail filter. It listens for messages to be filtered from a mail transfer agent (MTA) such as sendmail or Postfix through either the milter protocol or through SMTP.

One or more filters (see below) may be executed within a milter. pmx.conf describes all of the milters that should be running, and the pmx-milter program can be used to start, stop and monitor these milters.

filter

This maps to a Perl module that has an interface that is described in PerlMx.

The following configuration options are available:

<milter milter_name>

This maps to a multithreaded process that serves as a mail filter. It listens for messages to be filtered from an MTA (for example, sendmail) through either the milter protocol or SMTP. One or more filters (see below) may be executed within a milter. The pmx-milter program can be used to start, stop and monitor these milters.

A default milter section called Policy is created during the PureMessage installation. Use the pmx-milter-add program or edit this configuration file to create additional milters. (See the pmx-milter-add manpage for more information.)

port = inet:port@host

port = local:path

The port at which the mail filter listens for connections from the MTA (sendmail or Postfix). See smtp_talk_port for a description of what type of protocol traffic is expected on this port.

This option can only occur inside a milter section. It is mandatory if there is more than one milter section. The port must be unique for all enabled milters, and must correspond to the port on which sendmail is sending messages. The default is inet:3366@localhost.

If the MTA is running on a different host, the host part of the port setting must be set to the hostname of the PureMessage server. The default setting of localhost will not allow external connections.

smtp_talk_port = inet:port@host

smtp_talk_port = local:path

This option can only occur inside a <milter> section. It is unset by default. It sets the port at which the mail filter expects to feed filtered mail back into the MTA using the SMTP protocol.

This option must be set for mail filtering with Postfix, and should be left unset for mail filtering with sendmail.

Setting this option enables the mail filter to function as an SMTP Proxy Server, meaning that the mail filter will listen for incoming SMTP connections at the location specified by port, and feed the filtered SMTP traffic back to the location specified by smtp_talk_port. Leaving it unset makes the mail filter behave as a Milter protocol server. In other words, setting or unsetting this option toggles the mail filter between SMTP Proxy Server or Milter Server modes of operation.

filter = name

This option can only occur inside a <milter> section. More than one filter can be specified within a single milter section. If no filter is specified, the filter name will be assumed to be the same as the milter name. When the milter starts up it will create one instance of each configured filter and send milter events to each of them.

message_log = path/filename

Specify the log file used to store message-processing events for this milter. If a non-absolute filename is given, it is interpreted as relative to log_dir. There is no default.

nobounce-addr

The address that bounced messages are redirected to when using the pmx_route policy action with the :nobounce parameter.

perl_args = argsList

args = argsList

These options specify extra arguments to be passed to the perl interpreter when it starts up. They are normally not specified in pmx.conf. The perl_args is interpreted by perl. It can be used to set up extra inc paths or to enable warnings.

The ``args'' show up as @ARGV.

They are specified separately so that all milters may share the same perl_args setting while having individually different args.

relay_use_header

relay_from_header

relay_from_regex

relay_from_index

When operating in SMTP Proxy Server mode (i.e., with Postfix) or when using other MTAs that don't provide relay host information, these options can be used to control how PureMessage retrieves the hostname or IP address of the connecting MTA (relay address) from the headers of the message.

relay_use_header is a boolean that explicitly switches on header scanning. This option does not need to be set if running in SMTP Proxy Server mode. The default is ``no''.

relay_from_header is a string that identifies the header to look for. The value is case insensitive. The default is ``received''.

Valid relay address data that is selected by the regular expression is any sequence of space-separated hostnames and IP addresses. Individual hostnames or addresses may be optionally surrounded by square brackets. Example:

    host.company.com [123.123.123.123]

relay_from_index indicates which among the possibly multiple occurrences of the header to match against. The default is 0, which corresponds to the first such header encountered. A value of 1 refers to the second header, etc.

enabled = bool

This option can only occur inside a <milter> section. It defaults to ``yes''. If it is ``no'' then the pmx tool will not try to start this milter.

</milter>

GENERAL SETTINGS

Note: Many of the pmx.conf entries are set to the value __DEFAULT__. These are values that are computed at run time based on the system configuration and environment. Refer to the output of pmx-config to find their specific values on your system.

log_dir = directory

Directory where PureMessage log files are stored. If no path is specified, the directory is assumed to be relative to the PureMessage installation directory. The default is var/log.

run_dir = directory

Directory where the PureMessage pid and status files are stored. If no path is specified, the directory is assumed to be relative to the PureMessage installation directory. The default is 'var/run'.

log_to = filename

Name of the PureMessage Milter log file. If no path is specified, the filename is taken to be relative to the log_dir specified above. The default is 'pmx_log'.

log_utc = yes|no

Specify whether the log timestamps use GMT time instead of local time. The default is 'no'.

stdout = path/filename

Name of the file that stores output from the running milter(s). Normally, no output is generated. If no path is specified, the filename is taken to be relative to the log_dir specified above. The default is 'pmx_out'.

stderr = path/filename

This is the name of the file that stores error output from the running milter(s). Normally, no errors are generated. If no path is specified, the filename is taken to be relative to the log_dir specified above. The default is 'pmx_err'.

quarantine_dir = path/filename

Directory where viruses and spam messages are quarantined. Normally the PureMessage quarantine manager is used to inspect the contents of the quarantine directory. If no path is specified, the file name is taken to be relative to the PureMessage installation directory. The default is 'var/qdir'.

See also: the pmx-qman manpage

umask = nnn

Sets the umask value for the milter process. The default is 007.

quarantine_secret = randomString

When messages are released from quarantine, an 'X-PMX-Quarantine-Approved' header with the quarantine_secret value is added to the message to bypass PureMessage filters. There is no default; it is uniquely configured for each site during the PureMessage installation.

mail_sender = smtp:[IPaddress]/Hostname>:port

Specifies the location and port of the server to which re-sent messages are directed. For example, when messages are released from the quarantine, they are routed via this server. The value is normally specified in the form 'smtp:[IPaddress]:port', for example, the default is 'smtp:[127.0.0.1]:10026'. It is not recommended that you use a hostname instead of an IP address when referring to 'localhost' specifically. Doing so could result in delivery failure. Hostnames resolved by way of a DNS server may be used in place of an IP address.

admin Full Name <email@address>

Specifies the PureMessage administrator's email address. It is used in the From: header of messages generated by the Quarantine Manager, and in other email notifications generated by PureMessage. There is no default.

buffer_size = n

This number sets the internal buffer size that can be used to hold each message. Messages bigger than this are temporarily written to disk. The default is 1,000,000 (roughly 1 MB).

block_size = n

This number sets the block size in bytes that should be used for filesystem I/O. By default, PureMessage tries to discover the best block size automatically from the filesystem with stat(). Acceptable values for block_size are powers of 2 between 512 and 2,097,152, inclusive.

Higher values will potentially improve speed at the cost of higher memory consumption. It is not recommended that you use values lower than the default, and that larger values be exact multiples of the default value. The current default value used by PureMessage can be found in the output of the 'pmx config' command, with block_size set to __DEFAULT__.

max_pooled_procs = n

Instead of running each milter as a single multi-threaded process, PureMessage can start a persistent pool of processes to service connections for each milter. Setting this option to a non-zero value enables the process pool. The setting controls the maximum number of processes that the pool can contain. The default value is determined based on available memory.

When the concurrency limit is reached and the process pool is enabled, PureMessage stops accepting connections on its port (see port). Connections queue up until they overflow the TCP stack's listen queue, after which they are refused.

mime_max_part_headers = n

Determines the maximum number of MIME headers per message that PureMessage can process. The default is 512 headers. If you find it necessary to modify this setting, and you are using Postfix as your mail transfer agent (MTA), refer also to the documentation for the max_proto_data_size setting. These settings should be consistent with the MIME headers setting for your MTA.

min_pooled_procs = n

When the process pool is enabled, this option specifies how many processes should always be kept running. The default is 1.

pooled_proc_idle_limit = na

Where a is either s (seconds), m (minutes), or h (hours) and n is the number of seconds, minutes or hours.

When the process pool is enabled, this option specifies how long a process in the pool can stay idle before it goes away. The default is 5m.

pooled_proc_connect_limit = n

When the process pool is enabled, this option specifies how many connections a process is allowed to handle before it terminates and a new process can take its place. The default is 0, which means that processes are not retired.

listen_queue_size = n

Sets the size of the socket listen queue, which controls the maximum number of pending connections beyond which connections are refused. Some operating systems may not honor the value specified. This option is not listed in the default pmx-conf, as it is only occasionally required for support purposes. The default is 0, which means that the system default is used.

thread_stack_size = n

This specifies how much stack space (in KB) to allocate to the milter threads. The default value is 1024. A value of 0 selects the system default size, which is often too low on some systems.

preload_interpreters = n

Specifies how many perl interpreters should be started. The default is the number of CPUs on the system times 5.

reinit_limit = n

Specifies how many connections a perl interpreter serves before it is reinitialized. A value of 0 means never reinitialize. The default is 2048.

concurrency_limit = n

Specifies how many concurrent requests PureMessage can service at any given time. The default is calculated based on the physical memory available on the system.

concurrency_limit_action = wait|tempfail|accept

This option is meaningful only when the process pool is disabled, which is not a recommended mode of operation in recent versions of PureMessage. As such, this option is purely of historical interest. See max_pooled_procs.

To use this option, max_pooled_procs must be zero, and the use_threads option must be enabled. Run pmx config to determine these values.

This option specifies the action to take if the concurrency_limit is reached. Valid option values are 'wait', 'tempfail' or 'accept'. The default is 'tempfail'.

debug_level = n

Where n is a number from 0-9.

Selects the verbosity in the milter log specified in the log_to option (as described above). Higher numbers result in more verbose logging. The default is 0, which means log messages with 'DEBUG' priority are suppressed.

time_connection = i<on|off>

When enabled, a log entry is written to the milter log specified in the log_to option for the time spent on each connection. The default is 'off'.

time_message = on|off

When enabled, a log entry is written to the milter log specified in the log_to option for the time spent on each message. The default is 'off'.

active_mta = postfix

The mail transfer agent currently used by PureMessage. The default MTA is Postfix.

avoid_message_splitting = false|true

This capability is turned off by default because user-specific language preferences require per-recipient functionality, which in turn requires receiving the entire message in order to process it.

To configure PureMessage to process messages before all data is received, add avoid_message_splitting = false to pmx.conf. This disables user-specific language settings; only the default language preference is used. Per-recipient tests in the policy script ignore this option. This option is only recommended if you want to increase performance by rejecting or discarding messages early, and you have no need for per-recipient functionality.

language = aa

Where aa is a ISO 639 two-letter language code.

This sets the default language for the PureMessage installation.

!include pmx.d/*.conf

Provides compatibility with PureMessage 3.0-based filters.

max_proto_data_size = n

This is a low-level option that is not meant to be used without advanced knowledge of PureMessage internals.

Sets the limit (in bytes) for the size of data used in protocol operations. Among other things, the limit applies to the total size of header data allowed in messages. The default value is 65535.

This limit can only be changed to a value that the connecting MTA will be capable of supporting.

quarantine_type = pmdb|dir

Indicates the type of quarantine that will be used. The options are pmdb (PureMessage database, as specified in pmx_db) or dir (Filesystem based indexes).

pmx_db = postgres

Indicates the DBMS used as the PureMessage database. Only postgres is currently supported.

Note: In accordance with RFC 2822, the default behavior of PureMessage is to alter the Message-ID header whenever any of the message parts have changed. The following options allow you to alter this behavior to suit your environment. It is recommended that you contact support before applying either of these options.

preserve_msgid = 1

Edit pmx.conf to include this setting if you prefer to opt out of the default behavior and always preserve the Message-ID, regardless of what part of the message has been changed.

preserve_msgid_hdr_change = 1

This option provides an alternative to the preserve_msgid setting described above. Edit pmx.conf to include this line if you do not want message header changes to trigger the generation of a new Message-ID. Only changes to the message body will result in a new Message-ID. If preserve_msgid = 1 is also specified, then that setting will override this one.

quarantine_preserve_env_from = 1

Adding this option preserves the contents of the Envelope From address, so that the original sender of the message is identified. If this option is not present, or if it is set to ``0'', messages that have been released from the quarantine will have the postmaster address as the Envelope From address. After adding the option, you must run pmx-manager restart to make the change take effect, or, if you are viewing and searching the quarantine via the Groups Web Interface, run pmx-httpd restart.

NAME

SYNOPSIS

DESCRIPTION

MILTER AND FILTER BLOCKS

GENERAL SETTINGS

SEE ALSO

COPYRIGHT