Appendix D Using the ssoadm Command-Line Utility With Agents

When the agent configuration is centralized, you can configure OpenSSO Enterprise through OpenSSO Enterprise Console or through the command line, using the ssoadm utility.

The ssoadm utility cannot be used in scenarios where the agent configuration is stored locally with the agent.

The ssoadm utility has a set of subcommands that allow you to create and configure agents. All agent-related configurations that can be made using OpenSSO Enterprise Console can also be made using the command line. This appendix indicates which ssoadm subcommands are related to agents.

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

Agent-Related Subcommands for the ssoadm Command

This sections lists the options available for each of the agent-related subcommands of the ssoadm command. The agent-related subcommands are presented as links in the following list:

• The ssoadm Command: add-agent-to-grp subcommand

• The ssoadm Command: agent-remove-props subcommand

• The ssoadm Command: create-agent subcommand

• The ssoadm Command: create-agent-grp subcommand

• The ssoadm Command: delete-agent-grps subcommand

• The ssoadm Command: delete-agents subcommand

• The ssoadm Command: list-agent-grp-members subcommand

• The ssoadm Command: list-agent-grps subcommand

• The ssoadm Command: list-agents subcommand

• The ssoadm Command: remove-agent-from-grp subcommand

• The ssoadm Command: show-agent subcommand

• The ssoadm Command: show-agent-grp subcommand

• The ssoadm Command: show-agent-membership subcommand

• The ssoadm Command: show-agent-types subcommand

• The ssoadm Command: update-agent subcommand

• The ssoadm Command: update-agent-grp subcommand

The ssoadm Command: add-agent-to-grp subcommand

ssoadm add-agent-to-grp--options [--global-options]
Add agents to a agent group.

Usage:
ssoadm
    --realm|-e
    --agentgroupname|-b
    --agentnames|-s
    --adminid|-u
    --password-file|-f

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.

    --agentgroupname, -b
        Name of agent group.

    --agentnames, -s
        Names of agents.

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

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

The ssoadm Command: agent-remove-props subcommand

ssoadm agent-remove-props --options [--global-options]
Remove agent's properties.

Usage:
ssoadm
    --realm|-e
    --agentname|-b
    --attributenames|-a
    --adminid|-u
    --password-file|-f

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.

    --attributenames, -a
        properties name(s).

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

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

The ssoadm Command: create-agent subcommand

ssoadm create-agent --options [--global-options]
Create a new agent configuration.

Usage:
ssoadm
    --realm|-e
    --agentname|-b
    --agenttype|-t
    --adminid|-u
    --password-file|-f
    [--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.

    --agenttype, -t
        Type of agent. e.g. J2EEAgent, WebAgent

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

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

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

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

The ssoadm Command: create-agent-grp subcommand

ssoadm create-agent-grp --options [--global-options]
Create a new agent group.

Usage:
ssoadm
    --realm|-e
    --agentgroupname|-b
    --agenttype|-t
    --adminid|-u
    --password-file|-f
    [--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.

    --agentgroupname, -b
        Name of agent group.

    --agenttype, -t
        Type of agent group. e.g. J2EEAgent, WebAgent

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

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

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

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

The ssoadm Command: delete-agent-grps subcommand

ssoadm delete-agent-grps --options [--global-options]
Delete agent groups.

Usage:
ssoadm
    --realm|-e
    --agentgroupnames|-s
    --adminid|-u
    --password-file|-f

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.

    --agentgroupnames, -s
        Names of agent group.

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

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

The ssoadm Command: delete-agents subcommand

ssoadm delete-agents --options [--global-options]
Delete agent configurations.

Usage:
ssoadm
    --realm|-e
    --agentnames|-s
    --adminid|-u
    --password-file|-f

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.

    --agentnames, -s
        Names of agent.

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

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

The ssoadm Command: list-agent-grp-members subcommand

ssoadm list-agent-grp-members --options [--global-options]
List agents in agent group.

Usage:
ssoadm
    --realm|-e
    --agentgroupname|-b
    --adminid|-u
    --password-file|-f
    [--filter|-x]

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.

    --agentgroupname, -b
        Name of agent group.

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

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

    --filter, -x
        Filter (Pattern).

The ssoadm Command: list-agent-grps subcommand

ssoadm list-agent-grps --options [--global-options]
List agent groups.

Usage:
ssoadm
    --realm|-e
    --adminid|-u
    --password-file|-f
    [--filter|-x]
    [--agenttype|-t]

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.

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

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

    --filter, -x
        Filter (Pattern).

    --agenttype, -t
        Type of agent. e.g. J2EEAgent, WebAgent

The ssoadm Command: list-agents subcommand

ssoadm list-agents --options [--global-options]
List agent configurations.

Usage:
ssoadm
    --realm|-e
    --adminid|-u
    --password-file|-f
    [--filter|-x]
    [--agenttype|-t]

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.

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

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

    --filter, -x
        Filter (Pattern).

    --agenttype, -t
        Type of agent. e.g. J2EEAgent, WebAgent

The ssoadm Command: remove-agent-from-grp subcommand

ssoadm remove-agent-from-grp --options [--global-options]
Remove agents from a agent group.

Usage:
ssoadm--realm|-e
    --agentgroupname|-b
    --agentnames|-s
    --adminid|-u
    --password-file|-f

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.

    --agentgroupname, -b
        Name of agent group.

    --agentnames, -s
        Names of agents.

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

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

The ssoadm Command: show-agent subcommand

ssoadm show-agent --options [--global-options]
Show agent profile.

Usage:
ssoadm
    --realm|-e
    --agentname|-b
    --adminid|-u
    --password-file|-f
    [--outfile|-o]
    [--inherit|-i]

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.

    --outfile, -o
        Filename where configuration is written to.

    --inherit, -i
        Set this to inherit properties from parent group.

The ssoadm Command: show-agent-grp subcommand

ssoadm show-agent-grp --options [--global-options]
Show agent group profile.

Usage:
ssoadm
    --realm|-e
    --agentgroupname|-b
    --adminid|-u
    --password-file|-f
    [--outfile|-o]

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.

    --agentgroupname, -b
        Name of agent group.

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

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

    --outfile, -o
        Filename where configuration is written to.

The ssoadm Command: show-agent-membership subcommand

ssoadm show-agent-membership --options [--global-options]
List agent?s membership.

Usage:
ssoadm
    --realm|-e
    --agentname|-b
    --adminid|-u
    --password-file|-f

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.

The ssoadm Command: show-agent-types subcommand

ssoadm show-agent-types --options [--global-options]
Show agent types.

Usage:
ssoadm
    --adminid|-u
    --password-file|-f

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:
    --adminid, -u
        Administrator ID of running the command.

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

The ssoadm Command: update-agent subcommand

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.

The ssoadm Command: update-agent-grp subcommand

ssoadm update-agent-grp --options [--global-options]
Update agent group configuration.
Usage:

ssoadm
    --realm|-e
    --agentgroupname|-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.

    --agentgroupname, -b
        Name of agent group.

    --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.