Chapter 6   Messaging Multiplexor


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

• Encryption (SSL) Option

• Multiplexor Configuration

Encryption (SSL) Option

---

The iPlanet 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 your 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.

By default, SSL is not enabled since the SSL configuration parameters (Table 6-1) are commented out. Install a certificate as documented in the iPlanet Messaging Sever Installation Guide. To enable SSL, un-comment and set the following parameters:

Table 6-1    SSL Configuration Parameters 

Parameter	Description
SSLBacksidePort	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.
SSLCacheDir	SSL session cache directory. The default is the server-root/mmp-hostname directory.
SSLCertFile	Server certificate database file location (defined when you obtained a certificate for this server). The MMP requires a server certificate to offer to clients in the handshake phase of SSL. The location specified here should be absolute, not relative to the MMP installation directory. The default is server-root/mmp-hostname/cert7.db.
SSLCertNicknames	Nicknames of the certificates in the SSL certificate database to offer as the server certificate. The default is Server-Cert.
SSLCipherSecs	A colon-separated list of ciphers (or the string "all") representing the cipher algorithms that this server can use to encrypt SSL sessions. The client and server agree to one of them when a session is established. The available cipher specifications are: SSL_RSA_WITH_RC4_128_ MD5 SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA SSL_RSA_WITH_3DES_EDE_CBC_SHA SSL_RSA_FIPS_WITH_DES_CBC_SHA SSL_RSA_WITH_DES_CBC_SHA SSL_RSA_EXPORT_WITH_RC4_40_MD5 SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 SSL_RSA_WITH_NULL_MD5 The default is "all".
SSLEnable	Whether or not to enable SSL. If set to "True" or "Yes", Multiplexor will listen on both normal and SSL ports. If SSL is enabled, all of the following variables must be set. You can specify an empty parameter with empty quotes (""). SSLPorts SSLCertFile SSLKeyFile SSLKeyPasswdFile SSLCertNicknames The default is yes (SSL is enabled).
SSLKeyFile	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 default is server-root/mmp-hostname/key3.db. Be sure to protect this file so only the multiplexor and other authorized servers can read it.
SSLKeyPasswdFile	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 server-root/mmp-hostname/sslpassword.conf.
SSLPorts	Ports on which SSL will be turned on (accepted SSL connections). Syntax is: [ IP ":" ] PORT [ "|" [ IP ":" ] PORT ] For example: 993|127.0.0.1:1993 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). If this parameter is not set, and SSLEnable is set to "true" or "yes," then only IMAP STARTTLS is enabled.
SSLSecmodFile	Security module database file location. If you have hardware accelerators for SSL ciphers, this file describes them to the Multiplexor. \ The default is server-root/mmp-hostname/secmodule.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 6-2.

Table 6-2    Messaging Multiplexor Configuration Files 

File	Description
PopProxyAService.cfg	Configuration file specifying environment variables used for POP services.
ImapProxyAService.cfg	Configuration file specifying environment variables used for IMAP services.
AService.cfg	Configuration file specifying which services to start and a few options shared by both POP and IMAP services.

As an example, the LogDir and LogLevel parameters can be found in all three 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:

• ServiceList

• LogDir and LogLevel

• NumThreads

• BeTheUser and BeTheGroup

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

The Multiplexor configuration files are stored in the server-root/mmp-hostname directory, where server-root is the directory where you installed the Messaging Server and mmp-hostname is the subdirectory named after the MMP instance. For example, if you installed the MMP on a machine named tarpit and accepted the default installation location, the configuration files would be located in /usr/iplanet/server5/mmp-tarpit.

Multiplexor Configuration Parameters

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

Table 6-3 describes the parameters you can set:

---

Note	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 6-3 for more information.

---

Table 6-3    Multiplexor Configuration Parameters 

Variable	Description
AuthCacheSize AuthCacheTTL	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. Higher values will reduce performance, but result in faster recognition or server password changes. Lower values will increase performance, but result in delayed recognition of server password changes. The default AuthCacheSize is 10,000; the default AuthCacheTTL is 900.
AuthService AuthServiceTTL	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/IMAP 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 0. The AuthService parameter should almost never be turned on globally; you should configure this by virtual domain.
BacksidePort	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. The default is 110 for POP3; 143 for IMAP (the standard ports).
Banner	Banner replacement string. The MMP will use the string you specify for its greeting line. There is no default string.
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 setup installation program. These variables are applicable to UNIX only and are ignored on Windows platforms.
BGMax BGPenalty BGMaxBadness BGDecay BGLinear BGExcluded	BadGuys configuration parameters. 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).
BindDN BindPass	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. To maintain the integrity of your system's security, you should us a hard-to-guess password and also select a BindDN that has read-only access to the directory. The installation process sets BindDN to cn=Directory Manager, and will prompt for the value of BindPass. The Messaging Server default directory ACIs require a bind to authenticate users against the Directory Server. This means that you must set the BindDN and BindPass options before you start the MMP. The recommended method for doing so is to copy the values for local.ugldapbinddn and local.ugldapbindcred from Messaging Server installation to the BindDN and BindPass options in an MMP installation. These options can be found in the ImapProxyAservice.cfg and PopProxyAservice.cfg configuration files.
CanonicalVirtualDomainDelim	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.
Capability	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 iPlanet 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): IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN LANGUAGE XSENDER X-NETSCAPE XSERVERINFO AUTH=PLAIN
CertMapFile	The name of the certmap file (for SSL client-cert-based authentications). There is no default.
ConnLimits	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 0.0.0.0|0.0.0.0:20
CRAMs	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.
DefaultDomain	The default domain; this parameter is mostly used for HostedDomains. If it is set, the value is appended to unqualified user IDs when there is no matching VDMap entry for the connection.
HostedDomains	Boolean, whether to support HostedDomains. If you are using the iPlanet Messaging Server directory schema, this should be set to the default "Yes." If you are using a Netscape Messaging Server (NMS) directory schema (for example, a schema lacking a DC tree), this should be set to "No" and the ldapUrl will point to the root of the user/group tree in the directory rather than the root of the DC tree. Defaults to Yes.
LdapCacheSize LdapCacheTTL	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. Higher values will reduce performance, but result in faster recognition of LDAP user configuration changes. Lower 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.
LdapUrl	Pointer to the top of the site's Users/Groups directory tree. 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. For example: ldap://ldap1 ldap2/o=isp. The default is ldap://localhost/o=isp.
LogDir LogLevel	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 three configuration files: ImapProxyAService.cfg, PopProxyAService.cfg, and AService.cfg. The default LogDir is server-root/mmp-hostname/log and the default LogLevel is 1.
MailHostAttrs	Space-separated list of LDAP attributes identifying the user's mail host. Multiplexor tries to connect to each server returned by the search in the order specified by the list. The default is mailHost.
NumThreads	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. If this is a single-processor machine, specify 0 for optimal performance. This parameter is only found in the AService.cfg configuration file. The default is 0 (the main thread does all the work).
PreAuth	Enables Global Roaming preauthentication. With preauthentication, clients authenticate to the MMP and the MMP relays authentication information to the message store. If set to Yes, preauthentication is enabled. Note that enabling preauthentication reduces server performance. The default is no.
ReplayFormat	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 domain=siroe.com would yield: joe@siroe.com. The default is NULL (only userid replayed).
SearchFormat	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: %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=%s. Note that when using HostedDomains, the inetDomainSearchFilter attribute in the Domain Component (DC) tree in the LDAP server overrides this option.
ServerDownAlert	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."
ServiceList	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: DLLNAME [ "|" INSTANCENAME [ "|" SECTION ]] "@" HOSTPORT [ "|" HOSTPORT ] 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 or POP services (minus the .cfg extension, so the defaults are ImapProxyAService and PopProxyAService, respectively). INSTANCENAME can also take an optional SECTION parameter which allows you to specify which instance of the MMP defined in the configuration file you want to start. This makes it possible to run multiple instances of POP/IMAP on different interfaces, each with different SSL certificates or other such setting all under the same MMP. The default SECTION is default. If no INSTANCENAME is specified, the AService daemon passes NULL to the AService DLL when the DLL is started. The ServiceList parameter is only found in the AService.cfg configuration file. The default ServiceList entry is shown below (all on one line): server-root/bin/msg/mmp/lib/ImapProxyAService@143|993 server-root/bin/msg/mmp/lib/PopProxyAService@110
SpoofMessageFile	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 StoreAdminPass	StoreAdmin represents the user name of the store administrator for proxy authentication necessary to support SSL client certificates. There is no default for StoreAdmin or StoreAdminPass.
TCPAccess	Wrap-style filter that describes TCP access control for the MMP (globally). Defaults to NULL.
TCPAccessAttr	Per-user attribute that contains a wrap-style filter describing the TCP access control for the user. Defaults to mailAccessDomain.
Timeout	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 or 600 seconds (10 minutes) for POP. The default is 1800 seconds.
VirtualDomainDelim	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 @.
VirtualDomainFile	The name of the file containing your virtual domain mapping. The default file is server-root/mmp-hostname/vdmap.cfg. Uncomment this line in the configuration file to enable support for virtual domains.