This chapter describes how to install the Apache HTTP Server 2.2 agent, including:
About the Installation Prompts for the Apache HTTP Server 2.2 Agent
Example of the Installation Program Interaction for the Apache HTTP Server 2.2 Agent
Implications of Specific Deployment Scenarios for the Apache HTTP Server 2.2 Agent
Verifying a Successful Installation for the Apache HTTP Server 2.2 Agent
Because the Apache HTTP Server 2.2 agent was developed as part of the OpenSSO project, the distribution files are available only in .zip file format. Also, the installation is similar for all platforms, so this chapter is not divided into platform-specific sections
After you have successfully installed the agent, as described in this chapter, complete the post-installation tasks described in Chapter 6, Post-Installation Tasks for the Apache HTTP Server 2.2 Agent.
Follow the specific steps in this section before you install the web agent to reduce the chance of complications occurring during and after the installation.
Ensure that the Apache HTTP Server 2.2 agent is supported on the desired platform, as listed in Supported Platforms and Compatibility for the Apache HTTP Server 2.2 Policy Agent.
If necessary, install and configure the Apache HTTP Server 2.2 web container.
Also, check that the Apache HTTP Server 2.2 has the latest patches.
For more information, refer to the Apache HTTP Server 2.2 documentation: http://httpd.apache.org/docs/2.2/
Set your JAVA_HOME environment variable to a JDK version 1.5.0 or higher.
The installation program requires that your JAVA_HOME variable be set correctly. If you have incorrectly set the JAVA_HOME variable, the setup script will prompt you to supply the correct path:
Please enter JAVA_HOME path to pick up java:
(Conditional) Create a valid agent profile in the Access Manager Console, if one has not already been created.
Web agents can function using the default agent profile (UrlAccessAgent), but creating a different agent profile provides greater security. You must also create a different agent profile if Access manager is configured for cross domain single sign-on (CDSSO).
For information about how to create an agent profile, see Chapter 5, Relationship Between the Agent Profile and Web Agents.
To avoid configuration problems for the agent, you must know the agent profile ID and password used to create the agent profile. You must specify the agent profile password in the next step, and you must enter the agent profile ID when you install the agent.
Create an agent profile password word file.
An agent profile password file is a text file with one line that contains the agent profile password. You will need to provide the path to this file during the agent installation process. By using an agent profile password file, you do not need to enter the password during the agent installation. Set the security permissions for this file as required for your specific deployment.
Unzip the web agent .zip file. For example:
# unzip apache_v22_platform_agent.zip
where platform identities the specific platform where you are installing the agent:
SunOS — Solaris SPARC systems
SunOS_x86 — Solaris x86 systems
Linux — Linux systems
WINNT — Windows systems
On UNIX-based systems, ensure that the following programs have executable permissions:
agentadmin
crypt_util
certutil
These programs are located in the PolicyAgent-base/bin directory. For example, to secure these programs on Solaris systems:
# chmod +x agentadmin crypt_util certutil
The agent installation program (agentadmin) performs the following operations:
Creates the Apache HTTP Server 2.2 agent instance directory
Sets values (tag swapping) in the AMAgent.properties file
Updates agent information in the Apache HTTP Server 2.2 httpd.conf file
Change to the PolicyAgent-base/bin directory.
PolicyAgent-base/bin |
For information about the PolicyAgent-base directory, seeLocation of the Web Agent Base Directory in Policy Agent 2.2.
Issue the following command:
./agentadmin --install |
If you receive license agreement information, accept or reject the agreement. If you reject any portion of the agreement, the installation program will end.
The license agreement is displayed only during the first run of the agentadmin program.
After you accept the license agreement (if necessary), provide the following information when requested by the installation program (or accept the default values):
Path to the Apache HTTP Server 2.2 configuration directory
Access Manager services host name, port, and protocol
Access Manager services deployment URI
Agent host name, port, and protocol
Agent profile name and password file
The prompts are shown in Example of the Installation Program Interaction for the Apache HTTP Server 2.2 Agent.
Key points about the installation program to consider include:
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.
After you entered all values, the installation program displays a summary of your responses.
Note the agent instance name, such as Agent_001. You might be prompted for this name during the configuration process.
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.
Edit your responses if needed. When you are satisfied with your responses, choose option 1 to continue with the installation.
The following list provides information about specific prompts in the installation.
Enter the path to the Apache HTTP Server 2.2 configuration directory. The default is /usr/local/apache2/conf.
Enter the fully qualified host name, port, and protocol for the server where Access Manager is installed. The default port is 80, and the default protocol is http.
Enter the URI that will be used to for Access Manager. The default value is /amserver.
To use an agent profile, you must create the profile as a pre-installation step, as described in Preparing to Install the Apache HTTP Server 2.2 Agent. For more information about creating an agent profile, see also Chapter 5, Relationship Between the Agent Profile and Web Agents. The default is UrlAccessAgent.
Web agents can function using the default agent profile (UrlAccessAgent), but creating a different agent profile provides greater security. You must also create a different agent profile if Access manager is configured for cross domain single sign-on (CDSSO).
You should create the agent profile password file as a pre-installation step as described in Preparing to Install the Apache HTTP Server 2.2 Agent.
When the installation program prompts you for the password for the agent, enter the fully qualified path to this password file.
The following example shows a sample installation for the Apache HTTP Server 2.2 agent.
************************************************************************ Welcome to the Access Manager Policy Agent for Apache Server If the Policy Agent is used with Federation Manager services, User needs to enter information relevant to Federation Manager. ************************************************************************ Do you completely agree with all the terms and conditions of this License Agreement (yes/no): [no]: yes Enter the complete path to the directory which is used by Apache Server to store its configuration Files. This directory uniquely identifies the Apache Server instance that is secured by this Agent. [ ? : Help, ! : Exit ] Enter the Apache Server Config Directory Path [/usr/local/opt/apache2/conf]: /usr/local/opt/apache2/conf 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]: 8080 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 Web Server protected by the agent is installed. [ ? : Help, < : Back, ! : Exit ] Enter the Agent Host name: agenthost.example.com Enter the preferred port number on which the Web Server provides its services. [ ? : Help, < : Back, ! : Exit ] Enter the port number for Web Server instance [80]: 7000 Select http or https to specify the protocol used by the Web server instance that will be protected by Access Manager Policy Agent. [ ? : Help, < : Back, ! : Exit ] Enter the Preferred Protocol for Web Server instance [http]: 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 [UrlAccessAgent]: 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/agent-profile-password-file ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- Apache Server Config Directory : /usr/local/opt/apache2/conf Access Manager Services Host : amhost.example.com Access Manager Services Port : 8080 Access Manager Services Protocol : http Access Manager Services Deployment URI : /amserver Agent Host name : agenthost.example.com Web Server Instance Port number : 7000 Protocol for Web Server instance : http Agent Profile name : UrlAccessAgent Agent Profile Password file name : /opt/agent-profile-password-file 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]:
At the end of the installation process, the installation program prints the status of the installation along with the installed agent information. The information that the program displays can be very useful. The program also displays the location of specific files, which can be of great importance.
You might want to view the installation log file after the installation is complete, before performing the post-installation steps as described in Chapter 6, Post-Installation Tasks for the Apache HTTP Server 2.2 Agent.
The location of directories displayed by the installer are specific. However, throughout this guide and specifically in the summary of the agent installation shown in this section, PolicyAgent-base represents the directory where the distribution files are stored for a specific web agent:
Agent-HomeDirectory/web_agents/apache22_agent |
where Agent-HomeDirectory is the directory where you unzipped the web agent distribution file.
Information regarding the location of the web agent base directory is also described in Location of the Web Agent Base Directory in Policy Agent 2.2.
The installation program prints the following information:
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
After the agent is installed, the directories shown in the previous example are created in the Agent_00x directory, which for this example is Agent_001. Those directories and files are described in the following paragraphs.
Location of the web agent AMAgent.properties configuration file for the agent instance. Every instance of a web 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:
Location of the web agent local audit trail.
Location of all debug files required to debug an agent installation or configuration issue.
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.
The following sections refer to specific deployment scenarios involving the Apache HTTP Server 2.2 agent. These scenarios can affect how you respond to prompts during the installation process. You might also need to perform additional configuration operations.
Configuring the Apache HTTP Server 2.2 Agent for Multiple Apache HTTP Server Virtual Hosts
Installing the Apache HTTP Server 2.2 Agent on the Access Manager Host
Consider the scenario where the Apache HTTP Server 2.2 has two virtual hosts: http://site1.example.com/ and http://site2.example.com/.
Define the FQDN map property in the AMAgent.properties file as:
com.sun.am.policy.agents.config.fqdn.map = valid1|site1.example.com,valid2|site2.example.com
Define policies in Access Manager with virtual host names in the policy rules.
Define the FQDN map property in the AMAgent.properties file as:
com.sun.am.policy.agents.config.fqdn.map = valid1|site1.example.com,valid2|site2.example.com
Define the site2 URLs in the not-enforced URL list.
Installing the Apache HTTP Server 2.2 agent on the Access Manager host is not recommended for production deployments because performance can be degraded.
However, if you want to install the agent on the Access Manager host on the same Apache HTTP Server 2.2 instance, add all of the URLs related to Access Manager to the not enforced URL list. Configuring the not-enforced URL list is described in Configuring the Not-Enforced URL List. If you are installing the agent on a different Apache HTTP Server 2.2 instance, configuration of the not-enforced URL list is not required.
After installing the Apache HTTP Server 2.2 agent, ensure that it is installed successfully by using either or both of these methods:
Attempt to access a resource on the Apache HTTP Server 2.2 deployment container where the agent is installed.
If the web agent is installed correctly, accessing any resource should take you to the Access Manager login page. After a successful authentication, if the policy is properly defined, you should be able to access the resource, provided the policy definition in Access Manager allows it. The default is access denied.
Check the web agent AMAgent.properties configuration file.
Make sure that each property is set properly. For information about the properties in this file, see Appendix C, Web Agent AMAgent.properties Configuration File.