75 Message Store Command Reference
This chapter describes the Oracle Communications Messaging Server Message Store command reference.
configutil
The configutil utility enables you to list and change Messaging Server configuration options.
For a list of all configuration options, see the Messaging Server Reference.
All Messaging Server configuration options and values are stored locally in the msg.conf and msg.conf.defaults files. The msg.conf.defaults file must never be edited and contains defaults constructed during initial configuration. The msg.conf file contains settings that have been explicitly overridden from their default value using configutil. Use the -H option to configutil to view a setting's default value.Use configutil to edit configutil settings; do not edit these files directly.
Note:
If the administrator has defined any language-specific options (such as messages), you must use the language option at the end of the command in order to list or change them. Commands entered without a language option are only applied to attributes that do not have a specified language option.Requirements: Must be run locally on the Messaging Server. You may run configutil as root or mailsrv. If you make changes to the servers, you must restart or refresh the servers, depending on the variable, for the changes to take effect.
Location: MessagingServer_home/bin/configutil
You can use configutil to perform four tasks:
-
Display particular configuration options using -o option.
Add ;lang-xx after the option to list options with a specified language option. For example, ;lang-jp to list options specified for the Japanese language.
-
List configuration option values using the -p pattern option. (Can be used with the -m option.)
Use -p pattern to just list those configuration options whose names contain the pattern specified in pattern. * is the wildcard character and is assumed to follow pattern if there is no wildcard already in pattern.
Use -m to show whether or not the listed options are refreshable.
-
Set configuration options using the -o option and -v value options.
Add ;lang-xx after the option to set options for a specified language option. For example, ;lang-jp to set options specified for the Japanese language.
-
Import configuration option values from stdin using the -i option.
Include the -H option to show settings with help.
Examples:
configutil -H Configuration option: alarm.diskavail.msgalarmdescription Description: Description for the diskavail alarm. Syntax: string Default: percentage mail partition diskspace available alarm.diskavail.msgalarmdescription is currently set to: percentage mail partition diskspace available Configuration option: alarm.diskavail.msgalarmstatinterval Description: Interval in seconds between disk availability checks. Set to 0 to disable checks of disk usage. Syntax: int Default: 3600 alarm.diskavail.msgalarmstatinterval is currently set to: 3600 [.....] ### Show help on all configuration parameters ending in ".port" configutil -p \*.port -H Configuration option: local.ens.port Description: Port (and optionally, a specific IP address) ENS server will listen on, in the format of [address:]port, for example, 7997 or 192.168.1.1:7997. Syntax: string Default: 7997 local.ens.port is currently set to: 7997 Configuration option: local.service.http.proxy.port Description: Configures the port number of the back-end Messenger Express (HTTP) server with the Messaging Multiplexor. Syntax: uint Default: 80 local.service.http.proxy.port is currently set to: 80 Configuration option: local.snmp.port Description: SNMP subagent port number. Syntax: uint Default: 0 local.snmp.port is currently set to: 0 Configuration option: local.watcher.port Description: watcher listen port. Syntax: uint Default: 49994 local.watcher.port is currently set to: 49994 Configuration option: local.webmail.cert.port Description: Specifies a port number on the machine where the Messaging Server runs to use for CRL communication. This port is used locally for that machine only. The value must be greater than 1024. Syntax: int Default: 55443 local.webmail.cert.port is currently set to: 55443 Configuration option: local.webmail.da.port Description: Delegated Administrator port. Syntax: int Default: 8080 local.webmail.da.port is currently set to: 8080 Configuration option: local.webmail.sieve.port Description: The port of the web container where the Mail Filter has been deployed. Syntax: string Default: NULL (unset) local.webmail.sieve.port is currently unset Configuration option: metermaid.config.port Description: Port number on which MeterMaid listens for connections. Syntax: tcpport Default: 63837 metermaid.config.port is currently set to: 63837 Configuration option: service.http.port Description: Messenger Express HTTP port. Flags: MSG_RESTART_HTTP Syntax: uint Default: 80 service.http.port is currently set to: 81 Configuration option: service.imap.port Description: IMAP server port number. Flags: MSG_RESTART_IMAP Syntax: uint Default: 143 service.imap.port is currently set to: 143 Configuration option: service.pop.port Description: POP server port number. Flags: MSG_RESTART_POP Syntax: uint Default: 110 service.pop.port is currently set to: 110 ### Show help on store.partition.\*.path configutil -p store.partition.\*.path -H Configuration option: store.partition.*.path Description: Controls the store index file directory path. Flags: MSG_RESTART_ALL Syntax: filepath Default: NULL (unset) store.partition.primary.path is currently set to: /opt/SUNWmsgsr/data/store/partition/primary store.partition.three.path is currently set to: /opt/SUNWmsgsr/data/store/partition/three store.partition.two.path is currently set to: /opt/SUNWmsgsr/data/store/partition/two Configuration option: store.partition.primary.path Description: Full path name of the primary partition. Flags: MSG_RESTART_ALL Syntax: filepath Default: <msg.RootPath>/data/store/partition/primary store.partition.primary.path is currently set to: /opt/SUNWmsgsr/data/store/partition/primary
configutil [-h] [-f <configfile>] [-o <option>[;<language>] [-v <value>] configutil [-f <configfile>] [-p <pattern>] [-H] [-m] [-V] configutil -i <inputfile>
The options for this command are:
| Option | Description |
|---|---|
|
-d |
Enables you to delete an option. Used with the -o option. |
|
-f configfile |
Enables you to specify a local configuration file other than the default. (This option uses information stored in the ConfigRoot environment variable by default.) |
|
-h |
Shows usage statement. |
|
-H |
Enables you to get help on options. Used with the -o option. |
|
-i inputfile |
Imports configurations from a file. Data in the file to be entered in option=value format with no spaces on either side of the pipe. The inputfile should be specified as an absolute path. |
|
-m |
Lists meta data. |
|
-o option |
Specifies the name of the configuration option that you wish to view or modify. May be used with the -H, -v, -d options. Configuration option names starting with the word local are stored in the local server configuration file. |
|
-p pattern |
Lists only options with the given pattern (* is wildcard). Example: configutil - p *enable -H. If no wildcard is present in the pattern, a wildcard at the end of the pattern will be assumed (effectively changing pattern to pattern*). |
|
-v value |
Specifies a value for a configuration option. To be used with -o option. |
|
-V |
Enables you to validate the configuration against meta data. |
If you specify no command-line options, all configuration options are listed.
To list all configuration options and their values in both the Directory Server LDAP database and local server configuration file:
configutil
To import configurations from an input file named config.cfg:
configutil -i config.cfg
To list all configuration options with the prefix service.imap:
configutil -p service.imap
To display the value of the service.smtp.port configuration option:
configutil -o service.smtp.port
To set the value of the service.smtp.port configuration option to 25:
configutil -o service.smtp.port -v 25
To clear the value for the service.imap.banner configuration option:
configutil -o service.imap.banner -v ""
To display the refreshable status of the service.pop configuration options:
configutil -m -p service.pop
This example of the -m option could produce the following sample output:
service.pop.allowanonymouslogin = no [REFRESHABLE] service.pop.banner = "%h %p service (%P %V)" [REFRESHABLE] service.pop.createtimestamp = 20030315011827Z [REFRESHABLE] service.pop.creatorsname = "cn=directory manager" [REFRESHABLE] service.pop.enable = yes [NOT REFRESHABLE] service.pop.enablesslport = no [NOT REFRESHABLE] service.pop.idletimeout = 10 [REFRESHABLE] service.pop.maxsessions = 600 [NOT REFRESHABLE] service.pop.maxthreads = 250 [NOT REFRESHABLE]
To list or set options for a specific language, append ;lang-xx immediately after the option with no spaces, where xx is the two-letter language identifier. For example, to view the text of the Japanese version of the store.quotaexceededmsg message:
configutil -o "store.quotaexceededmsg;lang-jp"
The semicolon is a special character for most UNIX shells and requires special quoting as shown in the example.
counterutil
The counterutil utility displays and changes counters in a counter object. It can also be used to monitor a counter object at fixed intervals. For more information and examples see "Gathering Message Store Counter Statistics by Using counterutil."
Requirements: Must be run locally on the Messaging Server.
Location: MessagingServer_home/bin/
counterutil -l counterutil -o _counterobject_ [-i _interval_] [-n _numiterations_] counterutil -s -o _counterobject_ -c _counter_
The options for this command are:
Table 75-2 counterutil Options
| Option | Description |
|---|---|
|
-c counter |
Specifies a particular counter associated with a counter object. |
|
-i interval |
Specifies, in seconds, the interval between reports. The default is 5. |
|
-l |
Lists the content of the counter registry. |
|
-n numiterations |
Specifies the number of iterations. The default is infinity. |
|
-o counterobject |
Displays the contents of a particular counter object at specified intervals (by default, every 5 seconds). The valid counter objects are:imapstat, popstat, httpstat, alarm, diskusage, serverresponse, mmpstat. Each counter object has a list of counters. When you monitor a counter object, counterutil displays the counters associated with it. |
|
-s |
Resets the counter to 0. |
To list all counter objects in a given server's counter registry:
counterutil -l
To monitor the content of a counter object imapstat every 5 seconds:
counterutil -o imapstat
To reset the counter global.maxconnections, associated with the counter object imapstat, to zero:
counterutil -s -o imapstat -c global.maxconnections
For usage information on counterutil, refer to the "Gathering Message Store Counter Statistics by Using counterutil."
deliver
The deliver utility delivers mail directly to the message store.
If you are administering an integrated messaging environment, you can use this utility to deliver mail from another MTA, a sendmail MTA for example, to the Messaging Server message store.
Note:
The deliver utility is only for use with files which are already completely and properly formed email messages (RFC 822).Requirements: Must be run locally on the Messaging Server; the stored utility must also be running. Make sure that the environment variable ConfigRoot is set to MessagingServer_home/config.
Location on UNIX: MessagingServer_home/bin/
deliver [-r <address>] [-m <mailbox>] [-g <flag>] [-q] [-c] [-p] [-d] <userid>... | <pattern>
You can specify multiple userids. If you specify no options, mail is delivered to the inbox of the user specified in userid.
The options for this command are:
| Option | Description |
|---|---|
|
-c |
Automatically creates the mailbox if it doesn't exist in the message store.
|
|
-d |
This option is recognized but ignored by deliver in order to maintain compatibility with /bin/mail. |
|
-g flag |
Sets the system flag or keyword flag on the delivered message.
|
|
-m mailbox |
Delivers mail to a specific mailbox.
|
|
-p |
Deliver to the inbox of the users which match the wildcard pattern.
|
|
-q |
Overrides mailbox quotas. Delivers messages even when the receiving mailbox is over quota. |
|
-r address |
Inserts a Return-Path: header containing address. |
|
userid | pattern |
Deliver to the mailbox of the user(s) specified by userid. Multiple userid values can be specified.pattern will be expanded to the appropriate list of existing users when the -p option is used. |
Tip:
The mboxutil -lxp user/userid/mailbox command can be used to check the access controls on mailbox for userid.Debugging and Troubleshooting Options
Table 75-4 deliver Debugging and Troubleshooting Options
| Option | Description |
|---|---|
|
-t seconds |
Deliver as many copies of the message as possible to the userid in seconds time. This option is primarily meant for load-testing a mailbox. |
To deliver the contents of a file named message to Fred's tasks mailbox:
deliver -m tasks fred < message
In the above example, if the tasks mailbox does not grant "p" rights to the value of the authid passed in with the -a option or the tasks mailbox does not exist, the contents of message is delivered to the inbox of the user fred.
To deliver the contents of a file named message to the inbox of all existing users on the store
deliver -p '*' < message
To deliver the contents of a file named message to the inbox of all existing users in the example.com hosted domain.
deliver -p '*@example.com' < message
Tip:
Use the mboxutil command to determine which users will receive a copy of the message based on a given user pattern, e.g. mboxutil -lp "user/pattern/INBOX"To deliver the contents of a file named message to Fred's Important mailbox, and set the '\Flagged' IMAP flag on that new message.
deliver -m Important -g '\Flagged' fred < message
hashdir
The hashdir command calculates the hash where the specified user ID would be found in a store partition. If the user is not in the default domain, you should append @<domain> to the user ID.
hashdir [-a] [-i] <userid>[@<domain>]
The options for this command are:
| Option | Description |
|---|---|
|
-a |
Appends the specified user ID to the output. |
|
-i |
Allows you to use the command in interactive mode. |
hashdir user1 64/b1/ hashdir user1@domain.com 11/05/
Note:
The hashdir command does not validate the input to determine whether it is a valid userid or whether the mailbox exists in the store. Also, the user ID is case sensitive, specifying the wrong case will generate a different hash. To see where the folder exists in the store, the "mboxutil" command may be more useful.imarchive
The imarchive utility supports the AXS-One archiving system for Messaging Server. imarchive reads the AXS-One archive report files and performs one of the following actions:
-
Marks the messages as archived in the message store. Messages remain in both the message store and archive system. Marking a message prevents it from being re-archived. Marking messages is the default action.
-
Creates URL stubs of the messages. The user will see the same header, internal date, save date, and message flags, but instead of the message text, the user will have a clickable URL to retrieve the message text.
Requirements: Must be run locally on the Messaging Server. You can run imarchive as root or as mailsrv.
Location:MessagingServer_home/bin/
imarchive [-s] [-v] [-p <dir>]
The options for this command are:
| Option | Description |
|---|---|
|
-pdir |
Processes archive reports in the specified directory |
|
-s |
Replaces archived messages with stubs |
|
-v |
Provides verbose logging information |
If you do not use the -s option, imarchive takes the default action, marking the messages as archived in the message store.
To stub messages:
imarchive -s
imcheck
The imcheck utility prints mailbox data and metadata. In addition, imcheck prints mboxlist database data for specified database files and prints database statistics.
imcheck [-m mailbox [-c|-b messagenum] | -x dir [-c|-b messagenum] | -p partition | -f file] [-e | -H] [-D [-S separator]] imcheck -q imcheck -d <databasename> [-S separator] imcheck -s [-n] [subsystem...]
The options for this command are:
| Option | Description |
|---|---|
|
-b messagenum |
Prints the contents of the message specified by messagenum. |
|
-c messagenum |
Prints cache data for the specified message number. |
|
-d databasename |
Prints the contents of the database specified by databasename. |
|
-D |
Prints metadata in imsbackup format to verify the success of the backup operation. |
|
-e |
Prints the uids of expunged messages. |
|
-f file |
Prints metadata for the mailboxes listed in the specified file. You must specify a full path name for file. |
|
-H |
Print mailbox header only. |
|
-m mailbox |
Prints metadata for the specified mailbox. The mailbox name must be in Modified UTF-7 encoded format. You can use the "-E M-UTF-7" option with the mboxutil command to list mailboxes in Modified UTF-7 format. For information about the output produced by this option, see "imcheck -m Metadata Output." |
|
-n |
Specifies that no locking will occur. This option should be used only for debugging database hang problems. Caution Only use this option when the database is hung. It can cause data corruption in the message store. |
|
-p partition |
Prints metadata for every mailbox in the specified message store partition. |
|
-q |
Displays the maintenance queue. See "Displaying the Maintenance Queue" for more information. |
|
-s |
Prints database statistics. |
|
-S separator |
Specifies an output field separator. The default value is a vertical bar: "|" |
|
-x dir |
Prints metadata for the mailbox under the directory specified by dir. |
|
subsystem |
Prints the replication statistics. subsystem can be spool, lock, log, txn, or rep. |
Note:
When using the separator, check output consistency by trying the separator string as a single or double quoted string with escape sequences if required.The imcheck -m mailbox command displays metadata that describes the entire mailbox and metadata that describes each message.
The message-specific data is displayed in a table. Most of the fields in the table are self-explanatory. However, the following fields need further explanation:
HSize - Header size
MT - Message type ID, defined by configutil options such as store.messagetype.* and store.messagetype.enable. For a list of these options, see the Messaging Server Reference.
SFlags - System flags. The system flags are as follows:
R : Recent S : Seen D : Deleted A : Answered F : Flagged T : Draft B : Stubbed C : Archived E : Encrypted N : NoLeadingDots
In the imcheck -m mailbox output, the system-flag metadata is displayed as a character. For example: S
indicates that the Seen flag has been set.
UFlags - Flags defined by the user. User-flags are displayed as a hex number. The binary form of the hex number represents the user-flag switches. For example, if the user has defined six flags, the value
3f0000
indicates that all six flags are set.
To dump metadata to verify the imsbackup operation performed on the user jdoe's INBOX, separating the output with a colon (":"):
imcheck -D -S ":" -m user/jdoe/INBOX
To dump the contents of the folder.db database:
imcheck -d folder.db
To print metadata for the inbox of the user jdoe:
imcheck -m user/jdoe/INBOX -------------------------------------------------------------- Name: user/jdoe Version: 102 Exists: 10 Flags: 0 Largest Msg: 1094 bytes Last Append: 20080801062616 Last UID: 1008276527 Oldest Msg: 20000621093214 Oldest Uid: 2 Quota Used: 10061 UID Validity: 1008099930 Cache Offset: 7856 Start Offset: 256 ACL: jdoe lrswipcda Userflags: f1 f2 f3 f4 f5 f6 Subscribed: 0 Partition: primary Path: /var/opt/SUNWmsgsr/store/partition/primary/=user/64/b1/=jdoe Msg Path: /var/opt/SUNWmsgsr/store/partition/primary/=user/64/b1/=jdoe MsgNo Uid Internal-Date Sent-Date Size HSize Cache-Id C-Offset C-Len Last-Updated Save-Date MT SFlags UFlags Original-Uid Message-id --------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 1 20080801061303 20080801061259 752 744 1 16 1324 20080801061303 20080801061303 0 S 0.0.0 1217596383-1 <200808011312.m71DCxJp017783@dumbo.example.com> 2 2 20080801062616 20080801062615 781 772 1 1340 1440 20080801062616 20080801062616 0 S 0.0.0 1217596383-2 <200808011326.m71DQFYb018990@dumbo.example.com>
To print metadata for the Sent folder of a Japanese User jauser:
bash-3.00# ./mboxutil -E "M-UTF-7" -lp user/jauser/*
msgs Kbytes last msg partition quotaroot mailbox
0 0 - - primary 5120 user/jauser/INBOX
0 0 - - primary - user/jauser/&MFQwf3ux-
0 0 - - primary - user/jauser/&Tgtm+DBN-
1 0 2009/03/23 11:59 primary - user/jauser/&kAFP4W4IMH8-
bash-3.00# ./imcheck -m "user/jauser/&kAFP4W4IMH8-"
--------------------------------------------------------------------------------
Name: user/jauser/&kAFP4W4IMH8-
Version: 102
Exists: 1
Flags: 0
Largest Msg: 898 bytes
Last Append: 20090323115905
Last UID: 1
Oldest Msg: 20090323115905
Oldest Uid: 1
Quota Used: 898
UID Validity: 1237768457
Cache Offset: 7856
Start Offset: 256
ACL: jauser lrswipcda
Subscribed: 1
Partition: primary
Path: /opt/SUNWmsgsr/data/store/partition/primary/=user/20/b0/=jauser/=&k+A+F+P4+W4+I+M+H8-
Msg Path: /opt/SUNWmsgsr/data/store/partition/primary/=user/20/b0/=jauser/=&k+A+F+P4+W4+I+M+H8-
MsgNo Uid Internal Date Sent Date Size HSize CacheOff Last Updated Save Date MT SFlags UFlags Original-Uid Message-id
------------------------------------------------------------------------------------------------------------------------------------------------
1 1 20090323115905 20090323115905 898 549 7856 20090323115905 20090323115905 0 S 0.0.0 1237768457-1 <cd8b67384048.49c77989@dumbo.example.com>
imdbverify
The imdbverify utility takes and verifies message store database snapshots. For more information on running imdbverify, see "Administering Message Store Database Snapshots (Backups)."
imdbverify -s [-m]
The options for this command are:
imexpire
imexpire automatically expires messages in the message store based on administrator-specified criteria. The "impurge" command purges the messages.
Topics:
The expire phase can perform one of these actions:
-
Discard - removes messages from the mailbox immediately.
-
Archive - archives messages by using the AxsOne archive store.
-
Fileinto - moves messages to a specified mailbox folder.
-
Report - prints the specified mailbox name, uid, and uid validity to stdout.
By default, imexpire discards messages.
For details about how the imexpire actions can be performed, see "Message Store Maintenance Queue," "Configuring Message Expiration (Tasks)," and "Message Store Message Expiration."
The expire criteria can be set with configutil options or in a file called store.expirerule. Here are some of the criteria that can be specified:
-
Folder pattern
-
Number of messages in the mailbox
-
Total size of the mailbox
-
Age, in days, that messages have been in the mailbox. This criterion dates the age of a message from the time it first arrives in the message store (is first received by the user).
-
Age, in days, that messages have been saved in a particular mailbox folder. This criterion dates the age of a message from the time it is moved to a particular folder or re-saved in a folder.
-
Size of message and grace period (days that a message exceeding the size limit will remain in the message store before removal)
-
Whether a message has been flagged as seen or deleted
-
By message header field such as subject or message ID
-
According to a sieve script, as defined in RFC 3028
You can use imexpire to install a local expire rule file (store.expirerule) without conflicting with existing expire rules. If an expire rule file configured for the same partition or mailbox is executing while you try to install a new expire rule file, a warning message appears and the new expire rule file is not installed. Use the imexpire -i option to install a local expire rule file.
You can exclude a particular user or mailbox folder from all expire criteria by setting the exclusive expire rule for that user or mailbox without specifying any other rules in the expire rule file.
Note:
The functionality of imexpire has been expanded and the interface has changed since earlier versions of Messaging Server. However, this version continues to support older imexpire configurations.imexpire must run locally on the Messaging Server; the stored utility must also be running.
The location of imexpire is MessagingServer_home/bin.
imexpire [-n] [-d] [-v <num>] [-p <partition> | -u <user>] [-t <num>][-r <num>] [-m <num>] [-f <file>]
imexpire -i {-p <partition> | -x <mailbox>} -f <file>
The options for this command are:
Table 75-9 imexpire Command Options
|
Option |
Description |
|
-f file |
Use the expire rules specified in file. All other expire rules are ignored. When used with the -i option, -f file refers to the expire-rule file to be installed. Use a full path name to specify file. The expire rules in file must use the same format as the rules in the global expire configuration file. |
|
-i |
Install a local expire-rule configuration file. This option must be used with either the -p partition option to specify a message store partition or the -x mailbox option to specify a mailbox. In addition, it must be used with the -ffile option to specify the expire rule file to install. |
|
-n |
Trial run only - do not perform expire. A description of what would happen without this flag is output. |
|
-v 0|1|2 |
Log expire statistics. The number specifies the log level, where 0 = store level statistics (default setting) 2 = mailbox level statistics 3 = message level statistics Messages are logged to the log file by default. When the -d option is used, messages go to stdout. |
|
-d |
Display debug output to stdout/stderr. |
|
-p message_store_partition |
Expire the specified message store partition. |
|
-u user |
Expire the specified user. |
|
-t num |
Maximum number of threads per process. Default is 50. |
|
-r num |
Maximum number of threads per partition. Default is 1. |
|
-m num |
Maximum number of rules in a policy. Default is 128. |
|
-x mailbox |
Name of the mailbox to which the local expire rules apply. For example: user/joe/INBOX. This option is used with the -i option to install a local configuration file that will expire messages in the specified mailbox and its sub-folders. |
Install a local expire rule configuration file for the user jdoe. These expire rules will apply to jdoe's memos folder.
imexpire -i -x user/jdoe/memos -f /home/jdoe/store.expirerule
Messaging Server provides the following additional functionality to imexpire:
Attributes for Spam and Virus Scanning Through an MTA Channel
To facilitate spam and virus scanning through an MTA channel, the following attributes have been added to imexpire:
Table 75-10 imexpire Attributes
| Attribute | Description |
|---|---|
|
channel |
An MTA channel. |
|
rescanhours |
Rescan messages that have not been scanned for the specified number of hours. |
Sieve body-test functionality has been added to the imexpire utility. The test can find and perform actions on existing email messages in the Message Store on keywords in the body part.
To enable a Sieve body-test, set ENABLE_SIEVE_BODY=1 in option.dat.
Example usage in store.expirerule:
folderpattern: *
sieve: require "body"; body :contains "bug";
action: discard
iminitquota
The iminitquota utility reinitializes the quota limit from the LDAP directory and recalculates the total amount of disk space that is being used by the users. It updates the message store quota.db database under the mboxlist directory in the message store. The iminitquota utility should be run after the reconstruct -q utility is run.
Location: MessagingServer_home/bin/
iminitquota -a | -q | -s | -u <userid>
The options for this command are:
Table 75-11 iminitquota Options
| Option | Description |
|---|---|
|
-a |
Initializes and updates the quota files for every message store user. |
|
-q |
Initializes quota only. |
|
-s |
Initializes quota, usage, and overquota status. |
|
-u userid |
Reinitializes and updates the quota-related information for the specified user. The userid option specifies the message store id of a user, not the login id of the user. |
You must specify either the -a or -u option with the iminitquota command.
immonitor-access
Monitors the status of Messaging Server components-Mail Delivery (SMTP server), Message Access and Store (POP and IMAP servers), Directory Service (LDAP server) and HTTP server. This utility measures the response times of the various services and the total round trip time taken to send and retrieve a message. The Directory Service is monitored by looking up a specified user in the directory and measuring the response time. Mail Delivery is monitored by sending a message (SMTP) and the Message Access and Store is monitored by retrieving it. Monitoring the HTTP server is limited to finding out weather or not it is up and running.
The internal operation of immonitor-access is as follows: first it does an ldapsearch of a test user created by the administrator. This checks the Directory Server. It can then connect to the SMTP port and send a message to the mail address to check the dispatcher. Then, it checks Message Access by using the IMAP and POP server to see if the message made it to the Message Store. The command logs a message in the default log file if any of the thresholds are exceeded.
The command creates a report that contains the following information:
-
The state of the components
-
The response time
-
The round-trip time for that service
immonitor-access is typically run by cron at scheduled intervals to provide a snapshot of the status of the Message Access and Store components. immonitor-access can also connect to the IMAP/POP service and delete messages with the subject specified by -k. If -k is not specified, all messages containing the subject header, immonitor, are deleted.
The administrator must create a test user for use by this command before it can be executed.
immonitor-access -C <LMTP_host>[:<port>]=[<threshold>][,STLS|PORT] -u <user_name> [-D <threshold>] [-m <test_file>] [-k <subject>] [-dhnv] [-A <alert_host>] [-f <alert_from>] [-r <alert_recipients>] [-X] [-T] immonitor-access -I <IMAP_host>[:<port>]=[<threshold>][,STLS|PORT] -u <user_name> [-w passwd | -j pwdfile] [-D <threshold>] [-k <subject>] [-dhnvz] [-A <alert_host>] [-f <alert_from>] [-r <alert_recipients>] [-X] [-T] immonitor-access -H <HTTP_host>[:<port>]=[<threshold>][,STLS|PORT] [-c <cookiename>] -u <user_name> [-w passwd | -j pwdfile] [-D <threshold>] [-dhnv] [-A <alert_host>] [-f <alert_from>] [-r <alert_recipients>] [-X] [-T] immonitor-access -L <LDAP_host>[:<port>]=[<threshold>][,STLS|PORT] -u <user_name> [-b searchbase -B bindDN] [-w passwd | -j pwdfile] [-D <threshold>] [-r <alert_recipients>] [-A <altenate_host>] [-f <alert_from>] [-X] [-T] [-dhnv] immonitor-access -P <POP_host>[:<port>]=[<threshold>][,STLS|PORT] -u <user_name> [-w passwd | -j pwdfile] [-D <threshold>] [-k <subject>] [-dhnvz] [-A <alert_host>] [-f <alert_from>] [-r <alert_recipients>] [-X] [-T] immonitor-access -S <SMTP_host>[:<port>]=[<threshold>][,STLS|PORT] -u <user_name> [-D <threshold>] [-m <test_file>] [-k <subject>] [-dhnv] [-A <alert_host>] [-f <alert_from>] [-r <alert_recipients>] [-X] [-T]
The following list contains valid task options for the command.
Table 75-12 immonitor-access Command Options
|
Option |
Description |
|
-u user_name |
The valid test user account to use. This test mail user has to be created by the administrator. If the test mail user is in a hosted domain, user@domain should be specified. |
|
-w passwd |
The password corresponding to the user specified with u. To read the input from standard input, "-" can specified with -w. ANY PASSWORD SPECIFIED ON THE COMMAND LINE WITH -w WILL BE VISIBLE TO OTHER USERS OF THE SYSTEM. Use of the -j option is strongly encouraged. This option, or -j, is mandatory when the -H, -I, or -P options are used, or when -n is used in conjunction with -L. |
|
-j pwdfile |
A readable file containing the password corresponding to the user specified with -u. This option, or -w, is mandatory when the -H, -I, or -P options are used, or when -n is used in conjunction with -L. This might be available in a future release. |
|
-C LMTP_host: [ port ] = [ threshold ] |
Use the LMTP server and the port specified to check if Messaging Server is able to deliver the message to the store. The threshold is specified in seconds. |
|
-H HTTP_host: [ port ] = [ threshold ] |
Use the HTTP server and the port specified to check if the HTTP server is able to accept requests on the specified port. When -I -H or -P is used, it is necessary to provide the test user password with -w. When -S/-C, -I/-P are specified together, the command does the following: + sends mail and retrieves with IMAP and POP + reports the per protocol response time + reports round-trip time o reports delivery time (the time taken to send the mail and be visible to IMAP/POP) Multiple -I, -P, and -S options can be specified, which helps in monitoring Messaging Server on various systems. |
|
-I IMAP_host: [ port ] = [ threshold ] |
Use the IMAP server and the port specified to check the IMAP component of the Message Access. The threshold is specified in seconds. The threshold involves the time to login, retrieve, and delete the message. |
|
-L LDAP_host: [ port ] = [ threshold ] |
Use the LDAP server and the port specified to check the Directory Server. The threshold is specified in seconds. |
|
-P POP_host: [ port ] = [ threshold ] |
Use the POP server and the port specified to check the POP component of the Message Access. The threshold is specified in seconds. The threshold involves the time to login, retrieve, and delete the message. |
|
-S SMTP_host: [ port ] = [ threshold ] |
Use the SMTP server and the port specified to check if Messaging Server is able to accept mail for delivery. The threshold is specified in seconds. |
|
-A alert_host |
The SMTP server to send e-mail alerts to. This option helps in sending alert messages even when the primary mail server is down or heavily loaded. If -A is not specified, the SMTP server on the localhost is used. |
|
-b searchbase |
Use search base as the starting point for the searching in the Directory Server. It is the same as -b of ldap-search(1). If -b is not specified, the utility uses the value of dcRoot of the configuration option local.ugldapbasedn. |
|
-B bindDN |
LDAP DN to bind as when performing an LDAP search via -L. If not specified, then the value of configuration option local.ugldapbinddn is used. This option as well as -j or -w is mandatory when the -n option is used. |
|
-d |
The debug mode: display the execution steps. |
|
-D threshold |
The delivery (also called round-trip time) threshold. The time taken to send the mail and the mail being visible to POP/IMAP. This option can be used only when -I/-P and -S/-C are used. |
|
-f alert_from |
When immonitor-access sends out an e-mail, it usually is sent as root@domainname. Specify this option to send out an e-mail as different user: -f user@red.iplanet.com |
|
-h |
Prints command usage syntax. |
|
-k subject |
Header subject of the messages to be sent/deleted. The utility, by default, uses the string "immonitor:<date>" as the subject in the header sent out with the -S option. If -k is specified, the string "immonitor:subject" is used in the subject header. This option can be used with -z to delete messages, if -k is not specified, all messages with the Subject header containing "immonitor" are deleted. |
|
-m test_file |
The file that is mailed to the test user. You can get response and round-trip times for various mail sizes with this option. Specify only text files as non-text files result in unexpected behavior. If -m is not specified, the mailfile.txt file in MessagingServer_home/lib/locale/C/mailfile.txt is used as the mail file. |
|
-n |
Operate without a Messaging Server configuration. Useful when running the utility on a remote system. This might be available in a future release. |
|
-r alert_recipients |
A comma-separated list of mail recipients who will be notified. If this option is not specified, the command reports the alert messages on the standard output. |
|
-v |
Run in verbose mode, with diagnostics written to standard output. |
|
-z |
Delete messages containing the string specified by -k in the subject header. If -k is not specified, all messages with the subject header containing "immonitor" are deleted. Use -z only with -I or -P. Do note use -z with -S or -C as this can cause unexpected results. |
|
-x |
Enable SASL. |
|
-T |
Enable SSL. |
The default ports are:
SMTP = 25
IMAP = 143
POP = 110
LDAP = 389
LMTP = 225
HTTP = 80
If either the port or threshold is not specified, default ports with the default threshold of 60 seconds is assumed. The threshold specified can be a decimal number.
The command generates a report containing the various protocol execution times. For example:
Smtp Statistics for: thestork:25 Connect Time: 2.122 ms Greeting Time: 5.729 ms Helo Time: 2.420 ms Mail From: Time: 2.779 ms Rcpt To: Time: 4.128 ms Data Time: 1.268 ms Sending File Time: 94.156 ms Quit Time: 0.886 ms Total SMTP Time: 113.488 Milliseconds
If the alert recipients are specified and any of the threshold values are exceeded, the command mails the report containing the service name and the response time:
ALERT: <service> exceeds threshold Response time=secs/Threshold=secs
Note that in case of times reported for IMAP, the individual times might not add up to the exact value shown by the "Total IMAP time". This occurs because the message does not get to the store immediately. The utility loops until the message is found. Typically, the search time indicates only the successful search time. However, the total time includes each of the individual sleep and search times.
With POP, the utility needs to login and logout multiple times before the message is actually found in the store. Thus, the total time here is the accumulated time for all the logins and log outs.
Example 1: To monitor the SMTP, IMAP, and POP with the threshold 250 milliseconds more than the default value (60 seconds) on localhost use:
immonitor-access -S localhost:=60.25 -I localhost:=60.25 -P localhost:=60.25 -u test_user -w passwd
This example assumes that test_user exists with password "passwd."
Example 2: To monitor LDAP on localhost with no Messaging Server configuration use:
immonitor-access -n -L 127.0.0.1:389 -b o=usergroup -u test_user -B "cn=directory manager" -w passwd
The above example assumes that the Directory Manager password is passwd and that there is a user named test_user.
Example 3: To check remote connectivity and latency issues on remotehost use:
immonitor-access -S remotehost:=10 -I remotehost:=10 -P remotehost:=10 -u tester -w passwd
Example 4: To run immonitor-access on a normal port use:
immonitor-access -u admin -w password -P host:110
Example 5: To run immonitor-access using STLS:
immonitor-access -u admin -w password -P host:110 -Ximmonitor-access -u admin -w password -P host:110=STLS -X
Example 6: To run immonitor-access using SSL via STLS:
immonitor-access -u admin -w password -P host:110=STLS -T -X
Example 7: To run immonitor-access on the SSL port:
immonitor-access -u admin -w password -P host:995 -Timmonitor-access -u admin -w password -P host:995=PORT -T
Example 8: To run immonitor-access using SASL on SSL:
immonitor-access -u admin -w password -P host:995 -T -Ximmonitor-access -u admin -w password -P host:995=PORT -T -X
The exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error. A different exit status is returned when various thresholds are exceeded.
Table 75-13 Exit Status Description
| Status | Description |
|---|---|
|
0 |
Successful execution with no errors or thresholds exceeded |
|
1 |
Exceeded threshold of a service |
|
2 |
Errors |
|
64 |
Usage errors |
|
75 |
Insufficient virtual memory |
An alert message is written to the console when the response time of any server exceeds the threshold.
An error message is written to the console when any of the servers cannot be reached.
The password passed with -w can be visible to a user using the ps(1) command. It is strongly advised that you create a test user to be specifically used by the monitoring utilities.
It is recommended that you use -w and enter the password through standard input. However, if the utility is executed through cron, the password can be stored in a file. This file can be redirected as the standard input for the utility.
cat passwd_file | immonitor-access -w - immonitor-access -w - ... < passwd_file
Do not use the echo command such as:
echo password | immonitor-access .. -w - ..
because the ps might show the echo's arguments.
To delete the test mail sent by the -S option, invoke the immonitor-access command with the -z option separately. Do not use the two together.
impurge
The impurge command can be used to manually purge unused cache records and message files in mailboxes when the purge server daemon process is not running (local.purge.enable is disabled). For more information see the Messaging Server Reference. The impurge command has the following options:
Requirements: Must be run locally on the Messaging Server.
Location: MessagingServer_home/lib/
impurge [-d] [-r hours] [-e]
The options for this command are:
| Option | Description |
|---|---|
|
-d |
Enables debug mode |
|
-r hours |
Exists after the specified number of hours |
|
-e |
Exits when the work queue is empty |
If both -r and -e are specified, impurge exits when the queue is empty or time has expired.
Only one impurge process can be executed at a time. Attempting to run the impurge command whilst the purge server daemon is running will result in the following error message in the Messaging Server debug logs:
[24/Feb/2009:14:43:59 +1100] hostname impurge[17471]: General Error: Could not get purge session lock. Possibly another impurge is running
imquotacheck
The imquotacheck utility administers user quotas and domain quotas in the message store. This utility can also compare mailbox size with a user's assigned quota. As an option, you can email a notification to users who have exceeded a set percentage of their assigned quota.
The imquotacheck utility lists users in the local mboxlist database. To list users in the LDAP directory, use the imquotacheck -a option.
Requirements: Must be run locally on the Messaging Server.
Location:MessagingServer_home/bin/
To report quota and usage information to stdout:
imquotacheck [-u <user> | -d <domain>] [-p <partition>] | -p <partition> ] [-a]
To enforce a domain quota:
imquotacheck -f [-d <domain>]
To notify users when they have exceeded a set percentage of their assigned quota (to deliver over-quota notification messages):
imquotacheck -n [-e] [-d <domain>] [-r <rulefile>] [-t <message template>] [-l]
The options for this command are:
Table 75-15 imquotacheck Options
| Option | Description |
|---|---|
|
-a |
Lists users in the LDAP directory. If the -a option is not used, imquotacheck lists users in the message store (the local mboxlist database). |
|
-d domain |
Searches for users only in the specified domain.When used with the -f option, the -d <domain> option enforces quotas for the specified domain.When used with the -n option, the -d <domain> option delivers over-quota notifications for users in the specified domain. |
|
-f |
Enforces domain quotas. If the domain is over quota and the mailDomainStatus attribute is currently set to active, the value will be reset to overquota, which will prevent mail from being accepted by the message store. If the domain is not over quota and the mailDomainStatus attribute is set to overquota, then the value will be changed to active, and mail will be accepted. |
|
-h |
Displays help for this command. |
|
-n |
Sends notification messages based on the rules defined in the <rulefile>. If you do not define any rules with the -r option when you use the -n option, the default <rulefile> is used. If you have not set up a default <rulefile> and you do not define any rules when you use the -n option, you do not receive an error.Use of imquotacheck -n is mutually exclusive with dynamic notification (that is, when store.quotanotification is enabled). See "Methods of Notification." |
|
-p partition |
Reports quota for the specified partition. |
|
-r rulefile |
Specifies the set of rules to be used when you want to calculate quota usage. This option is used with the -n option. If -r is not specified, a default <rulefile> can be used. To set up a default <rulefile>, copy the "Sample Rulefile" to <MessagingServer_home>/config/imq.rulefile. See "Rulefile Format." |
|
-t message template |
Notifies users when their mailbox quota is exceeded. This option is used with the -n option.The message template format is the following:* %U% - user's mailbox id* %Q% - percentage of the used mailbox quota* %R% - quota usage details: assigned quota, total mailbox size, and percentage used. If the -e is specified, mailbox usage of the individual folders are also reported.* %M% - current mailbox size* %C% - quota attribute value. If -t is not specified, a default message file will be mailed. To setup a default message file, copy the "Notification File" to <MessagingServer_home>/config. |
|
-u user |
Obtains the quota status of the specified user id. Cannot be used to specify multiple users. |
|
-e |
Report disk usage of the individual folders in notification messages. |
|
-l |
Log users to action log who are above quota. |
To send a notification to all users in accordance to the default rulefile:
imquotacheck -n
To send a notification to all users in accordance to a specified rulefile, myrulefile, and to a specified mail template file, mytemplate.file:
imquotacheck -n -r myrulefile -t mytemplate.file
To enforce the domain quota for the example.com domain:
imquotacheck -f -d example.com
To list the usage of all users whose quota exceeds the least threshold in the rulefile:
imquotacheck
To list per folder usages for user user1:
imquotacheck -u user1
To only list the users in domain example.com:
imquotacheck -d example.com
The imquotacheck command has stable output formats that we support and allow customers to parse.
Sample imquotacheck output:
Name Quota(K) Usage(K) % Quota# Usage# % OverDate WarnDate -------------------- -------- -------- --- ------- ------- --- -------- -------- joe - 6 - - 1 - - - mary 100 110 110 - 49 - 10/14/15 10/14/15 big 52428800 420 0 - 1673 - - - small - 1014B - - 3 - - - --------------------------------------------------------------------------------
The rulefile format is organized into two sections: a general section and a rule name section. The general section contains attributes that are common across all rules. Attributes that are typically specified in the general section are the mailQuotaAttribute and the reportMethod. In the rule name section, you can write specific quota rules for notification intervals, trigger percentages, and so on. Attributes that are typically specified in the rule name section are notificationTriggerPercentage, enabled, notificationInterval, and messageFile. Note that the attributes and corresponding values are not case-sensitive. The following rulefile format is used:
[General] mailQuotaAttribute = [value] reportMethod = [value] [rulename1] attrname=[value] attrname=[value] [rulename2] attrname=[value] attrname=[value] [rulename3] attrname=[value] attrname=[value]
Table 75-16 shows the attributes, whether they are required, the default value, and the description.
Table 75-16 rulefile Attributes
| Attribute | Required Attribute? | Default Value | Description |
|---|---|---|---|
|
mailQuotaAttribute |
No |
Value in quotadb |
Specifies the name of the custom mailquota attribute. If not specified, the value in quotadb is used. |
|
reportMethod |
No |
Not Applicable |
You can provide your own code to customize the output of the quota report. The value of this attribute is specified as <library-path:function>, where <library-path> is the path of the shared library and <function> is the name of the report function. See "reportMethod Signature" for more information about what options your function must accept and return. |
|
notificationTriggerPercentage |
Yes |
Not Applicable |
Specifies the consumed quota percentage that will trigger notification. Value should be unique and an integer. |
|
messageFile |
No |
<MessagingServer_home>/config/imq.msgfile |
Specifies the absolute path to the message file. |
|
notificationInterval |
Yes |
Not Applicable |
Indicates the number of hours before a new notification is generated. |
|
enabled |
No |
0 (FALSE) |
Indicates if the particular rule is active. Applicable values are 0 for FALSE and 1 for TRUE. |
|
notificationMethod |
No |
Not Applicable |
You can provide your own code to perform the overquota notification. The value of this attribute is specified as <library-path:function>, where <library-path> is the path of the shared library and <function> is the name of the report function. See "notificationMethod Signature" for more information about what options your function must accept and return. |
If you override the imquotacheck reportMethod() with your own function, it must be defined as:
int symbol(QuotaInfo* info, char** message, int* freeflag)
typedef struct QuotaInfo {
const char* username; /* user name (uid or uid@domain) */
long quotakb; /* quota in kbytes */
long quotamsg; /* quota in number of messages */
ulong usagekb; /* total usage in kbytes */
ulong usagemsg; /* total usage in number of messages */
FolderUsage* folderlist; /* folder list (for -e) */
long num_folder; /* number of folders in the folderlist */
long trigger; /* not used */
const char* rule; /* not used */
}
typedef struct FolderUsage {
const char*foldername;
ulong usagekb; /* folder usage in kbytes */
}
The address, message, points to the output message. The report function is expected to fill the value of *message and allocate memory for message when necessary. The freeflag variable indicates if the caller is responsible for freeing allocated memory for *message.
The return values are 0 for success and 1 for failure.
The imquotacheck function will invoke the reportMethod to generate the report output. If the reportMethod returns 0 and *message is pointing to a valid memory address, message will be printed.
If the *freeflag is set to 1, the caller will free the memory address pointed to by message. If the -e option is specified, the quota usage for every folder will be stored in the folderlist, an array in FolderUsage; the num_folder variable is set to the number of folders in the folderlist.
If you override the imquotacheck notificationMethod() with your own function, it must be defined as:
int symbol(QuotaInfo* info, char** message, int* freeflag)
typedef struct QuotaInfo {
const char* username; /* user name (uid or uid@domain) */
long quotakb; /* quota in kbytes */
long quotamsg; /* quota in number of messages */
ulong usagekb; /* total usage in kbytes */
ulong usagemsg; /* total usage in number of messages */
FolderUsage* folderlist; /* folder list (for -e) */
long num_folder; /* number of folders in the folderlist */
long trigger; /* the exceeded notificationTriggerPercentage */
const char* rule; /* rulename that triggered notification */
}
typedef struct FolderUsage {
const char *foldername;
ulong usagekb; /* folder usage in kbytes */
}
The address, message, points to the notification message. The notification function is expected to fill in the value of this variable and allocate the memory for the message when necessary. The freeflag variable indicates if the caller is responsible for freeing the memory allocated for message.
The return values are 0 for success and 1 for failure.
If the notification function returns a 0, and *message is pointing to a valid address, the imquotacheck utility will deliver the message to the user. If the *freeflag is set to 1, the caller will free the memory address pointed to by message after the message is sent.
If the -e option is specified, the quota usage for every folder will be stored in the folderlist variable, an array of FolderUsage structure; the num_folder variable is set to the number of folders in the folderlist.
Note:
If the messageFile attribute is also specified, the attributed messageFile will be ignored.In the sample rulefile, the following files libzz.so, libzz.sl, and libzz.dll are library files. The /xx/yy are directory paths that should be replaced by the relative paths to where these library files are located on the server.
# # Sample rulefile # [General] mailQuotaAttribute=mailquota reportMethod=/xx/yy/libzz.so:myReportMethod [for Solaris only ] [rule1] notificationTriggerPercentage=60 enabled=1 notificationInterval=3 notificationMethod=/xx/yy/libzz.so:myNotifyMethod_60 [rule2] notificationTriggerPercentage=80 enabled=1 notificationInterval=2 messageFile=/xx/yy/message.txt [rule3] notificationTriggerPercentage=90 enabled=1 notificationInterval=1 notificationMethod=/xx/yy/libzz.so:myNotifyMethod_90 # # End #
Threshold Notification Algorithm
-
Rule precedence is determined by increasing trigger percentages.
-
The highest applicable threshold is used to generate a notification. The time and the rule's threshold are recorded.
-
If users move into a higher threshold since their last quota notification, a new notification will be delivered based on the current set of applicable rules. This notice can be immediately delivered to any user whose space usage is steadily increasing.
-
If usage drops, the notification interval of the current rule (lower threshold) will be used to check the time elapsed since the last notice.
-
The stored time and threshold for the user will be reset to zero if the user's mailbox size falls below all of the defined thresholds.
The utility depends on the message file to have at minimum a Subject Header. There should be at least one blank line separating the Subject from the body. The other required headers are generated by the utility. The notification file format is the following:
Subject: [Warning] quota reached for %U% Hello %U%, Your quota: %C% Your current mailbox usage: %M% Your mailbox is now %Q% full. The folders consuming the most space are: %R%. Please clean up unwanted diskspace. Thanks, -Administrator
where:
%U% - Species the user ID.
%Q% - Specifies the percentage of the mailbox quota used.
%R% - Specifies quota usage details, including assigned quota, total mailbox size, and percentage used. When -e is specified on the command line, the report shows the mailbox usage of the individual folders.
%M% - Specifies the current mailbox size.
%C% - Specifies quota attribute value.
Note:
If an account has less then 1KB of quota usage, imquotacheck prints out the usage in bytes (B) rather than kilobytes (KB) shown in the heading.imquotacheck -u testquota Name Quota(K) Usage(K) % Quota# Usage# % OverDate WarnDate -------------------- -------- -------- --- ------- ------- --- ---- testquota 256000 654B 0 100000 1 0 - - -------------------------------------------------------------------
Note:
Localized versions of imquotacheck notification incorrectly convert the % and the $ signs. To correct the encoding, replace every $ with \24 and replace every % with \25 in the message file.imsasm
The imsasm utility is an external ASM (Application Specific Module) that handles the saving and recovering of user mailboxes. imsasm invokes the imsbackup and imsrestore utilities to create and interpret a data stream.
During a save operation imsasm creates a save record for each mailbox or folder in its argument list. The data associated with each file or directory is generated by running the imsbackup or imsrestore command on the user's mailbox.
Location: MessagingServer_home/lib/msg
imsasm [<standard_asm_arguments>]
The options used in the imsasm utility are also known as standard-asm-arguments, which are Legato NetWorker backup standards.
Either -s (saving), -r (recovering), or -c (comparing) must be specified and must precede any other options. When saving, at least one path argument must be specified. path may be either a directory or filename.
The following options are valid for all modes:
| Option | Description |
|---|---|
|
-n |
Performs a dry run. When saving, walk the file system but don't attempt to open files and produce the save stream. When recovering or comparing, consume the input save stream and do basic sanity checks, but do not actually create any directories or files when recovering or do the work of comparing the actual file data. |
|
-v |
Turns on verbose mode. The current ASM, its arguments, and the file it is processing are displayed. When a filtering ASM operating in filtering mode (that is, processing another ASM's save stream) modifies the stream, its name, arguments, and the current file are displayed within square brackets. |
When saving (-s), the following options may also be used:
Table 75-18 imsasm Saving Options
| Option | Description |
|---|---|
|
-b |
Produces a byte count. This option is like the -n option, but byte count mode will estimate the amount of data that would be produced instead of actually reading file data so it is faster but less accurate than the -n option. Byte count mode produces three numbers: the number of records, i.e., files and directories; the number of bytes of header information; and the approximate number of bytes of file data. Byte count mode does not produce a save stream so its output cannot be used as input to another asm in recover mode. |
|
-o |
Produces an "old style" save stream that can be handled by older NetWorker servers. |
|
-e |
Do not generate the final "end of save stream" Boolean. This flag should only be used when an ASM invokes an external ASM and as an optimization chooses not to consume the generated save stream itself. |
|
-i |
Ignores all save directives from .nsr directive files found in the directory tree. |
|
-f proto |
Specifies the location of a .nsr directive file to interpret before processing any files. Within the directive file specified by proto, path directives must resolve to files within the directory tree being processed, otherwise their subsequent directives will be ignored. |
|
-p ppath |
Prepends this string to each file's name as it is output. This argument is used internally when one ASM executes another external ASM. ppath must be a properly formatted path which is either the current working directory or a trailing component of the current working directory. |
|
-t date |
The date after which files must have been modified before they will be saved. |
|
-x |
Crosses file system boundaries. Normally, file system boundaries are not crossed during walking. |
When recovering (-r), the following options may also be used:
Table 75-19 imsasm Recovering Options
| Option | Description |
|---|---|
|
-i response |
Specifies the initial default overwrite response. Only one letter may be used. When the name of the file being recovered conflicts with an existing file, the user is prompted for overwrite permission. The default response, selected by pressing Return, is displayed within square brackets. Unless otherwise specified with the -i option, n is the initial default overwrite response. Each time a response other than the default is selected, the new response becomes the default. When either N, R, or Y is specified, no prompting is done (except when auto-renaming files that already end with the rename suffix) and each subsequent conflict is resolved as if the corresponding lower case letter had been selected. The valid overwrite responses and their meanings are:
|
|
-m src=dst |
Maps the file names that will be created. Any files that start exactly with src will be mapped to have the path of dst replacing the leading src component of the path name. This option is useful if you wish to perform relocation of the recovered files that were saved using absolute path names into an alternate directory. |
|
-z suffix |
Specifies the suffix to append when renaming conflicting files. The default suffix is R. |
|
path |
Restricts the files being recovered. Only files with prefixes matching path will be recovered. This checking is performed before any potential name mapping is done with the -m option. When path is not specified, no checking is performed. |
To use imsasm to save the mailbox INBOX for user joe, the system administrator creates a directory file backup_root/backup/DEFAULT/joe/.nsr with the following contents:
imsasm: INBOX
This causes the mailbox to be saved using imsasm. Executing the mkbackupdir utility will automatically create the .nsr file. See "mkbackupdir."
imsbackup
The imsbackup utility is used to 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 via the imsrestore utility. The imsbackup utility provides a basic backup facility similar to the UNIX tar command.
When imsbackup, imsrestore, imsimport or any processing intensive operation takes significantly more system resources than normal, and continues doing so longer than the msprobe interval, there may be a temporary backlog of DB transaction log files to be cleared. If there are more files than specified in local.store.maxlog, then msprobe may erroneously restart all the processes during a restore. To prevent this from happening, disable msprobe during the imsbackup, imsrestore, and imsimport.
Location: MessagingServer_home/bin
For more information about imsbackup and backing up the message store, see "Backing Up and Restoring the Message Store" in the Messaging Server System Administrator's Guide.
imsbackup -f file [-b <blockfactor>] [-d <date>] [-m <link_count>] [-e <encoding>] [-u <file>] [-n <path>] [-ivlgrp] <name>...
The options for this command are:
|
Option |
Description |
|
-b blockfactor |
Everything written to the backup device is performed by blocks of the size 512 x blockfactor_. The default is 20. |
|
-d date |
Date from which messages are to be backed up, expressed in YYYYMMDD [:HHMMSS]; for example, -d 19990501:131000 would backup messages stored from May 1, 1999 at 1:10 pm to the present. The default is to back up all the messages regardless of their dates. |
|
-e encoding |
Mailbox name encoding (example: IMAP-mailbox-name) |
|
-f file |
Specifies the file name or device to which the backup is written. If file is "-', backup data is written to stdout. |
|
-g |
Debug mode. The output is written in the default log file not to the stdout. For the stdout, one should use -v. |
|
-i |
Ensures that all messages are backed up for a partial restore. Backs up every message multiple times if necessary. |
|
-l |
Used to autoload tape devices when end-of-tape is reached. |
|
-m link_count |
Specifies the minimum link count for hashing. |
|
-n path |
Specifies the networker backup path. |
|
-r |
Specifies read-only mode (does not upgrade or repair the mailbox automatically). |
|
-u file |
Specifies a backup object file. This file contains the object names (entire message store, user, group, mailbox, and so on) to backup. See name for a list of backup object |
|
-v |
Executes the command in verbose mode. |
|
-x |
Backs up expunged messages. |
|
name |
Can be 1) logical pathname of the backup object, 2) user ID, 3) message store mailbox name. Backup objects and paths:
|
The following example backs up the entire message store to /dev/rmt/0:
imsbackup -f /dev/rmt/0 /
The following backs up the mailboxes of user ID joe to /dev/rmt/0:
imsbackup -f /dev/rmt/0 /primary/user/joe
The following example backs up all the mailboxes of all the users defined in the backup group groupA to backupfile:
imsbackup -f- /primary/groupA > backupfile
imsconnutil
Monitors user access of the message store. imsconnutil can provide the following information:
-
Users currently logged in on IMAP or any HTTP webmail client.
-
The last access time (log in or log out) for a specified user.
-
For IMAP: lists the authentication method, the IP address from which the users are logged in, the IP address to which users are connected, and the port on which they are logged to and from.
This command requires root access by the system user, and you must set the configuration variables local.imap.enableuserlist, local.http.enableuserlist, and local.enablelastaccess to 1.
See "Monitoring User Access to the Message Store" for more information and examples.
Location: MessagingServer_home/bin
imsconnutil -c|-a [-s <service>] [-u <uid>] [-f <filename>]
imsconnutil -k {-u <uid> | -f <filename>}
The options for this command are:
Table 75-21 imsconnutil Options
| Option | Description |
|---|---|
|
-c|-a|-k |
At least one of -c or -a, or -k must be used. |
|
-a |
Last IMAP, POP, or http web mail client access (log in or log out) of user(s). -s does not affect the output of -a. |
|
-c |
List IMAPusers currently connected. |
|
-k |
Disconnect users from IMAP and POP. Users logged on to Communications Express lose the underlying IMAP connection and, thus, are also disconnected. The -k option must be used with either the -u uid option to specify users to disconnect or the -f filename option to specify the users listed in filename. The -k option requires that IMAP IDLE be configured. See "Configuring IMAP IDLE" for more information. |
|
-s service |
Can specify either IMAP or HTTP as service to monitor. Only applies to -c option. POP is not available because POP users do not typically stay logged on. |
|
-u uid |
Specify a UID to monitor. If -u and -f are not listed, then all users are monitored. |
|
-f filename |
File containing UIDs to monitor. Each UID must be on its own line. |
-
List every user ID currently logged into IMAP and http.
#imsconnutil -c
-
List last IMAP, POP, or Messenger Express access (log in or log out) of every user ID.
#imsconnutil -a
-
List access history (last log off or log on) of all user IDs. Lists current user IDs logged into IMAP and http.
#imsconnutil -a -c
-
List IMAP users currently logged on the message store.
#imsconnutil -c -s imap
-
Reveal whether user ID George is logged onto IMAP or not.
#imsconnutil -c -s imap -u George
-
Reveal whether user ID George is currently logged onto IMAP or Messenger Express, and lists the last time George was logged o or off.
#imsconnutil -c -a -u George
-
Disconnect the user ID George.
#imsconnutil -k -u George
The "rehostuser" utility makes use of the imsconnutil command. If you are planning to use the rehostuser command, for now, you must use the configutil command to explicitly configure service.imap.ensidle=1. This is because imsconnutil decides to use ENS or JMQ based on the configuration of the service.imap.ensidle option. While the imapd daemon treats that variable as "on" by default, if you have configured ibiff, imsconnutil treats the option as "off" by default.
imscripter
The imscripter utility connects to an IMAP server and executes a command or a sequence of commands.
May be run remotely.
Location: MessagingServer_home/bin/
imscripter [-h] imscripter [-s <server>] [-p <port>] [-u <userid>] [-x <password>] imscripter [-s <server>] [-p <port>] [-u <userid>] [-x <password>] -f <scriptfile> imscripter [-s <server>] [-p <port>] [-u <userid>] [-x <password>] -c <command> [<command data>] imscripter [-s <server>] [-p <port>] [-u <userid>] [-x <password>] -c <command> -f <command data file>
The options for this utility are:
Table 75-22 imscripter Command Options
| Option | Description |
|---|---|
|
-c command |
Executes command - see discussion of commands below. |
|
-f file |
The file may contain one or more commands, or a list of mailboxes on which commands are to be executed. See discussion of commands below. |
|
-h |
Displays help for this command. |
|
-p port |
Connects to the given port. The default is 143. |
|
-s server |
Connects to the given server. The default is localhost. The server can be either a host name or an IP address. |
|
-u userid |
Connects as userid. |
|
-v verbosity |
String containing options for printing various information. The options are as follows: E-Show errorsI-Show informational messages P-Show prompts C-Show input commands c-Show protocol commands B-Show BAD or NO untagged responses O-Show other untagged responses b-Show BAD or NO completion results o-Show OK completion results A-Show all of the above The letters designating options can be entered in any order. The default is EPBibo. |
|
-x passwd |
Uses this password. |
The imscripter command supports the following commands:
create <mailbox> delete <mailbox> rename <oldmailbox> <newmailbox< [<partition>] getacl <mailbox> setacl <mailbox> <userid> <rights> deleteacl <mailbox> <userid>
If one or more of the above variables are included, the option executes the given command with that input. For example, create lincoln creates a mailbox for the user lincoln.
If the -f file option is used, the option executes the command on each variable listed in the file. For example:
cat folders-to-create xyz abc def imscripter -u <userid> -x <password> -c create -f folders-to-create #
In addition to the commands which imscripter interprets (above), it will pass thru any raw IMAP command prefixed with an exclamation mark ("!"). For example:
imscripter -u <userid> -x <password> -c \!list "" \* 1) <= OK [CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN BINARY UNSELECT SORT CATENATE URLAUTH LANGUAGE ESEARCH ESORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ENABLE CONTEXT=SEARCH CONTEXT=SORT WITHIN SASL-IR SEARCHRES XSENDER X-NETSCAPE XSERVERINFO X-SUN-SORT ANNOTATE-EXPERIMENT-1 X-UNAUTHENTICATE X-SUN-IMAP X-ANNOTATEMORE XUM1 ID IDLE AUTH=PLAIN] s4u-280rd-zone1-bur02.east.sun.com IMAP4 service (Oracle Communications Messaging Exchange Server 7u4-20.01 64bit (built Nov 21 2010)) 1) <= OK User logged in 2) <= CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN BINARY UNSELECT SORT CATENATE URLAUTH LANGUAGE ESEARCH ESORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ENABLE CONTEXT=SEARCH CONTEXT=SORT WITHIN SASL-IR SEARCHRES XSENDER X-NETSCAPE XSERVERINFO X-SUN-SORT ANNOTATE-EXPERIMENT-1 X-UNAUTHENTICATE X-SUN-IMAP X-ANNOTATEMORE XUM1 ID IDLE 2) <= OK Completed 2) <= LIST (\NoInferiors) "/" INBOX 2) <= LIST (\HasNoChildren) "/" Drafts 2) <= LIST (\HasNoChildren) "/" Sent 2) <= LIST (\HasNoChildren) "/" Trash 2) <= LIST (\HasNoChildren) "/" abc 2) <= LIST (\HasNoChildren) "/" def 2) <= LIST (\HasNoChildren) "/" test2 2) <= LIST (\HasNoChildren) "/" xyz 2) <= OK Completed 3) <= BYE LOGOUT received 3) <= OK Completed #
If you issue the imscripter command without the -f and/or -c switches, it will go into interactive mode. If you did not specify -u, it will prompt for userid. If you did not specify -x, it will prompt for password. You can then type imscripter commands or raw IMAP commands prefixed by "!" and see the response. See discussion of commands above.
For example:
imscripter s4u-280rd-zone1-bur02 userid: <userid> s4u-280rd-zone1-bur02 password for <userid>: 1) <= OK [CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN BINARY UNSELECT SORT CATENATE URLAUTH LANGUAGE ESEARCH ESORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ENABLE CONTEXT=SEARCH CONTEXT=SORT WITHIN SASL-IR SEARCHRES XSENDER X-NETSCAPE XSERVERINFO X-SUN-SORT ANNOTATE-EXPERIMENT-1 X-UNAUTHENTICATE X-SUN-IMAP X-ANNOTATEMORE XUM1 ID IDLE AUTH=PLAIN] s4u-280rd-zone1-bur02.east.sun.com IMAP4 service (Oracle Communications Messaging Exchange Server 7u4-20.01 64bit (built Nov 21 2010)) 1) <= OK User logged in 2) <= CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN BINARY UNSELECT SORT CATENATE URLAUTH LANGUAGE ESEARCH ESORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ENABLE CONTEXT=SEARCH CONTEXT=SORT WITHIN SASL-IR SEARCHRES XSENDER X-NETSCAPE XSERVERINFO X-SUN-SORT ANNOTATE-EXPERIMENT-1 X-UNAUTHENTICATE X-SUN-IMAP X-ANNOTATEMORE XUM1 ID IDLE 2) <= OK Completed imscripter> !select inbox 3) <= FLAGS (\Answered \Flagged \Draft \Deleted \Seen $Forwarded) 3) <= OK [PERMANENTFLAGS (\Answered \Flagged \Draft \Deleted \Seen $Forwarded \*)] 3) <= EXISTS 3) <= RECENT 3) <= OK [UNSEEN 14] 3) <= OK [UIDVALIDITY 1266949413] 3) <= OK [UIDNEXT 354] 3) <= OK [READ-WRITE] Completed imscripter> quit 5) <= BYE LOGOUT received 5) <= OK Completed #
As with interactive mode (above), -s and -p default to localhost and port 143 and imscripter will prompt for -u and -x if not specified.
With -c, you can execute an individual imscripter command and optionally have it operate on several folders. See the example of creating several folders in the discussion of commands above.
As with interactive mode (above), -s and -p default to localhost and port 143 and imscripter will prompt for -u and -x if not specified.
With -f, you can put imscripter and raw IMAP commands in a file and have imscripter execute that script. For example:
cat script create nmo create blah !list "" * imscripter -u <userid> -x <password> -f script #
Notice the above displayed no output. It executed the command but did not display the output. Use the -v switch it specify which output you want to see. For example:
imscripter -u <userid> -x <password> -f script -v A Processing: script, verbosity: A, server: (<ask user>:143) connecting to s4u-280rd-zone1-bur02:143... addcallback CAPABILITY, NO, OK BAD 1) => LOGIN <userid> * *notice imscripter hid the password* 1) <= OK [CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN BINARY UNSELECT SORT CATENATE URLAUTH LANGUAGE ESEARCH ESORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ENABLE CONTEXT=SEARCH CONTEXT=SORT WITHIN SASL-IR SEARCHRES XSENDER X-NETSCAPE XSERVERINFO X-SUN-SORT ANNOTATE-EXPERIMENT-1 X-UNAUTHENTICATE X-SUN-IMAP X-ANNOTATEMORE XUM1 ID IDLE AUTH=PLAIN] s4u-280rd-zone1-bur02.east.sun.com IMAP4 service (Oracle Communications Messaging Exchange Server 7u4-20.01 64bit (built Nov 21 2010)) 1) <= OK User logged in 2) => CAPABILITY 2) <= CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ NAMESPACE UIDPLUS CHILDREN BINARY UNSELECT SORT CATENATE URLAUTH LANGUAGE ESEARCH ESORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ENABLE CONTEXT=SEARCH CONTEXT=SORT WITHIN SASL-IR SEARCHRES XSENDER X-NETSCAPE XSERVERINFO X-SUN-SORT ANNOTATE-EXPERIMENT-1 X-UNAUTHENTICATE X-SUN-IMAP X-ANNOTATEMORE XUM1 ID IDLE 2) <= OK Completed 3) Cmd: create nmo 3) => CREATE nmo 3) <= NO Mailbox already exists *this command failed because it succeeded the first time* 4) Cmd: create blah 4) => CREATE blah 4) <= NO Mailbox already exists *ditto* 5) Cmd: !list "" * 5) => list "" * 5) <= LIST (\NoInferiors) "/" INBOX 5) <= LIST (\HasNoChildren) "/" Drafts 5) <= LIST (\HasNoChildren) "/" Sent 5) <= LIST (\HasNoChildren) "/" Trash 5) <= LIST (\HasNoChildren) "/" abc 5) <= LIST (\HasNoChildren) "/" blah 5) <= LIST (\HasNoChildren) "/" def 5) <= LIST (\HasNoChildren) "/" nmo 5) <= LIST (\HasNoChildren) "/" test2 5) <= LIST (\HasNoChildren) "/" xyz 5) <= OK Completed 7) => LOGOUT 7) <= BYE LOGOUT received 7) <= OK Completed #
imsexport
The imsexport utility exports Messaging Server folders into UNIX /var/mail format folders.
The imsexport utility extracts the messages in a message store folder or mailbox and writes the messages to a UNIX file under the directory specified by the administrator. The file name is the same name as the IMAP folder name. For message store folders that contain both messages and sub-folders, imsexport creates a directory with the folder name and a file with the folder name plus a .msg extension. The folder.msg file contains the messages in the folder. The folder directory contains the sub-folders.
Location: MessagingServer_home/bin
imsexport [-g] [-v 0|1|2] [-f format] [-s mailbox] [-e encoding] -u user -d dir
The options for this command are:
| Option | Description |
|---|---|
|
-d dir |
Specifies the destination directory name where the folders will be created and written. This is a required option. |
|
-e encoding |
Specify an encoding option. |
|
-f format |
Specifies the export format, where format is Solaris, BSD, SYSV or RN. Default is Solaris. The format option impacts the date format used in the "From " line in the mailbox format.The formats are: %a %b %e %H:%M:%S %Y %z (Solaris) %a %b %e %H:%M:%S %Y (BSD) %a %b %e %H:%M %Z %Y (SYSV) %a %b %e %H:%M:%S %Z %Y (RN) |
|
-g |
Specifies debugging mode. |
|
-s folder |
Specifies the source folder to export. |
|
-u user |
Specifies the message store id for a user. Note that this is not necessarily the login id of the user. The message store id is either userid (for default domain users) or userid@domain (for other users). This is a required option. |
|
-v mode |
Specifies verbose mode. The values for mode are 0, 1, and 2. 0 specifies no output. 1 specifies mailbox level output. 2 (default) specifies message level output. |
In the following example, imsexport extracts all email for user smith1. smith1 is a valid user account in the Sun Java System Messaging Server message store. User smith1 has three folders on the store: INBOX (the normal default user folder), private, and private/mom. The destination directory will be /tmp/joes_mail.
% imsexport -u smith1 -d /tmp/joes_mail/
imsexport then transfers each message store folder into a /var/mail conforming file. Thus you will get the following files:
-
/tmp/joes_mail/INBOX
-
/tmp/joes_mail/private
-
/tmp/joes_mail/private.msg
-
/tmp/joes_mail/private/mom
imsimport
The imsimport utility migrates UNIX /var/mail format folders into a Messaging Server message store.
The imsimport utility extracts the messages stored in /var/mail mailboxes and appends them to the corresponding users' mailbox in the Messaging Server message store. Files in the directory that are not in the standard UNIX mailbox format are skipped. If the corresponding users do not exist in the message store, imsimport creates them. When the user quota is exceeded, imsimport bypasses the message store quota enforcement, so the user does not receive an "over quota" message.
The imsimport utility can be run while Messaging Server is running. If mail delivery is enabled for the mailbox you are importing, old mail can get mixed with new mail, so you might want to hold the delivery of this user during the migration. Mailbox access should not be a problem.
When imsbackup, imsrestore, imsimport or any processing intensive operation takes significantly more system resources than normal, and continues doing so longer than the msprobe interval, there may be a temporary backlog of DB transaction log files to be cleared. If there are more files than specified in local.store.maxlog, then msprobe may erroneously restart all the processes during a restore. To prevent this from happening, disable msprobe during the imsbackup, imsrestore, and imsimport.
Note:
imsimport does not use the IMAP server. However, the stored utility must be running to maintain message store integrity. The LDAP server should be running if imsimport is expected to create new users.Location: MessagingServer_home/bin/
imsimport -u <user> -s _file_ [-c y|n] [-d <mailbox>] [-e <encoding>] [-b] [-g] [-i] [-n] [-v <mode>]
The options for this command are:
Table 75-24 imsimport Command Options
| Option | Description |
|---|---|
|
-b |
Subscribes the destination mailbox folder when a new folder is created by the imsimport utility. |
|
-c y|n |
Provides an answer to the question: "Do you want to continue?" if an error occurs. Specify y for yes, n for no. |
|
-d mailbox |
Specifies the destination mailbox where the messages will be stored. |
|
-e encoding |
Specify an encoding option. |
|
-g |
Specifies debugging mode. |
|
-i |
Ignores the content-length field |
|
-n |
Creates a new mailbox with a .date extension if the mailbox exists. The .date extension is in the following form: .mmddyy.HHMMSS The month is specified by mm. The day is specified by dd. The year is specified by yy. For example, 052097 specifies May 20 in the year 1997. The time of day is specified by HHMMSS. For example 110000 specifies 11:00am. |
|
-s file |
Specifies the UNIX folder's file name from which the messages are to be imported. The file option must be a full path name. This is a required option. |
|
-u user |
Specifies the message store identification for a user. Note that this should be identical in content and case to the UID attribute of the user's LDAP entry. If it is not the same, users will not be able to login to their INBOXES. |
|
-v mode |
Specifies verbose mode. The values for mode are 0, 1, and 2. 0 specifies no output. 1 specifies mailbox level output. 2 (default) specifies message level output. |
imsimport migrates the specified /var/mail/folder for the specified user to the Messaging Server message store. If the destination folder is not specified, imsimport calls the destination folder by the same name as the source folder. In the following example, the command migrates the default /var/mailINBOX for the user smith, to the INBOX.
imsimport -u smith -s /var/mail/smith -d INBOX
Similarly, if you are trying to move a folder called test from /home/smith/folders/ to the Messaging Server message store, use the following command:
imsimport -u smith -s /home/smith/folders/test -d test
If a destination folder called test already exists in the Messaging Server message store, imsimport appends the messages to the existing folder in the mailbox.
imsrestore
The imsrestore utility restores messages from the backup device into the message store. See "Backing Up and Restoring the Message Store" for more information.
When imsbackup, imsrestore, imsimport or any processing intensive operation takes significantly more system resources than normal, and continues doing so longer than the msprobe interval, there may be a temporary backlog of DB transaction log files to be cleared. If there are more files than specified in local.store.maxlog, then msprobe may erroneously restart all the processes during a restore. To prevent this from happening, disable msprobe during the imsbackup, imsrestore, and imsimport.
Location: MessagingServer_home/bin
imsrestore -f <device>|- [-b <blocking_factor>] [-c y | n] [-d <path>] [-D] [-e <encoding>] [-h] [-i|-E] [-m <file>] [-n] [-p] [-P partition] [-r <file>] [-s] [-S] [-t] [-u <file>] [-g] [-v 0|1|2|3|4|5] [-x] [<name> . . .]
The options for this command are:
Table 75-25 imsrestore Options
| Option | Description |
|---|---|
|
-b blocking_factor |
Indicates the blocking factor. Everything read on the device is performed by blocks of the size 512 x blocking_factor. The default is 20. Note: this number needs to be the same blocking factor that was used for the backup. |
|
-c y | n |
Provides an answer to the question: "Do you want to continue?" if an error occurs. Specify y for yes, n for no. |
|
-d path |
Restore all mailboxes under <path> (for multiple incremental restore). |
|
-e encoding |
Mailbox name encoding (example: IMAP-mailbox-name). |
|
-E |
Updates and expunges existing messages. |
|
-f [device|filename|-] |
Specify the device or file from which to read the backup data. Use -f- to read from stdin (ie, to pipe the data from some other command). |
|
-h |
Dumps the header. |
|
-g |
Debug mode. |
|
-i |
Ignores existing messages. Does not check for existing messages before restore. Note that if you specify the -i option, you may have duplicate messages after the restore, since the -i option supersedes your ability to check for duplicates. |
|
-m file |
This mapping file is used when renaming user IDs. The format in the mapping file is oldname=newname with one set of names per line. For example: a=x b=y c=z where a, b, and c are old names and x, y, and z are new names. For users in a hosted domain, add @domain_name to the old and new user IDs. This option is used to rename user IDs when restoring from a Messaging Server 5.x, 6.x, or 7.x imsbackup file. Use the -u option when restoring from a SIMS 4.0 imbackup file. |
|
-n |
Creates a new mailbox with a .date extension (if the mailbox exists). By default, messages are appended to the existing mailbox. |
|
-p |
Restore mailboxes to original partition. |
|
-P |
Restore all mailboxes to this partition (ignore -p and mailMessageStore). |
|
-r file |
Reference file name (will restore all links in file). |
|
-s |
Used to restore a large file without using large file seeking. |
|
-t |
Prints a table of contents, but restore is not performed. |
|
-u file |
This file contains the object names (entire message store, user, group, mailbox, and so on) to restore. See name for a list of backup objects. For restoring SIMS 4.0 data into a Message Server 5.x, 6.x, or 7.x system, you can specify or rename users with -u file. Users should have one name per line. If you rename users, the format of file is oldname=newname with one set of names per line. For example: joe bonnie jackie=jackie1 where joe and bonnie are restored, and jackie is restored and renamed to jackie1. Note that full object pathnames are not needed for user IDs. |
|
-v [0|1|2|3|4|5] |
Executes the command in verbose mode. 0= no output 1= output at mailbox level 2= output at message level (default) 3= print meta data (for use with -t only) 4=print object level meta data (for use with -t only) 5=print the backup data of mailboxes and messages (for use with -t only) |
|
-x |
Restores stubs into message files. |
|
-S |
Not Applicable. |
|
name |
Can be 1) logical pathname of the backup object, 2) user ID, 3) mailbox. See "imsbackup" for description. |
The following example restores the messages from the file backupfile:
imsrestore -f backupfile
The following example restores the messages for joe from the file backupfile:
imsrestore -f backupfile /primary/user/joe
The following example lists the content of the file backupfile:
imsrestore -f backupfile -t
The following example renames users in the file mapfile:
imsrestore -m mapfile -f backupfile
where the mapfile format is oldname=newname:
userA=user1 userB=user2 userC=user3
mboxutil
The mboxutil command lists, creates, deletes, renames, or moves mailboxes (folders). You can use the mboxutil command to report quota information, restore expunged messages, and list mailbox subscriptions.
Note:
Do not "kill" the mboxutil process (SIGKILL (kill -9) command) in the middle of execution. Otherwise, you will need to restart the Messaging Server process.You can use POSIX regular expressions in the mboxutil command.
Requirements: Must be run locally on the Messaging Server. The stored utility must also be running.
Location: MessagingServer_home/bin
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.
List mailboxes:
mboxutil -l [-B <bound>] [-E <encoding>] [-p <MUTF7 IMAP pattern> | -P <regular expression>] [-x | -s] [-D] [-z]
Create mailboxes:
mboxutil -c [-E <encoding>] {<mailbox> | -f <file>}
Delete mailboxes:
mboxutil -d [-E <encoding>] { -p <MUTF7 IMAP pattern> | -P <regular expression> | -f <file> | <mailbox> }
Rename mailboxes:
mboxutil -r [-E <encoding>] { <oldname> <newname> | -f <file> } [<partition>]
Expunge mailboxes:
mboxutil -e [-E <encoding>] [-p <MUTF7 IMAP pattern> | -P <regular expression> ]
Schedule cleanup:
mboxutil -C [-g num] [-E encoding] [-p <MUTF7 IMAP pattern> | -P <regular expression>]
List orphan/inactive mailboxes:
mboxutil -o [-w <file> ] [-t <number of days>]
Restore expunged messages that have not been purged:
mboxutil -R [-E <encoding>] <mailbox name>
List personal mailbox subscriptions:
mboxutil -S [-n [-f <file>] | -u -f <file>]
The options for this command are:
Table 75-26 mboxutil Command Options
| Option | Description |
|---|---|
|
-B bound |
Uses the user specified delimiter while listing the mailboxes. The option is always used with the -l option like mboxutil -l [-B bound]. The given bound can be any string. |
|
-c mailbox |
Creates the specified mailbox. A mailbox must exist before creating a secondary mailbox. |
|
-C |
Schedules cleanup immediately. Cleanup is automatically scheduled when mailboxes are expunged. This command can be used to schedule cleanup manually when:
|
|
-d mailbox |
Deletes the specified mailbox. To delete a user from the message store, use the following value for -dmailbox: user/userid/INBOX For example, to delete the user john from the message store, use -d user/john/INBOX. To delete the mm folder in the user john's mailbox, use -d user/john/mm. The recommended method to delete a user is to mark the user status as deleted in the LDAP directory (by using the Delegated Administrator utility commadmin user delete command or the Delegated Administrator console.). Next, remove resources from the user that have been marked as deleted for a period longer than a specified number of days by using the msuserpurge command for all mail services and csclean for all calendar services. Finally, use the commadmin domain purge command to permanently remove the users. If you use the Delegated Administrator utility as described in the preceding paragraph, you do not have to use the mboxutil -d command to delete a mailbox. Note that -p and -P can be used in conjunction with one another. |
|
-D |
Lists deleted mailboxes. When used with the -l option, lists deleted folders (as long as if the you enabled the store.mailboxpurgedelay option before the delete). |
|
-e |
Expunges all deleted messages in the message store. This option also can be used with the -p pattern or -P regexp options to expunge all deleted mailboxes with names that match pattern or regexp. |
|
-E encoding |
Specifies character set encoding used for the folder name display or the input of localized mailbox names. The default is that the folder name is displayed (or input accepted) in the localized character set (that is, in the form the user would expect to see). Using "-E MUTF-7" causes the folder name to be displayed (or input accepted) in the form used internally by the message store. For more information, see "Localized Mailbox Names in imexpire." |
|
-f file |
Specifies a file that stores mailbox names. The -f option can be used with the -c, -r, -S, or -d options. The file contains a list of mailboxes on which the mboxutil command is executed. The following is an example of entries in a data file: user/daphne/INBOXuser/daphne/projxuser/daphne/mm |
|
-g num |
Minimum cleanup size, num must be > 0. Default is store.cleanupsize |
|
-l |
Lists all of the mailboxes on a server. mboxutil -l correctly displays characters associated with the system locale under which mboxutil is being executed. The -P regexp option accepts international characters. |
|
-n |
Lists personal, non-existing mailbox subscriptions. The -n option is used with the -S option. |
|
-o |
Checks for orphaned accounts. This option searches for inboxes in the current messaging server host that do not have corresponding entries in LDAP. For example, the -o option finds inboxes of owners who have been deleted from LDAP or moved to a different server host. For each orphaned account it finds, mboxutil writes the following command to the standard output: mboxutil-d user/userid/ INBOX unless -w is specified |
|
-p pattern |
When used with the -l option, lists only those mailboxes with names that match pattern. Can also be used with the -d or -e option to delete or expunge mailboxes with names that match pattern. You can use IMAP wildcards. This option expects a pattern in IMAP M-UTF-7 format. This is not the recommended way to search for non-ASCII mailboxes. To search for non-ASCII mailboxes, use the -P option. |
|
-P regexp |
Lists, deletes, or expunges only those mailboxes with names that match the specified POSIX regular expression. This option expects the regexp in the local character encoding. |
|
-q domain |
Obsolete. Use imquotacheck -d domain |
|
-r oldnamenewname [partition] |
Renames the mailbox from oldname to newname. Optionally, to move a folder from one partition to another, specify the new partition with the partition option. This option can be used to rename a user. For example, mboxutil -r user/user1/INBOX user/user2/INBOX moves all mail and mailboxes from user1 to user2, and new messages will appear in the new INBOX. (If user2 already exists, this operation fails.) Folders are cleaned and purged automatically during the rename process. When used with imsbackup and imsrestore, you can use mboxutil -r to transfer ownership of a set of shared folders to another user while preserving the readership settings. |
|
-R mailbox |
Restores deleted messages that have not yet been purged. When a mailbox is expunged or expired, the uids of the deleted messages are stored in a store.exp file. The messages are physically removed by impurge depending on the values of store.cleanupsize and store.cleanupage. If expunge or expire is done by mistake, this option can be used to restore the deleted messages that have not yet been purged by impurge into the original mailbox. |
|
-s |
When used with the -l option, displays only the mailbox name. No other data is displayed. |
|
-S |
Lists personal mailbox subscriptions. When used with the -n option, the -S option lists or unsubscribes non-existing mailbox subscriptions. |
|
-t days |
When used with the -o option, lists the mailboxes that have not been accessed in a specified number of days (days). Thus, the -t option identifies inactive mailboxes (based on last-accessed date) together with orphaned mailboxes (mailboxes that do not have corresponding user entries in the LDAP directory). To identify (list) the orphaned and inactive mailboxes, use mboxutil -o -w file-t num. To delete these orphaned and inactive mailboxes, use mboxutil -d -f file, where file is the same file as the one passed to -w in the preceding command. To use this feature, the configuration variable local.enablelastaccess must be enabled for at least the number of days specified with the -t option. |
|
-u |
Unsubscribes personal non-existing mailbox subscriptions listed in the file specified with the -f file option. |
|
-w file |
Used with the -o option. Writes to a file the mailbox names generated by the -o option (which identifies orphaned accounts). |
|
-x |
When used with the -l option, displays the path and access control for a mailbox. |
|
-z |
When used with the -l option, displays a count of the mailboxes displayed. |
Note:
When using the separator, check output consistency by trying the separator string as a single or double quoted string with escape sequences if required.To list all mailboxes for all users:
mboxutil -l
To list all mailboxes and also include path and ACL information:
mboxutil -l -x
To list all mailboxes displaying only the mailbox names:
mboxutil -l -s
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 Desdemona's mail folder from memos to memos-april:
mboxutil -r user/desdemona/memos user/desdemona/memos-april
To schedule a cleanup of Dorothea's mailbox if there are at least 50 expunged messages:
$ mboxutil -C -g 50 -p user/dorothea/*
To restore messages that were expunged from Desdemona's memos mail folder in the last 24 hours:
mboxutil -R -t 24 user/desdemona/memos
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
To list orphaned mailboxes and mailboxes that have not been accessed in 60 days:
mboxutil -o -w orphanfile -t 60
The preceding example writes the list of orphaned and inactive mailboxes to a file named orphanfile.
To delete orphaned and inactive mailboxes:
mboxutil -d -f orphanfile
where orphanfile is a file that has stored a list of orphaned and inactive mailboxes identified with the -o option.
To list personal, non-existing mailbox subscriptions for user mailboxes listed in a file named orphanfile:
mboxutil -S -n -f orphanfile
To unsubscribe the non-existing mailbox subscription list generated by the previous example:
mboxutil -S -u -f orphanfile
The mboxutil command has stable output formats that we support and allow customers to parse. mboxutil -l -p user/%/INBOX -s lists all accounts (INBOXES) in the store. mboxutil -o -w -t lists inactive accounts. The formats are the same: one line per mailbox name. To generate an active list, remove the inactive mailboxes from the all mailbox list. Sample mboxutil output:
user/joe/INBOX user/mary/INBOX
Mechanism to Schedule Cleanup Immediately
Normally, cleanup is scheduled automatically when mailboxes are expunged. This command can be used to schedule cleanup manually when:
-
The storage is very full.
-
store.cleanupsize is reduced.
For example, the following command schedules cleanup of mailboxes with at least 50 expunged messages. Messages are removed when store.cleanupage has expired.
$ mboxutil -C -g 50
mkbackupdir
The mkbackupdir utility creates and synchronizes the backup directory with the information in the message store. It is used in conjunction with Solstice Backup (Legato Networker). The backup directory is an image of the message store. It does not contain the actual data. mkbackupdir scans the message store's user directory, compares it with the backup directory, and updates the backup directory with the new user names and mailbox names under the message store's user directory.
The backup directory is created to contain the information necessary for Networker to backup the message store at different levels (server, group, user, and mailbox). The following figure displays the structure.
Location: MessagingServer_home/bin
The variables in the backup directory contents are:
Table 75-27 mkbackupdir Variables
| Variable | Description |
|---|---|
|
BACKUP_ROOT |
Message store administrator root directory. |
|
partition |
Store partition. |
|
group |
System administrator-defined directories containing user directories. Breaking your message store into groups of user directories allows you to do concurrent backups of groups of user mailboxes.To create groups automatically, specify your groups in the MessagingServer_home/config/backup-groups.conf file. The format for specifying groups is:groupname= patterngroupname is the name of the directory under which the user and mailbox directories will be stored, and pattern is a folder name with IMAP wildcard characters specifying user directory names that will go under the groupname directory. |
|
user |
Name of the message store user. |
|
folder |
Name of the user mailbox. |
|
mailbox |
Name of the user mailbox. |
The mkbackupdir utility creates:
-
A default group directory (ALL) or the group directories defined in the backup-groups.conf configuration file. The following is a sample backup-groups.conf file:
groupA=a* (regexp) groupB=b* groupC=c* . . .
-
A user directory under the backup directory for each new user in the message store.
-
A 0 length mailbox file for each mailbox.
-
A .nsr file for each subdirectory that contains user mailboxes.
The .nsr file is the NSR configuration file that informs the Networker to invoke imsasm. imsasm then creates and interprets the data stream.
Each user mailbox contains files of zero length. This includes the INBOX, which is located under the user directory.
Note:
Make sure the backup directory is writable by the message store owner (mailsrv).mkbackupdir [-a <name_of_asm>] [-i | -f | -u] [-g] [-t <number_of_threads>] [-e <encoding>] [-v] -p <directory>
The options for this command are:
Table 75-28 mkbackupdir Options
| Option | Description |
|---|---|
|
-a name_of_asm |
Creates .nsr files using the specified asm name. This can be used for when you have multiple instances of Messaging Server as in symmetric HA environments. |
|
-e encoding |
Specify an encoding option. |
|
-f |
Backs up the folders only. By default, all mailboxes are backed up. |
|
-g |
Executes the command in debug mode. |
|
-i |
Backs up the inbox only. By default, all mailboxes are backed up. |
|
-p directory |
Specifies the directory for the backup image. This is a required option when local.store.backupdir is not configured.The max_thread option must be set between 1 and 1024.Note: The Networker has a limitation of 64 characters for saveset name. If your default backup directory pathname is too long, you should use this option to specify another pathname. |
|
-t number_of_threads |
Specifies the number of threads that can be used to create the backup directory. The default is one thread for each partition, which is usually adequate. If you have many partitions, and you do not want mkbackupdir to consume all your resources, you can lower this number. |
|
-u |
User level backup. Instead of backing up each folder as a file, create a backup file per user. |
|
-v |
Executes the command in verbose mode. |
To create the mybackupdir directory, enter the following:
mkbackupdir -p /mybackupdir
msprobe
msprobe is a daemon that probes servers to see if they respond to service requests. When msprobe detects a possible problem, it can, depending upon other configuration, potentially let the Watcher know (at which point the Watcher can attempt to restart a troubled component) and/or generate an alarm message; see the Watcher options and Alarm options, respectively in the Messaging Server Reference.
For additional information on msprobe, see the Messaging Server Reference.
Location: MessagingServer_home/lib
msprobe [-d] [-n] [-r] [server]
The options for this command are:
Table 75-29 msprobe Command Options
| Option | Description |
|---|---|
|
-d |
Debug mode. |
|
-n |
Disable restart. |
|
-r |
Report the server, port, response_time, status, message to stdout. Status is: OK, SLOW, or BAD. Response time is in millisecond. |
|
server |
The accepted values for server are: imap pop http ens cert job_controller smtp lmtp submit metermaid deploymap If server is not specified, all enabled servers are probed. |
$ msprobe -r imap,143,0,OK,"No error" pop,110,-1,BAD,"Connection refused" ens,7997,0,OK,"No error" http,8990,0,OK,"No error" job_controller,27442,0,OK,"No error" smtp,25,35,SLOW,"No error" submit,587,1,OK,"No error" $ msprobe -r imap imap,143,0,OK,"No error"
msuserpurge
When user and domain mailboxes are marked for deletion, the msuserpurge command purges those user and domain mailboxes from the message store. Specifically, this command scans the following domain and user status attributes in LDAP for a value of deleted: inetDomainStatus, mailDomainStatus, inetUserStatus, mailUserStatus. This command can be run at the command line, or can be scheduled for execution with the configutil option local.sched.userpurge.
Requirements: If run manually, it must be manually run locally on the messaging server. Make sure that the environment variable ConfigRoot is set to MessagingServer_home/config.
Location: MessagingServer_home/lib
msuserpurge [-v|-r] [-d <domain>] [-g <days>]
The options for this command are:
Table 75-30 msuserpurge Options
| Option | Description |
|---|---|
|
-v |
Verbose (list deleted users). |
|
-r |
Report (list all users, do not purge). |
|
-g days |
Specify a grace period. |
|
-d domain |
Specify a domain. |
msuserpurge -d example.com -g 0
readership
The owner of an IMAP folder can grant permission for other users to access the folder. A folder that other users are allowed to access is called a shared folder. See "Managing Shared Folders" for more information. Users can modify the access rights on folders if their mail provides an interface to the SETACL IMAP commands. Administrators can use the readership utility to set or remove access rights on the folder, and to see how many users other than the owner are accessing a shared folder.
To list the rights on all shared folders, the mail administrator can use the imcheck -d lright.db command. To list rights on individual folders, use the mboxutil -lxp folder command.
Requirements: Must be run locally on the Messaging Server. The stored process must also be running.
Location: MessagingServer_home/bin/
readership [ -d <days> |-p <months> ] readership -r <folder pattern> readership -s <foldername> <identifier> <acl_right> readership -s -m <folder-pattern> <identifier> <acl_right> readership [-e <encoding>] -s [ -m pattern | mailbox ] <identifier> <acl_right>
To remove all rights for a user who has previously been granted access, set that user's rights to a null list, for example:
readership -s user/<userid>/<folder> <user-to-remove> ''
The options for this command are:
Table 75-31 readership Command Options
| Option | Description |
|---|---|
|
-d days |
Counts as a reader any identity that has selected the shared IMAP folder within the indicated number of days. The default is 30. |
|
-p months |
Does not count users who have not selected the shared IMAP folder within the indicated number of months. The default is infinity and removes the seen flag data for those users. This option also removes the seen flag data for those users from the store. |
|
-r folder_pattern |
Lists the last access time of the folders matching the pattern. |
|
-s folderidentifieracl_right |
Sets ACL rights character for folder, where folder is the name of the folder for which you are setting rights, identifier is the person or group to whom you are assigning the rights, and acl_rights are the rights you are assigning. See Table 75-32, "ACL Rights Characters". To remove a rights setting, specify a null set of rights. |
|
-s -m folder_patternidentifieracl_right |
Sets ACL rights as -s but on all folders matching the specified pattern. |
|
-e encoding |
Specifies character set encoding used for the folder name display or the input of localized mailbox names. The default is that the folder name is displayed (or input accepted) in the localized character set (that is, in the form the user would expect to see). Using "-e MUTF-7" causes the folder name to be displayed (or input accepted) in the form used internally by the message store. |
Table 75-32 ACL Rights Characters
| Character | Description |
|---|---|
|
l |
lookup - User can see and subscribe to the shared folder. (IMAP commands allowed: LIST and LSUB) |
|
r |
read - Users can read the shared folder. (IMAP commands allowed: SELECT, CHECK, FETCH, PARTIAL , SEARCH, COPY from the folder) |
|
s |
seen - Directs the system to keep seen information across sessions. (Set IMAP STORESEEN flag) |
|
w |
write - Users can mark as read, and delete messages. (Set IMAP STORE flags, other than SEEN and DELETED) |
|
i |
insert - Users can copy and move email from one folder to another. (IMAP commands allowed: APPEND, COPY into folder) |
|
p |
post - Users can send mail to the shared folder email address. (No IMAP command needed) |
|
k |
create - Users can create new sub-folders. (IMAP command allowed: CREATE) |
|
x |
delete - Users can delete entries from the shared folder. (IMAP commands allowed: EXPUNGE, set STOREDELETED flag) |
|
a |
administer - Users have administrative privileges. (IMAP command allowed: SETACL) |
|
t |
delete - For messages, sets or clears \DELETED flag via STORE, or sets \DELETED flag during APPEND/COPY. |
|
e |
expunge - Performs EXPUNGE and expunge as a part of CLOSE. |
|
n |
access - Retrieves annotation information about the folder (see RFC 5257 at |
Example
bin/readership -s -m user/kellyc/a\* barbs lr user/kellyc/abc: OK user/kellyc/abc/123: OK user/kellyc/abc/456: OK
reconstruct
The reconstruct utility rebuilds one or more mailboxes, or the master mailbox file (the mailboxes database), and repairs any inconsistencies. Use this utility to recover from almost any form of data corruption in the message store.
A mailbox consists of files under the user partition directory. The mailboxes database is the mboxlist database.
Requirements: Must be run locally on the Messaging Server host; the stored utility must also be running.
Location: MessagingServer_home/bin
reconstruct [-n | -f] [-i] [-x] [-p partition] {-r [<mailbox...>] | <mailbox...>}
reconstruct [-p <partition> [ -u <user> ] ] -m
reconstruct -a [-n | -f] [-t <nthreads>] [<mailbox...>]
reconstruct -A [-u userid]
reconstruct -l
reconstruct -q
reconstruct -s
The options for this command are:
Table 75-33 reconstruct Options
| Option | Description |
|---|---|
|
-a mailbox... |
Addresses a user's mailbox comprehensively. If reconstruct -a -f is run, a full repair and reparse is forced. If reconstruct -a -n is run, only a consistency check is run, printing out errors found in the folder. This can be useful to catch issues before fixing them. Since there are many recovery functions embedded in the store libraries, running -n might still fix and modify the folder to some degree. |
|
-A [-u userid] |
Repairs the annotation database. |
|
-i |
Sets the store.idx file length to zero before reconstructing. |
|
-f |
Forces reconstruct to perform a fix on the mailbox or mailboxes. |
|
-x |
Recovers partially delivered messages. |
|
-l |
Reconstructs lright.db. |
|
-m |
Performs a consistency check and, if needed, repairs the mailboxes database. This option examines every mailbox it finds in the spool area, adding or removing entries from the mailbox's database as appropriate. The utility prints a message to the standard output file whenever it adds or removes an entry from the database. Specifically it fixes folder.db, quota.db, and lright.db |
|
-n |
Checks the message store only, without performing a fix on the mailbox or mailboxes. The -n option cannot be used by itself unless a mailbox name is provided. When a mailbox name is not provided, the -n option must be used with the -r option. The -r option may be combined with the -p option. For example, any of the following commands are valid:reconstruct -n user/dulcinea/INBOXreconstruct -n -rreconstruct -n -r -p primaryreconstruct -n -r user/dulcinea |
|
-e |
Obsolete, see mboxutil -R. |
|
-o |
Obsolete, see mboxutil -o. |
|
-o-d filename |
Obsolete, see mboxutil -o. |
|
-p partition |
The -p option is used with the -m option and limits the scope of the reconstruction to the specified partition. If the -p option is not specified, reconstruct defaults to all partitions. Specifically it fixes folder.db and, quota.db, but not lright.db. This is because fixing the lright.db requires scanning the acls for every user in the message store. Performing this for every partition is not very efficient. To fix lright.db run reconstruct -l. Specify a partition name. Do not use a full path name. |
|
-q |
Fixes any inconsistencies in the quota subsystem, such as mailboxes with the wrong quota root or quota roots with the wrong quota usage reported. The -q option can be run while other server processes are running. |
|
-r [mailbox] |
Repairs and performs a consistency check of the partition area of the specified mailbox or mailboxes. The -r option also repairs all sub-mailboxes within the specified mailbox. If you specify -r with no mailbox argument, the utility repairs the spool areas of all mailboxes within the user partition directory. |
|
-s |
Repairs subscriptions. |
|
-t nthreads |
Performs a multithreaded reconstruct -a with nthreads threads (if -t is not specified, nthreads is chosen automatically, single-threaded if specific mailbox is specified). |
|
-u user |
The -u option is used with the -m option and limits the scope of the reconstruction to the specified user. The -u option must be used with the -p option. If the -u option is not specified, reconstruct defaults to all partitions or to the partition specified with the -p option. Specify a user name. Do not use a full path name. |
The mailbox argument indicates the mailbox to be repaired. You can specify one or more mailboxes. Mailboxes are specified with names in the format user/userid/sub-mailbox, where userid is the user that owns the mailbox. For example, the inbox of the user dulcinea is entered as: user/dulcinea/INBOX.
The following command performs a reconstruct on a specific mailbox:
reconstruct user/dulcinea/INBOX
The following checks the specified mailbox, without performing a reconstruct:
reconstruct -n user/dulcinea/INBOX
The following command checks all mailboxes in the message store:
reconstruct -n -r
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.
reconstruct -r first runs a consistency check. It reports any inconsistencies 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 the discussion about reconstruct Performance below.) 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
reconstruct -r -f focuses on fixing the folder index files. It assumes the folder record is good, and the peruser record is good. There are other commands to address these other data areas, such as reconstruct -m.
reconstruct -a attempts to address these all at once.
So if you think you need to repair an index file, but you're not sure if it is in the folder.db, you should not need to worry about running a reconstruct -m first, and whether the index corruption will be handled correctly there, or if both these will result in something that will conflict with the peruser entry later.
If you know your problem is with the index file, and there are no other complications, then you can go ahead and use reconstruct -r -f to save time.
Checking and Repairing Mailboxes
To perform a high-level consistency check and repair of the mailboxes database:
reconstruct -m
To perform a consistency check and repair of the primary partition:
reconstruct -p primary -m
Note:
Running reconstruct with the -P and -m flags together will not fix lright.db. This is because fixing the lright.db requires scanning the ACLs for every user in the message store. Performing this for every partition is not very efficient. To fix the lright.db run reconstruct -lTo perform a consistency check and repair of an individual user's mailbox named john:
reconstruct -p primary -u john -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 store_root/mboxlist.
-
Restart the server processes.
-
Run reconstruct -m to build a new mailboxes database from the contents of the spool area.
-
The time it takes reconstruct to perform an operation depends on the following factors:
-
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. Note that reconstruct is designed to run with the store services up. It is not necessary to keep the store offline to run reconstruct.
The reconstruct -r option performs an initial consistency check; this check improves reconstruct performance depending on how many folders must be rebuilt. The following performance was found with a system 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.refresh
The refresh utility refreshes the configuration of the specified messaging server processes (SMTP, IMAP, POP, STORE, HTTP, ENS, SCHED). It is used when an option for one of the services has been modified and you wish this option to take effect.
Location: MessagingServer_home/bin
refresh [ -h | <service>]
The options for this command are:
Table 75-34 refresh Command Options
| Option | Description |
|---|---|
|
-h |
Show usage statement and list available services that can be refreshed. |
|
service |
Refresh just the specified service. Accepted values are:
watcher
metermaid
store
imap
pop
cert
http
sched
dispatcher
job_controller
mmp
mta
If no components are specified, all enabled services will be refreshed. |
The following command refreshes the scheduler utility:
refresh sched
If refresh does not cause the change to take effect, then stop and restart the service.
rehostuser
The rehostuser utility enables you to move a Messaging Server user's mail store from one mailhost to another. It also disconnects any active session, locks the store to ensure atomicity of the move from the user's perspective (no loss of data, flag change, and so on), changes the user's LDAP entry, flushes LDAP caches as necessary, and causes any queued mail to be rerouted to the new store.
Requirements: The following setup and configuration is required before you can use rehostuser:
-
Ensure that both the source and destination mailhosts are running Messaging Server 8.0.1 or later.
-
Ensure that both the source and destination mailhosts have IMAP IDLE configured. See "Configuring IMAP IDLE" for more information.
-
Configure ssh on the source and destination mail hosts to allow the mail server user to perform a remote login. Even if you start rehostuser as root, it still needs to run and execute ssh as the mail server user.
-
Make sure that ugldapbinddn has read and write access to the mailHost, mailUserStatus, and mailMessageStore attributes. New installations of Messaging Server should have this access made as part of the installation or upgrade process. The rehostuser utility checks for these permissions at startup and exits with an error if the permissions are insufficient.
-
The source mailhost must be capable of sending mail to the destination mailhost. In particular, the tcp_intranet channel on the source mailhost must be open for relaying, the mail must be routable to the new mailhost (directly or following mx records), and the destination mailhost must accept mail coming from the source mailhost.
-
rehostuser needs to consider LDAP replication delay. If either the source or destination Messaging Server system (or both) are configured to use an LDAP replica server instead of a master, there may be problems where attribute changes do not show up on the replica as quickly as required. This issue can be addressed as follows:
-
If a Messaging Server points to a single Directory Server, configure the Directory Server in multi-master replication (MMR) mode so that it writes updates to its local database and replicates the change. (Note that MMR is the recommended way to setup Directory Server as opposed to the old slave/master model where slaves refer writes to the master, then have to wait for replication to get the updated data).
-
If Directory Server failover capability is needed, use Directory Server proxy and enable one of the client affinity modes that guarantees that any single client will always see the updated data it just wrote.
-
OpendDS 2.0, (possibly released 03/2009), may offer an assured replication feature where once a write is committed, it is guaranteed that the whole farm of replicated
-
rehostuser -u userid -d mailhost [-p partition] [-c imsconnutil] [-b imsbackup] [-s ssh] [-r imsrestore] [-e] [-o iss_src -t iss_dest -y scp_user [-z src_path] [-w dest_path]]
The options for this command are:
Table 75-35 rehostuser Options
| Option | Description | Default | Notes |
|---|---|---|---|
|
-u |
Specifies the user to move. |
NA |
NA |
|
-d |
Specifies the fully qualified domain name of the destination mailhost. |
NA |
NA |
|
-p |
Specifies the destination partition. |
NA |
NA |
|
-c |
Specifies the imsconnutil path |
MessagingServer_home/bin. |
NA |
|
-b |
Specifies the imsbackup path |
MessagingServer_home/bin. |
NA |
|
-s |
Specifies the ssh path |
/usr/bin/ssh |
Do not substitute rsh for ssh. The rsh command cannot pass failure status from the imsrestore command. |
|
-r |
Specifies the imsrestore path on the remote host. |
MessagingServer_home/bin |
NA |
|
-e |
Specifies extended availability of user's mailbox during move. |
NA |
In this mode, Messaging Server performs a full backup and a remote restore without locking the user out of the system. Once the full backup and restore are complete, the user is locked out and Messaging Server performs an incremental backup and restore to take care of any changes that occurred since the start time of the full backup. |
|
-x |
Moves the expunged message files. |
NA |
NA |
|
-n |
Does not remove the source mailbox. |
NA |
NA |
|
-o |
Moves the ISS index from the specified source host. |
NA |
NA |
|
-t |
Moves the ISS index to the specified destination host. |
NA |
NA |
|
-z |
Specifies the ISS source installation path. |
IndexingServer_home |
NA |
|
-w |
Specifies the ISS destination installation path. |
Source installation path |
NA |
|
-y |
ISS secure copy (scp) user name. |
NA |
NA |
This example shows how to move user2 to mail server bigdipper where the Messaging Server software is installed in the /opt/sun/comms/messaging directory and the mail server user is mailuser.
rehostuser -u user2 -d bigdipper.example.com -r /opt/sun/comms/messaging/bin/imsrestore -s "/usr/bin/ssh -x -l mailuser" disconnecting user2 -------------------------------------------- Tape Version : 2 Backup Date : 2008/01/08 17:45:16 Message Store : host1.example.com Block factor : 20 -------------------------------------------- /second/user/user2/INBOX restoring... /second/user/user2/INBOX/1 restoring... /second/user/user2/INBOX/2 restoring... /second/user/user2/INBOX/3 restoring... /second/user/user2/folder20 restoring... /second/user/user2/folder22 restoring... /second/user/user2/folder33 restoring... /second/user/user2/folder38 restoring... /second/user/user2/folder49 restoring... Mailbox user2 copied successfully. Updated LDAP entry for uid=user2, ou=People, o=example.com, o=usergroup Source mailbox deleted successfully.
relinker
Note:
The relinker feature is intended to repair the situation where the normal single-copy nature of the message store has become broken for some reason. You should only need to use the relinker if you have done something which could have caused duplicate messages to become individual copies instead of the normal single-copy. This feature is not the normal way the store normally accomplishes its single-copy feature. You should not need to keep the real-time relinker feature enabled for long periods of time. You should not need to use the relinker command on an ongoing basis. You should only need this feature if you have done (or will soon be doing) something which would break the single-copy feature of the store. For more information about single-copy, see the discussion in "How the Message Store Works."relinker finds and relinks duplicate messages. Refer to "Reducing Message Store Size Due to Duplicate Storage" for more information.
Requirements: You may run relinker as root or mailsrv.
Location: MessagingServer_home/bin
relinker [-p <partitionname>] [-d]
The options for this command are:
| Option | Description |
|---|---|
|
-d |
Specifies that the digest repository be deleted. |
|
-p partitionname |
Specifies the partition to be relinked. (default: all partitions). |
To relink a message store:
relinker Processing partition: primary Scanning digest repository... Processing user directories... --------------------------------------------------------- Partition statistics Before After --------------------------------------------------------- Total messages 73 73 Unique messages 41 40 Message digests in repository 1 1 Space used 55Kb 51Kb Space savings from single-copy 40Kb 43Kb --------------------------------------------------------- Note: run-time relinker (local.store.relinker.enabled) is not enabled, so the repository will not be automatically purged. When you're done with relinker, remember to purge the repository by running "relinker -d"
After the "Scanning digest repository..." text shown above, relinker displays another '.' for every 100,000 messages message digests it finds in the repository and another '.' for every 100,000 messages as it is scanning messages. This indicates the progress of the relinker command.
To delete the digest repository:
relinker -d Processing partition: primary Purging digest repository... --------------------------------------------------------- Partition statistics Before After --------------------------------------------------------- Message digests in repository 1 0 ---------------------------------------------------------
Note that command-line relinker is also controlled by the store.relinker.maxage (Unified Configuration) or local.store.relinker.maxage (legacy configuration) option, which defaults to 24 (hours). To have command-line relinker consider all messages in the store, rather than just those delivered in the past day:
For Unified Configuration, run:
msconfig set store.relinker.maxage -v 24 msconfig set store.relinker.maxage -1
For legacy configuration, run:
configutil -o local.store.relinker.maxage 24 configutil -o local.store.relinker.maxage -v -1 OK SET relinker Processing partition: primary Scanning digest repository... Processing user directories... --------------------------------------------------------- Partition statistics Before After --------------------------------------------------------- Total messages 75 75 Unique messages 40 22 Message digests in repository 1 22 Space used 51Kb 29Kb Space savings from single-copy 50Kb 73Kb --------------------------------------------------------- Note: run-time relinker (local.store.relinker.enabled) is not enabled, so the repository will not be automatically purged. When you're done with relinker, remember to purge the repository by running "relinker -d" # msconfig set store.relinker.maxage 24 (Unified Configuration) # configutil -o local.store.relinker.maxage -v 24 (legacy configuration) OK SET #
start-msg
The start-msg utility starts all of the messaging server processes (smtp, imap, pop, store, http, ens, sched), or optionally, one specified service. Some services started by start-msg can be controlled by enabling or disabling the following options: imap.enable, pop.enable, http.enable, sms_gateway.enable, snmp.enable, imta.enable, mmp.enable, ens.enable, schedule.enable (Unified Configuration) or service.imap.enable, service.pop.enable, service.http.enable, local.smsgateway.enable, local.snmp.enable, local.imta.enable, local.mmp.enable, local.ens.enable, and local.sched.enable (legacy configuration). The ha option starts the server in HA mode. The watcher monitors process restarts processes on failure. The HA agent monitors the watcher process. In HA mode, the watcher will terminate when it gives up on restarting processes to trigger a failover.
Location: MessagingServer_home/bin
start-msg [ -h | -m | ha | <service>]
The options for this command are:
| Option | Description |
|---|---|
|
-h |
Shows the usage statement:
Usage: start-msg [COMPONENTS...]
Start all or some Messaging Server components.
Usage: start-msg ha
Start all Messaging Server components in HA mode.
|
|
ha |
Starts all Messaging Server components in HA mode. |
|
service |
The accepted values for service are:
watcher
mfagent
ens
metermaid
store
imap
pop
cert
http
sched
dispatcher
job_controller
snmp
sms
mmp
mta
If no components are specified, all enabled services will be started. |
|
-m |
Starts the message store as a replication master. |
The following command starts all the Messaging Server processes:
start-msg
The following command starts the imap process:
start-msg imap
stop-msg
The stop-msg utility stops all Messaging Server processes (smtp, imap, pop, store, http, ens, sched), or optionally, one specified service. To use stop-msg component, the component must be enabled. The stop-msg command without arguments shuts down everything started by start-msg, including disabled components.
Location: MessagingServer_home/bin
stop-msg [ -h | ha | [-f] <service>]
The options for this command are:
Table 75-38 stop-msg Command Options
| Option | Description |
|---|---|
|
-f |
Force stop using SIGKILL. |
|
-h |
Shows the usage statement:
Usage: stop-msg [OPTIONS] [COMPONENTS...]
Stop all or some Messaging Server components.
Usage: stop-msg ha
Stop all Messaging Server components in HA mode.
|
|
ha |
Stops all Messaging Server components in HA mode. |
|
service |
The accepted values for service are: watcher mfagent ens metermaid store imap pop cert http sched dispatcher job_controller snmp sms mmp mta If no components are specified, all enabled services will be stopped. |
The following command stops all Messaging Server processes:
stop-msg
The following command stops the http service:
stop-msg http
stored
The stored utility starts a daemon that performs the following functions:
-
Performs checkpoint database transactions.
-
Deadlock detection and rollback of deadlocked database transactions.
-
Cleanup of temporary files and lock files on startup.
-
Creates a database snapshot archive.
-
Database recovery as necessary (see "Message Store Automatic Recovery On Startup.")
If any server daemon crashes, you must stop all daemons and restart all daemons including stored.
Requirements: Must be run locally on the Messaging Server.
Location: MessagingServer_home/lib/
To run stored as a daemon process:
stored -r | -R | -t [-v] | [-m] -d [site] | [-m]
The options for this command are:
| Option | Description |
|---|---|
|
-r |
Removes the database temporary files and synchronizes the database. This cleans up the database environment to prepare for an upgrade, downgrade, or migration. |
|
-R |
Removes the database temporary files without synchronizing the database. If stored -r fails because the software has been upgraded with an incompatible libdb, customers can run stored -R to remove the database temporary files. stored -R does not perform recovery. |
|
-t |
Checks the status of stored. The return code of this command indicates the status. To print the status, enter: stored -t -v |
|
-v |
Verbose output. |
|
-m |
Berkeley Database replication master. |
|
-d site |
Delete a mboxlist replication site. Site format is host[:port]. Default site is the local site. |