5.1 General Configuration

Configuring the general features of the Messaging
Server POP, IMAP, and HTTP services includes enabling or disabling the services,
assigning port numbers, and optionally modifying service banners sent to connecting
clients. This section provides background information; for the steps you follow
to make these settings, see 5.5 To Configure POP Services, 5.6 To Configure IMAP Services and 5.7 To Configure HTTP Services. This section consists of the following
subsections:

5.1.1 Enabling and Disabling Services

You can control whether any particular instance of Messaging Server
makes its POP, IMAP, or HTTP service available for use.
This is not the same as starting and stopping services (see 4.4 Starting and Stopping Services); to function, POP,
IMAP, or HTTP must be both enabled and started.

Enabling a service is a more “global” process than starting
or stopping a service. For example, the Enable setting persists across system
reboots, whereas you must restart a previously “stopped” service
after a reboot.

There is no need to enable services that you do not plan to use. For
example, if a Messaging Server instance is used only as a mail transfer agent
(MTA), you should disable POP, IMAP, and HTTP. If it is used only for POP
services, you should disable IMAP and HTTP. If it used only for web-based
email, you should disable both POP and IMAP.

You can enable or disable services at the server level. This process
is described in this chapter. 4.4.2.1 To Specify What Services Can Be Started also describes this process. You can also enable or
disable services at the user level by setting the LDAP attribute mailAllowedServiceAccess.

5.1.2 Specifying Port Numbers

For each service, you can specify the port number that the server is
to use for service connections:

If you enable the POP service, you can specify the port number
that the server is to use for POP connections. The default is 110.

If you enable the IMAP service, you can specify the port number
that the server is to use for IMAP connections. The default is 143.

If you enable the HTTP service, you can specify the port number
that the server is to use for HTTP connections. The default is 80.

You might need to specify a port number other than the default if you
have, for example, two or more IMAP server instances on a single host machine,
or if you are using the same host machine as both an IMAP server and a Messaging
Multiplexor server. (For information about the Multiplexor, see Chapter 7, Configuring and Administering Multiplexor Services.

Keep the following in mind when you specify a port:

Port numbers can be any number from 1 to 65535.

Make sure the port you choose isn’t already in use or
reserved for another service.

5.1.3.1 IMAP Over SSL

You can accept the default (recommended) IMAP over SSL port number (993)
or you can specify a different port for IMAP over SSL.

Messaging Server provides the option of using separate ports for IMAP
and IMAP over SSL because most current IMAP clients require separate ports
for them. Same-port communication with both IMAP and IMAP over SSL is an emerging
standard; as long as your Messaging Server has an installed SSL certificate
(see 23.5.1 Obtaining Certificates), it can support
same-port IMAP over SSL.

5.1.3.2 POP Over SSL

The default separate SSL port for POP is 995. One can also initiate
SSL over normal POP port with the command “STLS” (see 5.5 To Configure POP Services).

5.1.3.3 HTTP Over SSL

You can accept the default HTTP over SSL port number (443) or you can
specify a different port for HTTPS.

5.1.4 Service Banner

When a client first connects to the Messaging Server POP or IMAP port,
the server sends an identifying text string to the client. This service banner
(not normally displayed to the client’s user) identifies the server
as Sun Java System Messaging Server, and gives the server’s version number.
The banner is most typically used for client debugging or problem-isolation
purposes.

You can replace the default banner for the POP or IMAP service if you
want a different message sent to connecting clients.

5.2 Login Requirements

You can control how users are permitted to log in to the POP, IMAP,
or HTTP service to retrieve mail. You can allow password-based login (for
all services), and certificate-based login (for IMAP or HTTP services). This
section provides background information; for the steps you follow to make
these settings, see 5.5 To Configure POP Services, 5.6 To Configure IMAP Services or 5.7 To Configure HTTP Services. In addition, you can specify the valid
login separator for POP logins. This section consists of the following subsections:

To Set the Login Separator for POP Clients

Some mail clients will not accept @ as the login separator (that is,
the @ in an address like uid@domain).
Examples of these clients are Netscape Messenger 4.76, Netscape Messenger
6.0, and Microsoft Outlook Express on Windows 2000. The workaround is as follows:

Make + a
valid separator with the following command:

configutil
-oservice.loginseparator -v "@+"

Inform POP client users that they should login with + as
the login separator, not @.

5.2.1 To Allow Log In without Using the Domain Name

A typical login involves the user entering a user ID followed by a separator
and the domain name and then the password. Users in the default domain specified
during installation, however, can log in without entering a domain name or
separator.

To allow users of other domains to log in with just the user ID (that
is, without having to use the domain name and separator) set sasl.default.ldap.searchfordomain to 0. Note that the user ID must be unique to the entire directory
tree. If it is not unique, logging in without the domain name will not work.

You may wish to modify the attribute that user must enter to log in.
For example if you want to allow the user to log in with a phone number (telephoneNumber) or employee number (employeeID)
change the LDAP search defined by configutil parameter sasl.default.ldap.searchfilter. This parameter is a global default
setting for the inetDomainSearchFilter per-domain attribute
and follows the same syntax.

5.2.2 Password-Based Login

In typical messaging installations, users access their mailboxes by
entering a password into their POP. IMAP or HTTP mail client. The client sends
the password to the server, which uses it to authenticate the user. If the
user is authenticated, the server decides, based on access-control rules,
whether or not to grant the user access to certain mailboxes stored on that
server.

If you allow password login, users can access POP, IMAP, or HTTP by
entering a password. (Password- or SSL-based login is the only authentication
method for POP services.) Passwords are stored in an LDAP directory. Directory
policies determine what password policies, such as minimum length, are in
effect.

If you disallow password login for IMAP or HTTP services, password-based
authentication is not permitted. Users are then required to use certificate-based
login, as described in the next section.

To increase the security of password transmission for IMAP and HTTP
services, you can require that passwords be encrypted before they are sent
to your server. You do this by selecting a minimum cipher-length requirement
for login.

If you choose 0, you do not require encryption. Passwords
are sent in the clear or they are encrypted, depending on client policy.

If you choose a nonzero value, the client must establish an
SSL session with the server—using a cipher whose key length is at least
the value you specify—thus encrypting any IMAP or HTTP user passwords
the client sends.

If the client is configured to require encryption with key lengths greater
than the maximum your server supports, or if your server is configured to
require encryption with key lengths greater than what the client supports,
password-based login cannot occur. For information on setting up your server
to support various ciphers and key lengths, see 23.5.2 To Enable SSL and Selecting Ciphers.

5.2.3 Certificate-Based Login

In addition to password-based authentication, Sun Java System servers
support the authentication of users through examination of their digital certificates.
Instead of presenting a password, the client presents the user’s certificate
when it establishes an SSL session with the server. If the certificate is
validated, the user is considered authenticated.

If you have performed the tasks required to set up certificate-based
login, both password-based and certificate-based login are supported. Then,
if the client establishes an SSL session and supplies a certificate, certificate-based
login is used. If the client does not use SSL or does not present a client
certificate, it will send a password instead.

5.3 Performance Parameters

You can set some of the basic performance parameters for the POP, IMAP,
and HTTP services of Messaging Server. Based on your hardware capacity and
your user base, you can adjust these parameters for maximum efficiency of
service. This section provides background information; for the steps you follow
to make these settings, see 5.5 To Configure POP Services, 5.6 To Configure IMAP Services or 5.7 To Configure HTTP Services. This section consists of the following
subsections:

5.3.1 Number of Processes

Messaging Server can divide its work among several executing processes,
which in some cases can increase efficiency. This capability is especially
useful with multiprocessor server machines, in which adjusting the number
of server processes can allow more efficient distribution of multiple tasks
among the hardware processors.

There is a performance overhead, however, in allocating tasks among
multiple processes and in switching from one process to another. The advantage
of having multiple processes diminishes with each new one added. A simple
rule of thumb for most configurations is to have one process per hardware
processor on your server machine, up to a maximum of perhaps 4 processes.
Your optimum configuration may be different; this rule of thumb is meant only
as a starting point for your own analyses.

Note: On some platforms you might
also want to increase the number of processes to get around certain per-process
limits (such as the maximum number of file descriptors), specific to that
platform, that may affect performance.

The default number of processes is 1 each for the POP, IMAP, or HTTP
service.

5.3.2 Number of Connections per Process

The more simultaneous client connections your POP, IMAP, or HTTP service
can maintain, the better it is for clients. If clients are denied service
because no connections are available, they must then wait until another client
disconnects.

On the other hand, each open connection consumes memory resources and
makes demands on the I/O subsystem of your server machine, so there is a practical
limit to the number of simultaneous sessions you can expect the server to
support. (You might be able to increase that limit by increasing server memory
or I/O capacity.)

IMAP, HTTP, and POP have different needs in this regard:

IMAP connections are generally long-lived compared to POP
and HTTP connections. When a user connects to IMAP to download messages, the
connection is usually maintained until the user quits or the connection times
out. In contrast, a POP or HTTP connection is usually closed as soon as the
POP or HTTP request has been serviced.

IMAP and HTTP connections are generally very efficient compared
to POP connections. Each POP reconnection requires reauthentication of the
user. In contrast, an IMAP connection requires only a single authentication
because the connection remains open for the duration of the IMAP session (login
to logout). An HTTP connection is short, but the user need not reauthenticate
for each connection because multiple connections are allowed for each HTTP
session (login to logout). POP connections, therefore, involve much greater
performance overhead than IMAP or HTTP connections. Messaging Server, in particular,
has been designed to require very low overhead by open but idle IMAP connections
and by multiple HTTP connections.

Thus, at a given moment for a given user demand, Messaging Server may
be able to support many more open IMAP or HTTP connections than POP connections.

The default value for IMAP is 4000; the default value for HTTP is 6000
connections per process; the default value for POP is 600. These values represent
roughly equivalent demands that can be handled by a typically configured server
machine. Your optimum configuration may be different; these defaults are meant
only as general guidelines.

Typically, active POP connections are much more demanding on server
resources and bandwidth than active IMAP connections since IMAP connections
are idle most of the time while POP connections are constantly downloading
messages. Having a lower number of sessions for POP is correct. Conversely,
POP connections only last as long as it takes to download email, so an active
POP user is only connected a small percentage of the time, while IMAP connections
stay connected between successive mail checks.

5.3.3 Number of Threads per Process

Besides supporting multiple processes, Messaging Server further improves
performance by subdividing its work among multiple threads. The server’s
use of threads greatly increases execution efficiency, because commands in
progress are not holding up the execution of other commands. Threads are created
and destroyed, as needed during execution, up to the maximum number you have
set.

Having more simultaneously executing threads means that more client
requests can be handled without delay, so that a greater number of clients
can be serviced quickly. However, there is a performance overhead to dispatching
among threads, so there is a practical limit to the number of threads the
server can make use of.

For POP, IMAP, and HTTP, the default maximum value is 250 threads per
process. The numbers are equal despite the fact that the default number of
connections for IMAP and HTTP is greater than for POP. It is assumed that
the more numerous IMAP and HTTP connections can be handled efficiently with
the same maximum number of threads as the fewer, but busier, POP connections.
Your optimum configuration may be different, but these defaults are high enough
that it is unlikely you would ever need to increase them; the defaults should
provide reasonable performance for most installations.

5.3.4 Dropping Idle Connections

To reclaim system resources used by connections from unresponsive clients,
the IMAP4, POP3, and HTTP protocols permit the server to unilaterally drop
connections that have been idle for a certain amount of time.

The respective protocol specifications require the server to keep an
idle connection open for a minimum amount of time. The default times are 10
minutes for POP, 30 minutes for IMAP, 3 minutes for HTTP. You can increase
the idle times beyond the default values, but you cannot make them less.

If a POP or IMAP connection is dropped, the user must reauthenticate
to establish a new connection. In contrast, if an HTTP connection is dropped,
the user need not reauthenticate because the HTTP session remains open. For
more information about HTTP session security, see 23.2 About HTTP Security.

Idle POP connections are usually caused by some problem (such as a crash
or hang) that makes the client unresponsive. Idle IMAP connections, on the
other hand, are a normal occurrence. To keep IMAP users from being disconnected
unilaterally, IMAP clients typically send a command to the IMAP server at
some regular interval that is less than 30 minutes.

5.3.5 Logging Out HTTP Clients

An HTTP session can persist across multiple connections. HTTP clients
are not logged out when a connection is dropped. However, if an HTTP session
remains idle for a specified time period, the server will automatically drop
the HTTP session and the client is logged out (the default time period is
2 hours). When the session is dropped, the client’s session ID becomes
invalid and the client must reauthenticate to establish another session. For
more information about HTTP security and session ID’s, see 23.2 About HTTP Security.

5.4 Client Access Controls

Messaging Server includes access-control features that allow you to
determine which clients can gain access to its POP, IMAP, or HTTP messaging
services (and SMTP as well). You can create flexible access filters that allow
or deny access to clients based on a variety of criteria.

Command Line: You can set values
for the IMAP attributes at the command line as follows:

To enable or disable the IMAP service:

configutil -o service.imap.enable -v [ yes | no ]

To specify the port number:

configutil -o service.imap.port -vnumber

To enable a separate port for IMAP over SSL:

configutil -o service.imap.enablesslport -v [ yes | no ]

To specify a port number for IMAP over SSL:

configutil -o service.imap.sslport -vnumber

To enable or disable password login to the IMAP service:

configutil -o service.imap.plaintextmincipher -vvalue

If valueis > 0, then disable use of plaintext
passwords unless a security layer (SSL or TLS) is activated. This forces
users to enable SSL or TLS on their client to login which prevents exposure
of their passwords on the network. Default is 0.

5.6.1 Configuring IMAP IDLE

The IMAP IDLE extension to the IMAP specification, defined in RFC 2177,
allows an IMAP server to notify the mail client when new messages arrive and
other updates take place in a user's mailbox. The IMAP IDLE feature has the
following benefits:

Mail clients do not have to poll the IMAP server for incoming
messages.

Eliminating client polling reduces the workload on
the IMAP server and enhances the server's performance. Client polling is most
wasteful when a user receives few or no messages; the client continues to
poll at the configured interval, typically every 5 or 10 minutes.

A mail client displays a new message to the user much closer
to the actual time it arrives in the user's mailbox. A change in message status
is also displayed in near-realtime.

The IMAP server does not have
to wait for the next IMAP polling message before it can notify the client
of a new or updated mail message. Instead, the IMAP server receives a notification
as soon as a new message arrives or a message changes status. The server then
notifies the client through the IMAP protocol.

5.6.1.1 Prerequisites

The IMAP IDLE feature relies on the Event Notification Service
(ENS) to propagate notifications. To use IMAP IDLE, you must configure the
following ENS components:

An enpd server on at least one host

The iBiff notification plug-in on all message
store hosts

For information on configuring ENS for Messaging Server, see the Sun Java System Communications Services Event Notification Service Guide.

If
the ENS event key (ensEventKey) is set to its default value,
IMAP IDLE does not operate.

You must configure the ensEventKey value to end with %M. The string %M is
a substitution code that is replaced by the name of the mailbox in which the
event occurred.

Run the following configutil command:

./configutil -o local.store.notifyplugin.enseventkey -v "eventkey"

where eventkey is a unique identifier used by ENS.
Its default value is enp://127.0.0.1/store. The host-name
portion of the event key is not used to determine the host where ENS is running;
it is simply part of the identifier.

5.7 To Configure HTTP Services

Messaging Server supports the HTTP mail clients called Messenger Express
and Communications Express. While POP and IMAP clients send mail directly
to a Messaging Server MTA for routing or delivery, HTTP clients send mail
to a specialized web server called the Webmail Server (also called mshttpd
or Messaging Server http daemon). Depending on where the message is addressed,
the Webmail Server will direct the mail to an outbound MTA for routing or
to one of the backend message stores using IMAP. This is shown in Figure 5–1. Note that the Communications Express
Server simply routes requests to and from the Webmail Server.

Figure 5–1 HTTP Service Components

In previous versions, the Webmail Server accessed the message store
directly. Now, it accesses the message store through the IMAP server. This
provides several advantages:

Messenger Express and Communications Express clients are now
able to access shared folders that are located on different back-end message
stores.

The Webmail Server no longer must be installed on each back-end
server.

The Webmail Server can serve as a front-end server performing
the multiplexing capabilities previously performed by Messenger Express Multiplexor
(MEM).

MEM is obsoleted and is no longer used.

On the client side, nothing is changed except that users can
now access shared folders that are not on their message store.

In previous versions, the MEM received HTTP client requests and forwarded
it to the appropriate Webmail Server on the back-end message store. Because
of this, a copy of mshttpd had to be installed on every back-end server.
Now, the Webmail Server operates as a front-end server receiving HTTP client
email requests. It translates these requests to SMTP or IMAP calls and forwards
the calls to either the MTA or the appropriate IMAP server on the back-end
message store. If Messaging Server is used only for web-based email, make
sure that IMAP is enabled.

For each IMAP server that users access, the Webmail Server needs to
know the IMAP port, whether to use SSL, and the admin credentials to use for
user log-in. The configutil parameters to do this are as
follows:

local.service.proxy.imapport[.hostname] — IMAP port on which to connect (default 143).

local.service.proxy.imapssl — Enable SSL (default
no).

local.service.proxy.admin[.hostname] — Admin ID.

local.service.proxy.adminpass[.hostname] — Admin password.

These parameters can be set globally (applying to every IMAP backend
server), or for each individual IMAP backend server by appending the backend's
fully qualified domain name to the option name.

In order to use IMAP over SSL, the mshttpd must be also configured as
an SSL HTTP server, and the mshttpd certificate database must trust the IMAP
backend's CA. You MUST enable service.http.sslusessl. If
the backend message store running IMAP is using a self-signed certificate
(for example, as created by generate-certDB) then this
certificate needs to be added to the front-end mshttpd daemon
server.

Note that if local.service.proxy.admin/pass isn't
set, logins will be rejected with the error Mail server unavailable.
Administrator, check server log for details. and the http log will
list the missing configuration options.

Additional values for HTTP attributes can be set at the command line
as follows:

To enable or disable the HTTP service:

configutil -oservice.http.enable -v [ yes | no ]

By default, the HTTP service sends outgoing web mail to the local MTA
for routing or delivery. You might want to configure the HTTP service to send
mail to a remote MTA, for example, if your site is a hosting service and most
recipients are not in the same domain as the local host machine. To send web
mail to a remote MTA, you need to specify the remote host name and the SMTP
port number for the remote host. To specify the port number:

configutil -oservice.http.port -vnumber

To enable a separate port for HTTP over SSL:

configutil -oservice.http.enablesslport -v [ yes | no ]

To specify a port number for HTTP over SSL:

configutil -oservice.http.sslport -vnumber

To enable or disable password login:

configutil -oservice.http.plaintextmincipher -vvalue

If valueis > 0, then disable use of plaintext
passwords unless a security layer (SSL or TLS) is activated. This forces
users to enable SSL or TLS on their client to login which prevents exposure
of their passwords on the network. Default is 0.

When an HTTP client constructs a message with attachments, the attachments
are uploaded to the server and stored in a file. The HTTP service retrieves
the attachments and constructs the message before sending the message to an
MTA for routing or delivery. You can accept the default attachment spool directory
or specify an alternate directory. You can also specify a maximum size allowed
for attachments. To specify the attachment spool directory for client outgoing
mail use the following command. Note that this includes all the attachments
encoded in base64, and that base64 encoding requires an extra 33% more space.
Thus a 5 megabyte limit in the parameter results in the maximum size of one
message and attachments being about 3.75 megabytes.

configutil -oservice.http.spooldir -vdirpath

To specify the maximum message size:

configutil -oservice.http.maxmessagesize -vsize

where size is a number in bytes. Note that
this includes all the attachments encoded in base64, and that base64 encoding
requires an extra 33% more space. Thus a 5 megabyte limit in the parameter
results in the maximum size of one message and attachments being about 3.75M.