The following topics are covered in this chapter:

"SIMS Administration Commands" on page 26

"SIMS Monitoring" on page 30

"Message Access and Store" on page 31

"Sun Directory Services" on page 38

"Internet Message Transfer Agent" on page 43

"Installation" on page 59

The command-line utilities described in this chapter allow you to configure and manage server resources for SIMS. Most of the utilities are located in /opt/SUNWmail/sbin. For complete information, see the corresponding man page for the command you want.

---

Note - To view the man page of a compound command, that is a command that consists of two more words such as "imta test -rewrite" or "imadmin create user," type man word-word-word. Example: man imta-test-rewrite

---

SIMS Administration Commands

The SIMS Administration command line (CLI) utilities are also called commands. (The SIMS Administrator uses all the commands. The Delegated Administrator uses the add, modify, delete, and search commands for the user and group objects.) Each command's task and object summary is provided in the imadmin man page. For specific information about the use of these commands, refer to the individual man pages.

TABLE  1-1   SIMS Administration Commands 

Command	Description
imadmin	The imadmin(1M) man page describes the repertoire of SIMS Administration command line (CLI) utilities, also called commands.
imadmin add admin	Grants the SIMS Administrator privileges to a user. To grant privileges to multiple users, use the -i option.
imadmin add group	Adds a single group to the SIMS system. To add multiple groups, use the -i option. When a message is sent to the group address, SIMS sends the message to all members in the group.
imadmin add ldapserver	Adds a single ldap host:port for the admin server. Having multiple ldap servers for the admin server means that the admin server can failover to the next ldap server in the list when one ldap server goes down. To add multiple ldapservers with the same command, use the -i option.
imadmin add user	Adds a single user to the SIMS system. To add multiple users, use the -i option. You can run the imadmin add user command remotely using the DMS and supplying the domain name option.
imadmin create domain	Creates a single domain in the SIMS system. To create multiple domains, use the -i option.
imadmin delete domain	Deletes a single hosted domain from the SIMS system. To delete multiple hosted domains, use the -i option. When you invoke the command, the simsDomainStatus attribute of the domain's DC node entry is set to deleted. There is no undelete utility.
imadmin delete group	Deletes a single group from the SIMS system. To delete multiple groups, use the -i option. When you invoke this command, the inetmailGroupStatus of the group is set to deleted. There is no undelete utility.
imadmin delete user	Deletes a single user from the SIMS system. To delete multiple users, use the -i option. When the hostname option is used by a Delegated Administrator, hostname refers to the Delegated Management Server (DMS) host. When used by a SIMS Administrator, hostname refers to the LDAP host. When you invoke this command, the inetSubscriberStatus of the user is set to deleted. The deleted user remains connected to the system until the purge task is run against the user. There is no undelete utility.
imadmin modify currentldap	Modifies the current ldap server property of the admin server. After this command is executed successfully, the admin GUI and CLI will use the specified ldap server for it's directory operations.
imadmin modify domain	Modifies attributes of a single domain's directory entry. To modify multiple domains, use the -i option.
imadmin modify group	Changes the attributes of a single group that already exists in the SIMS system. To change multiple groups, use the -i option.
imadmin modify msglimits	Changes the message limits attributes of a single existing channel. To change multiple channels, use the -i option.
imadmin modify notary	Changes the delivery status notification schedule of a single channel. To change multiple channels, use the -i option. For a permanent failure, the message is bounced and a notification is sent to the postmaster. For a transient failure, by default, the channel sends a maximum of three warning messages to the originator of the message.
imadmin modify postmaster	Returned messages: SIMS might be unable to deliver a message because of long-term service failures or invalid addresses. The IMTA channel program returns the message to the sender with an accompanying explanation of why the message was not delivered. Warning messages: The IMTA occasionally sends warnings detailing messages that it has been unable to deliver. This is generally due to timeouts based on the setting of the notices channel keyword. The warning messages contain a description of what is wrong and how long delivery attempts will continue. To modify messages for multiple channels, use the -i option.
imadmin modify user	Changes the attributes of a single user that already exists in the SIMS system. To change multiple users, use the -i option. You can run the imadmin modify user command remotely using the Delegated Management Server and supplying the domain name option.
imadmin purge domain	Permanently deletes a single domain from the SIMS system. To permanently delete multiple domains, use the -i option. Use the command to remove all domains that have been deleted by the status attribute for a time period that is longer than the specified grace period. You can perform a purge at any time by invoking the command manually.
imadmin purge group	Use the command to permanently delete all groups that have been deleted by the status attribute for a time period that is longer than the specified grace period. To permanently delete multiple groups, use the -i option. You can perform a purge at any time by invoking the command manually. There is no undelete utility.
imadmin purge user	Use the command to remove all users who have been deleted by the status attribute for a time period that is longer than the specified grace period. To permanently delete multiple users, use the -i option. You can perform a purge at any time by invoking the command manually.
imadmin remove admin	Removes SIMS Administrator privileges from a user. To remove SIMS Administrator privileges from multiple users, use the -i option.
imadmin search admin	SIMS Administrators use this command to search and display users who have SIMS administrative privileges. The -n domain name option will distinguish a Delegated Administrator when the option is specified. When the -n option is omitted, the command will filter for all users who have been granted SIMS Administrator privileges.
imadmin search group	Obtains all the LDAP attributes associated with a single group. To obtain all the LDAP attributes for multiple groups, use the -i option.
imadmin search msglimits	Searches for the message limits attributes of single existing channel. To search for attributes for multiple channels, use the -i option.
imadmin search notary	Searches for the delivery status notification schedule of a single channel. To perform a search of the schedules for multiple channels, use the -i option.
imadmin search postmaster	Returns the values of the variables, which direct the system how to treat failure and warning messages for a single postmaster. To return values for multiple postmasters, use the -i option.
imadmin search user	Obtains the LDAP attributes associated with one or more users.

The following commands are part of the SIMS Administration.

TABLE  1-2   SIMS Administration Commands - miscellaneous

Command	Description
imedit	Used when the specified configuration file (config_file) is locked according to the SIMS configuration file locking convention. The contents of config_file are copied to a temporary file in the same directory. The editor specified by the VISUAL or EDITOR environment variables is invoked on the temporary file. If the editor exits with status 0, the temporary file is renamed to the specified file name (config_file) and unlocked. If the editor exits with a non-zero status, the temporary file is removed and the specified file is unlocked.
imxclean	Checks for the existence of SIMS configuration file update logs that are not locked by any running process. If any are found, they are assumed to represent SIMS configuration file transactions that were interrupted before completion. imxclean examines the log and rolls the transaction forward or backs the transaction out, according to whether or not the transaction has been committed.
setup-tty	A script that installs the Sun Internet Mail Server (SIMS) and related files and packages onto the system.
uninstall	A script that removes the Sun Internet Mail Server (SIMS) and related files and packages from the system. You can specify uninstall to perform a standard or dramatic uninstall procedure. The dramatic uninstall option is a clean uninstall, removing all files installed by the SIMS installation process and created by SIMS during operation, except packages that may have already been present before the uninstall procedure

SIMS Monitoring

These commands let you monitor the components of SIMS. For the specifics concerning the use of these related commands, refer to the man pages.

TABLE  1-3   SIMS Monitoring Commands 

Command	Description
immonitor	The umbrella script for monitoring the components of SIMS. For information about the installation, configuration, and example usage of these utilities look at the Monitoring_ex_conf_scen.html, Monitoring_install.html, and Monitoring_intro.html. These are found in /opt/SUNWmail/html/C.
immonitor access	Monitors the SIMS services, comprising Mail Delivery (SMTP), Message Access and Store (POP, IMAP), and Directory Service (LDAP). The Directory Service is monitored by looking up a specified user in the directory and measuring the response time. The Mail Delivery is monitored by sending a mail (SMTP) and the Message Access and Store is monitored by retrieving it. (POP/IMAP). This utility measures the response times of the various services and the total round trip time taken to send and retrieve a message.
immonitor queue	Monitors the IMTA component. Can be used to report the domains to which delivery has failed, the number of messages in the queue that are not eligible for delivery processing (messages with .HELD extension) and the number of messages in each channel queue.
immonitor reenqueue	Re-submits messages. The utility re-enqueues the message, for the movement to another channel to take place. The new channel with the rewrite rules must be created by the administrator prior to executing this command. Look at SIMS Administrator's Guide to create channel and add rewrite rules.
immonitor system	Monitors the status of system resources utilized by SIMS. These include: the swap space disk utilization the number of connections in the ESTABLISHED state.
immonitor users	Reports user information including top <n> submitters and targets of a SPAM attack. Looking at this information the administrator can block connections from a spammers domain or move their messages to a slower channel.

Message Access and Store

Message Access and Store refers to the data stores,protocol servers, software drivers, and libraries that support message delivery, storage, retrieval, and final disposition. The following command line utilities are used for message access and storage and are outlined in this section. Detailed information about access and store utilities can be found in the man pages.

imaccessd

imaccessd provides email clients with access to the Sun Internet Mail Server. The imaccessd daemon supports two access protocols: Post Office Protocol, version 3 (POP3, RFC 1939); and Internet Message Access Protocol (IMAP, RFC 2060). The imaccessd daemon process normally runs whenever the mail server is up. Unlike other commands, imaccessd is a daemon which, when started, runs in the background. If this daemon is not running, all client requests for IMAP or POP connections receive a "Connection Refused" error.

imbackup

Use the imbackup utility to back up stored Sun Message Store messages. imbackup should be run as the message store owner as specified in the ims.cnf file. The default owner should be set to inetmail.

---

Caution - The imbackup utility is unable to backup /var/mail messages, MIME files, and messages stored in the queues.

---

imcheck

The imcheck command validates the message store and the user files, reports errors, and generates message store reports. In addition to validating the message store and generating reports, it also allows you to recover the message store from a crash.

Messages may be lost if a crash occurs after the messages have been removed from mail queue by IMTA, but have not yet been "sync-ed" in the user file. When the -c option is specified, imcheck looks at all the messages delivered to the message store within the last few minutes before the crash, verifies if they are in the user files, and redelivers those that are not. Users may get the same message twice after a crash recovery.

---

Note - You must be logged in as the message store owner to use this utility.

---

imdeluser

imdeluser is a utility for the system administrator to remove a user from the message store. imdeluser is a utility command and needs to be run on the server as root.

If all of the following conditions are valid, all the folders and user files for the specified user are removed from the message store:

Administrator entered the correct user name and password

User or public shared folder exists in the message store

User is not receiving messages

---

Note - In SIMS 3.5 you needed to enter the full LDAP DN of the administrator. In Sun Internet Mail Server 4.0, you need to enter the login name (not the user name) of the administrator who has authority to manage the users in their domains.

---

imexpire

imexpire scans all user folders in the message store and marks all the messages that match the specified criteria as permanently deleted, or "expired." The deleted messages will be expunged from the user mailbox when the user connects or disconnects from the server.

The actual data will be removed from the message store when impurge -a is run after the imexpire utility.

imexpire must be run on the message store server by root or by the message store owner.

---

Note - imexpire does not remove expired messages from the message store. It only marks those messages as "expired." You must run impurge -a after you run imexpire to reclaim the disk space. When imexpire is used with the -s option, it marks the "unseen" messages as "pending" instead of "expired." Once a message is marked as "pending", imexpire will not expire the message. You must run impurge -a to clear the "pending" flag.

---

imexportmbox

imexportmbox is a SIMS utility which allows the message store owner (usually inetmail) to copy a user's folders to a target directory. Unless the -s option is used to specify a single folder, all the user's folders are copied into the destination directory preserving any folder hierarchies in the form of directories. If the destination directory does not exist, imexportmbox will attempt to create it. If a file already exists in the destination directory, imexportmbox will not overwrite the file and will move on to the next folder.

imexportmbox must be run as the message store owner as specified in the ims.cnf file. The default owner should be set to inetmail. The destination directory must allow the message store owner write permission.

imimportmbox

As the administrator, to populate your SIMS 3.5 message store with a user's existing messages and folders, you need to execute the message store utility called imimportmbox. This utility helps you to move the user's existing inbox messages and folders from existing /var/mail format to the newly installed message store.

It is possible to specify a non-existent user with imimportmbox.

---

Note - Run this utility as root or as the message store owner.

---

iminitquota

The iminitquota utility reinitializes the user's in the user's mailbox based on their LDAP entry and recalculates the total amount of disk space that is being used by the specified user. It updates the file quota under the user's Adm directory in the Message Store. This file will be read by the delivery agent when trying to determine if a certain user is over-quota.

iminitquota must be run as the message store owner as specified in the ims.cnf file. The default owner should be set to inetmail.

impurge

The impurge utility removes messages from the Message Store that are no longer referenced from any user folders, and returns the space to the file system. When a user deletes a message, the reference to the message is also removed. Eventually, all users who received the message may remove their references. When the last reference is gone, the message can be purged from the store.

The purge operation requires a considerable amount of time and system resources. Do not wait until your disk is full before attempting a message purge. Run impurge while there is more disk space than the amount of space used by the message store on the busiest 24 hour period of the message store. You can check the message store disk usage by noting the disk usage increase on the /var/opt/SUNWmail/ims partition over a 24 hour period.

---

Note - Messages under 2 days old will not get purged.

---

imquotacheck

imquotacheck, the Quota Notification utility, calculates the total mailbox size for each user in the message store, compares the size with their assigned quota, and sends a notification via email to the users that have exceeded a set percentage of their assigned quota. The default percentage used to determine quota is exactly 90%. The -p option may be used to specify a different percentage.

If the -v or -u options are not specified, imquotacheck displays only the users who have exceeded the quota.

imquotacheck must be run as the message store owner as specified in the ims.cnf file. The default owner should be set to inetmail.

---

Note - The content of the quota notification message can be changed.

---

imrestore

imrestore is the utility used to restore messages from the backup device into the message store.

imsasm

imsasm is an external Solstice Backup ASM (Application Specific Module) that handles the saving and recovering of user mailboxes. imsasm is used in Solstice Backup (Networker) and invokes the imbackup and imrestore 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 imbackup or imrestore command on the user's mailbox.

When browsing the file details with the nwrecover program, files (mailboxes) saved with imsasm will appear empty, but the full contents will be restored when they are actually recovered.

imsinit

imsinit is the utility that initializes the message store file system.

The top-level directories are specified in the /etc/opt/SUNWmail/ims/ims.cnf file. If a default SIMS installation has been performed, these directories are:

/var/opt/SUNWmail/ims/index

/var/opt/SUNWmail/ims/hash

/var/opt/SUNWmail/ims/data

/var/opt/SUNWmail/ims/adm

/var/opt/SUNWmail/ims/shared

/var/opt/SUNWmail/ims/user

The preceding directories must also be owned by the message store owner as specified in the ims.cnf file. If a default SIMS installation has been performed, the owner should be set to inetmail.

If the top-level directories are not present imsinit will create them.

Upon successful completion, the message store file system is initialized.

---

Note - You cannot run this command after you have initialized a message store in /var/opt/SUNWmail/ims.

---

mkbackupdir

The mkbackupdir utility creates and synchronizes the backup directory with the information in the message store. It is used in 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 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

The variables in the backup directory contents are:

ADM_ROOT	The message store administrator root directory as specified in the /etc/opt/SUNWmail/ims/ims.cnf file. The default directory is /var/opt/SUNWmail/ims/adm.
group	The user-defined group directory created by the system administrator.
user	Name of the message store user.
folder	Name of the user mailbox directory.
mailbox	Name of the user mailbox.

The mkbackupdir utility creates:

a user directory under the backup directory for each new user in the message store

a user folders hierarchy under the user/Mail subdirectory

a .nsr file for each subdirectory that contains user mailboxes

The user folder hierarchy (user/Mail) contains the same structure as the user/Mail directory in the message store. The INBOX and the user mailboxes under the folder hierarchy contain zero length files that represent the mailbox names that are to be saved. They do not contain the actual data.

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 is a file of zero length. This includes the INBOX, which is located under the user directory.

Sun Directory Services

This section summarizes the Sun Directory Services (LDAP) utilities commonly used for SIMS administration. For usage information on these utilities, refer to the Sun Directory Services documentation and the SIMS Administrator's Guide. For complete syntax and option information refer to the specific utility man pages.

---

Note - You can specify a regular expression for the distinguished name of an entry. For example, the regular expression dn="cn=Joe Smith, ou=.*,dc=XYZ, dc=com,o=internet" specifies the set of entries for people called Joe Smith in the whole of the XYZ Corporation. DN-based regular expressions are useful when defining access controls.

You can also use a DN-based regular expression to specify a set of values for an attribute whose values are DNs. For example, you can grant write access to a distribution list entry to any person whose DN is a value of the member attribute, using the regular expression member="dn=.*".

---

dsserv

The dsserv daemon is the directory server daemon. It listens for LDAP connections on port 389, responding to the LDAP operations it receives over these connections. dsserv is typically invoked at boot time, usually out of /etc/rc.local. Upon startup, dsserv normally forks and dissociates itself from the invoking tty. If the -d flag is specified, and debugging is set to a non-zero value, dsserv does not fork and dissociates from the invoking tty.

The dsserv daemon can be configured to provide replicated service for a data store, in conjunction with slurpd, the directory server update replication daemon. See the section "dspushd" on page 40 for details.

dsserv.conf

The file dsserv.conf contains configuration information for the dsservd daemon. This configuration information is also used by the dspushd and dspulld replication daemons and by the LDBM indexing utilities ldif2ldbm, ldif2index, ldif2id2entry, and ldif2id2children.

The dsserv.conf file consists of a series of global configuration options that apply to dsservd as a whole (including all data stores), followed by zero or more definitions that contain information specific to a data store.

dsserv.acl.conf

The file dsserv.acl.conf contains access control rules (also called ACLs) that apply to information stored in the directory. ACLs protect sensitive information such as user pass words. You can create extra ACLs that are specific to the kind of information that you need to protect. ACLs can be defined by using the Admin Console, or by hand, by editing the dsserv.acl.conf file. The syntax for an access control rule is:

access to what [ by who accesslevel ]...

Grant access (specified by accesslevel) to a set of entries and/or attributes (specified by what) by one or more requestors (specified by who).

dsserv.at.conf

The file dsserv.at.conf contains the SIMS attributes.

dsserv.oc.conf

The file dsserv.oc.conf contains the SIMS object class.

dsserv.replog

The file dsserv.replog is produced by the stand-alone LDAP daemon, dsservd, when changes are made to its local database that are to be propagated to one or more replica data stores. The file consists of zero or more records, each one corresponding to a change, addition, or deletion from the database. The file is used by dspushd, the stand-alone LDAP update replication daemon. The records are separated by a blank line.

dsservcmd

The dsservcmd command sends orders to the dsserv daemon to set the trace level, put the database into, and out of, read-only mode (for backup), and get SNMP statistics about the dsserv daemon.

dsprepush

The dsprepush command creates a replication log file for the replication daemon slurpd to use when creating a new replica. It extracts entry information from the data base directory (databasedir) and creates appropriate replica entries. All parameters are optional. If you do not supply any parameters, dsprepush generates replica entries for all databases and for all replica (slave) servers.

dspushd

The dspushd daemon is used to propagate changes from one dsserv database to another. If dsserv is configured to produce a replication log, dspushd reads that replication log and sends the changes to the replica dsserv instances using the LDAP protocol.

Upon startup, dspushd reads the replication log (given either by the replogfile directive in the dsserv configuration file, or by the -r option). If the replication log file does not exist or is empty, dspushd goes to sleep. It periodically wakes up and checks to see if any changes need to be made.

When changes need to be made to replica dsserv instances, dspushd locks the replication log, makes a private copy, releases the lock, and forks one copy of itself for each replica dsserv to be updated. Each child process binds to the slave dsserv with the DN given by the binddn option to the replica directive in the dsserv config file, and sends the changes. See dsprepush for details on the directory server daemon.

---

Note - By default, dspushd is set up not to run. To start it, you must modify /etc/opt/SUNWconn/ldap/current/dsserv.ini and change startDspush=true. Restart dsserv.

---

imldifsync

The imldifsync command synchronizes LDAP directory entries with data in passwd format and data in aliases format. It is used to generate and update directory entries for users and for groups in LDAP Directory Interchange Format (LDIF). The LDIF file format is described in ldif(4) and dsserv.replog. Entries created from the content of the LDIF file can be added to an LDAP directory using ldapmodify.

The imldifsync command runs in two modes that are mutually exclusive: user mode (option -u) to create user entries, and group mode (option -g) to create group entries. When you create or update your directory database, you need to run imldifsync twice: first in user mode, then in group mode. It is important to generate users first and apply the changes to the directory database before generating groups.

To generate user entries and email addresses, the imldifsync command uses the password file and alias file. The common name of each user entry is generated from the gecos field (the fifth field in the password file) by a conversion script. You can specify your own conversion script using the -G option if the default conversion does not meet your requirements.

To generate group entries, the imldifsync command uses primarily the alias file. Information about the members of a group is taken from the directory database, from the previously generated user entries.

Each entry must have a unique name. If two entries have the same name, the second entry is written to a temporary file in /tmp and a warning message is generated. Entries for which a proper common name cannot be created are ignored, and an error is generated.

When the program exits (or is terminated by CTRL-C), it prints some statistics to stderr indicating how many DNs were added, modified, or found to be duplicates. In the case of duplicates, it indicates the name of the temporary file to which they were written.

ldapadd

The ldapadd utility is used to add email entry tools. The entry information is read from standard input or from a file, specified using the -f option. The ldapadd command is a variant of the ldapmodify command. When invoked as ldapadd, the -a (add new entry) flag is turned on automatically. Additional information about modifying email entry tools can be found in the following section entitled ldapmodify."

ldapdelete

The ldapdelete command opens a connection to an LDAP server, binds, and deletes one or more entries. If one or more dn arguments are provided, entries with those distinguished names are deleted. If no dn arguments are provided, a list of DNs is read from file, if the -f flag is specified, or from standard input.

ldapmodify

The ldapmodify command opens a connection to an LDAP server, binds, and modifies or adds entries. The entry information is read from standard input or from a file, specified using the -f option. The ldapadd command is a variation of the ldapmodify command. When invoked as ldapadd, the -a (add new entry) flag is automatically turned on. Both ldapadd and ldapmodify reject duplicate attribute-name/value pairs for the same entry.

ldapsearch

The ldapsearch command opens a connection to an LDAP server, binds, and performs a search using the filter filter. If ldapsearch finds one or more entries, the attributes specified by attrs are retrieved and the entries and values are printed to standard output. If no attributes are listed, all attributes are returned.

ldbmcat

The ldbmcat command is used to convert a dsserv LDBM database to the LDAP Directory Interchange Format (LDIF) as defined in ldif2ldbm." It opens the id2entryfile file for the database to be converted and writes the corresponding LDIF output to standard output.

ldif

The ldif command converts arbitrary data to the LDAP Directory Interchange Format (LDIF). ldif reads data from standard input, converts it, and writes the corresponding LDIF output to standard output. The output is suitable for use as a line in an LDIF file.

By default, ldif considers its input a sequence of values, one value on each line, to be converted to values of the specified attribute. With the -b flag, ldif considers its input as a single raw binary value to be converted. This is useful when converting binary data such as a photo or audio attribute.

ldif2ldbm

This section describes the following conversion utilities used to convert LDIF to LDBM database format:

ldif2ldbm

ldif2index

ldif2id2entry

ldif2id2children

These utilities convert a database in LDAP Directory Interchange Format (LDIF) to an LDBM database suitable for use by dsserv. Normally, you need only use ldif2ldbm. It invokes the other utilities as necessary. Occasionally, it may be necessary to invoke them directly. For example, to create a new index file for an existing database, use the ldif2index program. To do the reverse conversion, from LDBM to LDIF, use the ldbmcat command, described in ldbmcat."

Internet Message Transfer Agent

The IMTA contains a modest collection of management utility programs that are used to perform various maintenance, testing, and management tasks. The following sections describe these utilities.

This section summarizes the Internet Message Transfer Agent (IMTA) utilities. These commands are in the /opt/SUNWmail/imta/sbin/ directory. You need to be logged in as root to run the imta start, imta stop, imta dirsync, and imta restart commands. Unless mentioned otherwise, all IMTA commands should be run as inetmail (the postmaster account created during installation).

TABLE  1-4   IMTA Utilities 

Utility	Description
imta cache -close	Has detached processes close their connections to the queue cache database.
imta cache -rebuild	Builds a new, synchronized queue cache database.
imta cache -synch	Synchronizes the current queue cache database.
imta cache -view	Views entries in the queue cache database.
imta chbuild	Compiles the IMTA character set conversion tables.
imta clbuild	Compiles an IMTA command definition file.
imta cnbuild	Compiles the IMTA configuration, alias, mapping, security, system wide filter, and option files
imta counters -clear	Clears the in-memory cache of channel counters
imta counters -show	Displays the contents of the database of channel counters
imta counters -today	Displays count of the number of messages processed today
imta crdb	Creates a IMTA database
imta dirsync	Recreates or updates the IMTA directory cache.
imta find	Finds the file name corresponding to the specified version of a IMTA file.
imta process	Lists currently running IMTA jobs.
imta program	Uses to manipulate the IMTA program delivery options.
imta purge	Purges IMTA log files.
imta qm	Manages IMTA message queues.
imta queue	Performs maintenance tasks on imta queue. The imta queue -retry_delivery channel_name command reprocesses HELD messages in the channel specified by the channel_name parameter. To avoid mail loops, the IMTA holds messages when they have been forwarded more than 30 times. When corrected, the administrator can run this command to reprocess all the HELD messages. The imta queue -recover_crash command rebuilds the MTA queue-cache database after a crash.
imta renamedb	Renames an IMTA database.
imta restart	Restarts detached IMTA processes.
imta return	Returns (bounce) a mail message to its originator.
imta run	Processes messages in a specified channel.
imta start	Starts detached IMTA processes.
imta stop	Shuts down the IMTA job controller and the IMTA Service Dispatcher.
imta submit	Processes messages in a specified channel.
imta submit_master	Process messages in a specified channel; on UNIX, a synonym for submit.
imta test -mapping	Test a mapping table.
imta test -match	Test a mapping wildcard pattern.
imta test -rewrite	Tests address rewriting.
imta view	Displays the contents of the specified "version" of a IMTA log file.
imta version	Prints the SIMS version number.

imta cache

The IMTA maintains a disk cache of all the messages currently stored in its queues. This cache is called the queue cache. The purpose of the queue cache is to make dequeue operations perform more by relieving master programs from having to open every message file to find out which message to dequeue and in which order.

The queue cache consists of the indexed files contained in the directory pointed at by the IMTA_QUEUE_CACHE_DATABASE option in the IMTA tailor file, /etc/opt/SUNWmail/imta/imta_tailor. Normally, the queue cache directory is called /etc/opt/SUNWmail/imta/queue_cache. This directory and the files it contains should be protected against world and group access and have the same uid as the directories /var/opt/SUNWmail/imta/queue and /var/opt/SUNWmail/imta/log.

imta cache -close

The imta cache -close command forces IMTA processes to close any open I/O channels to the queue cache database. This is generally done for two reasons: to close all channels to the files in the database so that the database can be modified, and to force processes to reopen the queue cache database files, to begin using any new version of that database.

imta cache -rebuild

The imta cache -rebuild command creates a new, synchronized queue cache. Although the new database inherits the ownership and file protections of the queue cache, it is a good idea to check afterwards that the new queue cache directory and files have the same uid as the queue and log directories and that the queue cache database directory and files are protected against group and world access.

---

Caution - Rebuilding the queue cache database with this command should only be performed as a last resort-for example, if disk problems have corrupted your queue cache database-as it will cause loss of some information from the queue cache database. The type of information lost includes, but is not limited to, message creation dates, deferral dates, and expiration dates.

---

imta cache -sync

The imta cache -sync command updates the active queue cache database by updating it to reflect all non-held message files currently present in the /var/opt/SUNWmail/imta/queue/* subdirectories. The imta cache -close command does not need to be issued in conjunction with the imta cache -sync command.

Note that the imta cache -sync utility does not remove any entry from the queue cache. The queue cache entries not corresponding to an actual queued message are silently discarded by master programs. They can also be removed using the imta cache -rebuild utility.

imta cache -view

The imta cache -view command shows the current non-held entries in the IMTA cache database for a channel.

imta chbuild

The imta chbuild command compiles the character set conversion tables and loads the resulting image file into shared memory. The IMTA ships with complete character set tables so you would not normally need to run this command.

imta clbuild

The imta clbuild utility compiles a command line definition file and loads the resulting image file into shared memory. The IMTA ships with a pre-compiled command line definition image so it is not normally necessary to run this utility.

You must have superuser privileges to run this utility.

TABLE  1-5   clbuild cld-file-spec

Command Qualifiers	Defaults
-debug	-nodebug
-image_file=file-spec	-noimage_file
-maximum	-nomaximum
-option_file=file-spec	-nooption_file
-remove	None
-sizes	-nosizes
-statistics	-nostatistics

The file specification of a an IMTA command definition file to read as input; for example, /opt/SUNWmail/imta/lib/imta.cld.

Example

The standard command used to compile the basic IMTA command definition file is:

# imta clbuild -option_file -image_file=IMTA_COMMAND_DATA 
/opt/SUNWmail/imta/lib/pmdf.cld

imta cnbuild

The imta cnbuild command compiles the textual configuration, option, mapping, conversion, and alias files, and loads the resulting image file into shared memory. The resulting image is saved to a file usually named /opt/SUNWmail/imta/lib/config_data by the IMTA_CONFIG_DATA option of the IMTA tailor file, /etc/opt/SUNWmail/imta/imta_tailor.

Whenever a component of the IMTA (for example, a channel program) must read a compiled configuration component, it first checks to see whether the file named by the IMTA tailor file option IMTA_CONFIG_DATA is loaded into shared memory; if this compiled image exists but is not loaded, the IMTA loads it into shared memory. If the IMTA finds (or not finding, is able to load itself) a compiled image in shared memory, the running program uses that image. This rule has two exceptions:

The reason for compiling configuration information is performance. The only penalty paid for compilation is the need to recompile and reload the image any time the configuration or alias files are edited. Also, be sure to restart any programs or channels that load the configuration data only once when they start up, for example, the IMTA multithreaded TCP SMTP server.

It is necessary to recompile the configuration every time changes are made to any of the following files:

IMTA configuration file (or any files referenced by it)

IMTA system alias file, the IMTA mapping file

IMTA option file

IMTA conversion file

These are the files pointed at the IMTA tailor file options: IMTA_CONFIG_FILE, IMTA_ALIAS_FILE, IMTA_MAPPING_FILE, IMTA_OPTION_FILE, and IMTA_CONVERSION_FILE, respectively, which usually point to the following files:

/etc/opt/SUNWmail/imta/imta.cnf

/etc/opt/SUNWmail/imta/aliases

/etc/opt/SUNWmail/imta/mappings

/etc/opt/SUNWmail/imta/option.dat

/etc/opt/SUNWmail/imta/conversions

---

Note - Until the configuration is rebuilt, changes to any of these files are not visible to the running IMTA system.

---

imta counters -clear

The IMTA accumulates in the form of message traffic statistics for each of its channels. These statistics are referred to as channel counters. The counters are kept in a shared memory cache.

The imta counters -clear command clears the in-memory channel counters.

Syntax

imta counters -clear

imta counters -create

The imta counters -create command creates an in-memory cache of channel counters.

---

Note - Do not execute this utility if you already have in-memory counters because imta start creates this section. Normally this utility should never be used unless you have manually deleted the counters using imta counters -delete.

---

imta counters -show

The contents of the in-memory cache of channel counters may be displayed with the imta counters -show command.

imta counters -today

imta counters -today counts and displays the number of messages processed on this day. Note that the messages counted are the number of messages processed at the time that this command is executed.

Example

# imta counters -today

4263 messages processed so far today 

30000 messages per day are permitted by your license 

This example shows IMTA's count of the number of messages processed so far on a particular day.

imta crdb

The imta crdb command creates and updates IMTA database files. imta crdb converts a plain text file into IMTA database records; from them, it either creates a new database or adds the records to an existing database.

In general, each line of the input file must consist of a left side and a right side. The two sides are separated by one or more spaces or tabs. The left side is limited to 32 characters in a short database (the default variety) and 80 characters in a long database. The right side is limited to 80 characters in a short database and 256 in a long database. Spaces and tabs may not appear in the left side.

imta dirsync

The imta dirsync utility recreates or updates the IMTA directory cache.

The -t option executes dirsync in the test mode. It searches the directory and prints out the details on invalid entries, if there are any. No changes are made to the cache itself. Run this in conjunction with the -F option (causes the directory cache to be completely regenerated, thus creating a faithful image of the directory) to test the entire directory contents used by this MTA. Without the -F option, only the new additions are tested.

---

Note - You must be logged in as root to use this utility.

---

imta find

The imta find command finds the precise file name of the specified version of an IMTA file. IMTA log files contain a -uniqueid, which is appended to the file name to allow for the creation of multiple versions of the log file.

imta find understands these unique ids and can find the particular file name corresponding to the requested version of the file.

TABLE  1-6   imta - find file pattern

Command Qualifiers	Defaults
-f=offset-from-first	None
-l=offset-from-last	None

By default, if no offset qualifier ( n ) is specified, imta find locates the most recent version of the file.

Examples

# imta find /var/opt/SUNWmail/imta/log/tcp_local_slave.log

This command will print out the file name of the /imta/log/tcp_local_slave.log-uniqueid file most recently created.

# imta find /imta/log/tcp_smtp_server.log -f=0

This command will display the file name of the oldest /var/opt/SUNWmail/imta/log/tcp_local_slave.log-uniqueid file.

imta process

This command displays the current IMTA processes. The IMTA Service Dispatcher and the IMTA Job Controller and SMTP should be present; in the Departmental Edition, the IMTA Job Controller should be present. Additional processes may be present if messages are currently being processed, or if certain additional IMTA components are in use.

imta program

The imta program commands are used to manipulate the program delivery options.

These commands can be executed as root or inetmail. A change in an existing one will take effect only after the next full dirsync is performed.

imta purge

The imta purge command deletes older versions of IMTA log files. imta purge can determine which log files are older, based on the uniqueid strings terminating IMTA log file names.

imta qm: Queue Management

The imta qm command is a utility for inspecting and manipulating the channel queue directories and the messages contained in them. It has some functionality overlap with the imta cache, imta queue, and imta counters commands. Privileges sufficient to read, create, and delete files in the channel queue directory tree as well as read and update the queue cache database are required to use this.

For example, imta queue -retry_delivery can be achieved using the release command in imta qm. As another example, some of the information returned by imta cache -view is also available through the directory command in imta qm. However, imta qm does not completely replace imta cache or imta queue.

imta qm can only be run by root or inetmail.

To run imta qm in interactive mode, issue the command

$ imta qm

To run imta qm in non-interactive mode, issue a command such as:

$ imta qm <command>

Use the exit or quit command to exit imta qm. The commands accepted by this utility in maintenance mode are summarized in .

---

Note - Some of the commands available in the interactive mode are not available in the non-interactive mode and the reverse is also true.

---

TABLE  1-7   imta qm Mode Commands 

Commands	Descriptions
counters	Controls aspects of the channel counter caches and database.
date	Shows current date and time
delete	Irrevocably deletes the specified messages
directory	Lists currently queued messages
exit	Exits the utility.
held	Lists messages which have been marked as held.
help	Obtains help.
history	Displays message delivery history information.
hold	Marks a message as held.
quit	Exits the utility.
read	Displays message envelope and header information
release	Releases held message.
return	Returns a message to its originator.
run	Executes commands from the specified file.
view	Controls whether the channel queue directory tree or queue cache database is viewed.

imta queue

Use the imta queue command to perform common maintenance tasks on the IMTA message queues. Unlike the imta cache utility, operations performed with imta queue apply not only to the queue cache database but also to the actual message queues (message files).

imta renamedb

The imta renamedb command renames an IMTA database. Since the IMTA may optionally reference several "live" databases, that is, databases whose presence triggers their use by the IMTA, it is important, first, to ensure that the IMTA does not see such a database while it is in a mixed state, and second, to minimize any period of time during which the database is inaccessible. The imta crdb command locks the database it is creating to avoid having it accessed in a mixed state.

To create or update the IMTA databases:

The imta renamedb utility, which must delete any old database files and rename the new database files, locks the database during the renaming process to avoid presenting the database in a mixed state. This way, the database is never accessible while it is in a mixed state, yet any window of time during which the database is inaccessible is minimized. Renaming is generally quicker than database generation.

imta restart

The imta restart command stops any IMTA Job Controller or IMTA Service Dispatcher jobs that are running, and restarts the IMTA Job Controller and IMTA Service Dispatcher. Detached IMTA processes should be restarted whenever the IMTA configuration is altered--these processes load information from the configuration only once and need to be restarted in order for configuration changes to become visible to them. In addition to general IMTA configuration files, such as the imta.cnf file, some components, such as the IMTA Service Dispatcher, have their own specific configuration files, for example, dispatcher.cnf, and should be restarted after changes to any of these files.

---

Note - You must be logged in as root to use this utility.

---

imta return

The imta return command returns a message to the message's originator. The returned message is in two parts. The first part explains why the message is being returned. The text of the reason is contained in the file return_bounce.txt located in the /etc/opt/SUNWmail/imta/locale/C/LC_MESSAGES/ directory. The second part of the returned message contains the original message.

imta run

The imta run command processes the messages in the channel specified by the channel parameter. Output during processing is displayed at your terminal, which makes your terminal unavailable for the duration of the operation of the utility. Refer also to the imta submit command that, unlike imta run, does not monopolize your terminal.

imta start

The imta start command starts up detached IMTA processes. If no component parameter is specified, then the IMTA Job Controller and IMTA Service Dispatcher are started. Starting the Service Dispatcher starts all services the Service Dispatcher is configured to handle, which may include SMTP server. If a component parameter is specified, then only detached processes associated with that component are started. The standard component names are:

Component	Description
dispatcher	Multithreaded Service Dispatcher
job_controller	Schedules deliveries (dequeues messages).

The services handled by the IMTA multithreaded Service Dispatcher must be started by starting the IMTA Service Dispatcher. Only services not being handled by the IMTA Service Dispatcher can be individually started using the imta start command. The Service Dispatcher may be configured to handle various services, for example, the multithreaded SMTP server.

---

Note - You must be logged in as root to use this utility.

---

imta stop

The imta stop command shuts down the IMTA Job Controller and the IMTA Service Dispatcher. Shutting down the IMTA Service Dispatcher shuts down all services (for example, SMTP) being handled by the Service Dispatcher.

---

Note - You must be logged in as root to use this utility.

---

imta submit

The imta submit command forks a process to execute the messages in the channel specified by the channel parameter.

imta test -mapping

Use the imta test -mapping utility to test the behavior of a mapping table in the mapping file. The result of mapping an input string will be output along with information about any meta characters specified in the output string.

If an input string is supplied on the command line, then only the result of mapping that input string will be output. If no input string is specified, imta test -mapping will enter a loop, prompting for an input string, mapping that string, and prompting again for another input string. imta test -mapping will exit when you press CTRL-D.

TABLE  1-8   imta test -mapping syntax

Command Qualifiers	Defaults
-flags=list of characters	-noflags
-image_file	-image_file
-mapping_file=file-spec	-mapping_file=IMTA_MAPPING_FILE
-option_file=file-spec	-option_file=IMTA_OPTION_FILE
-table=table-name	None

Example

In the following example, the sample PAGER mapping is tested. The -mapping_file qualifier is used to select the mapping file pager_table.sample instead of the default mapping file.

% pmdf test -mapping -noimage_file -mapping_file=/imta/table/pager_table.sample Enter table name: PAGER Input string: H|From: "Dancer" <dan@bridge.com> (Doof City) Output string: H|F:dan Output flags: [0,1,2,89] Input string: ^D %

imta test -match

You can use imta test -match to test a mapping pattern, particularly, to test wildcard and glob matching.

When invoked, imta test -match prompts for a pattern and then for a target string to compare against the pattern, and will output whether or not the target string matched and if it did match, which characters in the target string matched which wildcard or glob of the pattern. imta test -match will loop, prompting for input, until you exit using a CTRL/D.

Example

In the following example, the sample mapping pattern $[ax1]*@*.bridge.com is tested for several sample target strings.

% imta test -match Pattern: $[ax1]*@*.bridge.com Target: xx11a@sys1.bridge.com Match. 0 - xx11a 1 - sys1 Pattern: $[ax1]*@*.bridge.com Target: 12a@node.bridge.com No match. Pattern: $[ax1]*@*.bridge.com Target: 1xa@node.bridge.com Match. 0 - 1xa 1 - node Pattern: ^D %

imta test -rewrite

Use imta test -rewrite to provide a test facility for examining the IMTA's address rewriting and channel mapping process without actually sending a message. Various qualifiers can be used to control whether imta test -rewrite uses the configuration text files or the compiled configuration (if present), the amount of output produced, and so on.

If a test address is specified on the command line, imta test -rewrite applies the IMTA address rewriting to that address, reports the results, and exits. If no test address is specified, imta test -rewrite enters a loop, prompting for an address, rewriting it, and prompting again for another address. imta test -rewrite exits when you press CTRL-D.

When testing an email address corresponding to a restricted distribution list, imta test -rewrite uses as the posting address the return address of the local postmaster, which is usually postmaster@localhost unless specified by the IMTA option RETURN_ADDRESS in the IMTA Option file.

imta view

Use imta view to display a specified version of an IMTA log file. IMTA log files contain a uniqueid, which is appended to the file name to allow creation of multiple versions of the log file. imta view understands these unique ids and can display the contents of the particular file corresponding to the requested version of the file.

By default, if no offset qualifier ( n ) is specified, imta view displays the most recent version of the file.

TABLE  1-9   imta view Command Qualifiers

Command Qualifier	Description
-f=offset-from-first	Use this qualifier to specify displaying the nth version of the file (starting counting from 0). For instance, to display the earliest (oldest) version of the file, specify -f=0.
-l=offset-from-last	Use this qualifier to specify displaying the nth from the last version of the file (starting decrementing from 0 as the most recent version). For instance, to display the most recent (newest) version of the file, specify -l=0.

imta version

imta version prints out the IMTA version number, and displays the system's name, operating system release number and version, and hardware type.

Installation

This section describes the utilities associated with the installation process. For more information on installation, refer to the Sun Internet Mail Server 4.0 Advanced Installation Guide.

setup-tty

setup-tty is a script that installs SIMS and related files and packages onto the system.

---

Note - Because setup-tty is not installed on the target system, you must retrieve the setup-tty program from the distribution image and not from the system. On the CD, the setup-tty script can be found in /cdrom/sun_internet_mail_4_0/products/sims/setup-tty.

---

The setup-tty interface is considered to be "unstable." See attributes(5) for a description of interface stability.

Syntax

setup-tty [-c install | remove] [-d]

The options for setup-tty appear in TABLE 1-10

TABLE  1-10   setup-tty options

Option	Description
-c install	Specifies a standard install of SIMS and related files and packages.
-c remove	Specifies an uninstall of SIMS and related packages and files from the system.
-c removeall	Specifies a dramatic removeall of SIMS and related files and packages. This option removes data and configuration files left over from the standard removeall. This is a clean removeall, removing all files installed by the SIMS installation process and created by SIMS during operation, with the exception of packages that were present before the removeall procedure.
-d	Specifies a non-interactive automated install using the /tmp/sims_setup.dat file, if it exists. If /tmp/sims_setup.dat does not exist, setup-tty will default to the standard interactive install and prompt the user for necessary information. See TABLE 1-11 for a description of the parameters included in the sims_setup.dat file.

.

Examples

The following command performs a standard interactive installation, with -c install as the default parameter:

% setup-tty [-c install]

Execute the following to uninstall SIMS and related packages and files from the system:

% setup-tty -c remove

The following command:

% setup-tty -d

performs a non-interactive install, which uses the file /tmp/sims_setup.dat if it exists. It will gather all necessary configuration data from the /tmp/sims_setup.dat file. If the file does not exist, setup-tty reverts to the interactive install, which prompts the user for necessary information. If /tmp/sims_setup.dat exists and setup-tty is executed without the -d option specified, the /tmp/sims_setup.dat file is removed and the interactive install continues

sims_setup.dat File

TABLE 1-11 describes the parameters included in the sims_setup.dat file. The sims_setup.dat file can be provided by the user when the -d option is specified in the setup-tty command.

TABLE  1-11   sims_setup.dat File  

Parameter	Description
administrator-name	The user name for the directory administrator.
administrator-passwd	The password for the directory administrator.
cgi-bin	The location of the CGI bin directory for the HotJava Views server.
dcRoot	Root node for the directory tree (default is internet).
do_upgrade	Specifies whether or not to upgrade to SIMS 3.5 (1=upgrade, 0=do not upgrade).
document-root	The location of the document root for the Sun Web Server.
fax-number	The fax number. This is a text entry.
filename	Name of the file that contains the SIMS license.
ha_install	Determines whether or not to install the High Availability option. (0=do not install, 1=install).
ha_master	The logical hostname of the HA master host.
ha_masterlhost	The logical host name for the HA installation.
ha_sharedfs	The shared disk location for the HA installation.
hostname	Fully qualified name of the local host.
install-mode	Specifies which SIMS product package to upgrade (3=optional features install, 4=core install).
install-sws	Determines whether or not to install the Sun web server (0=do not install, 1=install).
ldap-port	The LDAP port number.
ldap-server	Hostname of the LDAP master server.
ldap-type	ldap server selected by user: sun for SunDS and netscape for Netscape DS
ldap_up	1 if the ldap (directory) is local; or if it is remote and the remote machine has the directory server running. 0 if the remote ldap server is not running.
locality	The name of the locality. This is a text entry.
maildomain	The mail domain.
mta-role	Determines if the IMTA is installed behind the firewall (0=not behind firewall, 1=behind firewall).
org-name-long	The name of the organization. This is a text entry.
phone-number	The phone number. This is a text entry.
postal-address	The postal address. This is a text entry.
postmaster	The postmaster's ID.
postmaster_uid	The postmaster's UID.
province	The name of the province. This is a text entry.
readfromfile	Determines whether or not the directory server license will be read from a local file (0=no, 1=yes).
remote-ldap	Determines where the LDAP server is located (0=local host, 1=not local).
remadmin	Determines whether or not to install the remote administrator option (0=do not install, 1=install).
rootdomain	The root domain.
standalone	Determines whether or not SIMS is already installed (0=SIMS already installed, 1=SIMS not installed).
sdk	Determines whether or not to install the SIMS SDK (0=do not install, 1=install).
sdk-doc	Determines whether or not to install the documentation for the SIMS SDK (0=do not install, 1=install).
select-options	Specifies whether or not any options have been selected to install (0=no options selected, 1=HA option only, 2=at least one option selected).
sims-doc	1 if the SIMS doc must be installed. 0 in all other cases.
siteadmin-name	The user name for the SIMS administrator.
siteadmin-passwd	The password for the SIMS administrator.
spmServer	The fully qualified host name of the machine where SPM is installed (default: local host).
smarthost	Has a text string value only if mta-role=1 (behind the firewall).
varmail	Determines whether or not the /var/mail message store is supported (0=not supported, 1=supported).
upgrade-possible	0=not upgradable.
webaccess	Determines whether or not to install the WebAccess option (0=do not install, 1=install).
ws_port	The Web server's port (default is 80).

uninstall

The uninstall utility removes SIMS and other related files and packages from your system. You can specify uninstall to perform a standard or dramatic procedure.

---

Note - uninstall might not remove packages that have been installed by a separate application and might be used by that application. This is the case even if SIMS has installed that package upon setup.

---

sendmail is restored by the SIMS uninstall utility but it is not started. To start sendmail, the user must either reboot the system or manually start the sendmail program.

Web server packages can be removed by uninstall, but httpd is not stopped.

Syntax

uninstall [-c sims] [-d sims]

The options for this command appear in TABLE 1-12.

TABLE  1-12   uninstall options

-c sims

Specifies a standard uninstall of SIMS and related files and packages. The standard uninstall does not remove the directories and files of configuration and data, for example, the message store. Only the binaries are removed.

-d sims

Specifies a dramatic uninstall of SIMS and related files and packages. This option removes data and configuration files left over from the standard uninstall. The dramatic uninstall option is a clean uninstall, removing all files installed by the SIMS installation process and created by SIMS during operation, with the exception of packages that may have already been present before the uninstall procedure.

---

Note - Option -d is recommended before re-installing SIMS.

---

Examples

The following command performs a standard uninstall:

% uninstall -c sims

The following command performs a dramatic uninstall:

% uninstall -d sims