Sun Java System Access Manager Policy Agent 2.2 Guide for JBoss Application Server 4.0

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

Location of the J2EE Agent Base Directory in Policy Agent 2.2

Unpacking the J2EE agent binaries creates a directory named j2ee_agents, within which an agent-specific directory is created. For example, if the J2EE agent being installed is Policy Agent 2.2 for Sun Java System Application Server 8.1, the directory created is named am_as81_agent. For other J2EE agents, the directory name is slightly different, but the naming format is the same. To see the preceding directory name specific to your J2EE agent, see Example 3–5.

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–23. For information about choosing a directory in which to unpack the J2EE agent binaries, see To Unpack Non-Package Formatted Deliverables of a J2EE Agent in Policy Agent 2.2.


Example 2–23 Policy Agent Base Directory

The directory you choose in which to unpack the J2EE agent binaries is referred to here as Agent-HomeDirectory. The following path is an example of the location for the PolicyAgent-base directory of Policy Agent 2.2 for Sun Java System Application Server 8.1:


Agent-HomeDirectory/j2ee_agents/am_as81_agent

For other J2EE agents, the directory names are different, but the naming format is the same. To see the preceding path name specific to your J2EE agent, see Example 3–5. References in this book to the PolicyAgent-base directory are references to the preceding path.


Inside the J2EE 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 J2EE 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 J2EE agent 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
Table 2–2 Example of Policy Agent Base Directory for a J2EE Agent

Directory Contents: Files and Subdirectories 

LICENSE.TXT

jce

README.TXT

jsse

THIRDPARTYLICENSEREADME.TXT

lib

bin

locale

config

logs

data

sampleapp

etc

agent_001

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:

sampleapp

This directory contains the sample application included with Policy Agent 2.2. This application is extremely useful. Not only does it demonstrate configuration options and features, but the application can be used to test if an agent is running.

Use the sample application that comes with the agent or build the application from scratch. Find instructions for building, deploying, and running this application at the following location:

PolicyAgent-base/sampleapp/readme.txt

The full path to the sample application is as follows:

PolicyAgent-base/sampleapp/dist/agentsample.ear

For more information about the sample application, see The Sample Application.

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 Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.

etc

This directory contains the agent application (agentapp.war) file, which is deployed during the agent installation. This application helps the agent perform certain housekeeping tasks.

logs

This directory contains various log files, including log files created when you issue the agentadmin command.

This directory also contains the installation log file. For the 2.2 release of Policy Agent, log information is stored in the installation log file after you install a J2EE 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 – 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 J2EE 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 an application 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.


After you successfully install the first instance of a J2EE 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 J2EE 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.


Note –

Agent-specific debug information is not stored in this directory when the J2EE agent and Access Manager are installed on the same deployment container. However, the J2EE agent and Access Manager must both support the same deployment container for this coexistence scenario to apply. When this coexistence applies, the debug information is stored in the following Access Manager directory:


/var/opt/SUNWam/debug

config

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