The agentadmin program is a required install and configuration tool for the 2.2 release of J2EE agents. The most basic of tasks, such as installation and uninstallation can only be performed with this tool.
The location of the agentadmin program is as follows:
PolicyAgent-base/bin
The following information about agentadmin program demonstrates the scope of this utility:
All agent installation and uninstallation is achieved with the agentadmin command.
All tasks performed by the agentadmin program, except those involving uninstallation, require the acceptance of a license agreement. This agreement is only presented the first time you use the program.
The following table lists options that can be used with the agentadmin command and gives a brief description of the specific task performed with each option.
A detailed explanation of each option follows the table.
In this section, the options described are the agentadmin program options that apply to all J2EE agents. Options that only apply to specific J2EE agents are relatively uncommon and are described where necessary within the corresponding J2EE agent guide.
Option |
Task Performed |
---|---|
--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 |
--getUuid |
Retrieves a universal ID for valid identity types |
--usage |
Displays the usage message |
--help |
Displays a brief help message |
This section demonstrates the format and use of the agentadmin command with the --install option.
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:
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.
Use this argument to install a J2EE 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.
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.
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.
This section demonstrates the format and use of the agentadmin command with the --uninstall option.
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:
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.
Use this argument to uninstall a J2EE 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.
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.
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.
This section demonstrates the format and use of the agentadmin command with the --listAgents option.
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.
Issuing the agentadmin command with the --listAgents option provides you with information about all the configured J2EE agents on that machine. For example, if two J2EE agents were configured on Sun Java System Application Server 8.1, the following text demonstrates the type of output that would result from issuing this command:
The following agents are configured on this Application Server. The following are the details for agent agent_001 :- Application Server Config Directory: /var/opt/SUNWappserver/domains/domain1/config Application Server Instance name: server1 The following are the details for agent agent_002 :- Application Server Config Directory: /var/opt/SUNWappserver/domains/domain1/config Application Server Instance name: server2 |
This example shows that two instances of the agent are configured: one for server1 and one for server2. Notice that the agentadmin program provides unique names, such as agent_001 and agent_002, to all the J2EE agents that protect the same instance of a deployment container, in this case Application Server 8.1. Each name uniquely identifies the J2EE agent instance.
This section demonstrates the format and use of the agentadmin command with the --agentInfo option.
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:
Use this option to specify which agent instance directory, therefore which agent instance such as agent_002, you are requesting information about.
Issuing the agentadmin command with the --agentInfo option provides you with information on the J2EE agent instance that you name in the command. For example, if you want information about a J2EE agent instance named agent_002 configured on Sun Java System Application Server 8.1, you can issue the command illustrated in the following example to obtain the type of output that follows:
./agentadmin --agentInfo agent_002 The following are the details for agent agent_002 :- Application Server Config Directory: /var/opt/SUNWappserver/domains/domain1/config Application Server Instance name: server2 |
In the preceding example, notice that information is provided only for the agent instance, agent_002, named in the command.
This section demonstrates the format and use of the agentadmin command with the --version option.
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.
Issuing the agentadmin command with the --version option provides you with version information for the configured J2EE agents on that machine. For example, if a J2EE agent were configured on Sun Java System Application Server 8.1, the following text demonstrates the type of output that would result from issuing this command:
-------------------------------------------------------------------------- Sun Java(TM) System Access Manager Policy Agent for: Sun Java(TM) System Application Server 8.1 -------------------------------------------------------------------------- Version: 2.2 Build Number: 05 AM 70 Client SDK Version: 20050810.2 AM 63 Client SDK Version: 20050914.1 Date: 2005-09-15 15:04 PDT Build Platform: machinename |
In the preceding example, notice that the Version field shows the major version number. The Build Number shows the minor version number. The Date field provides the date and time the agent was built, while the Build Platform field provides information about the platform on which the agent was built. The Client SDK versions signify the Access Manager–related client SDK versions that were shipped with the agent.
This section demonstrates the format and use of the agentadmin command with the --encrypt option.
The following example illustrates the format of the agentadmin command with the --encrypt option.
./agentadmin --encrypt AgentInstance-Dir fullpassfile |
The following arguments are supported with the agentadmin command when using the --encrypt option:
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 for a J2EE agent instance be present in the AMAgent.properties configuration file of that specific J2EE agent instance.
Use this option to specify the full path to the password file that will be encrypted.
The password file should be created as a J2EE agent pre-installation task. For more information, see Preparing to Install Agent for WebSphere Application Server 6.1
Issuing the agentadmin command with the --encrypt option enables you to change the password for an existing agent profile in Access Manager after the agent is installed.
For example, issuing the following command encrypts the password file, pwfile1 for the J2EE 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 Access Manager. Once the agent profile for a specific agent has been created in Access Manager, the installer enters the Policy Agent profile name and encrypted password in the respective J2EE agent AMAgent.properties configuration file for the agent instance. If you choose a new password for the Policy Agent profile, encrypt it and enter that encrypted password in the J2EE agent AMAgent.properties configuration file with the following property:
com.iplanet.am.service.secret |
This section demonstrates the format and use of the agentadmin command with the --getEncryptKey option.
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.
This option may be used in conjunction with the --encrypt option to encrypt and decrypt sensitive information in the J2EE agent AMAgent.properties configuration file. Issuing the agentadmin command with the --getEncryptKey option generates a new encryption key for the J2EE 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 J2EE agent AMAgent.properties configuration 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 J2EE agent AMAgent.properties configuration file stores the encryption key:
com.sun.identity.client.encryptionKey
For example, using the encryption key example provided previously, updating the encryption key value in the J2EE agent AMAgent.properties configuration file could appear as follows:
com.sun.identity.client.encryptionKey = k1441g4EejuOgsPlFOSg+m6P5x7/G9rb
Once you have updated the J2EE agent AMAgent.properties configuration 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.
This section demonstrates the format and use of the agentadmin command with the --uninstallAll option.
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.
Issuing the agentadmin command with the --uninstallAll option runs the agent uninstaller in an iterative mode, enabling you to remove select J2EE agent instances or all J2EE agent instances. 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 a J2EE agent. You can then decide, case by case, to remove a J2EE agent instance or not.
This section demonstrates the format and use of the agentadmin command with the --getUuid option.
The following example illustrates the format of the agentadmin command with the --getUuid option:
./agentadmin --getUuid userName IdType realmName |
The following arguments are supported with the agentadmin command when using the --getUuid option:
Use this first parameter of the --getUuid option to specify the name associated with the identity type. The identity type is represented in this example as the IdType parameter. Therefore, if the identity type is for a user, this userName parameter would be the name of that user.
Use this second parameter to specify a valid identity type. The following are examples of valid identity types: user, role, group, filtered role, agent, and such.
Use this third parameter to specify the name of the default organization of the Access Manager installation.
For example, if the ID of the user is manager, the identity type is role, and the realm name is dc=example,dc=com, the following would be the universal ID:
id=manager,ou=role,dc=example,dc=com |
The universal ID concept is only valid starting with Access Manager . Do not use this option with earlier versions of Access Manager, such as version 6.3. If the application is deployed with Access Manager 6.3 principals or roles, replace the role-to-principal mappings with the distinguished name (DN) of the user in Access Manager 6.3.
In Access Manager 7 2005Q4 and Access Manager 7.1, the agentadmin command with the --getUuid option retrieves the universal ID of any identity type in Access Manager.
If you run the agent in J2EE_POLICY mode, you must repackage the web applications with Access Manager role-to-principal mappings. The universal identifier is a way to make the name of the identity user unique.
Use the correct universal ID generated by this command in a deployment descriptor that is application container specific.
This section demonstrates the format and use of the agentadmin command with the --usage option.
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.
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. --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 ID. --version: Displays the version information. --encrypt: Encrypts a given string. --getEncryptKey: Generates an Agent Encryption key. --uninstallAll: Uninstalls all the agent instances. --getUuid: Retrieves a universal ID for valid identity types. --usage: Display the usage message. --help: Displays a brief help message. |
The preceding output serves as the content for the table of agentadmin options, introduced at the beginning of this section.
This section demonstrates the format and use of the agentadmin command with the --help option.
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.
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.