Chapter 5 Post-Installation Configuration: Policy Agent 2.2 for Apache HTTP Server

This chapter describes configuration and other post-installation considerations and tasks regarding Policy Agent 2.2 for Apache HTTP Server on the supported platforms as follows:

• All Systems: Configuring Agent for Apache HTTP Server on Multiple Apache HTTP Server Virtual Hosts

• Solaris Systems: Configuring Agent for Apache HTTP Server

• AIX Systems: Configuring Agent for Apache HTTP Server

• Linux Systems: Configuring Agent for Apache HTTP Server

• Windows Systems: Configuring Agent for Apache HTTP Server

This chapter covers a few configuration tasks of Policy Agent 2.2 for Apache HTTP Server. The major tasks covered are the configuration of the agent on multiple virtual hosts of Apache HTTP Server and the configuration of SSL with the agent. Perform the tasks described in this chapter if they apply to your site's deployment.

After completing the applicable tasks described in this chapter, perform the tasks to configure the web agent to your site's specific needs as explained in Chapter 6, Managing Policy Agent 2.2 for Apache HTTP Server.

All Systems: Configuring Agent for Apache HTTP Server on Multiple Apache HTTP Server Virtual Hosts

The task that follows applies to all platforms and provides an example of how to configure multiple virtual hosts. Therefore, if you are interested in configuring multiple instances of this agent, implement the task that follows.

To Enable Access to Multiple Virtual Hosts

For this task example, two virtual hosts are configured: http://site1.example.com and http://site2.example.com. These host names are only examples.

1. Define the FQDN map property in the web agent AMAgent.properties configuration file as follows:

   com.sun.am.policy.agents.config.fqdn.map = 
   valid1|site1.example.com,valid2|site2.example.com

2. Define policies in Access Manager with virtual host names in the policy rules.

Solaris Systems: Configuring Agent for Apache HTTP Server

This section provides task descriptions about using SSL for Solaris systems.

Solaris Systems: Using SSL With Agent for Apache HTTP Server

During installation, if you choose the HTTPS protocol, the Agent for Apache HTTP Server is automatically configured and ready to communicate over Secure Sockets Layer (SSL). Before proceeding with the tasks in this section, ensure that the Apache HTTP Server instance is configured for SSL.

---

Caution –

You should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation for Apache HTTP Server.

---

Default Trust Behavior of Agent for Apache HTTP Server on Solaris Systems

This section only applies when Access Manager itself is running SSL. By default, the web agent installed on a remote Apache HTTP Server instance trusts any server certificate presented over SSL by the Access Manager host. The web agent does not check the root Certificate Authority (CA) certificate. If the Access Manager host is SSL-enabled and you want the web agent to perform certificate checking, adhere to the guidelines as described in the following subsections:

• Disabling the Default Trust Behavior of Agent for Apache HTTP Server on Solaris Systems

• Installing the Access Manager Root CA Certificate for a Remote Apache HTTP Server Instance on Solaris Systems

Disabling the Default Trust Behavior of Agent for Apache HTTP Server on Solaris Systems

The following property in the web agent AMAgent.properties configuration file controls the agent’s trust behavior, and by default it is set to true:

com.sun.am.trust_server_certs

With this property set to true, the web agent does not perform certificate checking. On Solaris systems, setting this property to false is one of the steps involved in enabling the web agent to perform certificate checking as illustrated in the following task.

To Disable the Default Trust Behavior of Agent for Apache HTTP Server on Solaris Systems

1. Set the following property in the web agent AMAgent.properties configuration file to false as follows:

   com.sun.am.trust_server_certs = false

2. Set the directory Cert DB in the web agent AMAgent.properties configuration file as shown in the following example:

   com.sun.am.sslcert.dir = Apache-base/conf/cert

   where Apache-base represents the directory where Apache HTTP Server was installed.

3. (Conditional) Set the Cert DB Prefix.

   In cases where the specified Cert DB directory has multiple certificate databases, the following property must be set to the prefix of the certificate database to be used:

   com.sun.am.certdb.prefix

   Set the property in the following manner:

   com.sun.am.certdb.prefix = https-host.domain.com.host-

Installing the Access Manager Root CA Certificate for a Remote Apache HTTP Server Instance on Solaris Systems

The root CA certificate that you install on the remote instance of Apache HTTP Server must be the same one that is installed on the Access Manager host.

To Install the Access Manager Root CA Certificate on Apache HTTP Server on Solaris Systems

You can use the certutil program to install the root CA certificate on Apache HTTP Server.

1. Change directories to the location of the Apache HTTP Server configuration file.

   The following example is applicable for changing directories using the C shell when the Apache HTTP Server configuration file is in the default location of /etc/apache/:

   # /etc/apache/

2. Change to the cert directory.

3. Set the proper environment by issuing the following command:

   # setenv LD_LIBRARY_PATH PolicyAgent-base/SUNWam/agents/apache/lib:PolicyAgent-base/SUNWam/ agents/lib:/usr/lib/mps

4. (Conditional) If you have not already created the necessary certificate database, create that database now by issuing the following command:

   # PolicyAgent-base/SUNWam/agents/apache/cert/certutil -N -d .

5. Install root CA certificate by issuing the following command:

   # PolicyAgent-base/SUNWam/agents/apache/cert/certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

   cert-name

   The name for this root CA certificate

   cert-dir

   The directory where the certificate and key stores are located

   cert-file

   The base-64 encoded root CA certificate file.

   For more information on the cetrutil utility enter cetrutil -H for Help.

6. To verify that the certificate is properly installed, in the command line, issue the following command:

   # PolicyAgent-base/SUNWam/agents/apache/cert/certutil -L -d .

   The root CA certificate is then listed in the output of the certutil -L command as illustrated in the following code example:

   Certificate Name Trust Attrubutes cert-name C,C,C p Valid peer P Trusted peer (implies c) 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

7. Restart Apache HTTP Server.

AIX Systems: Configuring Agent for Apache HTTP Server

This section provides task descriptions for the following procedures:

• AIX Systems: Setting File Ownership and Permissions on Agent for Apache HTTP Server

• AIX Systems: Using SSL With Agent for Apache HTTP Server

After you check the file ownership and permissions (and reset if necessary), enable access to the proper libraries, and perform the procedure for verifying a successful installation. Next, determine if the remaining procedures described in this section apply to your site's deployment scenario. Perform the applicable procedures.

AIX Systems: Setting File Ownership and Permissions on Agent for Apache HTTP Server

On AIX systems, the Apache HTTP Server server must run as a non-root user. For example purposes in this section, the name apuser is used as the non-root user while apgroup is used as the name of the group.

To enable Agent for Apache HTTP Server to work properly, ensure that the non-root user has read permissions to the following files:

• /etc/opt/agents/apache/config/_PathInstanceName/AMAgent.properties

• /var/opt/agents/apache/debug/_PathInstanceName/amAgent

• PolicyAgent-base/agents/apache/lib/

PolicyAgent-base

represents the directory you choose in which to install the web agent

_PathInstanceName

represents a directory that is created and named during agent installation. This name is derived from the path to the Apache HTTP Server directory where slashes are converted to underscores. For this example, the path to the Apache HTTP Server directory is as follows:

/usr/local/apache2054

Based on the preceding path, during installation, the following _PathInstanceName directory would be created:

_user_local_apache2054_conf

You can set the required permissions to the files by issuing the following commands:

chown apuser:apgroup /etc/opt/agents/apache/config/_PathInstanceName
chown apuser:apgroup /var/opt/agents/apache/debug/_PathInstanceName/
chown apuser:apgroup PolicyAgent-base/agents/apache/lib/libamapc2.a

AIX Systems: Using SSL With Agent for Apache HTTP Server

During installation, if you choose the HTTPS protocol, Agent for Apache HTTP Server is automatically configured and ready to communicate over Secure Sockets Layer (SSL). Before proceeding with tasks in this section, ensure that the Apache HTTP Server instance is configured for SSL.

---

Caution –

You should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation for Apache HTTP Server.

---

Default Trust Behavior of Agent for Apache HTTP Server on AIX Systems

This section only applies when Access Manager itself is running SSL. By default, the web agent installed on a remote Apache HTTP Server instance trusts any server certificate presented over SSL by the Access Manager host. The web agent does not check the root Certificate Authority (CA) certificate. If the Access Manager host is SSL-enabled and you want the agent to perform certificate checking, adhere to the guidelines as described in the following subsections:

• Disabling the Default Trust Behavior of Agent for Apache HTTP Server on AIX Systems

• Installing the Access Manager Root CA Certificate for a Remote Apache HTTP Server Instance on AIX Systems

Disabling the Default Trust Behavior of Agent for Apache HTTP Server on AIX Systems

The following property in the web agent AMAgent.properties configuration file controls the agent’s trust behavior, and by default it is set to true:

com.sun.am.trust_server_certs

With this property set to true, the web agent does not perform certificate checking. On AIX systems, setting this property to false is one of the steps involved in enabling the web agent to perform certificate checking as illustrated in the following task.

To Disable the Default Trust Behavior of Agent for Apache HTTP Server on AIX Systems

1. Set the following property in the web agent AMAgent.properties configuration file to false as follows:

   com.sun.am.trust_server_certs = false

2. Set the directory Cert DB in the web agent AMAgent.properties configuration file as shown in the following example:

   com.sun.am.sslcert.dir = Apache-base/conf/cert

   where Apache-base represents the directory where Apache HTTP Server was installed.

3. Set the Cert DB Prefix, if required.

   In cases where the specified Cert DB directory has multiple certificate databases, the following property must be set to the prefix of the certificate database to be used:

   com.sun.am.certdb.prefix

   Set the property as follows:

   com.sun.am.certdb.prefix = https-host.domain.com.host-

Installing the Access Manager Root CA Certificate for a Remote Apache HTTP Server Instance on AIX Systems

The root CA certificate that you install on the remote instance of Apache HTTP Server must be the same certificate that is installed on the Access Manager host.

To Install the Access Manager Root CA Certificate on Apache HTTP Server on AIX Systems

The following steps outline a method for installing Access Manager Root CA Certificate on the Apache HTTP Server server. However, see the documentation for the Apache HTTP Server server for more information about installing certificates.

1. Change directories to the location of the Apache HTTP Server configuration file.

   The following example is applicable for changing directories using the C shell when the Apache HTTP Server configuration file is in the default location of Apache-base /conf/:

   # Apache-base/conf/

   where Apache-base represents the directory where Apache HTTP Server was installed.

2. Change to the cert directory.

   This cert directory is created by the agent installer.

3. Set the proper environment by issuing a command such as the following (using the tcsh shell, for example):

   # setenv LIBPATH PolicyAgent-base/agents/apache/lib:$LIBPATH

4. (Conditional) If you have not already created the necessary certificate database, create that database now by issuing the following command:

   # PolicyAgent-base/agents/bin/certutil -N -d .

5. Install root CA certificate by issuing the following command:

   # PolicyAgent-base/agents/bin/certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

   cert-name

   The name for this root CA certificate

   cert-dir

   The directory where the certificate and key stores are located

   cert-file

   The base-64 encoded root CA certificate file.

   For example, if the Root CA certificate of the Access Manager host is present in the current directory, which is Apache-base/conf/cert, and if the name of this certificate file is root_ca.crt, then execute the following command:

   /usr/local/apg/agents/bin/certutil -A -n am_root_ca_cert -t "C,C,C" -d . -i root_ca.crt

   For this example, PolicyAgent-base is /usr/local/apg.

   For more information on the cetrutil utility enter cetrutil -H for Help.

6. To verify that the certificate is properly installed, in the command line, issue the following command:

   # PolicyAgent-base/agents/bin/certutil -L -d .

   The root CA certificate is then listed in the output of the certutil -L command as illustrated in the following code example:

   Certificate Name Trust Attrubutes cert-name C,C,C p Valid peer P Trusted peer (implies c) 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

7. Restart Apache HTTP Server.

Linux Systems: Configuring Agent for Apache HTTP Server

This section provides task descriptions for Linux systems. Notice that the first task is specific to SUSE Linux. The tasks in this section are as follows:

• Agent for Apache HTTP Server on SUSE Linux: Obtaining the Required Libraries

• Linux Systems: Using SSL With Agent for Apache HTTP Server

Only perform a task if a respective condition applies.

Agent for Apache HTTP Server on SUSE Linux: Obtaining the Required Libraries

Agent for Apache HTTP Server supports SUSE Linux Enterprise 9 as described in Table 2–1. However, SUSE Linux Enterprise 9 does not contain certain shared libraries that are required by Agent for Apache HTTP Server. The following task describes how to make the required libraries available.

To Obtain the Libraries Required by SUSE Linux

1. Issue the following command:

   rpm --prefix=PolicyAgent-base -i common-2.2-0.i686.rpm

   This command installs the package common-2.2, which in turn installs the shared libraries from the agent binary.

   ---

   Note –

   If you install this agent again, you must perform this task again to make the required libraries available. Also, if you uninstall this agent you must remove the common-2.2 package as described in Agent for Apache HTTP Server on SUSE Linux: Removing the common-2.2 Package.

   ---

Linux Systems: Using SSL With Agent for Apache HTTP Server

During installation, if you chose the HTTPS protocol, the Agent for Apache HTTP Serveris automatically configured and ready to communicate over Secure Sockets Layer (SSL). Before proceeding with the tasks in this section, ensure that the Apache HTTP Server instance is configured for SSL.

---

Caution –

You should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation for Apache HTTP Server.

---

Default Trust Behavior of Agent for Apache HTTP Server on Linux Systems

This section only applies when Access Manager itself is running SSL. By default, the web agent installed on a remote Apache HTTP Server instance will trust any server certificate presented over SSL by the Access Manager host. The web agent does not check the root Certificate Authority (CA) certificate. If the Access Manager host is SSL-enabled and you want the agent to perform certificate checking, adhere to the guidelines as described in the following subsections:

• Disabling the Default Trust Behavior of Agent for Apache HTTP Server on Linux Systems

• Installing the Access Manager Root CA Certificate for a Remote Apache HTTP Server Instance on Linux Systems

Disabling the Default Trust Behavior of Agent for Apache HTTP Server on Linux Systems

The following property in the web agent AMAgent.properties configuration file controls the agent’s trust behavior, and by default it is set to true:

com.sun.am.trust_server_certs

With this property set to true, the web agent does not perform certificate checking. On Linux systems, enabling the web agent to perform certificate checking is a one-step process that only involves setting this property to false as illustrated in the following task.

To Disable the Default Trust Behavior of Agent for Apache HTTP Server on Linux Systems

1. Set the following property in the web agent AMAgent.properties configuration file to false as follows:

   com.sun.am.trust_server_certs = false

Installing the Access Manager Root CA Certificate for a Remote Apache HTTP Server Instance on Linux Systems

The root CA certificate that you install on the remote instance of Apache HTTP Server must be the same one that is installed on the Access Manager host.

To Install the Access Manager Root CA Certificate on Apache HTTP Server on Linux Systems

You can use the certutil program to install the root CA certificate on Apache HTTP Server.

1. Change directories to the location of the Apache HTTP Server configuration file.

   The following example is applicable for changing directories using the C shell when the Apache HTTP Server configuration file is in the default location of /etc/apache/:

   # /etc/apache/

2. Change to the cert directory.

3. Set the proper environment by issuing the following command:

   # setenv LD_LIBRARY_PATH PolicyAgent-base/agents/apache/lib:PolicyAgent-base/agents/lib:/usr/lib/mps

4. (Conditional) If you have not already created the necessary certificate database, create that database now by issuing the following command:

   # PolicyAgent-base/agents/apache/cert/certutil -N -d .

5. Install root CA certificate by issuing the following command:

   # PolicyAgent-base/agents/apache/cert/certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

   cert-name

   The name for this root CA certificate

   cert-dir

   The directory where the certificate and key stores are located

   cert-file

   The base-64 encoded root CA certificate file.

   For more information on the cetrutil utility enter cetrutil -H for Help.

6. To verify that the certificate is properly installed, in the command line, issue the following command:

   # PolicyAgent-base/agents/apache/cert/certutil -L -d .

   The root CA certificate is then listed in the output of the certutil -L command as illustrated in the following code example:

   Certificate Name Trust Attrubutes cert-name C,C,C p Valid peer P Trusted peer (implies c) 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

7. Restart Apache HTTP Server.

Windows Systems: Configuring Agent for Apache HTTP Server

This section provides task descriptions about using SSL for Windows systems.

Windows Systems: Using SSL With Agent for Apache HTTP Server

During installation, if you choose the HTTPS protocol, Agent for Apache HTTP Server is automatically configured and ready to communicate over SSL. Before proceeding with the tasks in this section, ensure that the Apache HTTP Server instance is configured for SSL.

---

Caution –

You should have a solid understanding of SSL concepts and the security certificates required to enable communication over the HTTPS protocol. See the documentation for the Apache HTTP Server server.

---

Default Trust Behavior of Agent for Apache HTTP Server on Windows Systems

This section only applies when Access Manager itself is running SSL. By default, Agent for Apache HTTP Server trusts any server certificate presented over SSL by the Access Manager host. The web agent does not check the root Certificate Authority (CA) certificate. If the Access Manager host is SSL-enabled and you want the agent to perform certificate checking, adhere to the guidelines as described in the following subsections:

• Disabling the Default Trust Behavior of Agent for Apache HTTP Server on Windows Systems

• Installing the Access Manager Root CA Certificate on Apache HTTP Server on Windows Systems

Disabling the Default Trust Behavior of Agent for Apache HTTP Server on Windows Systems

The following property exists in the web agent AMAgent.properties configuration file, and by default it is set to true:

com.sun.am.trust_server_certs

With this property set to true, the web agent does not perform certificate checking. On Windows systems, enabling the web agent to perform certificate checking is a one-step process that only involves setting this property to false as illustrated in the following task.

To Disable the Default Trust Behavior of Agent for Apache HTTP Server on Windows Systems

1. Set the following property in the web agent AMAgent.properties configuration file to false as follows:

   com.sun.am.trust_server_certs = false

Installing the Access Manager Root CA Certificate on Apache HTTP Server on Windows Systems

The root CA certificate that you install on the Apache HTTP Server instance that the agent protects must be the same certificate that is installed on the Access Manager host.

To Install the Access Manager Root CA Certificate on Apache HTTP Server on Windows Systems

The following steps outline a method for installing Access Manager Root CA Certificate on the Apache HTTP Server server. However, see the documentation for the Apache HTTP Server server for more information about installing certificates.

1. Change directories to the location of the Apache HTTP Server configuration file.

   The following example is applicable for changing directories using the CMD shell when the Apache HTTP Server configuration file is in the default location of c:\program files\apache group\apache2:

   # c:\program files\apache group\apache2

2. Change to the cert directory.

3. (Conditional) If the certificate database has not yet been created, create it at a unique location using a command such as the following:

   # PolicyAgent-base\bin\certutil -N -d .

4. Install the root CA certificate.

   Remember that the root CA certificate that you install on the Apache HTTP Server server must be the same certificate that is installed on the Access Manager host.

   The following example demonstrates a command you can issue that uses the certutil utility to install the certificate:

   # PolicyAgent-base\bin\certutil -A -n cert-name -t "C,C,C" -d cert-dir -i cert-file

   cert-name

   The name for this root CA certificate.

   cert-dir

   The directory where the certificate and key stores are located.

   cert-file

   The base-64 encoded root CA certificate file.

   For more information on the cetrutil utility enter cetrutil -H for Help.

5. To verify that the certificate is properly installed, in the command line, issue the following command:

   PolicyAgent-base\bin\certutil -L -d cert-dir

   The root CA certificate is then listed in the output of the certutil -L command as illustrated in the following code example:

   Certificate Name Trust Attrubutes cert-name C,C,C p Valid peer P Trusted peer (implies c) 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

6. Restart Apache HTTP Server.