test

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for JBoss Application Server 4.x/5.x

Installing the JBoss Application Server 4.x/5.x Agent

Gathering Information to Install the JBoss Application Server 4.x/5.x Agent

The following table describes the information you will need to provide when you run the agentadmin program to install the JBoss Application Server 4.x/5.x agent. For some agentadmin prompts, you can accept the default value displayed by the program, if you prefer.

Note. The examples and sample runs in this guide refer to JBoss AS 4.x; however, JBoss 5.x is also supported.

Table 2 Information Required to Install the JBoss Application Server 4.x/5.x Agent

Prompt 

Description 

Config Directory Path 

Path to the configuration directory for the JBoss Application Server instance. 

Applies to both default and custom installation options. 

For example: /opt/jboss-4.2.3.GA/server/default/conf

Home Directory Path 

Path to the JBoss Application Server home directory. 

Applies to both default and custom installation options. 

For example: /opt/jboss-4.2.3.GA

OpenSSO server URL 

OpenSSO Enterprise server URL, including the deployment URI. 

Applies to both default and custom installation options. 

For example: http://opensso-host.example.com:8080/opensso

Agent URL 

Agent URL, including the deployment URI for the agent application. 

Applies to both default and custom installation options. 

For example: http://agent-host.example.com:8090/agentapp

The agent application (agentapp.war) is a housekeeping application used by the agent for notifications and other functions such as cross-domain single sign-on (CDSSO). For information, see Deploying the Agent Application.

Encryption Key 

Key used to encrypt the agent profile password. The encryption key should be at least 12 characters long. You can accept the default key or create a new key using the agentadmin --getEncryptKey command.

Applies only to the custom installation option. 

Agent profile name 

A policy agent communicates with OpenSSO Enterprise using the name and password in the agent profile. 

Applies to both default and custom installation options. 

For information, see Creating an Agent Profile.

Agent profile password file name 

Path to the agent profile password file, which is ASCII text file with only one line specifying the agent profile password. You create the agent profile password file as a pre-installation step. 

Applies to both default and custom installation options. 

For information, see Creating a Password File.

Option to the create the agent profile 

The agentadmin program displays the following prompt if the agent profile previously specified for the Agent Profile Name prompt does not already exist in OpenSSO Enterprise:

Enter true if the Agent Profile is being created into OpenSSO by the installer. Enter false if it will be not be created by installer.

To have the installation program create the agent profile, enter true. The program then prompts you for:

  • Agent administrator who can create, update, or delete the agent profile. For example: agentadmin

    Important: To use this option, the agent administrator must already exist in OpenSSO Enterprise server. For information see, Creating an Agent Administrator.

    If you prefer, you can specify amadmin as this user.

  • Path to the agent administrator password file. For information, see Creating a Password File.

Applies only to the custom installation option. 

Option to add Java security permissions to the JBoss Application Server security policy file 

Indicates whether the JBoss Application Server instance runs with the Java Security Manager enabled and you want the installer to add the Java security permissions to the security policy file. 

  • true — The installer adds the Java security permissions to the JBoss Application Server security policy file.

    The installer first displays the server.policy file in the configuration directory. If the JBoss Application Server instance is using a different serve policy file, specify the path to that file.

  • false (default) — The installer does not add Java security permissions to the security policy file.

Applies only to the default installation option. 

Installing the JBoss Application Server 4.x/5.x Agent Using the agentadmin Program

The version 3.0 agentadmin program includes these installation options:

Before you install the JBoss Application Server 4.x/5.x agent:

Procedure To Install the JBoss Application Server 4.x/5.x Agent Using the agentadmin Program

  1. Log into the host server where you want to install the agent.

    Important: To install the agent, you must have write permission to the JBoss Application Server instance files and directories.

  2. If the JBoss Application Server instance is running, shut it down.

  3. Change to the following directory:

    PolicyAgent-base/bin

  4. On Solaris and Linux systems, set the permissions for the agentadmin program as follows, if needed:

    # chmod 755 agentadmin

  5. Start the agent installation:

    Default install: # ./agentadmin --install

    or

    Custom install: # ./agentadmin --custom-install

    On Windows systems, run the agentadmin.bat program.

  6. Enter information as requested by the agentadmin program, or accept the default values displayed by the program.

    After you have made your choices, the agentadmin program displays a summary of your responses. For example, for a custom installation:

    -----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------

JBoss Server Config Directory : /opt/jboss-4.2.3.GA/server/default/conf
JBoss Server Home Directory : /opt/jboss-4.2.3.GA
OpenSSO server URL : http://opensso-host.example.com:8080/opensso
Agent URL : http://agent-host.example.com:8090/agentapp
Agent Profile name : JBossAgentProfile
Agent Profile Password file name : /tmp/jbossagentpw
Agent permissions gets added to java permissions policy file : false

  7. Verify your choices and either continue with the installation (selection 1, the default) , or make any necessary changes.

    If you continue, the program installs the agent and displays a summary of the installation. For example, for a custom installation:

    SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/agents/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentBootstrap.properties
Agent Configuration file location
/agents/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentConfiguration.properties
Agent Audit directory location:
/agents/j2ee_agents/jboss_v42_agent/Agent_001/logs/audit
Agent Debug directory location:
/agents/j2ee_agents/jboss_v42_agent/Agent_001/logs/debug
Install log file location:
/agents/j2ee_agents/jboss_v42_agent/installer-logs/audit/install.log

  8. After the installation finishes successfully, if you wish, check the installation logs in the following directory:

    installer-logs/audit

  9. Start the JBoss Application Server instance.

Example 1 Sample agentadmin Program Installation for the JBoss Application Server 4.x/5.x Agent

************************************************************************
Welcome to the OpenSSO Policy Agent for JBoss Server 4.x.
************************************************************************
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.2.3/server/default/conf]: /opt/jboss-4.2.3.GA/server/default/conf

Enter the complete path to the directory where JBoss Server home directory is
stored
[ ? : Help, < : Back, ! : Exit ]
Enter the JBoss Server Home Directory Path
[/opt/jboss-4.2.3.GA]: /opt/jboss-4.2.3.GA

Enter the URL where the OpenSSO server is running. Please include the
deployment URI also as shown below:
(http://opensso.sample.com:58080/opensso)
[ ? : Help, < : Back, ! : Exit ]
OpenSSO server URL: http://opensso-host.example.com:8080/opensso

Enter the Agent URL. Please include the deployment URI also as shown below:
(http://agent1.sample.com:1234/agentapp)
[ ? : Help, < : Back, ! : Exit ]
Agent URL: http://agent-host.example.com:8090/agentapp

Enter the Agent profile name
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: JBossAgentProfile

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/jbossagentpw

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

-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
JBoss Server Config Directory :
/opt/jboss-4.2.3.GA/server/default/conf
JBoss Server Home Directory : /opt/jboss-4.2.3.GA
OpenSSO server URL : http://opensso-host.example.com:8080/opensso
Agent URL : http://agent-host.example.com:8090/agentapp
Agent Profile name : JBossAgentProfile
Agent Profile Password file name : /tmp/jbossagentpw
Agent permissions gets added to java permissions policy file : 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]: 1
Creating directory layout and configuring Agent file for Agent_001 instance ...DONE.
Reading data from file
/tmp/jbossagentpw and
encrypting it ...DONE.
Generating audit log file name ...DONE.
Creating tag swapped OpenSSOAgentBootstrap.properties file for instance
Agent_001 ...DONE.
Creating a backup for file
/opt/jboss-4.2.3.GA/server/default/conf/jboss-service.xml
...DONE.
Adding Agent parameters to
/opt/jboss-4.2.3.GA/server/default/conf/jboss-service.xml
file ...DONE.
Creating a backup for file null ...DONE.
Adding Agent parameters to null file ...DONE.
Adding Agent parameters to am-login-config.xml file ...DONE.
Adding Agent parameters to
/opt/jboss-4.2.3.GA/bin/setAgentClasspathdefault.sh
file ...DONE.
Adding Agent parameters to agentapp.war file ...DONE.

SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/agents/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentBootstrap.properties
Agent Configuration file location
/agents/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentConfiguration.properties
Agent Audit directory location:
/agents/j2ee_agents/jboss_v42_agent/Agent_001/logs/audit
Agent Debug directory location:
/agents/j2ee_agents/jboss_v42_agent/Agent_001/logs/debug

Install log file location:
/agents/j2ee_agents/jboss_v42_agent/installer-logs/audit/install.log

Thank you for using OpenSSO Policy Agent 3.0.

After You Finish the Install

Agent Instance Directory

The installation program creates the following directory for each agent instance:

PolicyAgent-base/Agent_nnn

Each agent instance directory contains the following subdirectories:

Considering Specific Deployment Scenarios for the JBoss Application Server 4.x/5.x Agent

Installing the JBoss Application Server 4.x/5.x Agent on Multiple JBoss Application Server Instances

You can install the JBoss Application Server 4.x/5.x agent on multiple JBoss Application Server instances on the same host machine. However, you must run the agentadmin program for each JBoss Application Server instance. During each installation, specify the unique server configuration directory and instance name, so the agent can differentiate the different instances.

Installing the JBoss Application Server 4.x/5.x Agent on the OpenSSO Enterprise Host Machine

You can install the JBoss Application Server 4.x/5.x agent on a different web container instance on the same host machine where OpenSSO Enterprise server is installed, as long as the web container is supported for both the JBoss Application Server 4.x/5.x agent and OpenSSO Enterprise server.