test

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

Chapter 3 Installing Policy Agent 2.2 for JBoss Application Server 4.0

Sun JavaTM System Access Manager Policy Agent 2.2 for JBoss Application Server 4.0, as with all J2EE agents in the 2.2 release of Policy Agent, is installed from the command line using the agentadmin program. 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.

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, because various key concepts are introduced in that chapter.

This chapter is organized into the following sections:

Before describing any task, this chapter provides you with installation-related information specific to JBoss Application Server 4.0. 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.

Once you have completed the steps described in this chapter, complete the applicable post-installation tasks described in Chapter 4, Post-Installation Tasks of Policy Agent 2.2 for JBoss Application Server 4.0.

Installation Related Information About Agent for JBoss Application Server 4.0

The following sections provide important information about Policy Agent 2.2 for JBoss Application Server 4.0 needed before you install the agent.

Supported Platforms and Compatibility of Agent for JBoss Application Server 4.0

The following sections provide information about the supported platforms of Policy Agent 2.2 for JBoss Application Server 4.0 as well as the compatibility of this agent with Access Manager.

Platform and Version Support of Agent for JBoss Application Server 4.0

The following table presents the platforms supported by Policy Agent 2.2 for JBoss Application Server 4.0.

Table 3–1 Platform and Version Support of Agent for JBoss Application Server 4.0

Agent for 

Supported Policy Agent Version 

Supported Access Manager Versions 

Supported Platforms 

JBoss Application Server 4.0 

Note: This agent is supported on JBoss Application Server 3.2.5 through 4.0.5

Version 2.2 

Version 6.3 Patch 1 or greater 

Version 7 

Version 7.1 

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

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

Red Hat Enterprise Linux Advanced Server 3 and 4 (32–bit and 64–bit) 

Windows 2003, Enterprise Edition 

Windows 2003, Standard Edition 

Compatibility of Agent for JBoss Application Server 4.0 With Access Manager

Compatibility of Policy Agent 2.2 With Access Manager 7 and Access Manager 7.1.

All agents in the Policy Agent 2.2 release are compatible with Access Manager 7 and Access Manager 7.1. Compatibility applies to both of the available modes of Access Manager: 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 discussed in Sun Java System Access Manager Policy Agent 2.2 Release Notes.

Compatibility of Policy Agent 2.2 With Access Manager 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.

JBoss Application Server 4.0 Agent Installation Functions

The agentadmin program performs the following functions during the installation of the agent for JBoss Application Server 4.0:

Preparing to Install Agent for JBoss Application Server 4.0

Detailed information about unpacking the distribution files for J2EE agents in Policy Agent 2.2 is covered in Chapter 2, Vital Installation Information for a J2EE Agent in Policy Agent 2.2. The best practice is to follow the detailed steps outlined in that chapter before you implement any steps outlined in this chapter.

The following examples provide quick details about the unpacking process. Furthermore, this section provides the opportunity to present again the cautionary note that follows about the GNU_tar program.

Caution – Caution –

For .tar.gz archives, do not use a program other than GNU_tar to untar the contents of the J2EE agent deliverables. Using a different program, such as another tar program, can result in some files not being extracted properly. To learn more about the GNU_tar program, visit the following web site:

http://www.gnu.org/software/tar/tar.html

Example 3–1 Format of the Distribution Files of Agent for JBoss Application Server 4.0

SJS_JBoss_4.0_Server_agent_2.2.tar.gz
SJS_JBoss_4.0_Server_agent_2.2.zip
SJS_JBoss_4.0_Server_agent_2.2_SUNWamjboss.tar.gz

For detailed information on the format of the distribution files, see Format of the Distribution Files for a J2EE Agent Installation in Policy Agent 2.2.

Example 3–2 Unpacking Non-Package Formatted Deliverables of Agent for JBoss Application Server 4.0

# gzip -dc SJS_JBoss_4.0_Server_agent_2.2.tar.gz | tar xvf -

For detailed information about this command, see To Unpack Non-Package Formatted Deliverables of a J2EE Agent in Policy Agent 2.2.

Example 3–3 Unpacking Package Formatted Deliverables of Agent for JBoss Application Server 4.0


# gzip -dc SJS_JBoss_4.0_Server_agent_2.2_SUNWamjboss.tar.gz | tar xvf -

For detailed information about this command, see To Unpack Package Formatted Deliverables of a J2EE Agent in Policy Agent 2.2.

Example 3–4 Unpacking a .zip Compressed file of Agent for JBoss Application Server 4.0

unzip SJS_JBoss_4.0_Server_agent_2.2.zip

For example, if you unzip the file in /opt, the home directory is /opt/j2ee_agents/am_jboss_agent. In this guide, JBOSS_AGENT_HOME represents the home directory.

For detailed information about this command, see To Unpack a .zip Compressed file of a J2EE Agent in Policy Agent 2.2.

Follow the specific steps outlined in the following section before you install the agent to reduce the chance of complications occurring during and after the installation.

ProcedureTo Prepare to Install the Agent for JBoss Application Server 4.0:

  1. Ensure that the Policy Agent 2.2 for JBoss Application Server 4.0 is supported on the desired platform as listed in Supported Platforms and Compatibility of Agent for JBoss Application Server 4.0.

  2. Install JBoss Application Server 4.0 if it is not already installed.

    Refer to the appropriate JBoss Application Server 4.0 installation documentation for information about installing this product on the following web site:

    http://www.jboss.com/downloads/index.

    Note –

    The Agent for JBoss Application Server 4.0 is not supported with the JBoss minimal configuration set.

  3. Ensure that the JBoss Application Server 4.0 instance that will be protected by the agent is shut down.

  4. Create a valid agent profile in Access Manager Console if one has not already been created.

    For information on how to create an agent profile, see Creating a J2EE Agent Profile.

    To avoid a misconfiguration of the agent, ensure that you know the exact 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 installing the agent.

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

    Ensure that this file is located in a secure directory of your choice. You will refer to this file during the agent installation process.

    With the agent profile password in this file, stored in a secure location, you do not need to enter sensitive information in the console. A valid password file can have only one line that contains the agent profile password.

Using the Installation Program of Agent for JBoss Application Server 4.0

After you issue the agentadmin command and accept the license agreement (if necessary) the installation program appears, prompting 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 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 list provides key points about the installation program.

About Installation Prompts in Agent for JBoss Application Server 4.0

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.

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.

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

Installing the Agent for JBoss Application Server 4.0

After you have performed any required pre-installation steps, use the agentadmin --install command to install the agent.

ProcedureTo Install the Agent for JBoss Application Server 4.0:

  1. Change to the following directory:


    JBOSS_AGENT_HOME/bin

    JBOSS_AGENT_HOME represents the directory where you unpacked or unzipped the JBoss Application Server 4.0agent distribution file. For example: /opt/j2ee_agents/am_jboss_agent.

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

  2. Issue the following command:


    ./agentadmin --install

    Note: On Windows systems, execute agentadmin.bat.

  3. (Conditional) If you receive license agreement, 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. Enter the installation information as prompted by the agentadmin program (or accept the default values).

    For example, specific information that you will need to enter includes:

    JBoss Server Configuration Directory

    Path to the /conf directory. For example: /opt/jboss-4.0.2/server/default/conf

    Java Security Manager Permissions

    Indicates (true or false) whether the JBoss server instance is running with Java Security Manager permissions:

    • true - The JBoss server standard server.policy file location is displayed. If JBoss server is using a different server.policy file, specify that file, including its path. The Java permissions file (standard file is server.policy) will be modified with agent-specific permissions.

    • false (default) - Skip the server.policy file interaction. The Java permissions file (standard file is server.policy) will not be modified, if it exists.

    For more information, see Installing the Agent on a JBoss Application Server 4.0 Instance Running with Java Security Manager Permissions.

    Deployment URI for the Agent Application

    The deployment URI for the agent application (agentapp.war) 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. The agent application is deployed during the agent installation. 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 Agent for JBoss Application Server 4.0. 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.

    J2EE Password File

    The J2EE password file should have been created as a pre-installation step. For the pre-installation steps, see Preparing to Install Agent for JBoss Application Server 4.0.

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

    Other values that you must specify include items such as the Access Manager server host name, port number, and protocol (http or https).

    After you specify all values, the program displays a summary of your responses. For example:

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
JBoss Server Config Directory : /opt/jboss-4.0.2/server/default/conf
Access Manager Services Host : am.example.com
Access Manager Services Port : 8880
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : am.example.com
Agent permissions gets added to java permissions policy file : true
File name of Java security manager permissions used for the chosen JBoss
server instance. :
/opt/jboss-4.0.2/server/default/conf/server.policy
Application Server Instance Port number : 8080
Protocol for Application Server instance : http
Deployment URI for the Agent Application : /agentapp
Encryption Key : 1Ae4alVx7M9YnVcQKI5OqCXsnGyPaKAP
Agent Profile name : jee
Agent Profile Password file name : /opt/ldp
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]:

  5. Based on this summary, select one of the options.

    If you choose option 1, Continue with Installation, the program performs the functions described in JBoss Application Server 4.0 Agent Installation Functions and then displays the Summary of the Agent Installation.

    For a complete sample run on an installation, see Sample Installation for the Agent for JBoss Application Server 4.0.

Summary of the Agent Installation

At the end of the installation process, the installation program displays a summary of the agent installation. For example:

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

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

Thank you for using Access Manager Policy Agent

In the following descriptions, PolicyAgent-base represents the J2EE base installation directory for the agent, and agent_001 identifies this specific agent installation. For more information about the location of a J2EE agent base directory, see Location of the J2EE Agent Base Directory in Policy Agent 2.2.

Files in the SUMMARY OF AGENT INSTALLATION include:

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 determine the cause of the failure.

Before performing the post-installation steps as described in Chapter 4, Post-Installation Tasks of Policy Agent 2.2 for JBoss Application Server 4.0, be sure to review the install.log file.

Sample Installation for the Agent for JBoss Application Server 4.0

Example 3–5 shows a sample installation run of the agent for JBoss Application Server 4.0.

This sample run represents a JBoss Application Server 4.0 installation running with Java security manager permissions. For more information, see Installing the Agent on a JBoss Application Server 4.0 Instance Running with Java Security Manager Permissions.

Example 3–5 Sample Installation for the Agent for JBoss Application Server 4.0

************************************************************************
Welcome to the Access Manager Policy Agent for JBoss Server 4.0. If the
Policy Agent is used with Federation Manager services, User needs to enter
information relevant to Federation Manager.
************************************************************************
Enter the complete path to the directory which is used by JBoss Server to
store its configuration Files. This directory uniquely identifies the JBoss
Server instance that is secured by this Agent.
[ ? : Help, ! : Exit ]
Enter the JBoss Server Config Directory Path
[/opt/jboss-4.0.2/server/default/conf]:

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

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

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

Indicate the specified server instance runs with Java security manager
permissions.
[ ? : Help, < : Back, ! : Exit ]
Specify whether the chosen server instance runs with Java security manager
permissions. [false]: true

Enter the complete path including the file name of Java security manager
permissions used for the chosen JBoss server instance.
[ ? : Help, < : Back, ! : Exit ]
Enter the complete path including the file name of Java security manager
permissions used for the chosen JBoss server instance.
[/opt/jboss-4.0.2/server/default/conf/server.policy]:

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

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 [1Ae4alVx7M9YnVcQKI5OqCXsnGyPaKAP]:

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

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: /opt/ldp
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
JBoss Server Config Directory : /opt/jboss-4.0.2/server/default/conf
Access Manager Services Host : am.example.com
Access Manager Services Port : 8880
Access Manager Services Protocol : http
Access Manager Services Deployment URI : /amserver
Agent Host name : agent.example.com
Agent permissions gets added to java permissions policy file : true
File name of Java security manager permissions used for the chosen JBoss
server instance. :
/opt/jboss-4.0.2/server/default/conf/server.policy
Application Server Instance Port number : 8080
Protocol for Application Server instance : http
Deployment URI for the Agent Application : /agentapp
Encryption Key : 1Ae4alVx7M9YnVcQKI5OqCXsnGyPaKAP
Agent Profile name : jee
Agent Profile Password file name : /opt/ldp
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]:

Creating directory layout and configuring AMAgent.properties file 
for agent_001 instance ...DONE.
Reading data from file /opt/ldp 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/jboss-4.0.2/server/default/conf/jboss-service.xml ...DONE.
Adding Agent parameters to
/opt/jboss-4.0.2/server/default/conf/jboss-service.xml file ...DONE.
Creating a backup for file
/opt/jboss-4.0.2/server/default/conf/server.policy ...DONE.
Adding Agent parameters to
/opt/jboss-4.0.2/server/default/conf/server.policy file ...DONE.
Adding Agent parameters to am-login-config.xml file ...DONE.
Adding Agent parameters to
/opt/jboss-4.0.2/bin/setAgentClasspathdefault.sh file ...DONE.
Adding Agent parameters to agentapp.war file ...DONE.

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: agent_001
Agent Configuration file location:
/opt/j2ee_agents/am_jboss_agent/agent_001/config/AMAgent.properties
Agent Audit directory location:
/opt/j2ee_agents/am_jboss_agent/agent_001/logs/audit
Agent Debug directory location:
/opt/j2ee_agents/am_jboss_agent/agent_001/logs/debug
Install log file location:
/opt/j2ee_agents/am_jboss_agent/logs/audit/install.log
Thank you for using Access Manager Policy Agent

Installing a J2EE Agent on Multiple JBoss Application Server 4.0 Instances

After you install the agent for a specific JBoss server instance, you can install the agent on another JBoss server instance on the same host server by executing the agentadmin --install command again.

However, the JBoss server agent and the Access Manager server must run on different web containers?

Installing the Agent on a JBoss Application Server 4.0 Instance Running with Java Security Manager Permissions

If you are installing the agent on an instance of JBoss Application Server 4.0 that runs with Java security manager permissions, during the installation process, answer true to the following prompt as shown:


Indicate the specified server instance runs with Java security manager
permissions.
[ ? : Help, < : Back, ! : Exit ]
Specify whether the chosen server instance runs with Java security manager
permissions. [false]: true

Answering true to the preceding prompt, causes the following prompt to appear:


Enter the complete path including the file name of Java security manager
permissions used for the chosen JBoss server instance.
[ ? : Help, < : Back, ! : Exit ]
Enter the complete path including the file name of Java security manager
permissions used for the chosen JBoss server instance.
[/opt/jboss-4.0.2/server/default/conf/server.policy]:

Enter the appropriate path information.