This chapter introduces Oracle Communications 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 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).
Table 2-1 describes how Unified Configuration improves upon issues with legacy configuration.
Table 2-1 Legacy Versus Unified Configuration
| Legacy Configuration | 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 Command," 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. 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 MessagingServer_home/lib/recipes directory, are good examples. See "Using Recipes" for more information. |
Table 2-2 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.
Table 2-2 Unified Configuration File Properties
| Configuration File | Description | File Management Tool | File Format | Char Set | File Ownership | Recommended File Permissions |
|---|---|---|---|---|---|---|
|
restricted.cnf |
Contains protected Messaging Server UID and GID information. |
Text editor |
option=value |
ASCII |
root |
0644 |
|
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 |
|
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 |
|
configlib.xml |
Contains static, default mapping tables that are mostly concerned with character sets and language issues, including:
|
Managed by Oracle (that is, the file is not to be edited) |
XML 1.0 |
UTF-8 |
mailsrv |
0644 |
Notes:
When you perform the initial Messaging Server configuration, the restricted.cnf file sets the UID under which to run Messaging Server. After initial configuration, there should rarely be a need to edit this file. A legacy configuration can also use the restricted.cnf file for enhanced security.
Never edit the configlib.xml file. Doing so causes an unsupported configuration.
Note:
About MTA Tailor OptionsIn 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.
There are two ways to enable Unified Configuration:
When migrating to Unified Configuration: Use the MessagingServer_home/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.
For a new Messaging Server instance: Run the configure 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 and choose to configure a Unified Configuration, you cannot revert that Unified Configuration to a legacy configuration. If, however, you upgrade Messaging Server 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).
Legacy configuration files such as dispatcher.cnf, option.dat, and so on, are ignored when Unified Configuration is enabled.
The following example shows how to determine if Unified Configuration is deployed on your system:
cd /opt/sun/comms/messaging64/bin imsimta version ... Using /opt/sun/comms/messaging64/config/config.xml SunOS host2.example.com 5.10 Generic_142901-03 i86pc i386 i86pc
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:
/opt/sun/comms/messaging64/bin/imsimta version ... Using /opt/sun/comms/messaging64/config/config.xml (not compiled) SunOS host1.example.com 5.10 Generic_147441-09 i86pc i386 i86pc /opt/sun/comms/messaging64/bin/imsimta cnbuild
For more information, see "Compiling the MTA Configuration."
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.
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.
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.
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.
Initial configuration generates an instance and role, as does migrating from a legacy configuration to Unified Configuration.
This section provides information about password, restricted, and obsolete options.
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 stores passwords in a separate file, you do not need to edit configuration files to remove them before sharing with Oracle Support.
Some configuration options are marked ”restricted” by Oracle. Additionally, 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.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
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 option on a channel (for MX mail forwarding records), any of the nomx, randommx, and other related ”mx” options 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 uses a ”unified” option naming convention that is reminiscent of legacy 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=”example.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.example.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:configutil -H -o logfile.imap.expirytime Configuration option: logfile.imap.expirytime Unified Config Name: imap.logfile.expirytime
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:
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
Edit the option.dat file and add the following option:
mm_debug=3
Edit (or create if it does not exist) the tcp_local_option file and add the following option:
trace_level=2
Check permissions on all files, especially the tcp_local_option file.
In Unified Configuration, the equivalent steps to the preceding task are the following:
% msconfig msconfig> set channel:tcp_local.slave_debug msconfig# set mm_debug 3 msconfig# set channel:tcp_local.options.trace_level 2 msconfig# write
You use recipe files, which are expressed by using a programming language, to automate configuration tasks, typically by scripting them. Recipes are located in the MessagingServer_home/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 the discussion on recipe language in the Messaging Server Reference.
This section provides some helpful commands to get started with Unified Configuration.
Use the msconfig show command to display current settings. For example, to show all currently enabled options:
/opt/sun/comms/messaging64/bin/msconfig show *enable role.watcher.enable = 1 role.schedule.enable = 1 role.store.enable = 1 role.store.purge.enable = 1 role.imap.enable = 1 role.pop.enable = 1 role.mta.enable = 1 role.dispatcher.service:SMTP.enable = 1 role.dispatcher.service:SMTP_SUBMIT.enable = 1 role.mmp.enable = 0 role.ens.enable = 1 role.http.enable = 1
Use the msconfig help command.