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