ecelerity.conf

ecelerity.conf — Momentum configuration file

The ecelerity.conf file is the master configuration file for the Momentum application server.

The easiest way to manipulate this file is through the web UI. If you make manual changes to this file be sure to use eccfg to commit your changes. For more information see eccfg and “Best Practices for Manually Changing Configuration Files”.

The default search path for config files is:

Options such as max_outbound_connections are simple configuration options while other configuration options define data structures. For example, the security option (or scope) has user and group options. Complex configuration options are as follows:

Configuration options defined at the top level of the ecelerity.conf file are defined in a global scope. Many of these options can be defined in other scopes for a more fine-grained configuration. For example, the max_outbound_connections option can be set globally to apply to all outbound connections or within a domain scope to apply to a specific domain only. You can also set it in both scopes if you wish. For a discussion of which value applies in which circumstances see “Configuration Scopes and Fallback”.

The various modules that extend the functionality of Momentum are also scopes. The clamav module for example, makes it possible to use ClamAV anti-virus scanning from within Momentum. Modules and their configuration options are discussed in the Modules Reference .

In common with many other Unix configuration files, the ecelerity.conf file uses the # (commonly referred to as "hash", "pound" or "octothorpe") symbol to introduce a single line comment. Whitespace is unimportant in the various configuration stanza; feel free to pad the whitespace as you see fit for maximum readability.

If the values assigned to any options contain whitespace or any of the characters ‘#’, ‘/’, ‘"’, ‘'’, ‘=’, ‘{’, ‘}’, ‘[’, ‘]’, ‘(’, ‘)’ they must be enclosed by quotation marks. Note that binding names cannot contain spaces.

All configuration options are case insensitive. For example, you can define an SMTP listener as ESMTP_Listener or esmtp_listener.

You may use C-style comments in your ecelerity.conf. C-style comments begin with /* and end with */. Any text between those two markers will be ignored by Momentum. C-style comments do not nest.

You may also break apart your configuration into multiple files and reference them using the include statement.

include "/opt/msys/ecelerity/etc/other.conf"

If you break up your configuration file into a number of different files you will need to add these new files to the repository. For instructions on adding configuration files to the repository see “Best Practices for Adding Configuration Files”.

For included files, the directory that holds the file being included from is checked before the default search path.

You may also use the include statement to allow the inclusion of a directory. When the referenced path is a directory, all the files within that directory are included in lexical order. Hidden files (those whose names begin with a single period) are not included. Sub-directories are not automatically processed.

In a cluster configuration, the eccluster.conf file is "included" from the ecelerity.conf file and configures cluster-related options.

You may split the configuration into multiple files using not only an 'include' directive but also the 'readonly_include' directive. As with the 'include' directive, 'readonly_include' is valid in any scope. 'readonly_include' also supports making online changes to the configuration with the 'config set ' and 'config unset ' commands. For more information see config.

When making an online change, Momentum must decide which of the multiple configuration files to save online changes to. This decision is controlled by the following factors:

• The Local_Changes_File option

• The Local_Changes_Only option,

• The read-only status of a particular configuration file

• Whether the operation being performed is replacing an old value with a new one, or setting a value that has not previously been set

**Readonly 'include' Files. ** Any configuration files included with the 'readonly_include' directive are read-only. Any configuration files included multiple times (overall, not necessarily from the same file) are read-only. Any configuration files loaded from a URI with a scheme other than 'file://', 'persist://', for example, are read-only. All other configuration files are considered writable.

The Local_Changes_File option sets the name of a configuration file which must be writable, and which is implicitly loaded after all other configuration files regardless of its placement in the configuration file. Since it must be writable and files included twice are read-only, the Local_Changes_File option cannot point to the same file as any 'include' directive, and it cannot point to the main configuration file. Since the Local_Changes_File is effectively loaded at the end of the main configuration file, options set in it are able to override any setting in any other configuration file; if it were loaded at some other point, options set after that point could not be overridden by it.

If the Local_Changes_File option is not defined, and the main configuration file is writable, then changes are written to the main configuration file. If Local_Changes_File is not defined, and the main configuration file is read-only, then a virtual file, not associated with any real path is used to hold changes; in this case, the config writeback command will issue a warning stating that not all portions of the configuration could be saved, and show the contents of the virtual file. This situation can be remedied by setting the Local_Changes_File to a valid path and issuing the config writeback command again, at which point changes in the virtual file will be saved to the newly configured location.

The Local_Changes_Only option defaults to 'false'. If it is 'true', the Local_Changes_File option must be defined and all changes are saved to the Local_Changes_File. If it is 'false', changes are distributed as described below:

• When replacing a value that has previously been set, if the file it was last set in is writable then the change is made in-place; the new option value replaces the old option value at the same location in the writable file.

• If replacing a value that was last set in a read-only file or setting a value that was not set previously, then the change will go to the lexically first writable file in which the scope instance containing the change was defined.

For an example of the lexically first writable file assume that ecelerity.conf is configured as follows:

and foo.conf contains:

Options set for the first time by commands starting with config set Domain yahoo.com will be saved in bar.conf, since foo.conf is read-only and baz.conf occurs after bar.conf. The change made by config set Domain yahoo.com gateway "server2.yahoo.com" would also end up in bar.conf, since the original location, foo.conf, is read-only, and bar.conf is the first writable location after it.

Finally, if the scope instance containing the change was only encountered in read-only files or not at all, then the change will be saved to the file defined by the Local_Changes_File option. Note that changes, even committed changes, are accumulated in in-memory representations of the configuration files and are not saved to disk until a config writeback command is issued.

It is possible to bypass validation modules by adding a context variable to your listener. Do this by creating a context variable with the name _bypassmodule_name and setting its value to true. For example, to bypass the spf_v1 module create a variable called __bypass_spf_v1 and set its value to true. To determine whether a module is a validation module see “All Modules”.

Momentum is built around a powerful event based scheduling engine. A key part of that engine is responding to events that occur on inbound sockets, known as listeners.

The basic listener syntax is as follows:

The *:25 is an example of an address; multiple addresses can be specified for a given listener, allowing you to configure service on multiple IP/port or Unix sockets.

When using any listener, if you change from listening on a specific IP address to listening on the "wildcard" address (*) or the reverse, you must issue the config reload command twice in order to reactivate the listener. This applies to Linux systems only.

Momentum supports three major types of listener for serving SMTP, Control and ECStream clients.

As of version 3.1.4, Momentum also supports an HTTP_Listener that is used with the REST Injection API. For more information see "HTTP_Listener".

For a complete list of the options that are valid within a listener see Table 9.25, “listener options”.

Configures the end-point(s) on which Momentum should listen for incoming control connections (made via ec_console or the web console). For local-only configurations, a Unix domain socket may be appropriate. If your network is reasonably secure, you can specify an IPv4 address and port for TCP/IP services.

In this case the file_mode option is set to 0666. With the socket file permission set to 0666, every user who can log in to the system can use ec_console to connect to the server.

The Control_Listener supports a number of extended properties including ALWAYS-ALLOW, LOGIN and DIGEST-MD5. For more information see “Configuring Authentication for the Control Listener”.

For information regarding IPv6 addresses and Listen stanzas, see the section called “Listeners and IPv6 Addresses”.

Configures the end-point(s) on which Momentum should listen for incoming SMTP connections. This list can contain any number of Unix domain sockets and/or IP:port addresses for TCP/IP service.

The ESMTP_Listener supports all of the extended properties and extensions described below.

The Pool_Name option associates the accept-pool ThreadPool with the listener. Concurrency should have a value that is equal to or less than the concurrency defined in the ThreadPool.

When using threaded accepts for listeners, you must now explicitly provision the thread pool you intend to use via the ThreadPool directive. If the thread pool you name is not found, or is unspecified, the IO pool will be used and a critical message will appear in your log. In version 2.2 if the pool didn't exist, the listener subsystem would create it for you.

Listen stanzas map 1:1 to an underlying socket, this means that :25 (which is the same as *:25) binds to IPv4 (and perhaps IPv6, depending on the kernel); for explicit IPv6, use [*]:25 instead. This change makes it possible to suspend and enable listener sockets individually on the fly. If you wish to disable the listener on port 25, as shown in “ESMTP_Listener”, issue the command config set esmtp_listener listen :25 enable false from the system console. You can use config set, get or eval with any one of the listener subsystem options. This applies to ESMTP_Listeners and Control_Listeners.

Note that Listen_Backlog has a new default value and can now be set higher than 200. Also note that the enable option is used in the listener scope to enable or disable a listener or listen scope and not enabled .

IPv6 addresses are case insensitive and can use ‘::’ for zero suppression. For this reason, the same address can be expressed in a variety of ways. The following examples all represent the same IPv6 address (example adapted from http://tools.ietf.org/html/rfc5952 ):

The ‘::’ can only appear once in an address.

When a Listen stanza uses an IPv6 address, you are required to enclose the IPv6 address in square brackets, followed by a colon and the port, with quotes around the entire address:port. For example:

Use of square brackets is also required when defining IPv6 ECCluster_listeners and and Control_Listeners.

IPv6 addresses are much more flexible than IPv4 addresses in terms of their formatting options. They also use a different delimiter character than IPv4 addresses (a colon instead of a period). This means that in certain contexts, an IPv6 address can create parsing ambiguities.

The accepted convention is to require that, in circumstances where a configuration parameter can also contain something other than an IP address, that an IPv6 address must be enclosed in square brackets. In practical terms, this means that things like the Gateway, Routes and Listen options must have IPv6 addresses enclosed in brackets. Others, such as Peer, Relay_Hosts and Prohibited_Hosts do not require the IPv6 address in brackets.

Inbound SMTP connections check if the configuration has changed between messages and while handling the RSET command. If the connection discovers that it is using an old configuration, a 421 code will be returned in response to the MAIL FROM or RSET command that triggered the check, and the connection will be closed. The message that accompanies the 421 code is configurable via the Reconfig_Message setting in the ESMTP_Listener scope, and defaults to "4.3.2 Reconfiguration in progress".

Issuing the system console command config reload while receiving email will trigger this message.

Configures the end-point(s) on which Momentum should listen for incoming ECStream connections. This list can contain any number of Unix domain sockets and/or IP:port addresses for TCP/IP service.

The ECStream protocol is a bare-bones, high performance injection mechanism. It does not support any extended properties.

The ECStream_Idle_Time is the number of seconds of inactivity before a client is disconnected. This option is valid in the ECStream_Listener and within the Listen and the Peer scopes within an ECStream_Listener. The default value is 300. The ECStream_Max_Batch_Size option specifies the maximum number of ECStream messages to accept before dropping back into the scheduler. If users are having problems with the MTA becoming unresponsive when injecting messages via ECStream, it can be useful to set this to 1. The default value for this option is 10000.

When delivering mail via ecstream, do not use the routes option. Use gateway instead.

Not all listener options are valid within the ECStream_Listener or the Listen scope within an ECStream_Listener. Find below a table of those that are valid.

The ecstream_idle_time and ecstream_max_batch_size options are only valid within the ECStream scope or a listen scope within this scope. They are also the only options valid in the ECStream::Peer scope or ECStream_Listener::Listen::Peer scopes. For more information about these options see Table 9.25, “listener options”.

For information regarding IPv6 addresses and Listen stanzas, see the section called “Listeners and IPv6 Addresses”.

If you are adding an ECStream_Listener using the web UI, you must first add the ecstream module. You cannot configure ECStream options until the ecstream module has been added.

If you are using the web UI and you manually change the ecelerity.conf file, be sure that the ecstream module appears before the ECStream_Listener.

**Configuration Change. ** This feature available as of version 3.6.

In version 3.6, multiple event loops are introduced. If you have purchased a multiple event loop license (the "Supercharger" license) you can associate mail delivery and reception with an event loop threadpool so that performance scales with multi-core CPUs.

The "Supercharger" license specifies a maximum number of event loops. When configuring an event loop, the concurrency option in the eventloop scope cannot exceed the licensed number of event loops. For more information see “Configuring for Multiple Event Loops in Momentum 3.6”.

A typical configuration would be as follows:

The event_loop option is valid in the esmtp_listener, the ecstream_listener, the http_listener and the listen scopes within those scopes. These options should not be used in the control_listener scope. You cannot currently configure an XMPP listener to use the event loop.

In order to use this option you must have a "Supercharger" license. For more information see “Configuring for Multiple Event Loops in Momentum 3.6”.

Changing the value of event_loop at runtime requires restarting the ecelerity process—issuing the ec_console command config reload will not suffice.

For a detailed discussion of IPv6 syntax see the section called “Listeners and IPv6 Addresses”.

This example shows a Listener configured on a Unix domain socket located at /tmp/2025 with a maximum backlog of 500.

**Timeout Option. ** A 'Timeout' option that specifies a timeout for idle control connections has been added to Control_Listeners. This option has a default value of 60 seconds and makes the control_listener_timeout option obsolete.

It may be necessary to temporarily disable a listener; the enable option provides a convenient way to express this, without completely removing the listener from the configuration file, and without having to comment out the entire listener stanza.

The following stanza configures listeners on port 25 and port 587; Momentum will bind a listener to port 25 but will skip port 587 because it is marked as disabled.

Note that the enable option is used to enable or disable a listener or listen scope and not enabled . The enabled option applies only to modules and the enable applies only to listen or listener stanzas.

ACLs are implemented via the Peer scope, which uses the existing matching infrastructure to find the most specific CIDR match for a given configured value. Fallback works here too, allowing for some expressive configurations that are easily understood. For more information about fallback see “Configuration Scopes and Fallback”.

IPv6 addresses are much more flexible than IPv4 addresses in terms of their formatting options. They also use a different delimiter character than IPv4 addresses (a colon instead of a period). This means that in certain contexts, an IPv6 address can create parsing ambiguities.

The accepted convention is to require that, in circumstances where a configuration parameter can also contain something other than an IP address, that an IPv6 address must be enclosed in square brackets. In practical terms, this means that things like the Gateway, Routes and Listen options must have IPv6 addresses enclosed in brackets. Others, such as Peer, Relay_Hosts and Prohibited_Hosts do not require the IPv6 address in brackets.

Options defined in the Peer CIDR block 10.0.0.0/16 will apply to all IP addresses defined by this block unless the connecting IP address is 10.0.0.1. In that case, anything defined in the peer scope 10.0.0.1 takes precedence.

Note that SMTP extensions are defined using the SMTP_Extensions array. SMTP extensions are discussed in the section called “SMTP Extensions”.

The options that are valid within the Peer scope are listed in the following section.

The following Listener options can also appear in both the Listen and the Peer scopes.

These options are explained in the following:.

If client certificate verification fails, the SMTP session does not terminate. The TLS status is stored in pre-defined context validation variables so it is possible to drive TLS policy from policy scripts. You can use this to reject messages when client verification failed. For more information regarding the TLS-related context variables see Validation Context Variables .

A complete list of the options that can be used within the listener scopes follows:

Implements the receiving side of an XCLIENT capable interaction. XCLIENT allows trusted senders to alter the connecting IP address and other connection-level identifiers to appear to be someone they are not. This is used for internally trusted re-mailing. More information on XCLIENT can be found at http://www.postfix.org/XCLIENT_README.html .

Advertise support for the Enhanced-Status-Codes extension as defined in RFC 2034. ENHANCEDSTATUSCODE is the EHLO keyword value associated with this extension. This capability makes reporting of success and errors more precise.

Enables the dumping of connection and message contexts during an SMTP conversation via an XDUMPCONTEXT command. This is mainly useful for debugging.

This extension enables a connecting client to change the perceived IP address from which it connected. This is useful when the Momentum instance is deployed behind a trusted SMTP gateway. If enabled, then the remote client may, at anytime, present XREMOTEIP IP_address and Momentum will alter all identifying information to appear as if the client originally connected from the provided IP address.

XSETCONTEXT lets a client set name/value pairs in the connection level validation context. The extension takes a series of RFC1891 encoded parameters; each name=value pair sets the connection level validation context key "name" to value "value", overriding whatever other value was previously set (if any).

Since the extension can set arbitrary items in the validation context, it should be considered a trusted extension and should not be enabled for public Internet facing listeners, because there is a risk that an attacker can manipulate their way through a policy script. This also holds true for XCLIENT.

Set a name/value pair in the folowing way:

XSETCONTEXT option1=value1 option2=value2

If present, the connection will succeed and will automatically be authenticated as the anonymous user.

Implements the CRAM-MD5 authentication mechanism specified in RFC 2195. A "uri" parameter is required specifying which uri to use for authentication. As the CRAM-MD5 protocol does not make use of any secure precalculated values, the passwords stored in the file (if it is a file:// uri) must be stored in clear text.

To advertise this auth mechanism over SMTP, the "extension = AUTH" and "extension_argument = CRAM-MD5" must be specified.

Implements the DIGEST-MD5 authentication mechanism specified in RFC 2831. A "uri" parameter is required specifying which uri to use for authentication. DIGEST-MD5 supports secure precomputed values, so the passwords may be stored "hashed" or in clear text. By default, passwords returned from the provided uri should be hashed. If the parameter "stored_cleartext" is set to "true", the passwords will be expected in clear text and the hash will be computed internally before matching.

DIGEST-MD5 authenticates users within a given realm. This realm can be specified by adding a "realm" parameter valued as needed. If left unspecified, the server hostname will be used.

To advertise this auth mechanism over SMTP, the "extension = AUTH" and "extension_argument = DIGEST-MD5" must be specified.

Implements the LOGIN authentication mechanism specified in RFC 2222. A "uri" parameter is required specifying which uri to use for authentication. As the LOGIN protocol does not make use of any secure precalculated values, the passwords stored in the file (if it is a file:// uri) must be stored in clear text.

To advertise this auth mechanism over SMTP, the "extension = AUTH" and "extension_argument = LOGIN" must be specified.

Note that the LOGIN mechanism both stores passwords in clear text locally and transmits the username and password credentials in clear text over the network. This authentication mechanism (as defined by standards) is in no way "secure." It should be avoided unless absolutely necessary; if you must use it, use it in conjunction with TLS.

The various configuration options can be broken out into specific types. All the listener-related options are found in Table 9.25, “listener options” and module-specific options are documented in Modules Reference . The remaining types are:

• Bounce Processing Options – For a listing of bounce-related options see Table 9.3, “bounce options”.

• Compliance/Conformance Options – E-mail is built on top of a large number of different standards documents. By default, Momentum is configured to conform to and support all of those standards. However, in some deployments, it is sometimes desirable to detour from those standards in the interests of performance and manageability.

  These options allow you to detour from the various standards-defined behavior. In some cases this is partially allowed by the standards, but in others, it is frowned upon. Make sure you understand the impact of such changes before deploying them. For a complete list of RFC-related options see Table 9.13, “RFC options”.

• Logging – For a list of logging-related options see Table 9.7, “logging options”.

• Miscellaneous – A list of the remaining options is found at Table 9.8, “misc options”.

• Module-related (in a global scope) – There are module-related (as oppposed to module-specific) options visible in the global scope that affect specific modules. Find these options listed at Table 9.9, “module options”.

  Because there are so many adaptive options in the global scope, these options are listed separately at “Adaptive Options”.

• Resource Budgeting Options – Many options tune the resource consumption of Momentum, affecting memory consumption, disk I/O and concurrency. Find a listing of these options at Table 9.12, “resource options”.

• Routing Options – For a listing of routing-related options see Table 9.14, “routing options”.

• Security Options – For a listing of security-related options see Table 9.15, “security options”.

• SNMP Support – Momentum features a built-in SNMP agent that exposes real-time metrics for consumption by SNMP capable consumers or by third-party SNMP Managers. Momentum's SNMP agent supports and provides information for Mail Monitoring MIB (MTA-MIB) objects as specified in RFC 2789. Additionally, the agent provides Momentum product information objects, several system level MIB objects and extends the MTA-MIB. Momentum product objects, and MTA-MIB extensions are defined in Message System's enterprise MIB.

  SNMP configuration is described in detail in SNMP. For a complete list of SNMP options see Table 9.17, “SNMP options”.

• Timeout Configuration Options – For the options used to configure various different timeouts see Table 9.18, “timeout options”.

• TLS Options – For a listing of TLS-related options see Table 9.19, “TLS options”.

• Traffic Shaping Options – Many options affect the network traffic characteristics of Momentum, changing the rate at which inbound and outbound connections are accepted or initiated and the volume of traffic on those connections. Find a listing of these options at Table 9.16, “shaping options”.

• Virtual Hosting – For a listing of virtual hosting related options see Table 9.20, “virtual options”.