Configuring advanced HTTPd customizations

Use advanced customization options to tailor HTTPd monitoring for your environment.

Securing server-status API

The HTTPd server-status endpoint exposes runtime information about the web server. Instana uses this endpoint to collect monitoring metrics from HTTPd.

By default, the HTTPd server-status endpoint can expose server metrics to anyone who can access it. To restrict access to the Instana agent only and protect monitoring data from unauthorized users, use the following options:

  • IP address whitelisting
  • Basic authentication (username and password)
Note:
For enhanced security, you can use both the options simultaneously.

Whitelisting IP address

IP address whitelisting restricts access to the server-status endpoint to specific IP addresses. Requests from any other source are denied. List the IP addresses for which the server status page must be accessible. If any malicious actor tries to access the page, the server throws an error.

HTTPd running directly on a host

If the HTTPd server is running directly on the same host as the Instana agent, use the following configuration snippet to enable access to the server-status page just for the Instana agent:

<Location /server-status>
    SetHandler server-status
    Require local
</Location>
LoadModule status_module lib/httpd/modules/mod_status.so
ExtendedStatus On

HTTPd running in Docker or Kubernetes

When the HTTPd server runs in a Docker or Kubernetes environment, the Instana agent typically runs in a separate container or pod and does not appear as localhost.

To configure access to the server-status page, complete the following steps:

  1. Set the INSTANA_AGENT_HOST environment variable with the IP address of the container or pod the Instana agent is running on.

    Note:
    Specify an IP address, not a hostname.

  2. Add the following configuration snippet:

    <Location /server-status>
    SetHandler server-status
    <RequireAll>
        Require expr %{ENV:INSTANA_AGENT_HOST}% != '' && %{REMOTE_ADDR} == %{ENV:INSTANA_AGENT_HOST}%
    </RequireAll>
</Location>
LoadModule status_module lib/httpd/modules/mod_status.so
ExtendedStatus On

    For more information about setting the INSTANA_AGENT_HOST environment variable in the HTTPd pod, see Configuring network access for monitored applications.

Apply the changes

Reload HTTPd server (apachectl graceful) for the changes to take effect.

Configuring basic authentication

Basic authentication adds a username and password requirement to the server-status endpoint. When combined with IP-address whitelisting, any request must satisfy both conditions before HTTPd server grants access.

Prerequisites

Ensure that the mod_auth_basic and mod_authn_file modules are enabled in your HTTPd server configuration:

LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authn_file_module modules/mod_authn_file.so

Step 1: Create the password file

Use the htpasswd utility (bundled with Apache) to generate a hashed-password file. Run this command on the host or inside the container image build:

htpasswd -c /usr/local/apache2/conf/.htpasswd <username>

Replace <username> with the user name that the Instana agent uses. The -c flag creates the password file. When adding additional users to an existing file, omit the -c flag.

Note:
Store the .htpasswd file outside the web document root so that it cannot be downloaded by web clients.

If you are building a Docker image, copy the password file into the image in your Dockerfile:

COPY conf/.htpasswd /usr/local/apache2/conf/.htpasswd

Step 2: Update httpd.conf

Add the AuthType, AuthName, and AuthUserFile directives to the <Location /server-status> block, and wrap all Require directives in a <RequireAll> block so that both the IP-address and credential checks must pass:

<Location /server-status>
    SetHandler server-status
    AuthType Basic
    AuthName "Server Status - Restricted Access"
    AuthUserFile /usr/local/apache2/conf/.htpasswd
    <RequireAll>
        Require expr %{ENV:INSTANA_AGENT_HOST} != '' && %{REMOTE_ADDR} == %{ENV:INSTANA_AGENT_HOST}
        Require valid-user
    </RequireAll>
</Location>
LoadModule status_module lib/httpd/modules/mod_status.so
ExtendedStatus On
Directive Description
AuthType Basic Enables HTTP Basic Authentication.
AuthName The realm shown in the browser's credential prompt.
AuthUserFile Absolute path to the .htpasswd file created in Step 1.
Require valid-user Grants access only to users listed in the password file.
<RequireAll> Enforces all enclosed Require rules, IP address match, and valid credentials.

Step 3: Configure the Instana agent

Set the user and password fields in agent/configuration.yaml so that the Instana agent includes the credentials when polling server-status:

com.instana.plugin.httpd:
  user: '<username>'
  password: '<password>'

Replace <username> and <password> with the credentials that are used in Step 1.

Apply the changes

Reload HTTPd server (apachectl graceful) for the changes to take effect.