An ssoadm Command-Line Example Specific to Agents

This section provides an example of how you can use the ssoadm command-line for agent-related subcommands. This example highlights the update-agent option. The update-agent option allows you to configure agent properties. The following is an example of how the ssoadm command can be issued with the update-agent option:

# ./ssoadm update-agent -e testRealm1 -b testAgent1 -u amadmin -f 
/tmp/testpwd -a "com.sun.identity.agents.config.notenforced.uri[0]=/exampledir/public/*"

For the preceding command example, notice that a wildcard was used in the value for this particular property and that the property and value are enclosed in double quotes. The caution that follows addresses this issue. For more information about wildcards, see Appendix C, Wildcard Matching in Policy Agent 3.0 J2EE Agents.

When issuing the ssoadm command, if you include values that contain wildcards (* or -*-), then the property name/value pair should be enclosed in double quotes to avoid substitution by the shell. This applies when you use the -a (--attributevalues) option. The double quotes are not necessary when you list the properties in a data file and access them with the -D option.

The format used to assign values to agent properties differs for OpenSSO Enterprise Console and the ssoadm command-line utility. For information about the format to use with the ssoadm utility, refer to the agent property file: OpenSSOAgentConfiguration.properties. This file demonstrates the correct format to use when assigning values to the agent properties using the ssoadm utility. Find this property file on the agent host machine in the following directory:

PolicyAgent-base/AgentInstance-Dir/config

For information on the place holders (PolicyAgent-base and AgentInstance-Dir) used in the preceding path, see Policy Agent Software: Path and Directory Names.

Listing the Options for an ssoadm Subcommand

You can read the options for a subcommand from this guide or you can list the options yourself while using the command. On the machine hosting OpenSSO Enterprise, in the directory containing the ssoadm utility, issue the ssoadm command with the appropriate subcommand. For example:

# ./ssoadm update-agent 

Since the preceding command is missing required options, the utility merely lists all the options available for this subcommand. For example:

ssoadm update-agent --options [--global-options]
Update agent configuration.
Usage:
ssoadm
    --realm|-e
    --agentname|-b
    --adminid|-u
    --password-file|-f
    [--set|-s]
    [--attributevalues|-a]
    [--datafile|-D]Global Options:
    --locale, -l
        Name of the locale to display the results.

    --debug, -d
        Run in debug mode. Results sent to the debug file.

    --verbose, -v
        Run in verbose mode. Results sent to standard output.

Options:
    --realm, -e
        Name of realm.

    --agentname, -b
        Name of agent.

    --adminid, -u
        Administrator ID of running the command.

    --password-file, -f
        File name that contains password of administrator.

    --set, -s
        Set this flag to overwrite properties values.

    --attributevalues, -a
        properties e.g. homeaddress=here.

    --datafile, -D
        Name of file that contains properties.

Analysis of an ssoadm Subcommand's Usage Information

By looking at the usage information of a subcommand, you can determine which options are required and which are optional. You can list an option for the command with either a single letter, such as -e or with an entire word, such as --realm. The following is a list of the usage information for the update-agent subcommand:

ssoadm update-agent
    --realm|-e
    --agentname|-b
    --adminid|-u
    --password-file|-f
    [--set|-s]
    [--attributevalues|-a]
    [--datafile|-D]

The options not bounded by square brackets are required. Therefore, realm, agentname, adminid, password-file. However, even though the three options in brackets (the global options) are considered optional, you must use either --attributevalues or --datafile to provide a property name and the corresponding value. The --attributevalues option is appropriate for assigning values to a single property. The --datafile option is appropriate for setting several properties at once. The realm and agentname options identify the specific agent you are configuring. The adminid and password-file commands identify you as someone who has the right to configure this agent.

The following command serves as an example of how you can change several agent properties at once. In this scenario the properties and their respective values are stored in a file, /tmp/testproperties, to which the command points:

# ./ssoadm update-agent -e testRealm1 -b testAgent1 -u amadmin -f 
/tmp/testpwd -D /tmp/testproperties