Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for Web Agents

Role of the agentadmin Program in Policy Agent 3.0

The agentadmin utility is the predominant install and configuration tool forPolicy Agent 3.0. The most basic of tasks, such as installation and uninstallation can be performed with this tool.


Note –

Installation and configuration tasks that can be performed with the agentadmin utility can also be performed with the OpenSSO Enterprise ssoadm utility. For more information, see Appendix D, Using the ssoadm Command-Line Utility With Agents.


The location of the agentadmin program is as follows:

PolicyAgent-base/bin

For information about the PolicyAgent-base directory, see Default Path and Directory Names.

The following information about agentadmin program demonstrates the scope of this utility:

Table 3–2 The agentadmin Program: Supported Options

Option 

Task Performed 

--install

Installs a new agent instance 

--custom-install

Installs a new agent instance 

--uninstall

Uninstalls an existing Agent instance 

--listAgents

Displays details of all the configured agents 

--agentInfo

Displays details of the agent corresponding to the specified agent IDs 

--version

Displays the version information 

--encrypt

Encrypts a given string 

--getEncryptKey

Generates an Agent Encryption key 

--uninstallAll

Uninstalls all agent instances 

--migrate

Migrates agent to a newer version 

--usage

Displays the usage message 

--help

Displays a brief help message 

agentadmin --install

This section demonstrates the format and use of the agentadmin command with the --install option. The --install option is very similar to the --custom-install option. However, when you install an agent using the agentadmin --install command, the installer provides you with a minimal number of prompts and uses default values for the other options. For example, with the --custom-install option, you can create the agent profile during agent installation. You do not have this option with the --install option.


Example 3–2 Command Format: agentadmin --install

The following example illustrates the format of the agentadmin command with the --install option:


./agentadmin --install [--useResponse] [--saveResponse] filename

The following arguments are supported with the agentadmin command when using the --install option:


--saveResponse

Use this argument to save all supplied responses to a state file, or response file, represented as filename in command examples. The response file, or state file, can then be used for silent installations.

--useResponse

Use this argument to install an agent in silent mode as all installer prompts are answered with responses previously saved to a response file, represented as filename in command examples. When this argument is used, the installer runs in non-interactive mode. At which time, user interaction is not required.

filename

Use this argument to specify the name of a file that will be created as part of the processing of this command. This file stores your responses when this argument is used in conjunction with the --saveResponse argument and provides your responses when this argument is used in conjunction with the --useResponse argument.


Example 3–3 Command Usage: agentadmin --install

When you issue the agentadmin command, you can choose the --install option. With the --install option, you can choose the --saveResponse argument, which requires a file name be provided. The following example illustrates this command when the file name is myfile:


./agentadmin --install --saveResponse myfile

Once the installer has executed the preceding command successfully, the responses are stored in a state file that can be used for later runs of the installer.

If desired, you can modify the state file and configure the second installation with a different set of configuration parameters.

Then you can issue another command that uses the ./agentadmin --install command and the name of the file that you just created with the --saveResponse argument. The difference between the previous command and this command is that this command uses the --useResponse argument instead of the --saveResponse argument. The following example illustrates this command:


./agentadmin --install --useResponse myfile

With this command, the installation prompts run the installer in silent mode, registering all debug messages in the install logs directory.


agentadmin --custom-install

This section demonstrates the format and use of the agentadmin command with the --custom-install option. The --custom-install option is very similar to the --install option. However, when you install an agent using the agentadmin --custom-install command, the installer provides you with a greater number of prompts, and therefore allows you to select a greater number of settings. The --install option, on the other hand, selects default values for many options. For example, with the --custom-install option, you can create the agent profile during agent installation. You do not have this option with the --install option.


Note –

The arguments available with the --custom-install option, as listed in the next section, are the same as for the --install option.



Example 3–4 Command Format: agentadmin --custom-install

The following example illustrates the format of the agentadmin command with the --custom-install option:


./agentadmin --custom-install [--useResponse] [--saveResponse] filename

The following arguments are supported with the agentadmin command when using the --custom-install option:


--saveResponse

Use this argument to save all supplied responses to a state file, or response file, represented as filename in command examples. The response file, or state file, can then be used for silent installations.

--useResponse

Use this argument to install an agent in silent mode as all installer prompts are answered with responses previously saved to a response file, represented as filename in command examples. When this argument is used, the installer runs in non-interactive mode. At which time, user interaction is not required.

filename

Use this argument to specify the name of a file that will be created as part of the processing of this command. This file stores your responses when this argument is used in conjunction with the --saveResponse argument and provides your responses when this argument is used in conjunction with the --useResponse argument.


Example 3–5 Command Usage: agentadmin --custom-install

When you issue the agentadmin command, you can choose the --custom-install option. With the --custom-install option, you can choose the --saveResponse argument, which requires a file name be provided. The following example illustrates this command when the file name is myfile:


./agentadmin --custom-install --saveResponse myfile

Once the installer has executed the preceding command successfully, the responses are stored in a state file that can be used for later runs of the installer.

If desired, you can modify the state file and configure the second installation with a different set of configuration parameters.

Then you can issue another command that uses the ./agentadmin --custom-install command and the name of the file that you just created with the --saveResponse argument. The difference between the previous command and this command is that this command uses the --useResponse argument instead of the --saveResponse argument. The following example illustrates this command:


./agentadmin --custom-install --useResponse myfile

With this command, the installation prompts run the installer in silent mode, registering all debug messages in the install logs directory.


agentadmin --uninstall

This section demonstrates the format and use of the agentadmin command with the --uninstall option.


Example 3–6 Command Format: agentadmin --uninstall

The following example illustrates the format of the agentadmin command with the --uninstall option:


./agentadmin --uninstall [--useResponse] [--saveResponse] filename

The following arguments are supported with the agentadmin command when using the --uninstall option:


--saveResponse

Use this argument to save all supplied responses to a state file, or response file, represented as filename in command examples. The response file, or state file, can then be used for silent uninstallations.

--useResponse

Use this argument to uninstall an agent in silent mode as all uninstaller prompts are answered with responses previously saved to a response file, represented as filename in command examples. When this argument is used, the uninstaller runs in non-interactive mode. At which time, user interaction is not required.

filename

Use this argument to specify the name of a file that will be created as part of the processing of this command. This file stores your responses when this argument is used in conjunction with the --saveResponse argument and provides your responses when this argument is used in conjunction with the --useResponse argument.


Example 3–7 Command Usage: agentadmin --uninstall

When you issue the agentadmin command, you can choose the --uninstall option. With the --uninstall option, you can choose the --saveResponse argument, which requires a file name be provided. The following example illustrates this command where the file name is myfile:


./agentadmin --uninstall --saveResponse myfile

Once the uninstaller has executed the preceding command successfully, the responses are stored in a state file that can be used for later runs of the uninstaller.

If desired, you can modify the state file and configure the second uninstallation with a different set of configuration parameters.

Then you can issue another command that uses the ./agentadmin --uninstall command and the name of the file that you just created with the --saveResponse argument. The difference between the previous command and this command is that this command uses the --useResponse argument instead of the --saveResponse argument. The following example illustrates this command:


./agentadmin --uninstall --useResponse myfile

With this command, the uninstallation prompts run the uninstaller in silent mode, registering all debug messages in the install logs directory.


agentadmin --listAgents

This section demonstrates the format and use of the agentadmin command with the --listAgents option.


Example 3–8 Command Format: agentadmin --listAgents

The following example illustrates the format of the agentadmin command with the --listAgents option:


./agentadmin --listAgents

No arguments are currently supported with the agentadmin command when using the --listAgents option.



Example 3–9 Command Usage: agentadmin --listAgents

Issuing the agentadmin command with the --listAgents option provides you with information about all the configured agents on that deployment container.


agentadmin --agentInfo

This section demonstrates the format and use of the agentadmin command with the --agentInfo option.


Example 3–10 Command Format: agentadmin --agentInfo

The following example illustrates the format of the agentadmin command with the --agentInfo option:


./agentadmin --agentInfo AgentInstance-Dir

The following argument is supported with the agentadmin command when using the --agentInfo option:

AgentInstance-Dir

Use this option to specify which agent instance directory, therefore which agent instance, such as Agent_002, you are requesting information about.



Example 3–11 Command Usage: agentadmin --agentInfo

Issuing the agentadmin command with the --agentInfo option provides you with information on the specific agent instance that you name in the command. For example, if you want information about an agent instance named Agent_002, you can issue the command illustrated in the following example:


./agentadmin --agentInfo Agent_002

agentadmin --version

This section demonstrates the format and use of the agentadmin command with the --version option.


Example 3–12 Command Format: agentadmin --version

The following example illustrates the format of the agentadmin command with the --version option:


./agentadmin --version

No arguments are currently supported with the agentadmin command when using the --version option.



Example 3–13 Command Usage: agentadmin --version

Issuing the agentadmin command with the --version option provides you with version information for the configured agents on that deployment container. For example, the agentadmin --version command provides the version of the agent, such as 3.0 and the build date of the agent.


agentadmin --encrypt

This section demonstrates the format and use of the agentadmin command with the --encrypt option.


Example 3–14 Command Format: agentadmin --encrypt

The following example illustrates the format of the agentadmin command with the --encrypt option.


./agentadmin --encrypt AgentInstance-Dir agentpasswordfile

The following arguments are supported with the agentadmin command when using the --encrypt option:

AgentInstance-Dir

Use this option to specify which agent instance directory, therefore which agent instance such as Agent_002, for which the given password file will be encrypted. Encryption functionality requires that an encryption key be available for an agent instance. Therefore, a default encryption key can be assigned by the agent during agent installation. You can also assign an encryption key yourself. The encryption key is stored in the OpenSSOAgentBootstrap.properties file. For example:

am.encryption.pwd = EphgFHmF6X3XmMjYGCUtYHSYA9C7qQlk
agentpasswordfile

Use this option to specify the full path to the password file that contains a clear text agent password to be encrypted.

The password file should be created as an agent pre-installation task.



Example 3–15 Command Usage: agentadmin --encrypt

Issuing the agentadmin command with the --encrypt option enables you to change the password for an existing agent profile in OpenSSO Enterprise after the agent is installed.

For example, issuing the following command encrypts the password file, pwfile1 for the agent instance directory Agent_001:


./agentadmin --encrypt Agent_001 pwfile1

The following is an example of an encrypted value:


ASEWEJIowNBJHTv1UGD324kmT==

Each agent uses a unique agent ID and password to communicate with OpenSSO Enterprise. Once the agent profile for a specific agent has been created in OpenSSO Enterprise, the installer assigns the Policy Agent profile name and encrypted password in the respective agent instance. If you choose a new password for the Policy Agent profile, encrypt it and enter that encrypted password in the OpenSSOAgentBootstrap.properties as the value for the following property:


com.iplanet.am.service.secret

agentadmin --getEncryptKey

This section demonstrates the format and use of the agentadmin command with the --getEncryptKey option.


Example 3–16 Command Format: agentadmin --getEncryptKey

The following example illustrates the format of the agentadmin command with the --getEncryptKey option:


./agentadmin --getEncryptKey

No arguments are currently supported with the agentadmin command when using the --getEncryptKey option.



Example 3–17 Command Usage: agentadmin --getEncryptKey

This option may be used in conjunction with the --encrypt option to encrypt and decrypt sensitive information in the OpenSSOAgentBootstrap.properties file. Issuing the agentadmin command with the --getEncryptKey option generates a new encryption key for the agent.

For example, the following text demonstrates the type of output that would result from issuing this command:


./agentadmin -getEncryptKey


Agent Encryption Key : k1441g4EejuOgsPlFOSg+m6P5x7/G9rb

The encryption key is stored in the OpenSSOAgentBootstrap.properties file. Therefore, once you generate a new encryption key, use it to replace the value of the property that is currently used to store the encryption key. The following property in the OpenSSOAgentBootstrap.properties file stores the encryption key:

com.sun.identity.agents.config.key

For example, using the encryption key example provided previously, updating the encryption key value for the applicable agent property could appear as follows:

com.sun.identity.agents.config.key = k1441g4EejuOgsPlFOSg+m6P5x7/G9rb

Once you have updated the OpenSSOAgentBootstrap.properties file with the new encryption key, issue the agentadmin --encrypt command to actually encrypt a password. The --encrypt option uses the encryption key in its processing.


agentadmin --uninstallAll

This section demonstrates the format and use of the agentadmin command with the --uninstallAll option.


Example 3–18 Command Format: agentadmin --uninstallAll

The following example illustrates the format of the agentadmin command with the --uninstallAll option:


./agentadmin --uninstallAll

No arguments are currently supported with the agentadmin command when using the --uninstallAll option.



Example 3–19 Command Usage: agentadmin --uninstallAll

Issuing the agentadmin command with the --uninstallAll option runs the agent uninstaller in an iterative mode, enabling you to remove select agent instances or all agent instances on that deployment container. You can exit the recursive uninstallation process at any time.

The advantage of this option is that you do not have to remember the details of each installation-related configuration. The agentadmin program provides you with an easy method for displaying every instance of an agent on a deployment container. You can then decide, case by case, to remove an agent instance or not.


agentadmin --migrate

This section demonstrates the format and use of the agentadmin command with the --migrate option.


Example 3–20 Command Format: agentadmin --migrate

The following example illustrates the format of the agentadmin command with the --migrate option:


./agentadmin --migrate

No arguments are currently supported with the agentadmin command when using the --migrate option.



Example 3–21 Command Usage: agentadmin --migrate

Issuing the agentadmin command with the --migrate option allows you to update an agent in the Policy Agent software set to a newer version of that same agent.

For example, you can migrate Policy Agent 2.2 to Policy Agent 3.0. The agentadmin --migrate command allows you to migrate the agent's binary files, update the agent's deployment container configuration, and convert the agent's AMAgent.properties file to the property files used for the 3.0 version: the OpenSSOAgentBootstrap.properties file and the OpenSSOAgentConfiguration.properties file.


agentadmin --usage

This section demonstrates the format and use of the agentadmin command with the --usage option.


Example 3–22 Command Format: agentadmin --usage

The following example illustrates the format of the agentadmin command with the --usage option:


./agentadmin --usage

No arguments are currently supported with the agentadmin command when using the --usage option.



Example 3–23 Command Usage: agentadmin --usage

Issuing the agentadmin command with the --usage option provides you with a list of the options available with the agentadmin program and a short explanation of each option. The following text is the output you receive after issuing this command:


./agentadmin --usage 

Usage: agentadmin <option> [<arguments>]

The available options are:
--install: Installs a new Agent instance.
--custom-install: Installs a new Agent instance
--uninstall: Uninstalls an existing Agent instance.
--version: Displays the version information.
--uninstallAll: Uninstalls all the agent instances.
--migrate: migrate agent to newer one
--listAgents: Displays details of all the configured agents.
--agentInfo: Displays details of the agent corresponding to the specified
agent ID.
--encrypt: Encrypts a given string.
--getEncryptKey: Generates an Agent Encryption key.
--usage: Display the usage message.
--help: Displays a brief help message.

agentadmin --help

This section demonstrates the format and use of the agentadmin command with the --help option.


Example 3–24 Command Format: agentadmin --help

The following example illustrates the format of the agentadmin command with the --help option:


./agentadmin --help

No arguments are currently supported with the agentadmin command when using the --help option.



Example 3–25 Command Usage: agentadmin --help

Issuing the agentadmin command with the --help option provides similar results to issuing the agentadmin command with the --usage option. Both commands provide the same explanations for the options they list. With the --usage option, all agentadmin command options are explained. With the --help option, explanations are not provided for the --usage option or for the --help option itself.

A another difference is that the --help option also provides information about the format of each option while the --usage option does not.