Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Messaging Server 6 2005Q1 Administration Reference 

Chapter 5
Messaging Multiplexor Configuration

This chapter describes the Messaging Multiplexor configuration. This chapter contains the following sections:


To configure HTTP user mailboxes (for example, Messenger Express), see the chapter “Configuring and Administering Multiplexor Support” in the Sun Java System Messaging Server Administration Guide.

Encryption (SSL) Option

The Sun Java System Messaging Multiplexor supports both unencrypted and encrypted (SSL) communications between the Messaging Server(s) and their mail clients.

When SSL is enabled, the MMP IMAP supports both STARTTLS on the standard IMAP port and IMAP+SSL on port 993. The MMP can also be configured to listen on port 995 for POP+SSL.

To enable SSL encryption for IMAP and POP services, edit the ImapProxyAService.cfg and PopProxyAService.cfg files, respectively. You must also edit the default:ServiceList option in the AService.cfg file to include the list of all IMAP and POP server ports regardless of whether or not they are secure.

To enable SSL encryption for SMTP proxy services, edit the SmtpProxyAService.cfg file.

By default, SSL is not enabled since the SSL configuration parameters (Table 5-1) are commented out. Install a certificate as documented in the Sun Java System Messaging Server Administration Guide. To enable SSL, un-comment and set the following parameters:

Table 5-1  SSL Configuration Parameters 




Port number to which the MMP will try to connect on the store servers for SSL. If this parameter is not set, the MMP will not use SSL when connecting to the store.

There are no default values, but ports 993 and 995 are recommended for IMAP and POP, respectively.

This parameter does not apply to SMTP proxy.


SSL session cache directory.

The recommended value is the msg_svr_base/config directory.


This has been replaced by the option SSLCertPrefix.


Nicknames of the certificates in the SSL certificate database to offer as the server certificate.

The recommended value is Server-Cert.


Filename prefix to the SSL certificate database file. The certificate database file must be in the directory specified by the SSLCacheDir setting. The recommended value is ““.


Whether or not to enable SSL. If set to “True”, “Yes” or “1”, Multiplexor will activate the STARTTLS (for IMAP, SMTP) or STLS (for POP) command. To activate SSL on separate ports, this must be set in addition to the SSLPorts option.

If SSL is enabled, all of the following variables must be set. You can specify an empty parameter with empty quotes (““).


The default is no (SSL is not enabled).


Key database file location (defined when you obtained a certificate for this server). Multiplexor requires a private key corresponding to its SSL server certificate. The location specified here should be absolute, not relative to the Multiplexor installation directory.

The recommended value is msg_svr_base/config/key3.db.

Be sure to protect this file so only the multiplexor and other authorized servers can read it.


File location for the passwords that protect access to the private key file. Passwords may be null if the key is not password-protected.

The default is msg_svr_base/config/sslpassword.conf.


Ports on which SSL will be turned on (accepted SSL connections). Syntax is:

[ IP ":" ] PORT [ "|" [ IP ":" ] PORT ]

For example: 993| means connections to any IP on port 993 and localhost on port 1993 get SSL on accept.

There are no default values, but ports 993 and 995 are recommended for POP and IMAP, respectively. Note that even if you set a port, the MMP will not actually accept connections to that port until it is included in the ServiceList (see “Multiplexor Configuration Parameters” on page 318). If this parameter is not set, and SSLEnable is set to “true” or “yes,” then only IMAP STARTTLS is enabled.


Security module database file location. If you have hardware accelerators for SSL ciphers, this file describes them to the Multiplexor.

The recommended value is secmod.db.

Multiplexor Configuration

This section describes how to configure the Messaging Multiplexor.

Multiplexor Configuration Files

To configure the Multiplexor, you must manually edit the configuration parameters in the Multiplexor configuration files, which are listed below in Table 5-2.

Table 5-2  Messaging Multiplexor Configuration Files 




Configuration file specifying configuration variables used for POP services.


POP services configuration template. If the PopProxyAService.cfg file does not exist, the PopProxyAService-def.cfg template is copied to create a new PopProxyAService.cfg file.


Configuration file specifying configuration variables used for IMAP services.


IMAP services configuration template. If the ImapProxyAService.cfg file does not exist, the ImapProxyAService-def.cfg template is copied to create a new ImapProxyAService.cfg file.


Configuration file specifying which services to start and a few options shared by both POP and IMAP services.


Configuration template specifying which services to start and a few options shared by both POP and IMAP services. If the AService.cfg file does not exist, the AService-def.cfg template is copied to create a new AService.cfg file.


Optional configuration file specifying configuration variables used for SMTP proxy services. Required if you enable POP before SMTP; useful for maximizing support for SSL hardware even if POP before SMTP is not enabled. For more information on POP before SMTP, see the Sun Java System Messaging Server Administration Guide.


Configuration template specifying configuration variables used for SMTP proxy services. If the SmtpProxyAService.cfg file does not exist, the SmtpProxyAService-def.cfg template is copied to create a new SmtpProxyAService.cfg file.

As an example, the LogDir and LogLevel parameters can be found in all configuration files. In ImapProxyAService.cfg, they are used to specify logging parameters for IMAP-related events; similarly, these parameters in PopProxyAService.cfg are used to configure logging parameters for POP-related events. In AService.cfg, however, LogDir and LogLevel are used for logging MMP-wide failures, such as the failure to start a POP or IMAP service.

The following configuration parameters are defined in the AService.cfg file:

For descriptions of these parameters, see “Multiplexor Configuration Parameters.

The Multiplexor configuration files are stored in the msg_svr_base/mmp-hostname directory, where msg_svr_base is the directory where you installed the Messaging Server and mmp-hostname is the subdirectory named after the MMP instance.

Multiplexor Configuration Parameters

You control how the MMP operates by specifying various configuration parameters in the MMP configuration files.

Table 5-3 describes the parameters you can set:


To allow configuration parameters for different instances to be specified in the same configuration file, all the parameters are preceded with “default:” to indicate the default section. See the ServiceList parameter in Table 5-3 for more information.

Table 5-3  Multiplexor Configuration Parameters 




The MMP can cache results of pre-authentication. The AuthCacheSize parameter defines the number of cache entries; AuthCacheTTL defines the length of time that entries are preserved in seconds. Lower values will reduce performance, but result in faster recognition or server password changes. Higher values will increase performance, but result in delayed recognition of server password changes.

A higher setting for AuthCacheSize improves performance while using more memory. A lower setting reduces performance and reduces the amount of memory used.

AuchCacheTTL controls how long a cachec entry remains in cache. Changes made to an entry in LDAP are not seen by the MMP until the entry’s TTL has expired. If you wish to have password changes seen at least every 15 minutes by the MMP, then set this value to 900.

These variables are only applicable when PreAuth is set to yes.

The default AuthCacheSize is 10,000; the default AuthCacheTTL is 900.

This options does not apply to SMTP proxy.


A space-separated list of additional LDAP attributes to look up and pass to the third-party authentication server specified by the AuthenticationServer option.


This specifies the hostname and port for a third-party authentication service to use with the MMP. The recommended value is when a third-party authentication service is available on the same machine as the MMP. For developer instructions and SDK see the directory msg_svr_base/examples/tpauth.

When not set, the MMP will authenticate via LDAP. This parameter is ignored unless the PreAuth option is set to yes. This parameter does not apply to the SMTP proxy.


If AuthService is set to yes and AuthServiceTTL is non-zero, the MMP will allow queries about who is currently logged into the MMP, for the purpose of POP before SMTP relay authentication. AuthServiceTTL represents the amount of time in seconds that an authentication record is kept valid.

The default for AuthService is no; the default AuthServiceTTL is -1.

The AuthService parameter should almost never be turned on globally; you should configure this by virtual domain. Setting the AuthService parameter to yes permits probing of the AuthService cache with the xqueryauth ip-address command over the POP protocol.

For POP before SMTP service, AuthServiceTTL should be set to a value greater than 0 in the PopProxyAService.cfg file. For all other MMP proxies (SMTP and IMAP), AuthServiceTTL should be omitted or set to -1. By default, the AuthServiceTTL parameter is found only in the PopProxyAService.cfg configuration file.


Port on which to connect to message store server. This parameter lets you run a multiplexor and a store server on the same machine, with the store server on a different port. You might want to do this if you want a flat configuration—that is, if you want to run Multiplexors on all machines.

This option does not apply to SMTP proxy. The SmtpRelays parameter provides equivalent functionality for the SMTP proxy.

The default is 110 for POP3; 143 for IMAP (the standard ports).


Banner replacement string. The MMP will use the string you specify for its greeting line.

The default banner string contains the software name and version information.

BeTheUser and BeTheGroup

BeTheUser and BeTheGroup are the user ID and group ID of the MMP, respectively, once it has started listening for connections. These values are set by the Messaging Server configure installation program. These variables are applicable to UNIX only and are ignored on Windows platforms.

The BeTheUser and BeTheGroup parameters are only found in the AService.cfg configuration file.


BadGuys configuration parameters. When an authentication failure occurs from a particular client IP address, subsequent authentication attempts from that IP address are treated as “BadGuys” and are delayed. If an authentication failure is followed by a successful authentication, the successful authentication is delayed, but the IP address ceases to be treated as a “BadGuy” for subsequent attempts.

BGMax is the maximum number of BadGuys to keep track of simultaneously (default is 10,000).

BGPenalty is the length of time in seconds added to a BadGuy’s sentence if he/she fails authentication (default is 2).

BGMaxBadness is the maximum penalty in seconds for authentication failure (default is 60).

BGDecay represents the time in seconds it takes for a BadGuy’s penalty to be forgiven (default is 900).

BGLinear defines whether a BadGuy’s penalty decays linearly over time, or is a step function on expiration (default is no, which means the penalty decays as a step function on expiration).

BGExcluded represents a list of excluded IP/mask pairs, or the name of a file to read for these pairs. These client addresses will not be penalized for authentication failure (there is no default value).

The BadGuys parameters apply even when PreAuth is disabled. These parameters do not apply to SMTP proxy.


Distinguished Name and password used to authenticate to the Directory Server. The BindDN must have privileges to access the BaseDN as specified by the LdapURL.

The Messaging Server default directory ACIs require a bind to authenticate users against the Directory Server.

These options can be found in the ImapProxyAservice.cfg and PopProxyAservice.cfg configuration files. These parameters do not apply to SMTP proxy.


Canonical virtual domain delimiter. The character used by the MMP to separate the user ID from the appended virtual domain when talking to the message store server and formatting queries for the LDAP server.

The default is @, so user IDs passed to LDAP and the message store servers have the form userid@virtual.domain.

This parameter does not apply to SMTP proxy.


Capability replacement string. The MMP will use the string you specify for Capability instead of its default (own) capability to tell IMAP clients what it (or the servers behind it) can do. This variable has no effect in POP3.

There is no need to adjust this string if the backend IMAP servers are entirely Sun Java System servers from the same version of the messaging server installer. Otherwise, it is important to specify a capability list that includes only the features supported by all the backend IMAP servers. The appropriate string can be determined by telnetting to port 143 on each kind of backend server and entering the command c capability. This lists only the capabilities present on all backend IMAP servers.

The default Capability string is as follows (with no line breaks):


When Messaging Server 5.2 backend mail stores are used, the BINARY option should be omitted.

This parameter does not apply to SMTP proxy. The EhloKeywords parameter provides a semi-equivalent function for the SMTP proxy.


This option is equivalent to UserGroupDN and is deprecated in favor of the new name (UserGroupDN takes precedence over this setting).


The name of the certmap file (for SSL client-cert-based authentications).

There is no default.

The recommended setting is msg_svr_base/config/certmap.conf


Performs a DNS reverse lookup on the client IP address when set to yes. The reverse lookup is performed unconditionally, so the SMTP relay server does not need to perform it. This option may be set on a per hosted domain basis.

The ClientLookup parameter provides a performance benefit for SMTP, but has no benefit when used with POP or IMAP. Note that a DNS lookup is performed regardless of this setting if hostnames are used in a global TCPAccess filter or a per-domain or per-user access filter.

This option defaults to no. For example:

default:ClientLookup yes


Limits the number of simultaneous connections permitted from a single client IP address.

A comma-separated list of entries in the following form:

IP “|” MASK “:” NUM

or the path and name of a specific file containing one or more of these entries; each entry on its own line. The entries should be listed from the most specific IP-MASK pairs to the least specific.

The default is|


Boolean indicating whether or not to enable Challenge-Response Authentication Mechanisms (CRAMs) including APOP and CRAM-MD5. For this to work, passwords must be stored in LDAP in plain text format and the BindDN must have read access to the userPassword attribute.

The default is no. This parameter does not apply to SMTP proxy.


When POP and IMAP users authenticate, they typically provide an unqualified user ID (a user ID without a domain portion). The value of the DefaultDomain parameter is appended to unqualified user IDs. When used as an MMP virtual domain parameter, this allows a single MMP server with multiple IP addresses to support unqualified user IDs for multiple hosted domains. This may also be set as a service-wide parameter.

This parameter does not apply to SMTP proxy.


A list of EHLO extension keywords for the proxy to pass through to the client, in addition to the default set. The MMP removes any unrecognized EHLO keywords from the EHLO list returned by an SMTP relay. EhloKeywords specifies additional EHLO keywords which should not be removed from the list. The default is empty, but the SMTP proxy supports the following keywords (there is no need to list them in this option): 8BITMIME, PIPELINING, ENHANCEDSTATUSCODES, EXPN, HELP, XLOOP, ETRN, SIZE, STARTTLS, AUTH

The following is an example that might be used by a site which uses the rarely used TURN extension:

default: EhloKeywords TURN

This parameter is found only in the SmtpProxyAService.cfg file.


If a connection to an SMTP relay fails, the MMP avoids trying that relay for a number of minutes equivalent to the failover time-out. For example, if the failover time-out is 10 seconds, and a relay fails, the MMP does not try that relay again for 10 minutes.

The default is 10 seconds.


Boolean, whether to support HostedDomains.

If you are using the Sun Java System Messaging Server directory schema (Sun ONE LDAP Schema, v1 or Sun ONE LDAP Schema, v2), this should be set to the default “Yes.”

If set to no, then the MMP assumes the server supports only one domain and LdapUrl points to a directory subtree containing all users supported by the server, each user with a unique UID. Setting HostedDomains to “no” is not recommended as even a small company is likely to eventually go through a name change or acquisition where support for multiple domains would be helpful.

When set to yes, the MMP honors the following MTA options in the msg_svr_base/config/option.dat file:


These settings may be used to enable Sun ONE LDAP Schema, v2 with the MMP.

Defaults to Yes. This parameter does not apply to SMTP proxy.


The MMP can cache results of user searches. The LdapCacheSize parameter defines the number of cache entries; LdapCacheTTL defines the length of time the entries are preserved in seconds. Lower values will reduce performance, but result in faster recognition of LDAP user configuration changes. Higher values will increase performance, but result in delayed recognition of LDAP user configuration changes.

The default LdapCacheSize is 10,000; the default LdapCacheTTL is 900.

These parameters do not apply to SMTP proxy.


Seconds that the MMP will keep a connection open to the LDAP server. When the MMP notices the refresh interval has passed, the MMP will close the LDAP connection and open a new one.

The default is 2100 (35 minutes).


Pointer to the top of the site’s DC directory tree, if HostedDomains is set to yes (default). If HostedDomains is set to no, then LdapUrl points to a directory subtree containing all users supported by the server. This parameter must be set in order for the MMP to operate correctly.

SSL (LDAPS) is supported, but the SSL configuration must also be correct, and SSL-enabled. To enable failover, the host part of the URL may be a space-separated list of hosts. Be sure to enclose the entire URL in double-quotes if it contains a space. For example:

"ldap://ldap1 ldap2/o=internet"

The default is ldap://localhost/o=internet.

This parameter does not apply to SMTP proxy.


LogDir is the directory in which the MMP creates log files. If you specify a directory that does not exist, no log file is created. Log file names are distinguished by their specific service; for example, an IMAP log file would have the format ImapProxy_yyyymmdd.log .

LogLevel represents the logging verbosity level—the amount of information written into log files. You can specify a number from 0 through 10, with 10 representing the highest level of verbosity. The higher the level, the more information in the log.

LogDir and LogLevel are present in all configuration files: ImapProxyAService.cfg, PopProxyAService.cfg, AService.cfg, and SmtpProxyAService.cfg.

The default LogDir is msg_svr_base/data/log and the default LogLevel is 1.


Space-separated list of LDAP attributes identifying the user’s mail host. Multiplexor tries each attribute returned by the search in the order specified by the list.

The default is mailHost. This parameter does not apply to SMTP proxy.


The maximum number of worker threads to allocate. If the machine has multiple CPUs, running the Multiplexor with worker threads will improve performance. The optimal number of work threads is the number of processors on the machine. For example if your machine has two CPUs, specify 2.

This parameter is only found in the AService.cfg configuration file.

The default is 1.


Name of an MTA channel to use for POP before SMTP authorized connections. The default is empty and the typical setting for users who want to enable POP before SMTP is tcp_intranet. For example:

default:PopBeforeSmtpKludgeChannel tcp_intranet

This parameter is only found in the SmtpProxyAService.cfg configuration file.


Enables pre-authentication by the MMP. When PreAuth is set to yes, a user is authenticated against the LDAP server before a connection is made to the backend mailstore server. When PreAuth is set to no, the MMP connects to the backend mailstore server and simply replays the authentication information. Because of the additional authentication step, PreAuth reduces the overall performance, but protects the backend mailstore servers from denial-of-service attacks by unapproved users. PreAuth is mandatory for the POP-before-SMTP and BadGuys features of the MMP.

When using HostedDomains, the mailAccessProxyPreAuth attribute in the domain node in the LDAP server overrides this option.

The default is no. This parameter does not apply to SMTP proxy.


Printf-style format string that says how to construct the user ID for replay to the Message Store server. Valid escape sequences are:

%U (userid only)
%V (virtual domain only)
%A[attr] (value of user’s attribute "attr")

For example, %A[uid]@%V for a user with joe as the user ID and would yield:

When using HostedDomains, the mailAccessProxyReplay attribute in the domain node in the LDAP server overrides this option.

The default is %U. This parameter does not apply to SMTP proxy.


When set to yes, this will forbid use of plaintext passwords unless an SSL/TLS security layer is active.

Defaults to no.


A printf-style format string with which to construct Users/Groups LDAP queries for the user’s mailhost when virtual domains are enabled. valid escape sequences are:

%o (original login id entered by the user)
%s (userid+virtualdomain)
%U (userid only)
%V (virtual domain only)
%C (client IP address)
%S (server IP address)
%D (client cert DN)

The default value is uid=%U if HostedDomains is yes, and uid=%s if HostedDomains is no.

Note that when using HostedDomains, the inetDomainSearchFilter attribute in the domain node in the LDAP server overrides this option.

This parameter does not apply to SMTP proxy.




IMAP only. String returned to client in an IMAP ALERT message when the MMP cannot connect to a user’s store server.

The default string is “Your IMAP server appears to be temporarily out of service.”


Specifies which services to start and the ports/interfaces on which the MMP will listen for those services. Services are listed all on a single line in the following format:


Where DLLNAME is the absolute pathname and filename to the AService DLL you want to load (minus the DLL file extension, .so, .dll, etc.). If no DLLNAME is specified or the one(s) specified cannot be loaded and initialized, the AService daemon will exit. Customer-supplied DLLs (shared libraries) are not supported.

The INSTANCENAME represents the name of the configuration file to use for IMAP, POP, or SMTP services (minus the .cfg extension, so the defaults are ImapProxyAService, PopProxyAService, and SmtpProxyAService, respectively). INSTANCENAME can also take an optional SECTION parameter which allows configuration for different instances to be stored in the same config file. Use of SECTION is not recommended and it will be removed in a future release. The default SECTION is default.

The ServiceList parameter is only found in the AService.cfg configuration file.

The default ServiceList entry is shown below (all on one line):

msg_svr_base/lib/ImapProxyAService@143|993 msg_svr_base/lib/PopProxyAService@110


Password used to authorize source channel changes on the SMTP relay servers. This option is mandatory with no default and must match the PROXY_PASSWORD option from the SMTP channel option file. For example:

default:SmtpProxyPassword password

This parameter is only found in the SmtpProxyAService.cfg configuration file.


A space-separated list of SMTP relay server hostnames (with optional port) to use for round-robin relay. These relays must support the XPEHLO extension. This option is mandatory with no default. For example:

default:SmtpRelays sesta:485 gonzo mothra

This parameter is only found in the SmtpProxyAService.cfg configuration file.


Defined in the PopProxyAService.cfg file. If this option is set to “on” (default is off) and the user’s server is unavailable, the MMP will simply return an empty mailbox listing. Turning this option on will override the SpoofMessageFile config keyword.


The file to use for POP3 inbox spoofing. The MMP can imitate a base-functionality POP3 server in case it can’t connect to a client’s store machine. In such a situation, the MMP creates an inbox for the user and places this one message into it. The format of the message contained in this file should conform to RFC 822 (including the final  '.').

By default, there is no spoof message file.


StoreAdmin represents the user name of the store administrator for proxy authentication necessary to support SSL client certificates and RFC 2595-style proxy authentication. There is no default for StoreAdmin or StoreAdminPass.

This parameter does not apply to SMTP proxy.


Wrap-style filters that describes TCP access control for the MMP (globally).

See “Configuring Client Access to POP, IMAP, and HTTP Services” in the “Configuring Security and Access Control” chapter of the Sun Java System Messaging Server Administration Guide for the syntax description of this option.

Defaults to NULL.


Per-user attribute that contains a wrap-style filter describing the TCP access control for the user.

Defaults to mailAllowedServiceAccess.


Session timeout in seconds. To be standards-compliant, the value of this parameter must not be set lower than 1800 seconds (30 minutes) for IMAP, 600 seconds (10 minutes) for POP or SMTP.

The default is 1800 seconds.


This specifies the baseDN for user, group and domain searches in Sun ONE LDAP Schema, v2 mode. It is also used for client certificate mapping lookups in Sun ONE LDAP Schema, v1 mode.


String of acceptable virtual domain delimiters. Any character in this string will be treated as a domain delimiter in a user ID received by the MMP. (The MMP searches user IDs from the end.)

The default delimiter is @. This parameter does not apply to SMTP proxy.


The name of the file containing your virtual domain mapping.

The recommended setting is msg_svr_base/config/vdmap.cfg. Uncomment this line in the configuration file to enable support for virtual domains.

Starting the Multiplexor

To start, stop, or refresh an instance of the Messaging Multiplexor, use the one of the following commands in Table 5-4 located in the msg_svr_base/sbin directory:

Table 5-4  MMP Commands 



start-msg mmp

Starts the MMP (even if one is already running).

stop-msg mmp

Stops the most recently started MMP.

refresh mmp

Causes an MMP that is already running to refresh its configuration without disrupting any active connections.

Previous      Contents      Index      Next     

Part No: 819-0106-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.