Gathering Information to Install the Tomcat 6.0 Version 3.0 Agent
Installing the Tomcat 6.0 Version 3.0 Agent Using the agentadmin Program
Considering Specific Deployment Scenarios for the Tomcat 6.0 Version 3.0 Agent
The following table describes the information you will need to provide when you run the agentadmin program to install the Tomcat 6.0 version 3.0 agent. For some agentadmin prompts, you can accept the default value displayed by the program, if you prefer.
Table 1 Information Required to Install the Tomcat 6.0 version 3.0 Agent
Prompt |
Description |
---|---|
Tomcat Server Config Directory Path |
Path to the configuration directory for the Tomcat 6.0 instance. Applies to both default and custom installation options. For example: /opt/apache-tomcat-6.0.18/conf |
OpenSSO server URL |
OpenSSO Enterprise server URL, including the deployment URI. Applies to both default and custom installation options. For example: https://openssohost.example.com:8080/opensso |
$CATALINA_HOME environment variable |
Path to the root directory where Tomcat 6.0 is installed. For example: /opt/apache-tomcat-6.0.18/ |
Install policy agent in global web.xml file |
Option to install the agent filter in the global web.xml file:
In both cases, agent filter are added to the manager and host manager and applications. See also Adding Absolute URIs to the Tomcat 6.0 Version 3.0 Agent Profile. Applies to the default installation option. |
Agent URL |
Agent URL, including the deployment URI, for the agent application. Applies to both default and custom installation options. For example: https://agenthost.example.com:8090/agentapp The agentapp is a housekeeping application used by the agent for notifications and other functions such as cross domain single sign-on (CDSSO) support. For more 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:
Applies only to the custom installation option. |
The version 3.0 agentadmin program includes these installation options:
Default install (agentadmin --install): The program asks a limited number of questions and uses default values for the other options. Use the default install option when the default options, as shown in Table 1, meet your deployment requirements.
or
Custom install (agentadmin --custom-install): The program asks a full set of questions similar to the version 2.2 program. Use the custom install option when you want to specify values other than the default options shown in Table 1.
Before you install the Tomcat 6.0 version 3.0 agent:
An OpenSSO Enterprise server instance must be installed and running. To check the server, specify the server URL. For example: http://opensso-host.example.com:8080/opensso
A Tomcat 6.0 server instance must be installed and configured on the machine where you plan to install the agent. For information, see http://tomcat.apache.org/.
You must have downloaded and unzipped the distribution file, as described in Downloading and Unzipping the tomcat_v6_agent_3.zip Distribution File.
Login into the server where you want to install the agent.
Important: To install the agent, you must have write permission to the Tomcat 6.0 instance files and directories.
If necessary, shut down the Tomcat 6.0 instance.
Change to the following directory:
PolicyAgent-base/bin
On Solaris and Linux systems, set the permissions for the agentadmin program as follows, if needed:
# chmod 755 agentadmin
Start the agent installation:
Default install: # ./agentadmin --install
or
Custom install: # ./agentadmin --custom-install
On Windows systems, run the agentadmin.bat program.
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 ----------------------------------------------- Tomcat Server Config Directory : /opt/apache-tomcat-6.0.18/conf $CATALINA_HOME environment variable : /opt/apache-tomcat-6.0.18 OpenSSO server URL : http://opensso-host.example.com:8080/opensso Agent URL : http://agent-host.example.com:8090/agentapp Encryption Key : oyFk4DYaNB2kc6MeJ2xnK4hbWtFhabsZ Agent Profile name : Tomcat6AgentProfile Agent Profile Password file name : /tmp/tomcat6agentpw Agent Profile will be created right now by agent installer : true Agent Administrator : amadmin Agent Administrator's password file name : /opt/amadminpw
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: /opt/agents/j2ee_agents/tomcat_v6_agent/ Agent_001/config/OpenSSOAgentBootstrap.properties Agent Configuration file location /opt/agents/j2ee_agents/tomcat_v6_agent/ Agent_001/config/OpenSSOAgentConfiguration.properties Agent Audit directory location: /opt/agents/j2ee_agents/tomcat_v6_agent/Agent_001/logs/audit Agent Debug directory location: /opt/agents/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug Install log file location: /opt/agents/j2ee_agents/tomcat_v6_agent/installer-logs/audit/custom.log
After the installation finishes successfully, if you wish, check the installation logs in the following directory:
installer-logs/audit
Restart the Tomcat 6.0 instance that is being protected by the agent.
After you install the Tomcat 6.0 version 3.0 agent for a specific domain, you cannot use that same agent on the same host for a different domain. To use the Tomcat 6.0 version 3.0 agent for another domain on the same host, you must install the agent specifically for that domain.
************************************************************************ Welcome to the OpenSSO Policy Agent for Apache Tomcat 6.0 Servlet/JSP Container ************************************************************************ Enter the complete path to the directory which is used by Tomcat Server to store its configuration Files. This directory uniquely identifies the Tomcat Server instance that is secured by this Agent. [ ? : Help, ! : Exit ] Enter the Tomcat Server Config Directory Path [/opt/apache-tomcat-6.0.18/conf]: $CATALINA_HOME environment variable is the root of the tomcat installation. [ ? : Help, < : Back, ! : Exit ] Enter the $CATALINA_HOME environment variable: /opt/apache-tomcat-6.0.18 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 a valid Encryption Key. [ ? : Help, < : Back, ! : Exit ] Enter the Encryption Key [oyFk4DYaNB2kc6MeJ2xnK4hbWtFhabsZ]: Enter the Agent profile name [ ? : Help, < : Back, ! : Exit ] Enter the Agent Profile name: Tomcat6AgentProfile 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/tomcat6agentpw WARNING: Agent profile/User: tomcat30-agent-custom does not exist in OpenSSO server! Either "Hit the Back button, and re-enter the correct agent profile name/user name", or "Create this agent profile when asked(available only in custom-install)", or "Continue without validating it because agent profile is in sub realm", or "Continue without validating/creating it, and manually validate/create it in OpenSSO server after installation". Enter true if the Agent Profile is being created into OpenSSO server by the installer. Enter false if it will be not be created by installer. [ ? : Help, < : Back, ! : Exit ] This Agent Profile does not exist in OpenSSO server, will it be created by the installer? (Agent Administrator's name and password are required) [true]: Agent Administrator is the Administrator user that can create, delete or update agent profile. [ ? : Help, < : Back, ! : Exit ] Enter the Agent Administrator's name: amadmin Enter the path to a file that contains the password of Agent Administrator [ ? : Help, < : Back, ! : Exit ] Enter the path to the password file that contains the password of Agent Administrator: /opt/amadminpw ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- Tomcat Server Config Directory : /opt/apache-tomcat-6.0.18/conf $CATALINA_HOME environment variable : /opt/apache-tomcat-6.0.18 OpenSSO server URL : http://opensso-host.example.com:8080/opensso Agent URL : http://agent-host.example.com:8090/agentapp Encryption Key : oyFk4DYaNB2kc6MeJ2xnK4hbWtFhabsZ Agent Profile name : Tomcat6AgentProfile Agent Profile Password file name : /tmp/tomcat6agentpw Agent Profile will be created right now by agent installer : true Agent Administrator : amadmin Agent Administrator's password file name : /opt/amadminpw 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]: Updating the /opt/apache-tomcat-6.0.18/bin/setclasspath.sh script with the Agent classpath ...DONE. Creating directory layout and configuring Agent file for Agent_001 instance ...DONE. Reading data from file /tmp/tomcat6agentpw 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/apache-tomcat-6.0.18/conf/server.xml ...DONE. Creating a backup for file /opt/apache-tomcat-6.0.18/conf/web.xml ...DONE. Adding OpenSSO Tomcat Agent Realm to Server XML file : /opt/apache-tomcat-6.0.18/conf/server.xml ...DONE. Adding filter to Global deployment descriptor file : /opt/apache-tomcat-6.0.18/conf/web.xml ...DONE. Adding OpenSSO Tomcat Agent Filter and Form login authentication to selected Web applications ...DONE. SUMMARY OF AGENT INSTALLATION ----------------------------- Agent instance name: Agent_001 Agent Bootstrap file location: /opt/agents/j2ee_agents/tomcat_v6_agent/ Agent_001/config/OpenSSOAgentBootstrap.properties Agent Configuration file location /opt/agents/j2ee_agents/tomcat_v6_agent/ Agent_001/config/OpenSSOAgentConfiguration.properties Agent Audit directory location: /opt/agents/j2ee_agents/tomcat_v6_agent/Agent_001/logs/audit Agent Debug directory location: /opt/agents/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug Install log file location: /opt/agents/j2ee_agents/tomcat_v6_agent/installer-logs/audit/custom.log Thank you for using OpenSSO Policy Agent
Agent Instance Directory
The installation program creates the following directory for each agent instance:
PolicyAgent-base/Agent_nnn
PolicyAgent-base is Agent-HomeDirectory/j2ee_agents/tomcat_v6_agent, where Agent-HomeDirectory is where you unzipped the agent distribution file.
nnn identifies the agent instance as Agent_001, Agent_002, and so on for each additional agent instance.
Each agent instance directory contains the following subdirectories:
/config contains the configuration files for the agent instance, including OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties.
/installer-logs contains the following subdirectories
/audit contains local audit trail for the agent instance.
/debug contains the debug files for the agent instance when the agent runs in debug mode.
Installing the Tomcat 6.0 Version 3.0 Agent on Multiple Tomcat 6.0 Instances
Installing the Tomcat 6.0 Version 3.0 Agent on the OpenSSO Enterprise Host Machine
You can install the Tomcat 6.0 version 3.0 agent on multiple Tomcat 6.0 instances on the same host machine. However, you must run the agentadmin program for each Tomcat 6.0 instance. During each installation, specify the unique server configuration directory and instance name, so the agent can differentiate the different instances.
You can install the Tomcat 6.0 version 3.0 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 Tomcat 6.0 version 3.0 agent and OpenSSO Enterprise server.