Previous     Contents     Index     Next     
iPlanet Messaging Server 5.2 Administrator's Guide



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

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:

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

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:

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

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

You should use the -m option when:

  • One or more directories were removed from the store spool area, so the mailbox database entries also need to be removed.

  • One or more directories were restored to the store spool area, so the mailbox database entries also need to be added.

  • The stored -d option is unable to make the database consistent.

    If the stored -d option is unable to make the database consistent, you should perform the following steps in the order indicated:

    • Shut down all servers.

    • Remove all files in server-root/msg-instance/store/mboxlist.

    • Restart the server processes.

    • Run reconstruct -m to build a new mailboxes database from the contents of the spool area.


To Remove Orphaned Accounts

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

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

To create a file listing orphaned mailboxes that can be turned into a script file that deletes the orphaned mailboxes, where the file is to be named orphans.cmd:

reconstruct -o -d orphans.cmd

Command output 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 a number of factors including:

  • The kind of operation being performed and the options chosen

  • Disk performance

  • The number of folders when running reconstruct -m

  • The number of messages when running reconstruct -r

  • The overall size of the message store

  • What other processes the system is running and how busy the system is

  • Whether or not there is ongoing POP, IMAP, HTTP, or SMTP activity

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

In one example with approximately 2400 users, a message store of 85GB, and concurrent POP, IMAP, or SMTP activity on the server:

  • reconstruct -m took about 1 hour

  • reconstruct -r -f took about 18 hours
    Note A reconstruct operation may take significantly less time if the server is not performing ongoing POP, IMAP, HTTP, or SMTP activity.




Backing Up and Restoring the Message Store

Backup and restore is one of the most common and important administrative tasks. 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:

  • Move user mailboxes from one server to another

  • System crashes

  • Hardware failure

  • Accidental deletion of messages or mailboxes

  • Problems when reinstalling or upgrading a system

  • Natural disasters (for example, earthquakes, fire, hurricanes)

You also need to back up data when migrating users.

Messaging Server provides command-line utilities that allow you to back up and restore the message store. Messaging Server also provides an integrated solution with 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. The backup utility 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 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. For example, backups are probably best scheduled for early morning hours such as 2:00 a.m.


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. Full backups are more appropriate when you need to move or migrate data.


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, for example, if you do not want to impact 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

By organizing users into groups, you can improve backup management. For example, you can specify separate backup sessions for each group. Or you can choose to back up several groups in parallel.

Assuming user messages are stored according to user last name, users whose names begin with A would represent a backup group while users whose last names begin with B would represent another backup group.

The logical view of the message store looks like the following:
               STORE       
           ______|______   
          |             |  
        GROUPA        GROUPB
       ___|___           
      |       |            
    USER    USER           
          ____|____       
         |         |       
       MAILBOX  MAILBOX    

By cataloging users into groups, you can improve backup management. For example, you can specify separate backup sessions for each group. Or you can choose to back up several groups in parallel. For more information about creating backup groups, see To Create Backup Groups.

If you want to create backup groups, you need to create a configuration file in which to store your group definitions. This file must be named backup-groups.conf and it must be stored in the following directory:

server_root/msg-instance/config/backup-groups.conf

The format of this file is:
groups=definitions
groups=definitions
.
.
.

For example, if you want to group users by the first letter of their user IDs, use the following definitions:
groupA=a*
groupB=b*
groupC=c*

Backup object naming uses the logical structure of the message store, as follows:

/server/group/user/mailbox

Where server is the message store instance name. For example: siroe

Messaging Server includes one predefined backup group that is available without creating the backup-groups configuration file. This group is called ALL; it includes all users.


Messaging Server Backup and Restore Utilities

To back up and restore your data, Messaging Server provides the imsbackup and imsrestore utilities.

Please note that the imsbackup and imsrestore utilities are not intended to provide a comprehensive backup facility. These 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. 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.

To perform a back up, issue the imsbackup command as shown in the following example, which backs up user1 to backupfile:

imsbackup -f backupfile /mystore/ALL/user1

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 /mystore/ALL/user1

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


Considerations for Partial Restore

This single-copy backup procedure has implications when restoring messages as follows:

  • Full Restore. During a full restore, linked messages will still point to the same inode as the message file to which they are linked.

  • Partial Backup/Restore. During a partial backup and partial restore, however, the single-copy characteristic of the message store might not be preserved.

Assume there are three messages belonging to three users A, B, and C, as follows:

A/INBOX/1
B/INBOX/1
C/INBOX/1

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

  1. Back up users B and C.

  2. Delete 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 user A.

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

    B/INBOX/1 AND C/INBOX/1 are backed up as links to A/INBOX/1.

  2. Delete users A and B.

  3. Restore user B.

    The restore utilities ask the administrator to restore A/INBOX first.

  4. Restore users A and B.

  5. Delete user A (optional).
    Note 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. This option is most useful in POP environments.



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.

Note 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 server_root/msg-instance/bin/imsasm

  2. From Sun or Legato, obtain a copy of the nsrfile binary and copy it to the following directory:

    /usr/lib/nsr/nsrfile

  3. 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 mkbackupdir.sh.

      Look at the directory structure in server_root/backup. The structure should look similar to that shown in Figure 11-2.

    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.

  4. In the directory /nsr/res/, create a res file for your savegroup to invoke the mkbackupdir.sh script before the backup. See Figure 11-3 for an example.
    Note Legato Networker has a limitation of 64 characters for the saveset name. By default mkbackupdir.sh will create the store image under the server_root/backup directory. If the name of this directory plus the logical name of the mailbox (for example, siroe/groupA/fred) is greater than 64 characters, then you must run mkbackupdir.sh -p. Therefore, you should use a short path name for the -p option of mkbackupdir.sh. For example the following command will create the backup image under the directory /backup:

    mkbackupdir.sh -p /backup

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


Figure 11-2 shows a sample backup groups directory structure.

Figure 11-2    Backup Group Directory Structure
siroe-groupA-a1
            -a2
     -groupB-b1
            -b2
     -groupC-c1
            -c2

Figure 11-3 shows a sample res file named IMS.res in the /nsr/res directory:

Figure 11-3    Sample res File
type: savepnpc
precmd: "echo mkbackupdir started",
   "/usr/siroe/server5/msg-siroe/bin/mkbackupdir.sh -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 savegroup if necessary.

    1. Run nwadmin.

    2. Select Customize | Group | Create.

  2. Create a backup client using savepnpc as the backup command:

    1. Set the saveset to the directory created by mkbackupdir.

      For a single session backup, use server_root/backup

      For parallel backups, use server_root/backup/server/group

      Be sure you've already created group as defined in To Create Backup Groups.

      You must also set the parallelism to the number of backup sessions.

      See Example. Creating A Backup Client in Networker.

  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
Savesets:/backup/siroe/groupA
   /backup/siroe/groupB
   /backup/gotmail/groupC
         .
         .
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)

iPlanet 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 iPlanet Messaging Server.

  1. Divide your users into groups (see "To Create Backup Groups") and create a backup-groups.conf file under the directory server_root/msg-<instance>/config/.

    For example, to group users by UID, use the following definitions in /usr/iplanet/server5/msg-siroe/config/backup-groups.conf:

    groupA=a*
    groupB=b*
    groupC=c*
    . . .
    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.


  2. Run imsbackup to backup each group into files under a staging area.

    The command is imsbackup -f <device> /<instance>/<group>

    You can run multiple imsbackup processes simultaneously. For example:

    # imsbackup -f- /siroe/groupA > /bkdata/groupA &
    # imsbackup -f- /siroe/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.

  3. Use your third party backup software to backup the group data files in the staging area (in our example that is /bkdata).

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

    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- /siroe/groupA/andy



Troubleshooting the Message Store

This section provides guidelines for pro-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 iPlanet Messaging Server Reference Manual. 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 wellness 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 server-root/msg-instance/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 13 "Logging and Log Analysis."


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.

  • Check that the stored process is running. A pid file is created and updated by stored (server-root/msg-instance/config/store.pid).

  • Check that the time stamps of the following files (in directory server-root/msg-instance/config/) are updated whenever one of the following functions are attempted by the stored process:

    Table 11-8    stored Operations

    stored Operation

    Function

    stored.ckp  

    Touched when a database checkpoint was initiated. Stamped approximately every 1 minute.  

    stored.lcu  

    Touched at every database log cleanup. Time stamped approximately every 5 minutes.  

    stored.per  

    Touched at every spawn of peruser db writeout. Time stamped once an hour.  

  • Check for the log file build up in server-root/msg-instance/store/mailboxlist.

  • Check for stored messages in the default log file server-root/msg-instance/log/default/default

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 iPlanet 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 server-root/msg-instance/store/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 nofix) 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.


Common Problems and Solutions

This section lists common message store problems and solutions:


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 server-root/msg-instance/store/mboxlist/ user directory to another location outside the message store.

  3. To find the user folder that might be causing the problem, you should 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.

    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 iPlanet Messaging Server Reference Manual.

  4. Once you find the folder, examine the files, check permissions, and verify the proper file sizes.

  5. Use reconstruct -r (without the -n option) to rebuild the mailbox.

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

  7. If the folder does not exist in the mboxlist directory (server-root/msg-instance/store/mboxlist), but exists in partition directory server-root/msg-instance/store/partition), there might be a global inconsistency. In this case, you should run the reconstruct -m command.

  8. If the previous steps do not work, you can remove the store.idx file and run the reconstruct command again.

    Caution

    		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.


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

  10. If you determine the folder exists on the disk (server-root/msg-instance/store/mboxlist/partition/ directory), but is apparently not in the database (server-root/msg-instance/store/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.


Global Store Problems

If you determine that the message store failure is a problem that is affecting all users or is a result of a global damage to a system, you can use the following guidelines to recover the system:

  1. Stop the message store processes.

    1. Once you have verified that the message store processes have been stopped, restart the message store processes.

    2. Run the stored process to recover the database.

    In many instances, the database can automatically recover from a failure. This process occurs because when stored starts, it initiates a database recovery that analyzes database log files against cache files and database files. It attempts to put the database in a consistent state.

  2. If the msg-start command unexpectedly stops while the stored process command is attempting to start the message store, stored either failed or is trying to recover the store.

    If this process abnormally ends while stored is attempting to start the message store, the stored process might be reviewing large log files in order to restore the database.

    1. Check the server-root/msg-instance/log/default/ directory to review the information that stored has been analyzing.

    2. In addition, you can review the configuration and pidfile.store files.

      The pidfile.store file shows the pid as well as the state of the stored process. The pidfile shows an init state when recovering and a ready state when the stored process has finished repairing the database.

  3. If the pidfile indicates a ready state, then the database has recovered, and the rest of the message store can restart.

    1. Start the store processes and run the reconstruct -m command. For more information on reconstruct, see Repairing Mailboxes and the Mailboxes Database.

    2. Determine if user mailbox directories are valid by monitoring test accounts and reviewing log files.

      If individual user mailboxes are damaged, run the reconstruct -r command.

    3. If damage to the message store is extensive, it might be necessary to repair with the message store processes stopped. See Message Store Recovery Procedures.

  4. If the pidfile cannot change to the ready state, then the stored process is either reviewing the mboxlist log files, or the database cannot recover.

    1. If there are a number of database log files in the server-root/msg-instance/store/mboxlist directory, the stored process might not go beyond the init state. In addition, the database might take too long to recover (For example, twenty to thirty log files can take too long to process on most machines.). If this scenario occurs, you should stop the stored process, remove the files in the server-root/msg-instance/store/mboxlist directory, and initiate snapshot or fast recovery processes.

    2. If the stored process cannot recover the message store, the database is most probably corrupted. You will then need to restore a snapshot copy of the database or initiate fast recovery techniques. For more information, see Message Store Recovery Procedures.

      Caution

      		You should never terminate a process while it is accessing the database. If you terminate the stored process while it is in the init state, you will not be able to recover the database from the existing mboxlist data. Consequently, the data must be removed. If you terminate another process that is accessing the database, the database might be left in an inconsistent state, and you will need to shut down the entire message store and restart it.



Message Store Recovery Procedures

This section describes recovery procedures to rebuild or repair the message store.


To Perform Fast Recovery

When the database is inconsistent, you will use the reconstruct utility during a standard recovery. (See Repairing Mailboxes and the Mailboxes Database.)

If the database is corrupted beyond standard repair, you can use the reconstruct utility for fast recovery by following these procedures:

  1. Stop the message store processes.

  2. Verify all store processes have been stopped.

  3. Copy the server-root/msg-instance/store/mboxlist/* files to a safe location to review at a later point.

  4. Remove all of the files in the server-root/msg-instance/store/mboxlist/ directory.

  5. Start the message store processes such as stored, imapd, popd, and mshttpd.

  6. Run the utility reconstruct -m to rebuild the folder.db.


To Create Database Snapshot Backups

You can pro-actively anticipate message store corruptions by creating backups of the mailboxes database and log files (referred to as snapshots). In the event that the database becomes corrupt, you can use the snapshot to replace the database without having to reconstruct the database. The snapshot facility makes consistent copies of the database over time and can be recovered. Be sure you have enough disk space to keep these backups.

Note Unless otherwise specified, the database snapshot parameters listed in Table 11-9 should only be used with iPlanet Messaging Server 5.2.


Table 11-9 describes the three configutil parameters that are used to create database snapshots. These database snapshots are then invoked by the stored process during recovery:

Table 11-9    configutil Database Snapshot Parameters 

Database Snapshot Parameter

Description

local.store.snapshotpath  

Specifies the path in which to copy the mboxlist directory. Permissions are set for the message store owner. Snapshots will be placed in subdirectories.  

local.store.snapshotinterval  

Interval of time between snapshots. Unit of time is in minutes. It is recommended that you perform this procedure at least once a day.  

local.store.snapshotdirs  

Number of separate snapshots to store on disk. Minimum is 2, default is 3, recommend enough to be sure you have a good database back by the time you figure out the current one is beyond repair.  

To create a backup of the database, you use the configutil command to specify values for the following parameters:

configutil -o local.store.snapshotinterval -v number

where number specifies how often stored will back up the database; number indicates a time interval in minutes.

configutil -o local.store.snapshotpath -v path

where path indicates the location of the backup copy.

Caution

Database snapshots utilities from earlier Messaging Server releases do not function in the same way as these utilities. Therefore, older Messaging Server versions of snapshot utilities are not recommended for use with Messaging Server 5.2.



To Recover the Message Store with Database Snapshots

In order to recover the database utilizing database snapshots, it is imperative that you are familiar with the message store layout. For more information, see Message Store Directory Layout.

After the database snapshots are created (as explained in To Create Database Snapshot Backups), they are stored in src subdirectories. These files eventually are moved to the dst server-root/msg-instance/store/mboxlist/ directory where the recovered database resides. In addition to the snapshot files, there are control files that are created while the snapshots are created. Table 11-10 describes the database snapshot control files. Note that these files are owned by the message store owner:

Table 11-10    Database Snapshot Control Files 

Control File

Description

dst/.nosnap  

Disables the database snapshot process even if configuration data is not refreshed.  

dst/.snaprst  

Marks all previous snapshots as invalid. This file is removed after the first new snapshot.  

dst/.catrecov  

Triggers the stored process to initiate a catastrophic recovery that restores the snapshot to a usable format.  

src/.snaptime  

Indicates a valid snapshot is in the directory. The time stamp of this file indicates when the snapshot completed.  

The following steps explain how to perform a manual recovery by using database snapshots, control files, src/, and dst/ directories:

  1. Be sure that you are the message store owner prior to performing the recovery.

  2. Stop the message store processes and verify all processes have been stopped.

  3. Copy the files in server-root/msg-instance/store/mboxlist/ directory to a safe location to review at a later time.

  4. Review the snapshots you took to determine which, if any, can replace the message store. For more information, see To Create Database Snapshot Backups.

    1. Use the *.snaptime files to determine the validity and time of backup. If a snapshot has too many corresponding log files, review a different snapshot.

    2. Pick the latest valid snapshot that did not capture the database problem.

      If no snapshot is available, follow the fast recovery procedures. For more information, see To Perform Fast Recovery.

  5. Remove all of the files in the server-root/msg-instance/store/mboxlist/ directory, since they are corrupted.

  6. Copy the corresponding snapshot files from the chosen snapshot to the server-root/msg-instance/store/mboxlist/directory, but be sure not to copy the *.snaptime files.

  7. Use the touch command to create the .catrecov file in directory server-root/msg-instance/store/mboxlist/.

    A .catrecov file signals to the message store that a catastrophic recovery needs to be performed.

  8. Start the message store processes.

  9. Monitor the stored process. The stored process should recover.

  10. Make sure that the server-root/msg-instance/store/mboxlist/.catrecov file has been removed after the stored process has recovered, otherwise the message store will assume it needs to do a catastrophic recovery whenever it starts up.

  11. Run reconstruct -m to fix any differences between the snaptime file and the database failure.


Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated February 27, 2002