INDEX

Page no.

1. JBoss and Agent Instructions

2.
3.
4.
5.
6.
7.

JBoss Agent Installation and Usage

...
Post Installation Tasks

Agent Uninstallation

Sampleapp

Installing the agent using agentadmin custom-install option

Migration of the 3.0 JBoss agent
....

4
8
9
10
10
13

1. JBoss and Agent Instructions

The instructions are default applicable to Windows platforms. Solaris specific are
mentioned explicitly.
1.1 JBoss at a glance:
1.

Download JBoss from http://www.jboss.com/products/jbossas/downloads.

Agent is tested so far with 4.0.5, 4.2.3 ,5.0.0.GA.
2. Choose either zip or gz archive.
3. Uncompress the JBoss archive.
4. Directory structure look like this in JBOSS_HOME.
bin/ - JBoss run scripts.
server/ - JBoss by default contains 3 server instances:
minimal/ - minimal jmx kernel support (with a JNDI server - EJBs and
Web Apps will not deploy in this config)
default/ - basic J2EE/EJB support with integrated Tomcat.
all/ - includes everything from default plus JBoss.NET for web services,
and larger scale services such as clustering and IIOP.
You can create your own instance by copying existing instance and
changing the port information in the configuration files. Agent is not
supported with minimal instance.
lib/ - JBoss bootstarp required jar files.
docs/
readme_j2ee.html
client/
jar-versions.xml
readme.html
1.2. JBoss server instance at a glance
Goto JBOSS_HOME/server/default. Directory structure looks like this:
conf/ - Instance specific configuration files.
deploy/ - Here all the war, ear, rar and sar files gets deployed. They can be
either archives and or in exploded mode.
lib/ - Instance specific jar files.
log/ - Instance specific log files.
1.3 JBoss server start/stop
Goto JBOSS_HOME/bin.
Execute run.bat (run.sh for Solaris). This will start 'default' server instance.
You can start a instance explicitly like this:

Execute run.bat b <host name> from the bin directory of the server
installation.
.
run.sh -c <server-instance>
Ex: run.sh -c all starts 'all' server instance.
For help options : run the below command

D:\jboss-4.2.3.GA\bin>run.bat --help
=======================================================================
========
usage: run.bat [options]
options:
-h, --help
-V, --version
--D<name>[=<value>]
-d, --bootdir=<dir>
absolute
or url
-p, --patchdir=<dir>
absolute or u
rl
-n, --netboot=<url>
base
-c, --configuration=<name>
-B, --bootlib=<filename>
bootclasspat
h
-L, --library=<filename>
classpath
-C, --classpath=<url>
classpath
-P, --properties=<url>
url
-b, --host=<host or ip>
-g, --partition=<name>
(default=DefaultDomain)
-u, --udp=<ip>
-l, --log=<log4j|jdk>

Show this help message

Show version information
Stop processing options
Set a system property
Set the boot patch directory; Must be

Set the patch directory; Must be

Boot from net with the given url as

Set the server configuration name
Add an extra library to the front

Add an extra library to the loaders

Add an extra url to the loaders
Load system properties from the given
Bind address for all JBoss services
HA Partition name
UDP multicast address
Specify the logger plugin type

===============================================================
================

2. JBoss Agent Installation and Usage

2.1. Agent Setup:
1. Unzip the JBoss_v42_agent_3.zip which you got after building the agent.
Example: Installation of the agent in D:\ directory looks like this:
D:\j2ee_agents\jboss_v42_agent\ say JBOSS_AGENT_HOME
2. Go to JBOSS_AGENT_HOME/bin. Execute agentadmin -install
3. JBoss specific input:
3.1. Specify the server instance configuration directory. A default directory will
be shown.
3.2. Optional: If JBoss server instance is running Java Security Manager
permissions, then user need to specify true/false. This will modify java
permissions file (standard file is server.policy) with Agent specific permissions.
If true, JBoss's standard server policy location will be displayed. If JBoss is using
a different serve.policy file, please specify it.
If false, Skips server.policy interaction. This means server.policy won't be
modified.
Rest of the setup deals with AM server information and agent's information.
A sample is given below:
D:\jbossagent2\j2ee_agents\jboss_v42_agent\bin>agentadmin --install

******************************************************************
******
Welcome to the Opensso Policy Agent for JBoss Server 4.x./5.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
[C:\jboss-4.2.3\server\default\conf]: D:\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 [D:\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://opensso1.sun.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://d-122008.sun.com:8080/agentapp
Enter the Agent profile name
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: jboss_qa
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: c:\password.txt
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]:
----------------------------------------------SUMMARY OF YOUR RESPONSES
----------------------------------------------JBoss Server Config Directory : D:\jboss-4.2.3.GA\server\default\conf
JBoss Server Home Directory : D:\jboss-4.2.3.GA
OpenSSO server URL : http://opensso1.sun.com:8080/opensso

Agent URL : http://d-122008.sun.com:8080/agentapp

Agent Profile name : jboss_qa
Agent Profile Password file name : c:\password.txt
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]:
Creating directory layout and configuring Agent file for Agent_001
instance ...DONE.
Reading data from file C:\password.txt 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
D:\jboss-4.2.3.GA\server\default\conf/jboss-service.xml ...DONE.
Adding Agent parameters to
D:\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
D:\jboss-4.2.3.GA/bin/setAgentClasspathdefault.bat file ...DONE.
Adding Agent parameters to agentapp.war file ...DONE.
SUMMARY OF AGENT INSTALLATION
----------------------------Agent instance name: Agent_001
Agent Bootstrap file location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentB
ootstrap.pro

perties
Agent Configuration file location
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentC
onfiguration
.properties
Agent Audit directory location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/logs/audit
Agent Debug directory location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/logs/debug
Install log file location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/installer-logs/audit/install.log
Thank you for using OpenSSO Policy Agent 3.0.
2.2 Agent Setup does the following:
1. Deploys agentapp.war in the server instance's deploy directory.
Example: D:/jboss-4.2.3/server/default/deploy/agentapp.war
2. Copies am-login-config-service.xml to server instance's deploy directory.
Example: D:/jboss-4.2.3/server/default/deploy/am-login-configservice.xml
3. Copies am-login-config.xml to server instance's conf directory.
Example D:/jboss-4.2.3/server/default/conf/am-login-config.xml
4. Copies setaAentClasspath script file pertaining to the server instance to
JBOSS_HOME/bin directory. This sets JBOSS_CLASSPATH with agent's config
and locale directories.
Example: D:/jboss-4.2.3/bin/setAgentClasspathdefault.bat , where default
in the file name indicates the server instance name. If the server instance name is
xyz, then the file name will be setAgentClasspathxyz.bat (On Solaris, the file
extension is .sh)
5. Modifies jboss-service.xml in the server's instance. The changes included to
load agent.jar and amclientsdk.jar.
Example:
<classpath codebase="/j2ee_agents/jboss_v42_agent/lib" archives="agent.jar"/>
<classpath codebase="/j2ee_agents/jboss_v42_agent/lib"
archives="amclientsdk.jar"/>
6 . Optional : Based on user's selection if JBoss is running with java permissions,
then modfies server.policy file in the server's instance's conf diretcory. Adds java
permissions to agent codebase.

Example:
grant codeBase "file:d:\j2ee_agents\ jboss_v42_agent/lib/-" {
permission java.lang.RuntimePermission "accessClassInPackage.org.apache.*";
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.io.FilePermission d:\j2ee_agents\ jboss_v42_agent
\agent_001\config\-", "read";
permission java.util.PropertyPermission "*", "read,write";
permission java.io.FilePermission d:\j2ee_agents\ jboss_v42_agent \locale\-",
"read";
permission java.io.FilePermission d:\j2ee_agents\ jboss_v42_agent
\agent_001\logs\-,
"read,write";
permission java.net.SocketPermission "*", "connect,resolve";
permission java.util.logging.LoggingPermission "control";
permission java.io.FilePermission "null/serverconfig.xml", "read";
};

3.Post Installation Tasks

JBOSS_CLASSPATH needs to be set with agent's config and locale directories.
The setAgentClassPath for the chosen server instance gets copied over
JBOSS_HOME/bin/.
This script needs be executed inside JBoss run script. User need to add the
following bold lines
to JBOSS_HOME/bin/run.bat script (run.sh for Windows).
Example: for windows platform. ADD
call D:\jboss-4.2.3.GA\bin\setAgentClasspathdefault.bat
after the line :
if not "%JAVAC_JAR%" == "" set RUNJAR=%JAVAC_JAR%;%RUNJAR%
if "%JBOSS_CLASSPATH%" == "" set RUN_CLASSPATH=%RUNJAR%
if "%RUN_CLASSPATH%" == "" set
RUN_CLASSPATH=%JBOSS_CLASSPATH%;%RUNJAR%
set JBOSS_CLASSPATH=%RUN_CLASSPATH%
for solaris platform . ADD
. setAgentClasspathdefault.sh
After the line :
if [ "x$JBOSS_CLASSPATH" = "x" ]; then
JBOSS_CLASSPATH="$JBOSS_BOOT_CLASSPATH"

else
JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$JBOSS_BOOT_CLASSPAT"
fi
if [ "x$JAVAC_JAR_FILE" != "x" ]; then
JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$JAVAC_JAR_FILE"
fi

4. Agent Uninstallation
Goto JBOSS_AGENT_HOME/bin. Execute agentadmin -uninstall
User needs to give JBoss server instance's configuration directory as the input.
A sample is shown below:
D:\jbossagent2\j2ee_agents\jboss_v42_agent\bin>agentadmin --uninstall

******************************************************************
******
Welcome to the Opensso Policy Agent for JBoss Server 4.x./5.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
[C:\jboss-4.2.3\server\default\conf]: D:\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 [D:\jboss-4.2.3.GA]:
----------------------------------------------SUMMARY OF YOUR RESPONSES
----------------------------------------------JBoss Server Config Directory : D:\jboss-4.2.3.GA\server\default\conf

JBoss Server Home Directory : D:\jboss-4.2.3.GA

Verify your settings above and decide from the choices below.
1. Continue with Uninstallation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:
Removing Agent parameters from
D:\jboss-4.2.3.GA\server\default\conf/jboss-service.xml file ...DONE.
Removing Agent parameters from null file ...DONE.
Removing Agent parameters from am-login-config.xml file ...DONE.
Removing Agent parameters from
D:\jboss-4.2.3.GA/bin/setAgentClasspathdefault.bat file ...DONE.
Removing Agent parameters from agentapp.war file ...DONE.
Deleting the config directory
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/config ...DONE.
Uninstall log file location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/installer-logs/audit/uninstall.log
Thank you for using OpenSSO Policy Agent 3.0.

5. Sampleapp
agentsample is included. Please see readme.txt included in the sampleapp
directory in agent installation directory for instructions on creating the j2ee agent
profile, subjects , policies , deploying the sample application in the deploy
directory of server installation.

6. Installing the agent using agentadmin custom-install

option :
The agentadmin program displays a full set of prompts similar to version 2.2
program.
A sample custom-installation of the 3.0 JBoss agent :

D:\jbossagent2\j2ee_agents\jboss_v42_agent\bin>agentadmin --custom-install

******************************************************************
******
Welcome to the Opensso Policy Agent for JBoss Server 4.x./5.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
[C:\jboss-4.2.3\server\default\conf]: D:\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 [D:\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://opensso1.sun.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://d-122008.sun.com:8080/agentapp
Enter a valid Encryption Key.
[ ? : Help, < : Back, ! : Exit ]
Enter the Encryption Key [UzkYmsyaz2891E3r5+/x+gOPapVATqZK]:
abcdefghijklmnopqrstuvwx
yz

Enter the Agent profile name

[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: jboss_qa
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: c:\password.txt
----------------------------------------------SUMMARY OF YOUR RESPONSES
----------------------------------------------JBoss Server Config Directory : D:\jboss-4.2.3.GA\server\default\conf
JBoss Server Home Directory : D:\jboss-4.2.3.GA
OpenSSO server URL : http://opensso1.sun.com:8080/opensso
Agent URL : http://d-122008.sun.com:8080/agentapp
Encryption Key : abcdefghijklmnopqrstuvwxyz
Agent Profile name : jboss_qa
Agent Profile Password file name : c:\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]:
Creating directory layout and configuring Agent file for Agent_001
instance ...DONE.
Reading data from file C:\password.txt 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
D:\jboss-4.2.3.GA\server\default\conf/jboss-service.xml ...DONE.
Adding Agent parameters to
D:\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
D:\jboss-4.2.3.GA/bin/setAgentClasspathdefault.bat file ...DONE.
Adding Agent parameters to agentapp.war file ...DONE.
SUMMARY OF AGENT INSTALLATION
----------------------------Agent instance name: Agent_001
Agent Bootstrap file location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentB
ootstrap.pro
perties
Agent Configuration file location
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/config/OpenSSOAgentC
onfiguration
.properties
Agent Audit directory location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/logs/audit
Agent Debug directory location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/Agent_001/logs/debug
Install log file location:
D:/jbossagent2/j2ee_agents/jboss_v42_agent/installer-logs/audit/custom.log
Thank you for using OpenSSO Policy Agent 3.0.

7. Migration of the 3.0 JBoss agent :

3.0 JBoss agent can be migrated from 3.0 to its latest patch. A sample is given
below:
D:\jbossagent1\j2ee_agents\jboss_v42_agent\bin>agentadmin --migrate

******************************************************************
******
Welcome to the Opensso Policy Agent for JBoss Server 4.x./5.x
******************************************************************
******
Agent installation directory to be migrated from.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent installation directory to be migrated from:
D:\newWORKSPACE\opensso\p
roducts\j2eeagents\built\jboss_v42\scratch\j2ee_agents\jboss_v42_agent
Migrating Agent Instance ...
Creating a backup for file
D:\jboss-4.2.3.GA\server\default\conf/jboss-service.xml ...DONE.
Removing Agent parameters from
D:\jboss-4.2.3.GA\server\default\conf/jboss-service.xml file ...DONE.
Creating directory layout and configuring Agent file for Agent_001
instance ...DONE.
Generating audit log file name ...DONE.
Creating tag swapped OpenSSOAgentBootstrap.properties file for instance
Agent_001 ...DONE.
Adding Agent parameters to
D:\jboss-4.2.3.GA\server\default\conf/jboss-service.xml file ...DONE.
Thank you for using OpenSSO Policy Agent 3.0.