The configutil utility enables you to list and change Messaging Server configuration options.

For a list of all configuration options, see 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.

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.deploymap.port
          	Description: The port Deployment Map option, deploymap.port, specifies the TCP port on which the Deployment Map service listens for incoming TCP connections. The default is 4570. Introduced in 8.0.
  	        Unified Config Name: deploymap.port
  	        Flags: NULL (unset)
  	        Syntax: uint16
  	        Default: 4570
  
  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: pmxbl.port
  	        Description: RESTRICTED: The port pmxbl option specifies the TCP port number on which the PureMessage IP Blocker service is running.
  	Unified Config Name: pmxbl.port
  	        Flags: USAGE RESTRICTED
  	        Syntax: uint16
  	        Default: 4466
  
  Configuration option: service.imap.indexer.port
  	        Description: The port Indexer option specifies the TCP port on which ISS listens for incoming TCP connections, i.e., the TCP port to which Messaging Server should connect to communicate with ISS. The default is 8070. If the indexer.sslusessl option (service.imap.indexer.sslusessl option in legacy configuration) is set, the IMAP server uses SSL to authenticate to ISS on this port.
  	        Unified Config Name: imap.indexer.port
  	        Flags: NULL (unset)
  	        Syntax: uint16
  	        Default: 8070
  
  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
  
  Configuration option: store.dbreplicate.port
  	        Description: The port Message Store dbreplicate option specifies the mailbox list database replication TCP port number. The default is 55000. This will be used to listen for incoming connections. Introduced in 7.0.5.
  	        Unified Config Name: store.dbreplicate.port
  	        Flags: NULL (unset)
  	        Syntax: uint16
  	        Default: 55000
  
  ### 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/sun/comms/messaging64/data/store/partition/primary
  store.partition.three.path is currently set
  to: /opt/sun/comms/messaging64/data/store/partition/three
  store.partition.two.path is currently set
  to: /opt/sun/comms/messaging64/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/sun/comms/messaging64/data/store/partition/primary

configutil [-h] [-f configfile] [-o option [-v value]
configutil [-f configfile] [-p pattern] [-H] [-m] [-V]
configutil -i inputfile

Table 64-1 describes the options for the configutil command.

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.

The counterutil utility displays and changes counters in a counter object. It can also be used to monitor a counter object at fixed intervals. See "Gathering Message Store Counter Statistics by Using counterutil" for more information and examples.

Requirements: Must be run locally on the Messaging Server.

Location: MessagingServer_home/bin/

List content of counter registry:

counterutil -l 

Monitor a counter object:

counterutil -o counterobject [-i interval] [-n iterations]

Reset a counter:

counterutil -s -o counterobject -c counter

Table 64-2 describes the options for the counterutil command.

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

See "Gathering Message Store Counter Statistics by Using counterutil" for usage information on counterutil.

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.

Requirements: Must be run locally on the Messaging Server; the stored utility must also be running.

Location on UNIX: MessagingServer_home/bin/

deliver [-h] [-r address] [-m folder] [-E encoding] [-g flag] 
[-qcpx] userid... | pattern

You can specify multiple userids. If you specify no options, mail is delivered to the inbox of the user specified in userid.

Table 64-3 describes the options for the deliver command.

Table 64-4 describes the troubleshooting options for the deliver command.

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

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

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

Table 64-5 describes the options for the hashdir command.

hashdir user1
64/b1/
hashdir user1@domain.com
11/05/

The imcheck utility prints mailbox data and metadata. In addition, imcheck prints mboxlist database data for specified database files and prints database statistics.

Print mailbox data:

imcheck [-m mailbox  [-c|-b msgno] | -x dir [-c|-b msgno] | -p partition | -f file] [-e | -H] [-D [-S sep]]

Print mboxlist database data:

imcheck -d db_name [-S sep]

Print database statistics:

imcheck -s [-n] [subsystem...]

Print maintenance queue:

imcheck -q

Table 64-6 describes the options for the imcheck command.

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 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 -m user/jdoe/INBOX -D -S ":"

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/sun/comms/messaging64/store/partition/primary/=user/64/b1/=jdoe
Msg Path: /var/opt/sun/comms/messaging64/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/sun/comms/messaging64/data/store/partition/primary/=user/20/b0/=jauser/=&k+A+F+P4+W4+I+M+H8-
Msg Path: /opt/sun/comms/messaging64/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>

The imdbverify utility takes and verifies message store database snapshots. See "Administering Message Store Database Snapshots (Backups)" for more information on running imdbverify.

imdbverify [-s] [-m]

Table 64-7 describes the options for the imdbverify command.

imexpire automatically expires messages in the message store based on administrator-specified criteria. The "impurge" command purges the messages.

Topics:

• Expire Actions

• Expire Criteria

• Requirements

• Location

• Syntax

• Options

• Examples

• Additional Functionality

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. If the specified folder does not exist, imexpire creates it.

• Report - prints the specified mailbox name, uid, and uid validity to stdout.

By default, imexpire discards messages.

See the following sections for more information about how the imexpire actions can be performed:

• Message Store Maintenance Queue

• Configuring Message Expiration (Tasks)

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

imexpire must run locally on the Messaging Server; the stored utility must also be running.

The location of imexpire is MessagingServer_home/bin.

Expire messages from the Message Store:

imexpire  [-n] [-d] [-v num] [-p partition | -u user] [-t num][-r num] [-m num] [-f config_file]

Install expire rule file:

imexpire -i {-p partition | -x mailbox | -u user} -f config_file

Table 64-8 describes the options for the imexpire command.

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

• Sieve Body-Test Functionality

Attributes for Spam and Virus Scanning Through an MTA Channel

Table 64-9 describes the attributes for the imexpire command that facilitate spam and virus scanning through an MTA channel.

Sieve Body-Test Functionality

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

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 [-s | -q] -a | -u user

Table 64-10 describes the options for the iminitquota command.

You must specify either the -a or -u option with the iminitquota command.

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 [-u user_name] [-w passwd | -j pwdfile] [service...]
[-D threshold] [-k mail_subject] [-m mailfile] [-r alert_recipients]
[-A alternate_mail_server] [-f from_user@domain] [-X] [-T] [-hdnvz]

where service is one or more of:

 Where service is one or more of
         -L LDAP_host[:port]=[threshold][,STLS|PORT] [-b searchbase -B bindDN]
         -S SMTP_host[:port]=[threshold][,STLS]
         -P POP_host[:port]=[threshold][,STLS|PORT]
         -I IMAP_host[:port]=[threshold][,STLS|PORT]
         -H HTTP_host[:port]=[threshold][,STLS|PORT] [-c cookiename]
         -C LMTP_host[:port]=[threshold][,STLS]
         -X (Enable SASL)
         -T (Enable SSL)

Table 64-11 describes the task options for immonitor-access command.

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

immonitor-access -u admin -w password -P host:110=STLS -X

Example 6: To run immonitor-access using SSL via STARTTLS:

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=PORT -T

Example 8: To run immonitor-access using SASL on SSL:

immonitor-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 64-12 describes the exit statuses.

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.

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

Table 64-13 describes the options for the impurge command.

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

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/

Report quota and usage:

imquotacheck [-u user | -d domain [-p partition] | -p partition ] [-a]

Enforce domain quota:

imquotacheck -f [-d domain]

Deliver over quota notification messages:

imquotacheck -n [-e] [-d domain] [-r rulefile] [-t msgfile] [-l]

Table 64-14 describes the options for the imquotacheck command.

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 64-15 describes the rulefile attributes.

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.

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
#

1. Rule precedence is determined by increasing trigger percentages.

2. The highest applicable threshold is used to generate a notification. The time and the rule's threshold are recorded.

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

4. If usage drops, the notification interval of the current rule (lower threshold) will be used to check the time elapsed since the last notice.

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

imquotacheck -u testquota
Name    Quota(K) Usage(K)  %   Quota#  Usage#  %  OverDate WarnDate
-------------------- -------- -------- --- ------- ------- --- ----
testquota  256000   654B   0   100000    1     0      -        -
-------------------------------------------------------------------

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 -s [-benov] [-ix] [ -t time ] [ -f proto ] [ -p ppath ] file...
imsasm -r [-dnv] [ -i {nNyYrR} ] [ -m src=dst ] -z suffix [ -p path ] file...
imsasm -c [-nv] [ -p path ] file...

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.

Table 64-16 describes the imsam options that are valid for all modes.

Table 64-17 describes the options you can use when saving (-s).

Table 64-18 describes the options you can use when recovering (-r).

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" for more information.

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

imsbackup -f file [-b blockfactor] [-d date] [-m link_count]
[-e encoding] [-u file] [-n path] [-ivlgrpx] name...

Table 64-19 describes the options for the imsbackup command.

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

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 imap.enableuserlist and http.enableuserlist to 1.

See "Monitoring User Access to the Message Store" for more information and examples.

Location: MessagingServer_home/bin

imsconnutil -c | -a | -k [-s service] [-u uid] [-f filename]

Table 64-20 describes the options for the imsconnutil command.

• List every user ID currently logged into IMAP and HTTP.

imsconnutil -c

• List last IMAP, POP, or HTTP 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 HTTP, 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.

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/

Print help:

imscripter [-h]

Go interactive:

imscripter [options]

Execute command from cmdfile:

imscripter [options] -f cmdfile

Execute the given command with the given argument(s):

imscripter [options] -c command [cmddata1 ...]

Execute the given command for each argument line in the datafile:

imscripter [options] -c command -f datafile

Table 64-21 describes the options for the imscripter command.

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
#

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. For classic message store, it also creates 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.

Table 64-22 shows the UW-IMAP MBOX header fields utilized by the imsexport utility.

Location: MessagingServer_home/bin

imsexport [-g] [-v 0|1|2] [-f format] [-s mailbox] [-e encoding] -u user -d dir

Table 64-23 describes the options for the imsexport command.

In the following example, imsexport extracts all email for user smith1. smith1 is a valid user account in the 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

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 preserves the UIDVALIDTY, LASTUID, and UID in the /var/mail folder if it is possible.

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.

Table 64-24 shows the UW-IMAP MBOX header fields utilized by the imsimport utility.

Location: MessagingServer_home/bin/

imsimport [-g] [-v 0|1|2] [-c y|n] [-d mailbox] [-n] [-e encoding] [-i] 
[-b] -u user -s file

Table 64-25 describes the options for the imsimport command.

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.

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 blockfactor] [-e encoding] [-v mode] [-c y|n] 
[-m mapfile] [-thngspxDS] [-i|-E] [-u file] [-r file] [-d path] 
[-P partition] [name...]

Table 64-26 describes the options for the imsrestore command.

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

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.

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 pattern | -P regular expression] [-x | -s] [-D] [-z]

Create mailboxes:

mboxutil -c [-E encoding] {mailbox_name | -f file}

Delete mailboxes:

mboxutil -d [-E encoding] {-p pattern | -P regexp | -f file | mailbox}

Rename mailboxes:

mboxutil -r [-E encoding] {old_name new_name | -f file} [partition]

Expunge mailboxes:

mboxutil -e [-E encoding] [-p IMAP-mailbox-name pattern | -P regular expression]

Schedule cleanup:

mboxutil -C [-g num] [-E encoding] [-p IMAP-mailbox-name 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][-m dest_mailbox_name][-U uid_sequence] mailbox_name

List personal mailbox subscriptions:

mboxutil -S [-n [-f file] | -u -f file]

Table 64-27 describes the options for the mboxutil command.

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 UID 1 to 3 from joe's INBOX to his Trash folder:

mboxutil -R -m user/joe/Trash -U 1:3 user/joe/INBOX

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

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

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). Figure 64-1 displays the structure.

Figure 64-1 Backup Directory Hierarchy

Description of "Figure 64-1 Backup Directory Hierarchy"

Location: MessagingServer_home/bin

Table 64-28 describes the variables in the backup directory contents.

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.

mkbackupdir [-i|-f|-u] [-vg] [-a asm] [-e encoding] [-p path] [-t max_thread]

Table 64-29 describes the options for the mkbackupdir command.

To create the mybackupdir directory, enter the following:

mkbackupdir -p /mybackupdir

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

For additional information on msprobe, see Messaging Server Reference.

Location: MessagingServer_home/lib

msprobe [-d] [-n] [-r] [server] 

Table 64-30 describes the options for the msprobe command.

imap
pop
http
ens
cert
job_controller
smtp
lmtp
submit
metermaid
deploymap

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

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.

Location: MessagingServer_home/lib

msuserpurge [-v|-r] [-d domain] [-g days]

Table 64-31 describes the options for the msuserpurge command.

msuserpurge -d example.com -g 0

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/

Count the number of users who have accessed their shared folders:

readership [ -d days |-p months ]

Set an acl for a mailbox:

readership [-e encoding] -s { -m pattern | mailbox } identifier acl

Table 64-32 describes the options for the readership command.

Table 64-33 describes the ACL rights characters.

Example

readership -s user/joe/golf mary lpr
readership -s -m user//joe/* mary lpr

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.

In a Cassandra message store, the mailboxes are stored in a Cassandra database. The only reconstruct command that works on Cassandra message store is:

reconstruct [-r] [-f | -n | -x] [-E encoding] [mailbox...]

On a Berkeley Database 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

Repair/validate mailboxes:

reconstruct [-r] [-f | -n | -x] [-E encoding] [-p partition | mailbox...]

Repair mboxlist database (Berkeley Database only):

reconstruct -m [-p partition [-u user]]

Repair quotas (Berkeley Database only):

reconstruct -q [-p partition]

Repair subscriptions (Berkeley Database only):

reconstruct -s

Repair ACLs db (lright.db) (Berkeley Database only):

reconstruct -l

Repair annotation db (Berkeley Database only):

reconstruct -A [-u userid]

Compact a database (Berkeley Database only):

reconstruct -c [-f] db_file_name

Comprehensively repair all aspects of a mailbox (Berkeley Database only):

reconstruct -a [-t nthreads] [mailbox...]

Table 64-34 describes the options for the reconstruct command.

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.

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

To 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

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:

1. Ensure that both the source and destination mailhosts are running Messaging Server 8.0.1 or later.

2. For Cassandra message store, you must use Local Mail Transfer Protocol (LMTP) to deliver messages into the Cassandra message store. If you are not currently using LMTP, you must configure it before you can use rehostuser to move the user's mail store from a classic message store to Cassandra message store.

3. Ensure that both the source and destination mailhosts have IMAP IDLE configured. See "Configuring IMAP IDLE" for more information.

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

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

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

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

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

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

   3. 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] [-x] [-n]
[-o iss_src -t iss_dest -y ssh_user [-z src_path] [-w dest_path]]

Table 64-35 describes the options for the rehostuser command.

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

Table 64-36 describes the options for the relinker command.

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
#

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" for more information.)

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] 

Table 64-37 describes the options for the stored command.