Using the ssoadm Command Line Interface

ssoadm contains many subcommands to perform specific tasks for a services, plug-ins, polices federation profiles, and so forth. Each subcommand contains a number of options, both required and non-required, that are defined to carry out these tasks. The following sections describe the usage of the subcommands and their associated options.

The basic syntax for the ssoadm command is:

ssoadm subcommand --options [--global-options]

The following global options are common to all subcommands, but are not required for the command to function:

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

Password File

In most ssoadm subcommands, the password file is required option. The password file is a simple file that contains the administrator password for the given task. To create a password file:

1. Create the password file in a location you will remember. For example:

   echo "" > /tmp/testpwd

2. It is recommended to change the permissions to read-only:

   chmod 400 /tmp/testpwd

ssoadm Usage Example

This section provides an example of how you can use the ssoadm command-line for a subcommand. 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.url[0]=/exampledir/public/*"

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.

Listing Options for an ssoadm Subcommand

You can read the options for a subcommand from this section 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. The global options are common to all subcommands. 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 attributes and corresponding values as in attribute-name=attribute-value. Enter one attribute and value per line.

Subcommand Usage

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

For subcommand options that accept multiple values, the values are space-separated and placed within quotation marks. For example, the -–attrubutevalues option, uses the following format:

–attributevalues “attributename=value” “attributename=value2”