Chapter 3 Installing the IBM WebSphere Portal Server 6.0 Policy Agent

Sun Java^TM System Access Manager Policy Agent 2.2 for IBM WebSphere Portal Server 6.0, as with all J2EE agents in the 2.2 release of Policy Agent, is installed from the command line using the agentadmin program.

This chapter is organized into the following sections:

• Installation Related Information for the IBM WebSphere Portal Server 6.0 Agent

• Preparing to Install the IBM WebSphere Portal Server 6.0 Agent

• Launching the Installation Program for the IBM WebSphere Portal Server 6.0 Agent

• Using the Installation Program for the IBM WebSphere Portal Server 6.0 Agent

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.

When installing the agent for IBM WebSphere Portal Server 6.0, you must run the agent installation program on every instance of the underlying IBM WebSphere Application Server. Typically, this includes two instances: the default instance, often named server1, and the IBM WebSphere Portal Server instance, often named WebSphere_Portal. This type of deployment is necessary since the security configuration in IBM WebSphere Application Server has global scope and cannot be performed independently for any particular instance of the server.

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

Once you have completed the steps described in this chapter, complete the applicable post-installation tasks described in Chapter 4, Post-Installation Tasks for the IBM WebSphere Portal Server 6.0 Policy Agent.

Installation Related Information for the IBM WebSphere Portal Server 6.0 Agent

The following sections provide important information about Policy Agent 2.2 for IBM WebSphere Portal Server 6.0 required before you install the agent.

Supported Platforms and Compatibility for the IBM WebSphere Portal Server 6.0 Agent

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

• Platform and Version Support for the IBM WebSphere Portal Server 6.0 Agent

• Compatibility of the IBM WebSphere Portal Server 6.0 Agent With Access Manager

Platform and Version Support for the IBM WebSphere Portal Server 6.0 Agent

The following table shows the platforms supported for the IBM WebSphere Portal Server 6.0 agent.

Compatibility of the IBM WebSphere Portal Server 6.0 Agent With Access Manager

• Compatibility With Access Manager 7.1 and Access Manager 7 2005Q4

• Compatibility With Access Manager 6 2005Q1 (6.3)

Compatibility With Access Manager 7.1 and Access Manager 7 2005Q4

All agents in the Policy Agent 2.2 release are compatible with both Access Manager 7.1 and Access Manager 7 2005Q4. Compatibility applies to both of the available modes of Access Manager: Realm Mode and Legacy Mode.

Install the latest Access Manager 7.1 or Access Manager 7 2005Q4 patches to ensure that all enhancements and fixes are applied. For information, see the compatibility information discussed in Sun Java System Access Manager Policy Agent 2.2 Release Notes.

Compatibility 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 2005Q1 (6.3).

Preparing to Install the IBM WebSphere Portal Server 6.0 Agent

The IBM WebSphere Portal Server 6.0 agent is available as a zip file named websphere_v60portal_agent.zip.

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

Download and unzip the file using the appropriate utility or command for your platform. For example, on Solaris systems:

# cd Agent_Home
# unzip websphere_v60portal_agent.zip

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

Agent_Home/j2ee_agents/websphere_v60portal_agent

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

To Prepare to Install the IBM WebSphere Portal Server 6.0 Agent

1. Ensure that the IBM WebSphere Portal Server 6.0 agent is supported on the desired platform, as listed in Supported Platforms and Compatibility for the IBM WebSphere Portal Server 6.0 Agent.

2. Install IBM WebSphere Portal Server 6.0 if not already installed.

   For information about the IBM WebSphere Portal Server 6.0 software, see http://www.ibm.com.

3. (Conditional) If the IBM WebSphere Portal Server 6.0 instance or the underlying IBM WebSphere Application Server instance on which you are about to install the agent is running, shut it down.

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

   For more information, see Creating a J2EE Agent Profile.

   To avoid a misconfiguration of the agent, ensure that you know the user ID and password used to create the agent profile. You must enter the agent profile password correctly in the next step, and you must enter the agent profile ID correctly when you install the agent.

5. Create a agent password file and add the agent profile password to that file.

   A valid password file can have only one line that contains the agent profile password. Ensure that this file is located in a secure directory. You will refer to this file during the agent installation process.

   With the agent profile password file stored in a secure location, you are not required to enter sensitive information during the installation.

Launching the Installation Program for the IBM WebSphere Portal Server 6.0 Agent

After you have performed all the pre-installation steps, you are ready to launch the installation program, as described in the following section.

To Launch the Installation Program for the IBM WebSphere Portal Server 6.0 Agent

1. Change to the following directory:

   PolicyAgent-base/bin

   This directory contains the agentadmin program for UNIX and Linux systems and the agentadmin.bat program for Windows systems. These programs are used for installing and uninstalling an agent as well as for performing other agent tasks. For more information, see Key Features and Tasks Performed With the J2EE agentadmin Program.

2. Issue the agentadmin command. For example on Solaris systems:

   ./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 agentadmin program will end.

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

Using the Installation Program for the IBM WebSphere Portal Server 6.0 Agent

When installing the IBM WebSphere Portal Server 6.0 agent, you must run the agent installation program on every instance of the underlying IBM WebSphere Application Server. Typically, this includes two instances: the default instance, often named server1, and the IBM WebSphere Portal Server instance, often named WebSphere_Portal. This type of deployment is necessary since the security configuration in IBM WebSphere Application Server has global scope and cannot be performed independently for any particular instance of the server.

After you issue the agentadmin command and accept the license agreement (if necessary) the installation program prompts you for information.

The steps in the installation program are displayed in this section in an example interaction. Your answers to prompts can differ slightly or greatly from this example depending upon your site's 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.

The following bulleted list provides key points about the installation program.

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

About Installation Prompts for the IBM WebSphere Portal Server 6.0 Agent

The following list provides information about specific prompts in the installation. Often the prompt is self explanatory. However, at other times you might find the extra information presented here to be very helpful. This extra information is often not obvious. Study this section carefully before issuing the agentadmin --install command.

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 one 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 IBM WebSphere Portal Server 6.0 Agent. For the actual information on creating an agent profile, see Creating a J2EE Agent Profile.

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 Password File

The J2EE password file should have been created as a pre-installation step. For the pre-installation steps, see Preparing to Install the IBM WebSphere Portal Server 6.0 Agent.

When the installation program prompts you for the password for the agent, enter the fully qualified path to this password file.

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. You might be prompted for this name during the configuration process.

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.

Example of Installation Program Interaction for the IBM WebSphere Portal Server 6.0 Agent

The following example is a sample installation for IBM WebSphere Portal Server 6.0. By no means does this sample represent a real deployment scenario.

The section following this example, Implications of Specific Deployment Scenarios for the IBM WebSphere Portal Server 6.0 Agent, explains specific deployment scenarios, such as installing the agent on multiple IBM WebSphere Portal Server 6.0 instances. If any of these deployment scenarios apply to your site's deployment, you might be required 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. Those explanations are divided into subsections as follows:

• Installing the Agent on Multiple IBM WebSphere Portal Server 6.0 Instances

You must install the agent on every instance of the underlying IBM WebSphere Application Server.

The following example shows a sample run of the the installation of the IBM WebSphere Portal Server 6.0 agent, where WebSphereServer-instance-name represents the WebSphere Server instance name. The default instance is often named server1 and the IBM WebSphere Portal Server instance is often named WebSphere_Portal.

************************************************************************
************************************************************************
Welcome to the Access Manager Policy Agent for IBM WebSphere Portal Server
6.0 Agent. If the Policy Agent is used with Federation Manager services,
User needs to enter information relevant to Federation Manager.

Enter the fully qualified path to the configuration directory of the Server
Instance for the WebSphere node. Please ensure that the installer is run on
the WebSphere instance that will host the WebSphere Administration Console
first before the installer is run on the WebSphere Portal instance.
[ ? : Help, ! : Exit ]
Enter the Instance Config Directory
[/opt/IBM/WebSphere/AppServer/profiles/wp_profile/config/cells/cell01/
nodes/node01/servers/WebSphereServer-instance-name]: 

Enter the Server/Portal Instance name.
[ ? : Help, < : Back, ! : Exit ]
Enter the Server/Portal Instance name [WebSphereServer-instance-name]:

Enter the WebSphere Install Root directory.
[ ? : Help, < : Back, ! : Exit ]
Enter the WebSphere Install Root directory [/opt/IBM/WebSphere/AppServer]: 

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

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: wpshost.example.com

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

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 [r2s+z4TxPsSwBLe/FbncKrwzVudy+nU5]:

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

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: /tmp/password.txt

-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Instance Config Directory :
/opt/IBM/WebSphere/AppServer/profiles/wp_profile/config/cells/cell01/
nodes/node01/servers/WebSphereServer-instance-name]: 
Instance Server/Portal name : WebSphereServer-instance-name
WebSphere Install Root Directory : /opt/IBM/WebSphere/AppServer
Access Manager Services Host : amhost.example.com
Access Manager Services Port : 80
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : wpshost.example.com
Application Server Instance Port number : 80
Protocol for Application Server instance : http
Deployment URI for the Agent Application : /agentapp
Encryption Key : r2s+z4TxPsSwBLe/FbncKrwzVudy+nU5
Agent Profile name : wpsagent
Agent Profile Password file name : /tmp/password.txt

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

Copy agent.jar,famclientsdk.jar to
/opt/IBM/WebSphere/AppServer/lib/ext...DONE.
Creating directory layout and configuring AMAgent.properties file for
Agent_001 instance ...DONE.

Reading data from file /tmp/password.txt and encrypting it ...DONE.

Generating audit log file name ...DONE.

Creating tag swapped AMAgent.properties file for instance Agent_001 ...DONE.

Creating a backup for file
/opt/IBM/WebSphere/AppServer/profiles/wp_profile/config/cells/cell01/
nodes/node01/servers/WebSphereServer-instance-name/server.xml
...DONE.

Configure server.xml file
/opt/IBM/WebSphere/AppServer/profiles/wp_profile/config/cells/cell01/
nodes/node01/servers/WebSphereServer-instance-name/server.xml...DONE.

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

Install log file location:
/opt/j2ee_agents/websphere_v60portal_agent/logs/audit/install.log

Thank you for using Access Manager Policy Agent

Implications of Specific Deployment Scenarios for the IBM WebSphere Portal Server 6.0 Agent

The following sections refer to specific deployment scenarios involving Policy Agent 2.2 for IBM WebSphere Portal Server 6.0. These scenarios are likely to affect how you respond to prompts during the installation process. You might also be required to perform additional configurations.

Installing the Agent on Multiple IBM WebSphere Portal Server 6.0 Instances

Once the agent is installed for a particular IBM WebSphere Portal Server 6.0 instance, you can install the agent on another instance on the same machine by running the agentadmin --install command. Once prompted to enter the appropriate server instance name, enter the server configuration directory and unique instance name that will enable the agent to distinguish the first instance from consecutive instances.

Summary of the Agent Installation

At the end of the installation process, the installation program prints the status of the installation along with the installed J2EE agent information. The information that the program displays can be very useful. For example, the program displays the agent instance name, which is required 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 IBM WebSphere Portal Server 6.0 Policy Agent.

The location of directories displayed by the installer are specific. However, throughout this guide and specifically in Summary of Agent Installation shown in this section, PolicyAgent-base is used to describe the directory where the distribution files are stored for a specific J2EE agent.

The following example serves as a quick description of the location of the J2EE agent base directory (PolicyAgent-base) of Policy Agent 2.2 for IBM WebSphere Portal Server 6.0.

Example 3–1 Policy Agent Base Directory for the IBM WebSphere Portal Server 6.0 Agent

The following directory represents PolicyAgent-base for the IBM WebSphere Portal Server 6.0 agent:

Agent_Home/j2ee_agents/am_wps_agent

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

Information regarding the location of the J2EE agent base directory is explained in detail in Location of the J2EE Agent Base Directory in Policy Agent 2.2.

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 Agent_001. Those directories and files are briefly described in the following paragraphs.

PolicyAgent-base/Agent_001/config/AMAgent.properties

Location of the 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.