This chapter details the commands used to administer the M-Store. Please note the mode in which each command utility is meant to operate. Also note that many of the utilities presented here can be accessed via the Web Administration Interface. Please see the "Web Administration" section of this document for further details.
The section provides the specific command paths for operating M-Store. This information is also presented in the Package Installation Summary screen if M-Store was installed using an included setup wizard.
Please log in as the superuser to start and stop M-Store. The command varies slightly by platform. Refer to the following command path appropriate to your platform:
To start M-Store: /etc/rc.d/init.d/rc.m-store start
All M-Store servers are daemon processes. It is possible that the rc.m-store script may falsely fail to detect the successful startup of a server. This behavior can occur on older slower machines or if the store is started while the machine is under load. To confirm the startup of a server, read the syslog files.
msadm_tclsh [-f config_file] [script...] |
msadm_tclsh is a simple TCL-based administrative client for the M-Store server. If given optional scripts on the command line, msadm_tclsh reads TCL commands from the file script and evaluates them. Otherwise, msadm_tclsh runs in interactive mode, reading commands from the standard input and evaluating them. msadm_tclsh runs until the exit or quit command is invoked, or until it reacIMhes end-of-file on its standard input. Any arguments other than those specified here are made available in the TCL variables argc and argv. msadm_tclsh must be run as the run-time user.
msadm_tclsh will not run if any database files are missing, in such a case a backup containing all database files must be restored.
Table 12-1. msadm_tclsh Options
Option | Description |
|---|---|
-f config_file | Specify an alternate location for the M-Store configuration file. |
script | Execute commands from a file script or execute the listed commands when evoked from a script as: #!/usr/local/md/sbin/msadm_tclsh\ domain_set esys.ca user_add joe |
The following commands may be used at any time during the session.
Table 12-2. msadm_tclsh Generic Commands
Command | Description & Example |
|---|---|
help | Get help on commands, for example, help command |
quit | Terminate the session and exit (that is, quit or exit). |
The following commands are used to manage site administrators. They may be used at any time during the session.
Table 12-3. msadm_tclsh Site Administration Commands
Command | Description & Example |
|---|---|
get_admin_domain | Displays the name of the administrative domain as defined by admin-domain in the configuration file, for example, get_admin_domain. |
site_admin_add | Add user as a site administrator in the administrative domain, for example, site_admin_add user. |
site_admin_del | Delete user as a site administrator in the administrative domain, for example, site_admin_del user. |
site_admin_list | List site administrators matching the specified glob pattern, for example, site_admin_list pattern. |
The following commands are used to manage domains.
Table 12-4. msadm_tclsh Domain Management Commands
Command | Description & Example |
|---|---|
domain_add | Create the specified domain. The users anonymous and anyone are implicitly created by this command, for example, domain_add domain |
domain_allow_anon | Allow anonymous logins for the specified domain. Anonymous logins are allowed by default when a domain is created, for example, domain_allow_anon domain. |
domain_del | Remove the specified domain and all corresponding users and mailboxes. This command is not reversible. Use it with caution. Example: domain_del domain. |
domain_del_quota | Remove the asigned quota for the specified domain, for example, domain_del_quota domain. |
domain_disable | Temporarily disables users of the specified domain from accessing the server. This prevents users of the domain from being authenticated, but still allows incoming mail to be delivered, for example, domain_disable domain. |
domain_disable_anon | Disable anonymous logins for the specified domain, for example, domain_disable_anon domain. |
domain_enable | Allow users of the specified domain to access the server. Domains created with domain_add are enabled by default, for example, domain_enable domain. |
domain_get | Display the details for the specified domain including whether or not it is enabled and allows anonymous logins, for example, domain_get domain. |
domain_list | List domains matching the specified glob pattern, for example, domain_list pattern. |
domain_rename | Rename domain oldname to newname. Any existing password/authentication accounts for this domain will not be renamed, for example, domain_rename oldname newname. |
domain_set | Set the administrative domain to domain. All subsequent account and mailbox commands will take place within the specified domain. This function assumes the domain has been created with domain_add, for example, domain_set domain. |
domain_set_quota | Set a quota limit of quota_limit kilobytes for the specified domain, for example, domain_set_quota domain quota_limit. |
The following commands are used to manage domain administator, internal password (authentication), and user accounts. They may only be used after defining the current administrative domain with the domain_set command.
Table 12-5. msadm_tclsh Account Management Commands
Command | Description |
|---|---|
admin_add | Designate the specified user to be an administrator of the current domain, for example, admin_add user. |
admin_del | Remove the administrator privileges for the specified user, for example, admin_del user. |
admin_list | List users of the current domain having administration privileges and matching the specified glob pattern, for example, admin_list pattern. |
auth_add | Add a password account for the specified authentication identifier with the specified password. The authentication identifier authid is the exact string used as a login name. If both the configuration option admin-append-domain-auth is enabled and the currently set administrative domain does not match the default-domain configuration option, the current administrative domain is appended to the authentication identifier making it authid@domain. |
auth_del | Delete the password account for user authid. If both the configuration option admin-append-domain-auth is enabled and the currently set administrative domain does not match the default-domain configuration option, the current administrative domain is appended to the authentication identifier making it authid@domain. |
auth_disable | Disable the password account so that the user authid is denied authentication with the stored password. If both the configuration option admin-append-domain-auth is enabled and the currently set administrative domain does not match the default-domain configuration option, the current administrative domain is appended to the authentication identifier making it authid@domain. |
auth_enable | Enable the password account so that the user authid may be authenticated with the stored password. All the passwords accounts created with auth_add are enabled by default. If both the configuration option admin-append-domain-auth is enabled and the currently set administrative domain does not match the default-domain configuration option, the current administrative domain is appended to the authentication identifier making it authid@domain. |
auth_get | Display the password account details for user authid. The output consists of three fields: authentication identifier: Fully qualified login name. password expiration date: If zero (0), the password never expires, otherwise the expiration date is expressed in the form YYYYMMDDHHNNSS, where YYYY is the year, MM is the month, DD is the day, HH is the hour, NN are the minutes, and SS are the seconds. account enabled flag: 1 if enabled, 0 if disabled If both the configuration option admin-append-domain-auth is enabled and the currently set administrative domain does not match the default-domain configuration option, the current administrative domain is appended to the authentication identifier making it authid@domain. |
auth_list | List password accounts matching the specified glob pattern, for example, auth_list pattern. |
auth_mod | Modify the password account for the user authid. Currently, this is limited to setting the expiration-date after which the user's password expires. By default, passwords created with auth_add or changed with passwd never expire. If the expiration-date is zero (0), the password never expires, otherwise the date is expressed in the form YYYYMMDDHHNNSS, where YYYY is the year, MM is the month, DD is the day, HH is the hour, NN are the minutes, and SS are the seconds, for example, auth_mod authid expiration-date. |
auth_passwd | Set the password stored in the password account for user authid to password. If both the configuration option admin-append-domain-auth is enabled and the currently set administrative domain does not match the default-domain configuration option, the current administrative domain is appended to the authentication identifier making it authid@domain. |
auth_rename | Rename the password account for user oldauthid to newauthid. If both the configuration option admin-append-domain-auth is enabled and the currently set administrative domain does not match the default-domain configuration option, the current administrative domain is appended to the authentication identifier making it authid@domain. |
user_add | Create the user account for the specified user, for example, user_add user. |
user_del | Delete user account for the specified user, for example, user_del user. |
user_list | List all user accounts for usernames matching the glob pattern pattern, for example, user_list pattern. |
user_rename | Rename the user account for user oldname to newname, for example, user_rename oldname newname. |
The following example is a typical session to create the traditional login jworker for user joe.worker@example.com in a multi-domain setting. It is assumed that the ms.conf configuration option admin-append-domain-auth is disabled to prevent appending the domain name on authentication account creation.
domain_set example.com mbox_user_add joe.worker auth_add jworker iMc001 auth_alias_add jworker joe@example.com quit |
 | Note: When creating the user account and mailboxes for joe.worker@example.com , create the authentication account jworker instead of joe.worker@example.com. We create the mapping so that Joe may authenticate as jworker and access his normal joe.worker@example.com account. |
M-Store provides the ability to explicitly map an authentication account to a particular authorization account. This allows a user to authenticate with a given identifier (authid) and also be authorized with a different identifier (userid).
This is used to provide users with the ability to authenticate using a traditional name such as joe in a multi-domain setting, where Joe's account is actually joe@example.com. Another use is to provide a friendly authentication alias such as joe.user, where Joe's authentication ID is actually his employee number.
Table 12-6. msadm_tclsh Account Mapping (alias) Commands
Command | Description |
|---|---|
auth_alias_add | Add a mapping from the fully-qualified authentication identifier authid to the authorization identifier userid. If the userid is not of the form user@domain, then the userid is assumed to be of the default-domain, for example, auth_alias_add authid alias. |
auth_alias_del | Remove the mapping for the fully-qualified authentication identifier, for example, auth_alias_del authid. |
auth_alias_mod | Change the mapping for the fully-qualified authentication identifier authid to point to the authorization identifier newuserid. If newuserid is not of the form user@domain, then it is assumed to be of the default-domain. |
auth_alias_list | List mapping entries matching the specified glob pattern, for example, auth_alias_list pattern. |
The following commands are used to manage user mailboxes. They may only be used after defining the current administative domain with the domain_set command.
Table 12-7. User Mailbox Management Commands
Command | Description & Example |
|---|---|
acl_user_del | Remove the rights acl for user identifier on the mailbox belonging to user, for example, acl_user_del user mailbox identifier acl. |
acl_user_get | Display the access control list for mailbox belonging to user, for example, acl_user_get user mailbox. |
acl_user_set | Add the rights acl for user identifier on mailbox belonging to user, for example, acl_user_set mailbox identifier acl. |
mbox_get_user_path | Display the path to the mailbox belonging to user, for example, mbox_get_user_path user mailbox. |
mbox_user_add | Create a user account and inbox for the specified user, for example, mbox_user_add user. |
mbox_user_del | Delete the specified user account and all associated mailboxes, for example, mbox_user_del user. |
mbox_user_list | List all the mailboxes of the domain that match the specified glob pattern, for example, mbox_user_list pattern. |
mbox_user_rename | Rename the oldusername to newusername and each of the associated mailboxes, for example, mbox_user_rename oldusername newusername. |
mbox_user_to_shared | Convert the mailbox belonging to user to a shared mailbox, for example, mbox_user_to_shared user sharedname Thus mbox_user_to_shared joe graphics would convert user/joe/INBOX user/joe/company_logos user/joe/company_logos/jpeg to shared/graphics/ shared/graphics/company_logos shared/graphics/company_logos/jpeg |
mbox_usersub_add | Create the sub-folder mailbox for user, for example, mbox_usersub_add user mailbox. |
mbox_usersub_del | Delete the sub-folder mailbox for user, for example, mbox_usersub_del user mailbox. |
mbox_usersub_rename | Rename the sub-folder oldboxname to newmboxname, for example, mbox_usersub_rename user oldmboxname newmboxname. |
quota_user_del | Remove the quota on a specified user, for example, quota_user_del user. |
quota_user_get | Display the current quota limit and usage for the specified user, for example, quota_user_get user. |
quota_user_set | Set a quota limit of quota kilobytes for user. The quota applies to all subfolders, for example, quota_user_set user quota. |
The following commands are used to manage shared mailboxes. They may only be used after defining the current administrative domain with the domain_set command.
Table 12-8. User Mailbox Management Commands
Command | Description & Example |
|---|---|
acl_shared_del | Remove the rights acl for user identifier on the shared mailbox, for example, acl_shared_del mailbox identifier acl. |
acl_shared_get | Display the access control list for the specified shared mailbox, for example, acl_shared_get mailbox. |
acl_shared_set | Add the rights acl for user identifier on the shared mailbox, for example, acl_shared_set mailbox identifier acl. |
mbox_get_shared_path | Display the path to the specified mailbox, for example, mbox_get_shared_path mailbox. |
mbox_shared_add | Create the shared mailbox mailbox owned by owner. The owner is not required if creating a sub-folder of an already owned folder, for example, mbox_shared_add mailbox owner. |
mbox_shared_del | Delete the specified shared mailbox, for example, mbox_shared_del mailbox. |
mbox_shared_list | List all shared mailboxes matching the specified glob pattern, for example, mbox_shared_list pattern. |
mbox_shared_rename | Rename the shared mailbox oldname to newname, for example, mbox_shared_rename oldname newname. |
quota_shared_del | Remove the quota on the specified shared mailbox, for example, quota_shared_del mailbox. |
quota_shared_get | Display the current quota limit and usage for the specified shared mailbox, for example, quota_user_get mailbox. |
quota_shared_set | Set a quota limit of quota kilobytes for shared mailbox. The quota applies to all subfolders, for example, quota_shared_set mailbox quota. |
The following example adds a new site administrator, where example.mail2.com is set as the Site Administrator domain.
domain_set example.mail2.com user_add bobadmin site_admin_add bobadmin auth_add bobadmin passwd |
The following example creates a domain and first user, where the domain example.com and the user joe@example.com with the password IamJoe!4 are created.
domain_add example.com domain_set example.com mbox_user_add joe auth add joe IamJoe!4 mbox_usersub_add joe Sentmail mbox_usersub_add Important mbox_usersub_add joe Important/fun mbox_usersub_add joe Important/work quit |
This example also creates the following folders within the example.com domain:
user/joe/INBOX user/joe/Sentmail user/joe/Important user/joe/Important/fun user/joe/Important/work quit |
The address joe@example.com is now deliverable and user joe can log on and check his mail.
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msadm_bulkadd, “ Add Users in Bulk to M-Store (msadm_bulkadd)”
msadm_bulkdel, “Delete Multiple Domains and Users (msadm_bulkdel)”
This section details the included tools designed to allow for the batch (bulk) administration of M-Store.
msadm_bulkadd [-iO] [-f config_file] [-d domain] [-q quota] |
msadm_bulkadd reads user information from the given data file and creates an account for each user.
It is highly recommended that msdb_backup be run after bulk adding users to safeguard new data and to clean the database transaction logs. If the transaction logs are not cleaned, there may be very long waits when running database recovery (as is usually done at boot time through the rc.mdstore boot script). At the very least, remove the unused transaction logs with msdb_archive.
Table 12-9. msadm_bulkadd Options
Option | Description |
|---|---|
-d domain | Specify a non-default domain in which the accounts are created. It is not necessary to use the -d flag in single-domain mode. |
-f config file | Specify an non-default location for the M-Store configuration file. |
-n | Do not create a mailbox for the user. The user's inbox is created by default. |
-O | All command line options are used to override the fields in the given data files. |
-q | Specify a default quota in kilobytes for all accounts we create. A quota of 0 signifies that no quota is to be assigned. |
-v | Display the datafile lines as interpreted. |
If -O is not given, command line option values are used only if the corresponding field is not present in the data files.
If -d is not given, then the domain specified in the configuration as default-domain is assumed.
msadm_bulkadd assumes the data files contain lines of the form:
<domain>:<user>:<passwd>:<quota>:<inbox>:\n |
where:
<domain> | is the domain. |
<user> | is the username. |
<passwd> | is the user's password. |
<quota> | is the user's assigned quota in kilobytes. |
<inbox> | is a flag with values '1' for creating the inbox, '0' for no inbox. |
If a field value is not specified, then the default given on the command line is used. If a specified domain does not exist, it will be created. Lines of the form <domain>:::<quota>:\n will create the specified quota. If the <quota> field is empty, no quota will be assigned (unless defaulted by the -q flag). If a specified domain does not exist it will be created.
If the configuration option admin-append-domain-auth is enabled and the domain does not match the default-domain configuration option, then the authentication account is of the form user@domain. Otherwise the authentication account is just user.
Add the users in the given data file. All users not specified with a domain will be added to the default-domain as specified in the configuration file.
msadm_bulkadd data |
Add the users given in the data file. All users not specified with a domain are assumed to be of the domain example.com. All users not specified with a quota are assigned a quota of two megabytes.
msadm_bulkadd -d example.com -q 2000 data |
Add the users given in the data file. All users (with or without a specified domain) are assumed to be of the domain example.com. All users (with or without a specified quota) are assigned a quota of two megabytes.
msadm_bulkadd -O -d example.com -q 2000 data |
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msadm_bulkdel, “Delete Multiple Domains and Users (msadm_bulkdel)”
msadm_tclsh, “IM-Store Administration Command Interpreter (msadm_tclsh)”
msdb_backup,“Database Backup Tool (msdb_backup)”
msdb_recover, “Database Recovery Tool (msdb_recover)”
rc.m-store, “M-Store rc.m-store Script” in Chapter 10
msadm_bulkdel [-f config_file] datafile |
msadm_bulkdel reads user information from a given data file and deletes account and messages for each user (or domain). User and domain deletion is permanent and cannot be reversed; please use with care.
It is highly recommended that msdb_backup be run after bulk deleting users to safeguard new data and to clean the database transaction logs. If the transaction logs are not cleaned, there may be very long waits when running database recovery (as is usually done at boot time through the rc.mdstore boot script). At the very least, remove the unused transaction log files with msdb_archive.
Table 12-10. msadm_bulkdel Options
Option | Description |
|---|---|
-f config_file | Specify a non-default location for the M-Store configuration. |
msadm_bulkdel assumes the data files contain lines of the form:
<user>@<domain> |
If the <user> field is empty, the entire domain will be deleted.
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msadm_bulkdel, “Delete Multiple Domains and Users (msadm_bulkdel)”
msadm_tclsh, “IM-Store Administration Command Interpreter (msadm_tclsh)”
msdb_backup, “Database Backup Tool (msdb_backup)”
msdb_recover, “Database Recovery Tool (msdb_recover)”
rc.m-store, “M-Store rc.m-store Script” in Chapter 10
These tools are for the various database activities required to ensure the reliable operation of M-Store.
msdb_archive [-alsv] [-f config] |
msdb_archive writes the pathnames of the log files that are no longer involved in active transactions. These logs, and the tables, may then be copied to backup media in case of corruption or system failures. The log files may be deleted after they are backed up to reclaim disk space. msdb_archive must be invoked as the superuser or the runtime-user as defined in the configuration file.
The msdb_archive utility attaches to one or more of the Berkeley DB shared memory regions. In order to avoid region corruption, it should always be given the chance to detach and exit gracefully. To cause msdb_archive to clean up after itself and exit, send it an interrupt signal (SIGINT).
The proper procedure for archiving the database is given in msdb_backup. msdb_archive exits 0 on success, and >0 if an error occurs
Table 12-11. msdb_archive Options
Option | Descriptions |
|---|---|
-a | Write pathnames as absolute pathnames instead of relative to the database home. |
-f config | Specify the path of an alternative M-Store configuration file. |
-l | Write the pathnames of all database log files, whether or not they are involved in active transactions. |
-s | Write the pathnames of all database files that need to be archived in order to recover the database from catastrophic failure. If any of the database files have not been accessed during the lifetime of the current log files, msdb_archive will not include them in the output. |
-v | Run in verbose mode, listing the checkpoints in the log files as they are reviewed. |
List the absolute pathname of all of files not involved in active transactions. These may be deleted to reclaim disk space.
msdb_archive -a |
List all of the log files for archive purposes.
msdb_archive -l |
Verbosely list all the log files not involved in active transactions.
msdb_archive -v |
/etc/md/store/ms.conf | The default M-Store configuration file. |
ms-path /database | The default database home, where ms-path is defined in the ms.conf file. |
ms-path defaults to /var/md/store |
|
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msdb_backup, “Database Backup Tool (msdb_backup)”
msdb_checkpoint, “Database Checkpoint Tool (msdb_checkpoint)”
msdb_recover, “Database Recovery Tool (msdb_recover)”
msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)”
msdb_backup |
msdb_backup provides a sample shell script that may be used to create live backups of the M-Store database. msdb_restore may be used to restore this backup in the event of a catastrophic failure.
msdb_backup will make a backup of the current database tables and logs in a subdirectory of /var/md/store/backup named by date and time. The default directory structure of a backup is:
Table 12-12. Default Directory Structure of a Backup
Path | File Name |
|---|---|
/var/md/store/backup/MSDB_Backup_<timestamp > | <table>.db |
| log.<log_number> |
Upon successful termination, the directory should be moved to backup media for archival purposes.
The msdb_backup script is only a sample backup script that can be used as a base for administrators to write their own customized backup scripts. A successful backup must include the following sequence of events:
1. | Force a checkpoint with msdb_checkpoint (recommended for non-live backups; this will not affect live backups). |
2. | Backup all database table files. |
3. | Use msdb_archive to determine which log files need to be backed up. |
4. | Backup the required log files. |
msdb_backup defines a number of paths in the PUBLIC DEPENDENCIES section of the script which may need to be changed to reflect any changes made from the default M-Store installation. The ms.conf file will contain any changed values.
After copying the transaction log files, msdb_backup deletes those that are not involved in active transactions.
/etc/md/store/ms.conf | The default M-Store configuration file. |
/var/md/store/backup | The default M-Store database backup directory. |
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msdb_archive, “Database Archive Tool (msdb_archive)”
msdb_checkpoint, “Database Checkpoint Tool (msdb_checkpoint)”
msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)”
msdb_checkpoint [-1dv] [-f config] [-k kbytes] [-p min] |
msdb_checkpoint monitors the message store database transaction logs and periodically checkpoints them. msdb_checkpoint may also be invoked as a daemon process. msdb_checkpoint must be invoked as the superuser or the runtime-user as defined in the configuration file. msdb_checkpoint is normally invoked from the storemgr daemon process as part of the set of managed server processes that make up a running message store. All stop and restart operations for msdb_checkpoint should be performed using the rc.m-store boot script.
msdb_checkpoint attaches to one or more of the message store database shared memory regions. In order to avoid region corruption, it should always be given the chance to detach and exit gracefully.
If msdb_checkpoint was invoked by storemgr, then the server cannot be independently shut down, as storemgr will automatically restart it. To shut down msdb_checkpoint , you must use the rc.m-store boot script.
msdb_checkpoint does not attempt to create the message store database shared memory regions if they do not already exist. msdb_test is used to create the region first, and then msdb_checkpoint is started.
msdb_checkpoint exits 0 on success, and >0 if an error occurs.
At least one of the -1, -k, and -p options must be specified. Both -1 and -d cannot be specified together.
Table 12-13. msdb_checkpoint Options
Option | Description |
|---|---|
-1 | Checkpoint the log once and exit. |
-d | Run as a daemon process, logging all output to the syslogd LOG_MAIL facility. |
-f config | Specify the path of an alternative message store configuration file. |
-k Kbytes | Checkpoint the database at least as often as every Kbytes of log file are written. |
-p min | Checkpoint the database at least every min minutes. |
-v | Write the time of each checkpoint to the standard output or syslog. |
msdb_checkpoint stores its process ID in the file ms-path/run/msdb_checkpoint.lock, where the ms-path variable is defined in the M-Store configuration file. Sending signals to that process ID will allow you to control various runtime functions in the server.
SIGTERM - If msdb_checkpoint was run standalone, sending SIGTERM to the server will stop it. If msdb_checkpoint was invoked by storemgr then sending SIGTERM will cause storemgr to restart it.
Checkpoint the log once and exit. Mostly used before archiving the database.
msdb_checkpoint -1 |
Run as daemon process and checkpoint the log at least as often as every four kilobytes of log file are written.
msdb_checkpoint -d -k 4 |
Run as a daemon process and checkpoint the log at least every hour. The time of the checkpoint will appear in the syslog output.
msdb_checkpoint -dv -p 60 |
/etc/md/store/ms.conf | The default M-Store configuration file. |
ms-path /database | The default database home, where ms-path is defined in the ms.conf file. |
ms-path /run/msdb_checkpoint.lock | The lock file containing the process ID of the running msdb_checkpoint process. |
defaults to ms-path /var/md/store |
|
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msdb_test, “Database Test Tool (msdb_test)”
rc.m-store, “M-Store rc.m-store Script” in Chapter 10
storemgr, “Store Manager (stormgr)” in Chapter 10
msdb_recover [-cv] [-f config] |
msdb_recover must be executed after an unexpected application, database, or system failure to restore the database to a consistent state. All committed transactions are guaranteed to appear after msdb_recover has run, and all uncommitted transactions will be completely undone. msdb_recover must be invoked as the superuser or the runtime-user as defined in the configuration file.
In the case of catastrophic failure, an archival copy or snapshot of all database files must be restored along with all of the log files written since the database file snapshot was made. (If disk space is a problem, log files may be referenced by symbolic links). For further information on creating a database snapshot, see “Database Backup Tool (msdb_backup)”. For further information on performing a recovery, see “Database Recovery Tool (msdb_recover)”.
msdb_recover exits 0 on success, and >0 if an error occurs.
If the failure was not catastrophic, the files present on the system at the time of failure are sufficient to perform recovery.
If log files are missing, msdb_recover will identify the missing log file(s) and exit on fail, in which case, the missing log files need to be restored and recovery performed again.
The msdb_recover utility attaches to one or more of the Berkeley DB shared memory regions. In order to avoid region corruption, it should always be given the chance to detach and exit gracefully. To cause msdb_recover to clean up after itself and exit, send it an interrupt signal (SIGINT).
If there are many existing transaction log files, msdb_recover may take a great deal of time to execute. This may give the appearance of being hung-up, even though it is continuing to function properly. This is common after doing bulk additions or deletions of users. msdb_archive may be used to list log files that may backed up and deleted.
Rarely, the transaction logs may become corrupted and cause all applications to hang at startup, and msdb_recover crashes due to a segfault. This is a database bug. The work-around is to delete all transaction log files and run msdb_test. Never attempt to do so on a live system.
Table 12-14. msdb_recover Options
Option | Description |
|---|---|
-c | Failure was catastrophic. |
-f config | Specify the path of an alternative message store configuration file. |
-v | Run in verbose mode. |
Verbosely recover the database. This is performed at startup by the rc.m-store boot script to ensure the consistency of the database before starting imapd or any other M-Store applications. The command is equivalent to msdb_test -r.
msdb_recover -v |
Verbosely recover the database after a catastrophic failure and subsequent restoration of the database. This is performed by msdb_restore as the final step in restoring a previously archived database.
msdb_recover -c |
/etc/md/store/ms.conf | The default M-Store configuration file. |
ms-path /database | The default database home, where ms-path is defined in the ms.conf file. |
ms-path defaults to /var/md/store on all systems. |
|
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msdb_archive, “Database Archive Tool (msdb_archive)”
msdb_backup, “Database Backup Tool (msdb_backup)”
msdb_checkpoint, “Database Checkpoint Tool (msdb_checkpoint)”
msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)”
msdb_test, “Database Test Tool (msdb_test)”
msdb_restore backup_path |
msdb_restore provides a sample shell script that can be used to restore backups of M-Store's database that were created with msdb_backup.
msdb_restore takes a single argument backup_path which must refer to the directory containing the archived database tables and transaction logs.
msdb_restore is only a sample backup script that can be used as a base for administrators to write their own customized backup restore scripts. The minimum sequence of events for restores is:
1. | Cleanly shutdown all M-Store database related applications. This may entail any or all of the following: an imapd/pop3d shutdown file, ensuring no administration tools are currently running, and stopping the rc.mdstore script. |
2. | Empty, or backup, the M-Store transaction_log and data directories. |
3. | Copy all archived data files (*.db) into the data directory. Copy all archived log files (log.*) into the transaction_log directory. |
4. | msdb_recover -c to finish restoring the database. |
Any existing database directories are renamed to:
<dirname>.asof<today's date>. |
msdb_restore defines a number of paths in the PUBLIC DEPENDENCIES section of the script which may need to be changed to reflect any changes made from the default M-Store installation. The ms.conf file will contain any changed values.
/etc/md/store/ms.conf | The default M-Store configuration file. |
/var/md/store/database/data | The default M-Store database data directory. |
/var/md/store/database/transaction_log | The default M-Store database log directory. |
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msdb_archive, “Database Archive Tool (msdb_archive)”
msdb_recover, “Database Recovery Tool (msdb_recover)”
msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)”
msdb_test [-rv] [-f config] |
msdb_test tests the message store database by quickly opening and closing the database tables, recovering any files if necessary. Any errors are written to standard error. msdb_test must be invoked as the superuser or the runtime-user (e.g., sms) as defined in the configuration file.
Certain deadlock conditions may cause msdb_test to hang while opening the database. In such cases, terminate msdb_test with ctrl-c and rerun msdb_test with the -r flag.
msdb_test exits 0 on success, and 1 if an error occurs
msdb_test will not run if any database files are missing, in such a case a backup containing all database files must be restored.
Table 12-15. msdb_test Options
Option | Description |
|---|---|
-f config | Specify the path of an alternative message store configuration file. |
-r | Recover the database before testing. This should be used if starting M-Store from a boot script to cleanup the database in case it was not cleanly shutdown. This flag is equivalent to executing msdb_recover and is only be given by the M-Store runtime user. Please see msdb_recover, “Database Recovery Tool (msdb_recover)” , for possible risks associated with this flag. |
-v | Verbosely display the state of the database upon exiting. |
Test the database and display a message regarding its state. If there are any problems with the database they will be echoed to standard error.
msdb_test -v |
Verbosely test the database. This is performed at startup by the rc.m-store boot script to ensure the consistency of the database before starting imapd or any other M-Store applications. This command is equivalent to msdb_recover -v.
msdb_test -r |
Verbosely test the database and check for any deadlocks.
msdb_test -lv |
/etc/md/store/ms.conf | The default M-Store configuration file. |
ms-path /database/ | Default database home, where ms-path is defined in the ms.conf file. |
ms-path defaults to /var/md/store |
|
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msdb_recover, “Database Recovery Tool (msdb_recover)”
rc.m-store, “M-Store rc.m-store Script” in Chapter 10
reconstruct -r esys.ca “user/foobar” |
reconstruct rebuilds one or more IMAP message store mailbox cache files within a given domain. It can be used to recover from almost any sort of data corruption. Since reconstruct can create new cache files it can be run as the M-Store runtime user.
When reconstruct finds existing header and index files, it attempts to preserve any data in them that is not derivable from the message files themselves. The state that reconstruct attempts to preserve includes: the flag name, flag state, and internal date. reconstruct derives all other information from the message files.
The mailbox arguments must be fully qualified IMAP mailbox names and may need to be quoted on the command line if the name contains shell-specific characters.
Table 12-16. reconstruct Options
Option | Description |
|---|---|
-f config_file | Specify an alternate location for M-Store's configuration file. |
-r | Recursively reconstruct all sub-mailboxes of the mailboxes or mailbox-prefixes given as arguments. If no mailbox arguments are given, all mailboxes within the specified domain will be reconstructed. |
-u | Reconstruct a specific user's mailbox or mailboxes. |
-v | Display program version information on standard error, then exit. |
reconstruct -r esys.ca “user/foobar” |
This command recursively reconstructs all cache files for the personal hierarchy of user foobar@esys.ca
Table 12-17. reconstruct Examples
Description | |
|---|---|
reconstruct -r example.com | Reconstruct all mailboxes in the example.com domain. |
reconstruct -r -u joe example.com | Reconstruct all of joe@example.com's mailboxes. |
reconstruct -u joe example.com INBOX | Reconstruct only joe@example.com's mailbox. |
reconstruct -r -u joe example.com pub | Reconstruct joe@example.com's pub folder and all sub-folders. |
reconstruct foo.com admin | Reconstruct the shared folder admin in the foo.com domain. |
reconstruct -r example.com admin | Reconstruct the shared folder admin and all sub-folders in the example.com domain. |
msdb_upgrade [-f config] |
msdb_upgrade creates a new message store database or upgrades an existing database to the current revision. All files must be present for the upgrade. File locations are determined from the configuration file. Any errors are written to standard error.
msdb_upgrade must be executed before using the message store for the first time. By default, all the necessary store databases are created during installation. msdb_upgrade must be invoked as the superuser or the runtime-user as defined in the configuration file.
msdb_upgrade will not run if any database files are missing, In such a case, a backup containing all database files must be restored. msdb_upgrade must not be run at the same time as any other M-Store process that accesses the database. msdb_upgrade exits 0 on success and 1 if an error occurs.
Table 12-18. msdb_upgrade Options
Option | Description |
|---|---|
-f config | Specify the path of an alternative message store configuration file. |