Sun Java logo     Previous      Contents      Index      Next     

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

Chapter 18
Managing the Message Store

This chapter describes the message store and its administration interface. This chapter contains the following sections:


The message store contains the user mailboxes for a particular Messaging Server instance. The size of the message store increases as the number of mailboxes, folders, and log files increase. You can control the size of the store by specifying limits on the size of mailboxes (disk quotas), by specifying limits on the total number of messages allowed, and by setting aging policies for messages in the store.

As you add more users to your system, your disk storage requirements increase. Depending on the number of users your server supports, the message store might require one physical disk or multiple physical disks. There are two ways to integrate this additional disk space into your system. The easiest way is to add additional message store partitions (see Configuring Message Store Partitions).

Likewise, if you are supporting multiple hosted domains, you might want to dedicate a server instance to a single, large domain. With this configuration, you can designate a store administrator for a particular domain. You can also expand the message store by adding more partitions.

To manage the message store, Messaging Server provides a set of command-line utilities in addition to the Sun Java System Console interface. Table # describes these command-line utilities. For information about using these utilities, see Performing Message Store Maintenance Procedures and the Messaging Server Reference Manual.

Table 18-1  Message Store Command-line Utilities




Sets and modifies configuration parameters for the store.


Delivers mail directly to the message store accessible by IMAP or POP mail clients.


Identifies the directory that contains the message store for a particular user.


Monitors user access of the message store.


Automatically removes messages from the message store based on administrator-specified criteria like age.


Reinitializes the quota limit from the LDAP directory and recalculates the disk space being used.


Handles the saving and recovering of user mailboxes.


Backs up stored messages.


Exports Certificate Management System mailboxes into UNIX /var/mail format folders.


Restores messages that have been backed up.


The IMAP server protocol scripting tool. Executes a command or sequence of commands.


Lists, creates, deletes, renames, or moves mailboxes; reports quota usage.


Creates and synchronizes the backup directory with the information in the message store.


Moves a user’s account from one messaging server to another.


Calculates the total mailbox size for each user in the message store and compares the size with their assigned quota. Localized versions of imquotacheck notification incorrectly convert the % and the $ signs. To correct the encoding, replace every $ with \24 and replace every % with \25 in the message file.


Collects readership information on shared IMAP folders.


Reconstructs mailboxes that have been damaged or corrupted.


Performs background and daily tasks, expunges, and erases messages stored on disk.

Message Store Directory Layout

Figure 18-1 shows the message store directory layout for a server instance. The message store is designed to provide fast access to mailbox contents. The store directories are described in Table #.

Figure 18-1  Message Store Directory Layout

Graphic shows Message Store Directory Layout.

The message store consists of a number of mailbox databases and the user mailboxes. The mailbox databases consists of information about users, mailboxes, partitions, quotas and other message store related data. The user mailboxes contain the user’s messages and folders. Mailboxes are stored in a message store partition, an area on a disk partition specifically devoted to storing the message store. See Configuring Message Store Partitions for details. Message store partitions are not the same as disk partitions, though for ease of maintenance, we recommend having one disk partition for each message store partition.

Mailboxes such as INBOX are located in the store_root. For example, a sample directory path might be:


The table below describe the message store directory.

Table 18-2  Message Store Directory Description




Default: /opt/SUNWmsgsr

The directory on the Messaging Server machine that holds the server program, configuration, maintenance, and information files.



Top-level directory of the message store. Contains the mboxlist, user, and partition subdirectories.


Contains the automatic message removal rules (expire rules). This optional file can be at different locations. See To Set the Automatic Message Removal (Expire and Purge) Feature.


Message store database backup snapshots.


Contains mailbox database, database (Berkeley DB) that stores information about the mailboxes and quota information.

folder.db contains information about mailboxes, including the name of the partition where the mailbox is stored, the ACL, and a copy of some of the information in store.idx. There is one entry in folder.db per mailbox

quota.db contains information about quotas and quota usage. There is one entry in quota.db per user.

lright.db - an index for the folders by acl lookup rights.

peruser.db contains information about per-user flags. The flags indicate whether a particular user has seen or deleted a message.

subscr.db contains information about user subscriptions.


Contains active message store process information.


Not used.


Contains the message store partitions. A default primary partition is created. Place any other partitions you define in this directory.


Contains all the user mailboxes in the subdirectory of the partition. The mailboxes are stored in a hash structure for fast searching. To find the directory that contains a particular user’s mailbox, use the hashdir utility.


The top-level mail folder for the user whose ID is userid. This is the user’s INBOX. For the default domain, userid is uid. For hosted domains, userid is uid@domain. Incoming messages are delivered to this mail folder.


A user-defined folder on the messaging server.


An index that provides the following information about mail stored in the /userid/ directory: number of messages, disk quota used by this mailbox, the time the mailbox was last appended, message flags, variable-length information for each message including the headers and the MIME structure, and the size of each message. The index also includes a backup copy of mboxlist information for each user and a backup copy of quota information for each user.


Contains a list of users who have accessed the folder. For each user listed, contains information about the last time the user accessed the folder, the list of messages the user has seen, and the list of messages the user has deleted.


Contains information about user subscriptions.


Contains a list of message files that have been expunged, but not removed from disk. This file appears only if there are expunged messages.


nn is a hash directory that contains messages in the format message_id.msg; nn can be a number from 00 to 99. message_id is also a number. Example: messages 1 through 99 are stored in the .../00 directory. The first message is 1.msg, the second is 2.msg, thrid 3.msg, and so on. Messages 100 through 199 are stored in the 01 directory; messages 9990 through 9999 are stored in the 99 directory; messages 10000 through 10099 are in the 00 directory, and so on.

How the Message Store Removes Messages

Messages are removed from the message store in three stages:

  1. Delete. A client sets a message flag to delete. At this point, the message is marked for removal, but client can still restore the message by removing the delete flag. If there is a second client, the deleted flag may not be recognized immediately by that second client. You can set the configutil parameter local.imap.immediateflagupdate to enable immediate flag update.
  2. Expunge. Messages are removed from the mailbox. Technically, they are removed from the message store index file, store.idx. The message itself is still on disk, but once messages are expunged, clients can no longer restore them.
  3. Expire is a special case of expunge. Messages that conform to a set of administrator-defined removal criteria such as message size, age and so forth, are expunged. See To Set the Automatic Message Removal (Expire and Purge) Feature

  4. Purge. The stored utility purges from the disk any messages that have been expunged at 11PM everyday by default. This can be configured with local.schedule.purge, which controls the message purge schedule, and store.cleanup, which controls the purge grace period (period of time before which the message will not be purged).

Specifying Administrator Access to the Store

Message store administrators can view and monitor user mailboxes and specify access control for the message store. Store administrators have proxy authentication privileges to any service (POP, IMAP, HTTP, or SMTP), which means they can authenticate to any service using the privileges of any user. These privileges allow store administrators to run certain utilities for managing the store. For example, using MoveUser, store administrators can move user accounts and mailboxes from one system to another.

This section discusses how to grant store privileges to the message store for your Messaging Server installation.


Other users might also have administrator privileges to the store. For example, some administrators may have these privileges.

You can perform administrator tasks as described in the following subsections:

To Add an Administrator

Console     To add an administrator entry at the Console:

  1. From Console, open the Messaging Server you want to configure.
  2. Click the Configuration tab and select Message Store in the left pane.
  3. Click the Administrator tab.
  1. Click the Add button beside the Administrator UID window.
  2. In the Administrator UID field, type the user ID of the administrator you want to add.
  1. Click OK to add the administrator ID to the list displayed in the Administrator tab.
  2. Click Save in the Administrator tab to save the newly modified Administrator list.

Command Line     To add an administrator entry at the command line:

configutil -o store.admins -v "adminlist"

where adminlist is a space-separated list of administrator IDs. If you specify more than one administrator, you must enclose the list in quotes. In addition, the administrator must be a member of the Service Administrator Group (in the LDAP user entry: memberOf: cn=Service Administrators,ou=Groups,o=usergroup).

To Modify an Administrator Entry

Console     To modify an existing entry in the message store Administrator UID list at the Console:

  1. Click the Administrator tab.
  2. Click the Edit button beside the Administrator UID window.
  3. Enter your changes to the Administrator UID field.
  4. Click OK to submit your changes and dismiss the Edit Administrator window.
  5. Click Save in the Administrator tab to submit and preserve the modified Administrator list.

Command Line     To modify an existing entry in the message store Administrator UID list at the command line:

configutil -o store.admins -v "adminlist"

To Delete an Administrator Entry

Console     To delete an entry from the message store Administrator UID list by using the Console:

  1. Click the Administrator tab.
  2. Select an item in the Administrator UID list.
  3. Click Delete to delete the item.
  4. Click Save to submit and preserve your changes to the Administrator list.

Command Line     To delete store administrators at the command line, you can edit the administrator list as follows:

configutil -o store.admins -v "adminlist"

About Shared Folders

A shared folder is a folder that can be accessed and read by a group of users. In other words, access rights to shared folders are granted to multiple users. For example, a user can create a folder called golf and allow others to view the contents of that folder.

By default, Messaging Server creates a folder called Shared Folders/Users in all email accounts. Users create and access shared folders in this folder. An example of how shared folders would appear in a client is shown in Figure 18-2. This example will be described further in To Set Up Distributed Shared Folders.

Figure 18-2  Example of Ed’s Client Shared Mail Folder List

Graphic shows example of Client Shared Mail Folder List.

Users can create private shared folders and provide access rights to those folders with their email client, if that client supports shared folders. These shared folders will appear in the Shared Folders of other users who are given access rights.

Shared folders are useful for starting, sharing, and archiving an ongoing conversation on a particular topic. For example, a group of software developers can create a shared folder for discussing development of a particular project. When a message is sent to the shared folder, everyone who is subscribed to the shared folder (subscribers can be added by individual address or by a group address) can open this mailbox and read the message.

There are two kinds of shared folders:

Normally shared folders are only available to users on a particular message store. Messaging Server, however, allows you to create special shared folders that can be accessed across multiple message stores. These are called distributed shared folders. See To Set Up Distributed Shared Folders for details.

Shared Folder Access Rights

Access rights are maintained in Access Control Lists (ACLs) stored in folder.db. Granting access rights is done by setting an ACL using either the IMAP SETACL command, the -s option with the readership command line utility (see To Change a Public Folder’s Access Control Rights), or using the Messenger Express interface.

ACL Identifiers

Each ACL entry has an identifier which specifies the user or group of users for which the entry applies. Identifiers starting with a dash (“-”) represent negative rights (those denied to the user or group).

anyone is a special identifier. The access rights for anyone apply to all users. Similarly, the access rights for anyone@domain apply to all users in the same domain.

Group identifiers start with group=.

ACL Rights Characters

Each ACL entry has a set of rights represented by a string of characters. The string of characters is defined by RFC 2086. To calculate the set of rights for a user, the server adds all the rights granted to this user and all of the groups this user belongs to, then it subtracts all of the rights denied the user and the groups this user belongs to.

The table that follows lists the characters recognized by Messaging Server and gives their names, a brief description of each, and shows the IMAP commands users with this permission are allowed to issue.

Table 18-3  ACL Rights Characters




lookup – User can see and subscribe to the shared folder. (IMAP commands allowed: LIST and LSUB)


read – Users can read the shared folder. (IMAP commands allowed: SELECT, CHECK, FETCH, PARTIAL, SEARCH, COPY from the folder)


seen – Directs the system to keep seen information across sessions. (Set IMAP STORE SEEN flag)


write – Users can mark as read, and delete messages. (Set IMAP STORE flags, other than SEEN and DELETED)


insert – Users can copy and move email from one folder to another. (IMAP commands allowed: APPEND, COPY into folder)


post – Users can send mail to the shared folder email address. (No IMAP command needed)


create – Users can create new sub-folders. (IMAP command allowed: CREATE)


delete – Users can delete entries from the shared folder. (IMAP commands allowed: EXPUNGE, set STORE DELETED flag)


administer – Users have administrative privileges. (IMAP command allowed: SETACL)

Group ACL

The identifier of an ACL entry can specify a group name. The access rights of this entry apply to all of the members of this group. The server determines group memberships by the aclGroupAddr attribute of the inetMailUser object class. A group is represented by a dynamic mailing list with a filter on the aclGroupAddr attribute. The following example shows an LDIF record that defines a group, including the aclGroupAddr attribute:

dn: cn=lee-staff,ou=Groups,

cn: lee-staff


inetMailGroupStatus: active


description: Dynamic Group of Lee’s staff

objectClass: top

objectClass: groupofuniquenames

objectClass: inetmailgroup

objectClass: inetmailgroupmanagement

objectClass: inetlocalmailrecipient

objectClass: groupofurls


memberURL: ldap:///


It is not necessary for a group to be created for the group email address to be used in the folder’s ACL. In practice, it makes sense to create such a dynamic group and set the aclGroupAddr attribute on user entries when adding members to the group. Once such a group is created, static external members can be added by using their email addresses in the attribute mgrpRfc822MailMember. Members should not be added using the uniqueMember attribute, nor by creating additional values of the memberURL attribute. Doing so would cause a disconnect between what the MTA sees as a member of the mailing list and what the IMAP server sees as a group member.

When a user logs in to an IMAP server or logs in with an HTTP access service client such as Messenger Express, the server fetches the aclGroupAddr attribute (along with other message store related attributes) and caches the group names in memory. The server uses this information to determine the user’s access rights whenever the client issues a command (such as LIST or SELECT) that requires access right verification.

Shared Folder Tasks

This section describes the shared folder administrator tasks:

To Create a Public Folder

Because public folders require access to the LDAP database as well as the readership command, they must be created by system administrators.

  1. Add an LDAP user entry that will act as a container for all public folders, for example, one called public:

    dn: cn=public,ou=people,,o=ISP

    objectClass: person

    objectClass: organizationalPerson

    objectClass: inetOrgPerson

    objectClass: inetUser

    objectClass: ipUser

    objectClass: inetMailUser

    objectClass: inetLocalMailRecipient

    objectClass: nsManagedPerson

    objectClass: userPresenceProfile

    cn: public


    mailDeliveryOption: mailbox


    uid: public

    inetUserStatus: active

    mailUserStatus: active

    mailQuota: -1

    mailMsgQuota: 100

  2. Create folders within the public account by using the mboxutil command line utility. For example:
  3. mboxutil -c user/public/golftournament

  4. Using the readership command line utility, set the appropriate ACL for this folder.
  5. In order to make this folder public, it must be assigned a group of users that can access it. This is done by setting an ACL using the readership command. For instructions on how to set the ACL, see To Change a Public Folder’s Access Control Rights that follows.

To Change a Public Folder’s Access Control Rights

From time to time you might need to change the access control for a public folder, or you will need to set the access control for a public folder you have newly created.

To do this, use the readership command line utility. The command has the following form:

readership -s foldername identifier rights_chars

where foldername is the name of the public folder for which you are setting rights, userid is the person or group to whom you are assigning the rights, and rights_chars are the rights you are assigning (these are RFC 2086 compliant access rights characters). For the meaning of each character, see ACL Rights Characters. You can also change the access control for a public folder using the Messenger Express interface.


For example, if you wish everyone at the sesta domain to have lookup, read and email marking (but not posting) access to the public folder, golftournament, issue the command as follows:.

readership -s User/public/golftournament anyone@sesta lwr

To assign lookup, read, email marking and posting rights to a group, issue the command as follows:

readership -s User/public/golftournament group=golfinterest lwrp

If you want to assign administrator and posting rights for this folder to an individual, jdoe, issue the command as follows:

readership -s User/public/golftournament jdoe lwrpa

To deny an individual or group access to a public folder, prefix the userid with a dash. For example, to deny lookup, read and write rights to jsmith, issue the command as follows:

readership -s User/public/golftournament -jsmith lwr

To Enable or Disable Listing of Shared Folders

The server will or will not return shared folders when responding to a LIST command depending on the setting in the configuration option Setting the option to off disables it. The setting is enabled by default (set to on).

SELECT and LSUB commands are not affected by this option. The LSUB command returns every subscribed folder, including shared folders. Users can SELECT the shared folders they own or are subscribed to.

To Set Up Distributed Shared Folders

Normally shared folders are only available to users on a particular message store. Messaging Server, however, allows you to create distributed shared folders that can be accessed across multiple message stores. That is, access rights to distributed shared folders can be granted to any users within the group of message stores. Note, however, that web mail clients (HTTP access clients like Messenger Express) do not support remote shared folders access. Users can list and subscribe to the folders, but they can’t view or alter the contents.

Distributed shared folders require the following:

The remote message stores (that is the message stores that do not hold the shared folder) must be configured as proxy servers by setting the configuration variables listed in Table 18-4.

Table 18-4  Variables for Configuring Distributed Shared Folders



Data Format


message store server list

space-separated strings


default store admin login name



default store admin password



store admin login name for a specific host



store admin password for a specific host


Setting Up Distributed Shared Folders—Example

Figure 18-3 shows a disturbed folder example of three message store servers called StoreServer1, StoreServer2, and StoreServer3.

Figure 18-3  Distributed Shared Folders—Example

Graphic shows example of distributed shared folders.

These servers are connected to each other as peer proxy message stores by setting the variables shown in Table 18-4. Each server has a private shared folder—golf (owned by Han), tennis (owned by Kat), and hurling (owned by Luke). In addition there are two public shared folders called press_releases and Announcements. Users on any of the three servers can access any of these three shared folders. Figure 18-2 shows Ed’s shared folder list. Below is an example of the ACLs for each server in this configuration.

$ StoreServer1 :> readership -l
Ed: user/Han/golf
Ian: user/Han/golf
anyone: user/public/press_releases

$ StoreServer2 :> readership -l
Jan: user/Kat/tennis
Ann: user/Kat/tennis
anyone: user/public+Announcements user/public+press_releases

$ StoreServer3 :> readership -l
Tuck: user/Ian/hurling
Ed: user/Ian/hurling
Jac: user/Ian/hurling
anyone: user/public/Announcements

To Monitor and Maintain Shared Folder Data

The readership command line utility allows you to monitor and maintain shared folder data which is held in the folder.db, peruser.db, and lright.db files. folder.db has a record for each folder that holds a copy of the ACLs.The peruser.db has an entry per user and mailbox that lists the various flags settings and the last date the user accessed any folders. The lright.db has a list of all the users and the shared folders for which they have lookup rights.

The readership command line utility takes the following options:

Table 18-5  readership Options



-d days

Returns a report, per shared folder, of the number of users who have selected the folder within the specified days.

-p months

Removes data from the peruser.db for those users who have not selected their shared folders within the specified months.


List the data in lright.db.

-s folder_identifier_rights

Set access rights for the specified folder. This updates the lright.db as well as the folder.db.

Using the various options, you can perform the following functions:

To Monitor Shared Folder Usage

To find out how many users are actively accessing shared folders, issue the command:

readership -d days

where days is the number of days to check. Note that this option returns the number of active users, not a list of the active users.

Example: To find out the number of users who have selected shared folders within the last 30 days, issue the following command:

readership -d 30

To List Users and Their Shared Folders

To list users and the shared folders to which they have access, issue the command:

readership -l

Example output:

$ readership -l user/user2/lee-staff
richb: user/golf user/user10/Drafts user/user2/lee-staff user/user10/Trash
han1: user/ user/golf
gregk: user/ user/heaving user/tennis

To Remove Inactive Users

If you want to remove inactive users (those who have not accessed shared folders in a specified time period) issue the command:

readership -p months

where months is the number of months to check for.

Example: Remove users who have not accessed shared folders for the past six months:

readership -p 6

To Set Access Rights

You can assign access rights to a new public folder, or change access rights on a current public folder.

For an example of how to set access rights with this command, see To Change a Public Folder’s Access Control Rights.

About Message Store Quotas

A message store quota is a way of setting a limit or quota for how much disk space or how many messages can be used by users or domains. This section contains information about the following:

For further information, see To Monitor Quota Limits

User Quotas

You can specify user quotas by disk space or by number of messages. Disk space quotas specify, in bytes, the amount of disk space for each user. Disk quotas apply to the total size of all the user’s messages, regardless of how many mail folders the user has or the total number of user messages. Message quotas allow you to limit the number of messages stored in a user’s mailbox.

Quota information is stored in user LDAP attributes (Table 18-6) and configutil variables (Table 18-7). In addition to setting the quota itself, Messaging Server allows you to control the following features:

Domain Quotas

As for users, quotas can also be set for domains by either number of bytes or number of messages. This quota is for all the cumulative bytes or messages of all the users in a particular domain.

Exceptions for Telephony Application Servers

To support unified messaging requirements, Messaging Server provides the ability to override quota limitations imposed by the message store. This guarantees the delivery of messages that have been accepted by certain agents, namely telephony application servers (TAS). Messages accepted by a TAS can be routed through a special MTA channel that ensures the message is delivered to the store regardless of quota limits. For more information about configuring the TAS channel, see Chapter 12, "Configuring Channel Definitions".

Table 18-6  Message Store Quota Attributes (See Sun Java System Communcations Services Schema Reference Manual for latest and complete information.)




Bytes of disk space allowed for the user’s mailbox. Special values:
 0 - No space allowed for user’s mailbox.
-1 - No limit on space usage allowed.
-2 - Use system default quota. (configutil parameter store.defaultmailboxquota)


Maximum number of messages permitted for a user. This is a cumulative count for all folders in the store. Special values:
 0 - No message allowed for user’s mailbox.
-1 - No limit on number of messages allowed.
-2 - Use system default quota. (configutil parameter store.defaultmessage.quota.)


Status of the mail user. Can be one of the following values:

active - mail is processed as normal. Default is active.

inactive - user’s mail account is inactive. A transient failure is returned.

deleted - Account marked deleted and ready for purge. Permanent failure returned. Access to mailbox blocked.

hold - Mail sent to the hold queue and access to the mailbox is disallowed

overquota - The MTA will not deliver mail to a mailbox with this status.


Bytes of disk space allowed for the cumulative count of all the mailboxes in a domain. A value of -1 means no limit on space usage. (Default) To enforce the domain disk quota run the command:     imquotacheck -f -d domain


Maximum number of messages permitted for a domain, that is, the total count for all mailboxes in the store. A value of -1 means no limit. (Default). To enforce the domain message quota run the command:     imquotacheck -f -d domain


Status of the mail domain. Values and default are the same as mailUserStatus.

Table 18-7  Message Store configutil parameters (See Sun Java System Messaging Server Administration Reference for latest and complete information.)




Enable quota enforcement Default: On


Enable quota notification. Default: On


Store default quota by number of bytes. Default: -1 (unlimited)


Store default quota by number of messages. Numeric. Default: -1 (unlimited)


Quota warning message. If none, notification is not sent. Default: None.


Interval, in days, for sending overquota notification. Default: 7


Time, in hours, a mailbox has been overquota before messages to the mailbox will bounce back to the sender. Number of hours. Default: 120


Quota warning threshold. Percentage of quota exceeded before clients are sent an over quota warning. Default: 90

When ON, allow delivery of message that puts disk usage over quota. At that time, messages are deferred or bounced, the quota warning message is sent, and the quota grace period timer starts. (The default is that the quota warning messages are sent when the message store reaches the threshold.) Default: Off

Enable quota enforcement before messages are enqueued in the MTA. This prevents the MTA queues from filling up. Default: off

Configuring Message Store Quotas

This section describes the following tasks:

To Specify a Default User Quota

To set a default quota that applies to users who do not have individual quotas set, perform the following steps:

Console     To specify a default user quota at the Console:

  1. Click the Configuration tab and select Message Store in the left pane.
  2. Click the Quota tab.
  3. To specify a default user disk quota for the “Default user disk quota” field, select one of the following options:
  4. Unlimited. Select this option if you do not want to set a default disk quota.

    Size specification. Select this option if you want to restrict the default user disk quota to a specific size. In the field beside the button, type a number, and from the drop-down list, choose Mbytes or Mbytes.

  5. To specify a message number quota, in the “Default user message quota” box, type a number.
  6. Click Save.
  7. Set the Mbytes attribute to -1 in the user entries that use the default message store quota. See Table 18-6.

Command Line     To specify a default user quota at the command line:

To specify a default user disk quota for total message size:

configutil -o store.defaultmailboxquota -v [ -1 | number ]

where -1 indicates no quota and number indicates a number of bytes.

To specify a default user quota for total number of messages:

configutil -o store.defaultmessagequota -v [ -1 | number ]

where -1 indicates no quota and number indicates the number of messages.

Set the mailQuota attribute to -1 in the user entries that use the default message store quota. See Table 18-6.

To Specify Individual User Quotas

Each user can have individualized quotas. To set user-specific quotas, set the mailQuota or mailmsgquota attributes in the user’s LDAP entry. (See Table 18-6.) To enforce the quota, set the configutil store.quotaenforcement to on.

To Specify Domain Quotas

You can set disk space quotas or message quotas for particular domains. These quotas are for the cumulative bytes or messages of all users in a particular domain. To set domain quotas, set the mailDomainDiskQuota or mailDomainMsgQuota attributes in the user’s LDAP entry (see Table 18-6) and run imquotacheck -f.

To Deploy Quota Notification

Quota notification is the process of sending users a warning message when they are getting close to their quota. Using this feature requires three procedures:

Enabling Quota Notification

Console     To enable quota notification at the Console:

  1. Click the Quota tab.
  2. Check the “Enable quota notification” box. To disable quota notification, uncheck this box.
  3. Define the quota warning messages. See Defining a Quota Warning Message.
  4. Click Save.

Command Line     To enable or disable quota notification at the command line:

configutil -o store.quotanotification -v [ yes | no ]
configutil -o store.quotaexceededmsg -v

If the message is not set, no quota warning message is sent to the user. See the next section for an example of quota warning message format.

Defining a Quota Warning Message

Define the message that will be sent to users who are close to exceeding their disk quota as follows. Messages are sent to the user’s mailbox.

Console     To define a quota warning message at the Console:

  1. Click the Quota tab.
  2. From the drop-down list, choose the language you want to use.
  3. Type the message you want to send in the message text field below the drop-down list.
  4. Click Save.

Command Line     To define a quota warning message at the command line:

configutil -o store.quotaexceededmsg -v message

The message must be in RFC 822 format. It must contain a header with at least a subject line, follow by $$, then the message body. ’$’ represents a new line. Example:

configutil -o store.quotaexceededmsg -v ‘Subject: WARNING: User quota exceeded$$User quota threshold exceeded - reduce space used.’

To define how often the warning message is sent:

configutil -o store.quotaexceededmsginterval -v number

where number indicates a number of days. For example, 3 would mean the message is sent every 3 days.

Specifying a Quota Threshold

A quota threshold is a percentage of a quota that is exceeded before clients are sent a warning. When a user’s disk usage exceeds the specified threshold, the server sends a warning message to the user.

For IMAP users whose clients support the IMAP ALERT mechanism, the message is displayed on the user’s screen each time the user selects a mailbox and a message is also written to the IMAP log.

Console     To specify a quota threshold at the Console:

  1. Click the Quota tab.
  2. In the “Quota warning threshold” field, enter a number for the warning threshold.
  3. This number represents a percentage of the allowed quota. For example, if you specify 90%, the user is warned after using 90% of the allowed disk quota. The default is 90%. To turn off this feature, enter 100%.

  4. Click Save.

Command Line     To specify a quota threshold at the command line:

configutil -o store.quotawarn -v number

where number indicates a percentage of the allowed quota.

To Enable Quota Enforcement

By default, users or domains can exceed their quotas with no effect except for receiving an over quota notication (if set). Quota enforcement locks the mailboxes from receiving further messages until the disk usage is reduced below the quota level.

Enabling Quota Enforcement at the User Level

Console     To enable quota enforcement at the Console:

  1. Click the Quota tab.
  2. Check the “Enable quota enforcement” box. To disable quota enforcement, uncheck this box.
  3. Click Save.

Command Line     To enable or disable quota enforcement:

configutil -o store.quotaenforcement -v [ on | off]

Note that messages are added to the MTA queues until the grace period expires and all messages are sent back to the senders, or the disk usage falls below the quota and messages can be dequeued from the MTA and delivered to the message store. If you want to return messages taht are over qutoa before they get to the message queues, use the following command line:

configutil -o store.overquotastatus on

To reject the message that will push the message store over its quota:

configutil -o -v off

Setting the value to on will accept the message that pushes the message store over its quota. The default is off.

Enabling Quota Enforcement at the Domain Level

To enforce quotas for a particular domain, use the command:

imquotacheck -f -d domain

To enable for all domains exclude the -d option. When a domain exceeds its quota, the maildomainstatus attribute is set to overquota, which halts all delivery to this domain. If a domain is not overquota, the value is set to active.

To Set a Grace Period

The grace period specifies how long the mailbox can be over the quota (disk space or number of messages) before messages are bounced back to sender. Messages are accepted by the MTA, but remain in the MTA queue and are not delivered to the message store until one of the following occurs:

For example, if your grace period is set for two days, and you exceed quota for one day, new messages continue to be received and held in the message queue, and delivery attempts continue. After the second day, the messages bounce back to the sender.


The grace period is not how long the message is held in the message queue, it’s how long the mailbox is over quota before all incoming messages, including those in the message queue, are bounced. The grace period starts when the user has reached the quota threshold. See Specifying a Quota Threshold and been warned.

Console     To set a grace period for how long messages are held in the queue at the Console:

  1. Click the Quota tab.
  2. In the “Over quota grace period” field, enter a number.
  3. From the drop-down list, specify Day(s) or Hour(s).
  4. Click Save.

Command Line     To specify a quota grace period at the command line:

configutil -o store.quotagraceperiod -v number

where number indicates number of hours.

To Set the Automatic Message Removal (Expire and Purge) Feature

The automatic message removal feature (also known as expire and purge) automatically removes messages from the message store based on a set of administrator-defined criteria.This feature can automatically remove old or overly large messages, seen/deleted messages, messages with certain Subject: lines and so on. This feature allows the following removal criteria:

This feature is performed by the imexpire utility, which expunges and purges messages. See How the Message Store Removes Messages for details on the message removal process.


The server removes messages without warning, so it is important to inform users about automatic message removal policies. Unexpected message removal can be a source of consternation for users and administrators.

imexpire Theory of Operation

imexpire can be invoked from the command line or scheduled to run automatically by the imsched daemon. The administrator configures the global expiration rules (that is rules for the entire message store) with either Console or the configutil command line utility. Local expire rules (rules that apply to folders or users) can be configured by creating expire rule files (store.expire) in a message store partition, user or mailbox directories.

imexpire loads all of the expire rules at start up. By default, imexpire creates one thread per partition. Each thread goes through the list of user folders under its assigned partition and loads the local expire rule files as it goes. The expire function checks each folder against the expire rules applicable to this folder and expunges messages as needed. If there is a store.exp file that exists under the mailbox directory, and there are messages that have been expunged/expired for longer than the time specified by the store.cleanupage configuration parameter, the purge function will permanently remove the message files under the message hash directories and remove the UID records from the store.exp files.

To Deploy the Automatic Message Removal Feature

Automatic message removal can be deployed by command line or by using the Console GUI. The process requires three steps:

  1. Define automatic message removal policy: Which messages will be automatically removed? What users, domains and partitions will have messages automatically removed? What size, message age, headers will define the removal criteria. See To Define Automatic Message Removal Policy.
  2. Specify theimexpire rules to implement this policy. See To Set Rules Implementing Automatic Message Removal Policy.
  3. Specify the imexpire scheduling. See To Schedule Automatic Message Removal and Logging Level.

To Define Automatic Message Removal Policy

Define your automatic message removal policy by specifying the criteria for removal. imexpire allows for removal using the following criteria:

Age of Message. Automatically remove messages older than X days. Attribute: messagedays.

Message Count. Automatically remove messages in a folder exceeding X messages. Attribute: messagecount.

Age of Oversized Message. Automatically remove messages that exceed X bytes after Y days grace period. Attributes: messagesize and messagesizedays.

Seen and Deleted Message Flag. Automatically remove messages with the Seen or Deleted flag set. These criteria can be set to “and” or “or.” If set to or, the message’s Seen/Delete flag will cause automatic deletion regardless of other criteria. If set to and, the message’s Seen/Delete flag must be set along with passing all other specified criteria. Attributes: seen and deleted.

Header Field of Message. Allows you specify a header and string as criteria for removing a message. For example, removing all messages with the header “Subject: Work from Home!”

Folder of Messages. Allows you to specify the folder on which to remove messages. Attribute: folderpattern


imexpire does not allow you to delete or preserve messages based on how long it has been since that message was read. For example, you cannot specify that messages that have not been read for 200 days will be removed.

Examples of Automatic Message Removal Policy

Example 1: Remove all messages 365 days old in a folder exceeding 1,000 messages.

Example 2: Remove messages in domain that are older than 180 days.

Example 3: Remove all messages that have been marked as deleted.

Example 4: Remove messages in that have been marked as seen, are older than 30 days, are larger than 100 kilobytes, from folders exceeding 1,000 messages, with the header X-spam.

To Set Rules Implementing Automatic Message Removal Policy

To implement the automatic message removal policy defined in the previous section, you must set the imexpire rules. Rules can be set in the following ways:

In this example, Rule 1 specifies that all messages in the trash folder will be remove after two days. Rule 2 specifies that all messages in the message store will be removed after 14 days.

Expiration Rules Guidelines

This section sets the guidelines for the store.expirerule.attribute configutil parameters and the store.expirerule file rules.

Setting imexpire Rules Textually

Automatic message removal rules can be set textually by using the configutil parameter store.expirerule.rulename.attribute or by specifying rules in a store.expirerule file.

The store.expirerule file contains one expire criteria per line. An expire criteria of the global rule configuration file (msg_svr_base/data/store/store.expirerule) has the following format:

rule_name.attribute: value

Code Example 18-1 shows a set of expiration rules in msg_svr_base/config/store.expirerule.

Rule 1 sets the global expiration policy (that is, policy that applies to all messages), as follows:

Rule 2 sets the automatic message removal policy for users at the hosted domain It limits mailbox sizes to 1 megabyte, removes messages that have been deleted, and removes messages older than 14 days.

Rule 3 sets the automatic message removal policy for messages in the inbox folder of user f.dostoevski. It removes messages with a subject line having the expression “On-line Casino.”

Code Example 18-1  Example imexpire Rules

Rule1.regexp: 1

Rule1.folderpattern: user/.*

Rule1.messagesize: 100000

Rule1.messagesizedays: 3

Rule1.deleted: or

Rule1.Subject: Viagra Now!

Rule1.Subject: XXX Porn!

Rule1.messagecount: 1000

Rule1.messagedays: 365

Rule2.regexp: 1

Rule2.folderpattern: user/.**

Rule2.exclusive: yes

Rule2.deleted: or

Rule2.messagedays: 14

Rule2.messagecount: 1000

Rule3.folderpattern: user/f.dostoevski/inbox

Rule3.Subject: *On-line Casino*

Note that this same global expiration policy could be set with configutil:

% configutil store.expirerule.rule1.regexp 1
% configutil store.expirerule.rule1.messagesizedays 3
% configutil store.expirerule.rule1.deleted or
% configutil store.expirerule.rule1.Subject Viagra Now!
% configutil store.expirerule.rule1.Subject XXX Porn!
% configutil store.expirerule.rule1.messagecount 1000
% configutil store.expirerule.rule1.messagedays 365
% configutil store.expirerule.rule1.messagesize 100000

Setting imexpire Folder Patterns

Folder patterns can be specified using POSIX regular expressions. The format must start with a user/, which represents the directory store_root/partition/*/ (Table 18-9 shows the folder pattern for various folders.)

Table 18-9  imexpire Folder Patterns

Folder Pattern



Apply rule to all messages in all folders of userid.


Apply rule to messages of userid in folder Sent:


Apply rule to entire message store.


Apply rule to the trash folder of all users.


Apply rule to folders in hosted domain


Apply rule to folders in default domain.


Apply rule to specific parition.

To Set Automatic Message Removal Rules with the Console
  1. Bring up the automatic message removal GUI as follows:
  2. Main Console > Server Group > Messaging Server (Open) >Messaging Server Console > Configuration Tab > Message Store > Expire/Purge >Add

    A very rough drawing of the GUI is shown on Figure 18-4.

    Figure 18-4  Automatic Message Removal (Expire/Purge) GUI—Rough Drawing
    Graphic shows an approximate drawing of the Automatic Message Removal GUI.

  3. Enter a name for the new rule.
  4. Enter the folders from which messages will be automatically removed.
  5. See Setting imexpire Folder Patterns above.

  6. If this rule is the exclusive rule for folders matching the specified criteria, then check the Exclusive box.
  7. If this box is checked, then this rule takes precedence over all other rules matching the specified pattern. See Table 18-8 for details on the exclusive checkbox.

  8. To create a rule based on folder size, do the following:
    • Check the Folder Size constraint checkbox. In the Message count field, specify the maximum number of messages that will be retained in a folder before the oldest messages are removed. In the Folder size field, specify the maximum folder size, in bytes, before the oldest messages are removed.
  9. To create a rule based on message age, check the Message age constraint checkbox:
  10. In the Number of days field, specify the age, in days, of how long messages should remain in the folder.

  11. To create a rule based on message size:
    • Check the Message size limit constraint checkbox. In the Message size limit field, enter the maximum size of a message allowed in the folder. In the “Grace period” field, enter the how long over-sized messages will remain in the folder before being removed.
  12. To create a rule based on whether the Seen or Deleted message flags are set:
    • Check the Message flags constraint checkbox.
    • For the Seen: field, select “and” to specify that the message must be seen and another criteria must be met before the rule is fulfilled. Select “or” to specify that the message need only be seen or another criteria be met before the rule is fulfilled.
    • For the Deleted: field, select “and” to specify that the message must be deleted and another criteria must be met before the rule is fulfilled. Select “or” to specify that the message need only be deleted or another criteria be met before the rule is fulfilled.
  13. To create a rule based on a header fields and their values:
    • Check the Header constraint checkbox.
    • Enter a comma separated list of headers and values in the following format:
    • header1: value1, header2: value2

      Example: Subject: Work at Home!,From:

      For the header Expires and Expiry-Date, the system will remove the message if their date value is older than the Message age constraint. If multiple expiration header fields are specified, the earliest expiration date will be used. (string).

  14. Click OK to add the new rule to the Automatic Message Removal list.

To Schedule Automatic Message Removal and Logging Level

Automatic message removal is activated by the imsched scheduling daemon. By default, imsched invokes imexpire at 23:00 every day, and messages are both expunged and purged. This schedule can be customized by setting the configutil parameters local.schedule.expire, local.schedule.purge, and store.cleanupage described in Table 18-10.

Expire and purge can take a long time to complete on a large message store, so you may wish to experiment and decide how often to run these processes. For example, if an expire/purge cycle takes 10 hours, you may not want the default schedule of running expire and purge once a day. Schedule expire and purge by using local.schedule.purge to specify a separate schedule for purge. If local.schedule.purge is not set, imexpire will perform purge after an expire.

Table 18-10  Expire and Purge configutil Log and Scheduling Parameters




Interval for running imexpire. Uses UNIX crontab format:
minute hour day-of-month month-of-year day-of-week

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, however, it is not typical to use them both since the number of such occurrences are very small. If they are both specified, then both will be required. For example, setting the 17th day of the month and Tuesday will require both values to be true.

Interval Examples:

1) Run imexpire at 12:30am, 8:30am, and 4:30pm:
   30 0,8,16 * * *

2) Run imexpire at weekday morning at 3:15 am:
   15 3 * * 1-5

3) Run imexpire only on Mondays:
   0 0 * * 1

Default: 0 23 * * *


Interval for running purge. Uses UNIX crontab format:
minute hour day-of-month month-of-year day-of-week.

Default: 0 0,4,8,12,16,20 * * * /opt/SUNWmsgsr/lib/purge -num=5
(Every four hours.)


Age (in hours) of expired or expunged message before purge will permanently remove it.

Default: None

Specify a log level:

1 = log summary for the entire expire session.
2 = log one message per mailbox expired.
3 = log one message per message expired.

Default: 1

imexpire Scheduling Using the Console

Bring up the automatic message removal GUI as follows:

Main Console > Server Group > Messaging Server (Open) >Messaging Server Console > Configuration Tab > Message Store > Expire/Purge

This Console page lists the expire rules on the top and the expire and purge schedule on the bottom. To schedule expire and purge, use the pull down menus in the Expire/Purge Schedule to set the month, day of month, day of week (with 0=Sunday), hours of day and minute of hours for both expire and purge.


The day value may be set by both day of the month and day of the week. Both are adhered to if both are set. If you set the 3rd day of the week (Wednesday) and the 17th day of the month, then a purge/expire will only occur on the 17th day of each month that falls on a Wednesday).

Setting imexpire Logging Levels

imexpire will log a summary to the default log file upon completion. If expire is invoked from the commmand line, the -v (verbose) and -d (debug) option can be used to instruct imexpire to log detail status/debug messages to stderr. If imexpire is invoked by imsched, the configutil parameter can be set to 1,2 or 3 for different levels of logging. Loglevel 1 is the default, it will log a summary for the entire expire session. Loglevel 2 will log one message per mailbox expired. Loglevel 3 will log one message per message expired.

Configuring Message Store Partitions

Mailboxes are stored in message store partitions, an area on a disk partition specifically devoted to storing the message store. Message store partitions are not the same as disk partitions, though for ease of maintenance, it is recommended that you have one disk partition and one file system for each message store partition. Message store partitions are directories specifically designated as a message store.

User mailboxes are stored by default in the store_root/partition/ directory (see Figure 18-1). The partition directory is a logical directory that might contain a single partition or multiple partitions. At start-up time, the partition directory contains one subpartition called the primary partition.

You can add partitions to the partition directory as necessary. For example, you might want to partition a single disk to organize your users as follows:


As disk storage requirements increase, you might want to map these partitions to different physical disk drives.

You should limit the number of mailboxes on any one disk. Distributing mailboxes across disks improves message delivery time (although it does not necessarily change the SMTP accept rate). The number of mailboxes you allocate per disk depends on the disk capacity and the amount of disk space allocated to each user. For example, you can allocate more mailboxes per disk if you allocate less disk space per user.

If your message store requires multiple disks, you can use RAID (Redundant Array of Inexpensive Disks) technology to ease management of multiple disks. With RAID technology, you can spread data across a series of disks but the disks appear as one logical volume so disk management is simplified. You might also want to use RAID technology for redundancy purposes; that is, to duplicate the store for failure recovery purposes.


To improve disk access, the message store and the message queue should reside on separate disks.

To Add a Partition

When adding a partition, you specify both an absolute physical path where the partition is stored on disk and a logical name, called the partition nickname.

The partition nickname allows you to map users to a logical partition name regardless of the physical path. When setting up user accounts and specifying the message store for a user, you can use the partition nickname. The name you enter must be an alphanumeric name and must use lowercase letters.

To create and manage the partition, the user ID used to run the server must have permission to write to the location specified in the physical path.


After adding a partition, you must stop then restart the server to refresh the configuration information.

Console     To add a partition to the store by using the Console:

  1. From Console, open the Messaging Server you want to configure.
  2. Click the Configuration tab and select Message Store in the left pane.
  3. Click the Partition tab in the right pane.
  4. Click the Add button.
  5. Enter the Partition nickname.
  6. This is the logical name for the specified partition.

  7. Enter the Partition path.
  8. This is the absolute path name for the specified partition.

  9. To specify this as the default partition, click the selection box labeled Make This the Default Partition.
  10. Click OK to submit this partition configuration entry and dismiss the window.
  11. Click Save to submit and preserve the current Partition list.

Command Line     To add a partition to the store at the command line:

configutil -o store.partition.nickname.path -v path

where nickname is the logical name of the partition and path indicates the absolute path name where the partition is stored.

To specify the path of the default primary partition:

configutil -o store.partition.primary.path -v path

To Move Mailboxes to a Different Disk Partition

By default, mailboxes are created in the primary partition. If the partition gets full, additional messages cannot be stored. There are several ways to address the problem:

If possible, we recommend adding additional disk space to a system using volume management software since this procedure is the most transparent for the user. However, you may also move mailboxes to a different partition by doing the following:

  1. Make sure user is disconnected from their mailbox during the migration process. This can be done by informing the user to log off and stay off during mailbox move, or, by setting the mailAllowedServiceAccess attribute so that POP, IMAP and HTTP services are disallowed after they are logged off. (See Sun Java System Communcations Services Schema Reference Manual.


    Setting mailAllowedServiceAccess to disallow POP, IMAP,HTTP access does not disconnect any open connections to the mailbox. You must make sure that all connections are closed prior to the moving mailboxes.

  2. Move the user mailbox with the following command:
  3. mboxutil -r user/<userid>/INBOX user/<userid>/INBOX <partition_name>


    mboxutil -r user/ofanning/INBOX user/ofanning/INBOX secondary

  4. Set the mailMessageStore attribute in the moved user’s LDAP entry to the name of the new partition.
  5. Example: mailMessageStore: secondary

  6. Inform the user that message store connection is now allowed. If applicable, change the mailAllowedServiceAccess attribute to allow POP, IMAP and HTTP services.

Performing Message Store Maintenance Procedures

This section provides information about the utilities you use to perform maintenance and recovery tasks for the message store. You should always read your postmaster mail for warnings and alerts that the server might send. You should also monitor the log files for information about how the server is performing. For more information about log files, see Chapter 20, "Logging and Log Analysis".

This section contains the following:

To Manage Mailboxes

This section describes the following utilities for managing and monitoring mailboxes: mboxutil, hashdir, readership.

The mboxutil Utility

You use the mboxutil command to perform typical maintenance tasks on mailboxes. Note that you should not to kill the mboxutil process in the middle of execution. If it is killed with SIGKILL (kill -9), it may potentially require that every server gets restarted and a recovery be done.

mboxutil tasks include the following:

You can also use the mboxutil command to view information about quotas. For more information, see To Monitor Quota Limits.

Table # lists the mboxutil commands. For detailed syntax and usage requirements, see the Messaging Server Reference Manual.

Table 18-11  mboxutil Options




Obsolete. Used to list all user quota information. Use. imquotacheck

-c mailbox

Creates the specified mailbox.

-d mailbox

Delete the specified mailbox.

-f file

Creates, deletes, or locks the mailbox or mailboxes listed in the specified data file.

-k mailbox cmd

Locks the specified mailbox at the folder level; runs the specified command; after command completes, unlocks the mailbox.


Lists all of the mailboxes on a server.

-p pattern

When used in conjunction with the -l option, lists only those mailboxes with names that match pattern. You can use POSIX regular expressions

-q domain

Obsolete. Use imquotacheck -d domain

-r oldname newname

Renames the mailbox from oldname to newname. To move a folder from one partition to another, specify the new partition with the partition option.

This option can be used to rename a user. For example, mboxutil -r user/user1/INBOX user/user2/INBOX moves all mail and mailboxes from user1 to user2, and new messages will appear in the new INBOX. (If user2 already exists, this operation will fail.)

-u user

Obsolete. Used to list user information. Use imquotacheck -u user


When used in conjunction with the -l option, shows the path and access control for a mailbox.


POSIX regular expressions can be used in the mboxutil command.

Mailbox Naming Conventions

You must specify mailbox names in the following format: user/userid/mailbox, where userid is the user that owns the mailbox and mailbox is the name of the mailbox. For hosted domains, userid is uid@domain.

For example, the following command creates the mailbox named INBOX for the user whose user ID is crowe. INBOX is the default mailbox for mail delivered to the user crowe.

mboxutil -c user/crowe/INBOX

Important: The name INBOX is reserved for each user’s default mailbox. INBOX is the only folder name that is case-insensitive. All other folder names are case-sensitive.


To list all mailboxes for all users:

mboxutil -l

To list all mailboxes and also include path and ACL information:

mboxutil -l -x

To create the default mailbox named INBOX for the user daphne:

mboxutil -c user/daphne/INBOX

To delete a mail folder named projx for the user delilah:

mboxutil -d user/delilah/projx

To delete the default mailbox named INBOX and all mail folders for the user druscilla:

mboxutil -d user/druscilla/INBOX

To rename the mail folder memos to memos-april for the user desdemona:

mboxutil -r user/desdemona/memos user/desdemona/memos-april

To lock a mail folder named legal for the user dulcinea:

mboxutil -k user/dulcinea/legal cmd

where cmd is the command you wish to run on while the folder is locked.

To move the mail account for the user dimitria to a new partition:

mboxutil -r user/dimitria/INBOX user/dimitria/INBOX partition

where partition specifies the name of the new partition.

To move the mail folder named personal for the user dimitria to a new partition:

mboxutil -r user/dimitria/personal user/dimitria/personal partition

The hashdir Utility

The mailboxes in the message store are stored in a hash structure for fast searching. Consequently, to find the directory that contains a particular user’s mailbox, use the hashdir utility.

This utility identifies the directory that contains the message store for a particular account. This utility reports the relative path to the message store, such as d1/a7/. The path is relative to the directory level just before the one based on the user ID. The utility sends the path information to the standard output.

For example, to find the relative path to the mailbox for user crowe:

hashdir crowe

The readership Utility

The readership utility reports on how many users other than the mailbox owner have read messages in a shared IMAP folder.

An owner of a IMAP folder may grant permission for others to read mail in the folder. A folder that others are allowed to access is called a shared folder. Administrators can use the readership utility to see how many users other than the owner are accessing a shared folder.

This utility scans all mailboxes and produces one line of output per shared folder, reporting the number of readers followed by a space and the name of the mailbox.

Each reader is a distinct authentication identity that has selected the shared folder within the past specified number of days. Users are not counted as reading their own personal mailboxes. Personal mailboxes are not reported unless there is at least one reader other than the folder’s owner.

For example, the following command counts as a reader any identity that has selected the shared IMAP folder within the last 15 days:

readership -d 15

To Monitor Quota Limits

Monitor quota usage and limits by using imqutoacheck, which generates a report listing defined quotas and limits, and provides information on quota usage. Quotas and usage figures are reported in kilobytes. This utility can also compare mailbox size with a user’s assigned quota. As an option, you can email a notification to users who have exceeded a set percentage of their assigned quota.

To list the usage of all users whose quota exceeds the least threshold in the rule file:


List quota information for a the domain

imquotacheck -d

To send a notification to all users in accordance to the default rule file:

imquotacheck -n

To send a notification to all users in accordance to a specified rulefile, myrulefile, and to a specified mail template file, mytemplate.file (for more information, refer to the Sun Java System Messaging Server Administration Reference):

imquotacheck -n -r myrulefile -t mytemplate.file

To list the usage of all users and (will ignore the rule file):

imquotacheck -i

To list per folder usages for users user1 (will ignore the rule file):

imquotacheck -u user1 -e

To Monitor Disk Space

You can specify how often the system should monitor disk space and under what circumstances the system should send a warning. To configure disk space monitoring and notification, you use the configutil command to set the alarm space attributes, which are described in Table #.

Table 18-12  Disk Space Alarm Attributes

Disk Space Attributes

Default Value


3600 seconds




24 hours

For example, if you want the system to monitor disk space every 600 seconds, specify the following command:

configutil -o alarm.diskavail.msgalarmstatinterval -v 600

If you want to receive a warning whenever available disk space falls below 20%, specify the following command:

configutil -o alarm.diskavail.msgalarmthreshold -v 20

For more information about setting alarm attributes, see the Messaging Server Reference Manual and Monitoring Disk Space.

Using the stored Utility

The stored utility performs the following monitoring and maintenance tasks for the server:

The stored utility automatically performs cleanup and expiration operations once a day at 11 PM. You can choose to run additional cleanup and expiration operations.

Table # lists some of the stored options. Some common usage examples follow the table. For detailed syntax and usage requirements, see the Messaging Server Reference Manual.

Table 18-13  stored Options




OBSOLETE. Use start-msg store to start up stored which will run as daemon, performing system checks and activating alarms, deadlock detection, and database repair.


Checks the status of stored. The return code of this command indicates the status.


Verbose output.

-v -v

More verbose output.

To print the status, enter:

stored -t -v

If you want to change the time of the automatic cleanup and expiration operations, use the configutil utility as follows:

configutil -o store.expirestart -v 21

Occasionally, you might need to restart the stored utility; for example, if the mailbox list database becomes corrupted. To restart stored on UNIX, use the following commands at the command line:

msg_svr_base/sbin/stop-msg store
msg_svr_base/sbin/start-msg store

If any server daemon crashes, you must stop all daemons and restart all daemons including stored.

Backing Up and Restoring the Message Store

Message store backup and restore is one of the most common and important administrative tasks. It consists of backing up all the messages and folders on a message store. You must implement a backup and restore policy for your message store to ensure that data is not lost if problems such as the following occur:

You can do message store back up and restore using command-line utilities imsbackup and imsrestore, or the integrated solution that uses Legato Networker´┐Ż.

Messaging Server provides a single-copy backup procedure. Regardless of how many user folders contain a particular message, during backup, the message file is backed up only once using the first message file found. The second message copy is backed up as a link to the name of the first message file, and so on. imsbackup maintains a hash table of all messages using the device and inode of the message files as the index. This method does have implications when restoring data, however. For more information, see Considerations for Partial Restore.

This section contains the following subsections:

Creating a Mailbox Backup Policy

Your backup policy will depend on several factors, such as:

Peak Business Loads

You need to take into account peak business loads when scheduling backups for your system as this can reduce system load during peak hours. For example, backups are probably best scheduled for early morning hours such as 2:00 AM.

Full and Incremental Backups

Incremental backups will scan the store for changed data and back up only what has changed. Full backups will back up the entire message store. You need to determine how often the system should perform full as opposed to incremental backups. You’ll probably want to perform incremental backups as a daily maintenance procedure and full backups once a week.

Parallel or Serial Backups

When user data is stored on multiple disks, you can back up user groups in parallel if you wish. Depending on system resources, parallel backups can speed up the overall backup procedure. However, you might want to use serial backups if you want to reduce backup impact on the server’s performance. Whether to use parallel or serial backups can depend on many factors, including system load, hardware configuration, how many tape drives are available, and so on.

To Create Backup Groups

A backup group is an arbitrary set of user mailboxes defined by regular expressions. By organizing user mailboxes into backup groups, you can define more flexible backup management.

For example, you could create three backup groups, the first containing user IDs starting with the letters A through L, the second with users whose user IDs begin with M-Z, and the third with users whose user IDs begin with a number. Administrators could use these backup groups to backup mailboxes in parallel, or perhaps only certain groups on one day and other groups on another.

There are several things to remember about backup groups:

  1. These are arbitrary virtual groups of mail users. They do not precisely map to the message store directory (Figure 18-1), although it may look like it.
  2. They are defined by the administrator using UNIX regular expressions.
  3. The regular expressions are defined in the configuration file
  4. When backup groups are referenced in imsbackup and imsrestore, they use the path format: /partition_name/backup_group

The format of backup-groups.conf is as follows:


Using the example described in the paragraph above, the following definitions would be used to create the three backup groups:


You can now scope imsbackup and imsrestore at several levels.You can backup/restore the whole message store using the backup command:

imsbackup -f device /

To backup all mailboxes for all users in groupA use the following:

imsbackup -f device /partition/groupA

The default partition is called primary.

Pre-defined Backup Group

Messaging Server includes one predefined backup group that is available without creating the backup-groups configuration file. This group is called user; it includes all users. For example, the following will backup all users on the primary partition:

imsbackup -f backupfile /primary/user

Messaging Server Backup and Restore Utilities

To back up and restore your data, Messaging Server provides the imsbackup and imsrestore utilities. Note that the imsbackup and imsrestore utilities do not have the advanced features found in general purpose tools like Legato Networker. For example, the utilities have only very limited support for tape auto-changers, and they cannot write a single store to multiple concurrent devices. Comprehensive backup will be achieved via plug-ins to generalized tools like Legato Networker. For more information about using Legato Networker, see To Use Legato Networker.

The imsbackup Utility

With imsbackup, you can write selected contents of the message store to any serial device, including magnetic tape, a UNIX pipe, or a plain file. The backup or selected parts of the backup may later be recovered by using the imsrestore utility. The output of imsbackup can be piped to imsrestore.

The following example backs up the entire message store to /dev/rmt/0:

imsbackup -f /dev/rmt/0 /

This backs up the mailboxes of user ID joe to /dev/rmt/0:

imsbackup -f /dev/rmt/0 /primary/user/joe

This example backs up all the mailboxes of all the users defined in the backup group groupA to backupfile (see To Create Backup Groups):

imsbackup -f- /primary/groupA > backupfile

This command uses the default blocking factor of 20. For a complete syntax description of the imsbackup command, see the Messaging Server Reference Manual.

The imsrestore Utility

To restore messages from the backup device, use the imsrestore command. For example, the following command restores messages for user1 from the file backupfile.

imsrestore -f backupfile /primary/user1

For a complete syntax description of the imsbackup command, see the Messaging Server Reference Manual.

Considerations for Partial Restore

The message store uses a single-copy message system. That is, only a single copy of any message is saved in the store as a single file. Any other instances of that message (like when a message is sent to multiple mailboxes) are stored as links to that copy. Because of this, there are implications when restoring messages. For example:

The following examples demonstrate what happens to a message used by multiple users when a partial restore is performed. Assume there are three messages, all the same, belonging to three users A, B, and C, as follows:


Example 1. In the first example, the system performs a partial backup and full restore procedure as follows:

  1. Back up mailboxes for users B and C.
  2. Delete mailboxes of users B and C.
  3. Restore the backup data from step 1.

In this example, B/INBOX/1 and C/INBOX/1 are assigned a new inode number and the message data is written to a new place on the disk. Only one message is restored; the second message is a hard link to the first message.

Example 2. In this example, the system performs a full backup and a partial restore as follows:

  1. Perform full backup.
  2. Delete mailboxes for user A.
  3. Restore mailboxes for user A.

A/INBOX/1 is assigned a new inode number.

Example 3. In this example, partial restore might require more than one attempt:

  1. Perform full backup.
  2. B/INBOX/1 and C/INBOX/1 are backed up as links to A/INBOX/1.

  3. Delete mailboxes for users A and B.
  4. Restore mailboxes for user B.
  5. The restore utilities ask the administrator to restore A/INBOX first.

  6. Restore mailboxes for users A and B.
  7. Delete mailboxes for user A (optional).


    If you want to ensure that all messages are restored for a partial restore, you can run the imsbackup command with the -i option. The -i option backs up every message multiple times if necessary.

    If the backup device is seekable (example: a drive or tape), imsrestore seeks to the position containing A/INBOX/1 and restore it as B/INBOX/1. If the backup device is non-seekable example: a UNIX pipe), imsrestore logs the object ID and the ID of the depending (linked) object to a file, and the administrator must invoke imsrestore again with the -r option to restore the missing message references.

To Use Legato Networker

Messaging Server includes a backup API that provides an interface with third-party backup tools, such as Legato Networker. The physical message store structure and data format are encapsulated within the backup API. The backup API interacts directly with the message store. It presents a logical view of the message store to the backup service. The backup service uses the conceptual representation of the message store to store and retrieve the backup objects.

Messaging Server provides an Application Specific Module (ASM) that can be invoked by the Legato Networker’s save and recover commands to back up and restore the message store data. The ASM then invokes the Messaging Server imsbackup and imsrestore utilities.


This section provides information about how to use Legato Networker with the Messaging Server message store. To understand the Legato Networker interface, see your Legato documentation.

Backing Up Data Using Legato Networker

To perform backups of the Messaging Server message store using Legato Networker, you must perform the following preparatory steps before invoking the Legato interface:

  1. Create a symbolic link from /usr/lib/nsr/imsasm to msg_srv_base/lib/msg/imsasm
  2. From Sun or Legato, obtain a copy of the nsrfile binary and copy it to the following directory:
  3. /usr/bin/nsr

    Note that this is required only if you are using an older version of Networker (5.x). With Networker 6.0 and above, nsrfile is automatically installed under /usr/bin/nsr.

  4. If you want to back up users by groups, perform the following steps:
    1. Create a backup group file as described in To Create Backup Groups.
    2. To verify your configuration, run

      Look at the directory structure created by structure should look similar to that shown in Table 18-4.

      Note that if you do not specify a backup-groups.conf file, the backup process will use the default backup group ALL for all users.

  5. In the directory /nsr/res/, create a res file for your save group to invoke the script before the backup. See Table 18-4 for an example.


    Earlier versions of Legato Networker have a limitation of 64 characters for the save set name. If the name of this directory plus the logical name of the mailbox (for example, /primary/groupA/fred) is greater than 64 characters, then you must run -p. Therefore, you should use a short path name for the -p option of For example the following command will create the backup image under the directory /backup: -p /backup

    Important: The backup directory must be writable by the message store owner (example: inetuser).

Figure 18-5 shows a sample backup groups directory structure.

Figure 18-5  Backup Group Directory Structure


The example below shows a sample res file named IMS.res in the /nsr/res directory:

type: savepnpc;
precmd: "echo mkbackupdir started",
   "/usr/siroe/server5/msg-siroe/bin/ -p /backup";
pstcmd: "echo imsbackup Completed";
timeout: "12:00 pm";

You are now ready to run the Legato Networker interface as follows:

  1. Create the Messaging Server save group if necessary.
    1. Run nwadmin.
    2. Select Customize | Group | Create.
  2. Create a backup client using savepnpc as the backup command:
    1. Set the save set to the directory created by mkbackupdir.
  3. Select Group Control | Start to test your backup configuration.

Example. Creating A Backup Client in Networker:

To create a backup client in Networker. From nwadmin, select Client | Client Setup | Create

Name: siroe
Group: IMS
Backup Command:savepnpc
Parallelism: 4


Restoring Data Using Legato Networker

To recover data, you can use the Legato Networker nwrecover interface or the recover command-line utility. The following example recovers user a1’s INBOX:

recover -a -f -s siroe /backup/siroe/groupA/a1/INBOX

The next example recovers the entire message store:

recover -a -f -s siroe /backup/siroe

To Use a Third Party Backup Software (Besides Legato)

Messaging Server provides two message store backup solutions, the command line imsbackup and the Solstice Backup (Legato Networker). A large message store running a single imbackup to backup the entire message store can take a significant amount of time. The Legato solution supports concurrent backup sessions on multiple backup devices. Concurrent backup can shorten backup time dramatically (backups of 25GB of data per hour have been achieved).

If you are using another third party concurrent backup software (for example, Netbackup), you may use the following method to integrate your backup software with the Messaging Server.

  1. Divide your users into groups (see To Create Backup Groups) and create a backup-groups.conf file under the directory msg_svr_base/config/.

  2. Note

    This backup solution requires additional disk space. To backup all the groups concurrently, the disk space requirement is 2 times the message store size. If you do not have that much disk space, divide your users into smaller groups, and then backup a set of groups at a time. For example group1 - group5, group6 - group10. Remove the group data files after backup.

  3. Run imsbackup to backup each group into files under a staging area.
  4. The command is imsbackup -f <device> /<instance>/<group>

    You can run multiple imsbackup processes simultaneously. For example:

    # imsbackup -f- /primary/groupA > /bkdata/groupA &
    # imsbackup -f- /primary/groupB > /bkdata/groupB &

    . . .

    imsbackup does not support large files, if the backup data is larger than 2 GB, you need to use the -f- option to write the data to stdout and then pipe the output to a file.

  5. Use your third party backup software to backup the group data files in the staging area (in our example that is /bkdata).
  6. To restore a user, identify the group filename of the user, restore that file from tape, and then use imsrestore to restore the user from the data file.
  7. Note that imsrestore does not support large files. If the data file is larger than 2GB. Use the following command:

    # cat /bkdata/groupA | imsrestore -f- /primary/groupA/andy

Monitoring User Access

Messaging Server provides the command, imsconnutil, which allows you to monitor user’s message store access via IMAP, POP and http. You can also determine the last log in and log out of users. This command works on a per message store basis and will not work across message stores.


Use of this function or other Messaging Server functions to monitor, read or otherwise access user’s email may constitute a potential source of liability if used in violation of applicable laws or regulations or if used in violation of the customer’s own policies or agreements.

This command requires root access by the system user (default: inetuser), and you must set the configuration variables local.imap.enableuserlist, local.http.enableuserlist, local.enablelastaccess to 1.

To list users currently logged on via IMAP or any web mail client, use the following command:

# imsconnutil -c

To list the last IMAP, POP, or Messenger Express access (log in and log out) of every user on the message store use:

# imsconnutil -a

The following command does two things: 1) it determines whether the specified user is currently logged on via IMAP or Messenger Express or any client that connects via mshttp (note that this does not work for POP because POP users generally do not stay connected), and 2) it lists the last time the users have logged on and off:

# imsconnutil -c -a -u user_ID

Note that a list of users can be input from a file, one user per line, using the following command:

# imsconnutil -c -a -f filename

You can also specify a particular service (imap or http) using the -s flag. For example, to list whether a particular user ID is logged onto IMAP or not, use the following command:

# imsconnutil -c -s imap -u user_ID

For a complete description of the imsconnutil syntax, refer to the Sun Java System Messaging Server Administration Reference.

Here is some example output:

$ ./imsconnutil -a -u soroork

UID   IMAP last access  HTTP last access  POP last access
soroork   08/Jul/2003:10:49:05  10/Jul/2003:14:55:52  ----NOT-RECORDED----

$ ./imsconnutil -c

UID  TIME   AUTH          TO           FROM
ed  17/Jun/2003:11:24:03  plain
bill  17/Jun/2003:04:28:43  plain
mia   17/Jun/2003:09:36:54  plain
jay  17/Jun/2003:05:38:46  plain
paul  17/Jun/2003:12:23:28  plaintext
tony  17/Jun/2003:05:38:46  plain
anil  17/Jun/2003:12:26:40  plaintext
anil  17/Jun/2003:12:25:17  plaintext
jack  17/Jun/2003:12:26:32  plaintext
toni  17/Jun/2003:12:25:32  plaintext

10 users were logged in to imap.
Feature is not enabled for http.

Troubleshooting the Message Store

This section provides guidelines for actively maintaining your message store. In addition, this section describes other message store recovery procedures you can use if the message store becomes corrupted or unexpectedly shuts down. Note that the section on these additional message store recovery procedures is an extension of Repairing Mailboxes and the Mailboxes Database.

Prior to reading this section, it is strongly recommended that you review this chapter as well as the command-line utility and configutil chapters in the Sun Java System Messaging Server Administration Reference. Topics covered in this section include:

Standard Message Store Monitoring Procedures

This section outlines standard monitoring procedures for the message store. These procedures are helpful for general message store checks, testing, and standard maintenance.

For additional information, see Monitoring the Message Store.

Check Hardware Space

A message store should have enough additional disk space and hardware resources. When the message store is near the maximum limit of disk space and hardware space, problems might occur within the message store.

Inadequate disk space is one of the most common causes of the mail server problems and failure. Without space to write to the message store, the mail server will fail. In addition, when the available disk space goes below a certain threshold, there will be problems related to message delivery, logging, and so forth. Disk space can be rapidly depleted when the clean up function of the stored process fails and deleted messages are not expunged from the message store.

For information on monitoring disk space, see To Monitor Disk Space and Monitoring the Message Store.

Check Log Files

Check the log files to make sure the message store processes are running as configured. Messaging Server creates a separate set of log files for each of the major protocols, or services, it supports: SMTP, IMAP, POP, and HTTP. You can look at the log files through the Console or in directory msg_svr_base/log/. You should monitor the log files on a routine basis.

Be aware that logging can impact server performance. The more verbose the logging you specify, the more disk space your log files will occupy for a given amount of time. You should define effective but realistic log rotation, expiration, and backup policies for your server. For information about defining logging policies for your server, see Chapter 20, "Logging and Log Analysis".

Check User IMAP/POP Session

Messaging Server provides a feature called telemetry that can capture a user’s entire IMAP or POP session into a file. This feature is useful for debugging client problems. For example, if a user complains that their message access client is not working as expected, this feature can be used to trace the interaction between the access client and Messaging Server.

To capture a session, simply create the following directory:


Messaging Server will create one file per session in that directory. Example output is shown below.

LOGIN redb 2003/11/26 13:03:21

>0.017>1 OK User logged in




2 OK Completed

<0.046<3 select "INBOX"

>0.236>* FLAGS (\Answered lagged raft eleted \Seen $MDNSent Junk)

* OK [PERMANENTFLAGS (\Answered lagged raft eleted \Seen $MDNSent Junk \*)]

* 1538 EXISTS


* OK [UNSEEN 23]

* OK [UIDVALIDITY 1046219200]

* OK [UIDNEXT 1968]

3 OK [READ-WRITE] Completed

<0.045<4 UID fetch 1:* (FLAGS)

>0.117>* 1 FETCH (FLAGS (\Seen) UID 330)

* 2 FETCH (FLAGS (\Seen) UID 331)

* 3 FETCH (FLAGS (\Seen) UID 332)

* 4 FETCH (FLAGS (\Seen) UID 333)

* 5 FETCH (FLAGS (\Seen) UID 334)


Check stored Processes

The stored function performs a variety of important tasks such as deadlock and transaction operations of the message database, enforcing aging policies, and expunging and erasing messages stored on disk. If stored stops running, Messaging Server will eventually run into problems. If stored doesn’t start when start-msg is run, no other processes will start.

For more information on the stored process, see Using the stored Utility and the stored utility in the Messaging Server Command-line Utilities chapter of the Messaging Server Reference Manual.

For additional information on monitoring the stored function, see Monitoring the Message Store.

Check Database Log Files

Database log files refer to sleepycat transaction checkpointing log files (in directory store_root/mboxlist). If log files accumulate, then database checkpointing is not occurring. In general, there are two or three database log files during a single period of time. If there are more files, it could be a sign of a problem.

Check User Folders

If you want to check the user folders, you might run the command
reconstruct -r -n (recursive no fix) which will review any user folder and report errors. For more information on the reconstruct command, see Repairing Mailboxes and the Mailboxes Database.

Check for Core Files

Core files only exist when processes have unexpectedly terminated. It is important to review these files, particularly when you see a problem in the message store. On Solaris, use coreadmin to configure core file location.

Message Store Startup and Recovery

Message store data consists of the messages, index data, and the message store database. While this data is fairly robust, on rare occasions there may be message store data problems in the system. These problems will be indicated in the default log file, and almost always will be fixed transparently. In rare cases an error message in the log file may indicate that you need to run the reconstruct utility. In addition, as a last resort, messages are protected by the backup and restore processes described in Backing Up and Restoring the Message Store. This section will focus on the automatic startup and recovery process of stored.

The message store automates many recovery operations which were previously the responsibility of the administrator. These operations are performed by message store daemon stored during startup and include database snapshots and automatic fast recovery as necessary. stored thoroughly checks the message store’s database and automatically initiates repairs if it detects a problem.

stored also provides a comprehensive analysis of the state of the database via status messages to the default log, reporting on repairs done to the message store and automatic attempts to bring it into operation.

Automatic Startup and Recovery—Theory of Operations

The stored daemon starts before the other message store processes. It initializes and, if necessary, recovers the message store database. The message store database keeps folder, quota, subscription, and message flag information. The database is logging and transactional, so recovery is already built in. In addition, some database information is copied redundantly in the message index area for each folder.

Although the database is fairly robust, on the rare occasions that it breaks, in most cases stored recovers and repairs it transparently. However, whenever stored is restarted, you should check the default log files to make sure that additional administrative intervention is not required. Status messages in the log file will tell you to run reconstruct if the database requires further rebuilding.

Before opening the message store database, stored analyzes its integrity and sends status messages to the default log under the category of warning. Some messages will be useful to administrators and some messages will consists of coded data to be used for internal analysis. If stored detects any problems, it will attempt to fix the database and try starting it again.

When the database is opened, stored will signal that the rest of the services may start. If the automatic fixes failed, messages in the default log will specify what actions to take. See Error Messages Signifying that reconstruct -m is Needed for details.

In previous releases, stored could start a recovery process which would take a very long time leaving the administrator wondering if stored was “stuck.” This type of long recovery has been removed and stored should determine a final state in less than a minute. However, if stored needs to employ recovery techniques such as recovering from a snapshot, the process may take a few minutes.

After most recoveries, the database will usually be up to date and nothing else will be required. However, some recoveries will require a reconstruct -m in order to synchronize redundant data in the message store. Again, this will be stated in the default log, so it is important to monitor the default log after a startup. Even though the message store will seem to be up and running normally, it is important to run any requested operations such as reconstruct.

Another reason for reading the log file is to determine what caused damage to the database in the first place. Although stored is designed to bring up the message store regardless of any problem on the system, you will still want to try to ascertain cause of the database damage as this may be a sign of a larger hidden problem.

Error Messages Signifying that reconstruct -m is Needed

This section describes the type of error messages that require reconstruct -m to be run.

When the error message indicates mailbox error, run reconstruct <mailbox>. Example:

"Invalid cache data for msg 102 in mailbox user/joe/INBOX. Needs reconstruct"

"Mailbox corrupted, missing fixed headers: user/joe/INBOX"

"Mailbox corrupted, start_offset beyond EOF: user/joe/INBOX"

When the error message indicates a database error, run reconstruct -m. Example:

"Removing extra database logs. Run reconstruct -m soon after startup to resync redundant data"

"Recovering database from snapshot. Run reconstruct -m soon after startup to resync redundant data"

Database Snapshots

A snapshot is a hot backup of the database and is used by stored to restore a broken database transparently in couple minutes. This is much quicker than using reconstruct, which relies on the redundant information stored in other areas.

Message Store Database Snapshot—Theory of Operations

Snapshots of the database, located in the mboxlist directory, are taken automatically, by default, once every 24 hours. Snapshots are copied by default into a subdirectory of the store directory. By default, there are five snapshots kept at any given time: one live database, three snapshots, and one database/removed copy. The database/removed copy is newer and is an emergency copy of the database which is thrown into a subdirectory removed of the mboxlist database directory.

If the recovery process decides to remove the current database because it is determined to be bad, stored will move it into the removed directory if it can. This allows the database to be analyzed if desired.

The data move will only happen once a week. If there is already a copy of the database there, stored will not replace it every time the store comes up. It will only replace it if the data in the removed directory is older than a week. This is to prevent the original database which had the problem of being replaced too soon by successive startups.

To Specify Message Store Database Snapshot Interval and Location

There should be five times as much space for the database and snapshots combined. It is highly recommended that the administrator reconfigure snapshots to run on a separate disk, and that it is tuned to the system’s needs.

If stored detects a problem with the database on startup, the best snapshot will automatically be recovered. Three snapshot variables can set the following parameters: the location of the snapshot file, the interval for taking snapshots, number of snapshots saved. These configutil parameters are shown in Table 18-15.

Having a snapshot interval which is too small will result in a frequent burden to the system and a greater chance that a problem in the database will be copied as a snapshot. Having a snapshot interval too large can create a situation where the database will hold the state it had back when the snapshot was taken.

A snapshot interval of a day is recommended and a week or more of snapshots can be useful if a problem remains on the system for a number of days and you wish to go back to a period prior to point at which the problem existed.

stored monitors the database and is intelligent enough to refuse the latest snapshot if it suspects the database is not perfect. It will instead retrieve the latest most reliable snapshot. Despite the fact that a snapshot may be retrieved from a day ago, the system will use more up to date redundant data and override the older snapshot data, if available.

Thus, the ultimate role the snapshot plays is to get the system as close to up-to-date and ease the burden of the rest of the system trying to rebuild the data on the fly.

Table 18-15  Message Store Database Snapshot Parameters



Location of message store database snapshot files. Either existing absolute path or path relative to the store directory.

Default: dbdata/snapshots

Minutes between snapshots. Valid values: 1 - 46080

Default: 1440 (1440 minutes = 1 day)

Number of different snapshots kept. Valid values: 2 -367

Default: 3

Repairing Mailboxes and the Mailboxes Database

If one or more mailboxes become corrupt, you can use the reconstruct utility to rebuild the mailboxes or the mailbox database, and repair any inconsistencies. See Error Messages Signifying that reconstruct -m is Needed.

The reconstruct utility rebuilds one or more mailboxes, or the master mailbox file, and repairs any inconsistencies. You can use this utility to recover from almost any form of data corruption in the mail store. Note that low-level database repair, such as completing transactions and rolling back incomplete transactions is performed by automatically on startup.

Table # lists the reconstruct options. For detailed syntax and usage requirements, see the Messaging Server Reference Manual.

Table 18-16  reconstruct Options




Remove store.exp file upon reconstruct.


Initialize store.idx file upon reconstruct.


Forces reconstruct to perform a fix on the mailbox or mailboxes.


Repairs and performs a consistency check of the mailboxes database. This option examines every mailbox it finds in the spool area, adding or removing entries from the mailbox’s database as appropriate. The utility prints a message to the standard output file whenever it adds or removes an entry from the database.


Checks the message store only, without performing a fix on the mailbox or mailboxes. The -n option cannot be used by itself unless a mailbox name is provided. When a mailbox name is not provided, the -n option must be used with the -r option. The -r option may be combined with the -p option. For example, any of the following commands are valid:

reconstruct -n user/dulcinea/INBOX

reconstruct -n -r

reconstruct -n -r -p primary

reconstruct -n -r user/dulcinea/


Checks for orphaned accounts. This option searches for inboxes in the current messaging server host which do not have corresponding entries in LDAP. For example, the -o option finds inboxes of owners who have been deleted from LDAP or moved to a different server host. For each orphaned account it finds, reconstruct writes the following command to the standard output:

mboxutil-d user/userid/INBOX

-o -d filename

If -d filename is specified with the -o option, reconstruct opens the specified file and writes the mboxutil -d commands into that file. The file may then be turned into a script file to delete the orphaned accounts.

-p partition

Specifies a partition name; do not use a full path name. If this option is not specified, reconstruct defaults to all partitions.


Fixes any inconsistencies in the quota subsystem, such as mailboxes with the wrong quota root or quota roots with the wrong quota usage reported. The -q option can be run while other server processes are running.

-r [mailbox]

Repairs and performs a consistency check of the partition area of the specified mailbox or mailboxes. The -r option also repairs all sub-mailboxes within the specified mailbox. If you specify -r with no mailbox argument, the utility repairs the spool areas of all mailboxes within the user partition directory.

To Rebuild Mailboxes

To rebuild mailboxes, use the -r option. You should use this option when:

With the 5.0 release, reconstruct -r first runs a consistency check. It reports any consistencies and rebuilds only if it detects any problems. Consequently, performance of the reconstruct utility is improved with this release.

You can use reconstruct as described in the following examples:

To rebuild the spool area for the mailboxes belonging to the user daphne, use the following command:

reconstruct -r user/daphne

To rebuild the spool area for all mailboxes listed in the mailbox database:

reconstruct -r

You must use this option with caution, however, because rebuilding the spool area for all mailboxes listed in the mailbox database can take a very long time for large message stores. (See reconstruct Performance.) A better method for failure recovery might be to use multiple disks for the store. If one disk goes down, the entire store does not. If a disk becomes corrupt, you need only rebuild a portion of the store by using the -p option as follows:

reconstruct -r -p subpartition

To rebuild mailboxes listed in the command-line argument only if they are in the primary partition:

reconstruct -p primary mbox1 mbox2 mbox3

If you do need to rebuild all mailboxes in the primary partition:

reconstruct -r -p primary

If you want to force reconstruct to rebuild a folder without performing a consistency check, use the -f option. For example, the following command forces a reconstruct of the user folder daphne:

reconstruct -f -r user/daphne

To check all mailboxes without fixing them, use the -n option as follows:

reconstruct -r -n

Checking and Repairing Mailboxes

To perform a high-level consistency check and repair of the mailboxes database:

reconstruct -m

You should use the -m option when:

To Remove Orphan Accounts

To search for orphaned accounts (orphaned accounts are mailboxes that do not have corresponding entries in LDAP) use the following command:

reconstruct -o

Command output follows:

  reconstruct: Start checking for orphaned mailboxes
  mboxutil -d user/test/annie/INBOX
  mboxutil -d user/test/oliver/INBOX
  reconstruct: Found 2 orphaned mailbox(es)
  reconstruct: Done checking for orphaned mailboxes

Use the following command to create a file listing orphaned mailboxes that can be turned into a script file that deletes the orphaned mailboxes (file is named orphans.cmd):

reconstruct -o -d orphans.cmd

The command output is as follows:

  reconstruct: Start checking for orphaned mailboxes
  reconstruct: Found 2 orphaned mailbox(es)
  reconstruct: Done checking for orphaned mailboxes

reconstruct Performance

The time it takes reconstruct to perform an operation depends on the following factors:

The reconstruct -r option performs an initial consistency check; this check improves reconstruct performance depending on how many folders must be rebuilt.

The following performance was found with a system with approximately 2400 users, a message store of 85GB, and concurrent POP, IMAP, or SMTP activity on the server:

Common Problems and Solutions

This section lists common message store problems and solutions:

Messenger Express or Communications Express Not Loading Mail Page

If the user cannot load any Messenger Express pages or Communications Express mail page, the problem may be that the data is getting corrupted after compression. This can sometimes happen if the system has deployed a outdated proxy server. To solve this problem, try setting local.service.http.gzip.static and local.service.http.gzip.dynamic to 0 to disable data compression. If this solves the problem, you may want to update the proxy server.

Command Using Wildcard Pattern Doesn’t Work

Some UNIX shells may require quotes around wildcard parameters and some will not. For example, the C shell tries to expand arguments containing wild cards (*, ?) as files and will fail if no match is found. These pattern matching arguments may need to be enclosed in quotes to be passed to commands like mboxutil.

For example:

mboxutil -l -p user/usr44*

will work in the Bourne shell, but will fail with tsch and the C shell. These shells would require the following:

mboxutil -l -p "user/usr44*"

If a command using a wildcard pattern doesn’t work, verify whether or not you need to use quotes around wildcards for that shell.

Unknown/invalid Partition

A user can get the message “Unknown/invalid partition” in Messenger Express if their mailbox was moved to a new partition which was just created and Messaging Server was not refreshed or restarted. This problem only occurs on new partitions. If you now add additional user mailboxes to this new partition, you will not have to do a refresh/restart of Messaging Server.

User Mailbox Directory Problems

A user mailbox problem exists when the damage to the message store is limited to a small number of users and there is no global damage to the system. The following guidelines suggest a process for identifying, analyzing, and resolving a user mailbox directory problem:

  1. Review the log files, the error messages, or any unusual behavior that the user observes.
  2. To keep debugging information and history, copy the entire store_root/mboxlist/ user directory to another location outside the message store.
  3. To find the user folder that might be causing the problem, run the command reconstruct -r -n. If you are unable to find the folder using reconstruct, the folder might not exist in the folder.db.
  4. If you are unable to find the folder using the reconstruct -r -n command, use the hashdir command to determine the location. For more information on hashdir, see The hashdir Utility and the hashdir utility in the Messaging Server Command-line Utilities chapter of the Messaging Server Reference Manual.

  5. Once you find the folder, examine the files, check permissions, and verify the proper file sizes.
  6. Use reconstruct -r (without the -n option) to rebuild the mailbox.
  7. If reconstruct does not detect a problem that you observe, you can force the reconstruction of your mail folders by using the reconstruct -r -f command.
  8. If the folder does not exist in the mboxlist directory (store_root/mboxlist), but exists in the partition directory store_root/partition), there might be a global inconsistency. In this case, you should run the reconstruct -m command.
  9. If the previous steps do not work, you can remove the store.idx file and run the reconstruct command again.


    You should only remove the store.idx file if you are sure there is a problem in the file that the reconstruct command is unable to find.

  10. If the issue is limited to a problematic message, you should copy the message file to another location outside of the message store and run the command reconstruct -r on the mailbox/ directory.
  11. If you determine the folder exists on the disk (store_root/partition/ directory), but is apparently not in the database (store_root/mboxlist/ directory), run the command reconstruct -m to ensure message store consistency.

For more information on the reconstruct command, see Repairing Mailboxes and the Mailboxes Database.

Store Daemon Not Starting

If stored won’t start with the following error message:

# msg_svr_base/sbin/start-msg

msg_svr_base: Starting STORE daemon ...Fatal error: Cannot find group in name service

This indicates that the UNIX group configured in local.servergid cannot be found. Stored and others need to set their gid to that group. Sometimes the group defined by local.servergid gets inadvertently deleted. In this case, create the deleted group, add inetuser to the group, change ownership of the instance_root and its files to inetuser and the group.

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.