<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-apache-20'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>Installing the Apache 2.0.x Policy Agent</title>

<indexterm><primary>Apache HTTP Server</primary></indexterm>

<para>This chapter covers installation of the policy agent for Apache

Web Server 2.0.x.</para>

<section xml:id="before-apache20-agent-install">

<title>Before You Install</title>

<para>Make sure OpenAM is installed, running, that you can contact OpenAM

from the system running the policy agent. Next, create a profile for your

policy agent as described in the <citetitle>Administration Guide</citetitle>

section on <link xlink:href="admin-guide#create-agent-profiles"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Creating Agent

Profiles</citetitle></link>. To protect resources with the agent also create

at least one policy as described in the section on <link

xlink:href="admin-guide#configure-authz-policy"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

Policies</citetitle></link>. Consider creating a simple policy, such as a

policy that allows only authenticated users to access your resources, in order

to test your policy agent after installation.</para>

<para>You must install Apache HTTP Server before you install the policy

agent, and you must stop the server during installation.</para>

<para>You must install a supported version of the Java runtime environment.

Please review the <link xlink:show="new"

xlink:href="http://openam.forgerock.org/openam-documentation/openam-doc-source/doc/release-notes/#java-requirements">

<citetitle>OpenAM Release Notes</citetitle></link> for the currently supported version

of Java, and set the <literal>JAVA_HOME</literal> environment

variable accordingly. The policy agent installer requires Java.</para>

<screen>$ echo $JAVA_HOME

/path/to/java

$ which java

/usr/bin/java</screen>

<para>>Go to <link xlink:href="install-guide#download-openam-software"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Obtaining OpenAM Software</citetitle></link>

to determine which version of the agent to download and download the agent.

Also verify the checksum of the file you download against the checksum

posted on the download page.</para>

<para>Unzip the file in the directory where you plan to install the web

policy agent. The agent you install stores its configuration and logs

under this directory.</para>

<variablelist>

<para>When you unzip the policy agent .zip download, you find the following

directories under the <filename>web_agents/apache_agent</filename>

directory.</para>

<varlistentry>

<term><filename>bin</filename></term>

<listitem>

<para>Contains the installation and configuration program,

<command>agentadmin</command>; the certificate management tool

<command>certutil</command> and the password hashing tool

<command>crypt_util</command>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>config</filename></term>

<listitem>

<para>Configuration templates used by the <command>agentadmin</command>

command during installation</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>data</filename></term>

<listitem>

<para>Not used</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>etc</filename></term>

<listitem>

<para>Apache configuration template used during installation</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>installer-logs</filename></term>

<listitem>

<para>Location for log files written during installation</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>lib</filename></term>

<listitem>

<para>Shared libraries used by the web policy agent</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>locale</filename></term>

<listitem>

<para>Property files used by the installation program</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="install-apache20-web-agent">

<title>Installing Apache 2.0 Web Policy Agent</title>

<para>Complete the following procedures to install the policy agent.</para>

<procedure xml:id="create-apache20-agent-profile">

<title>To Create the Apache 2.0 Web Agent Profile</title>

<para>Regardless of whether you store configurations centrally in OpenAM

or locally with your agents, the agent requires a profile so that it can

connect to and communicate with OpenAM.</para>

<step>

<para>In the OpenAM console, browse to Access Control &gt;

<replaceable>Realm Name</replaceable>&gt; Agents &gt; Web,

and then click the New... button in the Agent table.</para>

</step>

<step>

<para>Complete the web form using the following hints.</para>

<variablelist>

<varlistentry>

<term>Name</term>

<listitem>

<para>The name for the agent profile used when you install the

agent</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Password</term>

<listitem>

<para>Password the agent uses to authenticate to OpenAM</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Configuration</term>

<listitem>

<para>Centralized configurations are stored in the OpenAM configuration

store. You can manage the centralized configuration through the OpenAM

console. Local configurations are stored in a file alongside the

agent.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Server URL</term>

<listitem>

<para>The full URL to an OpenAM instance, or if OpenAM is deployed in

a site configuration (behind a load balancer) then the site URL</para>

<para>In centralized configuration mode, the Server URL is used to

populate the agent profile for services such as Login, Logout, Naming,

and Cross Domain SSO.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Agent URL</term>

<listitem>

<para>The web server URL that the agent protects</para>

<para>In centralized configuration mode, the Agent URL is used to

populate the Agent Profile for services such as notifications.</para>

</listitem>

</varlistentry>

</variablelist>

</step>

</procedure>

<procedure xml:id="create-apache20-agent-pwdfile">

<title>To Create the Password File</title>

<step>

<para>Create a text file containing only the password.</para>

<screen>$ echo password > /tmp/pwd.txt</screen>

</step>

<step>

<para>Protect the password file you create as appropriate for your

operating system.</para>

<screen>$ chmod 400 /tmp/pwd.txt</screen>

</step>

</procedure>

<procedure xml:id="install-agent-into-apache20">

<title>To Install the Policy Agent into Apache 2.0</title>

<step>

<para>Shut down the Apache 2.0 server where you plan to install the

agent.</para>

<screen>$ /path/to/apache20/bin/apachectl -k stop</screen>

</step>

<step>

<para>Make sure OpenAM is running.</para>

</step>

<step>

<para>Run <command>/agentadmin --install</command> to install the agent.</para>

<screen>$ cd /path/to/web_agents/apache_agent/bin/

$ /agentadmin --install

...

-----------------------------------------------

SUMMARY OF YOUR RESPONSES

-----------------------------------------------

Apache Server Config Directory : /path/to/apache20/conf

OpenAM server URL : http://openam.example.com:8080/openam

Agent URL : http://www.example.com:80

Agent Profile name : Apache 2.0 Agent

Agent Profile Password file name : /tmp/pwd.txt

...

SUMMARY OF AGENT INSTALLATION

-----------------------------

Agent instance name: Agent_001

Agent Bootstrap file location:

/path/to/web_agents/apache_agent/Agent_001/config/

<?eval ${agentsBootstrapFile}?>

Agent Configuration Tag file location

/path/to/web_agents/apache_agent/Agent_001/config/

<?eval ${agentsConfigurationFile}?>

Agent Audit directory location:

/path/to/web_agents/apache_agent/Agent_001/logs/audit

Agent Debug directory location:

/path/to/web_agents/apache_agent/Agent_001/logs/debug

Install log file location:

/path/to/web_agents/apache_agent/installer-logs/audit/install.log

...</screen>

<para>Upon successful completion, the installer has added the agent as

a module to the Apache 2.0 configuration, and also set up configuration

and log directories for the agent.</para>

<note>

<para>If the agent is in a different domain than the server, refer to the

<citetitle>Administration Guide</citetitle> procedure, <link

xlink:href="admin-guide#chap-cdsso"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring

Cross-Domain Single Sign On</citetitle></link>.</para>

</note>

</step>

<step>

<para>Take note of the configuration files and log locations.</para>

<para>Each agent instance that you install on the system has its own

numbered configuration and logs directory. The first agent's configuration

and logs are thus located under the directory

<filename>web_agents/apache_agent/Agent_001/</filename>.</para>

<variablelist>

<varlistentry>

<term><filename>config/<?eval ${agentsBootstrapFile}?></filename></term>

<listitem>

<para>Used to bootstrap the web policy agent, allowing the agent to

connect to OpenAM and download its configuration</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>config/<?eval ${agentsConfigurationFile}?></filename></term>

<listitem>

<para>Only used if you configured the web policy agent to use local

configuration</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>logs/audit/</filename></term>

<listitem>

<para>Operational audit log directory, only used if remote logging

to OpenAM is disabled</para>

</listitem>

</varlistentry>

<varlistentry>

<term><filename>logs/debug/</filename></term>

<listitem>

<para>Debug directory where the <filename>amAgent</filename> debug file

resides. Useful in troubleshooting policy agent issues.</para>

</listitem>

</varlistentry>

</variablelist>

</step>

<step>

<para>If your policy agent configuration is not in the top-level realm (/),

then you must edit config/<?eval ${agentsBootstrapFile}?> to identify

the sub-realm that has your policy agent configuration.

Find com.sun.identity.agents.config.organization.name and change

the / to the path to your policy agent profile. This allows the policy agent

to properly identify itself to the OpenAM server. </para>

</step>

<step>

<para>Start the Apache 2.0 server where you installed the agent.</para>

<screen>$ /path/to/apache20/bin/apachectl -k start</screen>

</step>

</procedure>

<procedure xml:id="check-apache20-agent-installation">

<title>To Check the Policy Agent Installation</title>

<step>

<para>Check the Apache 2.0 error log after you start the server to make

sure startup completed successfully.</para>

<screen>$ tail -n 1 /path/to/apache20/logs/error_log

[Fri Sep 09 17:01:37 2011] [notice] Apache/2.0.64 (Unix) configured

-- resuming normal operations</screen>

</step>

<step>

<para>Check the <filename>amAgent</filename> debug log to verify that

no errors occurred on startup.</para>

<screen>$ tail /path/to/web_agents/apache_agent/Agent_001/logs/debug/amAgent

2011-09-09 17:01:37.179 -1 14516:94c6e58 all: ==============...=====

2011-09-09 17:01:37.179 -1 14516:94c6e58 all: Version: ...

2011-09-09 17:01:37.179 -1 14516:94c6e58 all:

2011-09-09 17:01:37.179 -1 14516:94c6e58 all: Build Date: ...

2011-09-09 17:01:37.179 -1 14516:94c6e58 all: Build Machine: ..forgerock.com

2011-09-09 17:01:37.179 -1 14516:94c6e58 all: ==============...=====</screen>

</step>

<step performance="optional">

<para>If you have a policy configured, you can test your policy agent.

For example, try to browse to a resource that your policy agent protects.

You should be redirected to OpenAM to authenticate, for example as user

<literal>demo</literal>, password <literal>changeit</literal>. After

you authenticate, OpenAM then redirects you back to the resource you tried

to access.</para>

</step>

</procedure>

</section>

<section xml:id="custom-apache20-agent-installation">

<title>Custom Apache 2.0 Web Policy Agent Installation</title>

<para>When running multiple Apache 2.0 servers on the same host, use

<command>/agentadmin --custom-install</command>.</para>

<para>When performing a scripted, silent installation, use

<command>/agentadmin --install --saveResponse

<replaceable>response-file</replaceable></command>

to create a response file for scripted installation. Then install silently

using <command>/agentadmin --install --useResponse

<replaceable>response-file</replaceable></command>.</para>

<para>With <command>/agentadmin --custom-install</command>, you can opt to

create the policy agent profile during installation. The OpenAM administrator

must first create an agent administrator user, as described in <link

xlink:href="admin-guide#delegate-agent-profile-creation"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Delegating Agent

Profile Creation</citetitle></link>, and provide you with the agent

administrator user name and password. Before running the

<command>/agentadmin --custom-install</command> command, put the password

alone in a read-only file only the user installing can access, as for the

agent password. When the <command>agentadmin</command> command prompts you to

create the profile during installation, enter <literal>true</literal>, and

then respond to the <command>agentadmin</command> prompts for the agent

administrator user name and password file.</para>

</section>

<section xml:id="uninstall-apache20-agent">

<title>Remove Apache 2.0 Web Policy Agent Software</title>

<para>Shut down the Apache 2.0 server before you uninstall the

policy agent.</para>

<screen>$ /path/to/apache20/bin/apachectl -k stop</screen>

<para>To remove the web policy agent, use <command>/agentadmin

--uninstall</command>.</para>

<screen>$ /agentadmin --uninstall

...

-----------------------------------------------

SUMMARY OF YOUR RESPONSES

-----------------------------------------------

Apache Server Config Directory : /path/to/apache20/conf

...

Deleting the config directory

/path/to/web_agents/apache_agent/Agent_001/config ...DONE.

Removing Agent parameters from /path/to/apache20/conf/httpd.conf file

Uninstall log file location:

/path/to/web_agents/apache_agent/installer-logs/audit/uninstall.log

...</screen>

</section>

</chapter>