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.
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.
The following table shows the options for the configure command:
Options for configure Command
|--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.
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.
The following table shows the options for the configtoxml command:
Options for configtoxml Command
|-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.
|-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:
|-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.
- 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.
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:
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:
|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
|ALIASES [alias-name]||MTA aliases|
|CHANNELS [channel-name]||MTA channels|
|CONVERSIONS||MTA conversion channel control entries|
|MAPPINGS [mapping-name]||MTA mappings|
|OPTION option-name||Specifies an option|
|REWRITES||MTA rewrite rule|
- 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:
or you can run the following in interactive mode:
- 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.
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|
|service.http.proxy.adminpass.*||proxy:*.httpadminpass (host-specific proxy password)|
|local.service.proxy.adminpass.*||proxy:*.imapadminpass (host-specific proxy password)|
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: