41 Messaging Server Command-Line Reference

This information describes the Oracle Communications Messaging Server configure, configtoxml, and msconfig commands that you use to manage a Unified Configuration. You need to be logged in either as root or mailsrv to run these commands. These commands are located by default in the MessagingServer_home/bin directory.

See "Overview of Messaging Server Unified Configuration" for a description of Unified Configuration.


configure Command

The configure command creates an initial runtime configuration for Messaging Server. It gives you a base working configuration from which you can make your specific customizations. The command is only meant to be run once. Subsequent running of this command overwrites the existing configuration. To modify your initial runtime configuration, use the "msconfig Command."


configure [<options>]


Table 41-1 shows the options for the configure command:

Table 41-1 Options for configure Command

Option Description


Provides additional debugging (primarily for LDAP operations)


Shows this help


Does not disable sendmail after configuration


Specifies an LDAP port, if you want to use other than port 389


Does not modify LDAP directory, just writes LDIF


Runs without LDAP present (statefile only)


Skips most validation of user inputs


Generates legacy configuration (does not use XML-based Unified Configuration); can also be used to replace a Unified Configuration with a freshly generated legacy configuration (fresh installation of Messaging Server, not an upgrade where the configtoxml command was run)


Specifies file where state information is saved


Requires SSL when configuring LDAP


Uses silent state file to configure product


Shows product version


Generates Unified Configuration (XML)


  • To configure an initial Unified Configuration:

  • To configure an initial legacy configuration:

configure --noxml


A statefile can use the XMLCONFIG=0 or XMLCONFIG=1 option to specify a legacy or Unified Configuration, respectively. The --xml and --noxml command options override what is specified in the statefile.

configtoxml Command

The configtoxml command converts a legacy configuration to a Unified Configuration.


configtoxml [<options>]


Table 41-2 shows the options for the configtoxml command:

Table 41-2 Options for configtoxml Command

Option Description


Installation is 32-bit (-32) or 64-bit (-64) Messaging Server. Default is 64-bit when the installation type cannot be inferred from the SERVERROOT or ConfigRoot environment variables or from the location of this script.

-f |--force

Ignores safety checks, enables running as non-root and permits overwriting of any pre-existing Unified Configuration files.

Caution: Using this option may result in a non-functioning configuration. The restricted.cnf file must always be owned by root.

-h |--help

Shows this help.


Inserts instance name in the generated configuration files. The default is ims.

-l DIR | --location DIR

Reads the legacy configuration files from the specified directory. The default to use is determined by the following:

  1. The ConfigRoot environment variable, if defined

  2. The SERVERROOT/config/ path, if the SERVERROOT environment variable is defined

  3. Location of ConfigRoot, determined from the location of this script

  4. The OS-specific default path

-n | --noactive

Does not generate an active configuration and does not move the legacy configuration files to the ConfigRoot/legacy-config/ directory. The generated Unified Configuration files have the names config.xml, xpass.xml, and restricted.cnf, and are written to ConfigRoot. This option cannot be used in conjunction with the --output or --undo options.



Directs the Unified Configuration file output to the designated files. By default, the files config.xml, xpass.xml, and resricted.cnf are written to the ConfigRoot or SERVERROOT/config/ directory. This option cannot be used in conjunction with the --noactive or --undo options.

-r ROLE | --role ROLE

Inserts the role name in the generated configuration files. The default is ims.

-y |--yes

Pre-answer any confirmation questions with a "yes" response so that this script can be run without user intervention.

-u |--undo

Removes any active Unified Configuration files and restores any legacy configuration files.

Key environment variables for this command are:

  • SERVERROOT (The default is /opt/sun/comms/messaging64/.)

  • ConfigRoot (The default is /opt/sun/comms/messaging64/config/.)


The following example shows the configtoxml converting a legacy configuration to a Unified Configuration.

# bin/imsimta version
Oracle Communications Messaging Server 7u5-28.12 64bit (built Nov 5 2012)
libimta.so 7u5-28.12 64bit (built 15:58:11, May 23 2012)
Using /opt/sun/comms/messaging/config/imta.cnf (not compiled)
Linux host1.example.com 2.6.39-100.5.1.el5uek #1 SMP Tue Mar 6 20:25:25 EST 2012 x86_64 x86_64 x86_64 GNU/Linux

# bin/configtoxml
WARNING: This procedure will produce an active Unified Configuration which
        will override any existing legacy configuration.

Continue anyway [no]? yes
Creating the directory /opt/sun/comms/messaging/config/legacy-config/
Moving the processed legacy configuration files to /opt/sun/comms/messaging/config/legacy-config/
# bin/imsimta version
Oracle Communications Messaging Server 7u5-28.12 64bit (built May Nov 5 2012)
libimta.so 7u5-28.12 64bit (built 15:58:11, Nov 5 2012)
Using /opt/sun/comms/messaging/config/config.xml (not compiled)
Linux host1.example.com 2.6.39-100.5.1.el5uek #1 SMP Tue Mar 6 20:25:25 EST 2012 x86_64 x86_64 x86_64 GNU/Linux

Notes on the configtoxml Command

  • Stop Messaging Server before running the configtoxml command. Alternatively, use the --noactive switch to prevent writing out an active configuration.

  • When generating an active Unified Configuration, the configtoxml command moves all the processed legacy configuration files to the $ConfigRoot/legacy-config directory. The --undo option removes the Unified Configuration and restores the legacy configuration files.

  • The --undo option leaves the Unified Configuration restricted.cnf password file in place.

msconfig Command

The msconfig command administers the Unified Configuration.


You can invoke the msconfig command in "interactive" or "non-interactive" mode.


Only edit your Unified Configuration by running the msconfig command. This saves old configurations and allows for rollback. Do not hand-edit any of the Unified Configuration files. Oracle Support may occasionally edit these files to work around any issues pertaining to msconfig
  • To invoke in non-interactive mode:

    msconfig <command> <option> <value>

See Table 41-3, "msconfig Commands" for a list of commands.

The option syntax is scope.optionname, where scope can be multiple . or : delimited name components and optionname is a single name component (with no .). In this context, scope is the set of groups (and group names) used in the naming convention as described in "Unified Configuration Option Names ." The option name determines the semantics of the option, and the scope determines the part of the product to which those semantics apply. Thus, an option with "role.base" scope applies to the entire product unless the same option is used with a more specific scope.

For example, consider the sslnicknames option. A setting for base.sslnicknames applies to the entire product, but a different one can be specified for different parts of the product. For example, imap.sslnicknames only applies to the IMAP server (while the rest of the servers would use base.sslnicknames).

The . delimiter appears before a name component of an option scope that is predetermined. The : delimiter appears before a name component of an option scope that is customer supplied and usually extensible.

The scope prefix is optional if unambiguous. There is also a higher-level scope of instance or role that you normally do not specify but that the msconfig command does display. For example:


Some scopes have associated names. For example, schedule.task:expire.crontab sets the crontab option in the task named expire in the schedule scope.

  • To invoke in interactive mode:


When run interactively, the default prompt for msconfig changes to the following:


After you have modified the configuration, the prompt changes to the following:


The DEFAULT, INSTANCE, and ROLE commands also affect the prompt. In default mode:


In Instance mode:


In Role mode:



Table 41-3 lists the commands for msconfig:

Table 41-3 msconfig Commands

Command Description


Uses option's default location

DIRECTORY [filter]

Shows available recipes, optional filter matches string


Compares configurations

EDIT object

Edits by using external editor

EXECUTE command

Executes single recipe command


Exits msconfig utility with option to write

HELP [topic [subtopic ...]]

Shows this help


Lists previous saved configurations


Stores options in instance

IMPORT config [pass]

Reads configuration from alternate file(s)


Acts as a synonym for history


Exits msconfig utility immediately


Discards any changes and reloads configuration


Stores options in role

RUN recipe

Runs specified recipe

SET option [value]

Sets option to the specified value

SHOW option [namefilter [valuefilter]]

Shows value of option, optional valuefilter matches string

UNSET option

Deletes option from the configuration

WRITE [-remark=remark-string]

Writes configuration changes, includes optional remark


The msconfig help command contains extensive documentation not only about running the msconfig command itself, but also on other Unified Configuration topics.

Table 41-4 describes the object types used with the EDIT sub-command. The EDIT sub-command places the specified object in a file in an appropriate textual form then invokes the editor specified by the EDITOR shell variable. After being edited, the file is read and any changes are incorporated into the configuration.

Table 41-4 object Types Used with the EDIT Sub-command

object Type Description

ALIASES [alias-name]

MTA aliases

CHANNELS [channel-name]

MTA channels


MTA conversion channel control entries


Sieve filter

MAPPINGS [mapping-name]

MTA mappings

OPTION option-name

Specifies an option


MTA rewrite rule

Notes on the msconfig Command

  • The msconfig command checks syntax and prevents potential misconfigurations due to, for example, entering channel options twice or using invalid (obsolete) channel options.

  • Do not run the msconfig and configutil commands together.

  • The msconfig command validates the correctness of each individual option value when it is set and the correctness of the entire configuration.

  • The msconfig prevents writing an invalid configuration to the active configuration.

  • Configuration validation is not performed by other Messaging Server processes.

  • Schema errors do not prevent Messaging Server from running, however, XML syntax errors do prevent operation.

  • If the value provided to the msconfig option contains special characters, each special character must be prefixed with the escape character "\" if you are using non-interactive mode. If you use msconfig in interactive mode to set the value that contains special characters, you do not need to prefix them with the escape character.

    Example: To set the value of the auth.searchfilter option to:


    you can run the following in non-interactive mode:

    msconfig set auth.searchfilter \"\(\|\(uid\=\%U\)\(mail\=\%o\)\)\"

    or you can run the following in interactive mode:

    msconfigmsconfig> set auth.searchfilter "(|(uid=%U)(mail=%o))"
    msconfig# write

Option Name Changes in Unified Configuration

  • For some configutil options, simply dropping the local. or service. prefix results in the Unified Configuration name but not always. Consult the msconfig help documentation for a list of option names.


    Use the configutil -o legacy-name -H command to see the Unified Configuration option name.
  • Two options were "restructured" rather than just renamed in Unified Configuration: local.store.notifyplugin and the MMP ServiceList.

  • Most MTA option.dat option names are unchanged in Unified Configuration.

  • Most job controller and dispatcher option names are unchanged in Unified Configuration, with a few exceptions that were misleading.

Table 41-5 lists some of the structural name changes for configutil options.

Table 41-5 Structural Name Changes for configutil Options in Unified Configuration

Legacy Option Unified Configuration Option


























proxy:*.httpadminpass (host-specific proxy password)


proxy:*.imapadminpass (host-specific proxy password)





Using the msconfig Command in Edit Mode

You can use the msconfig editobject command to edit the specified object in a file in an appropriate textual form. The msconfig edit command invokes the editor specified by the EDITOR shell variable. You can then make the change, save it, exit, and your configuration is updated.

For example, suppose you want to set the master_debug option on the tcp_local channel. In a legacy configuration, you need to edit the imta.cnf file, locate the tcp_local channel block, add the master_debug option to it, and save the file. This process is much simplified when you use the msconfig command. The equivalent operation is the following command:

msconfig set channel:tcp_local.master_debug

Even if you did not know the preceding command, you could still use the msconfig command to perform this operation by invoking it in edit mode:

msconfig edit channels

You can also edit a single channel block by itself by running the following command:

msconfig edit channel tcp_local

The msconfig command provides the same editing capability for rewrites (edit rewrites), mappings (edit mappings) and aliases (edit aliases).

Channel-specific option files are mapped into the Unified Configuration as sub-elements of a general "options" channel option. These options appear at the bottom of each channel block when you run edit channels. The following example illustrates this point:

tcp_local identnonenumeric inner loopcheck maysaslserver maytlsserver mx \
 pool SMTP_POOL remotehost saslswitchchannel tcp_auth smtp sourcespamfilter1 \