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

<chapter xml:id='chap-varnish'

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

<indexterm><primary>Varnish HTTP Accelerator</primary></indexterm>

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

HTTP Accelerator 3.0.3.</para>

<para>Varnish is unlike the other policy agents supported for OpenAM. It does

not require the Java environment necessary for the other policy agents, and it has

a unique set of instructions for the agentadmin command. Varnish uses a directory

called vmods. This is the location where you will need to handle any required

installation or Varnish updates, and it requires the user to have administrative

rights to update this directory for changes to take effect. You can also configure

your Varnish instance using the Varnish Configuration Language (VCL) file.</para>

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

<title>Before You Install</title>

<para>You need to setup your container and OpenAM before installing

the web agent.</para>

<itemizedlist>

<listitem>

<para>Install the server.</para>

</listitem>

<listitem>

<para>Create and delegating an agent profile.</para>

</listitem>

<listitem>

<para>Download and prepare the policy agent for installation.</para>

</listitem>

</itemizedlist>

<procedure xml:id="varnish-server">

<title>Installing the server</title>

<step>

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

</step>

<step>

<para>Contact OpenAM from the system running the policy agent.</para>

</step>

<step>

<para>Install the Varnish HTTP Accelerator.</para>

</step>

</procedure>

<procedure xml:id="create-varnish-agent-profile1f">

<title>Creating a Policy Agent Profile</title>

<indexterm>

<primary>Policy agents</primary>

<secondary>Creating profiles</secondary>

</indexterm>

<para>To create a new web agent profile, you need a name and password, and the

URLs to OpenAM and the application to protect. 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.</para>

<mediaobject xml:id="figure-new-web-agent">

<alt>Diagram of web policy agent use</alt>

<imageobject>

<imagedata fileref="images/new-web-agent.png" format="PNG" />

</imageobject>

<textobject>

<para>The page for new web agents.</para>

</textobject>

</mediaobject>

<para>Use the following information to help you with the form.</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>

<step>

<para>After creating the agent profile, you can click the link to the

new profile to adjust and export the configuration.</para>

</step>

</procedure>

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

<title>To Create the Password File for Customized Installations</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="prepare-web-policy-agent">

<title>Preparing the Agent for Installation</title>

<step>

<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.</para>

</step>

<step>

<para>Verify the checksum of the file you download against the checksum

posted on the download page.</para>

</step>

<step>

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

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

under this directory.</para>

</step>

</procedure>

</section>

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

<title>Installing Varnish Web Policy Agent</title>

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

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

<title>To Install the Varnish Policy Agent</title>

<step>

<para>Stop Varnish.</para>

<screen>$ sudo service varnish stop</screen>

</step>

<step>

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

</step>

<step>

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

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

$ /agentadmin</screen>

<note>

<para>If the agent is in a different domain than the server, refer to the <citetitle>Administration Guide</citetitle> chapter, <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>Accept the ForgeRock Web Policy Agent License. Select Configure Varnish

Web Policy Agent instance from the subsequent window.</para>

</step>

<step>

<para>Click on Configure Varnish Web Policy Agent instance and enter the

following information for each consecutive screen.</para>

<para>Press F3 to move to the next field, or F2 to return to the previous

field to make a correction. Be careful as you make your entires, backspace will

erase the entire entry, not just the last character.</para>

<itemizedlist>

<listitem>

<para>URL where the OpenAM server runs</para>

<screen>Enter URL where the OpenAM server is running:

http://openam.example.com:8080/openam</screen>

</listitem>

<listitem>

<para>Agent URL that protects the web container</para>

<screen>Enter URL where Agent is protecting the Web Container:

http://www.website.example.com:80</screen>

</listitem>

<listitem>

<para>Profile ID and password</para>

<screen>Enter the Agent profile attributes in the OpenAM server:

Profile ID: webagent

Password: cangetin</screen>

</listitem>

<listitem>

<para>Path to Varnish modules directory</para>

<screen>Enter the path to Varnish modules directory

/usr/lib/varnish/vmods</screen>

</listitem>

</itemizedlist>

<para>Once you have configured your agent, you will get a page displaying

the agent configuration results. Verify the information. Click F4 when you

are done.</para>

<screen>Agent configuration results:

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

Agent URL: http://website.example.com

Profile: webagent

WebServer configuration:

/opt/webagent/web_agents/varnish/bin/instances/agent_1/config/am.vcl</screen>

</step>

<step>

<para>Encrypt the password if you want additional security.</para>

<note>

<para>The new agent appears as <literal>agent_1</literal>. You can return

to this screen at any time by running <literal>/path/to/web_agents/varnish/bin/agentadmin</literal>

to remove it.</para>

</note>

</step>

<step>

<para>Exit the screen.</para>

</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>/path/to/web_agents/varnish/instances/agent_1/</filename>.</para>

<variablelist>

<varlistentry>

<term><filename>config/OpenAMAgentBootstrap.properties</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/OpenAMAgentConfiguration.properties</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/OpenAMAgentBootstrap.properties 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>Setup the backend by updating the following lines in the VLC script.

Make sure port and host are set correctly.</para>

<screen>$ vi /path/to/web_agents/varnish/instances/agent_1/config/am.vcl

import am;

backend default {

.host = "127.0.0.1";

.port = "8080";

}</screen>

</step>

<step>

<para>Start Varnish with the following command. It will also load the

VLC script.</para>

<screen>varnishd -u root -F -T localhost:8080 -f

/path/to/web_agents/varnish/instances/agent_1/config/am.vcl -a :80 -s malloc,50M</screen>

</step>

</procedure>

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

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

<step>

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

sure startup completed successfully.</para>

</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/varnish/instances/agent_1/logs/debug/amAgent

2011-09-03 13:28:16.971 -1 32686:9daae60 all: ==============...=====

2011-09-03 13:28:16.972 -1 32686:9daae60 all: Version: ...

2011-09-03 13:28:16.972 -1 32686:9daae60 all: Revision: ...

2011-09-03 13:28:16.972 -1 32686:9daae60 all: Build Date: ...

2011-09-03 13:28:16.972 -1 32686:9daae60 all: Build Machine: ..forgerock.com

2011-09-03 13:28:16.972 -1 32686:9daae60 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-varnish-agent-installation">

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

<para>Varnish is unique because modifications are done in Command Line Mode

where you can use it to create a new server configuration template/vcl file,

such as instance/agent_1/config. This file is then used to start Varnish to

create the file or directory links to the Varnish vmods, where it will be

properly loaded when Varnish is started.</para>

<itemizedlist>

<para>You can use the following commands for customizing your Varnish policy

agent.</para>

<listitem>

<para><literal>agentadmin -l</literal></para>

<para>Lists all of the agent instances</para>

</listitem>

<listitem>

<para><literal>agentadmin -r agent_1</literal></para>

<para>Removes the agent_1 instance create in the example</para>

</listitem>

<listitem>

<para><literal>agentadmin -e password</literal></para>

<para>Encrypts the password using an base64 output for the encoded password

and encryption key</para>

</listitem>

<listitem>

<para><literal>agentadmin -o openamurl -a agenturl -i agent_profile_id

-p /path/to/passwordfile -c /usr/lib/varnish/vmods</literal></para>

<para>Creates the agent instance with the configuration parameters. Based on

the examples in the procedures, you would get the following:</para>

<itemizedlist>

<listitem>

<para>openamurl for the OpenAM server at <literal>http://openam.example.com:80/openam</literal></para>

</listitem>

<listitem>

<para>agenturl of the Agent server url is <literal>http://www.website.example.com:80</literal></para>

</listitem>

<listitem>

<para>agent_profile is the agent profile name shown in OpenAM</para>

</listitem>

<listitem>

<para>/path/to/passwordfile is the path where you saved the agent profile

password file</para>

</listitem>

<listitem>

<para>/path/to/varnish/vmod is the path to the Varnish vmods directory

<literal>/usr/lib/varnish/vmods</literal></para>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<para><literal>agentadmin -v</literal></para>

<para>View the version</para>

</listitem>

<listitem>

<para><literal>agentadmin -?</literal></para>

<para>Displays a list of all possible options supported by Varnish</para>

</listitem>

</itemizedlist>

</section>

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

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

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

policy agent.</para>

<screen>$ sudo service varnish stop</screen>

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

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

$ /agentadmin</screen>

<para>Scroll down and select Remove <replaceable>'agent'</replaceable> instance.</para>

</section>

</chapter>