OpenAM Web Policy Agent Installation Guide
Chapter 7. Installing the Varnish Policy Agent

Procedure 7.5. To Install the Varnish Policy Agent

1. Stop Varnish.

   $ sudo service varnish stop

2. Make sure OpenAM is running.

3. Run ./agentadmin to install the agent.

   $ cd /path/to/web_agents/varnish/bin/
   $ ./agentadmin

   	Note
   	If the agent is in a different domain than the server, refer to the Administration Guide chapter, Configuring Cross-Domain Single Sign On.

4. Accept the ForgeRock Web Policy Agent License. Select Configure Varnish Web Policy Agent instance from the subsequent window.

5. Click on Configure Varnish Web Policy Agent instance and enter the following information for each consecutive screen.

   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.

   • URL where the OpenAM server runs

     Enter URL where the OpenAM server is running:
        http://openam.example.com:8080/openam

   • Agent URL that protects the web container

     Enter URL where Agent is protecting the Web Container:
        http://www.website.example.com:80

   • Profile ID and password

     Enter the Agent profile attributes in the OpenAM server:
        Profile ID: webagent
        Password: cangetin

   • Path to Varnish modules directory

     Enter the path to Varnish modules directory    
        /usr/lib/varnish/vmods

   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.

   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

6. Encrypt the password if you want additional security.

   	Note
   	The new agent appears as agent_1. You can return to this screen at any time by running /path/to/web_agents/varnish/bin/agentadmin to remove it.

7. Exit the screen.

8. Take note of the configuration files and log locations.

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

   config/OpenAMAgentBootstrap.properties

   Used to bootstrap the web policy agent, allowing the agent to connect to OpenAM and download its configuration

   config/OpenAMAgentConfiguration.properties

   Only used if you configured the web policy agent to use local configuration

   logs/audit/

   Operational audit log directory, only used if remote logging to OpenAM is disabled

   logs/debug/

   Debug directory where the amAgent debug file resides. Useful in troubleshooting policy agent issues.

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

10. Setup the backend by updating the following lines in the VLC script. Make sure port and host are set correctly.

    $ vi /path/to/web_agents/varnish/instances/agent_1/config/am.vcl
     import am;
     backend default {
     .host = "127.0.0.1";
     .port = "8080";
     }

11. Start Varnish with the following command. It will also load the VLC script.

    varnishd -u root -F -T localhost:8080 -f
      /path/to/web_agents/varnish/instances/agent_1/config/am.vcl -a :80 -s malloc,50M

Procedure 7.6. To Check the Policy Agent Installation

1. Check the Varnish error log after you start the server to make sure startup completed successfully.

2. Check the amAgent debug log to verify that no errors occurred on startup.

   $ 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: ==============...=====

3. 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 demo, password changeit. After you authenticate, OpenAM then redirects you back to the resource you tried to access.