Chapter 2 Vital Installation Information for a Web Agent in Policy Agent 2.2

This chapter applies to Policy Agent 2.2 web agents developed through the OpenSSO project. These web agents differ from other web agents in a few ways as described in the following sections:

• Format of the Distribution Files for Web Agents in Policy Agent 2.2

• Introduction of the agentadmin Program in Web Agents for Policy Agent 2.2

• Web Agent Directory Structure in Policy Agent 2.2

Though this chapter applies to all web agents developed through the OpenSSO project, occasionally a specific web agent, Policy Agent 2.2 for Sun Java System Web Server 7.0, is used for example purposes. These examples are provided to illustrate general format. Replace web agent specific information where necessary.

Format of the Distribution Files for Web Agents in Policy Agent 2.2

The distribution files for agents in the Policy Agent 2.2 software set are different depending upon if the agent is developed as part of the OpenSSO project or not. Since Agent for Sun Java System Web Server 7.0 was developed in the OpenSSO project, it is only available as a .zip file, regardless of the platform on which it is to be deployed.

Introduction of the agentadmin Program in Web Agents for Policy Agent 2.2

The agentadmin program is a required installation and uninstallation tool for specific web agents in the Policy Agent 2.2 release. This section appears in this guide specifically because Agent for Sun Java System Web Server 7.0 is one of the web agents in the 2.2 release that uses the agentadmin program. Of the web agents in the Policy Agent 2.2 release, only those developed through the OpenSSO project use the agentadmin program.

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

For more information on the location of PolicyAgent-base, see Example 2–17.

The following information about the 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 specifically to web agents.

agentadmin --install

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

Example 2–1 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 a web 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 2–2 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 --uninstall

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

Example 2–3 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 a web 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 2–4 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 2–5 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 2–6 Command Usage: agentadmin --listAgents

Issuing the agentadmin command with the --listAgents option provides you with information about all the configured web agents on that machine. For example, if two web agents were configured on Sun Java System Web Server 7.0, the following text demonstrates the type of output that would result from issuing this command:

The following agents are configured on this Web Server.

The following are the details for agent Agent_001 :-
Sun Java System Web Server Config Directory:
/var/opt/SUNWwbsvr7/https-agentHost1.example.com/config

The following are the details for agent Agent_002 :-
Sun Java System Web Server Config Directory:
/var/opt/SUNWwbsvr7/https-agentHost1.example.com/config

Notice that the agentadmin program provides unique names, such as Agent_001 and Agent_002, to all the web agents that protect the same instance of a deployment container, in this case Web Server 7.0. Each name uniquely identifies the web agent instance.

The string “Agent” in Agent_00x is configurable. You can change this string by editing the following file: PolicyAgent-base/config/AMToolsConfig.properties

agentadmin --agentInfo

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

Example 2–7 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 2–8 Command Usage: agentadmin --agentInfo

Issuing the agentadmin command with the --agentInfo option provides you with information on the web agent instance that you name in the command. For example, if you want information about a web agent instance named Agent_002 configured on Sun Java System Web Server 7.0, 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 :-
Sun Java System Web Server Config Directory:
/var/opt/SUNWwbsvr7/https-agentHost1.example.com/config

In the preceding example, notice that information is provided only for the agent instance, Agent_002, named in the command.

agentadmin --version

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

Example 2–9 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 2–10 Command Usage: agentadmin --version

Issuing the agentadmin command with the --version option provides you with version information for the configured web agents on that machine.

agentadmin --uninstallAll

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

Example 2–11 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 2–12 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 web agent instances or all web 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 web agent. You can then decide, case by case, to remove a web agent instance or not.

agentadmin --usage

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

Example 2–13 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 2–14 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.
--uninstall: Uninstalls an existing Agent instance.
--version: Displays the version information.
--uninstallAll: Uninstalls all the agent instances.
--listAgents: Displays details of all the configured agents.
--agentInfo: Displays details of the agent corresponding to the specified
agent ID.
--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.

agentadmin --help

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

Example 2–15 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 2–16 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.

Web Agent Directory Structure in Policy Agent 2.2

The Policy Agent installation directory is referred to as the Policy Agent base directory (or PolicyAgent-base in code examples). The location of this directory and its internal structure are important facts that are described in this section. While the specifics of the agent directory structure described in this section apply to Policy Agent 2.2 for Sun Java System Web Server 7.0, they do not apply to web agents that were not developed through the OpenSSO project.

Location of the Web Agent Base Directory in Policy Agent 2.2

Unpacking the web agent binaries creates a directory named web_agents, within which an agent-specific directory is created. Regarding Policy Agent 2.2 for Sun Java System Web Server 7.0, the directory created is named sjsws_agent.

This agent-specific directory is the Policy Agent base directory, referred to throughout this guide as the PolicyAgent-base directory. For the full path to the PolicyAgent-base directory, see Example 2–17, which follows.

Example 2–17 Policy Agent Base Directory

The directory you choose in which to unpack the web agent binaries is referred to here as Agent-HomeDirectory. The following is the path to the PolicyAgent-base directory of Policy Agent 2.2 for Sun Java System Web Server 7.0:

Agent-HomeDirectory/web_agents/sjsws_agent

References in this book to the PolicyAgent-base directory are references to the preceding path.

Inside the Web Agent Base Directory in Policy Agent 2.2

After you finish installing an agent by issuing the agentadmin ---install command and interacting with the installer, you will need to access web agent files in order to configure and otherwise work with the product. Within the Policy Agent base directory are various subdirectories that contain all agent configuration and log files. The structure of the Policy Agent base directory for a web agent developed through the OpenSSO project is illustrated in Table 2–2.

The list that follows the table provides information about many of the items in the example Policy Agent base directory. The Policy Agent base directory is represented in code examples as PolicyAgent-base. The full path to any item in this directory is as follows:

PolicyAgent-base/item-name

where item-name represents the name of a file or subdirectory. For example, the full path to the bin directory is as follows:

PolicyAgent-base/bin

The preceding example of PolicyAgent-base lists files and directories you are likely to find in this directory. The notable items in this directory are summarized in the list that follows:

bin

This directory contains the agentadmin script for the agent bits. You will use this script a great deal. For details about the tasks performed with this script, see Introduction of the agentadmin Program in Web Agents for Policy Agent 2.2.

logs

This directory contains installation-related log files, for example log files created after you issue the agentadmin command.

Log information is stored in the installation log file after you install a web agent instance. The following is the location of this log file:

PolicyAgent-base/logs/audit/install.log

lib

The lib directory has a list of all the agent libraries that are used by the installer as well as the agent run time.

locale

This directory has all the agent installer information as well as agent run time specific locale information pertaining to the specific agent.

data

This directory has all the installer specific data.

---

Caution –

Do not edit any of the files in the data directory under any circumstance. If this directory or any of its content loses data integrity, the agentadmin program cannot function normally.

---

Agent_001

The full path for this directory is as follows:

PolicyAgent-base/AgentInstance-Dir

where AgentInstance-Dir refers to an agent instance directory, which in this case is Agent_001.

---

Note –

This directory does not exist until you successfully install the first instance of a web agent. Once you have successfully executed one run of the agentadmin --install command, an agent specific directory, Agent_00x is created in the Policy Agent base directory. This directory is uniquely tied to an instance of the deployment container, such as a web server instance. Depending on the number of times the agentadmin --install command is run, the number that replaces the x in the Agent_00x directory name will vary.

Furthermore, the string “Agent” in Agent_00x is configurable. You can change this string by editing the following file: PolicyAgent-base/config/AMToolsConfig.properties

---

After you successfully install the first instance of a web agent, an agent instance directory named Agent_001 appears in the Policy Agent base directory. The path to this directory is as follows:

PolicyAgent-base/Agent_001

The next installation of the agent creates an agent instance directory named Agent_002. The directories for uninstalled agents are not automatically removed. Therefore, if Agent_001 and Agent_002 are uninstalled, the next agent instance directory is Agent_003.

Agent instance directories contain directories named config and logs.

---

Note –

When a web agent is uninstalled, the config directory is removed from the agent instance directory but the logs directory still exists.

---

The following table is an example of the contents of an agent instance, such as Agent_001, directory.

Example of an Agent Instance (Agent_001) Directory
logs config

logs

Two subdirectories exist within this directory as follows:

audit

This directory contains the local audit trail for the agent instance.

debug

This directory has all the agent-specific debug information. When the agent runs in full debug mode, this directory stores all the debug files that are generated by the agent code.

config

This directory contains the web agent AMAgent.properties configuration file that is specific to the agent instance. Each web agent can be configured by a unique instance of the web agent AMAgent.properties configuration file. This file holds the key to the agent behavior at runtime.