Chapter 13 Messaging Multiplexor

This chapter describes Netscape Messaging Multiplexor and provides installation and configuration instructions. This chapter contains the following sections:

• About Messaging Multiplexor
• Multiplexor Configuration


• Installing and Configuring Multiplexor (Unix)


• Installing and Configuring Multiplexor (NT)


• Running Multiplexor


• Uninstalling Multiplexor

If you provide electronic mail service to many users, you can install and configure Messaging Multiplexor so that an entire array of messaging servers will appear to your mail users to be a single host.

• Both unencrypted and encrypted (SSL) communications with mail clients.
• Client certificate-based authentication, described in Certificate-Based Client Authentication.
• User pre-authentication, described in User Pre-Authentication.
• Virtual domains that listen on different IP addresses and automatically append domain names to user IDs, described in Virtual Domains.
• Multiple installations of Multiplexor on different machines (one installation per machine).
• Multiple instances of Multiplexor on a server machine, described in Multiple Multiplexor Instances. Multiple instances can be used for alternate configurations such as SSL or the listen port that cannot be handled through virtual domains.
• Enhanced LDAP searching.

Message stores on heavily used messaging servers can grow quite large. Spreading user mailboxes and user connections across multiple servers can therefore improve capacity and performance. In addition, it may be more cost-effective to use several small server machines than one large, high-capacity, multiprocessor machine.

• Simplified user management

Because all users connect to one server (or two, if you have separate Multiplexors for POP and IMAP), you can preconfigure email clients and distribute uniform login information to all users. This simplifies your administrative tasks and reduces the possibility of distributing erroneous login information.

For especially high-load situations, you can run multiple Multiplexor servers and manage connections to them by DNS round robin or by using a load- balancing program, such as LocalDirector from Cisco Systems.

Because Multiplexor uses information stored in the LDAP directory to locate each user's messaging server, moving a user to a new server is simple for the system administrator and transparent to the user. The administrator can move a user's mailbox from one messaging server to another, and then update the user's entry in the directory. The user's mail address, mailbox access, and other client preferences need not change.

• Improved performance

If a message store grows prohibitively large for a single machine, you can balance the load by moving some of the message store to another machine.

You can assign different classes of users to different machines. For example, you can choose to locate premium users on a larger and more powerful machine.

Multiplexor performs some buffering, so that slow client connections (through a modem, for example) do not slow down the messaging server.

• Decreased cost

Because you can efficiently manage multiple messaging servers with Messaging Multiplexor, you can decrease overall costs by purchasing several small server machines that together cost less than one very large machine.

• Better scalability

With Messaging Multiplexor, your configuration can expand easily. You can incrementally add machines as your performance or storage-capacity needs grow, without replacing your existing investment.

• Minimum user downtime

Using Messaging Multiplexor to spread a large user base over many small store machines isolates user downtime. When an individual server fails, only its users are affected.

• Increased security

You can use the server machine on which Messaging Multiplexor is installed as a firewall machine. By routing all client connections through the Multiplexor machine, you can restrict access to the internal message store machines by outside computers. Messaging Multiplexor supports both unencrypted and encrypted communications with clients.

Messaging Multiplexor is a multithreaded server that facilitates distributing mail users across multiple server machines. Multiplexor handles incoming client connections destined for other server machines (the machines on which user mailboxes reside). Clients connect to Multiplexor itself, which then redirects the session to the server with the correct mailbox. This capability allows Internet service providers and other large installations to spread message stores across multiple machines (to increase capacity) while providing the appearance of a single mail host for users (to increase efficiency) and for external clients (to increase security).

1. A user's client connects to Multiplexor, which accepts preliminary authentication information (user name).
2. Multiplexor queries an LDAP directory server to determine which messaging server contains that user's mailbox.
3. Multiplexor connects to the proper messaging server, replays authentication, then acts as a pass-through pipe for the duration of the connection.

The Netscape Multiplexor supports both unencrypted and encrypted (SSL) communications between the IMAP server and mail clients.

• When using the mmp-setup script, answer yes to the "Should the IMAP MMP do SSL" prompt. Then specify port, secmodfile, certfile, keyfile, keypass, ciphers, and certname parameters. See Table 13.9 for details about configuration prompts.
• When specifying Multiplexor configuration options from the command line, use the -s parameters (secmodfile, certfile, keyfile, keypass, ciphers, and certname) parameters. See Table 13.4 for details.

Multiplexor can use certmap to match a client's certificate to the correct user in the user-group LDAP database.

mapname:DNComps FROMATTR=TOATTR
mapname:FilterComps FROMATTR=TOATTR

mapname:FilterComps ou=uid

1. Decide on the user ID you intend to use as store administrator.

While you can use the mail administrator for this purpose, Netscape recommends that you create a unique user ID for store administrator. For example, mmpstore.

2. Make sure that SSL encryption is (or will be) enabled as described in Encryption (SSL) Option.
3. Configure Multiplexor to use certificate-based client authentication:

• When using the mmp-setup script, answer yes to the "Do you have a certmap.conf (Should MMP do client-cert auth)" prompt. Then specify the location of the certmap.conf file, the store administrator user ID, and password. See Table 13.9 for details.
• When specifying Multiplexor configuration options from the command line, use the -cm cmfile, -d storeadmin, and -W password options. See Table 13.4 for details about these configuration prompts.

Multiplexor has the option of pre-authenticating users by binding to the directory as the incoming user and logging the result.

date time (sid 0x%p) user name pre-authenticated - client IP address

Multiplexor supports the 4.0 format virtual domain file syntax.

• When installing in Unix environments, answer yes to the "Should this MMP do virtual domain mapping?" prompt. Then specify the location (name) of the virtual domain mapping file and the domain delimiters it uses. See Table 13.7 for details.
• When specifying Multiplexor with the Server Setup program in Windows NT environments, answer yes to the "Use Virtual Domain Mapping" prompt. See Table 13.9 for details.
• When specifying Multiplexor configuration options from the command line in Windows NT environments, use the -vd file option followed by the -vdd str option. See Table 13.4 for details.

vdmap name IPaddr
name:property value

You can create multiple instances of Multiplexor, all of which must be on the same server. In other words, you can have multiple installations of Multiplexor on different servers, and on any given machine you can have multiple instances.

• Configuration environment variables are parameters that are permanently stored and applied each time Multiplexor is run. There are several methods of specifying configuration environment variables as described in Table 13.2.
• Command line configuration options are parameters that are specified on the command line at the time Multiplexor is run. A configuration parameter specified on the command line at the time Multiplexor is run overrides any corresponding value specified as an environment variable. For example, if you have specified a value for the capability parameter as an environment variable, but you enter a different capability value from the command line, the command line value will be used by that Multiplexor session.

• In Unix environments, environment variables for each Multiplexor instance are stored in configuration files named ImapMMP.config and PopMMP.config. These files are stored in the directory MMPRoot/MMP_instanceName.
• In NT environments, environment variables for each Multiplexor instance are stored in the Windows registry.

You control how Multiplexor operates by specifying various configuration parameters, either as environment variables or as command-line options.

Once an instance of Multiplexor has been installed using the Server Setup program, you can run Multiplexor directly from the command line using either the PopProxy or ImapProxy commands as described in Running Multiplexor.

PopProxy [install] [options]

ImapProxy [install] [options]

Note that using the install option aborts loading Multiplexor. In other words, if you run PopProxy or ImapProxy with the install option, Multiplexor does not start.

• In NT environments, if you run PopProxy or ImapProxy with the install option, any options you specify on the command line are added to or changed in the NT registry. In other words, options you specify on the command line become environment variables. The next time Multiplexor is started, it will take those variables from the registry. Note that if a parameter is specified in the registry, and you do not include it on the command line, it remains as it was in the registry.
• In Unix environments, the install option does not make any changes to any of the configuration files. In other words, the install option does not create any environment variables. Instead, the configuration options you specified on the command line are printed out, and you can copy those into a configuration file.

Before you install Messaging Multiplexor on a Unix machine, perform the following tasks:

1. Choose the machine on which you will install Multiplexor. Netscape recommends against installing Multiplexor on a system that is also running Messaging Server or Directory Server. It is best to use a separate machine for Multiplexor.
2. Check that the system meets all the hardware and software requirements for using Netscape Messaging Server. For more information about installation requirements, see the Messaging Server Installation Guide.
3. On the machine that Messaging Multiplexor is to be installed on, create a new user to be used exclusively by Multiplexor. This new user must belong to a group. Suggested names for the user are nsmmp ("Netscape Messaging Multiplexor") or nsmail.
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 the Directory Server documentation.
5. If you already have an older version of the Multiplexor installed and want to replace it, you must remove the old version of Multiplexor before you can install the new one. To remove Multiplexor, remove the mmp server root directory and the /etc/netscape.mmp.conf file.

maxfiles 16384 
maxfiles_lim 16384 
nfiles 32768 

In Unix environments, Multiplexor executable files are stored in the Multiplexor installation directory (MMPRoot in this document), and two subdirectories of MMPRoot: MMPRoot/bin and MMPRoot/lib. At installation time you specify the directory that you want to use as MMPRoot. For example,
/usr/netscape/server4/bin/mmp.

In Unix environments, there are two ways to install Messaging Multiplexor on a machine:

• When you install Messaging Server or other Netscape components, the Server Setup program gives you the option of choosing to install Messaging Multiplexor at the same time. You can run the Server Setup program to install Multiplexor at any time. See Creating a Multiplexor Instance (Unix) for details. (For instructions on using the Server Setup program, see the Messaging Server Installation Guide.)
• Once Multiplexor has been installed on a machine, you can also use the Multiplexor Installer to create additional Multiplexor instances by running the mmp-setup script on that machine. See Creating Additional Instances (Unix) for details.

You must use the Server Setup program to create your first Multiplexor instance. This program sets up and then uses the Netscape Messaging Multiplexor Installer. (Note that Multiplexor installation is not the default; you must select it as part of the Messaging Server suite.) For subsequent installations of additional instances, you can call the Multiplexor Installer directly by running the mmp-setup script.

1. When prompted for the user name that Multiplexor should run as, enter the user name that you created for exclusive use of Multiplexor as explained in Before You Install (Unix).

The default value is nobody. Change this to the user name that you created.

2. At the next prompt, enter the installation directory (called MMPRoot/ in this document), the directory path into which you want Multiplexor to be installed.

To accept the default (/usr/netscape/suitespot4/mmp), press Enter. In this example the /mmp directory is the MMPRoot.

The installation program creates the directories for the Multiplexor installation and installs the files. (If you are creating a second or subsequent instance of Multiplexor on this machine, the installation program uses the existing installed files.)

The installer program starts to create an instance of Multiplexor from those files. (If there is a previously installed instance of Multiplexor, you can at this point choose to either configure the existing instance or create a new one.)

3. If you choose to configure a new instance of Multiplexor, enter the name you want to give it.

To accept the default name (the host name of the machine you are installing Multiplexor onto) press Enter. The installation program finishes creating the new instance, installing it into the subdirectory MMPRoot/ MMP-instanceName/ where instanceName is the name you specified.

4. Enter one of the following numbers to specify which kind of mail service you want this instance to support:

1 - Configure this instance for IMAP mail service
2 - Configure this instance for POP3 mail service
3 - Configure this instance for both IMAP4 and POP3 mail service

5. You are then stepped through a series of configuration prompts that allow you to specify environment variables that will control how this instance of Multiplexor operates. See Configuration Prompts (Unix) for a description of these prompts.
6. The installer shows you a summary of the information you have entered. If the information is correct, type y. If you need to make changes, type n, in which case the install program takes you back through the prompts again.

After you have approved the configuration parameters and the Multiplexor Installer has implemented them, the program displays the following information:

• The location of shell scripts you can use to start Multiplexor. Depending on your system's capabilities, you may be able to put these scripts in your init directory to start Multiplexor automatically at system startup. Alternatively, you can run the scripts from the command line by typing ImapMMP.sh start or PopMMP.sh start. These shell scripts set environment variables that control Multiplexor configuration and then execute the Multiplexor program.
• The location of the Netscape Messaging Multiplexor Installer (mmp-setup). When you use the Netscape Servers installation program to install the Messaging Multiplexor, the Multiplexor Installer installs itself (at the top level of the installation directory, under MMPRoot/), so that you can later execute it directly to modify the configuration of this instance.
• Instructions for removing Messaging Multiplexor, in case you ever need to. To remove all instances of Multiplexor from the host, remove the entire installation directory (MMPRoot/) and the Multiplexor configuration file (netscape.mp.conf, in the directory /etc/). To remove only a single instance of Multiplexor, remove just the subdirectory MMPRoot/MMP_instanceName/.

Use the Multiplexor Installer to create a new instance after an initial installation.

1. Go to the directory that contains the Multiplexor Installer.

The program is installed at the top of the installation directory, under MMPRoot/.

2. From the command line, type mmp-setup.
3. The Multiplexor Installer asks whether you want to change an existing instance or create a new one. If you choose to create a new instance, the installer takes you through the installation process, as described in Creating a Multiplexor Instance (Unix).

Use the Multiplexor Installer to modify the configuration of a previously installed instance of the Multiplexor.

1. Go to the directory that contains the Multiplexor Installer. The program is installed at the top of the installation directory, under MMPRoot/.
2. From the command line, type mmp-setup.
3. The Multiplexor Installer asks whether you want to change an existing instance or create a new one. To change an existing instance, select the name of that instance. The installer takes you back through the prompts for configuring the Multiplexor so you can make the changes you want. For information about each parameter, see Multiplexor Configuration.

Multiplexor is controlled by setting the configuration parameters that are described in Table 13.3. See Table 13.2 for different methods you can use to set configuration parameters.

• Using the configuration prompts invoked by running the Server Setup program or the mmp-setup script. See Configuration Prompts (Unix).
• Directly editing the Multiplexor configuration files. See Directly Setting Configuration Variables (Unix).

To display a list of the current configuration parameters, you can execute Multiplexor for either POP or IMAP by running either PopProxy or ImapProxy from the command line, using the -h option with no attributes:

PopProxy -h 
ImapProxy -h

Keep the following in mind when entering a port number:

• Port numbers can be any number from 1 to 65535.
• If you choose a port number 1024 or lower, you must start all processes as root (superuser).
• Make sure the port you choose isn't already in use or reserved for another service. Look at the file /etc/services on the Multiplexor machine to make sure you don't assign a port number that is used by another service.

Table 13.7 lists the Multiplexor configuration prompts and associated environment variables in Unix environments. See Table 13.3 for environment variable descriptions.

UidAttr

MailHostAttrs

On Unix, Multiplexor configuration parameters are stored in the configuration files ImapMMP.config and PopMMP.config. These files are stored in the directory MMPRoot/MMP_instanceName. You can set configuration parameters by directly modifying the parameter specifications in these files.

Capability="IMAP IMAP4rev1 AUTH=LOGIN AUTH=PLAIN X-NETSCAPE"

In the example shown in Figure 13.3, the fictional Airius Corporation has two Multiplexors (on separate machines), each supporting several Netscape 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.

The IMAP Multiplexor in Figure 13.3 is installed on sandpit, a machine with 2 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.

LDAPHost=phonebook
BaseDN="o=Airius.com"
LogDir="/usr/netscape/suitespot/mmp/MMP_sandpit/log"
LogLevel=5
BindDN="cn=Directory Manager"
BindPassword="password"
NumThreads=2
ListenPort=143
BacksidePort=143
Capability="IMAP4 IMAP4rev1 AUTH=LOGIN AUTH=PLAIN X-NETSCAPE"
VirtualDomainFile="/usr/netscape/suitespot/mmp/vdfile.txt"
SSLEnable=y
SSLListenPort=993
SSLSecmodFile="/usr/netscape/suitespot/mmp/secmod.db"
SSLCertFile="/usr/netscape/suitespot/mmp/cert7.db"
SSLKeyFile="/usr/netscape/suitespot/mmp/key3.db"
SSLKeyPasswd=""
SSLCipherSpecs="all"
SSLCertNickname="Airius.com Server Cert"

The POP Multiplexor example in Figure 13.3 is installed on tarpit, a machine with 4 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.

LDAPHost=phonebook
BaseDN="o=Airius.com"
LogDir="/usr/netscape/suitespot/mmp/MMP_tarpit/log"
LogLevel=10
BindDN="cn=Directory Manager"
BindPassword="password"
NumThreads=4
ListenPort=
BacksidePort=
SpoofMessageFile="/usr/netscape/suitespot/mmp/pop3spoof.txt"
SSLEnable=n

Before you install Messaging Multiplexor on a Windows NT machine, perform the following tasks:

1. Choose the machine on which you will install Multiplexor. Netscape recommends against installing Multiplexor on a system that is also running Messaging Server or Directory Server. It is best to use a separate machine for Multiplexor.
2. Check that the system meets all the hardware and software requirements for using Netscape Messaging Server. For more information about installation requirements, see the Messaging Server Installation Guide.
3. On the machine that Messaging Multiplexor is to be installed on, create a new user to be used exclusively by Multiplexor. This new user must belong to a group. Suggested names for the user are nsmmp ("Netscape Messaging Multiplexor") or nsmail.
4. Set up the LDAP directory server and its host machine if it's not already set up.
5. If you already have an older version of Multiplexor installed and want to replace it, you must remove the old Multiplexor before you can install the new one. To remove it, open a command prompt window, change to the directory containing Multiplexor, and type the following commands:

    c:\MultiPlex\ImapProxy uninstall 
    c:\MultiPlex\PopProxy uninstall 

Multiplexor installation and executable files are initially installed in server-root\bin\mmp. (In this document, server-root refers to the Messaging Server root directory, for example, C:\Netscape\Server4.)

In NT environments, there are two different ways to install Messaging Multiplexor on a machine:

• When you install Messaging Server or other Netscape components, the Server Setup program gives you the option of choosing to install Messaging Multiplexor at the same time. You can also use the Server Setup program to install a Multiplexor instance at a later time. See Creating a Multiplexor Instance (NT) for details. (For instructions on using the Server Setup program, see the Messaging Server Installation Guide.)
• Once Multiplexor has been installed on a machine, you can create additional Multiplexor instances by running the PopProxy (for a POP instance) or ImapProxy (for an IMAP instance) programs. See Creating Additional Instances (NT) for details.

You must use the Server Setup program to create your first Multiplexor instance. (For subsequent installations of additional instances, you can re-run the Server Setup program or use the ImapProxy or PopProxy commands.)

1. Run the Server Setup program (setup.exe), as described in the Messaging Server Installation Guide.

When you run the Server Setup program, you are asked to choose between three types of installation: Express, Typical, and Custom. If you choose Express, you are asked to specify a minimum number of variables and all other variables are automatically set to the default. If you choose Custom, you are asked to specify all values. If you choose Typical the number of variables you are asked to specify is greater than with an Express installation, but fewer than with a Custom installation.

2. When the Select Components screen is displayed, select Netscape Messaging Suites and click the Change button.

The Select Sub-Components window is displayed.

3. Unselect the server itself and select Netscape Messaging Multiplexor.

The Messaging Multiplexor Upgrade window is displayed.

4. Select Create a new multiplexor instance.

The Messaging Multiplexor Instance window is displayed.

Note: The "Upgrade all existing multiplexor instances" selection in the Messaging Multiplexor Upgrade window is for repairing or upgrading Multiplexor software, not for re-configuring an instance. If you choose this selection, all currently running Multiplexor instances are halted, the software files are recopied into each instance's directory, and those instances that were running at the time you chose to upgrade are restarted.

5. Enter information about your installation and configuration in response to the windows and prompts as they are displayed.

The windows and prompts you see will vary depending on the kind of installation you chose (Express, Typical, or Custom) and the choices you make as you proceed. See Configuration Prompts (NT) for a description of these windows and prompts.

6. When you see the summary of the information you've entered, make sure the information is correct, and then click Next.

The program files are now copied to your hard disk.

7. The setup program then runs each of the Multiplexors (first POP, then IMAP) in a special configuration mode to configure them according to the information you have entered.

To install an additional instance of Multiplexor on a machine that already has an installed instance, you can either:

• Re-run the Netscape Servers installation program as described in Creating a Multiplexor Instance (NT). Enter a new instance name in the Messaging Multiplexor Instance window.
• Create a directory for the new instance under the server-root directory (server-root \mmp-instancename). Copy all of the files in server-root\bin\mmp to the new instance directory. Then run the PopProxy (for a POP instance) or ImapProxy (for an IMAP instance) program from the command line with the install option. See Command-Line Configuration Options for additional details. Note that each instance name must be unique.

To make permanent configuration changes to a Multiplexor instance, you can:

• Uninstall and then re-install Multiplexor.
• Go to the directory containing the instance you want to modify and run the PopProxy or ImapProxy programs from the command line with the install option as described in Command-Line Configuration Options.
• Modify the information in the NT Registry as described in Directly Specifying Configuration Variables (NT).

Multiplexor is controlled by setting the configuration parameters that are described in Table 13.3. See Table 13.2 for the different methods you can use to set these configuration parameters.

• Using the configuration prompts invoked by running the Server Setup program. See Configuration Prompts (NT).
• Directly editing the Windows NT Registry. See Directly Specifying Configuration Variables (NT).

To display a list of the command-line configuration options stored in the Registry, you can execute Multiplexor for either POP or IMAP from the command line, using the -h option with no attributes:

PopProxy -h 
ImapProxy -h

Table 13.9 lists the Multiplexor configuration prompts and associated configuration parameters for Windows NT. (Table 13.3 describes the configuration parameters that the prompts specify.) Configuration variables are stored in the Windows NT registry key: HKEY_LOCAL_MACHINE/SOFTWARE/Netscape/MMP/instance.

In a Windows NT environment, you can set configuration environment variables by modifying entries in the NT Registry at:

\\HKEY_LOCAL_MACHINE\SOFTWARE\Netscape\MMP 

Capability="IMAP IMAP4rev1 AUTH=LOGIN AUTH=PLAIN X-NETSCAPE"

• Environment variables. You can specify and store configuration environment variables prior to running Multiplexor. When you run Multiplexor, it uses these environment variables as its configuration parameters. For general information about setting configuration parameters, see Multiplexor Configuration; for platform specific information, see Multiplexor Configuration (Unix) and Multiplexor Configuration (NT); for a description of available configuration parameters, see Table 13.3.
• Command-line options. You can specify configuration parameters as command-line options at the time you run Multiplexor. When you use command-line options, they are used instead of any corresponding environment variable for that session of Multiplexor only. For more information, see Command-Line Configuration Options; for a description of available options, see Table 13.4.

To run an installed Multiplexor instance in a Unix environment, you can use either the PopProxy command or PopMMP script to start up POP service, or either the ImapProxy command or the ImapMMP script to start up IMAP service.

When you start Multiplexor with either the PopProxy or ImapProxy commands, you can specify configuration options on the command line. Configuration parameters that you do not specify on the command line are taken from previously set environment variables or set to default values.

PopProxy [options]

ImapProxy [mode] [options]

You can start Multiplexor by running either the PopMMP or ImapMMP scripts. These scripts can be placed in your init directory for automatic startup, or used in the same way as any other Unix command scripts.

PopMMP

ImapMMP

The preferred method of running an installed Multiplexor instance in a Windows NT environment is with the Service Control Manager in the Windows Control Panel. You can use the Service Control Manager to start and stop Multiplexor instances.

PopProxy start [options]

ImapProxy start [options]

PopProxy service [options]

ImapProxy service [options]

To uninstall Multiplexor in Unix environments:

1. Remove CONFIG_FILE from /etc/netscape.mmp.conf.
2. Remove the MMPRoot directory and its subdirectories.

To uninstall all Multiplexor instances on a given machine in a Windows NT environment:

1. From the command line, go to the server-root directory:

For example, cd c:\netscape\server4

2. Enter the following command:

    uninstall

1. From the command line, go to the directory of the instance you want to uninstall

For example, cd netscape\server4\mmp-mplex1.

2. Enter the following commands:

    ImapProxy uninstall 
    PopProxy uninstall