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.
Topics:
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."
Table 41-1 shows the options for the configure command:
Table 41-1 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:
configure
To configure an initial legacy configuration:
configure --noxml
Note:
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.The configtoxml command converts a legacy configuration to a Unified Configuration.
Table 41-2 shows the options for the configtoxml command:
Table 41-2 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. 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. |
|
-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-FILEPASSWORD-FILERESTRICTED-FILE | --output CONFIG-FILEPASSWORD-FILERESTRICTED-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)
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
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.
Caution:
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 msconfigTo 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:
role.channel:ims-ms.official_host_name role.channel:ims-ms.backoff role.channel:ims-ms.defragment role.channel:ims-ms.fileinto role.channel:ims-ms.maxjobs role.channel:ims-ms.notices role.channel:ims-ms.pool
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:
msconfig
When run interactively, the default prompt for msconfig changes to the following:
msconfig>
After you have modified the configuration, the prompt changes to the following:
msconfig#
The DEFAULT, INSTANCE, and ROLE commands also affect the prompt. In default mode:
msconfig>
In Instance mode:
msconfig.instance>
In Role mode:
msconfig.role>
Table 41-3 lists the commands for msconfig:
| 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 |
Tip:
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 |
|
CONVERSIONS |
MTA conversion channel control entries |
|
FILTER |
Sieve filter |
|
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 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:
(|(uid=%U)(mail=%o))
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
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.
Tip:
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 |
|---|---|
|
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) |
|
local.store.notifyplugin.*.* |
notifytarget:*.* |
|
service.imap.capability.* |
imap.capability_* |
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 \ switchchannel tcp_local-daemon == trace_level=2