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.

API Firewall 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`
`PLATFORM_HOST`	The host and port where API Firewall can access your platform instance. If you are an enterprise customer not accessing 42Crunch Platform at the default URL `https://platform.42crunch.com` (see Platform URL), you can use this variable to define and store the host and port that API Firewall must use as part of its deployment configuration. This variable overrides host and port provided from CLI.	`protection.42crunch.com:8001`

API Firewall blocking levels for protected and unknown APIs

In normal operation mode, API Firewall instance blocks all API traffic (both requests and responses) that do not conform to the API definition of the API it is protecting. However, you can use the environment variable GUARDIAN_BLOCKING_LEVEL to control what exactly you want API Firewall to block:

Value	Impact
`6`	Custom blocking mode lets you choose how API Firewall treats incoming requests and outgoing responses that have not been described in your API. This allows you to protect your API progressively as you keep improving on it. You can also choose if you want to include the transaction bodies from requests and responses into the transaction logs that API Firewall writes for further analysis. Depending on your API, the transaction bodies may contain sensitive or personally identifiable information (PII). If you choose to log the transaction bodies, you should make sure that transaction logs are not stored in 42Crunch Platform. See Switch log destination for API Firewall logs. Custom blocking mode is only available for API Firewall images `v1.1.1` or later.
`5` (default)	In normal operation (full blocking mode), API Firewall blocks all non-conforming traffic, such as: Requests to an unknown API Requests to an unknown path or operation (method) Requests not conforming to the defined `content-type`, `schema`, or applied protection Responses with unknown response codes Responses not conforming to the defined `content-type`, `schema`, or applied protection
`4`	API Firewall blocks: Requests to an unknown API Requests to an unknown path or operation (method) Requests not conforming to the defined `content-type`, `schema`, or applied protection Unknown response codes
`3`	API Firewall blocks: Requests to an unknown API Requests to an unknown path or operation (method) Requests not conforming to the defined `content-type`, `schema`, or applied protection
`2`	API Firewall blocks: Requests to an unknown API Requests to an unknown path or operation (method) API Firewall does not validate any payloads in requests or responses.
`1`	API Firewall blocks: Requests to an unknown API In other words, if the base path of the protected API is, for example, `/api/v1`, all calls with this base path are accepted even if they are not defined in the OpenAPI definition.
`0`	API Firewall is in listening mode and does not block any traffic, it only reports what would have been blocked.

You can also specify different treatment to requests where the API is unknown. There are three options:

If you define only GUARDIAN_BLOCKING_LEVEL, API Firewall applies the blocking level to all incoming requests, no matter if they are to the protected API or to unknown APIs.
If you define only GUARDIAN_DEFAULT_API_BLOCKING_LEVEL, API Firewall applies the blocking level to all requests to the protected API. Any requests to unknown APIs are blocked.
If you define both GUARDIAN_DEFAULT_API_BLOCKING_LEVEL and GUARDIAN_BLOCKING_LEVEL:
- API Firewall applies GUARDIAN_DEFAULT_API_BLOCKING_LEVEL to requests to the protected API. The level can be any of 5—0.
- API Firewall applies GUARDIAN_BLOCKING_LEVEL to requests to unknown APIs. Only values 5 (block everything) and 0 (block nothing) have effect, because levels 4—1 are compared against the API definition of the API. Levels 4—1 are treated as level 5 (the default value).

For mode details, see Set API Firewall blocking level.

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`

Always 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.

If 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 API Firewall 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.

Variables for basic configuration

The variables for the basic configuration of your API Firewall instance include all the mandatory variables — such as the overall TLS configuration — that you must configure, as well as some optional variables, for example, for logs.

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 Firewall instance 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 (`/opt/guardian/conf/ssl/`). 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. 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`
`HTTPS_PROXY`	Defines the address of the proxy server, if the connection from API Firewall instance to 42Crunch Platform must go through a HTTPS proxy. For more details, see Set API Firewall connect to the platform through a HTTPS proxy.	`https://myproxy.acme.com`
`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`
`LOG_LEVEL`	The level of detail in the runtime logs of the protected API and its virtual host (`vh-<API UUID>.error.log`). API Firewall supports the standard Apache log levels. We recommend using the values `warn`, `info`, or `error`, depending on the granularity you need. The values `debug`, `trace1`, `trace5`, and `trace7` should not be used in production, but may be used when troubleshooting issues. For more details on the log levels, see LogLevel Directive in Apache documentation.	`warn`
`ERROR_LOG_LEVEL`	The level of detail in the loading and initialization logs of the API Firewall instance (`error.log`). API Firewall supports the standard Apache log levels. We recommend using the values `warn`, `info`, or `error`, depending on the granularity you need. The values `debug`, `trace1`, `trace5`, and `trace7` should not be used in production, but may be used when troubleshooting issues. For more details on the log levels, see LogLevel Directive in Apache documentation.	`warn`

Variables for connection between the API client and API Firewall

The following optional variables control the front-end connection between the protected API and the API Firewall instance protecting it.

Variable name	Description	Default or sample value
`VHOST_TIMEOUT`	How long (in seconds) the API Firewall instance allows for reading from or writing to the frontend API client. Each new protocol data successfully received from or sent to the client resets the timeout.	`30`
`VHOST_KEEPALIVE`	Does the API Firewall instance keep the connection to client open to wait for any subsequent requests from the client.	`on`
`VHOST_KEEPALIVE_TIMEOUT`	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 (for example, `1500ms`).	`5`
`VHOST_TLS_PROTOCOLS`	Which TLS protocols are used for the connection between the client and the API Firewall instance.	`-ALL +TLSv1.2 +TLSv1.3`
`VHOST_TLS_CHIPHER_SUITES`	Which TLS cipher suites are used for the connection between the client and the API Firewall instance.	`ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256`
`VHOST_TLS_STRICT_SNI_VHOST_CHECK`	Does the API Firewall instance refuse or allow client TLS connections that do not have server name indication (SNI) or where the name does not match the `SERVER_NAME` defined for the firewall instance. This setting is on by default for better processing performance, because refusing unwanted TLS connections already during the TLS handshake phase avoids wasting effort on processing them further.	`on`

Variables for connection between API Firewall and the backend services

You can use the following optional variables to fine-tune how API Firewall connects to your backend services that serve the protected API.

Variable name	Description	Default or sample value
`BACKEND_TIMEOUT`	How long (in seconds) the API Firewall instance allows for writing or reading from the backend server. Each new protocol data successfully sent to or received from the backend server resets the timeout.	`30`
`BACKEND_CONNECTION_TIMEOUT`	How long (in seconds) the API Firewall instance allows for establishing the TCP connection to the backend server.	`5`
`BACKEND_KEEPALIVE`	Does the API Firewall instance keep the connection to backend services open to wait for any subsequent responses from the backend.	`on`
`BACKEND_KEEPALIVE_TIMEOUT`	How long the API Firewall instance keeps the connection to backend services open for subsequent requests forwarded to the same backend server before closing the connection. By default, the value is in seconds. To define the timeout in milliseconds, add `ms` after the value (for example, `1500ms`).	`15`
`BACKEND_TLS_PROTOCOLS`	Which TLS protocols are used for the connection between the API Firewall instance and the backend services.	`-ALL +TLSv1.2 +TLSv1.3`
`BACKEND_TLS_CHIPHER_SUITES`	Which TLS cipher suites are used for the connection between the API Firewall instance and the backend server.	`ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256`
`BACKEND_TLS_CHECK_PEER_NAME`	Does the API Firewall instance check the certificate name of the backend server. The firewall matches the Common Name (CN) or one of the Subject Alternative Names (SAN) in the backend server's certificate against the SNI that was used to establish the TLS connection, to verify that the connected backend server is the one the API Firewall instance is configured to connect to. In case of a mismatch, an error is returned to the client.	`on`
`BACKEND_TLS_CHECK_PEER_EXPIRE`	Does the API Firewall instance check if the certificate of the backend server has expired. If the certificate has expired, an error is returned to the client.	`on`
`BACKEND_ADD_HEADERS`	Does the API Firewall instance add the headers `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Server` when it forwards the HTTP request to the backend server.	`off`

API Firewall transaction log destination and strategy

You can use the API-specific variable LOG_DESTINATION to choose where API Firewall instance publishes logs.

Value	Impact
`PLATFORM`	Transaction logs are published to 42Crunch Platform. Error logs and access logs are written to the file system of the API Firewall container. This is the default value.
`FILES`	All transaction, error, and access logs are written to a directory that you mount to your deployment as a volume for `/opt/guardian/logs/${GUARDIAN_INSTANCE_NAME}`.
`STDOUT`	All transaction, error, and access logs are written as standard output (STDOUT) to console.
`FILES+STDOUT`	All transaction, error, and access logs are written to a directory that you mount to your deployment as a volume for `/opt/guardian/logs/${GUARDIAN_INSTANCE_NAME}` and as standard output to console.
`PLATFORM+STDOUT`	Transaction logs are published to 42Crunch Platform and written as standard output to console. Error logs and access logs are written to the file system of the API Firewall container and as standard output to console.

Log destination PLATFORM (alone or with STDOUT) is not suitable for firewall instances running in production environment due to the volume of logs produced. We recommend setting the log destination to FILES or STDOUT (or both) in production or for performance testing.

Using the default size for the container file system is fine for testing, or when you can be sure that the logs volume stays low. However, the volume of logs can rapidly increase, especially in production, so if you want to use PLATFORM or FILES (alone or with STDOUT), you must plan for this growth to avoid running out of disk space in your API Firewall container. Either reserve enough disk space, or mount an external disk as a volume.

If you use only STDOUT, then all logs are pushed out of the container, and container disk space is not a concern.

Depending on the nature of your API, transaction logs could include personally identifiable information that falls under, for example, GDPR regulations. To facilitate the requirements from these regulations, such as the right to forget, it is possible to delete transaction logs from 42Crunch Platform. See Delete transaction logs.

For more details, see Switch log destination for API Firewall logs.

If you want API Firewall to send transaction logs to 42Crunch Platform, you can also use the variable LOG_STRATEGY to choose what happens if the API Firewall instance loses connection to the platform.

Value	Impact
`RECONNECT_ON_PLTF_LOST`	If an API Firewall loses the connection to the platform, it tries to reconnect until it succeeds or the instance is manually stopped. In the meantime, it continues to handle traffic to the protected API normally, but does not write transaction logs. This is the default value.
`KILL_ON_PLTF_LOST`	If an API Firewall loses the connection to the platform, the instance stops and the traffic to the API is interrupted. Use this value if you want to prevent API traffic and untracked transactions when transaction logs cannot be written.

LOG_STRATEGY is ignored if you have specified in LOG_DESTINATION that transaction logs do not go to 42Crunch Platform.

For more details, see Stop API Firewall from serving traffic without logs.

API Firewall healthcheck over HTTPS

By default, the healthcheck service on API Firewall is listens on HTTP connections. However, if needed, you can use environment variables to switch it to use HTTPS connection.

Value	Description	Default or sample value
`HEALTHCHECK_SSL`	Are healthcheck calls made over HTTP (default) or HTTPS. If set to `on`, calls are made over HTTPS and you must provide the certificate and private key to be used for the HTTPS connection.	`off`
`HEALTHCHECK_SSL_CERT`	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 (`/opt/guardian/conf/ssl/`). The value can be the same as for `LISTEN_SSL_CERT`.	`fullchain-cert.pem`
`HEALTHCHECK_SSL_KEY`	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. The value can be the same as for `LISTEN_SSL_KEY`.	`firewall-key.pem`
`HEALTHCHECK_SSL_SERVERNAME`	The CN/hostname that the healthcheck client connects to. The value should ideally be the same as your certificate CN and the DNS name that your healthcheck client connects to.	`localhost:8443`