Chapter 4 Configuring General Messaging Capabilities

This chapter describes the general Messaging Server tasks—such as starting and stopping services and configuring directory access 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:

• 4.1 To Modify Your Passwords

• 4.2 Managing Mail Users, Mailing Lists and Domains

• 4.3 Managing Messaging Server with Sun ONE Console

• 4.4 Starting and Stopping Services

• 4.5 Automatic Restart of Failed or Unresponsive Services

• 4.6 To Schedule Automatic Tasks

• 4.7 To Configure a Greeting Message

• 4.8 To Set a User-Preferred Language

• 4.9 To Customize Directory Lookups

• 4.10 Encryption Settings

• 4.11 Setting a Failover LDAP Server

• 4.12 Email Security Concerns

4.1 To Modify Your Passwords

Because you set up a number of administrators with the same password during initial configuration (see 1.3 Creating 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, see configutil in Sun Java System Messaging Server 6.3 Administration Reference for complete syntax and usage.

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

configutil -o local.enduseradmincred -v newpassword

4.2 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 Delegated Administrator for Sun LDAP Schema 2 and the iPlanet Delegated Administrator for Messaging (for Sun LDAP Schema 1), 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 the Chapter 5, Command Line Utilities, in Sun Java System Delegated Administrator 6.4 Administration Guide.

2. Remove services from the user.

   A service can be a mailbox or a calendar. For the current version of Messaging Server, the program is called msuserpurge. (See msuserpurge in Sun Java System Messaging Server 6.3 Administration Reference). For calendar services, the program is csclean. (See the Sun Java System Calendar Server 6.3 Administration Guide.)

3. 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 the Chapter 5, Command Line Utilities, in Sun Java System Delegated Administrator 6.4 Administration Guide).

2. Remove services from the users of that domain.

   A service can be a mailbox or a calendar. For Messaging Server, the program is called msuserpurge. (See msuserpurge in Sun Java System Messaging Server 6.3 Administration Reference. For calendar services, the program is csclean. (See Sun Java System Calendar Server Administration Guide.)

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

4.3 Managing Messaging Server with Sun ONE Console

The Sun ONE Administration Console is no longer supported in Messaging Server. Use the equivalent command line interfaces.

4.4 Starting and Stopping Services

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

4.4.1 To Start and Stop Services in an HA Environment

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

scswitch -n -j resource
scswitch -e -j resource

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

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

4.4.2 To Start and Stop Services in a non-HA Environment

Start and stop services from the command line using the commands msg-svr-base/sbin/start-msg and msg-svr-base/sbin/stop-msg. While it is possible to start and stop services individually using the command template: msg-svr-base/sbin/stop-msg service (where service can be smtp, imap, pop, store, http, ens, or sched) it is not recommended except in specific tasks as described in this manual. Certain services have dependencies on other services and must be started in a prescribed order. Complications can arise when trying to start services on their own. For this reason, you should start and stop all the services together using the start-msg and stop-msg commands.

You must first enable services such as POP, IMAP, and HTTP, before starting or stopping them. For more information, see 5.1.1 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 4.5 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.

To Start Up, Shut Down, or View the Status of Any Messaging Services

Again, it is not recommended to shut down individual services except in the specific tasks as described in various parts of this manual. Certain services have dependencies on other services and must be started in a prescribed order. Complications can arise when trying to start services on their own. For this reason, you should start and stop all the services together using the start-msg and stop-msg commands.

1. Use the start-msg and stop-msg commands to start or stop any of the messaging services. Examples:

   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

   The services must be enabled in order to stop or start them. See 4.4.2.1 To Specify What Services Can Be Started.

   ---

   Note –

   The start-msg and stop-msg command 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 start-msg in Sun Java System Messaging Server 6.3 Administration Reference and stop-msg in Sun Java System Messaging Server 6.3 Administration Reference.

   ---

4.4.2.1 To Specify What Services Can Be 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 configutil Parameters in Sun Java System Messaging Server 6.3 Administration Reference for details on how these work.

4.4.3 Starting and Stopping a Messaging Server Running in MTA-only Mode

To start an MTA-only system, you should also start imsched. Before you do this, remove any scheduled jobs that are not appropriate to your installations.

imschedis an individual component of Messaging Server which must be started separately if you are not starting all of Messaging Server. If you start your MTA-only system using start-msg imtaor start-msg smtp, then you will not be running the imsched process.

To run messaging server in MTA mode only (no store/imap/pop/http processes), then you can either select the MTA to be only installed/configured during the configuration of messaging server after initial install (msg_base/sbin/configure) or manually disable the message store and mshttp process using the following configutil commands:

./configutil -o local.store.enable -v 0 
./configutil -o service.http.enable -v 0

Once you have disabled http and other store processes, you can then start messaging server by running the following:

# ./start-msg
bash-3.00# ./start-msg 
Connecting to watcher ... 
Launching watcher ... 4034 
Starting ens server ... 4035 
Starting sched server ... 4036 
Starting dispatcher server .... 4038 
Starting job_controller server .... 4042

Not that all the appropriate processes are started including imsched and imta. This way the customer doesn't have to remember to start the sched process.

4.5 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 crash or become unresponsive (the services hangs). watcher monitors server crashes. msprobe monitors server hangs by checking the response time. When a server fails or stops responding to requests, it is automatically restarted. Table 4–4 shows the services monitored by each utility.

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 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) and records all server starts and stops. An example log is shown below:

watcher process 13425 started at Tue Oct 21 15:29:44 2003

Watched ’imapd’ process 13428 exited abnormally
Received request to restart:  store imap pop http
Connecting to watcher ...
Stopping http server 13440 .... done
Stopping pop server 13431 ... done
Stopping pop server 13434 ... done
Stopping pop server 13435 ... done
Stopping pop server 13433 ... done
imap server is not running
Stopping store server 13426 .... done
Starting store server .... 13457
checking store server status ...... ready
Starting imap server ..... 13459
Starting pop server ....... 13462
Starting http server ...... 13471

      

See 27.8.9 Monitoring Using msprobe and watcher Functions for more details on how to configure this feature.

msprobe is controlled by imsched. If imsched crashes, this event will be detected by watcher and trigger a restart (if autorestart is enabled). However, in the rare occurrence of imsched hanging, you will need to kill imsched with a kill imsched_pid, which will cause the watcher to restart it.

4.5.1 Automatic Restart in High Availability Deployments

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

4.6 To Schedule Automatic Tasks

Messaging Server provides a general task scheduling mechanism using a process called imsched. It is intended for scheduling Messaging Server processes. It is enabled by setting the local.schedule.taskname configutil parameter. If you modify the schedule, you must either restart the scheduler with the command stop-msg sched and start-msg sched, or you can refresh the scheduler process (refresh sched).

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

command args can be any Messaging Server command and its arguments. Paths can be relative to msg-svr-base or absolute paths. See 4.6.2 Pre-defined Automatic Tasks for relative path examples.

minute hour day-of-month month-of-year day-of-week is the schedule for running the command. It follows the UNIX crontab format.

The values are separated by a space or tab and can be 0-59, 0-23, 1-31, 1-12 or 0-6 (with 0=Sunday) respectively. Each time field can be either an asterisk (meaning all legal values), a list of comma-separated values, or a range of two values separated by a hyphen. Note that days can be specified by both day of the month and day of the week and both will be required if specified. For example, setting the 17th day of the month and Tuesday will only run the command on the 17th day of a month when it is Tuesday. See Table 20–10

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 refresh the scheduler process:

refresh sched

To disable a scheduled task, run the following:

# configutil -o local.schedule.taskname.enable -v no 
#  refresh sched

4.6.1 Scheduler Examples

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

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

Display MTA channel queue message counters every 20 minutes:

# configutil -o local.schedule.counters -v “0,20,40 * * * * /opt/SUNWmsgsr/sbin/ims
# imta qm counters > /tmp/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”

4.6.2 Pre-defined Automatic Tasks

At installation, Messaging Server creates, schedules and enables a set of pre-defined automatic tasks. These are shown below.

The following automatic tasks are set and enabled for the message store:

local.schedule.expire = "0 23 * * * sbin/imexpire"
local.schedule.expire.enable = 1
local.schedule.snapshotverify = "0 0,4,8,12,16,20 * * * sbin/imdbverify -m"
local.schedule.snapshotverify.enable = 1

The following automatic tasks are set and enabled for the MTA:

local.schedule.purge="0 0,4,8,12,16,20 * * * sbin/imsimta purge -num=5"
local.schedule.purge.enable = 1
local.schedule.return_job = "30 0 * * * lib/return_job"
local.schedule.return_job.enable = 1

The following automatic tasks are set and enabled for the message store:

local.schedule.msprobe = "5,15,25,35,45,55 * * * * lib/msprobe"
local.schedule.msprobe.enable = 1

4.7 To Configure a Greeting Message

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

To Create a New User Greeting

1. To create a new-user greeting use 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 $ represents a new line.

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

   configutil -o gen.newuserforms -v ’Subject: Welcome!! $$ Sesta.com 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.)

4.7.1 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.newuserforms 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 attribute syntax is as follows:

mailDomainWelcomeMessage;lang-user_prefLang
mailDomainWelcomeMessage;lang-domain_prefLang
mailDomainWelcomeMessage;lang-gen.sitelanguage

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 siroe.com!

Using the above examples, we assume the following:

• the domain is siroe.com

• a new user belongs to this domain

• the user’s preferred language is French as specified by the LDAP attribute preferredlanguage

• siroe.com has the above English and French welcome messages available

• the site language is en as specified by gen.sitelanguage.

For a list of supported locales and their language value tag, see the (Directory Server Reference Manual).

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.

4.7.1.1 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:

mailDomainWelcomeMessage;lang-user_prefLang
mailDomainWelcomeMessage;lang-domain_prefLang
mailDomainWelcomeMessage;lang-gen.sitelanguage
mailDomainWelcomeMessage
gen.newuserforms;lang-"$user-prefLang"
gen.newuserforms;lang-"$domain-prefLang"
gen.newuserforms;lang-"$gen.sitelanguage"
gen.newuserforms

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 untagged 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 siroe.com. 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 siroe.com):

mailDomainWelcomeMessage;lang-fr
mailDomainWelcomeMessage;lang-ja
gen.newuserforms;lang-de
gen.newuserforms;lang-en
gen.newuserforms

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

4.8 To Set a User-Preferred Language

Administrators can set a preferred language for the GUI and server-generated messages 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).

4.8.1 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 mexico.siroe.com. Administrators can set a domain preferred language by setting the attribute preferredLanguage in the domain’s LDAP entry.

To Specify a 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.

1. Command Line: Specify a site language as follows:

   configutil -o gen.sitelanguage -v value

   where value is one of the local supported languages. See Chapter 5 of Sun Java System Directory Server 5 2005Q1 Administration Guide for a list of supported locales and the language value tag.

4.9 To Customize Directory Lookups

Messaging Server cannot function without an LDAP-based directory system such as the Sun Java System Directory Server. Messaging Server requires directory access for a number of purposes. For example:

• When you create or update account information for mail users or mail groups, the information is stored in a directory called the user directory.

• When routing messages and delivering mail to mailboxes, Messaging Server looks up information about the sender or recipients in the user directory.

• When authenticating a user for mail routing lookups.

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.

To Modify the Messaging Server LDAP User-lookup Settings

1. The commands for the user-directory connection settings are shown below, but first set the LDAP and PAB password as follows:

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

   • 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 specify whether to use Messaging Server specific directory settings:

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

   Host name is 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. To specify the LDAP host name for user lookup:

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

   Port number is 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). To specify the LDAP port number for user lookup:

   configutil -o local.ugldapport -v number

   The Base DN: is 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. To specify the LDAP base DN for user lookup:

   configutil -o local.ugldapbasedn -v basedn

   Bind DN: is 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. To specify the LDAP bind DN for user lookup:

   configutil -o local.ugldapbinddn -v binddn

4.10 Encryption Settings

This is described in 23.5.2 To Enable SSL and Selecting Ciphers, which also contains background information on all security and access-control topics for Messaging Server.

4.11 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:

To Set a Failover LDAP Server

1. Set local.ugldaphost to the multiple LDAP machines. Example:

   configutil -o local.ugldaphost -v "server1 server2 ..."

2. 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:

   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.

4.12 Email Security Concerns

By default, Messaging Server enables four private commands called XADR, which returns information about how an address is routed internally by the MTA as well as general channel information, XCIR, which returns MTA circuit check information, XGEN, which returns status information about whether a compiled configuration and compiled character set are in use, and XSTA, which returns status information about the number of messages processed and currently in the MTA channel queues. Releasing such information may constitute a breach of security for some sites.

Sites may wish to disable these commands for the tcp_local channel by by adding the following lines to the file tcp_local_options, creating it if necessary.

DISABLE_ADDRESS=1
DISABLE_CIRCUIT=1
DISABLE_STATUS=1
DISABLE_GENERAL=1
.