Previous     Contents     Next     
iPlanet Policy Agent Pack Installation Guide



Chapter 2   URL Policy Agents for Solaris 8


iPlanet URL policy agents work in tandem with iPlanet Directory Server Access Management Edition (DSAME) to grant or deny user access to Web Servers in an enterprise. The iPlanet Policy Agent Pack 1.0 provides a set of URL policy agents for use with various web and proxy servers. This chapter explains how to install and configure the URL policy agents for servers running on the Solaris 8 operating system.

Topics include:



Supported Solaris Web Servers

Policy Agent Pack 1.0 supports the following servers running on the Solaris 8 operating system:

  • iPlanet Web Server 6.0 SPx

  • iPlanet Web Server 4.1 SP8

  • iPlanet Proxy Server 3.6

  • Apache 1.3.12



Before You Begin

Be sure that you are familiar with the concepts presented in Chapter 1 "Read This First" on page 11. The chapter includes brief but important information on the following topics:



Using the Graphical User Interface (GUI) Version of the Installation Program

The GUI version of the Installation program allows you to install only one policy agent at a time.


Installing a Web Server Policy Agent

Use these instructions for installing agents on the following servers using the Solaris 8 operating system:

  • iPlanet Web Server 4.1

  • iPlanet Web Server 6.0

  • Apache Web Server 1.3.12


To Install a Web Server URL Policy Agent

You must have root permissions when you run the agent Installation program. Be sure all web browsers are closed before starting the installation program.

  1. Unpack the product binaries file using the following command:

      # gunzip -dc agents-1.0-domestic-us.sparc-sun-solaris2.8.tar.gz | tar -xvof -

  2. Run the setup program. You'll find the program in the directory where you untarred the binaries file. At the command line, enter the following:

    # ./setup

  3. In the Welcome page, click Next.

  4. Read the License Agreement. Click Yes to agree to the license terms.

  5. When prompted, provide the following information about the Web Server this agent will protect:

    Install DSAME agent in this directory: Enter the full path to the directory where you want this agent to be installed, and then click Next.

    Select the desired component: Mark the checkbox of the agent you want to install, and then click Next. Note that only one agent can be installed at a time.

    Host Name: Enter the fully qualified domain name of the machine where the remote Web Server is installed. For example, mycomputer.iplanet.com.

    Web Server Instance Directory: This prompt displays only if you have selected the Web Server agent. Specify the Web Server instance that this agent will protect. Enter the full path to the directory where the Web Server instance is installed. Example: /web_server_root/https-hostname.com.

    Apache Config File Location: This prompt displays only if you've selected the Apache Web Server agent. Specify the Web Server that this agent will protect. Enter the full path to the directory where the httpd.conf file is located.

    Web Server Port: Enter the port number for the Web Server that will be protected by the agent.

    Web Server Protocol: If the Web Server has been configured for SSL, choose HTTPS; otherwise choose HTTP.

    Agent Deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) is /amagent.

    The URI prefix tells the Web Server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the Web Server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the Web Server Document Root.

    When all the information is entered correctly, click Next.

  6. Enter information about the Web Server that runs DSAME policy and management services. The URL Policy Agent will connect to this server.

    DSAME Services Host: Enter the fully qualified domain name of the computer system where the primary Web Server that runs DSAME services is installed. For example, myserver.iplanet.com.

    DSAME Services Port: Enter the port number for Web Server that runs DSAME services.

    DSAME Services Protocol: If the Web Server that runs DSAME services is SSL-enabled, select HTTPS; otherwise select HTTP.

    DSAME Services Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.

    Failover Server Host: Enter the fully qualified domain name for the secondary Web Server that will run DSAME services if the primary Web Server becomes unavailable. If no failover host exists, then leave this field blank.

    Failover Server Port: Enter the port number of the secondary Web Server that runs DSAME services. If no failover host exists, then leave this field blank.

    Password: Enter the password for the user amAdmin.

    When all the information is entered correctly, click Next.

  7. Review the Installation Summary to be sure that the information you've entered is correct. If you want to make changes, click Back. If all the information is correct, click Next

  8. In the Ready to Install page, click Install Now.

  9. When the installation is complete, you can click Details to view details about the installation, or click Exit to end the Installation program.

  10. You must restart your iPlanet Web Server or Apache Web Server for the installation to be complete.


Installing a Proxy Server URL Policy Agent

Use these instructions for installing a URL Policy Agent on iPlanet Proxy Server using the Solaris 8 operating system.


To Install a Proxy Server URL Policy Agent

You must have root permissions when you run the agent Installation program. Be sure all web browsers are closed before starting the installation program.

  1. Unpack the product binaries file using the following command:

      # gunzip -dc agents-1.0-domestic-us.sparc-sun-solaris2.8.tar.gz | tar -xvof -

  2. Run the setup program. You will find the program in the directory where you untarred the binaries file. At the command line, enter the following:

    # ./setup

  3. In the Welcome page, click Next.

  4. Read the License Agreement. Click Yes to agree to the license terms.

  5. To search for the directory where you would like to install the agent, click Browse. To accept the default, click Next.

  6. Select the component DSAME Agent for iPlanet Proxy Server 3.6, and then click Next. Note that only one component can be installed at a time.

  7. When prompted, provide the following information about the Web Server where this agent will be installed:

    Host Name: Enter the fully qualified domain name of the computer system where the remote Web Server is installed. For example, mycomputer.iplanet.com.

    Proxy Server Install Location: Enter the full path to the directory where the iPlanet Proxy Server is installed.

    Proxy Server Port: Enter the port number for the Proxy server instance. If you login to Proxy Server on the local machine as admin, you can click on the Proxy Server instance and check the port number.

    Agent Deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) is /amagent.

    The URI prefix tells the Web Server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the Web Server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the Web Server Document Root.

    When all the information is entered correctly, click Next.

  8. When prompted, provide the following information about the Web Server that runs DSAME services.

    DSAME Services Host: Enter the fully qualified domain name of the computer system where the primary Web Server that runs DSAME services is installed. For example, myserver.iplanet.com.

    DSAME Services Port: Enter the port number for the primary Web Server that runs DSAME services.

    DSAME Services Protocol: If the Web Server that runs DSAME services has been configured for SSL select HTTPS; otherwise select HTTP.

    DSAME Services Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.

    Failover Server Host: Enter the fully qualified domain name for the secondary Web Server that will run DSAME services if the primary Web Server becomes unavailable. If no failover host exists, then leave this field blank.

    Failover Server Port: Enter the port number of the secondary Web Server that will run DSAME services. If no failover host exists, then leave this field blank.

    Password: Enter the password for the user amAdmin.

    When all the information is entered correctly, click Next.

  9. Click Install Now.

  10. When the installation is complete you may review the details or click Exit.

  11. Restart the Proxy Server.

    If there is a failure in the installation, a file is created in /var/sadm/install/logs directory which is popped up in a window. You can look into this file for possible errors.


Disabling and Uninstalling a URL Policy Agent

If you don't want to use a URL policy agent, you can disable it or uninstall it. You can disable the URL policy agent by modifying the Web Server configuration files. To uninstall an agent, you must run the Installation program.


To Uninstall a URL Policy Agent

  1. In the directory where the agent is installed, at the command line, enter the following command:

    # java uninstall_DSAME_Agent

  2. Click Next on Welcome Panel.

  3. On Type of Install Panel, select Full.

  4. Click Uninstall Now.

  5. Click Exit after uninstallation is complete.


To Disable a URL Policy Agent Installed on Web Server 6.x

  1. In the file obj.conf, remove or comment out lines containing the following strings:

    • web_agent_init

    • validate_session_policy

  2. Restart the Web Server.


To Disable a URL Policy Agent Installed on Web Server 4.x

  1. In the file magnus.conf, remove or comment out lines containing the following strings:

    • web_agent_init

    • validate_session_policy

  2. Restart the Web Server.


To Disable a URL Policy Agent Installed on Apache 1.3.12

  1. In the file httpd.conf remove or comment out the following line:

    include /<httpd.conf-location>/dsame.conf

For example:

# include /etc/apache/dsame.conf

  1. Restart the server.



Using the Command-Line Version of the Installation Program

The command-line version of the Installation program provides you an alternative to the graphical user interface (GUI) version.


To Install an Agent Using the Command Line

  1. In the directory where you unpacked the binaries file, at the command line, enter the following:

      # java agent_sol -nodisplay

  2. When prompted, provide the following information:

    Have you read, and do you accept, all of the terms of the preceding Software License Agreement? Enter yes.

    Install DSAME Agent in this directory: Enter the full path to the directory in which you want to install the policy agent.

    The following text displays:

    [ ] 1 DSAME Agent for iPlanet Web Server 6.0 SPx
    [ ] 2 DSAME Agent for iPlanet Web Server 4.1 SP8
    [ ] 3 DSAME Agent for iPlanet Proxy Server 3.6
    [ ] 4 DSAME Agent for Apache 1.3.12
    DSAME Agent components showing a checked box will be installed. Only one agentmay be installed at a time.

    To check a particular component, enter its number, or 0 when you are finished: Enter the number that corresponds to the policy agent you want to install. The following message displays, with a checkmark beside the server your specified.

[X] _1 DSAME Agent for iPlanet Web Server 6.0 SPx
[ ] 2 DSAME Agent for iPlanet Web Server 4.1 SP8
[ ] 3 DSAME Agent for iPlanet Proxy Server 3.6
[ ] 4 DSAME Agent for Apache 1.3.12

To check a particular component, enter its number, or 0 when you are finished: Enter 0 to continue.

  1. Provide information about the iPlanet Web Server this agent will protect.

    Host Name: Enter the full path and host name of the Web Server the agent will protect.

    Web server Port: Enter the port number of the Web Server where the agent is installed.

    Web Server Protocol: If the Web Server where the agent is installed is SSL-enabled, enter https. If it is not SSL-enabled, enter http.

    iPlanet Web Server Instance Directory: Enter the full path and instance name of the Web Server the agent will protect. Example:

    /web_server_root/https-madisonparc.com

    Agent Deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) is /amagent.

    The URI prefix tells the Web Server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the Web Server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the Web Server Document Root.

  2. Provide information about the Web Server that runs DSAME Services. The following fields refer to the computer system where DSAME is installed.

    Host Name: Enter the host name or IP address of the computer system where DSAME is installed (Examples: 29.153.345.89 or blue.madisonparc.com).

    Port Number: Enter the port number for the Web Server that runs DSAME Services.

    Protocol: Enter HTTPS if the Web Server that runs DSAME services is SSL-enabled. Enter HTTP if it is not SSL-enabled.

    Deployment URI: Enter the location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) is /amserver.

    Failover Host: If you have configured a failover Web Server to run DSAME Services, enter the IP address or host name of the failover computer system. Examples: 29.153.345.89 or blue.madisonparc.com. If no failover server exists, then leave this field blank.

    Failover Port: If you have configured a failover Web Server to run DSAME Services, enter the Web Server port number. If no failover host servers, then leave this field blank.

    amAdmin Password: amAdmin is the DSAME Super Administrator and has unrestricted access and privileges. Enter the amAdmin user's password.

  3. The following text displays:

    Ready to Install

    1. Install Now
    2. Start Over
    3. Exit Installation

    When prompted, What would you like to do?, enter 1 to start the installation.


To Uninstall an Agent Using the Command Line

  1. In the directory where you unpacked the binaries file, at the command line, enter the following:

      # java uninstall_DSAME_Agent -nodisplay

  2. The following text displays:
    Please select the type of uninstall to perform from the following choices:
    1. Full
    2. Partial

    To remove the product and all of the components from your system, enter 1 for Full. To remove some, but not all, product components, enter 2 for Partial.

  3. The following text displays:
    Ready to Uninstall

    1. Uninstall Now
    2. Start Over
    3. Exit Uninstallation

    When prompted, What would you like to do? enter 1 to begin uninstallation.

  4. The following text displays:

    Product     Result  More Info
    1. DSAME Agent Full Available
    2. Done

    To see log information on the agent, enter 1. To exit the Installation program, enter 2.



Installing Multiple Web Server Agents on the Same Solaris Computer System

If you have multiple iPlanet Web Servers installed on one computer system, you can install a different agent for each server or server instance. Note that since only one iPlanet Proxy Server can be installed on a computer system, you cannot install multiple Proxy Server agents on the same computer system. The same principle is also true for Apache Web Server.

When installing multiple Web Server agents on the same computer system, use the graphical user interface (GUI) version of the Agent Installation program to install the only first agent. During this first installation, the Installation program also installs the package SUNWamagt.

When you install a second agent on the same computer system, to specify a different directory for a new SUNWamagt package, you must use the pkgadd command at the command line; do not use the GUI version of the Installation program for installing the second or any subsequent agents.

Note

This is not the same as simply changing the $BASEDIR value.



To Install Multiple Web Server Agents on the Same Computer System

You must have root permissions to perform these steps.

  1. Install an agent following the directions in Using the Graphical User Interface (GUI) Version of the Installation Program.

  2. At the command line, enter the following:

      # pkgadd -R install_directory -d path SUNWamagt

    where install_directory is the directory where you want to install the agent, and path is a full path to the SUNWamagt package you untarred with the Policy Agent Pack product. The install_directory you specify must be different from the directory where the initial SUNWamagt package is located. which is "/ ".

  3. When prompted, provide the following information:

    Enter the directory to install DSAME Agent Components: Enter the same base directory for the package. The package will be installed under the install_directory you specified in step 2. The real location where the packaged is installed is the concatenation of the install_directory and the base_directory.

    Enter the local hostname: Enter the fully qualified domain name of the host computer where the agent will be installed. Example: sales.madisonparc.com

    Install agent on: Specify the server the agent will protect.

    For iPlanet Web Server 6.0 SPx, enter 1.

    For iPlanet Web Server 4.1, enter 2.

    For iPlanet Proxy Server 3.6, enter 3.

    Enter the web server instance directory: Enter the full path and instance name of the Web Server this agent will protect. The instance name will include the prefix https-. Example: /web_server_root/https-instance_name.

    Enter the web server port: Enter the port number of the Web Server the agent will protect.

    Select the web server protocol: If the Web Server does not use Secure Sockets Layer (SSL) protocol, enter 1. If the Web Server uses SSL, enter 2.

    Enter the agent deployment URI: Enter a directory name. The default Universal Resource Identifier (URI) is /amagent.

    The URI prefix tells the Web Server where to look for HTML pages that need to be displayed. For example, when a user attempts to access a URL, but cannot provide proper credentials, the agent must display an "Access denied" message. The URI prefix tells the Web Server where to look for the HTML page that contains the message. A directory specified by this URI will be created in the Web Server Document Root.

    Enter the DSAME service host: Enter the fully qualified domain name of the Web Server that runs DSAME services. Example: sales.madisonparc.com.

    Enter the DSAME service port: Enter the port number for the Web Server that runs DSAME services.

    Select the DSAME service protocol: If the Web Server that runs DSAME services is not SSL-enabled, then enter 1. If it is SSL-enabled, then enter 2.

    Enter the DSAME deployment URI: Enter the default location that was specified when DSAME was installed. The default Universal Resource Identifier (URI) for DSAME is /amserver.

    Enter the DSAME failover server host: Enter the fully qualified domain name for the secondary Web Server that will run DSAME services if the primary Web Server becomes unavailable. If no failover server exists, then leave this field blank.

    Enter the DSAME failover server port: Enter the port number for the secondary Web Server that will run DSAME services. If no failover server exists, then leave this field blank.

    Enter the amAdmin password: amAdmin is the Super Administrator for DSAME. Enter the password for this user.

    The selected base directory must exist before installation is attempted.Do you want this directory created now? If the installation directory is correct, enter y for Yes. If it is not correct, enter n for No.

    The following message displays:
    This package contains scripts which will be executed with super-user permission during the process of installing this package. Do you want to continue with the installation of <SUNWamagt>?

    Enter y for Yes; enter n for No.

  4. When installation is finished, you must restart your iPlanet Web Server for the installation to be complete.


    Note

    When you need to uninstall an agent that was installed using the pkgadd command, be sure to use the pkgrm command instead of the GUI Installation program.



To Remove an Agent Using the pkgrm Command

  1. At the command line, enter the following:

      # pkgrm -R install_directory SUNWamagt

    where install_directory is the directory where the agent you want to remove is installed. The following message displays:
    The following package is currently installed:
    SUNWamagt iPlanet Directory Server Access Management Edition 5.0 Agent

  2. When prompted, Do you want to remove this package? enter y for Yes.

    The following message displays:
    This package contains scripts which will be executed with super-user permission during the process of removing this package.

    Do you want to continue with the removal of this package?

    Enter y for Yes.



Using Secure Sockets Layer (SSL) with an Agent

You can configure a remote Web Server (with policy agent installed) to communicate over SSL with the Web Server that runs DSAME services. The SSL protocol consists of rules governing encrypted communication between servers and clients. The requests and transactions between the remote Web Server and the Web Server that runs DSAME services are encrypted when SSL is fully enabled. This protects the communication between the servers from intrusion by unauthorized entities.

During installation, if you choose the HTTPS protocol, the agent is automatically configured and ready to communicate over SSL. If you did not specify the HTTPS protocol during Installation, then follow the instructions in these next sections.


Note

Before proceeding with the following steps, you should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation that comes with your web server. If you're using iPlanet Web Server, you can access the following documentation on the Internet:

http://docs.iplanet.com/docs/manuals/enterprise/60sp1/ag/esecurty.htm#1011961



The Agent's Default Trust Behavior

By default, the a URL policy agent installed on a remote iPlanet Web Server 6.0 or Apache Server 1.3.12 will trust any server certificate presented over SSL by the Web Server that runs DSAME services; the agent does not check the root Certificate Authority (CA) certificate. If the Web Server that runs DSAME services is SSL-enabled, and you want the URL policy agent to perform certificate-checking, you must do two things:

  1. Disable the agent's default trust behavior.

  2. Install a root CA certificate on the remote Web Server (where the agent is installed). The root CA certificate must the be same one that is installed on the Web Server that runs DSAME service.


Disabling the Agent's Default Trust Behavior

The following property exists in the AMAgent.properites file, and by default it is set to true:

com.iplanet.am.policy.agents.trust_server_certs=true

This means that the agent does not perform certificate-checking.


To Disable the Default Behavior

The following property must be set to false:

com.iplanet.am.policy.agents.trust_server_certs=false


Installing the Root CA Certificate on the Remote Web Server

The root CA certificate that you install on the remote Web Server must be the same one that is installed on the Web Server that runs DSAME services.


To Install the Root CA Certificate on iPlanet Web Server

See the instructions for installing a root CA Certificate in the documentation that comes with the Web Server. Access the documentation for iPlanet Web Server 6.0 on the Internet at the following URL:

http://docs.iplanet.com/docs/manuals/enterprise/60sp1/ag/esecurty.htm#1011961.


To Install the Root CA Certificate on Apache 1.3.12

You can use the certutil program to install the root CA Certificate on Apache 1.3.12.

  1. In C shell, at the command line, enter the following:

      # cd /agent_root/SUNWam/apache1.3.12/cert

      # setenv LD_LIBRARY_PATH /agent_root/SUNWam/apache1.3.12/lib

      # ./certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

    using the following variables:

    • cert-name can be any name for this root certificate.

    • cert-dir is directory where the certificate-related files are located. On Solaris the location is httpd.conf-location/cert.

    • cert-file is the base-64 encoded root certificate file.

    For more information on the certutil utility, enter certutil -H for online Help.

  2. To verify that the certificate is properly installed, at the command line, enter the following:

      # ./certutil -L -d .

    Trust database information will display including the name of the root CA certificate you installed. Example:
    Certificate Name Trust Attributes

    rootCAcert CT,CT,CT

    p Valid peer
    P Trusted peer (implies p)
    c Valid CA
    T Trusted CA to issue client certs (implies c)
    C Trusted CA to certs(only server certs for ssl) (implies c)
    u User cert
    w Send warning


Previous     Contents     Next     
Copyright © 2002 Sun Microsystems, Inc.

Last Updated March 28, 2002