Overview of Messaging Server Unified Configuration

Skip to end of metadata
Go to start of metadata

Overview of Oracle Communications Messaging Server Unified Configuration

This information introduces Messaging Server Unified Configuration, describes its capabilities, and provides initial guidelines on how to transition from a legacy configuration. Unified Configuration provides the ability to configure Messaging Server in a way that is much less error-prone and much easier to script and reuse across multiple hosts.

Unified Configuration was introduced in Messaging Server 7 Update 5.

Topics:

What Is Messaging Server Unified Configuration?

Unified Configuration is an improved process to configure and administer Messaging Server. Unlike in legacy configurations, Unified Configuration uses validation to verify configuration accuracy, and employs a single tool to configure the entire Messaging Server configuration (with a few exceptions).

The following table describes how Unified Configuration improves upon issues with legacy configuration.

Legacy Versus Unified Configuration

Legacy Configuration Issue Unified Configuration Improvement
Dealing with many configuration files (with inconsistent formats) and hand-editing them can lead to errors and invalid configurations. Unified Configuration "unifies" configuration management. One tool, msconfig, administers Messaging Server configuration. Validation checking prevents introducing some configuration errors.
Configuration settings themselves are often complicated and not straight-forward. Unified Configuration reduces redundancy and host specific-configurations, so that, for example, you can use the same settings for many options among the MMP, MTA, and message store configurations.
When problems arise, there are support challenges due to the many Messaging Server configuration files. Additionally, because passwords are contained in the configuration files, it makes it difficult for customers to just send these files to Oracle Support without first removing the passwords. Unified Configuration uses only three text files to store configuration data, with most data stored in the config.xml file. Passwords are stored in a separate file, removing the need for customers to edit configuration files before sending to Oracle Support. In addition, Unified Configuration provides an audit trail of configuration changes. The changes (currently the last 100 changes) are actually stored in a repository, referred to as a graveyard. Storing of changes further enables you to restore an entire configuration, and to roll-back and roll-forward between configurations.

See Unified Configuration Files for more information.
It is difficult to separate instance-specific details from details shared by functionally similar machines. Unified Configuration separates tasks for single instances (referred to as instance) of Messaging Server from global tasks for a group (referred to as role) of Messaging Server machines. The intention is that the role contain configuration information suitable for sharing with other hosts that have the same function in the deployment. At present, there is no mechanism to automatically share role configuration.

See Separating Roles and Instances for more information.
Customers must create their own procedures and scripts with their own tools to manage a deployment. New customers can write automation scripts by using the Unified Configuration recipe language. In Messaging Server 7 Update 4 and prior releases, you had to manually automate configuration changes, which overwrote configuration files, potentially removed necessary files, and could introduce syntax errors. Also, necessary machine-specific variations in the configuration files made this sort of automation fairly complex. The recipe language introduces the ability to robustly change a configuration in a reproducible fashion in a way that can be sensitive to what was previously in the configuration. When you use recipes, you are able to make use of the Unified Configuration history and administrative undo features. In addition, Oracle can use the recipe language to automate configuration changes that are otherwise complex, interconnected, and require lots of documentation. The SpamAssassin.rcp, HAConfig.rcp, and LMTPSingleSystem.rcp recipes, available in the msg-svr-base/lib/recipes directory, are good examples.

See Using Recipes for more information.

Unified Configuration Files

The following table describes the Unified Configuration file names, file management tool, file format, character set, XML schema, ownership, and file permissions. The Unified Configuration files are located in the configroot directory, by default, /var/opt/sun/comms/messaging64/config.

Unified Configuration File Properties

Configuration File Description File Management Tool File Format Character Set File Ownership Recommended File Permissions Notes
restricted.cnf Contains protected Messaging Server UID and GID information. Text editor option=value ASCII root 0644 When you perform the initial Messaging Server configuration, this file sets the UID under which to run Messaging Server. After initial configuration, there should rarely be a need to edit this file.

Note: A legacy configuration can also use the restricted.cnf file for enhanced security.
xpass.xml Contains obfuscated passwords (BASE64 encoded). This is the only file within Unified Configuration where password information is stored. msconfig utility XML 1.0 UTF-8 mailsrv 0600 Not Applicable
config.xml Contains most of the non-password configuration information. In addition, when necessary, you could send this entire file to Oracle Support to help with resolving problems. msconfig utility XML 1.0 UTF-8 mailsrv 0640 Not Applicable
configlib.xml Contains static, default mapping tables that are mostly concerned with character sets and language issues, including:
  • DISPOSITION_LANGUAGE
  • DOMAIN_DC
  • LANGUAGE_LOCALES
  • LDAP_USERS_LANGUAGE
  • LDAP_USERS2_LANGUAGE
  • NOTIFICATION_LANGUAGE
Managed by Oracle (that is, the file is not to be edited) XML 1.0 UTF-8 mailsrv 0644 Never edit this file. Doing so causes an unsupported configuration.
Note: About MTA Tailor Options
In legacy configuration, you use the MTA tailor file of option settings (imta_tailor) to set various MTA installation and operational parameters. In Unified Configuration, the MTA tailor file is obsolete and no longer used. Unified Configuration replaces the MTA tailor options that specified locations of MTA directories or files with rationalized, consistent locations, which are based off the installation main location and located by using the SERVERROOT environment variable. Legacy configuration MTA tailor options that set other sorts of MTA operational parameters have typically been replaced with Unified Configuration options of the form mta.option-name.

Enabling Unified Configuration in Messaging Server

There are two ways to enable Unified Configuration:

  1. When migrating to Unified Configuration: Use the msg-svr-base/bin/configtoxml program to migrate a legacy configuration to Unified Configuration. When you run configtoxml, your old configuration is converted to Unified Configuration.
    • The legacy configuration is saved in the configroot/legacy-config directory.
    • If necessary, you can use the configtoxml -undo command to restore a saved legacy configuration.
  2. When installing a fresh instance of Messaging Server 7 Update 5 or greater: For a new Messaging Server instance, run the configure --xml command to enable Unified Configuration by default.
    • The presence of a config.xml file in the config directory indicates that Unified Configuration is enabled.
    • To generate a legacy configuration instead of a Unified Configuration, you can use the configure -noxml command.
    • When you perform a fresh installation of Messaging Server 7 Update 5 or greater, and choose to configure a Unified Configuration, you cannot revert that Unified Configuration to a legacy configuration. If, however, you upgrade Messaging Server to Messaging Server 7 Update 5 or greater, and convert to a Unified Configuration (by running the configtoxml command), you can revert back to the legacy configuration.
    • A Unified Configuration is more simple than a legacy configuration. In addition, where appropriate, modern default values are established and seldom used features are removed (for example, the tcp_tas channel is not present in Unified Configuration).
    • The Messaging Server 7 Update 4 and prior releases configuration files, such as dispatcher.cnf, option.dat, and so on, are ignored when Unified Configuration is enabled.

To Determine if Unified Configuration Is Deployed

The following example shows how to determine if Unified Configuration is deployed on your system:

In this example, the presence of the config.xml file indicates that Unified Configuration has been enabled on this host.

If you are using a compiled configuration and see in that the status is not compiled, you should recompile the configuration. For example:

For more information, see Compiling the MTA Configuration.

Understanding Unified Configuration Limitations

In general, Unified Configuration has consolidated all the various Messaging Server files. Nevertheless, the current Unified Configuration implementation has a few limitations:

  • The channel sieves and channel header trimming option files have not yet been converted to XML.
  • Some files, such as localized templates for DSNs and NDNs, might remain in their current format and not be converted to XML.
  • The content of the conversions file is a mono-block in XML.

Using the Repository of Previous Configurations

The repository of previous configurations, known as the graveyard, is stored in the configroot/old-configs/ directory. The move from current configuration to the graveyard is performed when a new configuration is written to disk. The graveyard maintains the most recent 100 configurations. With the graveyard, you can restore an old configuration by reverting to a previous configuration. Furthermore, you can compare differences between any two configurations, for example, between the active configuration and a previous configuration, or two old configurations.

To List Configurations

  • Use the msconfig history command to show a list of configurations currently in the graveyard.

To Compare Configurations

  • To compare configurations, use the msconfig differences m _n command, where m and n are the numbers of the previous configurations from the history command that you want to compare.

Using Legacy Configuration Tools with Unified Configuration

Once Unified Configuration in enabled, legacy configuration tools might work differently than in previous releases. Specifically:

  • Scripts that directly alter legacy configuration files do not work in a Unified Configuration.
  • The configutil command can still set, get, and delete a legacy configuration. Additionally, in Unified Configuration, configutil options can also automatically perform:
    • Option name translations
    • Option value translations
    • Option value validations
Note
Use of the configutil command is deprecated in Unified Configuration mode. Some configuration changes that were previously possible with the configutil command are only possible by using the msconfig command, for example, some changes to notification configuration.
  • The mkbackupdir command, which creates and synchronizes the backup directory with the information in the message store, works with Unified Configuration.
  • The imsimta program command, which manipulates the program delivery options, does not work with Unified Configuration. Instead, you must use the msconfig command.
    • This command issues an error and exits with 1 when Unified Configuration is being used.
  • All other utilities only consume options and continue to work with both Unified Configuration and legacy configurations.

About Compiled MTA Configurations

The following changes for compiled MTA configurations are introduced in Messaging Server 7 Update 5:

  • The configure command no longer generates a compiled configuration by default, for both legacy and Unified Configuration.
  • Unified Configuration provides the -xmlfile= switch to use test tools on a non-live configuration. (This was previously only possible with a compiled configuration.)
  • The imsimta version command now shows if a compiled configuration is used or not.

Separating Roles and Instances

Unified Configuration separates tasks for single instances (referred to as instance) of Messaging Server from global tasks for a group (referred to as role) of Messaging Server machines. The intention is that the role contain configuration information suitable for sharing with other hosts that have the same role in the deployment.

Note
At present, there is no mechanism to automatically share role configuration.

Any configuration option can be an instance setting, a role setting, or both. When the same option is in both the role and instance, the instance value takes precedence. Both the configure and msconfig commands put a given setting in either the instance or the role based on the likely scope for the option. Normally, you use the default location (instance or role) determined by the msconfig command and not explicitly specify one or the other.

The Messaging Server 7 Update 5 initial configuration generates an instance and role, as does migrating from a legacy configuration to Unified Configuration.

More About Unified Configuration Options

This section provides information about password, restricted, and obsolete options.

Options That Have Passwords

The password options have the following characteristics:

  • Options can be marked as being a password.
  • By default, password values are not displayed.
  • The passwords are stored in obfuscated form in the xpass.xml file. Because Messaging Server 7 Update 5 stores passwords in a separate file, you do not need to edit configuration files as with previous Messaging Server releases before sharing with Oracle Support.

Restricted Options

Some configuration options are marked "restricted" by Oracle. Additionally, starting with Messaging Server 7 Update 5, the XML schema exposes the entire configuration, so there are no longer any hidden configuration options.

Options may be restricted for several reasons, including:

  • The option has complex and subtle consequences and would cause harm in all but a very few rare circumstances.
  • The option might be a legacy option that should not be used in new systems.
  • The option might be a placeholder for a feature that has not yet been implemented.

Restricted options have the following characteristics:

  • The msconfig command displays a warning when you attempt to set a restricted option. In addition, the msconfig command requires an extra step to actually set the restricted option.
  • The restriction is noted within the configuration file itself, which helps you to be aware of any special circumstances. For example:
    <delimiter_char v="127" xannotation="RESTRICTED USAGE OPTION: user remark" xauthor="dcn@example.com" xmtime="2010-05-12T17:42:19-08:00"/>
    

The user remark text is any optional remark added by the administrator when the configuration was updated. The "RESTRICTED USAGE OPTION" is text inserted by Oracle into the remark field when the option is restricted.

Caution
If you set a restricted option without being advised to do so by Oracle Support, your configuration is considered unsupported by Oracle.

Obsolete Options

When an option has been marked by Oracle as being obsolete, the configuration no longer uses it. However, you cannot remove it from the XML Schema as that would make existing configurations invalid.

When marked as obsolete, the option:

  • Remains in the XML Schema
  • Can no longer be set or changed
  • Can only be deleted from a configuration

Option Relationships

Unified Configuration enables some relationships between options to be expressed so that when a particular option is set, other unnecessary options can be automatically removed. For example, if you set the mx keyword on a channel (for MX mail forwarding records), any of the nomx, randommx, and other related "mx" keywords are removed. In addition, Unified Configuration uses the concept of default relationships to help with configuration. For example, option X and option Y might have a default relationship such that when X is not set, the value is taken from Y; or when Y is not set, then Y's default value is value. Furthermore, Unified Configuration has the capability to know in which release an option became available and warn when a certain configuration is not release-suitable. In general, option relationships help to reduce configuration mistakes.

Unified Configuration Option Names

Unified Configuration uses a "unified" option naming convention that is reminiscent of Messaging Server 7 Update 4 and prior releases configutil option names.

In general, this option naming convention uses the following structure:

[role.]group[.sub-group|.sub-group].option
[instance.]group[.sub-group|.sub-group].option

The following example shows a group.sub-group.option convention:

imap.logfile.flushinterval

In this example, imap is the group, logfile is the sub-group, and flushinterval is the option.

This example shows a group.option convention:

mta.mm_debug

In this example, mta is the group and mm_debug is the option.

Characteristics about option names to keep in mind:

  • Many groups only appear once (for example, imap and pop).
  • Some groups may appear many times.
    For example:
    channel
    mapping
    sectoken
    alias
    task 
    
  • The group or sub-group can include a :name portion used for "named" groups.
    For example:
    channel:tcp_local.slave_debug
    partition:primary.path
    

Characteristics about instances and roles to keep in mind:

  • An option in the "instance" overrides the same option in the "role." For example, IMAP is effectively disabled by this configuration:
    instance.imap.enable = 0
    role.imap.enable = 1
    
  • There actually is no option called imap.enable. It is either role.imap.enable or instance.imap.enable.
  • When setting options, you typically do not specify either "role" or "instance." The msconfig command applies heuristics to determine whether "role" or "instance" applies.
    Here is a sample, basic config.xml file that shows how the configuration uses instance and role:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <xconfig ...>
    <role name="store">
    <base>
    <defaultdomain v="siroe.com"/>        role.base.defaultdomain
    </base>
    <imap>
    <enable v="1"/>           role.imap.enable
    <numprocesses v="2"/>          role.imap.numprocesses
    </imap>
    <mapping name="ABC">
    <rule pattern="x*y" template="$N"/>        role.mapping:ABC.rule
    <rule pattern="*" template="$Y"/>         role.mapping:ABC.rule
    </mapping>
    </role>
    <instance name="ims" roleref="store">
    <base>
    <hostname v="wassonite.siroe.com"/>         instance.base.hostname
    </base>
    <mta>
    <mm_debug v="5"/>            instance.mta.mm_debug
    </mta>
    </instance>
    </xconfig>

In the preceding example, some option names that you would see upon listing them with the msconfig show command are displayed in bold. Also, you can see that the default domain (defaultdomain), number of IMAP processes (numprocesses), and mappings (mapping name) have been defined for the store role; and that the host name (hostname) and MTA logging debug level (mm_debug) have been set for the store instance.

Tip
Use the configutil -H command to translate the legacy configutil option names to Unified Configuration names. For example:

Example of Legacy Configuration and Unified Configuration

Unified Configuration greatly simplifies the configuration process, as shown in this example of configuring the SMTP server for debugging.

In a legacy configuration, you need to perform the following steps:

  1. Edit the imta.cnf file and modify the tcp_local channel entry:
    tcp_local identnonenumeric inner loopcheck maysaslserver maytlsserver mx \
    pool SMTP_POOL remotehost saslswitchchannel tcp_auth smtp sourcespamfilter1 \
    switchchannel master_debug
    tcp_local-daemon
    
  2. Edit the option.dat file and add the following option:
    mm_debug=3
    
  3. Edit (or create if it does not exist) the tcp_local_option file and add the following option:
    trace_level=2
    
  4. Check permissions on all files, especially the tcp_local_option file.

In Unified Configuration, the equivalent steps to the preceding task are the following:

Using Recipes

You use recipe files, which are expressed by using a programming language, to automate configuration tasks, typically by scripting them. Messaging Server 7 Update 5 recipes are located in the msg-svr-base/lib/recipes directory. The primary inspiration for the recipe language is the Icon programming language designed by Ralph Griswald. As such, it supports C-like expressions, operators, and assignments, Sieve-like conditionals, and loops. The available data types are integers, strings, and lists.

Recipes typically operate in three phases. First, a number of checks are done to make sure the right conditions exist for the recipe to be effective. Next the recipe asks a number of questions to determine exactly what changes should be made. Finally, the recipe implements the requested changes. Note that while this is the typical ordering, recipes are not constrained to use it and may use other approaches if appropriate.

By using the recipe language, you can more easily script complex configuration changes. For more information on writing recipes, see the help text for the recipe language by typing msconfig -help and choosing help for the Recipe_language topic, or refer to Recipe Language.

To Run a Recipe

To run a recipe, type the following command:

Helpful Commands

This section provides some helpful commands to get started with Unified Configuration.

To Show Settings

  • Use the msconfig show command to display current settings.
    For example, to show all currently enabled options:

To Get Help

  • Use the msconfig help command.
Labels:
messagingserver messagingserver Delete
unifiedconfig unifiedconfig Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jul 08, 2013

    Spelling error:

    imap.logfile.flushinterval

    In this example, map is the group, logfile is the sub-group, and flushinterval is the option.

    "map" should be "imap"

    1. Jul 09, 2013

      Thanks for catching this, I have fixed the doc.

      Joe

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.