Installing the Application Server 8.2/9.0/9.1 Agent

To Install the Application Server 8.2/9.0/9.1 Agent

1. Change to the following directory:

   PolicyAgent-base/bin

   This directory contains the agentadmin program, which is used to install a J2EE agent and for performing other tasks. For more information on the agentadmin program, see Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.

2. Issue the following command:

   ./agentadmin --install

3. (Conditional) If you receive license agreement information, accept or reject the agreement prompts. If you reject any portion of the agreement, the program will end.

   The license agreement is displayed only during the first run of the agentadmin program.

4. After you accept the license agreement (if necessary), provide the information requested by the installation program (or accept the default values).

   The prompts are shown in the Example of Installation Program Interaction for the Application Server 8.2/9.0/9.1 Agent.

   Your answers to prompts can differ from this example depending upon your specific deployment. In the example, most of the defaults have been accepted. This example is provided for your reference and does not necessarily indicate the precise information you should enter.

   Key points about the installation program to consider include.

   • Each step in the installation program includes an explanation that is followed by a more succinct prompt.

   • For most of the steps you can type any of the following characters to get the results described:

     ?

     Type the question mark to display Help information for that specific step.

     <

     Type the left arrow symbol to go back to the previous interaction.

     !

     Type the exclamation point to exit the program.

   • Most of the steps provide a default value that can be accepted or replaced. If a default value is correct for your site, accept it. If it is not correct, enter the correct value.

5. After you have completed all the steps, a summary of your responses appears followed by options that allow you to navigate through those responses to accept or reject them.

   When the summary appears, note the agent instance name, such as Agent_001.password file

   About the options, the default option is 1, Continue with Installation.

   • If you are satisfied with the summary, choose 1 (the default).

   • If you want to edit input from the last interaction, choose 2.

   • If you want to edit input starting at the beginning of the installation program, choose 3.

   • If you want to exit the installation program without installing, choose 4.

   You can edit your responses as necessary, return to the options list, and choose option 1 to finally process your responses.

About Installation Prompts in Agent for Application Server 8.2/9.0/9.1

The following list provides information about specific prompts in the installation:

Deployment URI for the Agent Application

The deployment URI for the agent application is required for the agent to perform necessary housekeeping tasks such as registering policy and session notifications, legacy browser support, and CDSSO support. Accept /agentapp as the default value for this interaction. Once the installation is completed, browse the directory PolicyAgent-base/etc. Use the agentapp.war file to deploy the agent application in the application container. Please note that the deployment URI for agent application during install time should match the deployment URI for the same application when deployed in the J2EE container.

Encryption Key

This key is used to encrypt sensitive information such the passwords. The key should be at least 12 characters long. A key is generated randomly and provided as the default. You can accept the random key generated by the installer or create your own using the .agentadmin --getEncryptKey command.

For information about creating a new encryption key, see agentadmin --getEncryptKey.

Agent Profile Name

An agent profile should have been created as a pre-installation step. The creation of the agent profile is mentioned in that section. For the pre-installation steps, see Preparing to Install the Application Server 8.2/9.0/9.1 Agent.

In summary, the J2EE agent communicates with Access Manager with a specific ID and password created through an agent profile using Access Manager Console. For J2EE agents, the creation of an agent profile is mandatory. Access Manager uses the agent profile to authenticate an agent. This is part of the security infrastructure.

Agent Profile Password File

The Agent Profile password file should have been created as a pre-installation step. When the installation program prompts you for the password for the agent, enter the fully qualified path to this password file.

Example of Installation Program Interaction for the Application Server 8.2/9.0/9.1 Agent

The following example shows a sample installation for the Application Server 8.2/9.0/9.1 agent.

This sample represents an installation that is not on a remote server instance host. Installations on remote server instance hosts receive two additional prompts that are not present in this example. The section following this example, Implications of Specific Deployment Scenarios for the Application Server 8.2/9.0/9.1 Agent, explains specific deployment scenarios, such as for remote servers. If any of these deployment scenarios apply to your deployment, you might need to respond to prompts in a specified manner during the installation as explained in that section. Review the explanations in that section before proceeding with the installation.

************************************************************************
Welcome to the Access Manager Policy Agent for Sun Java(TM) Application Server 8.1/8.2/9.0/9.1
************************************************************************
Enter the complete path to the directory which is used by Application Server to store 
its configuration Files. This directory uniquely identifies the Application Server 
instance that will be secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the Application Server Config Directory Path
[/var/opt/SUNWappserver/domains/domain1/config]:

Enter the name of the Application Server instance that will be secured by this Agent .
[ ? : Help, < : Back, ! : Exit ]
Enter the Application Server Instance name [server]:

Enter the fully qualified host name of the server where Access Manager Services are 
installed.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Host: subcompany22.company22.example.com

Enter the port number of the Server that runs Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services port [80]: 58080

Enter http/https to specify the protocol used by the Server that runs Access Manager 
services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Protocol [http]: http

Enter the Deployment URI for Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Deployment URI [/amserver]:

Enter the fully qualified host name on which the Application Server protected by the agent 
is installed.
 [ ? : Help, < : Back, ! : Exit ]
Enter the Agent Host name: employee.company22.example.com

Enable this field only when the agent is being installed on a remote server
instance host.
[ ? : Help, < : Back, ! : Exit ]
Is Domain administration server host remote ? [false]:

Enter the preferred port number on which the application server provides its services.
 [ ? : Help, < : Back, ! : Exit ]
Enter the port number for Application Server instance [80]: 8080

Select http or https to specify the protocol used by the Application server instance that 
will be protected by Access Manager Policy Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the Preferred Protocol for Application Server instance [http]: http

Enter the deployment URI for the Agent Application. This Application is used by the agent 
for internal housekeeping.
[ ? : Help, < : Back, ! : Exit ]
Enter the Deployment URI for the Agent Application [/agentapp]: :

Enter a valid Encryption Key.
[ ? : Help, < : Back, ! : Exit ]
Enter the Encryption Key [sLK2JGqkJdFYArPYH6v2Md+HTKKmkif7JD]:

Enter a valid Agent profile name. Before proceeding with the agent 
installation, please ensure that a  valid Agent profile exists in Access 
Manager.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: exampleagent

Enter the path to a file that contains the password to be used for identifying the Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the path to the password file: /export/temp/passwordfile

Enter true only if agent is being installed on a remote instance from the
Domain Administration server host.
[ ? : Help, < : Back, ! : Exit ]
Is the agent being installed on the DAS host for a remote instance ? [false]:

Enter true if the Agent is being installed on the same instance of Application
Server on which Access Manager is deployed. Enter false if that is not the
case.
[ ? : Help, < : Back, ! : Exit ]
Are the Agent and Access Manager installed on the same instance of
Application Server ? [false]:


*********************************************************
SUMMARY OR YOUR RESPONSES
*********************************************************

Application Server Config Directory :
/var/opt/SUNWappserver/domains/domain1/config
Application Server Instance name : server
Access Manager Services Host : subcompany22.company22.example.com
Access Manager Services Port : 58080
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : employee.company22.example.com
Application Server Instance Port number : 8080
Protocol for Application Server instance : http
Deployment URI for the Agent Application. : /agentapp
Encryption Key : sLK2JGqkJdFYArPYH6v2Md+HTKKmkif7JD
Agent Profile name : exampleagent
Agent Profile Password file name : /export/temp/passwordfile

Verify your settings above and decide from the choices below.
1. Continue with Installation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:

Summary of a J2EE Agent Installation in Policy Agent 2.2

At the end of the installation process, the installation program prints the status of the installation along with the installed agent information. The information that the program displays can be very useful. For example, the program displays the agent instance name, which is needed when configuring a remote instance. The program also displays the location of specific files, which can be of great importance. In fact, you might want to view the installation log file once the installation is complete, before performing the post-installation steps as described in Chapter 4, Post-Installation Tasks for the Application Server 8.2/9.0/9.1 Agent.

Example 3–1 Policy Agent Base Directory of Agent for Application Server 8.2/9.0/9.1

The following directory represents PolicyAgent-base of Agent for Application Server 8.2/9.0/9.1:

Agent_Home/j2ee_agents/appserver_v9_agent

where Agent_Home is the directory where you unzipped the agent zip file.

Information regarding the location of the J2EE agent base directory is explained in detail in Application Server 8.2/9.0/9.1 Agent PolicyAgent-base Directory.

The following type of information is printed by the installer:

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Configuration file location:
PolicyAgent-base/Agent_001/config/AMAgent.properties
Agent Audit directory location:
PolicyAgent-base/Agent_001/logs/audit
Agent Debug directory location:
PolicyAgent-base/Agent_001/logs/debug

Install log file location:
PolicyAgent-base/logs/audit/install.log

Thank you for using Access Manager Policy Agent

Once the agent is installed, the directories shown in the preceding example are created in the Agent_00x directory, which for this example is specifically Agent_001. Those directories and files are briefly described in the following paragraphs.

PolicyAgent-base/Agent_001/config/AMAgent.properties

Location of the J2EE agent AMAgent.properties configuration file for the agent instance. Every instance of a J2EE agent has a unique copy of this file. You can configure this file to meet your site's requirements. For more information, see the following sections:

• Appendix B, J2EE Agent AMAgent.properties Configuration File in Policy Agent 2.2

• Key Features and Tasks Performed With the J2EE AMAgent.properties Configuration File

PolicyAgent-base/Agent_001/logs/audit

Location of the J2EE agent local audit trail.

PolicyAgent-base/Agent_001/logs/debug

Location of all debug files required to debug an agent installation or configuration issue.

PolicyAgent-base/logs/audit/install.log

Location of the file that has the agent install file location. If the installation failed for any reason, you can look at this file to diagnose the issue.

Implications of Specific Deployment Scenarios for the Application Server 8.2/9.0/9.1 Agent

The following sections refer to specific deployment scenarios involving the Application Server 8.2/9.0/9.1 agent. These scenarios can affect how you respond to prompts during the installation process.

• Installing an Application Server 8.2/9.0/9.1 Agent on Multiple Application Server 8.2/9.0/9.1 Instances

• Installing an Application Server 8.2/9.0/9.1 Agent on a Different Server Domain

• Installing the Application Server 8.2/9.0/9.1 Agent on a Remote Application Server 8.2/9.0/9.1 Instance

• Installing the Application Server 8.2/9.0/9.1 Agent on the Access Manager Web Container

Installing an Application Server 8.2/9.0/9.1 Agent on Multiple Application Server 8.2/9.0/9.1 Instances

Once a J2EE agent is installed for a particular domain configuration directory, you can install the agent on more than one Application Server 8.2/9.0/9.1 instance associated with the same domain by running the agentadmin --install command. Once prompted to enter the appropriate server instance name, enter the domain configuration directory and unique instance name that will enable the agent to distinguish the first instance from consecutive instances.

Installing an Application Server 8.2/9.0/9.1 Agent on a Different Server Domain

Once a J2EE agent is installed for a specific domain, the J2EE agent binaries cannot be used on that same Application Server installation for a different Application Server 8.2/9.0/9.1 domain. If you attempt to use previously installed J2EE agent binaries on the same Application Server installation, but on a different domain, the installation fails.

J2EE agents associate a specific set of agent binaries with a particular domain for Application Server 8.2/9.0/9.1. If you want to install a J2EE agent on a different domain, unzip a new set of bits and copy them to a separate location before running the agentadmin --install command for the second domain.

Installing the Application Server 8.2/9.0/9.1 Agent on a Remote Application Server 8.2/9.0/9.1 Instance

The agent installation for each remote Sun Java System Application Sever 9/9.1 instance requires one installation run on the remote host and one configuration run for the remote agent on the DAS host. The following installation steps are based on the assumption that the remote instance has been set up correctly.

For information about installing the agent, see Installing the Application Server 8.2/9.0/9.1 Agent.

To Install the Application Server 8.2/9.0/9.1 Agent on a Remote Application Server 8.2/9.0/9.1 Instance

Before You Begin

Shutdown both the DAS domain and remote server instance before installing the Application Server 8.2/9.0/9.1 agent.

1. Install the Application Server 8.2/9.0/9.1 agent on the remote server instance host.

   During installation, answer the following questions as indicated:

   Enable this field only when the agent is being installed on a remote server 
   instance host.
   [ ? : Help, < : Back, ! : Exit ]
   Is Domain administration server host remote ? [false]: true

   Enter true only if agent is being installed on a remote instance from the
   Domain Administration server host.
   [ ? : Help, < : Back, ! : Exit ]
   Is the agent being installed on the DAS host for a remote instance ? [false]: false

2. Install the Application Server 8.2/9.0/9.1 agent on the DAS host for the same remote server instance.

   During installation, answer the following questions as indicated:

   Enable this field only when the agent is being installed on a remote server 
   instance host.
   [ ? : Help, < : Back, ! : Exit ]
   Is Domain administration server host remote ? [false]: false

   Enter true only if agent is being installed on a remote instance from the
   Domain Administration server host.
   [ ? : Help, < : Back, ! : Exit ]
   Is the agent being installed on the DAS host for a remote instance ? [false]: true

   The following two questions are asked only when the answer to the previous question is true:

   Enter the value of the agent instance name provided by the agent installation 
   on the remote instance.
   [ ? : Help, < : Back, ! : Exit ]
   Agent instance name []: Agent_001

   Note: Agent_001 is the agent instance name generated in Step 1 for the remote server instance. The agent installation generates an agent instance name, which is displayed at the end of installation and is available in the install log. The instance name must be valid.

   Enter the value of the agent install directory on the remote instance host.
   [ ? : Help, < : Back, ! : Exit ]
   Agent install directory on remote instance host
   [/opt/j2ee_agents/am_as81_agent]:

   Enter the directory where the agent has been installed on the remote server instance host. This is the agent binary directory on the remote server instance host instead of the agent binary directory on DAS host.

3. Edit the following files to allow the agent to work on the remote server instance:

   1. On the DAS host, edit the DAS domain's domain.xml file.

      For example: /var/opt/SUNWappserver/domains/domain1/config/domain.xml

      In the domain.xml file, find and change the following text:

      <jvm-options>
      -Djava.util.logging.config.file=agent-deploy-directory-on-DAS-host
      /j2ee_agents/appserver_v9_agent/config/AMAgentLogConfig.properties
      </jvm-options>

      to

      <jvm-options>
       -Djava.util.logging.config.file=
      agent-deploy-directory-on-remote-server-instance-host/j2ee_agents/appserver_v9_agent
      /config/AMAgentLogConfig.properties
      </jvm-options>

   2. On the DAS host, edit the DAS domain's server.policy file.

      For example: /var/opt/SUNWappserver/domains/domain1/config/server.policy

      In the server.policy file, find and change the following text:

      grant codeBase "file:agent-deploy-directory-on-DAS-host
      /j2ee_agents/appserver_v9_agent/lib/*" {
             permission java.security.AllPermission;
      };

      to

      grant codeBase "file:agent-deploy-directory-on-remote-server-instance-host
      /j2ee_agents/appserver_v9_agent/lib/*" {
             permission java.security.AllPermission;
      };

4. Start the DAS domain and remote server instance.

Installing the Application Server 8.2/9.0/9.1 Agent on the Access Manager Web Container

The Application Server 8.2/9.0/9.1 agent and Access Manager should not be installed on the same Application Server 8.2/9.0/9.1 instance. Therefore, when you install the agent, always choose false (the default) for the following question:

Enter true if the Agent is being installed on the same instance of Application
Server on which Access Manager is deployed. Enter false if that is not the
case.
[ ? : Help, < : Back, ! : Exit ]
Are the Agent and Access Manager installed on the same instance of
Application Server ? [false]: