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

<chapter xml:id='chap-sun-websvr'

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 Sun Web Server Policy Agent</title>

<indexterm><primary>Sun Web Server</primary></indexterm>

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

Web Server.</para>

<section xml:id="before-sjsws-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/sjsws_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>Not used</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-sjsws-web-agent">

<title>Installing Sun Web Server Web Policy Agent</title>

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

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

<title>To Create the Sun Web Server 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-sjsws-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-sjsws">

<title>To Install the Policy Agent into Sun Web Server</title>

<step>

<para>Shut down Sun Web Server instance where you plan to install the

agent.</para>

</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/web_agents/sjsws_agent/bin/agentadmin --install

...

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

SUMMARY OF YOUR RESPONSES

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

Sun Java System Web Server Config Directory :

/path/to/webserver7/https-www.example.com/config/

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

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

Agent Profile name : Sun Web Server 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/sjsws_agent/Agent_001/config/

<?eval ${agentsBootstrapFile}?>

Agent Configuration Tag file location

/path/to/web_agents/sjsws_agent/Agent_001/config/

<?eval ${agentsConfigurationFile}?>

Agent Audit directory location:

/path/to/web_agents/sjsws_agent/Agent_001/logs/audit

Agent Debug directory location:

/path/to/web_agents/sjsws_agent/Agent_001/logs/debug

Install log file location:

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

...</screen>

<para>Upon successful completion, the installer has backed up and updated

the Sun Web Server instance configuration, and has 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>web_agents/sjsws_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 log directory. 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>Set up ownership of the log directory. The default is to run as a

webservd user instead of root. To post its logs, the agent needs permission to

add the files to the directory.</para>

<screen>chown -R webservd:webservd /opt/web_agents/sjsws_agent/Agent_<replaceable>number</replaceable>/logs</screen>

</step>

<step>

<para>Restart the Sun Web Server instance where you installed the

agent.</para>

</step>

<step>

<para>Check that the agent protects the web site.</para>

<para>If you have not yet configured any policies to allow access, then

you should receive an HTTP 403 Forbidden error. In the above example, when

accessing <literal>http://www.example.com:8080/</literal>, the content of

the page returned appears in the browser as follows.</para>

<literallayout><emphasis role="strong">Forbidden</emphasis>

Your client is not allowed to access the requested object.</literallayout>

<para>If it appears the protection is inadequate, complete one of the

following steps.</para>

<note>

<para>A potential cause for the protection failing is updates to the

<filename>server.xml</filename> file for the <literal>object-file</literal>

property. A <literal>object-file</literal> property refers to the

<literal>obj.conf</literal> file created during the web server installation.

Multiple servers create their own <literal>obj.conf</literal> files, which can

cause problems with protection. Also, admin changes can update the

<literal>obj.conf</literal> file. For more information, checkout the <link

xlink:show="new" xlink:href="http://docs.oracle.com/cd/E19146-01/821-1827/abvag/index.html">

<citetitle>Syntax and Use of obj.conf</citetitle></link>.</para>

</note>

<stepalternatives>

<step>

<para>This step removes the <filename>obj.conf</filename> file if it is

not needed.</para>

<para>Open the <filename>server.xml</filename> and remove the <literal>object-file</literal>

property. The web server will use the default <filename>obj.conf</filename>

configuration.</para>

<note>

<para>Do not change the original file.</para>

</note>

<screen>$ vi /path/to/webserver7/config/server.xml

&lt;virtual-server&gt;

&lt;name&gt;virtual.example.com&lt;/name&gt;

&lt;http-listener-name&gt;http-listener-1&lt;/http-listenername&gt;

&lt;host&gt;virtual.example.com&lt;/host&gt;

- &lt;object-file&gt;virtual.example.com-obj.conf&lt;/object-file&gt;

&lt;document-root&gt;/path/to/webserver7/htdocs&lt;/document-root&gt;

&lt;name&gt;virtual.example.com&lt;/name&gt;

&lt;/virtual-server&gt;</screen>

</step>

<step>

<para>This step updates the <filename>obj.conf</filename> file if it

is needed.</para>

<para>Open the <filename>server.xml</filename> and manually update the

<literal>object-file</literal> property to validate the location of

the <filename>obj.conf</filename> file.</para>

<note>

<para>Do not change the original file.</para>

</note>

<screen>$ vi /path/to/webserver7/config/server.xml

&lt;Object path="*/dummypost/sunpostpreserve*"&gt;

Service type=text/* method=(GET) fn=append_post_data

&lt;/Object&gt;

&lt;Object path="*/UpdateAgentCacheServlet*"&gt;

Service type=text/* method=(POST) fn=process_notification

&lt;/Object&gt;</screen>

</step>

</stepalternatives>

</step>

<step>

<para>Save the file and restart the Sun Web Server.</para>

</step>

</procedure>

</section>

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

<title>Custom Sun Web Policy Agent Installation</title>

<para>For alternative installations, 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-sjsws-agent">

<title>Remove Sun Web Policy Agent Software</title>

<para>Shut down the Sun Web Server before you uninstall the

policy agent.</para>

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

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

</section>

</chapter>