Web Agents 2023.11.1

Install Apache or IBM HTTP Web Agent

Consider the following points before installing Apache or IBM HTTP Web Agent:

  • SELinux can prevent the web server from accessing agent libraries, and the agent from being able to write to audit and debug logs. For more information, refer to Troubleshooting.

  • By default, 32 agent instances can run at the same time in a single installation. For information about changing the limit, refer to AM_MAX_AGENTS in Environment variables.

  • (For Apache Web Agent) By default, the agent replaces authentication functionality provided by Apache, for example, the mod_auth_* modules. Configure Use Built-in Apache HTTPD Authentication Directives to use built-in Apache authentication directives such as AuthName, FilesMatch, and Require for specified not-enforced URLs.

Tune multi-processing modules

Apache and IBM HTTP server include Multi-Processing Modules (MPMs) that extend the functionality of a web server to support a wide variety of operating systems and customizations for a site.

Before installation, configure and tune MPMs, as follows:

  • Configure one of the following modules:

    • mpm-event for Unix-based servers

    • mpm-worker for Unix-based servers

    • mpm_winnt for Windows servers

    The prefork-mpm module isn’t adapted to high-traffic deployments. It can cause performance issues to both the agent and AM.

  • Make sure that there are enough processes and threads available to service the expected number of client requests.

    MPM-related performance is configured in the file conf/extra/http-mpm.conf:

    <IfModule mpm_worker_module>
StartServers            2
MaxRequestWorkers     150
MinSpareThreads        25
MaxSpareThreads        75
ThreadsPerChild        25
MaxConnectionsPerChild  0
</IfModule>

    MaxRequestWorkers and ThreadsPerChild control the maximum number of concurrent requests. The default configuration allows 150 concurrent clients across 6 processes of 25 threads each.

    Configure MaxRequestWorkers and ServerLimit to get a high level of concurrent clients.

    To prevent problems registering the notification queue listener, don’t change the default value of MaxSpareThreads, ThreadLimit, or ThreadsPerChild.

    For information about Apache configuration properties, refer to Apache MPM worker.

Install interactively

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. (Optional) In environments where a user isn’t defined in the Apache or IBM HTTP server configuration file httpd.conf, set the following environment variables in your command line session to change ownership of created directories.

    The following examples change ownership to the user user:

    $ export APACHE_RUN_USER=user
$ export APACHE_RUN_GROUP=user

    For more information, refer to Installation environment variables

  3. Shut down the Apache or IBM HTTP server where you plan to install the agent.

  4. Make sure AM is running.

  5. Run agentadmin --i to install the agent:

    • Apache on Linux

    • Apache on Windows

    • IBM HTTP Server on Linux

    $ cd /web_agents/apache24_agent/bin/
$ ./agentadmin --i
    C:\> cd web_agents\apache24_agent\bin
C:\path\to\web_agents\apache24_agent\bin> agentadmin.exe --i
    $ cd /web_agents/httpservern_agent/bin/
$ ./agentadmin --i

  6. When prompted, enter information for your deployment:

    To cancel the installation at any time, press CTRL-C.

    1. Enter the complete path to the Apache or IBM HTTP server configuration file:

      • Apache on Linux

      • Apache on Windows

      • IBM HTTP Server on Linux

      Configuration file [/opt/apache/conf/httpd.conf]:/etc/httpd/conf/httpd.conf
      Configuration file [/opt/apache/conf/httpd.conf]:/etc/httpd/conf/httpd.conf
      Configuration file [/opt/apache/conf/httpd.conf]: /opt/IBM/HTTPServer/conf/httpd.conf

    2. (Optional) When installing the agent as the root user, consider changing directory ownership to the same user and group specified in the server configuration:

      Change ownership of created directories using
User and Group settings in httpd.conf
[ q or 'ctrl+c' to exit ]
(yes/no): [no]: yes

      This step appears only if environment variables are set as described in step 2, and User and Group are not defined in httpd.conf, such as in non Red Hat Enterprise Linux-based distributions.

      See which user or group is running the server by viewing the Group and User directives in httpd.conf.

      The following errors can occur when the permissions are wrong:

      • Server fails to start up

      • Requests to a protected resource return a blank page

      • Log rotation errors

    3. Enter the full path to an existing agent configuration file to import the settings, or press Enter to skip the import.

      To set properties from an existing configuration enter path to file
[ q or 'ctrl+c' to exit, return to ignore ]
Existing agent.conf file: /config/agent.conf

      The installer can import settings from an existing agent on the new installation and skip prompts for values present in the existing configuration file. You must re-enter the agent profile password.

    4. Enter the full URL for the AM instance that the agent will use, including the deployment URI:

      AM server URL: http://am.example.com:8080/am
      If a reverse proxy is configured between AM and the agent, set the AM URL to the proxy URL, for example, https://proxy.example.com:443/am. For information about setting up an environment for reverse proxies, refer to Apache as a reverse proxy.

    5. Enter the full URL of the agent:

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

    6. Enter the name of the agent profile created in AM:

      Agent Profile name: web-agent

    7. Enter the agent profile realm:

      Agent realm/organization name: [/]:  /
      Realms are case-sensitive.

    8. Enter the full path to the file containing the agent profile password:

      The path to the password file: /secure-directory/pwd.txt

    9. Review the configuration:

      Installation parameters:
   AM URL: http://am.example.com:8080/am
   Agent URL: http://www.example.com:80
   Agent Profile name: web-agent
   Agent realm/organization name: /
   Agent Profile password source: /secure-directory/pwd.txt

Confirm configuration (yes/no): [no]:
Validating...
Validating... Success.
Cleaning up validation data...
Creating configuration...
Installation complete.

    10. Accept or update the configuration:

      • To accept the configuration type yes.

      • To change the configuration type no or press Enter. The installer loops through the configuration prompts again using your provided settings as the default. Press Enter to accept each one, or enter a replacement setting.

      On successful completion, the installer adds the agent as a module to the server configuration file httpd.conf. The agent adds a backup configuration file with the installation datestamp: http.conf_amagent_yyyymmddhhmmss.

  7. (Unix only) Make sure the user or group running the Apache or IBM HTTP server has appropriate permissions for the following directories:

    • Apache on Linux

    • Apache on Windows

    • IBM HTTP Server on Linux

    Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log
    Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log
    Read permission:
* /web_agents/httpservern_agent/lib

Read and write permission:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log
    See which user or group is running the server by viewing the Group and User directives in httpd.conf.

    The following errors can occur when the permissions are wrong:

    • Server fails to start up

    • Requests to a protected resource return a blank page

    • Log rotation errors

    The same issues can occur if SELinux is enabled in enforcing mode, and not configured to allow access to agent directories. For more information, refer to Troubleshooting.

  8. Start the Apache or IBM HTTP server.

  9. Check the installation, as described in Check the installation.

Install on a virtual host

Web Agent instances can operate with multiple virtual hosts. Each configuration instance is independent and has its own configuration file, debug logs, and audit logs. Each instance can connect to a different AM realm, or even different AM servers.

Installing on a virtual host is a manual process that involves copying an instance directory created by the agentadmin installer and adding it to the configuration file of the virtual host.

  1. Install an agent in the default root configuration, as described in Install Apache or IBM HTTP Web Agent. This agent is referred to as the root agent.

  2. Create a profile for the agent on the virtual host, as described in Creating agent profiles. This agent is referred to as the virtual host agent.

  3. Create at least one AM policy to protect resources on the virtual host, as described in Policies in AM’s Authorization guide.

  4. Shut down the Apache or IBM HTTP server where you plan to install the agent.

  5. Locate an agent configuration instance to duplicate, and make a copy. For example, copy agent_1 to agent_2:

    • Apache on Linux

    • Apache on Windows

    • IBM HTTP Server on Linux

    $ cd /web_agents/apache24_agent/instances
$ cp -r agent_1 agent_2
    c:\> cd c:\web_agents\apache24_agent\instances
c:\path\to\web_agents\apache24_agent\instances> xcopy /E /I agent_1 agent_2
    $ cd /web_agents/httpservern_agent/instances
$ cp -r agent_1 agent_2

  6. Assign modify privileges to the new instance folder for the user that runs the virtual host. The following examples assign privileges for agent_2 to a user named user:

    • Apache on Linux

    • Apache on Windows

    • IBM HTTP Server on Linux

    $ cd /web_agents/apache24_agent/instances
$ chown -hR user agent_2
    c:\> cd c:\web_agents\apache24_agent\instances
c:\path\to\web_agents\apache24_agent\instances> **icacls "agent_2" /grant user:M
    $ cd /web_agents/httpservern_agent/instances
$ chown -hR user agent_2

  7. In the new instance folder, edit the agent.conf file as follows:

    1. Set the value of Agent Profile Name to the name of the profile you created for the virtual host agent. For example, set the value to agent_2.

    2. Configure the encryption key and password for the virtual host agent, using a scenario that suits your environment:

      • Scenario 1: The password of the virtual host agent profile is the same as the password of the root agent profile[1].

        The encryption key and encryption password of the root agent and virtual host agent must match. Because you copied the configuration file, you don’t need to do anything else.

      • Scenario 2: The password of the virtual host agent profile is different from the password of the root agent profile[2].

        Follow these steps to generate a new encryption key, encrypt the new password, and configure them in the profile of the virtual host agent:

        1. Generate a new encryption key:

          $ agentadmin --k
Encryption key value: YWM…​5Nw==

        2. (Unix only) Store the agent profile password in a file, for example, newpassword.file .

        3. Encrypt the agent profile password:

          • Apache on Linux

          • Apache on Windows

          • IBM HTTP Server on Linux

          $ ./agentadmin --p "YWM…​5Nw==" “cat newpassword.file”
Encrypted password value: 07b…​dO4=
          $ agentadmin.exe --p "YWM…​5Nw==" "newpassword"
Encrypted password value: 07b…​dO4=
          $ ./agentadmin --p "YWM…​5Nw==" “cat newpassword.file”
Encrypted password value: 07b…​dO4=

        4. Set the following properties in agent.conf:

    3. Throughout the configuration, replace references to the original instance directory with the new instance directory. For example, replace agent_1 with agent_2 in the following properties:

    4. Throughout the configuration, replace references to the original website being protected with the new website being protected. For example, replace http://www.example.com:80/amagent with http://customers.example.com:80/amagent in the following properties:

  8. Edit the Apache or IBM HTTP server configuration file, httpd.conf:

    1. Find the following lines at the end of the file. The following example is for Apache agent on Linux, but you can adapt it to your configuration:

      LoadModule amagent_module /web_agents/apache24_agent/lib/mod_openam.so
AmAgent On
AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_1/config/agent.conf

    2. Leave the first line, LoadModule …​, and move the other two lines on the virtual host configuration element of the default site, for example:

      <VirtualHost *:80>
# This first-listed virtual host is also the default for *:80
ServerName www.example.com
ServerAlias example.com
DocumentRoot "/var/www/html"
AmAgent On
AmAgentConf /web_agents/apache24_agent/instances/agent_1/config/agent.conf
</VirtualHost>

    3. Copy the same two lines on the new virtual host, and replace agent_1 with the new agent configuration instance folder, for example agent_2:

      <VirtualHost *:80>
ServerName customers.example.com
DocumentRoot "/var/www/customers"
AmAgent On
AmAgentConf /web_agents/apache24_agent/instances/agent_2/config/agent.conf
</VirtualHost>
      If the new virtual host configuration is in a separate file, copy the two configuration lines on the VirtualHost element within that file.

  9. Save and close the configuration file.

  10. (Unix only) Make sure the user or group running the Apache or IBM HTTP server has appropriate permissions for the following directories:

    • Apache on Linux

    • Apache on Windows

    • IBM HTTP Server on Linux

    Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log
    Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log
    Read permission:
* /web_agents/httpservern_agent/lib

Read and write permission:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log
    See which user or group is running the server by viewing the Group and User directives in httpd.conf.

    The following errors can occur when the permissions are wrong:

    • Server fails to start up

    • Requests to a protected resource return a blank page

    • Log rotation errors

    The same issues can occur if SELinux is enabled in enforcing mode, and not configured to allow access to agent directories. For more information, refer to Troubleshooting.

  11. Start the Apache or IBM HTTP server.

  12. Check the installation, as described in Check the installation.

Install silently

Use the agentadmin --s command for silent installation. For information about the options, refer to agentadmin command.

  1. Review the information in Before you install, and perform the steps in Preinstallation tasks.

  2. Shut down the Apache or IBM HTTP server where you plan to install the agent.

  3. Make sure AM is running.

  4. Run the agentadmin --s command with the required arguments. The following example is for Apache agent on Linux, but you can adapt it to your configuration:

    $ sudo agentadmin --s \
  "/etc/httpd/conf/httpd.conf" \
  "http://am.example.com:8080/am" \
  "http://www.example.com:80" \
  "/" \
  "webagent" \
  "/secure-directory/pwd.txt" \
  --changeOwner \
  --acceptLicence
Web Agent for Apache Server installation.

Validating…​
Validating…​ Success.
Cleaning up validation data…​
Creating configuration…​
Installation complete.

  5. (Unix only) Make sure the user or group running the Apache or IBM HTTP server has appropriate permissions for the following directories:

    • Apache on Linux

    • Apache on Windows

    • IBM HTTP Server on Linux

    Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log
    Read permission:
* /web_agents/apache24_agent/lib

Read and write permission:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/apache24_agent/instances/agent_n
* /web_agents/apache24_agent/log
    Read permission:
* /web_agents/httpservern_agent/lib

Read and write permission:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log

Execute permission to validate an installation by using the agentadmin --V[i\] command:
* /web_agents/httpservern_agent/instances/agent_n
* /web_agents/httpservern_agent/log
    See which user or group is running the server by viewing the Group and User directives in httpd.conf.

    The following errors can occur when the permissions are wrong:

    • Server fails to start up

    • Requests to a protected resource return a blank page

    • Log rotation errors

    The same issues can occur if SELinux is enabled in enforcing mode, and not configured to allow access to agent directories. For more information, refer to Troubleshooting.

  6. Start the Apache or IBM HTTP server.

  7. Check the installation, as described in Check the installation.

Check the installation

  1. After you start Apache or IBM HTTP server, check the error log to make sure startup was successful:

    [Tue Sep …​] AH00163:
Apache/2.4.6 (CentOS) Web Agent/2023.11 configured — resuming normal operations

  2. Make an HTTP request to a resource protected by the agent, then check the /log/system_0.log file to verify that no errors occurred on startup. The log should contain a message similar to this:

    [0x7fb89e7a6700:22]: Web Agent Version: 2023.11
Revision: ab12cde, Container: Apache 2.4 Linux 64bit (Centos6),
Build date: Mar …​

  3. (Optional) If an AM policy is configured, test that the agent enforces a policy decision. For example, make an HTTP request to a protected resource and check that you are redirected to AM to authenticate. After authentication, AM redirects you back to the resource you tried to access.

Install in a subrealm

Examples in this document install the agent in the top-level realm. To install the agent in a subrealm during interactive or silent installation, use the subrealm during the installation or in the response file.

For example, instead of:

Agent realm/organization name: [/]: /

specify:

Agent realm/organization name: [/]: /myrealm

Even though the agent is installed in a subrealm, the default login redirect requires the user realm to be the top-level realm. For information about how to change the user realm, refer to Login redirect.

Configure error logs

Edit the server configuration file httpd.conf to log errors.

The following line, present by default in httpd.conf, logs warning conditions for the container:

LogLevel warn

The following example line includes the agent error logs at debug-level:

LogLevel warn amagent:debug
1. The root agent profile refers to the agent installation performed in Install Apache or IBM HTTP Web Agent and required for installation on virtual hosts.
2. The root agent profile refers to the agent installation performed in Install Apache or IBM HTTP Web Agent and required for installation on virtual hosts.