Messaging Server Unified Configuration Command-line Utilities

Skip to end of metadata
Go to start of metadata
Starting with Oracle Communications Unified Communications Suite 7.0.6, and Delegated Administrator and Calendar Server 7.0.5, the documentation for Connector for Microsoft Outlook 8.0.2, Contacts Server 8.0, Instant Messaging Server 9.0.2, Delegated Administrator, and Calendar Server 7.0.5 is available on the Oracle Documentation site at

Oracle Communications Messaging Server Unified Configuration Command-line Utilities

This information describes the 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 msg-svr-base/bin directory.

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

Unified Configuration was introduced in Messaging Server 7 Update 5.


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. In Messaging Server 7 Update 5, the configure command defaults to producing a legacy configuration (non-Unified Configuration). To produce a Unified Configuration, use the configure --xml command.


configure [<options>]


The following table shows the options for the configure command:

Options for configure Command

Option Description
--debug Provides additional debugging (primarily for LDAP operations)
--help,-? Shows this help
--ignoreSendmail Does not disable sendmail after configuration
--ldapport=port Specifies an LDAP port, if you want to use other than port 389
--ldif Does not modify LDAP directory, just writes LDIF
--noldap Runs without LDAP present (statefile only)
--novalidate Skips most validation of user inputs
--noxml 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)
--saveState= filename Specifies file where state information is saved
--ssl Requires SSL when configuring LDAP
--state=filename Uses silent state file to configure product
--version,-V Shows product version
--xml Generates Unified Configuration (XML)


  • To configure an initial Unified Configuration after installing Messaging Server 7 Update 5:
  • To configure an initial legacy configuration after installing Messaging 7 Update 5:
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 state file.

configtoxml Command

The configtoxml command converts a legacy configuration to a Unified Configuration. Run this command after first upgrading from a prior Messaging Server release to Messaging Server 7 Update 5.


configtoxml [<options>]


The following table shows the options for the configtoxml command:

Options for configtoxml Command

Option Description
-32,-64 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.
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.
-i INSTANCE 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.
-o CONFIG-FILE PASSWORD-FILE RESTRICTED-FILE | --output CONFIG-FILE PASSWORD-FILE RESTRICTED-FILE 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) 7u5-28.12 64bit (built 15:58:11, May 23 2012)
Using /opt/sun/comms/messaging/config/imta.cnf (not compiled)
Linux 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) 7u5-28.12 64bit (built 15:58:11, Nov 5 2012)
Using /opt/sun/comms/messaging/config/config.xml (not compiled)
Linux 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 the msconfig Commands table 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:



The following table lists the commands for msconfig:

msconfig Commands

Command Description
DEFAULT Uses option's default location
DIRECTORY [filter] Shows available recipes, optional filter matches string
DIFFERENCES [m [n]] Compares configurations
EDIT object Edits by using external editor
EXECUTE command Executes single recipe command
EXIT Exits msconfig utility with option to write
HELP [topic [subtopic ...]] Shows this help
HISTORY Lists previous saved configurations
INSTANCE Stores options in instance
IMPORT config [pass] Reads configuration from alternate file(s)
LOG Acts as a synonym for history
QUIT Exits msconfig utility immediately
REVERT [n] Discards any changes and reloads configuration
ROLE 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.

The following table 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.

object Types Used with the EDIT Sub-command

object Type Description
ALIASES [alias-name] MTA aliases
CHANNELS [channel-name] MTA channels
CONVERSIONS MTA conversion channel control entries
FILTER Sieve filter
MAPPINGS [mapping-name] MTA mappings
OPTION option-name Specifies an option
REWRITES MTA rewrite rule

Notes on the msconfig Command

  • The msconfig command checks syntax and prevents potential misconfigurations due to, for example, entering channel keywords 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:

    # ./msconfig
    msconfig> 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: 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.

The following table some of the structural name changes for configutil options.

Structural Name Changes for configutil options in Unified Configuration

Legacy Option Unified Configuration Option
logfile.*.* *.logfile.*
sasl.default.ldap.* auth.*
sasl.default.* auth.*
metermaid.table.*.* metermaid.local_table:*.*
metermaid.mtaclient.* metermaid_client.*
metermaid.config.* metermaid.*
alarm.*.* alarm.system:*.*
store.quotaexceededmsg;lang-* message_language:*.quotaexceededmsg
gen.newuserforms;lang-* message_language:*.welcomemsg
schedule.* schedule.task:*.crontab
encryption.rsa.nssslpersonalityssl base.sslnicknames
probe.*.* msprobe.probe:*.*
service.http.proxy.adminpass.* proxy:*.httpadminpass (host-specific proxy password)
local.service.proxy.adminpass.* proxy:*.imapadminpass (host-specific proxy password)*.* notifytarget:*.*
service.imap.capability.* imap.capability_*

Using the msconfig Command in Edit Mode

You can use the msconfig edit object 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 keyword 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 keyword to it, and save the file. This process is much simplified when you use the msconfig command. The equivalent operation is the following command:

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:

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

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:

messagingserver messagingserver Delete
unifiedconfig unifiedconfig Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.

The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.