Appendix B       Installing the Messaging Multiplexor


This appendix contains the following sections to help you install and configure the Messaging Multiplexor:

• Installing and Configuring Multiplexor

• Starting the Multiplexor

• Sample Messaging Topology

Installing and Configuring Multiplexor

---

The Messaging Multiplexor (MMP) is available as part of iPlanet Messaging Server. You can install the 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 the system to support the MMP.

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

• iPlanet Messaging Server 5.0 Administrator's Guide

• iPlanet Messaging Server 5.0 Reference Manual

Before You Install

Before installing the MMP:

1. Choose the machine on which you will install the MMP. It is recommended that you do not install the MMP on a system that is also running the Messaging Server or Directory Server. It is best to use a separate machine for the MMP.

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

3. On the machine that the MMP is to be installed on, create a new user to be used exclusively by the MMP. This new user must belong to a group. Suggested names for the user are nsmmp or nsmail. The default is mmpsrv.

4. 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 your Directory Server documentation.

5. If you already have an older version of the MMP installed and want to replace it, you must remove the old version of MMP before you can install the new one. To do this, run the Messaging Server uninstall script located in server-root.

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 B-1:

Table B-1    Messaging Multiplexor 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.
AService.rc	Executable used to start, stop, restart, and/or reload the MMP. For more information, see Starting the Multiplexor.

Multiplexor Installation

To install the MMP, you must use the Messaging Server setup program, which gives you the option of choosing to install the Messaging Multiplexor. For detailed information about the setup program refer to the iPlanet Messaging Server Installation Guide.

---

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

---

You can run the setup program to install the MMP at any time. For instructions on using the setup program, see the Messaging Server Installation Guide.

---

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 the MMP:

1. Run the Messaging Server setup program.

   ./setup

2. Answer yes or press Return for the following to continue with the installation:

   Welcome to the iPlanet Server Products installation program. This program will install iPlanet Server Products and the iPlanet Console on your computer.

   It is recommended that you have "root" privilege to install the software.

   Tips for using the installation program:
     - Press "Enter" to choose the default and go to the next screen
     - Type "Control-B" to go back to the previous screen
     - Type "Control-C" to cancel the installation program
     - You can enter multiple items using commas to separate them.
        For example: 1, 2, 3

   Would you like to continue with installation? [Yes]:

3. Read the license agreement and answer yes to the following question to continue. The license agreement is located in the LICENSE.txt file in the directory where you downloaded the installation software.

   BY INSTALLING THIS SOFTWARE YOU ARE CONSENTING TO BE BOUND BY AND ARE BECOMING A PARTY TO THE AGREEMENT FOUND IN THE LICENSE.TXT FILE. IF YOU DO NOT AGREE TO ALL OF THE TERMS OF THIS AGREEMENT, PLEASE DO NOT INSTALL OR USE THIS SOFTWARE.

   Do you agree to the license terms? [No]:

4. Select option 1 from the following:

   Select the items you would like to install:

   1. iPlanet Servers

      Installs iPlanet Servers with the integrated Netscape Console
      onto your computer.

   2. Netscape Console

      Installs Netscape Console as a stand-alone Java application
      on your computer.

   To accept the default shown in brackets, press the Enter key.

   Select the component you want to install [1]:

5. Select either the Typical or Custom installation from the following menu:
   

   ---

   Note	You cannot install the Messaging Multiplexor with the Express Installation; you must use either the Typical or Custom Installation.

   ---

   
   

   Choose an installation type:

   1. Express installation

      Allows you to quickly install the servers using the most
      common options and pre-defined defaults. Useful for quick
      evaluation of the products.

   2. Typical installation

      Allows you to specify common defaults and options.

   3. Custom installation

      Allows you to specify more advanced options. This is
      recommended for experienced server administrators only.

   To accept the default shown in brackets, press the Enter key.

   Choose an installation type [2]:

6. Specify the desired installation location, or press Return to accept the default.

   This program will extract the server files and install them into a directory you specify. That directory is called the server root in the product documentation and will contain the server programs, the Administration Server, and the server configuration files.

   To accept the default shown in brackets, press the Enter key.

   Install location [/usr/iplanet/server5]:

7. Select option 4 from the following menu:

   iPlanet Server Products components:

   Components with a number in () contain additional subcomponents which you can select using subsequent screens.

   1. Netscape Server Products Core Components (3)
   2. Netscape Directory Suite (2)
   3. Administration Services (2)
   4. iPlanet Messaging Suite (5)

   Specify the components you wish to install [All]:

8. Select option 3 from the following menu:

   iPlanet Messaging Suite components:

   Components with a number in () contain additional subcomponents which you can select using subsequent screens.

   1. iPlanet Message Store and Message Access
   2. iPlanet Internet Message Transport Agent
   3. iPlanet Messaging Multiplexor
   4. High Availability for iPlanet Messaging Server
   5. iPlanet Delegated Administrator Command Line Utilities

   Specify the components you wish to install [1, 2, 5]:

9. Specify the fully qualified domain name of the installation machine.

   Enter the fully qualified domain name of the computer on which you're installing server software. Using the form <hostname>.<domainname>
   Example: eros.airius.com.

   To accept the default shown in brackets, press the Enter key.

   Computer name [budgie.siroe.com]:

10. Specify a system user and system group.

    Choose a Unix user and group to represent the iPlanet server in the user directory. The iPlanet server will run as this user. It is recommended that this user should have no privileges in the computer network system. The Administration Server will give this group some permissions in the server root to perform server-specific operations.

    If you have not yet created a user and group for the iPlanet server, create this user and group using your native UNIX system utilities.

    To accept the default shown in brackets, press the Return key.

    System User [nobody]:

11. Specify the user ID under which the MMP will run:

    The Mail Multiplexor runs as a privileged user. The account should already exist on the system and should be a member of the iPlanet Group.

    Please enter the Mail Multiplexor user [mmpsrv]:

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

Post-Installation Procedures

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.ldapsiedn and local.ldapsiecred from a 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.

It is also possible for an end user to set BindDN and BindPass by using the Directory Manager DN (for example, cn=Directory Manager) and password specified during installation.

---

Note	It is important that the password is something fairly cryptic and not some easy-to-guess dictionary word.

---

Configuring the MMP to use SSL

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 run startconsole to login to the Netscape Console:

   ./startconsole

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 on the "configuration" tab and within that tab, click on the "Encryption" tab.

5. Click on "Certificate Setup Wizard."

   The setup wizard walks you through a certificate request.

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

7. From the command line, make the following symbolic links to simplify things:

   cd server-root/mmp-hostname
   ln -s ../alias/admin-serv-instance-cert7.db cert7.db
   ln -s ../alias/admin-serv-instance-key3.db key3.db
   ln -s ../admin-serv/config/secmod.db secmod.db

   Also, make sure that those files are owned by the user ID under which the MMP will run.

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

   This file contains:

   Communicator Certificate DB: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 with the following command:

AService.rc start

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

12. Get a copy of a client certificate and the CA certificate which signed it. You can do this with Netscape CMS 4.1, which is available from the iPlanet web site.

13. Start the Netscape Console and Certificate Wizard as before (on the same machine as the MMP), but this time import the CA certificate as a "Trusted Certificate Authority."

14. Create a Store Administrator.

    For more information, see the iPlanet Messaging Server 5.0 Administrator's Guide.

15. 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.

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

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

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

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

18. If the MMP is not already running, start it with:

    AService.rc start

    or

    AService.rc restart

19. 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 and/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 Messaging Multiplexor, run the AService.rc script in the server-root/mmp-hostname directory:

./AService.rc [options]

Optional parameters for the AService.rc script are described below in Table 3-2.

Table 3-2 Optional Parameters for the AService.rc Script

Option	Description
start	Start the MMP (even if one is already running).
stop	Stop the most recently started MMP.
restart	Stop the most recently started MMP, then start an MMP.
reload	Causes an MMP that is already running to reload its configuration without disrupting any active connections.

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 3-1.

Figure 3-1    Multiple MMPs Supporting Multiple Messaging Servers

IMAP Configuration Example

The IMAP Multiplexor in Figure 3-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              /usr/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       /usr/iplanet/server5/mmp-sandpit/secmod.db default:SSLCertFile         /usr/iplanet/server5/mmp-sandpit/cert7.db default:SSLKeyFile          /usr/iplanet/server5/mmp-sandpit/key3.db default:SSLKeyPasswdFile    "" default:SSLCipherSpecs      all default:SSLCertNicknames    Siroe.com Server-Cert default:SSLCacheDir         /usr/iplanet/server5/mmp-sandpit default:SSLBacksidePort     993 default:VirtualDomainFile   /usr/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          /usr/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 3-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              /usr/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   /usr/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          /usr/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