test

Sun Java System Access Manager Policy Agent 2.2 Guide for BEA WebLogic Server/Portal 10

Chapter 3 Installing the Policy Agent for WebLogic Server/Portal 10

You install the Sun JavaTM System Access Manager Policy Agent 2.2 for WebLogic Server/Portal 10 from the command line using the agentadmin program. This chapter includes these sections:

Before reading this chapter or performing any of the tasks , considering reviewing Chapter 2, Vital Installation Information for a J2EE Agent in Policy Agent 2.2, since various key concepts are introduced in that chapter.

For more information about the tasks you can perform with the agentadmin program, see Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.

After you have successfully installed the agent, as described in this chapter, complete the post-installation tasks described in Chapter 4, Post-Installation Tasks for the WebLogic Server/Portal 10 Agent.

Choosing an Installation Environment: Cluster or Stand-Alone

Determine which type of installation you will perform and follow the instructions for that type of installation:

Installing the WebLogic Server/Portal 10 Agent in a Clustered Environment

If you are installing the agent for WebLogic Server/Portal 10 in a clustered environment, you must perform many of the steps explained in this chapter. However, see Chapter 5, Installing and Configuring the WebLogic Server/Portal 10 Agent in a Cluster. The installation and configuration of a clustered deployment is presented in that chapter combining specific tasks with generalized tasks. For the generalized tasks, you are directed to various locations in this guide to perform the more detailed steps required.

Installing the Agent for WebLogic Server/Portal 10 in a Stand-Alone Environment

Before describing any tasks, this chapter provides you with installation-related information specific to WebLogic Server/Portal 10. The subsequent sections lead you through the pre—installation and installation steps and describe how to view the installation log files. First, perform the pre-installation (preparation) steps. Then, perform the installation itself. The installation process has two phases. The first phase of the installation includes launching the installation program, which requires a directory to already have been selected for the agent files. The second phase of the installation involves interacting with the installation program. During this phase, the program prompts you step by step to enter information. Accompanying the prompts, are explanations of the type of information you need to enter. After you complete the installation, you can look at the installation log files.

Supported Platforms and Compatibility of Agent for WebLogic Server/Portal 10

The following sections provide information about the supported platforms of Policy Agent 2.2 for WebLogic Server/Portal 10 as well as the compatibility of this agent with Access Manager.

Platform and Version Support of Agent for WebLogic Server/Portal 10

The following table lists the platforms supported by the WebLogic Server/Portal 10 agent.

Table 3–1 Platform and Version Support for theWebLogic Server/Portal 10 Agent

Agent For 

Supported Policy Agent Version 

Supported Access Manager Versions 

Supported Platforms 

BEAWebLogic Server/Portal 10 

Supports: 

BEA WebLogic Server 10.0 

BEA WebLogic Portal 10.0 

Version 2.2 

Access Manager 6 2005Q1 (6.3) Patch 1 or greater 

Access Manager 7 2005Q4 

Access Manager 7.1 

SolarisTM Operating System (OS) for the SPARC® platform, versions 9 and 10

Solaris (OS) for x86 platforms, versions 9 and 10 

Red Hat Enterprise Linux Advanced Server 3.0 and 4.0 

Windows 2003, Enterprise Edition 

Compatibility of Agent for WebLogic Server/Portal 10 With Access Manager

Compatibility of Policy Agent 2.2 With Access Manager

All agents in the Policy Agent 2.2 release are compatible with Access Manager 7.1 and Access Manager 7.1. Compatibility applies to both Realm Mode and Legacy Mode.

Install the latest Access Manager patches to ensure that all enhancements and fixes are applied. For an example of Access Manager patches that can be installed, see the compatibility information in the Sun Java System Access Manager Policy Agent 2.2 Release Notes.

Compatibility of Policy Agent 2.2 With Access Manager 6 2005Q1 (6.3)

All agents in Policy Agent 2.2 are also compatible with Access Manager 6.3 Patch 1 or greater. However, certain limitations apply. For more information, see J2EE Agent Backward Compatibility With Access Manager 6.3.

Preparing to Install the WebLogic Server/Portal 10 Agent

The WebLogic Server/Portal 10 agent is available as a zip file named weblogic_v10_agent.zip.

First, create a directory where you plan to download the zip file. For example: Agent_Home.

After you download the file, unzip it using the appropriate utility or command for your platform. For example, on Solaris systems:

# cd Agent_Home
# unzip weblogic_v10_agent.zip

This guide uses PolicyAgent-base to refer to the files for the WebLogic Server/Portal 10 agent. For example, if you uzipped the file in the Agent_Home directory, PolicyAgent-base is:

Agent_Home/j2ee_agents/weblogic_v10_agent

Before you install the agent, follow the steps in the next section.

ProcedureTo Prepare to Install the WebLogic Server/Portal 10 Agent

  1. Ensure that the agent for WebLogic Server/Portal 10 is supported on the desired platform, as listed in Supported Platforms and Compatibility of Agent for WebLogic Server/Portal 10.

  2. Install WebLogic Server/Portal 10, if it is not already installed.

    For information about installing WebLogic Server 10 or WebLogic Portal 10, see the BEA product documentation at http://e-docs.bea.com/.

  3. Create a server or portal domain.

    Using the configuration or domain wizard appropriate for your server version and operating system, create a new stand-alone server domain. Typically, the configuration wizard launch script or program is located in the respective directory, as follows:

    • UNIX and Linux systems: DeployContainer-base/wlserver_10.0/common/bin/config.sh

    • Windows systems: DeployContainer-base\wlserver_10.0\common\bin\config.cmd

  4. Shut down the WebLogic Server/Portal 10 instance that will be protected by the agent.

  5. Create an agent profile in the Access Manager Console, if one has not already been created.

    For information, see Creating a J2EE Agent Profile.

    To install the agent, you must know the agent profile ID and password used to create the agent profile. You must enter the agent profile password in the next step, and you must enter the agent profile ID when installing the agent.

  6. Create an agent profile password file.

    An agent profile password file is a text file with only one line that contains the agent profile password. You will refer to this file during the agent installation process. Ensure that this file is located in a secure directory. With the agent profile password in this file, stored in a secure location, you do not need to enter sensitive information during the agent installation.

  7. Ensure that the ownership and group settings for the files in the PolicyAgent-base directory are correct.

    For information about the PolicyAgent-base directory, seeWebLogic Server/Portal 10 Agent Directory Structure.

    Often, installations are performed by a user with root permissions. In these cases, the potential problems discussed subsequently in this step would not apply.

    Therefore, if necessary, change the ownership of all the files in the PolicyAgent-base directory to the WebLogic Server/Portal 10 installation user and change the group associated with these files to the same group associated with the WebLogic Server/Portal 10 installation user.

    Caution – Caution –

    For the agent installation to be successful, the WebLogic Server/Portal 10 installation user must have write permissions to the files in the Policy Agent base directory. Furthermore, to help prevent permission problems, the ownership of all the files in the Policy Agent base directory should be changed to the WebLogic Server/Portal 10 installation user. Otherwise, permission-related issues might occur, which can be as serious as WebLogic Server/Portal 10 not starting.

Installing the WebLogic Server/Portal 10 Agent

ProcedureTo Install the WebLogic Server/Portal 10 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. 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 WebLogic Server/Portal 10 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.

    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 WebLogic Server/Portal 10

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 WebLogic Server/Portal 10 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 WebLogic Server/Portal 10 Agent

The following example shows a sample installation for the WebLogic Server/Portal 10 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 WebLogic Server/Portal 10 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 BEA WebLogic 10.0 Platform.
If the Policy Agent is used with Federation Manager services, User needs to
enter information relevant to Federation Manager.
************************************************************************

Enter the path to the location of the script used to start the WebLogic domain. 
Please ensure that the agent is first installed on the admin server instance 
before installing on any managed server instance.
[ ? : Help, ! : Exit ]
Enter the Startup script location
[/usr/local/bea/user_projects/domains/mydomain/startWebLogic.sh]: 
/usr/local/bea/user_projects/domains/serverdomain/startWebLogic.sh
Enter the name of the WebLogic Server/Portal instance secured by the
agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the WebLogic Server/Portal instance name [myserver]: 


Enter the fully qualified host name of the server where Access Manager
Services are installed.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Host:  amhost.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]: 
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:  agenthost.example.com


Enter the WebLogic home directory
[ ? : Help, < : Back, ! : Exit ]
Enter the WebLogic home directory [/usr/local/bea/wlserver_10.0]:


Enter true if the agent is being installed on a Portal domain
[ ? : Help, < : Back, ! : Exit ]
Is the agent being installed on a Portal domain ? [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]:  7001


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]: 


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 [KpsVJMr84cwd6OATx+UgLWHSCB8KWFVW]:

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 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 OF YOUR RESPONSES
-----------------------------------------------
Startup script location :
/usr/local/bea/user_projects/domains/mydomain/startWebLogic.sh
WebLogic domain name : myserver
Access Manager Services Host : amhost.example.com
Access Manager Services Port : 58080
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : agenthost.example.com
WebLogic home directory : /usr/local/bea/wlserver_10.0
Agent Installed on Portal domain : false
Application Server Instance Port number : 7001
Protocol for Application Server instance : http
Deployment URI for the Agent Application : /agentapp
Encryption Key : KPsVJMr84cwd6OATx+UgLWHSCB8KWFVW
Agent Profile name : exampleagent
Agent Profile Password file name : /export/temp/passwordfile
Agent and Access Manager on same application server instance : false

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 WebLogic Server/Portal 10 Agent.

Information regarding the location of the J2EE agent base directory is explained in detail in WebLogic Server/Portal 10 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:

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 WebLogic Server/Portal 10 Agent

The following sections refer to specific deployment scenarios involving the WebLogic Server/Portal 10 agent. These scenarios can affect how you respond to prompts during the installation process.

Installing the Agent on Multiple WebLogic Server/Portal 10 Instances on the Same Domain

Once the agent is installed for a particular domain configuration directory, you can install the agent on more than one WebLogic Server/Portal 10 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 the Agent on a Different WebLogic Server/Portal 10 Domain

Caution – Caution –

Once the agent is installed for a specific domain, the agent binaries cannot be used on that same installation for a different WebLogic Server/Portal 10 domain. If you attempt to use previously installed agent binaries on the same installation, but on a different domain, the installation fails.

J2EE agents associate a specific set of agent binaries with a particular domain for WebLogic Server/Portal 10. 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 WebLogic Server/Portal 10 Agent on the Access Manager Web Container

Currently, BEA WebLogic Server/Portal 10 is not a supported web container for Access Manager. Therefore, do not install the WebLogic Server/Portal 10 agent and Access Manager on the same WebLogic Server/Portal 10 instance. 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]: