IBM Cloud installation

  Last updated 2024-02-20

The Next-Gen WAF agent can be deployed with IBM Cloud application runtimes. The installation process is compatible with any of the language buildpacks.

This is a supply-buildpack for Cloud Foundry that provides integration with the Next-Gen WAF agent for any programming language supported by the platform, and requiring zero application code changes.

Prerequisites

Copy the agent keys for the site that you want the agent to be able to access. You will use the agent keys when configuring the Next-Gen WAF agent package.

Installation

  1. Application developers will need to specify the buildpack with the cf push command:

    $ cf push YOUR-APP -b https://github.com/signalsciences/sigsci-cloudfoundry-buildpack.git -b APP_BUILDPACK

  2. Set your agent's access key and secret using the cf set-env command. Replace your-application-name with the name of your application and replace access-key-goes-here and secret-key-goes-here with your agent keys:

    $ cf set-env your-application-name SIGSCI_ACCESSKEYID access-key-goes-here
    $ cf set-env your-application-name SIGSCI_SECRETACCESSKEY secret-key-goes-here

  3. Run cf push as you normally would to deploy your application.

Additional configuration options

The Next-Gen WAF agent can be configured with environment variables using the cf command, replacing OPTION and VALUE with the agent configuration option and its value:

$ cf set-env your-application-name OPTION "VALUE"

To have these changes take effect, you must at least re-stage your app:

$ cf restage your-application-name

Server hostname

Each time you deploy your application, IBM Cloud will automatically assign a new random name for the agent. To specify an agent name for each deployment, set the SIGSCI_SERVER_HOSTNAME environment variable:

$ cf set-env your-application-name SIGSCI_SERVER_HOSTNAME agent-name

Reverse proxy upstream

To define upstream hosts that the Agent will proxy requests to, use the SIGSCI_REVERSE_PROXY_UPSTREAM option, replacing ip:port with the upstream host IP address and port. This variable is optional with a default value of 127.0.0.1:8081:

$ cf set-env your-application-name SIGSCI_REVERSE_PROXY_UPSTREAM ip:port

Access logs

To enable the agent's access logging, set the SIGSCI_REVERSE_PROXY_ACCESSLOG environment variable:

$ cf set-env your-application-name SIGSCI_REVERSE_PROXY_ACCESSLOG /tmp/sigsci_access.log

Agent version

By default the buildpack will install the latest version of the Next-Gen WAF agent. To specify which agent version to install, set the SIGSCI_AGENT_VERSION environment variable, replacing version-number with the specific version number to install:

$ cf set-env <application name> SIGSCI_AGENT_VERSION version-number

Health checks

Currently, IBM Cloud does not support HTTP health checks native to Cloud Foundry. If the application process crashes while the Next-Gen WAF agent is still running, IBM Cloud may not detect that the application is in an unhealthy state. The latest release of the Signal Sciences Cloud Foundry installer script can be configured to implement health checking that will stop the agent process if the application process is in an unhealthy state.

There are two environment variables that enable/configure health checking:

Set SIGSCI_HC to true to enable health checking:

$ cf set-env your-application-name SIGSCI_HC true

Set SIGSCI_HC_CONFIG to configure the health check. If you do not set this environment variable the default settings will be used.

The default settings configure the health check to:

  • Check the / path every 5 seconds.
  • If the agent listener returns a 502 for 5 sequential checks, then the health check fails.
  • If the application process does not return a 200 response for 3 sequential tries, then the health check fails.

To specify custom health check settings, the SIGSCI_HC_CONFIG value is a string that consists of several fields delimited by :.

SIGSCI_HC_CONFIG fields:

<frequency>:<endpoint>:<listener status>:<listener warning>:<upstream status>:<upstream warning>
FieldDescription
frequencyHow often to perform the check in seconds (e.g., every 5 seconds)
endpointWhich endpoint to check for both the listener and upstream process
listener statusThe status code that not healthy and will trigger stopping the agent
listener warningThe number of times the check can fail before stopping the agent
upstream statusThe status code that is healthy, any other code will trigger stopping the agent
upstream warningThe number of times the check can fail before stopping the agent

As an example, the default settings looks like:

5:/:502:5:200:3

Example custom health check settings

These example settings configure the health check to:

  • Check the /health.html path every 10 seconds.
  • If the agent listener returns a 502 for 10 sequential tries the health check fails.
  • If the application process does not return a 200 for 5 sequential tries, the health check fails.
10:/health.html:502:10:200:5

Require agent

By default the installer script will allow the application to start even if the Next-Gen WAF agent fails to start. To ensure that your application never starts without being protected by the Next-Gen WAF agent, use the SIGSCI_REQUIRED environment variable:

$ cf set-env your-application-name SIGSCI_REQUIRED true

Additional configuration options

Additional configuration options are listed on the agent configuration page.

Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Fastly
© Fastly 2024