This chapter provides an overview of how to use the Oracle Communications Convergence administration command-line utility to administer Oracle Communications Convergence.
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.
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 certified application server if you make any configuration changes using the iwcadmin command.
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 List all the configuration parameters and their values. Optionally takes 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, ISS, ab, client, admin, sso, im, smime, 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:
\{ ... \}
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.
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 |
--value |
Value to be set. Use with the |
|
-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
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.
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