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

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

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 Tomcat Policy Agent</title>

<indexterm><primary>Apache Tomcat Server</primary></indexterm>

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

Tomcat.</para>

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

<title>Before You Install</title>

<para>Make sure OpenAM is installed and running, and 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 Tomcat before you install the policy

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

<para>All of the Tomcat scripts must be present in

<filename>$CATALINA_HOME/bin</filename>. The Tomcat Windows executable

installer does not include the scripts, for example. If the scripts

are not present in your installation, copy the contents of the

<filename>bin</filename> directory from a .zip download of Tomcat of

the same version as the one you installed.</para>

<para>You must install a Java 6 runtime environment, and set the

<literal>JAVA_HOME</literal> environment variable.</para>

<screen>$ echo $JAVA_HOME

/path/to/java1.6

$ 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 J2EE

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

under this directory.</para>

<variablelist>

<para>When you unzip the policy agent, you find the following directories

under the <filename>j2ee_agents/tomcat_v6_agent</filename> directory.</para>

<para>Despite the directory name, the policy agent supports

<?eval ${agentTomcatSupport}?>.</para>

<varlistentry>

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

<listitem>

<para>The installation and configuration program,

<command>agentadmin</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>Configuration templates 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 J2EE policy agent</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

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

</listitem>

</varlistentry>

<varlistentry>

<term><filename>sampleapp</filename></term>

<listitem>

<para>Sample application that demonstrates key features of the policy

agent. Wait until you have installed the agent to deploy this.</para>

</listitem>

</varlistentry>

</variablelist>

</section>

<section xml:id="install-tomcat-agent">

<title>Installing the Tomcat Policy Agent</title>

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

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

<title>To Create the Tomcat 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; J2EE,

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 URL to the J2EE application 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-tomcat-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-tomcat">

<title>To Install the Policy Agent into Tomcat</title>

<step>

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

agent.</para>

<screen>$ /path/to/tomcat/bin/shutdown.sh</screen>

</step>

<step>

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

</step>

<step>

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

<screen>$ /path/to/j2ee_agents/tomcat_v6_agent/bin/agentadmin --install

...

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

SUMMARY OF YOUR RESPONSES

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

Tomcat Server Config Directory : /path/to/tomcat/conf

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

$CATALINA_HOME environment variable : /path/to/tomcat

Tomcat global web.xml filter install : true

Agent URL : http://www.example.com:8080/agentapp

Agent Profile name : Tomcat Agent

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

...

SUMMARY OF AGENT INSTALLATION

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

Agent instance name: Agent_001

Agent Bootstrap file location:

/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/config/

<?eval ${agentsBootstrapFile}?>

Agent Configuration file location

/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/config/

<?eval ${agentsConfigurationFile}?>

Agent Audit directory location:

/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/audit

Agent Debug directory location:

/path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug

Install log file location:

/path/to/j2ee_agents/tomcat_v6_agent/installer-logs/audit/install.log

...</screen>

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

configuration to Tomcat's 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 <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>j2ee_agents/tomcat_v6_agent/Agent_001/</filename>.</para>

<variablelist>

<varlistentry>

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

<listitem>

<para>Used to bootstrap the J2EE 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 J2EE 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>debug.out</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 performance="optional">

<para>If you choose not to let the installer install a global filter in

Tomcat's <filename>web.xml</filename>, then you must add the filter

manually for each protected application's <filename>web.xml</filename>

configuration, following the opening &lt;web-app&gt; tag. The file for

the sample application delivered with the agent is

<filename>/path/to/j2ee_agents/tomcat_v6_agent/sampleapp/etc/web.xml</filename>.</para>

<programlisting language="xml"> &lt;filter&gt;

&lt;filter-name&gt;Agent&lt;/filter-name&gt;

&lt;display-name&gt;Agent&lt;/display-name&gt;

&lt;description&gt;OpenAM Policy Agent Filter&lt;/description&gt;

&lt;filter-class&gt;com.sun.identity.agents.filter.AmAgentFilter&lt;/filter-class&gt;

&lt;/filter&gt;

&lt;filter-mapping&gt;

&lt;filter-name&gt;Agent&lt;/filter-name&gt;

&lt;url-pattern&gt;/*&lt;/url-pattern&gt;

&lt;dispatcher&gt;REQUEST&lt;/dispatcher&gt;

&lt;dispatcher&gt;INCLUDE&lt;/dispatcher&gt;

&lt;dispatcher&gt;FORWARD&lt;/dispatcher&gt;

&lt;dispatcher&gt;ERROR&lt;/dispatcher&gt;

&lt;/filter-mapping&gt;</programlisting>

</step>

<step>

<para>Add the agent application web archive to Tomcat's webapps.</para>

<para>$ cp /path/to/j2ee_agents/tomcat_v6_agent/etc/agentapp.war

/path/to/tomcat/webapps/</para>

</step>

<step>

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

<screen>$ /path/to/tomcat/bin/startup.sh</screen>

</step>

</procedure>

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

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

<step>

<para>Check the Tomcat server log after you start the server to make

sure startup completed successfully.</para>

<screen>$ tail -n 1 /path/to/tomcat/logs/catalina.out

INFO: Server startup in 810 ms</screen>

</step>

<step>

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

the agent did start up.</para>

<screen>$ tail -n 7 /path/to/j2ee_agents/tomcat_v6_agent/Agent_001/logs/debug/debug.out

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

Version: ...

Revision: 3111

Build Date: 20120915

Build Machine: builds.forgerock.org

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

</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="silent-tomcat-agent-installation">

<title>Silent Tomcat Policy Agent Installation</title>

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

</section>

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

<title>Remove Tomcat Policy Agent Software</title>

<para>Shut down the Tomcat server before you uninstall the

policy agent.</para>

<screen>$ /path/to/tomcat/bin/shutdown.sh</screen>

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

--uninstall</command>. You must provide the Tomcat server configuration

directory location.</para>

<para>Uninstall does not remove the agent instance directory, but you can

do so manually after removing the agent configuration from Tomcat.</para>

</section>

</chapter>