Using the Convergence Administration Utility

About the Convergence Administration Utility

You can use the Convergence iwcadmin command-line utility to perform administrative tasks in Convergence. The following are some of the reasons you would want to use the command-line utility:

During the initial runtime configuration, you created the runtime environment for your deployment using the initial configuration utility. While some of the many possible properties were set from your choices, many of the configuration properties were merely given default values that might not be right for your site. You can use the administration utility to change those values to ones appropriate to your site.
In time you will need to make various changes to the configuration to accommodate changing business needs, including day-to-day operations. The configuration utility enables you to change the properties to suit your needs.
The utility validates the values you specify. It confirms that your new values are of the proper data types, and fall within the range of valid values, if appropriate.

Administration Utility Options

The iwcadmin command reads or writes single or multiple configuration file properties. When the utility writes to the configuration file, it performs a validity check on the value that you provide for the property. The validity check validates data types, value limits, and ranges. The iwcadmin command exists in the Convergence_Home/sbin directory.

You can use the iwcadmin command only on the local machine on which Convergence is installed.

You must restart the Oracle WebLogic server if you make any configuration changes using the iwcadmin command.

Command-Line Utility Syntax

Use the iwcadmin command to display its usage and syntax:

iwcadmin -h

The following example shows the usage and syntax of the iwcadmin command:


USAGE: iwcadmin [-p port] [-s] [-o param_name [-v param_value]] [-l [group_name]] [-f config_params_file] [-V]
    -u    --admin           userID of user authorized to make iwcadmin updates. Optional parameter. If -u is not specified, userID (default: admin)
                            is pulled from the iwcadmin.properties file.
    -p    --port            Administration port of the server.
    -s    --secure          Use a secure connection (HTTPS).
    -o    --option          The configuration parameter name to read or write.
    -v    --value           The value to be set. Must be used with the -o option and must be specified immediately after the -o option.
    -l    --list            List all the configuration parameters and their values.
    -f    --file            The file from which to read configuration property/value pairs.
    -V    --version         Display the version information of the product.
    -h    --help            Display this message.

To read the value of a property:
```
iwcadmin [-p port] [-s] -o option_name
```

To write the value of a property:

iwcadmin [-p port] [-s] -o option_name -v option_value

To update multiple properties:

iwcadmin [-p port] [-s] -f path/filename

To read the value of all configuration properties:
```
iwcadmin [-p port] [-s] -l
```

To get information about configuration properties:

iwcadmin [-p port] [-s] -o config_parameter_name -h

To get information about configuration properties for a specific module:
```
iwcadmin [-p port] [-s] -l group_name
```
This option is useful when you want to see the values of the configuration parameters for a specific group

For example:
```
iwcadmin -l mail
mail.cookiename = webmailsid
mail.enable = true
mail.enablessl = false
mail.host = siroe.com
mail.port = 8990
mail.proxyadminid = admin
mail.proxyadminpwd = r6iwhIcDUL6r69vu2Jt24A==
mail.requesttimeout =
mail.spam.enableaction =
mail.spam.folder =
mail.uwcsievecompatible = true
```
Where group_name is the name of the group for which you want to list the parameters. To get a list of the groups available in the Convergence deployment, use the -h option.

For example:

iwcadmin -l -h lists all the configuration parameters and their values. It optionally takes the group name as an argument and lists the parameters that belong to the given group.
Available groups: base, ugldap, auth, mail, log, cal, caldav, nab,  ab, client, admin, sso, user, ens, notify, oin.

To get the current version of the software:
```
iwcadmin -V
```

Note:

If you use tcsh and enter an iwcadmin parameter enclosed in curly braces {}, you must escape the braces by preceding each brace with a backslash (\).

For example:

\{ ... \}

Managing Security of Passwords

When using the iwcadmin command, you cannot include the -W password_file parameter unless the password file is encrypted. For this reason, the -W parameter is omitted from all examples in this guide.

Use the following command to retrieve an encrypt password:

iwcadmin -o admin.adminpwd

If you exclude the -W password_file parameter from your commands, the command-line utility asks you to provide your password.

Command-line Options

Table 2-1 lists all the command-line syntax options.

Table 2-1 Options for Configuration Utility for Convergence

Option	Long name	Description
-p	--port	Administration port on which the server listens.
-s	--secure	Optional. Ensures a secure connection.
-o	--option	Configuration property name to read or write. If you do not specify the `-v` option, the utility performs a read operation. If this option is specified in the same command with the `-f` option, the `-f` option is ignored. The `-o` option takes precedence.
-v	--value	Value to be set. Use with the `-o` option and must be specified immediately after the `-o` option.
-f	--file	The file that contains the property name value pairs. This file contains multiple pairs of properties and their values. It enables an administrator to update multiple properties in a batch mode using a single command. The format of the file is a list of option and value pairs (separated by =), and a line return between options.
-V	--version	Version information of the product.
-l	--list	This option has no values. It retrieves all existing configuration parameters and displays them. Optionally, this parameter also takes a group name as an argument and lists the parameters that belong to the given group.
-h	--help	Help to use this utility.

You can obtain details about the configuration parameters that you can use with the -o option by using this option along with the -h option. Before setting a configuration parameter value, you can learn about the parameter usage, the functionality, and the supported data type.

The following syntax shows the usage of the -o option with the -h option:

iwcadmin [-p port] [-s] -o config_params_name -h

The -h option displays the following configuration parameter details:

Option Name: Name of the configuration parameter.
Description: Short description.
Syntax: Input data type.
Allowed Pattern: Accepted parameter pattern or range of values.
Current Value: Current value of this parameter in the Convergence deployment.

The following example displays help for the user.mail.blockimages configuration parameter:

iwcadmin -o user.mail.blockimages -h
Option Name: user.mail.blockimages
Description: Specifies if images in the incoming mail should be shown or blocked
Syntax: boolean
Current Value: false

Setting and Unsetting Configuration Parameters

You can set or unset configuration parameters in Convergence. If a parameter does not require mandatory values, you can unset the parameter by setting its value to a blank string. You cannot unset parameters that require mandatory values.

For example, to unset the ab.pstore.[psidentifier1].ldaphost parameter, type the following command:

iwcadmin -o ab.pstore.[psidentifier1].ldaphost -v ""

This parameter is unset in the configuration.

To set a parameter, type the following command:

iwcadmin -o ab.pstore.[psidentifier1].ldaphost -v "ldap_host_name"

The iwcadmin command checks whether the parameter that you set is valid and has acceptable values.

Running the Administration Utility in Batch Mode

To update multiple attributes or configuration parameters in your deployment, invoke the iwcadmin command in batch mode. The -f parameter in the iwcadmin command enables you to set multiple parameters in a file by invoking the command only once.

To run the iwcadmin command in the batch mode:

Create a file with the name-value pairs for the options that you want to set. For example, the following entries in a file set the log level for all the log related modules in Convergence to the DEBUG level and the log rotation policy to 2048 bytes.
```
log.ADDRESS_BOOK.level = DEBUG
log.ADMIN.level = DEBUG
log.AUTH.level = DEBUG
log.CONFIG.level = DEBUG
log.DEFAULT.level = DEBUG
log.PROTOCOL.level = DEBUG
log.PROXY_CAL.level = DEBUG
log.PROXY_MAIL.level = DEBUG
log.SIEVE.level = DEBUG
log.sizetriggerval = 2048
```
In this example, the left hand side option is the name of the parameter that you want to set and the right hand side string is the value that you want to set it to.
Save the file at an appropriate location. For example, /tmp/logLevelSetting.
Type the iwcadmin command with the -f option and provide the path to the file:
```
iwcadmin -f /tmp/logLevelSetting
```