Chapter 11   Managing the Message Store


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

• "Overview"

• "Message Store Directory Layout"

• "How the Store Erases Messages"

• "Specifying Administrator Access to the Store"

• "About Message Store Quotas"

• "Configuring Message Store Quotas"

• "To Specify Aging Policies"

• "Configuring Message Store Partitions"

• "Performing Maintenance and Recovery Procedures"

• "Backing Up and Restoring the Message Store"

• "Troubleshooting the Message Store"

Overview

---

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 partitions. Optionally, you can also add additional Messaging Server instances, each responsible for a particular message store. However, this approach is more complex.

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, iPlanet Messaging Server provides a set of command-line utilities in addition to the iPlanet Console interface. Table 11-1 describes these command-line utilities. For information about using these utilities, see Performing Maintenance and Recovery Procedures and the Messaging Server Reference Manual.

Table 11-1    Message Store Command-line Utilities

Utility	Description
configutil	Sets and modifies configuration parameters for the store.
deliver	Delivers mail directly to the message store accessible by IMAP or POP mail clients.
hashdir	Identifies the directory that contains the message store for a particular user.
iminitquota	Reinitializes the quota limit from the LDAP directory and recalculates the disk space being used.
imsasm	Handles the saving and recovering of user mailboxes.
imsbackup	Backs up stored messages.
imsexport	Exports Certificate Management System mailboxes into UNIX /var/mail format folders.
imsrestore	Restores messages that have been backed up.
imscripter	The IMAP server protocol scripting tool. Executes a command or sequence of commands.
mboxutil	Lists, creates, deletes, renames, or moves mailboxes; reports quota usage.
mkbackupdir	Creates and synchronizes the backup directory with the information in the message store.
MoveUser	Moves a user's account from one messaging server to another.
quotacheck	Calculates the total mailbox size for each user in the message store and compares the size with their assigned quota.
readership	Collects readership information on shared IMAP folders.
reconstruct	Reconstructs mailboxes that have been damaged or corrupted.
stored	Performs background and daily tasks, expunges, and erases messages stored on disk.

Message Store Directory Layout

---

Figure 11-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 11-2.

Figure 11-1    Message Store Directory Layout

For example, a sample directory path might be:

server_root/msg-instance/store/partition/primary/=user/53/53/=mack1

Table 11-2    Message Store Directory Description

Location	Content/Description
server_root/msg-instance/ store/	Top-level directory of the message store. Contains the mboxlist, user, and partition subdirectories.
.../store/mboxlist/	Contains a database (Berkley DB) that stores information about the mailboxes on the server and stores quota information about the mailboxes. The file 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 The file quota.db contains information about quotas and quota usage. There is one entry in quota.db2 per user. The file peruser.db contains information about per-user flags. The flags indicate whether a particular user has seen or deleted a message. The file subscr.db contains information about user subscriptions.
.../store/user/	Not used.
.../store/partition/	Contains the default primary partition. You can also place any other subpartitions you define in this directory.
/partition/=user/	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.
/=user/hashdir/hashdir/ userid/	The top-level mail folder for the user whose ID is userid. For the default domain, userid is uid. For hosted domains, userid is uid@domain. Messages are delivered to this mail folder.
/userid/folder	A user-defined folder.
/userid/store.idx	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.
/userid/store.usr	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.
/userid/store.exp	Contains a list of message files that have been expunged, but not removed from disk. This file appears only if there are expunged messages.
/userid/store.sub	Contains information about user subscriptions.
/userid/nn/	A hash directory that contains messages in the format msgid.msg; nn can be a number from 00 to 99. For example, messages 1 through 99 are stored in the 00 directory; 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 Store Erases Messages

---

Messages are erased from the store in three stages:

1. Delete. A client marks the message to be deleted. At this point, the client can restore the message by removing the "deleted" marking.

2. Expunge. A client, or the aging policies you have specified, expunges messages that have been marked deleted from the mailbox. Once messages are expunged, the client can no longer restore them, but they are still stored on disk. (A second client with an existing connection to the same mailbox may still be able to fetch the messages.)

3. Cleanup. The stored utility erases from the disk any messages that have been expunged for at least one hour.

Messages can also be erased by setting the expire option. The server deletes messages based on aging policies defined by configutil. At expiration, messages are expunged, but will not be physically removed until cleanup. (See "To Specify Aging Policies".)

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.

---

Note

Other users might also have administrator privileges to the store. For example, if your site uses the Delegated Administration (DA) product, top-level DA administrators by default have store privileges for all messaging servers in the mail system. DA domain administrators by default have store privileges for their domain. For more information about the DA administrators, see the Messaging Server Provisioning Guide and the DA documentation.

---

You can perform tasks as described in the following subsections:

• To Add an Administrator

• To Modify an Administrator Entry

• To Delete an Administrator Entry

You can specify administrator access to the store by using the configutil command or by using Console.

If you want to use 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 in the right pane.

To Add an Administrator

Console. To add an administrator entry at the Console:

1. Click the Administrator tab.

   The tab contains a list of existing administrator IDs.

2. Click the Add button beside the Administrator UID window.

3. In the Administrator UID field, type the user ID of the administrator you want to add.

   The user ID you type must be known to the iPlanet Directory Server.

4. Click OK to add the administrator ID to the list displayed in the Administrator tab.

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

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 Message Store Quotas

---

This section contains information about the following:

• User Quotas

• Domain Quotas and Family Group Quotas

• Exceptions for Telephony Application Servers

User Quotas

You can limit the size of the message store by specifying limits on the size of user mailboxes. You can specify the following types of quotas.

• Disk quotas allow you to limit the amount of disk space allotted to 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 to the total number of user messages. If disk space is limited, you might want to set user disk quotas.

• Message quotas allow you to limit the number of messages stored in a user's mailbox.

Quota information is stored as LDAP attributes and configuration variables. If quota enforcement is enabled, Messaging Server checks the quota cache and configuration file to ensure quotas have not been exceeded before inserting messages into the message store. If quota notification is enabled, users are sent an error message when they have reached their disk quota. You can also enable the server to send a warning message when users are nearing their quota limit.

You can set default quotas for all users or set quotas for individual users. To determine if a user is over quota, Messaging Server first checks to see if a quota has been set for the individual user. If no quota has been set, Messaging Server then looks at the default quota set for all users.

If a user's messages exceed their quota, incoming messages remain in the MTA queue until one of the following occurs:

(1) The size or number of the user's messages no longer exceeds the quota, at which time the MTA delivers the messages to the user. (2) The undelivered message remains in the MTA queue longer than the specified grace period. See "To Set a Grace Period".

Disk space becomes available when a user deletes and expunges messages or when the server deletes messages according to the aging policies you have established.

Domain Quotas and Family Group Quotas

You can also set quotas for a particular domain and for family groups within a domain. These quotas are not enforced, but they are useful for reporting purposes.

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 will ensure the message is delivered to the store regardless of quota limits. For more information about configuring the TAS channel, see Chapter 8 "Configuring Channel Definitions."

Configuring Message Store Quotas

---

You set default quotas for all users by using iPlanet Console or by using the configutil command. You can also set quotas for individual users, family groups, and hosted domains.

This document describes how to set default quotas. For more information about setting quotas for individual users, family groups, and domains, see the Delegated Administrator's User Guide.

This section describes the following tasks:

• To Specify a Default User Quota

• To Enabling Quota Enforcement and Notification

• To Set a Grace Period

If you want to use iPlanet Console:

1. From iPlanet 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 Quota tab in the right pane.

To Specify a Default User Quota

The default quota applies to users who do not already have individual quotas set for them. A quota set for an individual user overrides the default quota.

Console. To specify a default quota at the Console:

1. Click the Quota tab.

2. To specify a default user disk quota, for the "Default user disk quota" field, select one of the following options:

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

3. To specify a message number quota, in the "Default user message quota" box, type a number.

4. Click Save.

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; number indicates a number in bytes.

To specify a default user quota for total message number:

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

where -1 indicates no quota; number indicates number of messages.

To Enabling Quota Enforcement and Notification

You can enable or disable quota enforcement and quota notification. The action the server takes depends on how these configuration variables are set, as shown in Table 11-3.

Table 11-3    Quota Enforcement and Notification

	Enforcement On	Enforcement Off
Notification On	Messages are deferred for specified grace period; rejected if grace period expires. Messages cannot be appended to mailbox. IMAP SELECT, IMAP APPEND, SMTP sendmail mechanism and deliver command will display error message.	Messages are delivered to the store. Messages can be appended to mailbox. IMAP SELECT, IMAP APPEND, SMTP sendmail mechanism and deliver command do not display error messages.
Notification Off	Messages are deferred for specified grace period; rejected if grace period expires. Messages cannot be appended to mailbox. IMAP SELECT command, deliver command, and SMTP sendmail mechanism do not display error message. IMAP APPEND command will display error message.	Messages are delivered to the store. Messages can be appended to mailbox. IMAP SELECT, IMAP APPEND, SMTP sendmail mechanism and deliver command do not display error message.

Enabling Quota Enforcement

Console. To enable quota enforcement at the Console:

1. Click the Quota tab.

2. Check the "Enable quota enforcement" box.

   This box acts as a toggle. To disable quota enforcement, uncheck this box.

3. Click Save.

Command Line. To enable quota enforcement at the command line:

configutil -o store.quotaenforcement -v [ yes | no]

If you specify no, quotas are not enforced.

Enabling Quota Notification

Console. To enable quota notification at the Console:

1. Click the Quota tab.

2. Check the "Enable quota notification" box.

   This box acts as a toggle. To disable quota enforcement, uncheck this box.

3. Define the quota warning messages

   See "Defining a Quota Warning Message".

4. Click Save.

Command Line. To enable quota notification at the command line:

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

If the message is not set, then no quota warning message will be sent to the user.

Defining a Quota Warning Message

You can define the message that will be sent to users who have exceeded 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.

To define how often the warning message is sent:

configutil -o store.quotaexceedmsginterval -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

You can send a warning message to IMAP users before they reach their disk quota by specifying a quota threshold. 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 (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.

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

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

• The mailbox no longer exceeds the quota, at which time messages are delivered to the mailbox.

• The user has remained over quota longer than the specified grace period, at which time the server will bounce all messages including those in the queue.

• The message has remained in the queue longer than the maximum message queue time.

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

---

Note	Grace period is NOT how long the message will held in the queue, it's how long the mailbox is over quota before all incoming messages, including those in the queue, are bounced.

---

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 Specify Aging Policies

---

Aging policies are another way to control disk usage on your server. You can control how long messages are stored in one or more mailboxes. If you have limited disk space, you might want to set aging policies to remove messages from the store. If you set aging policies, you should educate your users about these policies because the server will not send warning messages before it deletes messages from the store.

You can create aging rules based on the following criteria:

• Number of messages in the mailbox.

• Total size of the mailbox.

• Number of days that messages remain in the mailbox.

• Number of days that messages exceeding a given size remain in the mailbox,

If you specify more than one rule for a mailbox, all expiration rules will apply, but the most restrictive rule takes precedence. For example, assume two rules apply to a single mailbox. The first rule allows 1000 messages; the second rule allows 500 messages. When expiration occurs, the server will delete messages from the mailbox until 500 remain. For another example, if the first rule allows a message size of 100,000 bytes for 3 days and the second rule allows a message size of 1000 bytes for 12 days, the resulting union of rules allows a message size of 100,000 bytes for 3 days. The server will delete messages over 100,000 bytes that have been in the mailbox over 3 days. If you want to ensure that a specific rule is the only rule for a particular mailbox or set of mailboxes, use the Exclusive parameter.

Console. To create a new rule by using Console:

1. From iPlanet 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 Aging tab in the right pane.

4. Click Add to go to the Add Rule window.

5. Enter a name for the new rule.

6. Specify the target folders for which this rule applies.

   You can enter a path name, filename, or partial string. You can use IMAP wildcards as follows:

   * - Match any series of characters.
   % - Match any series of characters except slash characters.

   The new rule applies only to folders matching the pattern you specify.

7. If this rule is to be the only rule applied to the target folders, click the Exclusive selection box.

8. If you want to create a rule based on folder size, do the following:
   • 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 a number for the folder size; from the associated drop-down list, choose Mbyte(s) or KByte(s).

   When the specified folder size is exceeded, the server removes the oldest messages until this size is no longer exceeded.

9. If you want to create a rule based on message age, in the "Number of days" field, specify a number to indicate how long messages should remain in the folder.

10. If you want to create a rule based on message size:
    • In the "Message size limit" field, enter a number to indicate the maximum size message allowed in the folder; from the associated drop-down list, choose Mbytes or Kbytes.

    • In the "Grace period" field, enter a number to indicate how long over-sized messages should remain in the folder.

    After the grace period, the server deletes messages that exceed the maximum size.

11. Click OK to add the new rule to the Aging Rule list and dismiss the Add window.

12. Click Save to submit and preserve the current Aging Rule list.

Command Line. To create a new rule at the command line, use the following commands where name represents the name you give the rule. Note that this describes only the most frequently used store.expire* options. For a complete list refer to the iPlanet Messaging Server Reference Manual.

To specify the target folders for which this rule applies:

configutil -o store.expirerule.name.folderpattern -v pattern

For example, the pattern user/* matches everything; the patter user/%@siroe.com/* matches all folders for all users in the domain siroe.com; and the pattern user/%/Trash matches the Trash folder for all users.

To specify that this rule is to be the only rule applied to the target folders:

configutil -o store.expirerule.name.exclusive -v [ yes | no ]

To specify the maximum number of messages that will be retained in a folder before the oldest messages are removed:

configutil -o store.expirerule.name.messagecount -v number

To specify the folder size:

configutil -o store.expirerule.name.foldersizebytes -v number

where number is a size in bytes.

To specify message age:

configutil -o store.expirerule.name.messagedays -v number

where number indicates the number of days.

To specify message size:

configutil -o store.expirerule.name.messagesize -v number

where number is a size in bytes.

To indicate how long over-sized messages should remain in the folder:

configutil -o store.expirerule.name.messagesizedays -v number

where number indicates number of days.

To Specify Expiration Time and Day

To specify the expiration time and day:

configutil -o store.expirestart -v time (example: 23 is 11:00PM)
configutil -o local.store.expire.workday -v day (0-6, 0 is Sunday)

Setting local.store.expire.workday to -1 or a value larger than 6 will disable expire/cleanup. stored will check this configuration variable at the time specified by store.expirestart everyday. If local.store.expire.workday is not set, then the default is to run every day. There is no need to restart stored after changing this variable.

Configuring Message Store Partitions

---

All user mailboxes are stored by default in the msg-instance/store/partition/ directory. The partition directory is a logical directory that might contain a single subpartition or multiple subpartitions. The subpartitions might map to a single physical drive or to multiple physical drives. 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:

msg-instance/store/partition/mkting/
msg-instance/store/partition/eng/
msg-instance/store/partition/sales/

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.

---

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

---

Note	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 iPlanet 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.

   This is the logical name for the specified partition.

6. Enter the Partition path.

   This is the absolute path name for the specified partition.

7. To specify this as the default partition, click the selection box labeled Make This the Default Partition.

8. Click OK to submit this partition configuration entry and dismiss the window.

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

• Reduce the size of user mailboxes

• If you are using volume management software, add additional disks

• Create additional partitions ("To Add a Partition") and move mailboxes to the new partitions

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 the ProvisioningUsers Chapter in the iPlanet Messaging Server Provisioning Guide.
   

   ---

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

   mboxutil -r user/<userid>/INBOX user/<userid>/INBOX <partition_name>

   Example:

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

3. Set the mailMessageStore attribute in the moved user's LDAP entry to the name of the new partition.

   Example: mailMessageStore: secondary

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

Performing Maintenance and Recovery 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 13 "Logging and Log Analysis."

This section contains the following:

• To Manage Mailboxes

• To Monitor Quota Limits

• To Monitor Disk Space

• Using the stored Utility

• Repairing Mailboxes and the Mailboxes Database

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. These tasks include the following:

• List mailboxes

• Create mailboxes

• Delete mailboxes

• Rename mailboxes

• Move mailboxes from one partition to another

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

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

Table 11-4    mboxutil Options

Option	Description
-a	Lists all user quota information.
-c mailbox	Creates the specified mailbox.
-d mailbox	Deletes the specified mailbox.
-f file	Creates, deletes, or locks the mailbox or mailboxes listed in the specified data file.
-g group	Lists quota information for the specified group.
-k mailbox cmd	Locks the specified mailbox at the folder level; runs the specified command; after command completes, unlocks the mailbox.
-l	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 IMAP wildcards.
-q domain	Lists quota information for the specified domain.
-r oldname newname [partition]	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	Lists user information such as current size of mail store, quota (if one has been set), and percentage of quota currently in use.
-x	When used in conjunction with the -l option, shows the path and access control for a mailbox.

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.

Examples
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

You can monitor quota usage and limits by using the mboxutil utility. The mboxutil utility generates a report that lists defined quotas and limits, and provides information on quota usage. Quotas and usage figures are reported in kilobytes.

For example, the following command lists all user quota information:

mboxutil -a

The next example lists quota information for the user crowe:

mboxutil -u crowe

The next example lists quota information for a the domain siroe.com:

mboxutil -q siroe.com

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 11-5.

Table 11-5    Disk Space Alarm Attributes

Disk Space Attributes	Default Value
alarm.diskavail.msgalarmstatinterval	3600 seconds
alarm.diskavail.msgalarmthreshold	10%
alarm.diskavail.msgalarmwarninginterval	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:

• Background and daily messaging tasks.

• Deadlock detection and rollback of deadlocked database transactions.

• Cleanup of temporary files on startup.

• Implementation of aging policies.

• Periodic monitoring of server state, disk space, service response times, and so on (see "stored").

• Issuing of alarms if necessary.

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 11-6 lists the stored options. Some common usage examples follow the table. For detailed syntax and usage requirements, see the Messaging Server Reference Manual.

Table 11-6    stored Options

Option	Description
-c	Performs one cleanup pass to erase expunged messages. Runs once, then exits. The -c option is a one-time operation, so you do not need to specify the -1 option.
-d	Run as daemon. Performs system checks and activates alarms, deadlock detection, and database repair.
-1	Run once, then exit.
-n	Run in trial mode only. Does not actually age or cleanup messages. Runs once, then exits.
-v	Verbose output.
-v -v	More verbose output.

To test expiration policies:

stored -n

To perform a single aging and cleanup pass:

stored -l -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:

server-root/msg-instance/stop-msg store
server-root/msg-instance/start-msg store

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

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 mailboxes database, and repair any inconsistencies.

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 with stored -d.

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

Table 11-7    reconstruct Options

Option	Description
-f	Forces reconstruct to perform a fix on the mailbox or mailboxes.
-m	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 mailboxes database as appropriate. The utility prints a message to the standard output file whenever it adds or removes an entry from the database.
-n	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/
-o	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.
-q	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:

• Accessing a mailbox returns one of the following errors: "System I/O error" or "Mailbox has an invalid format".

• Accessing a mailbox causes the server to crash.

• Files have been added to or removed from the spool directory.

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

Y