Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Messaging Server 6 2004Q2 Administration Guide 

Chapter 4
Configuring General Messaging Capabilities

This chapter describes the general Messaging Server tasks—such as starting and stopping services and configuring directory access—that you can perform by using Sun ONE Server Console (hereafter called Console) or by using command-line utilities. Tasks specific to individual Messaging Server services—such as POP, IMAP, HTTP, and SMTP—are described in subsequent chapters. This chapter contains the following sections:

To Modify Your Passwords

Because you set up a number of administrators with the same password in during initial configuration (see To Create the Initial Messaging Server Runtime Configuration), you might want to change the passwords of those administrators.

Refer to Table 4-1, which shows the parameters where default passwords are set up during initial runtime configuration and the utilities you can use to change them. For those parameters that use the configutil utility to change for complete syntax and usage.

Table 4-1  Passwords Set in Messaging Server Initial Runtime Configuration 




Password for the user/group administrator set through the configutil utility.


Password for user specified by Bind DN for PAB searches set through the configutil utility.

SSL passwords for key files

Passwords that are directly set in the sslpassword.conf file.

Service Administrator Credentials

These are credentials that are directly set in your LDAP Directory (with the ldapmodify command).

Service Administrator for Delegated Administrator

You will only need to change the password of this administrator if you have enabled Sun LDAP Schema 1 and you are using the Delegated Administrator utility.

To change the password of the Delegated Administrator Service Administrator, you can do so in the Sun ONE Console, your LDAP Directory (with the ldapmodify command), or the Delegated Administrator UI.

Store Administrator

To change the password of the Store Administrator, you can do so in either the Sun ONE Console or in your LDAP Directory (with the ldapmodify command).

The following example uses the local.enduseradmincred configutil parameter to change the password of the end user administrator.

configutil -o local.enduseradmincred -v newpassword

Managing Mail Users, Mailing Lists and Domains

All user, mailing list and domain information is stored as entries in an LDAP directory. An LDAP directory can contain a wide range of information about an organization’s employees, members, clients, or other types of individuals that in one way or another “belong” to the organization. These individuals constitute the users of the organization.

In the LDAP directory, the information about users is structured for efficient searching, with each user entry identified by a set of attributes. Directory attributes associated with a user can include the user’s name and other identification, division membership, job classification, physical location, name of manager, names of direct reports, access permission to various parts of the organization, and preferences of various kinds.

In an organization with electronic messaging services, many if not all users hold mail accounts. For Messaging Server, mail-account information is not stored locally on the server; it is part of the LDAP user directory. The information for each mail account is stored as mail attributes attached to a user’s entry in the directory.

Creating and managing mail users and mailing lists consists of creating and modifying user and mailing list entries in the directory. This is done using the User Management Utility for Sun LDAP Schema 2 and the iPlanet Delegated Administrator for Messaging, Delegated Administrator command line utilities, or by directly modifying the LDAP directory for Sun LDAP Schema 1.

To Remove a User from Messaging Server

  1. Mark the user as deleted by running the commadmin user delete command. (See Sun Java System Communications Services 6 2004Q2User Management Utility Admin Guide at
  2. Remove resources from the user.
  3. A resource can be a mailbox or a calendar. For Messaging Server, the program is called msuserpurge. (See Sun Java System Messaging Server Administration Reference at For calendar services, the program is csclean. (See Sun Java System Calendar Server Administration Guide

  4. Permanently remove the user, by invoking the commadmin domain purge command.

To Remove a Domain from Messaging Server

  1. Mark the domain as deleted by running the commadmin domain delete command. (See Sun Java System Communications Services 6 2004Q2User Management Utility Admin Guide at
  2. Remove resources from the users of that domain.
  3. A resource can be a mailbox or a calendar. For Messaging Server, the program is called msuserpurge. (See Sun Java System Messaging Server Administration Reference at For calendar services, the program is csclean. (See Sun Java System Calendar Server Administration Guide

  4. Permanently remove the domain, by invoking the commadmin domain purge command.

Managing Messaging Server with Sun ONE Console

When the messaging server installation process and initial runtime configuration program completes, you can start your Messaging Server through the Admin Console. If your directory and messaging server reside on a single machine, you can use the Console interface to manage both servers.

To invoke the console, run the /usr/sbin/mpsconsole command.

You can review some of the basic information about an installed Messaging Server by viewing its Information form in the Sun ONE Server Console.

To display the Information form:

  1. In Console, open the Messaging Server whose information you want to view.
  2. Select the server’s icon in the left pane.
  3. Click the Configuration tab in the left pane.
  4. Click the Information tab in the right pane, if it is not already frontmost.
  5. The Information form appears. It displays the server name, server root directory, installation directory, and instance directory.

Starting and Stopping Services

Services are started and stopped differently depending on whether they are installed in an HA environment or not.

To Start and Stop Services in an HA Environment

While the Messaging Server is running under HA control, you cannot use the normal Messaging Server start, restart, and stop commands to control individual Messaging Server services. If you attempt a stop-msg in an HA deployment, the system warns that it has detected an HA setup and will tell you how to properly stop the system.

The appropriate start, stop and restart commands are shown in the tables below. Note that there are no specific HA commands to individually start, restart, or stop other Messaging Server services (for example, SMTP). However, you can run a stop-msg service command to stop/restart individual servers such as imap, pop or sched.

Sun Cluster’s finest granularity is that of an individual resource. Since Messaging Server is known to Sun Cluster as a resource, scswitch commands affect all Messaging Server services as a whole.

Table 4-2  Start, Stop, Restart in a Sun Cluster 3.0/3.1 Environment


Individual Resource

Entire Resource Group


scswitch -e -j resource

sscswitch -Z -g resource_group


scswitch -n -j resource
scswitch -e -j

scswitch -R -g resource_group


scswitch -n -j resource

scswitch -F -g resource_group

Table 4-3  Start, Stop, Restart in Veritas 1.3, 2.0, 2.1, and 3.5 Environments


Individual Resource

Entire Resource Group


hares -online resource -sys system

hagrp -online group -sys system


hares -offline resource -sys system
hares -online resource -sys system

hagrp -offline group -sys system
hagrp -online group -sys system


hares -offline resource -sys system

hagrp -offline group -sys system

To Start and Stop Services in a non-HA Environment

You can start and stop services from Console or from the command line. In addition, you only need to run the services that your server actually uses. For example, if you are using Messaging Server solely as a message transfer agent (MTA), you can turn on the MTA alone. Or, if maintenance, repair, or security needs require shutting down the server, you may be able to turn off just the affected service. (If you never intend to run a particular service, you should disable it instead of just turning it off.)


You must first enable services such as POP, IMAP, and HTTP, before starting or stopping them. For more information, see Enabling and Disabling Services.

Important: If a server process crashes, other processes may hang as they wait for locks held by the server process that crashed. If you are not using automatic restart (see Automatic Restart of Failed or Unresponsive Services), and if any server process crashes, you should stop all processes, then restart all processes. This includes the POP, IMAP, HTTP, and MTA processes, as well as the stored (message store) process, and any utilities that modify the message store, such as mboxutil, deliver, reconstruct, readership, or upgrade.

Console: Console provides a form that allows you to start and stop individual services and view status information about each service.

For each service—IMAP, POP, SMTP, and HTTP—the form displays the service’s current state (on or off). If the service is running, the form shows the time at which the service was last started up. It can also display other status information.

To start up, shut down, or view the status of any messaging services:

  1. From Console, open the Messaging Server whose services you want to start or stop.
  2. Get to the Services General Configuration form in either of these two ways:
    1. Click the Tasks tab, then click “Start/Stop Services”.
    2. Click the Configuration tab and select the Services folder in the left pane. Then click the General tab in the right pane.
  3. The Services General Configuration form appears.
  4. The left column of the Process Control field lists the services supported by the server; the right column gives the basic status of each of the services (ON or OFF, plus—if it is ON—the time it was last started).

  5. To view status information about a service that is currently on, select the service in the Process Control field.
  6. The Service Status field displays status information about the service.

    For POP, IMAP, and HTTP the field shows the last connection time, the total number of connections, the current number of connections, the number of failed connections since the service last started, and the number of failed logins since the service last started.

    The information in this field helps you to understand the load on the server and the reliability of its service, and it can help spotlight attacks against the server’s security.

  7. To turn a service on, select it in the Process Control field and click Start.
  8. To turn a service off, select it in the Process Control field and click Stop.
  9. To turn all enabled services on or off simultaneously, click the Start All or Stop All button.

Command Line: You can use the start-msg and stop-msg commands to start or stop any of the messaging services (smtp, imap, pop, store, http, ens, sched), as shown in the following example:

msg_svr_base/sbin/start-msg imap
msg_svr_base/sbin/stop-msg pop
msg_svr_base/sbin/stop-msg sched
msg_svr_base/sbin/stop-msg smtp

Note that the services must be enabled in order to stop or start them. See To Specify What Services are Started.


The start-msg smtp and stop-msg smtp commands start and stop all of the MTA services—not just the SMTP server. If you want more granular control when starting or stopping the MTA services, you can use the start/stop msg command for the dispatcher and the job controller. For more information, see the Messaging Server Reference Manual.

To Specify What Services are Started

By default the following services are started with start-msg:

# ./start-msg
Connecting to watcher ...
Launching watcher ...
Starting ens server .... 21132
Starting store server .... 21133
checking store server status ... ready
Starting imap server .... 21135
Starting pop server .... 21138
Starting http server .... 21141
Starting sched server .... 21143
Starting dispatcher server .... 21144
Starting job_controller server .... 21146

These can be controlled by enabling or disabling the configutil parameters: service.imap.enable, service.pop.enable, service.http.enable, local.smsgateway.enable, local.snmp.enable, local.imta.enable, local.mmp.enable, local.ens.enable, and local.sched.enable. Note that you need to set both service.imap.enable and service.imap.enablesslport to 0 in order to disable IMAP. The same goes for POP and HTTP. See the Sun Java System Messaging Server Administration Reference for details on how these work.

Automatic Restart of Failed or Unresponsive Services

Messaging Server provides two processes called watcher and msprobe that transparently monitor services and automatically restart them if they fail or become unresponsive (the services hang or freeze up). watcher monitors server failures. msprobe monitors server response time. When a server fails or stops responding to requests, it is automatically restarted. Table 4-4.

Table 4-4  Services Monitored by watcher and msprobe



IMAP, POP, HTTP, job controller, dispatcher, message store (stored, utilities), imsched, MMP. (LMTP/SMTP servers are monitored by the dispatcher and LMTP/SMTP clients are monitored by the job_controller.)

IMAP, POP, HTTP, job controller, message store (stored, utilities), imsched, ENS, LMTP, SMTP

Setting local.watcher.enable=on (default) will monitor process failures and unresponsive services and will log error messages to the default log file indicating specific failures. To enable automatic server restart, set the configutil parameter local.autorestart to yes. By default, this parameter is set to no.

If any of the message store services fail or freeze, all message store services that were enabled at start-up are restarted.For example, if imapd fails, at the least, stored and imapd are restarted. If other message store services were running, such as the POP or HTTP servers, then those will be restarted as well, whether or not they failed.

Automatic restart also works if a message store utility fails or freezes. For example, if mboxutil fails or freezes, the system will automatically restart all the message store servers. Note, however, that it will not restart the utility. msprobe runs every 10 minutes. Service and process restarts will be performed up to two times within a 10 minute period (configurable using local.autorestart.timeout).

Whether or not local.autorestart is set to yes, the system still monitors the services and sends failure or non-response error messages to the console and msg_svr_base/data/log. watcher listens to port 49994 by default, but this is configurable with local.watcher.port.


A new watcher log file is generated in msg_svr_base/data/log/watcher. This log file is not managed by the logging system (no rollover or purging).

Automatic Restart in High Availability Deployments

Automatic restart in high availability deployments require the following configutil parameters to be set:

Table 4-5  HA Automatic Restart Parameters


Description/HA Value


Enable watcher. On (Default is On)


Enable autorestart. On


Failure retry time-out. If a server fails more than twice in this designated amount of time, then the system stops trying to restart the server. If this happens on an HA system, Messaging Server is shutdown and a failover to the other system occurs. The value (set in seconds) should be set to a period value longer than the msprobe interval (local.schedule.msprobe).


msprobe run schedule. A crontab style schedule string (see Table 18-10). Default is 600 seconds.

To Schedule Automatic Tasks

Messaging Server provides a general task scheduling mechanism using a process called imsched. It is enabled by setting the local.schedule.taskname configutil parameter.

This parameter requires a command and a schedule on which to execute the command. The format is as follows:

configutil -o local.schedule.taskname -v “schedule

taskname is a unique name for this command/schedule combination.

schedule has the format:

minute hour day-of-month month-of-year day-of-week command args

Note that if you modify scheduler, you must either restart the scheduler with the command stop-msg sched and start-msg sched, or you can send SIGHUP to the scheduler process:

kill -HUP scheduler_pid

Scheduler Examples

Run imexpire in verbose mode at 12:30am, 8:30am, and 4:30pm:

configutil -o local.schedule.rm_messages -v 30 0,8,16 * * * /opt/SUNWmsgsr/sbin/imexpire -v

Display MTA channel queue message counters every 20 minutes:

configutil -o local.schedule.counters -v 20,40,60 * * * * /opt/SUNWmsgsr/sbin/imsimta qm counters -show > temp.txt

Run imsbackup Monday through Friday at midnight (12AM):

configutil -o local.schedule.msbackup -v 0 0 * * 1-5 /opt/SUNWmsgsr/sbin/imsbackup -f backupfile /primary

To Configure a Greeting Message

Messaging Server allows you to create a greeting message to be sent to each new user.

Console     To create a new-user greeting by using Console:

  1. In Console, open the Messaging Server whose new-user greeting you want to configure.
  2. Click the Configuration tab. If the server’s icon in the left pane is not already highlighted, select it.
  3. Click the Miscellaneous tab in the right pane.
  4. Create a new-user greeting or make changes, as needed.
  5. You must format the greeting as an email message, with a header (containing at least a subject line), then a blank line, then the message body.

    When you create a message, specify its language with the drop-down list above the message field. You can create several messages in several languages, if desired.

  6. Click Save.

Command Line: To create a new-user greeting by using the command line:

configutil -o gen.newuserforms -v Message

Where Message must contain a header (with at least a subject line), followed by $$, then the message body. The message must contain a header (with at least a subject line), followed by $$, then the message body. The $ represents a new line.

For example, to enable this parameter, you can set the following configuration variables:

configutil -o gen.newuserforms -v ’Subject: Welcome!! $$ welcomes you to the premier internet experience in Dafandzadgad!

Depending on the shell that you are using, it might be necessary to append a special character before $ to escape the special meaning of $. ($ is often the escape character for the shell.)

To Set a Per-Domain Greeting Message

Whenever you create a new hosted domain, it is a good idea to create per-domain greeting messages for your supported languages. If this is not done, the generic greeting message set by gen.newuserform will be sent.

You can set a greeting message for new users in each domain. The message can vary depending on the user’s, the domain’s, or the site’s preferred language. This is done by setting the mailDomainWelcomeMessage attribute in the desired LDAP domain entry. The syntax is as follows:


The following example sets the domain welcome message for English:

mailDomainWelcomeMessage;lang-en: Subject: Welcome!! $$Welcome to the mail system.

The following example sets the domain welcome message for French:

mailDomainWelcomeMessage;lang-fr: Subject: Bienvenue!! $$Bienvenue a!

Using the above examples, we assume the following: 1) the domain is, 2) a new user belongs to this domain, 3) the user’s preferred language is French as specified by the LDAP attribute preferredlanguage, 4) has the above English and French welcome messages available, 5) the site language is en as specified by gen.sitelanguage. See the Directory Server Reference Manual for a list of supported locales and their language value tag (

When the user logs in for the first time, they will receive the French greeting. If the French welcome message isn’t available, they will get the English greeting.

Greeting Message Theory of Operations

Greeting messages can be set by both the LDAP attribute mailDomainWelcomeMessage and the configutil parameter gen.newuserforms. The order in which a message will get chosen, with the top one having the highest preference, is shown below:


The algorithm works as follows: if there are no domains (or there are, but there is no per domain welcome message provisioned for them), a welcome message is configured with the gen.newuserforms parameter, if specified. If a user has a preferred language (set with the preferredlanguage LDAP attribute) and gen.newuserforms;lang-user_prefLang is set, the user will receive that welcome message at the time of their first log in to the server. If gen.newuserforms;lang-gen.sitelanguage is set, and preferredlanguage is not set, but the site language is set (using gen.sitelanguage parameter), user will receive that message. If no language tag parameter is set and a plain gen.newuserforms is set, then that message will be sent to the user. If none of the values are set, user will not receive any welcome message.

If the user is in a domain, then similar to the discussion above, the user might receive one of mailDomainWelcomeMessage;lang-xx, depending on which one is available in the list and in the order given.

Example: Domain is The domain preferred language is German (de). But the new user in this domain has preferred language of Turkish (tr). Site language is English. The following values are available (mailDomainWelcomeMessage are attributes of the domain


According to the algorithm, the message sent to user will be gen.newuserforms;lang-de.

To Set a User-Preferred Language

Administrators can set a preferred language by setting the attribute preferredLanguage in the user’s LDAP entry.

When the server sends messages to users outside of the server’s administrative domain it does not know what their preferred language is unless it is responding to an incoming message with a preferred language specified in the incoming message’s header. The header fields (accept-language, Preferred-Language or X-Accept-Language) are set according to attributes specified in the user’s mail client.

If there are multiple settings for the preferred language—for example, if a user has a preferred language attribute stored in the Directory Server and also has a preferred language specified in their mail client—the server chooses the preferred language in the following order:

  1. The accept-language header field of the original message.
  2. The Preferred-Language header field of the original message.
  3. The X-Accept-Language header field of the original message.
  4. The preferred language attribute of the sender (if found in the LDAP directory).

To Set a Domain Preferred Language

A domain preferred language is a default language specified for a particular domain. For example, you may wish to specify Spanish for a domain called Administrators can set a domain preferred language by setting the attribute preferredLanguage in the domain’s LDAP entry.

To Configure a Server Site Language

You can specify a default site language for your server as follows. The site language will be used to send language-specific versions of messages if no user preferred language is set.

Console: To specify a site language from Console:

  1. Open the Messaging Server you want to configure.
  2. Click the Configuration tab.
  3. In the right pane, click the Miscellaneous tab.
  4. From the site language drop-down list, choose the language you wish to use.
  5. Click Save.

Command Line: you can also specify a site language at the command line as follows:

configutil -o gen.sitelanguage -v value

where value is one of the local supported languages. See the Directory Server Reference Manual for a list of supported locales and the language value tag (

To Customize Directory Lookups

Messaging Server cannot function without an LDAP-based directory system such as the Sun Java System Directory Server. Messaging Server and Console require directory access for three purposes:

You can modify each of these directory-configuration settings in the following ways:

Reconfiguring your Messaging Server to connect to a different user directory for user and group lookups is strictly optional. In most cases, the user directory that defines your server’s administrative domain is the one used by all servers in the domain.


If you specify a custom user directory for your Messaging Server lookups, you must also specify that same directory whenever you access the Users and Groups interface of Console to make changes to the directory’s user or group information.

Console: To modify the Messaging Server LDAP user-lookup settings by using Console:

  1. From Console, open the Messaging Server whose LDAP connection you want to customize.
  2. Click the Configuration tab.
  3. Select the Services folder in the left pane.
  4. Select the LDAP tab in the right pane. The LDAP form appears.
  5. The LDAP form displays the configuration settings for both the configuration directory and the user directory. The configuration-directory settings, however, are read-only in this form. See the Administration Server chapter of Sun ONE Server Console 5.2 Server Management Guide if you need to change them.

  6. To change the user-directory connection settings, click the box labeled “Use messaging server specific directory settings”.
  7. Update the LDAP configuration by entering or modifying any of the following information (for explanations of directory concepts, including definitions of terms such as distinguished name, see the Directory Server Administration Guide):
  8. Host name: The name of the host machine on which the directory containing your installation’s user information resides. This is typically not the same as the Messaging Server host, although for very small installations it might be.

    Port number: The port number on the directory host that Messaging Server must use to access the directory for user lookup. This number is defined by the directory administrator, and may not necessarily be the default port number (389).

    Base DN: The search base—the distinguished name of a directory entry that represents the starting point for user lookups. To speed the lookup process, the search base should be as close as possible in the directory tree to the information being sought. If your installation’s directory tree has a “people” or “users” branch, that is a reasonable starting point.

    Bind DN: The distinguished name that your Messaging Server uses to represent itself when it connects to the directory server for lookups. The bind DN must be the distinguished name of an entry in the user directory itself that has been given search privileges to the user portion of the directory. If the directory allows anonymous search access, you can leave this entry blank.

  9. To change the password used, in conjunction with the Bind DN, to authenticate this Messaging Server to the LDAP directory for user lookups, click the Change Bind password button. A Password-Entry window opens, into which you can enter the updated password.
  10. Your own security policies should determine what password you use in this situation. Initially, the password is set to no password. The password is not used if you have specified anonymous access by leaving the Bind DN field blank.

    This step updates the password stored in server configuration, but does not change the password in the LDAP server. This account is also used for PAB lookups by default. The following two steps need to be performed after the password has been changed.

  11. Modify the password for the user specified in the configuration attribute local.ugldapbinddn. This user account exists in the directory server specified in configuration attribute local.ugldaphost.
  12. If the same account is used for PAB access, specified in the attributes local.service.pab.ldapbinddn and local.service.pab.ldaphost, then the password stored in local.service.pab.ldappasswd must be updated.

To return to using the default user directory, uncheck the “Use messaging server specific directory settings” box.

Command Line: You can also set values for the user-directory connection settings at the command line as follows. Be sure to also set the LDAP and PAB password as described in the steps 8 and 9 above.

To specify whether to use messaging server specific directory settings:

configutil -o local.ugldapuselocal -v [ yes | no ]

To specify the LDAP host name for user lookup:

configutil -o local.ugldaphost -v name[:port_number]

To specify the LDAP port number for user lookup:

configutil -o local.ugldapport -v number

To specify the LDAP base DN for user lookup:

configutil -o local.ugldapbasedn -v basedn

To specify the LDAP bind DN for user lookup:

configutil -o local.ugldapbinddn -v binddn

Encryption Settings

You can use Console to enable Secure Sockets Layer (SSL) encryption and authentication for Messaging Server and to select the specific encryption ciphers that the server will support across all of its services.

Although this task is a general configuration task, it is described in the section “Enabling SSL” in Chapter 19, "Configuring Security and Access Control"” which also contains background information on all security and access-control topics for Messaging Server.

Setting a Failover LDAP Server

It is possible to specify more than one LDAP server for the user/group directory so that if one fails another takes over:

  1. Set local.ugldaphost to the multiple LDAP machines. Example:
  2. configutil -o local.ugldaphost -v "server1 server2 ..."

  3. Set local.ugldapuselocal to yes. This specifies that the user/group LDAP configuration data will be stored in the local configuration file. Otherwise, it is stored in LDAP. Example:
  4. configutil -o local.ugldapuselocal -v yes

If the first server on the list fails, the existing LDAP connections will get recognized as down and new connections will be made. When a new ldap connection is needed, the ldap library will try all the ldap servers in the order they’re listed.

Just as there is failover for the user/group directory one can similarly set failover servers for configuration directory. The configuration attribute is local.ldaphost.

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.