This section describes what the main Netscape Messaging Server 4.0 command-line utilities do, defines their syntax, and gives examples of how they are used. The utilities are listed in alphabetical order.
configutil
The configutil utility enables you to list and change Messaging Server configuration options.
Most Messaging Server configuration options and values are stored in the LDAP database on the Directory Server with the remaining options and values stored locally on the Messaging Server in a file named configdb (see Location of Configuration Data for details).
configutil Syntaxconfigutil [-f configdbfile] [command-options]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
You can use configutil to perform four tasks:
If you specify no command-line options, all configuration options are listed.
Examples of Ways to Use configutil
To list all configuration options and their values in the both the Directory Server LDAP database and local server configuration file:
configutil
To list all configuration options with the prefix service.imap:
configutil -p service.imap
To list all configuration option with the prefix service.imap, including those with empty values:
configutil -e -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 ""
(See Alarm Attributes for information on using configutil to set alarm attributes.)
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.
counterutil Syntaxcounterutil -o counterobject [-r registryname]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
Examples of Ways to Use counterutil
To list all counter objects in a given server's counter registry:
counterutil
To display the content of counter object imapstat every 5 seconds:
counterutil -o imapstat -r server-root/msg-instance/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.
deliver Syntaxdeliver [-l] [-d] [-r address] [-f address] [-m mailbox] [-a authid]
[-q] [-F flag]...[userid]...
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/store/bin
If you specify no options, mail is delivered to the inbox.
Examples of Ways to Use deliver
To deliver the contents of a file named message.list to Fred's Tasks mailbox:
deliver -m tasks fred < message.list
In this 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 utility identifies the directory that contains the message store for a particular account. This utility reports the relative path to the message store, such as d1/a7/. The path is relative to the directory level just before the one based on the user ID. The utility sends the path information to the standard output.
hashdir Syntaxhashdir [-a] [-i] account_name
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
imscripter
The imscripter utility connects to an IMAP server and executes a command or a sequence of commands.
imscripter Syntaximscripter [-h] [-f script | [-c command] -f datafile]] [-c command]
[-s serverid | -p port | -u userid | -x passwd |-v verbosity]
Requirements: May be run remotely.
Location: server-root/bin/msg/admin/bin
imscripter File Formats
Data files used with the -f option have to be formatted as a list of mailboxes with fully qualified paths, one mailbox per line. For example:
shared folders/indira/INBOX
shared folders/makeba/INBOX
shared folders/vladmir/INBOX
Scripts used with the -f option have to be in the following format:
command options
For example, an imscripter script file that adds the mailboxes contained in a file named add.list, and deletes mailboxes contained in a file named delete.list, looks like this:
create -f add.list
delete -f delete.list
Suppose the example file shown above is named dothis.script. To run it showing only errors, input commands, BAD and NO untagged and completion responses, enter:
imscripter -v ECBb -f dothis.script.
Examples of Ways to Use imscripter
To run imscripter in interactive mode:
imscripter [options]
In interactive mode, each command is entered one line at a time at the imscripter prompt. The command is then executed and responses displayed.
To execute the commands specified in a script file:
imscripter [options] -f script
To execute a specific command on mailbox:
imscripter [options] [-l] -c command mailbox
To execute a specific command for each line of data in a data file:
imscripter [options] -c command -f datafile
To execute commands from the specified script file:
imscripter -s username.airius.com -f script
mailq
The mailq utility checks and reports on the mail queue of messages awaiting delivery.
mailq Syntaxmailq [-v]
Requirements: Must be locally run on the server.
Location: /bin/mailq
mailq Examples
To check the mail queue, type mailq at a command prompt. If there are no queued messages, that fact will be reported:
% mailq
Mail queue is empty.
If there are queued messages, each host that has queued messages waiting to be delivered will be listed, along with the number of pending deliveries. For example, output might look like this:
% mailq
Queued Messages Destination Host
--------------- ----------------
2 math.marsu.edu
3 universal-robots.com
In the example above, five messages are waiting for delivery. Delivering all of them should require two connections to other machines because the messaging server attempts to deliver all queued mail for a host before disconnecting.
See processq for information how to manually force immediate delivery of messages in the mail queue.
mboxutil
The mboxutil utility lists, creates, deletes, renames, or moves mailboxes (folders).
mboxutil Syntaxmboxutil [-c mailbox] [-d mailbox] [-r oldname newname [partition]]
[-l] [-p pattern] [-x]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
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 desdemona is entered as: user/desdemona/INBOX.
Examples of Ways to Use mboxutil
To list mailboxes:
mboxutil -l
To list all folders and also include path and acl information:
mboxutil -l -x
To create a mailbox named INBOX for the user druscilla:
mboxutil -c user/druscilla/INBOX
To delete a mailbox named INBOX for the user delilah:
mboxutil -d user/delilah/INBOX
To rename Daphne's mailbox from memos to memos-april:
mboxutil -r user/daphne/memos user/daphne/memos-april
MoveUser
The MoveUser utility moves a user's account from one mail server to another. When user accounts are moved from one mail server to another, it's 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.
MoveUser SyntaxMoveUser -s srcmailhost -x proxyuser -p password
[-u uid] [-l ldapURL -D bindDN -w password] -d destmailhost [options]
Requirements: May be run remotely.
Location: server-root/bin/msg/admin/bin
Examples of Ways to Use MoveUser
To move all users from host1 to host2, based on account information in the Directory Server airius.com:
MoveUser -l
"ldap://airius.com:389/o=Airius.com???(objectclass=mailrecipient)"
-D "cn=Directory Manager" -w password -s host1 -x admin -p password
-d host2 -a admin -v password
To move one user from host1 to host2, based on account information in the Directory Server airius.com:
MoveUser -l
"ldap://airius.com:389/o=Airius.com???(uid=userid)"
-D "cn=Directory Manager" -w password -s host1 -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.airius.com:
MoveUser -l
"ldap://server1.airius.com:389/o=Airius.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 is specified in the command line:
MoveUser -u
uid -s host1 admin -p password
-d host2 -x admin -v password -o /var/mail/spool/mailbox
-m /usr/netscape/suitespot4/msg-airius/store/partition/primary
NscpMsg
The NscpMsg utility starts, stops, and refreshes the Messaging Server services. This utility is only available in Unix environments.
NscpMsg Syntax/etc/NscpMsg start [imap | pop | smtp | store]
/etc/NscpMsg stop [imap | pop | smtp | store]
/etc/NscpMsg refresh [imap | pop | smtp | store]
Requirements: Must be run as root locally on the Messaging server.
Location: /etc
server-root/bin/msg/admin/bin
The NscpMsg utility sets the CONFIGROOT and LD_LIBRARY_PATH environment variables for the commands it runs.
NscpMsg is similar to the /etc/NscpMail utility supplied with Messaging Server 3.x.
Table A.15 NscpMsg options
Option
| Description
|
|---|
refresh
| Refresh mail server processes.
|
start
| Starts all mail server processes (stored, smtpd, popd, imapd), or optionally, one specified service.
|
stop
| Stops all mail server processes (stored, smtpd, popd, imapd), or optionally, one specified service.
|
processq
The processq utility immediately delivers messages in the deferred queue.
processq Syntaxprocessq [[-R]hostname]
Requirements: Must be locally run on the server.
Location: /usr/lib
The deferred queue is automatically processed at regular intervals, so you normally never need to deliver the queue manually with the processq utility. You can also manage the queue by using the Netscape Console. For more information, see Managing the Message Queue in Chapter 3.
processq Examples
To deliver all messages in the deferred queue:
/usr/lib/processq
To deliver all queued mail addressed to math.marsu.edu:
/usr/lib/processq -Rmath.marsu.edu
To deliver all queued mail addressed to all hosts in the domain marsu.edu:
/usr/lib/processq `*.marsu.edu'
qconvert
The qconvert utility converts the Netscape Messaging Server 3.x message queue to the Netscape Messaging Server 4.0 format.
Examples of Ways to Use qconvertqconvert [-s sourceq -d targetq] [-l] [-r] [-h] [-f configdbfile]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
If you do not specify the location of the 3.x message queue or the 4.0 message queue, the qconvert utility reads the 3.x and 4.0 configuration files to locate the message queue directories. Consequently, if you do not specify the message queue locations, the following configuration information must be available to the qconvert utility.
For Messaging Server 3.x, configuration information is determined as shown in Table A.18:
For Messaging Server 4.0, configuration information is determined as shown in Table A.19 :
The qconvert utility reads the 3.x directories in the following order:
sourceq/control, sourceq/deferred, sourceq/messages. These directories are subdirectories of the post office directory that was specified at installation time.
The qconvert utility reads and converts the 3.x directories as follows:
The utility reads the 3.x control files and rewrites them into the 4.0 envelope log file located in targetq/control/env-date-1.
The utility reads the 3.x deferred directory and creates an envelope file for every subdirectory in the 4.0 deferred directory.
The utility merges the 3.x message header file (-Header) and message body file (-Body) into one 4.0 file located in targetq/control/msgname.
The utility automatically converts 3.x access rights to 4.0 access rights so that users have access to the appropriate files.
quota
The quota utility reports mailbox quota usage. This utility generates a report listing quotas, giving their limits and usage.
quota Syntaxquota [user/user-id...]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
Netscape Messaging Server 4.0 supports quotas at the root (inbox) level. Quotas on subdirectories are not supported.
readership
The readership utility reports on how many users other than the mailbox owner have read messages in a shared mailbox. This utility scans all mailboxes.
A mailbox owner may grant permission for others to read mail in the owner's box. Administrators can use the readership utility to see how many users are accessing a mailbox other than the owner.
readership Syntaxreadership [-d days] [-p months]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
This utility produces one line of output per mailbox, reporting the number of readers followed by a space and the name of the mailbox.
Each reader is a distinct authentication identity that has selected the mailbox within the past specified number of days. Users are not counted as reading their own personal mailboxes. Personal mailboxes are not reported unless there is at least one reader other than the mailboxes owner.
reconstruct
The reconstruct utility rebuilds one or more mailboxes, or the master mailbox file, and repairs any inconsistencies. You can use this utility to recover from almost any form of data corruption in the mail store.
Note that low-level database repair, such as completing transactions and rolling back incomplete transactions is performed with stored -d.
reconstruct Syntaxreconstruct [-p partition] [-r [mailbox [mailbox...]] | [-m] [-q]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
Note: Netscape recommends that you shut down your server before running the reconstruct utility.
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 of Ways to Use reconstruct
To rebuild all mailboxes in the primary partition:
reconstruct -r -p primary
To rebuild mailboxes listed in the command line argument only if they are in the primary partition:
reconstruct -p primary mbox1 mbox2 mbox3
To perform a high-level consistency check and repair of the mailboxes database:
reconstruct -m
You should use the -m option when:
If the stored -d option is unable to make the database consistent, you should:
Shut down all servers.
Remove all files in server-root/msg-instance/store/mboxlist.
Run stored.
In Unix environments, start stored by entering:
/etc/NscpMsg
start store
Run reconstruct -m to build a new mailboxes database from the contents of the spool area.
After reconstruct -m completes, restart the server processes.
To rebuild the spool area for the mailboxes belonging to the user crowe:
reconstruct -r user/crowe
To rebuild the spool area for all mailboxes listed in the mailbox database:
reconstruct -r
You should use the -r option when:
stored
The stored utility performs the following functions:
The stored automatically performs cleanup and expiration operations once a day at midnight. You can choose to run additional cleanup and expiration operations.
How Messages are Deleted
Messaging Server messages are erased in three stages:
Delete. An IMAP or POP client marks the message to be deleted. IMAP clients mark messages with a /deleted flag, POP clients use the DELE command. This is referred to as deleting a message. At this point, the client can restore the message by removing the "deleted" marking.
Expunge. A client, or the expiration policies you have specified, expunges messages that have been marked deleted from the mailbox. (IMAP clients do this with the EXPUNGE command. POP clients expunge a mailbox with the QUIT command.) Once messages are expunged, the client can no longer restore them, but they are still stored on disk. (A second POP or IMAP client with an existing connection to the same mailbox may still be able to fetch the messages.)
Cleanup. The stored utility erases messages from the disk that have been expunged for at least one hour.
stored Syntax
To run stored from the command line to perform a specific operation:
stored [-1] [-c] [-n] [-h hour] [-v [-v]]
To run stored as daemon:
stored [-d] [-h hour] [-v [-v]]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
Examples of Ways to Use stored
To test expiration policies:
stored -c
To perform a single cleanup pass:
stored -n -v
If you want to change the time of the automatic cleanup and expiration operations, use the configutil utility as follows:
configutil -o store.expirestart -v 21
upgrade
The upgrade utility transfers mailboxes stored in 3.x format on a 3.x server to Netscape Messaging Server 4.0 format mailboxes.
The upgrade utility is similar to the migrate utility provided by 3.x. The 3.x utility migrated both users and their mailboxes. The Messaging Server upgrade utility only transfers mailboxes since the way users are stored has not changed from 3.x to 4.0.
The 4.0 upgrade utility assumes that both Messaging Server 3.x and Messaging Server 4.0 reside on the same machine. The utility transfers the 3.x mailboxes on a machine to 4.0 format mailboxes on the same machine. Once upgrade has been run, you cannot start up the 3.x processes.
The 4.0 upgrade process occurs in two steps: (1) The folders are upgraded. (2) The messages are upgraded. You must update the folders (by using the -s option) before you update the messages (by using the -m or -u options). The message upgrade is a multi-threaded process. You can specify the number of threads by using the -t option.
The 4.0 upgrade utility first searches the LDAP server to find all the user mailboxes in that machine (users are considered to belong the 3.x server if their mailhost attribute is one of the MessageHostNames in that 3.x server). It then creates a one-to-one mailbox-mapping information in the 4.0 mailbox database. These mailboxes are marked as "TRANSITION".
Based on the options you specify, upgrade can transfer all 3.x mailboxes immediately. In NT environments, the upgrade utility retrieves the 3.x information through the registry. In Unix environments, the upgrade utility retrieves the 3.x information through a predefined configuration file. The upgrade does not change the 3.x directory structure, so 4.0 must be put in a different directory.
If you have 3.x mailboxes located in non-default mailbox paths, the upgrade utility tries to create a 4.0 mailbox directory in that mailbox path, and uses a number (such as 001) to automatically assign the 4.0 partition name. In 4.0, the partition name is a logical name of a physical directory where user mailboxes can be physically created.
You can find the detailed mailboxes mapping information in the upgrade.conf file in the default 3.x mailbox directory.
If you want to save disk space, you can use the -r option to remove the messages after the upgrade.
If you have servers on multiple machines, you must run upgrade on each different machine.
Note: The 3.x mailboxes might require more disk space after the upgrade to 4.x. For more information on the upgrade process, see the server installation instructions.
upgrade Syntaxupgrade [-s] [-m] [-u userlist] [-i] [-r] [-h] [-f configdbfile]
[-l ldapURL] [-t number]
Requirements: Must be run locally on the Messaging server.
Location: server-root/bin/msg/admin/bin
Previous
