Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Messaging Server 6 2004Q2 Administration Reference 

Chapter 1
Messaging Server Command-line Utilities

Sun Java System Messaging Server provides a set of command-line utilities in addition to its graphical user interface. This chapter describes utilities for messaging server starting, stopping, administration, message access, and message store.

For descriptions of the command-line utilities for the MTA, see Chapter 2, "Message Transfer Agent Command-line Utilities".

The commands described in this chapter are listed in Table 1-1.

Table 1-1  Messaging Server Commands 

Command

Description

configutil

Enables you to list and change Messaging Server configuration parameters.

counterutil

Displays all counters in a counter object. Monitors a counter object.

deliver

Delivers mail directly to the message store accessible by IMAP or POP mail clients.

hashdir

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

imexpire

Expires and purges messages in the Message Store

iminitquota

Reinitializes the quota limit from the LDAP directory and recalculates the disk space being used.

immonitor-access

Monitors the status of the Messaging Server components.

imquotacheck

Calculates the total mailbox size for each user in the message store and compares the size with their assigned quota.

imsasm

Handles the saving and recovering of user mailboxes.

imsbackup

Backs up stored messages.

imsconnutil

Monitors user access of the message store.

imsexport

Exports Sun Java System Messaging Server mailboxes into UNIX /var/mail format folders.

imsimport

Migrates UINX /var/mail format folders into an Sun Java System Messaging Server message store.

imsrestore

Restores messages from the backup device into the message store.

imscripter

The IMAP server protocol scripting tool. Executes a command or sequence of commands.

mboxutil

Lists, creates, deletes, renames, or moves mailboxes (folders).

mkbackupdir

Creates and synchronizes the backup directory with the information in the message store.

MoveUser

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

msuserpurge

Purges those user and domain mailboxes from the message store.

readership

Reports on how many users other than the mailbox owner have read messages in a shared IMAP folder.

reconstruct

Rebuilds one or more mailboxes, or the master mailbox file, and repairs any inconsistencies.

refresh

Refreshes the configuration of the specified messaging server processes

start-msg

Starts the messaging server processes.

stop-msg

Stops the messaging server processes.

stored

Performs cleanup and expiration operations.


Command Descriptions

This section describes what the main Sun Java System Messaging Server command-line utilities do, defines their syntax, and provides examples of how they are used. The utilities are listed in alphabetical order.

Store programs do a setuid at configuration initialization time if running as root. IMAPD and POP3 do a setuid after opening the sockets, since that needs root privilege. The few files (logs, locks) which may be created before the uid change are chowned to mailsrv so that they are still usable by utilities starting directly as mailsrv.

configutil

The configutil utility enables you to list and change Sun Java System Messaging Server configuration parameters.

For a list of all configuration parameters, see Chapter 3, "Messaging Server Configuration."

Most Sun Java System Messaging Server configuration parameters and values are stored in the LDAP database on Directory Server with the remaining parameters and values stored locally in the msg.conf and local.conf files. The startup parameters are stored in the msg.conf file and are set during installation. The local.conf files should not be edited manually. Use configutil to edit the parameters stored in those files.


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


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: msg_svr_base/sbin/configutil

You can use configutil to perform four tasks:

Syntax

configutil [-f configdbfile] [-o option [;language] [-v value]]

configutil [-f configdbfile] [-p prefix][;language]

configutil [-f configdbfile] -l[-o option [;language] [-v value]]

configutil -i inputfile

Options

The options for this command are:

Option

Description

-f configdbfile

Enables you to specify a local configuration file other than the default. (This option uses information stored in the CONFIGROOT environment variable by default.)

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

-l

Lists configuration parameters stored in the local server configuration file. When used in conjunction with the -v option, specifies that a configuration parameter value be stored in the local server configuration file.

-o option

Specifies the name of the configuration parameter that you wish to view or modify. May be used with the -l and -i options. Configuration parameter names starting with the word local are stored in the local server configuration file.

-p prefix

Lists configuration parameters with the specified prefix.

-v value

Specifies a value for a configuration parameter. To be used with -o option. If the -l option is also specified or the configuration parameter name specified with the -o option begins with local, the option value is automatically stored in the local server configuration file rather than the Directory Server.

If you specify no command-line options, all configuration parameters are listed.

Examples

To list all configuration parameter and their values in the 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 parameters with the prefix service.imap:

configutil -p service.imap

To display the value of the service.smtp.port configuration parameter:

configutil -o service.smtp.port

To set the value of the service.smtp.port configuration parameter to 25:

configutil -o service.smtp.port -v 25

To clear the value for the service.imap.banner configuration parameter:

configutil -o service.imap.banner -v ""

Language Specific Options

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"

counterutil

The counterutil utility displays and changes counters in a counter object. It can also be used to monitor a counter object every 5 seconds.

Requirements: Must be run locally on the Messaging Server as root.

Location: msg_svr_base/sbin/

Syntax

counterutil -o counterobject [-i interval] [-l] [-n numiterations]

  [-r registryname]

Options

The options for this command are:

Option

Description

-i interval

Specifies, in seconds, the interval between reports. The default is 5.

-l

Lists the available counter objects in the registry specified by the -r option.

-n numiterations

Specifies the number of iterations. The default is infinity.

-o counterobject

Continuously display the contents of a particular counter object every 5 seconds.

-r registryname

Indicates the counter registry to use. If no registryname is specified with the -r registryname option, the default is msg_svr_base/counter/counter.

Examples

To list all counter objects in a given server’s counter registry:

counterutil -l

To display the content of a counter object imapstat every 5 seconds:

counterutil -o imapstat -r \

msg_svr_base/counter/counter

deliver

The deliver utility delivers mail directly to the message store accessible by IMAP or POP mail clients.

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.


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 msg_svr_base/config.

Location on UNIX: msg_svr_base/sbin/

Syntax

deliver [-l] [-c] [-d] [-r address] [-f address] [-m mailbox]

  [-q] [-g flag] [userid]...

You can specify multiple userids.

Options

The options for this command are:

Option

Description

-a authid

Specifies the authorization ID of the sender. Defaults to anonymous.

-c

Automatically creates the mailbox if it doesn’t exist in the message store.

-d

This option is recognized by deliver in order to maintain compatibility with /bin/mail, but it is ignored by deliver.

-g flag

Sets the system flag or keyword flag on the delivered message.

-f address

Inserts a forwarding path header containing address.

-l

Accepts messages using the LMTP protocol (RFC 2033).

-m mailbox

Delivers mail to mailbox.

  • If any user ids are specified, attempts to deliver mail to mailbox for each user id. If the access control on a mailbox does not grant the sender the “p” right or if the -m option is not specified, then this option delivers mail to the inbox for the user ID, regardless of the access control on the inbox.
  • If no user ids are specified, this option attempts to deliver mail to mailbox. If the access control on a mailbox does not grant the sender the “p” right, the delivery fails.

-q

Overrides mailbox quotas. Delivers messages even when the receiving mailbox is over quota.

-r address

Inserts a Return-Path: header containing address.

userid

Deliver to inbox the user specified by userid.

If you specify no options, mail is delivered to the inbox.

Examples

To deliver the contents of a file named message.list to Fred’s tasks mailbox:

deliver -m tasks fred < message.list

In the above example, if the tasks mailbox does not grant “p” rights to the sender, the contents of message.list are delivered to the inbox of the user fred.

hashdir

The hashdir command identifies the directory that contains the message store for a particular account. This utility reports the relative path to the message store. The path is relative to the directory level just before the one based on the user ID. hashdir sends the path information to standard output.

Requirements: Must be run locally on the Messaging Server. Make sure that the environment variable CONFIGROOT is set to msg_svr_base/config.

Location: msg_svr_base/sbin/

Syntax

hashdir [-a] [-i] account_name

Options

The options for this command are:

Option

Description

-a

Appends the directory name to the output.

-i

Allows you to use the command in interactive mode.

Examples

hashdir user1

imexpire

imexpire automatically removes messages from the message store based on administrator-specified criteria. The criteria can be set in the Admin Console GUI, with configutil parameters, or in a file called store.expirerule. (See the Sun Java System Messaging Server Administration Guide detailed usage information.) The following removal criteria can be specified:


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.


Requirements: Must run on local machine (the machine that holds the message store files). Some or all of the following may be required: local.schedule.expire, local.schedule.purge, store.cleanupage, local.store.expire.loglevel, store.expirerule.rulename.attribute, store.expirestart, local.store.expire.workday, local.store.expire.cleanonly

Location: msg_svr_base/sbin

Syntax

imexpire [-c] [-e] [-n] [-v] [-d] [-p partition]

Options

The options for this command are:

Option

Description

-c

Do purge only—do not expire. Remove expunged and expired messages.

-e

Do expire only - do not purge.

-n

Trial run only - do not perform expire or cleanup. A description of what would happen without this flag is output.

-v 1|2|3

Display verbose output. The number specifies the loglevel, where

1= partition level
2 = mailbox level
3 = message level

Messages are logged to the log file by default. When the -d option is used, messages go to stderr.

-d

Display debug output to stderr.

-p message_store_partition

Expire/Purge the message store partition specified.

Examples

Purge expunged messages with verbose output.

imexpire -c -v

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: msg_svr_base/sbin/

Syntax

iminitquota -a | -u userid

Options

The options for this command are:

Option

Description

-a

Initializes and updates the quota files for every message store user.

-u userid

Reinitializes and updates the quota-related information for the specified user. The userid parameter 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:

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.

Syntax

immonitor-access -u user_name { [-L LDAP_host:[port]=[threshold] ] [-b searchbase] [-I IMAP_host:[port]=[threshold] ] [-P POP_host:[port]=[threshold] ] [-H HTTP_host:[port]=[threshold] ] [-S SMTP_host:[port]=[threshold] ] [-w passwd] } [-D threshold] [-m file] [-r alert_recipients] [-A Host] [-f SOMSADMIN] [-C LMTP_host:[port]=[threshold] ] [-hdv]

immonitor access -u user_name -w passwd { [ -I IMAP_host:[port]=[ threshold ]] [ -P POP_host: [port]=[ threshold ]]} [-k subject] -z

immonitor access -u user_name -w passwd { [ -H HTTP_host:[port]=[ threshold ]] }

Options

The following list contains valid task options for the command.

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. This option is mandatory when the -I or -P is used. “-” can specified with -w, to enter the password through standard input.

-L LDAP_host: [ port ] = [ threshold ]

Use the LDAP server and the port specified to check the Directory Server. The threshold is specified in seconds.

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

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

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

-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 parameter local.ugldapbasedn.

-f mail From option:

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

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

-h

Prints command usage syntax.

-i inputfile

Read the command information from a file instead of from the command line.

-m 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 msg_svr_base/lib/locale/C/mailfile.txt is used as the mail file.

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

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

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

-A host

The alternate mail server to be used to send mail to the alert_recipients. 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.

-h

Display the usage message.

-d

The debug mode: display the execution steps.

-v

Run in verbose mode, with diagnostics written to standard output.

Output

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.

Examples: To monitor the LDAP, SMTP, IMAP and POP with the threshold of 10 seconds and 250 milliseconds on localhost use:

immonitor access -L localhost:=60.25 -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

Exit Status

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.

0  Successful execution with no errors or thresholds exceeded

1  Exceeded threshold of a service

2  Errors

64  Usage errors

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.

Warnings

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 -w -
immonitor -w - ... < passwd_file

Do not use the echo command such as:

echo password | immonitor .. -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.

imquotacheck

The imquotacheck utility calculates the total mailbox size for each user 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.

Requirements: Must be run locally on the Messaging Server.

Dependencies: The delivery agent’s quota warning mechanism needs to be turned off in order for imquotacheck to work, because the imquotacheck and the delivery agent use the same element in the quota database to record last-warn time. To turn off the delivery agent’s quota warning, set store.quotanotification to off.

Location: msg_svr_base/sbin/

Syntax

The following form of imquotacheck should be used when you want to notify users if they have exceeded a set percentage of their assigned quota.

imquotacheck [-e] [-d domain][-f] [-r rulefile] [-t message template] [-D] -n

This following form of imquotacheck should be used when you want to report the usage to stdout.

imquotacheck [-e] [-d domain] [-r rulefile] [-t message template] [-i] [-v]

  [-h] [-u user] [-D]

Options

The options for this command are:

Option

Description

-e

Allows extended reporting. Per folder usage is included in the report.

-d domain

Looks for users only in the specified domain. The -i option is implied, so it does not need to be specified.

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

-r rulefile

Specifies the set of rules to be used when you want to calculate quota usage. If -r is not specified, a default rulefile can be used. To setup a default rulefile, copy the Sample Rulefile to msg_svr_base/config. See Rulefile Format.

-t message template

Notifies users when their mailbox quota is exceeded. 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 msg_svr_base/config.

-n

Sends notification messages based on the rules defined in the rulefile. If you do not define any rules when you use this option, you will receive an error.

-i

Ignores the rulefile and any active rule defined in it. The quota status of all the users in the message store will be printed to stdout. This option can only be used when you want to report usage. If -i is not specified, the active rule with the least threshold is used to print a list of all of the users and their quota status to stdout.

-v

Prints the username, quota, total mailbox size and percentage of mailbox used by all of the users. When you are using imquotacheck to report usage, it will default to this option if no other options are specified.

-u user

Obtains the quota status of the specified user id. Can be used with -e for extended reporting on the user. Cannot be used to specify multiple users.

-D

Debug mode; displays the execution steps to stdout.

Examples

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 list the usage of all users whose quota exceeds the least threshold in the rulefile:

imquotacheck

To list the usage of all users and (will ignore the rulefile):

imquotacheck -i

To list per folder usages for users user1 (will ignore the rulefile):

imquotacheck -u user1 -e

To only list the users in domain siroe.com:

imquotacheck -d siroe.com

Rulefile Format

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

This table shows the attributes, whether they are required, the default value, and the description.

General 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

  

Can 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 to see the structure of the attribute.

Rule Attribute

Required Attribute?

Default Value

Description

notificationTriggerPercentage

Yes

  

Specifies the consumed quota percentage that will trigger notification. Value should be unique and an integer.

messageFile

No

msg_svr_base/
config/
imq.msgfile

Specifies the absolute path to the message file.

notificationInterval

Yes

  

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

  

Can customize the overquota notification method to send to the user. 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 to see the structure of the attribute.

reportMethod Signature

The following signature can be used for the reportMethod():

int symbol(QuotaInfo* info, char** message, int* freeflag)
info is a pointer to the following structure:
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.

notificationMethod Signature

The following signature can be used for the notificationMethod():

The notification function has the following prototype:
int symbol(QuotaInfo* info, char** message, int* freeflag)
info is a pointer to the following structure:
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.


Sample Rulefile

#
# Sample rulefile
#
[General]
mailQuotaAttribute=mailquota
reportMethod=/xx/yy/libzz.so:myReportMethod
[for Solaris only ]
    /xx/yy/libzz.sl:myReportMethod [for HP-UX only]
    
\xx\yyibzz.dll:myReportMethod [for Windows NT 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

  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.

Notification File

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


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: msg_svr_base/lib/msg

Syntax

imsasm [standard_asm_arguments]

Options

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:

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:

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:

  • n—Do not recover the current file.
  • N—Do not recover any files with conflicting names.
  • y—Overwrite the existing file with the recovered file.
  • Y—Overwrite files with conflicting names.
  • r—Rename the conflicting file. A dot “.” and a suffix are appended to the recovered file’s name. If a conflict still exists, the user will be prompted again.
  • R—Automatically renames conflicting files by appending a dot “.” and a suffix. If a conflicting file name already ends in a .suffix, the user will be prompted to avoid potential auto rename looping conditions.

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

Examples

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” on page 50.

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.

Location: msg_svr_base/sbin

For more information about imsbackup and backing up the message store, see the section “Backing Up and Restoring the Message Store” in the Messaging Server Administration Guide.

Syntax

imsbackup -f device [-b blocking_factor] [-d datetime] [-e encoding] [-u file]
[-m linkcount] [-ivlgx] [name ...]

Options

The options for this command are:

Option

Description

-b blocking_factor

Everything written to the backup device is performed by blocks of the size 512xblocking_factor. The default is 20.

-d datetime

Date from which messages are to be backed up, expressed in yyyymmdd[:hhmmss]; for example, -d 19990501:13100 would backup messages stored from May 1, 1999 at 1:10 pm to the present. The default is to backup all the messages regardless of their dates.

-e encoding

Mailbox name encoding (example: IMAP_MODIFIED-UTF-7)

-f device

Specifies the file name or device to which the backup is written. If device is ‘-’, backup data is written to stdout.

-g

Debug mode

-i

Ignore links. Used for partial store.

-l

Used to autoload tape devices when end-of-tape is reached.

-m link_count

Specifies the minimum link count for hashing.

-u file

Specifies a backup object 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 object

-v

Executes the command in verbose mode.

name

Can be 1) logical pathname of the backup object, 2) user ID, 3) message store mailbox name. Backup objects and paths:

  • Entire message store: /
  • Message store partition: /partition_name
    (default: /primary)
  • Backup group—a group of users defined with regular expressions in a configuration file. See backup groups in the Sun Java System Messaging Server Administration Guide for details.

    Path: /partition_name/backup_group
    (
    /primary/user represents all users under primary).
  • User: /partition_name/backup_group/user_ID
  • Mailbox:
    /partition_name/backup_group/user_ID/mailbox_name
  • Message:
    /partition_name/backup_group/user_ID/mailbox_name/msgID

User IDs: can be any user ID in the message store. If the user is not in the default domain, the user ID must be fully qualified (example: Wally@siroe.com). If user is in the default domain, the user ID can stand alone (example: Wally).

mailbox: An email folder. It is specified using the following message store internal name:

user/user_ID/folder_name.

Note that user is a message store keyword.

Examples

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:


Note

Do not kill this process while it is operating.


This command requires root access by the system user, and you may set the configuration variables local.imap.enableuserlist, local.http.enableuserlist, local.enablelastaccess to 1.

Location: msg_svr_base/sbin

Syntax

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

Options

The options for this command are:

Option

Description

-c|-a

One of -c or -a 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 IMAP or Messenger Express users currently connected.

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

--v

Returns version of this tool.

--h

Returns usage information.

Examples

The following examples show imsconnutil and some various flags.

Lists every user ID currently logged into IMAP and http.

# imsconnutil -c

Lists last IMAP, POP, or Messenger Express access (log in or log out) of every user ID.

# imsconnutil -a

Lists access history (last log off or log on) of all user IDs. Lists current user IDs logged into IMAP and http.

# imsconnutil -a -c

Lists IMAP users currently logged on the message store.

# imsconnutil -c -s imap

Reveals whether user ID George is logged onto IMAP or not.

# imsconnutil -c -s imap -u George

Reveals 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

imsexport

The imsexport utility exports Sun Java System 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: msg_svr_base/bin/msg/store/bin

Syntax

imsexport -d dir -u user [-c y|n] [-e encoding] [-g] [-s mailbox] [-v mode]

Options

The options for this command are:

Option

Description

-c y|n

Provides an answer to the question: “Do you want to continue?” Specify y for yes, and specify n for no.

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

-g

Specifies debugging mode.

-s mailbox

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.

Example

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/

imexport then transfers each message store folder into a /var/mail conforming file. Thus you will get the following files:

imsimport

The imsimport utility migrates UNIX /var/mail format folders into a Sun Java System 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 Sun Java System 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.


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: msg_svr_base/sbin/

Syntax

imsimport -u user -s file [-c y|n] [-d mailbox] [-e encoding] [-g] [-n] [-v mode]

Options

The options for this command are:

Option

Description

-c y|n

Provides an answer to the question: “Do you want to continue?” Specify y for yes, and specify 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.

-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 where the messages are to be imported. The file parameter must be a full path name. This is a required option.

-u user

Specifies the message store id for a user. Note that this is not necessarily the login id of the user. 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.

Examples

imsimport migrates the specified /var/mail/folder for the specified user to the Sun Java System 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/mail INBOX 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 Sun Java System 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 Sun Java System 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.

Location: msg_svr_base/sbin

Syntax

imsrestore -f device|- [-a userid] [-b blocking_factor] [-c y | n] [-e encoding [-h] [-i] [-m file] [-n] [-r file] [-t] [-u file] [-v 0|1|2] [path]

Options

The options for this command are:

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

Automatically answers yes or no to the question “Do you want to continue?”

-e encoding

Mailbox name encoding (example: IMAP_MODIFIED-UTF-7)

-f device|-

When -f- is specified, backup data from stdin is read. Otherwise, the backup data is read from the specified device or filename.

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

This option is only used to rename user IDs from an older version of Messaging Server to a newer version of Messaging Server. Use the -u option for restoring users from SIMS to Messaging Server.

-n

Creates a new mailbox with a .date extension (if the mailbox exists). By default, messages are appended to the existing mailbox.

-r file

Reference file name (will restore all links in file).

-t

Prints a table of contents, but restore is not performed.

-u file

Specifies a backup object 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 data into a Sun Java System Message Store, 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]

Executes the command in verbose mode.

0 = no output
1= output at mailbox level (default)
2= output at message level
3=print meta data (for use with -t only)
4=print object level meta data (for use with -t only)

name

Can be 1) logical pathname of the backup object, 2) user ID, 3) mailbox. See imsbackup for description.

Examples

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

imscripter

The imscripter utility connects to an IMAP server and executes a command or a sequence of commands.

May be run remotely.

Location: msg_svr_base/sbin/

Syntax

imscripter [-h] [-f script | [-c command] -f datafile]] [-c command]

  [-s serverid | -p port | -u userid | -x passwd | -v verbosity]

Options

The options for this utility are:

Option

Description

-c command

Executes command, which can be one of the following:

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.

-f file

The file may contain one or more commands, or a list of mailboxes on which commands are to be executed.

-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 errors
I—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.

mboxutil

The mboxutil command lists, creates, deletes, renames, or moves mailboxes (folders). mboxutil can also be used to report quota information.

You must specify mailbox names in the following format:

user/userid/mailbox

userid is the user that owns the mailbox and mailbox is the name of the mailbox.

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

Location: msg_svr_base/bin/msg/admin/bin

Syntax

mboxutil [-c mailbox] [-d mailbox] [-f file]

  [-r oldname newname [partition]] [-l] [-o] [-p pattern] [-w file] [-x]

Options

The options for this command are:

Option

Description

-c mailbox

Creates the specified mailbox.

A mailbox must exist before creating a secondary mailbox.

-d mailbox

Deletes the specified mailbox.

There are some limitations with using the -d option to remove a user. Using the -d option to remove an active user (by removing the mailbox user/userid/INBOX) could result in a partially deleted mailbox. This occurs when either the user is connecting to the server or when the server is delivering mail to the user’s mailbox.

The recommended method to delete a user is to mark the user status as deleted in LDAP (using the imadmin user delete utility), and then use the imadmin user purge utility to purge the users that have been marked as deleted for a period longer than the specified number of days.

-f file

Creates, deletes the specified data file. The -f option can be used with the -c, -d or -k options.

The data 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/INBOX
user/daphne/projx
user/daphne/mm

-l

Lists all of the mailboxes on a server.

If you create multibyte folders for different language locales, you should edit: msg_svr_base/bin/msg/bundles/encbylang.properties to associate the appropriate character set with the LANG environment variable.

-o

Checks for orphaned accounts. This option searches for inboxes in the current messaging server host which 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 in conjunction with the -l option, lists only those 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 only those mailboxes with names that match the specified POSIX regular expression. This option expects the regexp in the local language

-r oldname newname [partition]

Renames the mailbox from oldname to newname. To move a folder from one partition to another, specify the new partition with the partition option.

-w file

Write command to file.

-x

When used in conjunction with the -l option, displays the path and access control for a mailbox.

Examples

To list all mailboxes for all users:

mboxutil -l

To list all mailboxes and also include path and acl information:

mboxutil -l -x

To create the default mailbox named INBOX for the user daphne:

mboxutil -c user/daphne/INBOX

To delete a mail folder named projx for the user delilah:

mboxutil -d user/delilah/projx

To delete the default mailbox named INBOX and all mail folders for the user druscilla:

mboxutil -d user/druscilla/INBOX

To rename Desdemona’s mail folder from memos to memos-april:

mboxutil -r user/desdemona/memos user/desdemona/memos-april

To lock a mail folder named legal for the user dulcinea:

mboxutil -k user/dulcinea/legal cmd

where cmd is the command you wish to run on the locked mail folder.

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

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

Figure 1-1  Backup directory hierarchy

This figure shows the Backup directory hierarchy with the Back_Root at the top.  Under that is partition.  Under partition is DEFAULT and group.  Under Default are 3 users.  Under the first user are two mailboxes and .nsr

Location: msg_svr_base/bin/msg/store/bin

The variables in the backup directory contents are:

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 msg_svr_base/config/backup-groups.conf file. The format for specifying groups is:

groupname= pattern

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

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


Syntax

mkbackupdir [-a name_of_asm] [-i | -f] [-g] [-t number_of_threads] [-v] -p directory

Options

The options for this command are:

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.

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

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.

Examples

To create the mybackupdir directory, enter the following:

mkbackupdir -p /mybackupdir

MoveUser

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

May be run remotely.

Location: msg_svr_base/sbin/


Note

If you expect the moveuser utility to alter the LDAP attributes, then you must run the following command to set the authentication cache timeout value to 0:

configutil -o service.authcachettl -v 0


Syntax

MoveUser -s srcmailhost[:port] -x proxyuser -p password -d destmailhost[:port]

  [-u uid | -u uid -U newuid| -l ldapURL -D binDN -w password

  [-r DCroot -t defaultDomain]] [-a destproxyuser]

Options

The options for this command are:

Option

Description

-a destproxyuser

ProxyAuth user for destination messaging server.

-A

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

-d destmailhost

Destination messaging server.

By default, MoveUser assumes IMAP port 143. To specify a different port, add a colon and the port number after destmailhost. For example, to specify port 150 for myhost, you would enter:

-d myhost:150

-D binddn

Binding dn to the given ldapURL.

-F

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

-h

Display help for this command.

-l ldapURL

URL to establish a connection with the Directory Server:

ldap://hostname:port/base_dn?attributes?scope?filter

For more information about specifying an LDAP URL, see your Directory Server documentation.

Cannot be used with the -u option.

-L

Add a license for Messaging Server if not already set.

-m destmaildrop

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

-n msgcount

Number of messages to be moved at once.

-o srcmaildrop

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

-p srcproxypasswd

ProxyAuth password for source messaging server.

-r DCroot

DC root used with the -l option to move users under a hosted domain.

-s srcmailhost

Source messaging server.

By default, MoveUser assumes IMAP port 143. To specify a different port, add a colon and the port number after srcmailhost. For example, to specify port 150 for myhost, you would enter:

-s myhost:150.

-S

Do not set new message store path for each user.

-t defaultDomain

Default domain used with the -l option to move users under a hosted domain.

-u uid

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

-U newuid

New (renamed) user ID that the mailbox is to be moved to. Must be used with -u uid, where -u uid, identifies the old user name that is to be discontinued. Both the old and the new user ID must currently exist on both the source and the destination mailhost. After migration you are free to manually remove the original user ID from LDAP if you wish to do so.

-v destproxypwd

ProxyAuth password for destination messaging server.

-w bindpasswd

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

-x srcproxyuser

ProxyAuth user for source messaging server.

Examples

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

MoveUser -l \

"ldap://siroe.com:389/o=siroe.com???(mailhost=host1.domain.com)" \

-D "cn=Directory Manager" -w password -s host1 -x admin \

-p password -d host2 -a admin -v password

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

MoveUser -l \

"ldap://siroe.com:389/o=siroe.com???(uid=userid)" \

-D "cn=Directory Manager" -w password -s host1:150 -x admin \

-p password -d host2 -a admin -v password

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

MoveUser -l \

"ldap://server1.siroe.com:389/o=siroe.com???(uid=s*)" \

-D "cn=Directory Manager" -w password -s host1 -x admin \

-p password -d host2 -a admin -v password

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

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

-v password

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

MoveUser -u aldonza -U dulcinea -s host1 -x admin -p password \

-d host2 -a admin -v password

msuserpurge

When user and domain mailboxes 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 parameter 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 msg_svr_base/config.

Location: msg_svr_base/lib

Syntax

msuserpurge [-d domain_name] [-g grace_period]

Options

The options for this command are:

Option

Description

-d domain_name

Specifies domain to check for deleted attribute, and, if set, purges the mailboxes in that domain. If -d is not specified, then all domains on this mail host are checked for the deleted attribute and all mailboxes in the deleted domains are purged. If the domain spans more than one mail host, then you need to run this command on each host. (This command uses the mailhost attribute to determine where to purge.)

-g grace_period

Specifies the number of days that a domain or user must be marked as deleted before this command is run.

Examples

msuserpurge -d siroe.com

readership

An owner of an IMAP folder may grant permission for others to read mail in the folder. A folder that others are allowed to access is called a shared folder. Administrators can use the readership utility to see how many users other than the owner are accessing a shared folder or have access rights to shared folders.

Requirements: Must be run locally on the messaging server; the stored utility must also be running.

Location: msg_svr_base/sbin/

Syntax

readership [-d days] [-p months] [-l] [-s folder identifier right]

Options

The options for this command are:

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.

-l

List the data in lright.db.

-s folder identifier right

Setacl for folder.

reconstruct

The reconstruct utility rebuilds one or more mailboxes, or the master mailbox file (the mailboxes database), and repairs any inconsistencies. You can 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; the stored utility must also be running.

Location: msg_svr_base/sbin/


Note

Low-level database repair, such as completing transactions and rolling back incomplete transactions is performed with stored -d.


Syntax

reconstruct [-n | -f] [-l] [-p partition] -r [mailbox [mailbox...]]

reconstruct [-n | -f] [-p partition] mailbox [mailbox...]

reconstruct [-p partition] -m

reconstruct -q

Options

The options for this command are:

Option

Description

-f

Forces reconstruct to perform a fix on the mailbox or mailboxes.

-l

Reconstruct lright.db.

-m

Repairs and performs a consistency check of the mailboxes database. This option examines every mailbox it finds in the spool area, adding or removing entries from the mailboxes database as appropriate. The utility prints a message to the standard output file whenever it adds or removes an entry from the database.

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

reconstruct -n -r

reconstruct -n -r -p primary

reconstruct -n -r user/dulcinea/

-p partition

Specifies a partition name; do not use a full path name. If this option is not specified, reconstruct defaults to all partitions.

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

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.

Examples

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

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: msg_svr_base/sbin

Syntax

refresh [dispatcher | job_controller | smtp | imap | pop | store | http | ens | sched]

Examples

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.

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. The services started by start-msg can be controlled by enabling or disabling the configutil parameters: 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.

Location: msg_svr_base/sbin

Syntax

start-msg [dispatcher | job_controller | smtp | imap | pop | store | http | ens | sched] [snmp] [sms] [mmp]

Examples

The following command starts all the Messaging Server processes:

start-msg [-a]

The following command starts the imap process:

start-msg imap

-a : ha mode

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: msg_svr_base/sbin

Syntax

stop-msg [dispatcher | job_controller | smtp | imap | pop | store | http | ens | sched] [snmp] [sms] [mmp]

Examples

The following command stops all Messaging Server processes:

stop-msg

The following command stops the http service:

stop-msg http

stored

The stored utility performs the following functions:

Requirements: Must be run locally on the Messaging Server.

Location: msg_svr_base/lib/

Syntax

To run stored as a daemon process:

stored [-r] [-R] [-t] [-v]

Options

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. This is used if the -r option fails because of a corrupted database. This forces removal of temporary files.

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



Previous      Contents      Index      Next     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.