API Firewall variables

You can use variables to configure your API Firewall deployment. Where and how this is done depends on the environment where you are deploying the API Firewall instance. For more details on the specifics of each environment, see the dedicated deployment guides available in our Resources repository in GitHub.

Regardless of your target environment, the variable names are the same. Below you can find descriptions of the variables that control different aspects of the deployment.

Environment variables

The environment variables are for distinguishing the particular API Firewall instance in your wider deployment. The variables are used mostly in logs or on the 42Crunch Platform UI, and many of them are only applicable to deployments in a Kubernetes environment.

Variable name Description Default or sample value
GUARDIAN_INSTANCE_NAME Required.The unique name of the API Firewall instance. Used in logs and on the UI. You can use the default value, or specify your own if you want.

Kubernetes: metadata.name

You can also use a hard-coded string (for example, aws-vg-instance1).

GUARDIAN_NODE_NAME Required. The unique name of the API Firewall node (the system or cluster where the API Firewall container runs on). Used in logs and on the UI. You can use the default value, or specify your own if you want. Kubernetes: spec.nodeName

You can also use a hard-coded string (for example, aws-vg-node1).

GUARDIAN_INSTANCE_NAMESPACE The namespace of the API Firewall instance. Used only in logs. This variable applies only to Kubernetes environments. metadata.namespace
GUARDIAN_INSTANCE_IP The IP address of the API Firewall pod. Used only in logs. This variable applies only to Kubernetes environments. status.podIP
GUARDIAN_INSTANCE_SERVICE_ACCOUNT The service account context of the API Firewall instance. Used only in logs. This variable applies only to Kubernetes environments. spec.serviceAccountName

Protection token variable

The protection token links the tailor-made protection configuration you have created for your API in 42Crunch Platform with the API Firewall instance protecting your API.

Variable name Description Sample value
PROTECTION_TOKEN

Required. The UUID of the protection configuration to be run. Used in deploying the API Firewall Docker image.

xxxxxxxx‑2b0d‑40acbbe1‑dfe34cca96f8

Security riskAlways store all your tokens securely, for example, in Kubernetes Secrets, like other secrets you use! Treat tokens as you would other sensitive information, like your passwords.

Make sure that the value you set for PROTECTION_TOKEN matches the protection configuration you want to run in your deployment. If you no longer have the value of that token, create a new token and copy the value. For more details, see Create a protection configuration.

TipIf you have several APIs and several environments, it can be difficult to keep track of where each protection token is used. To stay on top of things, in addition to giving descriptive names to protection tokens, use descriptive names for your stored secrets as well, for example, in Kubernetes secrets. We recommend that you include the name of the token and the name or API UUID of the API in the name of the secret. For example, in a Kubernetes secret generic-pixi-protection-token, generic is the name entered for the token when it was created and pixi is the name of the API the token was created for.

API-specific variables

The API-specific variables configure the listening interface of the API Firewall instance as well as the connections between the API consumer and API Firewall and API Firewall and the protected API. You must configure these variables to match the API that the API Firewall instance protects.

The following graphic shows which variables are needed for the TLS configuration and where they apply:

The example diagram illustrates what parts of the deployment each setting controls.

For more details on TLS in API Firewall, see TLS configuration.

Variable name Description Default or sample value
SERVER_NAME

Required. The hostname where your API endpoint is exposed and that your clients will call to invoke your API. This is the address that the API Firewallinstance listens on.

API Firewall validates the hostname in the Host header on each incoming request and rejects any requests where the value does not match SERVER_NAME.

If API Firewall is terminating TLS connection, the certificates in LISTEN_SSL_CERT must match this hostname.

myapis.acme.com
LISTEN_PORT Required. The port that the API Firewall instance listens on. In Kubernetes deployments, this must match the value of containerPort of the API Firewall container. 443
TARGET_URL Required. The backend URL where the API Firewall instance proxies requests to. Both HTTP and HTTPS are supported. If the protected API and the API Firewall instance run in the same container, use localhost for better performance. http://localhost:8090
LISTEN_SSL_CERT

Required if LISTEN_NO_TLS is not specified. The name of the certificate file that the API Firewall instance uses for secure connections. The certificate file must be in PEM format, and the whole certificate chain (CA, Intermediate CA, the certificate) must all be stored in this file, sorted from leaf to root. The file must be present in the file system of the API Firewall container.

If API Firewall is terminating TLS connection, the certificates must match SERVER_NAME.

fullchain-cert.pem
LISTEN_SSL_KEY Required if LISTEN_NO_TLS is not specified. The name of the private key file that the API Firewall instance uses for secure connections. The key must match the certificate chain. The file must be in PEM format, and it must be present in the file system of the API Firewall container. firewall-key.pem
LISTEN_NO_TLS

Use HTTP connections to API Firewall.

By default, the listener interface of API Firewall only accepts HTTPS connections, and you must specify the variables LISTEN_SSL_CERT and LISTEN_SSL_KEY. If you want to use HTTP connections instead, you can add the variable LISTEN_NO_TLS to your API Firewall configuration.

It is enough for this variable just to be present in your API Firewall configuration to change the behavior of API Firewall. The variable does not need a specific value, but deployment fails if you leave he value empty. If you have the variable LISTEN_NO_TLS in your API Firewall configuration, regardless of the value, API Firewall will use HTTP instead of HTTPS.

Note To switch back to HTTPS, you must completely remove the variable LISTEN_NO_TLS from the API Firewall configuration. Changing the value to false does nothing.

If HTTP connections are used, the TLS setup is disregarded and you do not need to specify LISTEN_SSL_CERT and LISTEN_SSL_KEY. If you have, you do not need to remove them, the variables are simply ignored.

For more details, see Switch API Firewall to use HTTP connections.

LISTEN_NO_TLS=ON, LISTEN_NO_TLS=TRUE, LISTEN_NO_TLS=1
PRESERVE_HOST

Defines if the API Firewall instance passes the Host header value unchanged to the backend.

  • Off: API Firewall uses the host name (and port, if any) from TARGET_URL in the host header of the request to the backend.
  • On: API Firewall includes the host header from the incoming request in the request to the backend as is.
Off
TIMEOUT_IN How long (in seconds) the API Firewall instance waits for a TCP packet from the client to arrive before closing the connection. 60
TIMEOUT_KEEPALIVE How long the API Firewall instance waits for any subsequent requests from the client before closing the connection. By default, the value is in seconds. To define the timeout in milliseconds, add ms after the value. 15
LOG_DESTINATION

Where the transaction logs from the API Firewall instance are published. There are two options:

  • PLATFORM: API Firewall logs are published in 42Crunch Platform.
  • FILES: API Firewall logs are published to mounted directory. If you set LOGS_DESTINATION to FILES, you must also make sure the mounted volumes are included in your deployment. For more details, see Switch logs destination for API Firewall logs.
PLATFORM
LOG_LEVEL The level of detail in the logs. Available values are warn, info, debug, and notice. warn