Previous     Contents     Index     DocHome     Next     
iPlanet Messaging Server 5.0 Administrator's Guide



Chapter 10   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. If you have a very large user base, you might have multiple Messaging Server instances, each responsible for a particular message store. 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.

To manage the message store, iPlanet Messaging Server provides a set of command-line utilities in addition to the iPlanet Console interface. Table 10-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 10-1 Message Store Command-line Utilities

Utility

Description

configutil  

Sets and modifies configuration parameters for the store.  

hashdir  

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

mboxutil  

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

MoveUser  

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

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.  

imsbackup  

Performs backups of the messages stored on disk.  

imsrestore  

Restores messages that have been backed up.  



Message Store Directory Layout



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

Figure 10-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 10-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/  

Contains information about the IMAP folders to which each user subscribes. Information for each user is stored in a file called userid.sub. These files are stored in a hash structure for fast searching. To find the directory that contains a particular user's files, use the hashdir utility.  

.../store/partition/  

Contains the default primary partition. You can also place any other subpartitions you define in this directory.  

/subpartition/=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  

(Not shown in Figure 10-2.) 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  

(Not shown in Figure 10-2.) 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 Message



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.



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.


Adding 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 comma-separated list of administrator IDs. If you specify more than one administrator, you must enclose the list in quotes.


Modifying 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"


Deleting 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 the total size or the total number of all the user's messages exceeds the specified limits set, messages destined for the user remain in the message queue until one of the following occurs: (1) The size or number of all the user's messages no longer exceeds the limit, at which time the server delivers the message to the user. (2) The undelivered message has been in the queue longer than the specified grace period and the user is still over quota, at which time the server bounces the message.



Note The server does not consider the size of the message when it is attempting to deliver to an account that is still under quota. If the message causes the user to go over quota, the message is still delivered, but the next message will be held in the queue.



Disk space becomes available when a user deletes and expunges messages or when the server deletes messages according to the maintenance policies you have established (aging policies, for example).


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. For more information about domain and family group quotas, see the Delegated Administrator User's Guide.


Exceptions for Telephony Application Servers

To support unified messaging requirements, Messaging Server provides the ability to override quota limitations imposed by the message store, thus guaranteeing 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.


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


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

Table 10-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. Click Save.

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

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


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.


Setting a Grace Period

If a user mailbox exceeds the quota for allotted disk space or total number of messages, the grace period you specify determines how long messages will be held in the message queue before the server starts bouncing the messages. Messages will remain in the queue until one of the following occurs:

  • The mailbox no longer exceeds the quota, at which time the server will deliver the message to the mailbox.

  • The user has remained over quota longer than the specified grace period, at which time the server will bounce the message.

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

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.



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

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.



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.




Adding 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



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 12 "Logging and Log Analysis."

This section contains the following:


Managing 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 Monitoring Quota Limits.

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


Table 10-4 mboxutil Options

Option

Description

-a  

Lists all user quota information.  

-c mailbox  

Creates the specified mailbox.  

-d mailbox  

Deletes the specified mailbox.  

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


Note that you cannot rename a user's INBOX. Nor can you use mboxutil -r to move mail stored under one user ID to another user ID.
 

-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


Monitoring 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


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


Table 10-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.


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

  • Issuing of alarms if necessary

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

You can also use the stored utility to create a backup of the mailboxes database and log files. If the database becomes corrupt, you can use the backup copy to replace the database without having to reconstruct the database. 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.

Table 10-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 10-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 becomes 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 10-7 lists the reconstruct options. For detailed syntax and usage requirements, see the Messaging Server Reference Manual.


Table 10-7 reconstruct Options

Option

Description

-f  

Forces a reconstruct without performing a consistency check. You can use this option to force a reconstruct even if the consistency check passes.  

-m  

Performs a high-level consistency check and repair of the mailboxes database. Examines every mailbox in the spool area, adding or removing entries from the mailboxes database as appropriate. Prints a message to the standard output file whenever it adds or removes an entry from the database. This option should be run with stored -d to ensure that the database is checkpointed as it is reconstructed.  

-n  

Performs a consistency check, but makes no repairs even if a problem is found. This option is used primarily for debugging, but it can also be used to check the store.  

-o  

Checks for orphaned accounts. Searches for inboxes in the current messaging server host which do not have corresponding entries in LDAP. For example, the -o option would find 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. You can use this option on the first usage of reconstruct.  

-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]  

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


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

    • Run stored -d.

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

    • After reconstruct -m completes, restart the server processes.


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




Moving a User's Account

The MoveUser utility moves a user's account from one messaging server to another. When user accounts are moved from one messaging server to another, it's also necessary to move the user's mailboxes and the messages they contain from one server to the other. In addition to moving mailboxes from one server to another, MoveUser updates entries in the Directory Server to reflect the user's new mailhost name and message store path.

To use the MoveUser utility, the user must authenticate by including the -a option in the MoveUser command. Any valid message store administrator can run the MoveUser command. Users are granted store administrator privileges as follows:

  • You can grant message store administration privileges for a specific Messaging Server by using iPlanet console. For more information, see Specifying Administrator Access to the Store.

  • DA Top-level administrators are automatically granted message store administration privileges for the entire mail system.

  • DA domain administrators are automatically granted message store administration privileges for the domain.

Table 10-8 lists the MoveUser options. Usage examples follow the table. For detailed syntax and usage requirements, see the Messaging Server Reference Manual.


Table 10-8 MoveUser Options

Option

Description

-a destproxyuser  

ProxyAuth user for destination messaging server.  

-A  

Do not add an alternate email address to the LDAP entry.  

-d destmailhost  

Destination messaging server.  

-D binddn  

Binding dn to the given ldapURL.  

-F  

Delete messages in source messaging server after successful move of mailbox. (If not specified, messages will be left in source messaging server.)  

-h  

Display help for this command.  

-l ldapURL  

URL to establish a connection with the Directory Server:  

-L  

Add a license for Messaging Server if not already set.  

-m destmaildrop  

Message store path for destination messaging server. (If not specified, the default is used.)  

-n msgcount  

Number of messages to be moved at once.  

-o srcmaildrop  

Message store path for source messaging server. (If not specified, the default is used.)  

-p srcproxypasswd  

ProxyAuth password for source messaging server.  

-s srcmailhost  

Source messaging server.  

-S  

Do not set new message store path for each user.  

-u uid  

User ID for the user mailbox that is to be moved. Cannot be used with -l option.  

-U newuid  

New (renamed) user ID that the mailbox is to be moved to.  

-v destproxypwd  

ProxyAuth password for destination messaging server.  

-w bindpasswd  

Binding password for the binddn given in the -D option.  

-x srcproxyuser  

ProxyAuth user for source messaging server.  

To move all users from host1 to host2, based on account information in the Directory Server siroe.com:

MoveUser -l \
  "ldap://siroe.com:389/o=Siroe.com???\
  (mailhost=host1.domain.com)" \
  -D "cn=Directory Manager" -w password -s host1 -x admin \
  -p
password -d host2 -a admin -v password


To move one user from host1 which uses port 150 to host2, based on account information in the Directory Server siroe.com:

MoveUser -l \
  "ldap://siroe.com:389/o=Siroe.com???(uid=userid)" \
  -D "cn=Directory Manager" -w password -s host1:150 -x admin \
  -p password -d host2 -a admin -v password


To move a group of users whose uid starts with letter `s' from host1 to host2, based on account information in the Directory Server server1.siroe.com:

MoveUser -l \
  "ldap://server1.siroe.com:389/o=Siroe.com???(uid=s*)" \
  -D "cn=Directory Manager" -w password -s host1 -x admin \
  -p password -d host2 -a admin -v password


To move a user's mailboxes from host1 to host2 when the user ID of admin is specified in the command line:

MoveUser -u uid \
  -s host1 -x admin -p password \
  -d host2 -a admin -v password


To move a user named aldonza from host1 to a new user ID named dulcinea on host2:

MoveUser -u aldonza -U dulcinea \
  -s host1 -x admin -p password \
  -d host2 -a admin -v password




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:

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


How Users Are Provisioned

Depending on the size of your message store, message data might be stored on several disks. Disk 1 might hold messages for users whose last names being with A through F; disk 2 might hold messages for users whose last names begin with G through M, and so on. Or, users might be provisioned by function, with disk 1 containing Marketing personnel data, disk 2 containing Engineering personnel data, and so on.

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

The logical view of the message store looks like the following:

               STORE       
           ______|______   
          |             |  
        GROUP         GROUP
       ___|___           
      |       |            
    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 Creating Backup Groups.


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.


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

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:

serverRoot/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

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 general-purpose 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 Using 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.




Using 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 serverRoot/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 Creating Backup Groups.

    2. To verify your configuration, run mkbackupdir.sh.

      Look at the directory structure in serverRoot/msg-instance/backup. The structure should look similar to that shown in Figure 10-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 10-3 for an example.

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

Figure 10-2    Backup Group Directory Structure

siroe-groupA-a1
            -a2
     -groupB-b1
            -b2
     -groupC-c1
            -c2


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

Figure 10-3    Sample res File

type: savepnpc
precmd: "echo mkbackupdir started",
   "usr/siroe/server5/msg-siroe/bin/mkbackupdir.sh"
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 serverRoot/msg-instance/backup

      For parallel backups, use serverRoot/msg-instance/backup/server/group

      Be sure you've already created group as defined in Creating 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:/usr/siroe/server5/msg-siroe/backup/siroe/groupA
   /usr/siroe/server5/msg-siroe/backup/siroe/groupB
   /usr/siroe/server5/msg-gotmail/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 usr/siroe/server5/msg-siroe/backup/siroe/groupA/a1/INBOX

The next example recovers the entire message store:

recover -a -f -s siroe /usr/siroe/server5/msg-siroe/backup/siroe


Previous     Contents     Index     DocHome     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated September 14, 2000