Chapter 4   Installing the Messaging Multiplexor


This chapter contains the following sections to help you install and configure the Messaging Multiplexor for Windows NT:

• Installing and Configuring Multiplexor

• Starting the Multiplexor

• Sample Messaging Topology

Installing and Configuring Multiplexor

---

The iPlanet Messaging Multiplexor (MMP) is a specialized messaging server that acts as a single point of connection to multiple messaging servers. With the Multiplexor, large-scale messaging-service providers can distribute POP and IMAP user mailboxes across many machines to increase messaging capacity. All users connect to the single Multiplexor server that will direct each connection to the appropriate messaging server.

---

Note	To configure HTTP user mailboxes (like Messenger Express), see the chapter on "Configuring and Administering Multiplexor Support" in the iPlanet Messaging Server Administrator's Guide.

---

You can install MMP at the same time as you install Messaging Server, or you can install it later using the setup program. Either way, you first need to prepare your system to support the MMP.

---

Note	If you install MMP on the same machine as Messaging Server, you must perform a Custom Installation of Messaging Server, so that the POP and IMAP servers can be set to non-standard ports. That way, the MMP and Messaging Server ports will not conflict with one another.

---

More information about the MMP can be found in the following:

• iPlanet Messaging Server Administrator's Guide

• iPlanet Messaging Server Reference Manual

Before You Install

Before installing the MMP:

1. Choose the machine on which you will install the MMP. It is best to use a separate machine for the MMP.
   

   ---

   Note	It is recommended that the MMP not be installed on a machine that is also running either Messaging Server or Directory Server.

   ---

   
   

2. Check that the system meets all the hardware and software requirements for using iPlanet Messaging Server. For more information about installation requirements, System Requirements.

3. Set up the LDAP Directory Server and its host machine for use with Messaging Server, if they are not already set up. For more information, see Chapter 2, "Installation Instructions."

Multiplexor Files

The Messaging Multiplexor files are stored in the mmp-hostname subdirectory of the server-root. Each MMP instance will have its own mmp-hostname directory that contains the files described in Table 4-1:

Table 4-1    Messaging Multiplexor Configuration Files 

File	Description
PopProxyAService.cfg	Configuration file specifying configuration variables used for POP services.
PopProxyAService-def.cfg	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.
ImapProxyAService.cfg	Configuration file specifying configuration variables used for IMAP services.
ImapProxyAService-def.cfg	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.
AService.cfg	Configuration file specifying which services to start and a few options shared by both POP and IMAP services.
AService-def.cfg	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.
AService.exe	Executable used to start, stop, restart, and reload the MMP. For more information, see Starting the Multiplexor.
SmtpProxyAService.cfg	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 iPlanet Messaging Server Administrator's Guide.
SmtpProxyAService-def.cfg	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.

Multiplexor Installation

To install the MMP, you must use the Messaging Server setup.exe program that gives you the option of choosing to install the Messaging Multiplexor. For detailed information about the setup.exe program refer to the Running the Setup Program.

---

Note	The MMP is not installed by default; you must select it as part of the Messaging Server Applications component in the Messaging Server installation.

---

To install a stand-alone version of the MMP, follow these steps:

1. Login as Administrator on Windows NT.

   You must have super user privileges (logged in as Administrator) to run the installation program.

2. Run the setup command from the install binaries, using optional parameters (See Table 2-1) if necessary.
   

   ---

   Note	If you are going to perform a Silent Installation, you must first run the setup command with the -k option. This creates a file called install.inf which is used for the Silent Installation. For more information, see Silent Installation.

   ---

   
   

3. Welcome screen

   This is the first screen you will see. Be sure to read this screen, then click Next to continue with the MMP installation.

4. License Agreement

   As part of the MMP installation process, you will be asked if you agree to the terms listed in the license agreement which is located in the LICENSE.txt file in the installation binaries. After reading the license agreement, click on Yes to continue with the installation.

5. Select Server or Console Installation

   You are given the option to install the iPlanet Servers (which includes the iPlanet Console and related components) or solely the iPlanet Console, also referred to as Netscape Console. For the MMP installation, you should choose "iPlanet Servers."

6. Installation Type

   You are given the option to choose the type of installation you want to use. For the MMP, you cannot use the Express Installation Type. You can choose either Typical or Custom Installation. However, if you want to install both the Messaging Server and MMP on the same machine, you must install a Custom Installation so the POP and IMAP servers can be set to non-standard ports.

   • Typical Installation. This level provides a balance between configuration options that you are asked to specify and those that are supplied automatically. This is the default level.

   • Custom Installation. This level provides the greatest amount of configuration options and is intended for expert users. After you select the installation level, you enter your installation and configuration information, according to the type of installation you selected.

7. Installation Location (server-root)

   Specify the desired installation location by clicking Browse. Or, you can click Next to accept the default.

8. Netscape Server Products Components

   Specify which products in the Messaging Server Suite you want to install. For a detailed description on each product and component, see Installation Components.

   For the MMP installation, click on iPlanet Messaging Server component and then click Change (In a stand-alone MMP installation, make sure iPlanet Messaging Server component is unchecked before clicking Change to select MMP.).

   The Messaging Server component includes Messaging Server, iPlanet Internet Message Transport Agent, and iPlanet Messaging Multiplexor.

   Make sure that iPlanet Messaging Multiplexor is the only sub-component checked (in a stand-alone MMP installation) before clicking Next.

   Note that if you want to use SSL, you also have to install the Administration Server and Console on the same machine as MMP; in this case, select options 1, 3, and 4. You will need to answer additional questions to set up the Administration Server and Console. For more information on these questions, see Chapter 3, "Installation Questions."

9. MMP Users and Groups Directory URL

   Enter the LDAP URL of the DC tree so that the MMP will be able to access the DC tree in the Users and Groups Directory Server. This is usually in the following format: ldap://user-group_directory_server_hostname>:port/o=internet

   
   
   

10. MMP LDAP URL User Credentials

    Enter the Bind DN and password of the Directory Manager or any LDAP user with read access to the Users and Groups Directory.

At this point, the installation begins. Various messages are displayed as the installation proceeds.

Configuring the MMP to use SSL

The MMP supports both unencrypted and encrypted (SSL) communications between the Messaging Server(s) and their mail clients. To configure the MMP to use SSL, do the following:

---

Note	It is assumed that the MMP is installed on a machine that does not have a Message Store or MTA.

---

1. Install the Administration Console, Administration Server, and MMP on the machine.

   Point the MMP to a Directory Server on a different machine that is already configured as a Messaging Server Message Store.

2. Go to your server-root and double-click the iPlanet Console icon:

3. Open up the "Server Group" for the MMP server.

   The MMP server does not appear, but the Administration Server does; double-click on the Administration Server icon.

4. Click the "Configuration" tab and within that tab, click on the "Encryption" tab.

5. Click "Certificate Setup Wizard."

   The setup wizard walks you through a certificate request.

6. Install the certificate as the certificate for "This Server."

7. Copy the following files: cert7.db, key3.db, secmod.db, and sslpassword.conf from an existing Messaging or Directory Server. These servers must have a server certificate and a key appropriate for the same domain already installed.

8. Create an sslpassword.conf file in this directory.

   This file contains:

   Internal (Software) Token:password

   where password is the password you specified in the Certificate Setup Wizard.

9. Edit the ImapProxyAService.cfg file and uncomment all the SSL settings.

10. If you want SSL and POP, edit the PopProxyAService.cfg file and uncomment all the SSL settings.

    Additionally, you must edit the AService.cfg file and add "|995" after the "110" in the ServiceList setting.

11. Make sure that the BindDN and BindPass options are set in the ImapProxyAService.cfg and PopProxyAService.cfg files.

    It is possible to copy these values from the local.ugldapbinddn and local.ugldapbindcred configutil options on the Messaging Server, but you can also create a new user with search privileges (for plain text support) or search privileges and user password read privileges (for CRAM-MD5/APOP support). You should also set the DefaultDomain option to your default domain (the domain to use for unqualified user names).

    If you just want server-side SSL support, you are finished. Start the MMP through Services in the Control Panel.

    If you want client-side SSL support, do the following:

12. A "Trusted Certificate Authority" should be installed on Messaging or Directory Server with an installed server certificate for the same domain.

13. Use the Store Administrator you created during your Messaging Server installation.

    For more information, refer to the iPlanet Messaging Server Administrator's Guide.

14. Create a certmap.conf file for the MMP. For example:

    certmap default         default
    default:DNComps
    default:FilterComps          e=mail

    This means to search for a match with the "e" field in the certificate DN by looking at the "mail" attribute in the LDAP server.

15. Edit your ImapProxyAService.cfg file and:
    1. Set CertMapFile to certmap.conf

    2. Set StoreAdmin and StorePass to values from Step 13.

    3. Set CertmapDN to the root of your Users and Groups tree.

16. If you want client certificates with POP3, repeat Step 15 for the PopProxyAService.cfg file.

17. If the MMP is not already running, start it through Services in the Control Panel.

18. Import the client certificate into your client. In Netscape, click on the padlock (Security) icon, then select "Yours" under "Certificates," then select "Import a Certificate..." and follow the instructions.
    

    ---

    Note	All your users will have to perform this step if you want to use client certificates everywhere.

    ---

    
    

Creating Additional Instances

Use the Messaging Server setup program to create new instances of the MMP after an initial installation. You will run through the same installation procedure as when you created your first instance; you will be asked all the same questions. The setup program automatically creates a new instance in the server-root; for example, if you are installing on a machine called tarpit, the first instance you created would be called mmp-tarpit, and the second instance would be mmp-tarpit-1.

Modifying an Existing Instance

To modify an existing instance of the MMP, edit the ImapProxyAService.cfg or PopProxyAService.cfg configuration files as necessary. These configuration files are located in the mmp-hostname subdirectory.

Starting the Multiplexor

---

To start an instance of the MMP, go to Services in the Windows NT Control Panel and click on "Start." You can also click on "Stop" to stop the MMP. The service options are described below in Table 4-2.

Table 4-2    MMP Service Options

Option	Description
start	Starts the MMP (even if one is already running).
stop	Stops the most recently started MMP.
restart	To restart on Windows NT, stop the most recently started MMP and then start an MMP.
reload	To reload the MMP, go to the mmp-instance directory and type AService refresh at the command prompt.

Sample Messaging Topology

---

The fictional Siroe Corporation has two Multiplexors on separate machines, each supporting several Messaging Servers. POP and IMAP user mailboxes are split across the Messaging Server machines, with each server dedicated exclusively to POP or exclusively to IMAP. (You can restrict client access to POP services alone by removing the IMAP-server binary; likewise, you can restrict client access to IMAP services alone by removing the POP-server binary.) Each Multiplexor also supports only POP or only IMAP. The LDAP directory service is on a separate, dedicated machine.

This topology is illustrated below in Figure 4-1.

Figure 4-1    Multiple MMPs Supporting Multiple Messaging Servers

IMAP Configuration Example

The IMAP Multiplexor in Figure 4-1 is installed on sandpit, a machine with two processors. This Multiplexor is listening to the standard port for IMAP connections (143). Multiplexor communicates with the LDAP server on the host phonebook for user mailbox information, and it routes the connection to the appropriate IMAP server. It overrides the IMAP capability string, provides a virtual domain file, and supports SSL communications.

This is its ImapProxyAService.cfg configuration file:

default:LdapUrl             ldap://phonebook/o=Siroe.com default:LogDir              c:\iplanet\server5\mmp-sandpit/log default:LogLevel            5 default:BindDN              "cn=Directory Manager" default:BindPass            secret default:BacksidePort        143 default:Timeout             1800 default:Capability          "IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN LANGUAGE XSENDER X-NETSCAPE XSERVERINFO AUTH=PLAIN" default:SearchFormat        (uid=%s) default:SSLEnable           yes default:SSLPorts            993 default:SSLSecmodFile       c:\iplanet\server5\mmp-sandpit\secmod.db default:SSLCertFile         c:\iplanet\server5\mmp-sandpit\cert7.db default:SSLKeyFile          c:\iplanet\server5\mmp-sandpit\key3.db default:SSLKeyPasswdFile    "" default:SSLCipherSpecs      all default:SSLCertNicknames    Siroe.com Server-Cert default:SSLCacheDir         c:\iplanet\iplanet\server5\mmp-sandpit default:SSLBacksidePort     993 default:VirtualDomainFile   c:\iplanet\server5\mmp-sandpit\vdmap.cfg default:VirtualDomainDelim  @ default:ServerDownAlert     "your IMAP server appears to be temporarily out of service" default:MailHostAttrs       mailHost default:PreAuth             no default:CRAMs               no default:AuthCacheSize       10000 default:AuthCacheTTL        900 default:AuthService         no default:AuthServiceTTL      0 default:BGMax               10000 default:BGPenalty           2 default:BGMaxBadness        60 default:BGDecay             900 default:BGLinear            no default:BGExcluded          c:\iplanet\server5\mmp-sandpit\bgexcl.cfg default:ConnLimits          0.0.0.0|0.0.0.0:20 default:LdapCacheSize       10000 default:LdapCacheTTL        900 default:HostedDomains       yes default:DefaultDomain       Siroe.com

POP Configuration Example

The POP Multiplexor example in Figure 4-1 is installed on tarpit, a machine with four processors. This Multiplexor is listening to the standard port for POP connections (110). Multiplexor communicates with the LDAP server on the host phonebook for user mailbox information, and it routes the connection to the appropriate POP server. It also provides a spoof message file.

This is its PopProxyAService.cfg configuration file:

default:LdapUrl             ldap://phonebook/o=Siroe.com default:LogDir              c:\iplanet\server5\mmp-tarpit\log default:LogLevel            5 default:BindDN              "cn=Directory Manager" default:BindPass            password default:BacksidePort        110 default:Timeout             1800 default:Capability          "IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN LANGUAGE XSENDER X-NETSCAPE XSERVERINFO AUTH=PLAIN" default:SearchFormat        (uid=%s) default:SSLEnable           no default:VirtualDomainFile   c:\iplanet\server5\mmp-tarpit\vdmap.cfg default:VirtualDomainDelim  @ default:MailHostAttrs       mailHost default:PreAuth             no default:CRAMs               no default:AuthCacheSize       10000 default:AuthCacheTTL        900 default:AuthService         no default:AuthServiceTTL      0 default:BGMax               10000 default:BGPenalty           2 default:BGMaxBadness        60 default:BGDecay             900 default:BGLinear            no default:BGExcluded          c:\iplanet\server5\mmp-tarpit\bgexcl.cfg default:ConnLimits          0.0.0.0|0.0.0.0:20 default:LdapCacheSize       10000 default:LdapCacheTTL        900 default:HostedDomains       yes default:DefaultDomain       Siroe.com