Msconfig utility

Syntax
msconfig &#x5b;switches&#x5d; &#x5b;command&#x5d; &#x5b;\command&#x5d;...

Parameters
The msconfig utility may be used interactively by invoking it without any commands: msconfig or noninteractively by specifying one or more commands as an argument, e.g., msconfig SET &#x3c;option&#x3e; &#x3c;value&#x3e;

Switches
The msconfig utility accepts a number of switches on the invocation line.

Specifies an alternate location for Messaging Server configuration files. msconfig will read and write config.xml and xpass.xml from this alternate location. The directory where the files are located must be given as an argument.

Prints basic information about using msconfig and enters the msconfig help system. msconfig exits after help system access is terminated.

If specified, msconfig will read commands from a file instead of from the terminal. The input file name must be given as an argument. If -input is specified no msconfig commands can be given on the invocation line.

If specified, the -multiple switch allows multipe commands to be specified on the command line separated by backslashes "\".

Read the configuration but do not validate it. Warning: This should only be used in extreme situations where a broken configuration needs to be analyzed. Such a configuration should NEVER be used in production.

If specified, msconfig will direct its output to the specified file.

Controls whether or not msconfig help system output stops and prompts after each page. -page is the default; use -nopage to disable output paging.

Controls whether or not the help system prompts for additional topics after a topic has been output. -prompt is the default; use -noprompt to turn off help system prompting.

Open configuration in readonly mode and without locking. This is useful when performing display operations that should not fail when someone is editing the configuration.

Specifies a remark to attach to configuration as it is written. The remark string must be given as an argument.

The primary use of -remark is to specify a remark when a command is given on the invocation line, e.g., msconfig -remark "Enable enqueue debugging" set mm_debug 5

The -require switch specifies a list of conditions that must be met for "successful" operation. msconfig will exit with a nonzero status if these conditions are not met. The available conditions are:



 write - One or more configuration writes must have been performed. 



Commands
List of msconfig utility commands:

Reset the location where options are set to default location.

Manipulate deployment maps. The supported operations are ADD, DELETE, DUMP, LIST, CREATE, RENAME, SET, READ, and WRITE.

Displays the recipes whose names match the specified &#x3c;filter&#x3e;.

Compare configurations.

Places the specified object in a file and invokes the editor to enable editing.

Execute the specified string as if it were a one-line recipe. The final value computed by the recipe is printed at the end of execution.

Exit msconfig utility with a prompt to write if configuration was modified.

Display help.

Display previous saved configurations.

Store options in instance.

Read configuration from alternate file(s).

Display previous saved configurations. Synonym for

Exit msconfig utility discarding changes.

Discard modifications and reload configuration.

Store options in role.

Run the specified recipe file with the specified arguments. If no file path is given as part of "recipe" the command will look for the file in &#x3c;configroot&#x3e;/recipes, and if not found there, it will look in &#x3c;serverroot&#x3e;/lib/recipes.

The arguments specified in the run command can be accessed in the recipe with the argc and argv functions.

Set option to the specified value(s).

Show value of option.

Delete option setting.

Write out configuration changes.

Description
The msconfig utility is used to examine and modify Messaging Server configuration. See Configuration syntax for more information on the Messaging Server configuration.

The utility performs type checking on configuration settings it makes. See Option value syntax for further details.

Prompts
When run interactively, msconfig&#x27;s default prompt is: msconfig&#x3e; When modifications have been made to the configuration the prompt will change to: msconfig# The DEFAULT, INSTANCE, and ROLE commands also affect the prompt:





Default mode: msconfig&#x3e; 



Instance mode: msconfig.instance&#x3e; 



Role mode: msconfig.role&#x3e; 



Return status
msconfig returns a status of 0 if the last command executed successfully, 1 if the last command generated an error, and 2 if the last command could not be performed because the configuration was locked.

msconfig will also return a status of 1 if the conditions specified as arguments to the -require switch are not met.

Help Command
The msconfig utility is a comprehensive help utility and its help command can be used to get help not only on the utility and its commands but also on various topics pertaining to the Messaging Server. msconfig help This lists all the Topics on which help is available. Choose a specific Topic which gives some information and then one can enter additional sub-topics for more in depth information.

Help on specific msconfig commands can be accessed in interactive mode by entering: help commands           &#x3c;- List of available commands help commands &#x3c;command&#x3e; &#x3c;- Information about command &#x3c;command&#x3e; Help on the options msconfig can manipulate can be accessed by entering: help option &#x3c;option&#x3e;    &#x3c;- Information about option &#x3c;option&#x3e; Note that options in the help system should be specified without any associated scope.

Use the  switch along with list of strings to display ALL articles that contain the specified strings. help -search string1 &#x5b;string2...&#x5d; Use the  switch along with list of keywords to display ALL articles marked with any of the specified keywords.

To disable the prompts when additional information is available, use the  switch.

Help output by default is paged. Use  to display additional pages. displays an additional line. displays remaining information without paging and  stops the output. Use  switch to disable paging.

Show Command
Use the msconfig show command to display current settings.

For example, to show all currently enabled options: msconfig show &#x2a;enable

Set Command
Use the msconfig set option &#x5b;value1 &#x5b;value2&#x5d;&#x5d; command to set option values.

Use the -prompt switch for entering passwords since it causes the utility to prompt for the value without echoing it.

Values must be quoted if they contain spaces. In non-interactive mode, each special character must be prefixed with the escape character "\". For example, to set the value of the auth.searchfilter option to (&#x7c;(uid=%U)(mail=%o)): msconfig set auth.searchfilter \"\(\&#x7c;\(uid\=\%U\)\(mail\=\%o\)\)\"

Edit Command
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: 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 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 The msconfig command provides the same editing capability for MTA rewrite rules (edit rewrites), mappings (edit mappings), MTA conversion channel control entries (edit conversions), Sieve filters (edit filter), options (edit option) and MTA aliases (edit aliases)

All objects placed in the file for editing are deleted prior to reloading the file&#x27;s contents. Use  to treat the resulting  file contents as configuration additions.

All configuration changes are normalized and validated by default. Use  to disable validation.

List and Compare Configurations Commands
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. msconfig history        &#x3c;- List of configurations in the graveyard msconfig differences    &#x3c;- Compare configurations

See also:
 * Messaging Server command line utilities
 * Configuration syntax
 * Option value syntax
 * instancename Option
 * rolename Option
 * Special symbolic names
 * Recipe language
 * Sieve filters
 * TCP wrappers
 * restricted.cnf file
 * MTA options