Log in as the superuser to start and stop M-Store. The command path varies slightly by platform. Refer to Chapter 12, “Administration Commands” for specific details regarding the location and usage of the rc.m-store script on specific platforms.
The following is an outline of the tools necessary to administer the M-Store database. This section is organized into specific duties and the files needed to perform these duties.
msdb_test quickly opens and closes the message store database, creating or recovering any files if necessary. Any errors are written to standard error. msdb_test must be invoked as the superuser or the runtime-user (that is, sms) as defined in the configuration file.
Certain deadlock conditions may cause msdb_test to hang while opening the databases. 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.
Option | Description |
|---|---|
-f config | Specify the path of an alternative message store configuration file. |
-l | Test for deadlocks after opening the database. |
-r | Recover the databases before testing. This should be used if starting M-Store from a boot script to clean up the database in case it was not cleanly shut down. 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)” in Chapter 12 , for possible risks associated with this flag. |
-v | Verbosely display the state of the database upon exiting. |
msdb_test -v
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 -r
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 -lv
Verbosely test the database and check for any deadlocks.
It is strongly recommended that backups be performed on a regular basis. While M-Store has the ability to recover its mailstore from a system fault, all pending transactions (new accounts, mailboxes, etc.) will be lost. The physical mail will not be directly affected by a database crash.
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 3-2. 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:
Force a checkpoint with msdb_checkpoint (recommended for non-live backups; this will not affect live backups).
Backup all database table files.
Use msdb_archive to determine which log files need to be backed up.
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)” in Chapter 12
msdb_checkpoint, “Database Checkpoint Tool (msdb_checkpoint)” in Chapter 12
msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)” in Chapter 12
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 restore 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 are:
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.
Empty, or backup, the M-Store transaction_log and data directories.
Copy all archived data files (*.db) into the data directory. Copy all archived log files (log.*) into the transaction_log directory.
Enter msdb_recover -c to finish restoring the database.
Any existing database directories are renamed to:
dirname.asoftoday'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.
msdb_recover -v
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 -c
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.
/etc/md/store/ms.conf | The default configuration file. |
/var/md/store/database/data | The default database data directory. |
/var/md/store/database/transaction_log | The default database log directory. |
ms.conf, “Message Store Configuration (ms.conf)” in Chapter 10
msdb_archive, “Database Archive Tool (msdb_archive)” in Chapter 12
msdb_checkpoint, “Database Checkpoint Tool (msdb_checkpoint)” in Chapter 12
msdb_recover, “Database Recovery Tool (msdb_recover)” in Chapter 12
msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)” in Chapter 12
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 msdb_backup, “Database Backup Tool (msdb_backup)” in Chapter 12. For further information on performing a recovery, see msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)” in Chapter 12.
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 3-3. 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. |
/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_archive, “Database Archive Tool (msdb_archive)” in Chapter 12
msdb_backup,“Database Backup Tool (msdb_backup)” in Chapter 12
msdb_checkpoint, “Database Checkpoint Tool (msdb_checkpoint)” in Chapter 12
msdb_restore, “Database Restore-From-Backup Tool (msdb_restore)” in Chapter 12