The following are the current configuration options (as of v4.78.0 on the linux platform). You can view these options on the installed Agent version by running with the `--usage` command line option. ## Configuration options The configuration options are as follows: | | Name | Type | Status | Description | Default | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | | `accesskeyid` | string | Check circle icon indicating active status

| Set anonymous IP secret key. Default is to use `secretaccesskey` when generating anonymous IP addresses | | | | `bypass-egress-proxy-for-upstreams` | boolean | Flask icon indicating experimental status

| Add custom headers to the RPC response, which will be added to the HTTP request by the module \[format is CSV if name:val pairs with $AgentResponse, $RequestID, $TagList dynamic values] | | | | `debug-log-all-the-things` | boolean | Flask icon indicating experimental status

| CDN URL to check and download new configurations before checking download-url, empty string disables CDN fetch | `https://wafconf.signalsciences.net` | | | `download-config-cache` | string | Check circle icon indicating active status

| URL to check and download new configurations if download-url is not available | `https://sigsci-agent-wafconf-us-west-2.s3.amazonaws.com` | | | `download-interval` | time-duration | Flask icon indicating experimental status

| Expect response data from envoy: 0=response data is not expected and some dependent product features will not be available, 1=agent will wait for response data via http_grpc_access_log gRPC API | `0` | | | `envoy-extproc-enabled` | boolean | Flask icon indicating experimental status

| DO NOT USE: the alternative response code concept is deprecated - all codes 300-599 are now considered blocking codes and this option will be removed | | | | `inspection-anomaly-duration` | time-duration | Flask icon indicating experimental status

| Envoy/revproxy global duration after which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection | `1s` | | | `inspection-anomaly-size` | integer | Flask icon indicating experimental status

| Envoy/revproxy global response size limit which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection | `524288` | | | `inspection-debug` | boolean | Flask icon indicating experimental status

| Set local networks for determining the real client IP (CSV of CIDR, 'all', 'none', or 'private'). These are the networks trusted to set the client IP header. | `all` | | | `log-out` | string | Check circle icon indicating active status

| Log output location, 'stderr', 'stdout', or file name (NOTE: on Windows, important logs will be sent to the eventlog) | | | | `max-backlog` | integer | Check circle icon indicating active status

| Reload the reverse proxy service config on agent config updates to support dynamic reconfiguration (only functions on OSes that support zero downtime restarts such as Linux >= 3.9 kernel) | `false` | | | `rpc-address` | string | Check circle icon indicating active status

| Server hostname. By default, the agent asks the OS for the hostname configuration unless a value is configured here. | | | | `service-shutdown-timeout` | time-duration | Check circle icon indicating active status

| Filepath to create file checked by startup probes. Creates the file once the agent has loaded a ruleset. Ex: /sigsci/tmp/startup | | | | `startup-probe-listener` | string | Flask icon indicating experimental status

| HTTP listener for responding to startup probes. Returns HTTP 200 once the agent has loaded a ruleset. Ex: 0.0.0.0:2024 | | | | `statsd-address` | string | Check circle icon indicating active status

| Filename to log WAF inspection data (currently JSON format). Using "eventlog" on Windows will send these to the eventlog. Requests are logged to the provided location if they have at least one signal added by default inspectors or if they have at least one signal added by a request rule with a Request logging value of Sampled. | | | | `waf-data-log-all` | boolean | Flask icon indicating experimental status

| Set the windows eventlog level (use names that will be converted to integers: `debug`, `info`, `warning`, `error`, or `none`). | `3` | ## Reverse proxy listener options Reverse proxy mode supports multiple listeners. In the configuration file, each listener is defined in a `revproxy-listener` block that has its own set of directives. Each block is formatted as a [TOML table](https://toml.io/en/v1.1.0#table). Each block must: - have a unique name in the format `[revproxy-listener.NAME]`, where `NAME` is a string that you define. - be located at the end of the configuration after all other global options. Alternatively, use command-line options or environment variables with this format: - `--option='name1:{opt=val,...};name2:{opt=val,...}'` - `SIGSCI_OPTION='name1:{opt=val,...};name2:{opt=val,...}'` For more details and an example, check out our [Reverse proxy listener configuration](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/reverse-proxy-deployment/configuring-agent-reverse-proxy-deployments/#reverse-proxy-listener-configuration) section. | | Name | Type | Status | Description | Default | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | | `access-log` | string | Check circle icon indicating active status

| Maximum total number of upstream connections in any state per host (0 is unlimited). Connections over the limit will block until more are available | `0` | | | `conn-timeout` | time-duration | Check circle icon indicating active status

| This experimental option replaces 'close-conn-on-request-smuggling' functionality. The option will need to be enabled per each reverse proxy listener. | `true` | | | `extend-content-types` | boolean | Check circle icon indicating active status

| Duration after which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection | `1s` | | | `inspection-anomaly-size` | integer | Check circle icon indicating active status

| Response size limit which the request will be considered an anomaly and the response will be inspected even if nothing else was found in the request during inspection | `524288` | | | `inspection-debug` | boolean | Check circle icon indicating active status

| Minimal header rewriting. If enabled, then only hop-by-hop headers will be removed as required by RFC-2616 sec 13.5.1. No proxy headers will be added/modified, though they will be passed through if trust-proxy-headers is set | `false` | | | `pass-host-header` | boolean | Check circle icon indicating active status

| Pass the client supplied host header through to the upstream (including the upstream TLS handshake for use with SNI and certificate validation) | `true` | | | `read-buffer-size` | integer | Check circle icon indicating active status

| Interval to flush any buffered/streaming response data (0 disables forced flushes; -1 forces flushes after every write; interval values force flushes on a fixed time interval) | `0s` | | | `response-header-timeout` | time-duration | Check circle icon indicating active status

| TLS listener cipher suites. Only affects TLS 1.2 and below. \[use --show-tls-cipher-suites for a list] | `TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256,TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA,TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA` | | | `tls-handshake-timeout` | time-duration | Check circle icon indicating active status

| TLS private key passphrase in the format `type:data`, where type is one of: `pass` or `file` (EX: `pass:mypassword` or `file:/etc/secrets/tls-key-passphrase`) | | | | `tls-min-version` | string | Check circle icon indicating active status

| Force the servername used in upstream TLS verification; consider using pass-host-header first, but this may be required if neither the hostname used by the downstream client nor the hostname/ip used in the upstream URL is listed in the upstream TLS certificate | | | | `trust-proxy-headers` | boolean | Check circle icon indicating active status

| Trust the incoming proxy (X-Forwarded-For\*) header values. If not trusted, then incoming proxy headers are removed before any additions are made | `true` | | | `upstreams` | csv-string | Check circle icon indicating active status

| Network write timeout for the listener | `0s` | ## System environment options These system level environment variable based options will also affect processing. | | Name | Type | Status | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | | `HTTP_PROXY` or `http_proxy` | url | Warning icon indicating deprecated status

| Proxy outbound HTTPS requests through the proxy at the defined URL (takes precedence over HTTP_PROXY for HTTPS requests) | | | `NO_PROXY` or `no_proxy` | csv-url | Check circle icon indicating active status

| Comma separated list of URLs NOT to proxy or '\*' for all URLs | The options are generally available in three forms, overridden in the following order: 1. In the configuration file (default: `/etc/sigsci/agent.conf`) 2. On the command line, prefixed with a double dash (--) (e.g., `--help`) 3. As an environment variable, all capitalized, prefixed with `SIGSCI_` and dashes changed to underscores (\_) (e.g., the `max-procs` option would become the `SIGSCI_MAX_PROCS` environment variable) There are a few exceptions: - Informational options such as `--help`, `--legal`, and `--version` only make sense as command line options as noted. - The `HTTP_PROXY` environment variable is deprecated and will no longer be honored for https connections. `HTTPS_PROXY` must be used. - The agent will honor the system `HTTPS_PROXY` environment variable allowing configuration of an egress HTTPS proxy URL for those sites where outbound access must be through a proxy (e.g., `HTTPS_PROXY=http://10.0.0.1:8080`). ## Configuring FIPS 140-3 compliance for the agent > **IMPORTANT:** FIPS 140-3 mode is only compatible for agent version 4.71.0 or higher. The Next-Gen WAF agent libraries and backend connections are [FIPS 140-3](https://go.dev/doc/security/fips140) compliant when FIPS 140-3 mode is enabled. FIPS 140-3 is a North American security standard used to ensure hardware and software are secure, tamper-resistant, and properly implemented to protect sensitive information. ### Linux package-based systems To achieve FIPS 140-3 compliance for communication between the agent and cloud services, enable one of the following FIPS 140-3 mode environment variables: - **`GODEBUG=fips140=only`:** the agent strictly negotiates only FIPS 140-3 approved TLS versions and algorithms. Any use of non-FIPS-approved cryptographic algorithms will cause the agent to panic or error. To enable `GODEBUG=fips140=only`, run the following command: ```term copy export GODEBUG=fips140=only ``` - **`GODEBUG=fips140=on`:** the agent negotiates only FIPS 140-3 approved TLS versions and algorithms. This option is not as strict as `GODEBUG=fips140=only` and can be used if the agent encounters issues or panics with the stricter setting. To enable `GODEBUG=fips140=on`, run the following command: ```term copy export GODEBUG=fips140=on ``` To check if FIPS 140-3 mode is enabled, send the `SIGUSR1` signal to the `sigsci-agent` process: ```term copy kill -s USR1 `pidof sigsci-agent` ``` ### Windows package-based systems To achieve FIPS 140-3 compliance for communication between the agent and cloud services, enable one of the following FIPS 140-3 mode environment variables: - **`GODEBUG=fips140=only`:** the agent strictly negotiates only FIPS 140-3 approved TLS versions and algorithms. Any use of non-FIPS-approved cryptographic algorithms will cause the agent to panic or error. To enable `GODEBUG=fips140=only`, use the [Environment](https://www.fastly.com/documentation/reference/ngwaf/agent-config#windows-based-systems) registry key to set `GODEBUG` or run the following command: ```term copy set GODEBUG=fips140=only ``` - **`GODEBUG=fips140=on`:** the agent negotiates only FIPS 140-3 approved TLS versions and algorithms. This option is not as strict as `GODEBUG=fips140=only` and can be used if the agent encounters issues or panics with the stricter setting. To enable `GODEBUG=fips140=on`, use the [Environment](https://www.fastly.com/documentation/reference/ngwaf/agent-config#windows-based-systems) registry key to set `GODEBUG` or run the following command: ```term copy set GODEBUG=fips140=on ``` ## Configuring HTTPS proxy for the agent If the system the agent is running on does not have direct internet access, it may need to be configured to access the internet via a HTTPS proxy. To do this, one or more of the `HTTPS_PROXY`, or `NO_PROXY` [system environment variables](https://www.fastly.com/documentation/reference/ngwaf/agent-config#system-environment-options) will need to be configured. While some systems may set this system wide, we recommend using the proxy for only the Next-Gen WAF agent. Also, note that the [package](https://pkg.go.dev/golang.org/x/net/http/httpproxy?utm_source=godoc#Config.ProxyFunc) the agent relies on to determine the proxy URL from `HTTPS_PROXY`, `NO_PROXY` variables, ignores `localhost` or loopback addresses (e.g., `127.0.0.1`, `0.0.0.0`) with or without the port number. If you are relying on `HTTPS_PROXY` or `NO_PROXY` environment variables to be set with either of the aforementioned addresses, use a fully qualified domain name (FQDN) via the operating systems host file (e.g., `c:\Windows\System32\Drivers\etc\hosts` or `/etc/hosts`) and use it as the value. ### Linux package-based systems On Linux and similar systems, the sigsci-agent service (e.g., systemd, upstart, init.d) will source in the `/etc/default/sigsci-agent` file containing `var=value` pairs. To set the proxy for the agent, add the environment variable configurations into this file, one per line. For example, to use the HTTPS proxy at `10.0.0.1` on port 8080, add the following to `/etc/default/sigsci-agent`: ``` HTTPS_PROXY=http://10.0.0.1:8080 ``` On distributions using upstart, the `export` function needs to be prefixed: ```term $ export HTTPS_PROXY=http://10.0.0.1:8080 ``` The `sigsci-agent` service will then need to be restarted. ### Windows package-based systems On Windows-based system where the agent is run as a service, the environment variables can be set system wide. However, this may require a system reboot for the services to acknowledge the change. If the change only needs to be set for the Next-Gen WAF agent, then set the following registry entry to update the environment settings for only the `sigsci-agent` service: 1. Add a Multi-String Value (REG_MULTI_SZ) registry entry if it does not already exist: ``` HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\sigsci-agent\Environment ``` 2. Edit the `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\sigsci-agent\Environment` value adding an environment variable and value in `var=value` form, one per line. For example: ``` HTTPS_PROXY=http://10.0.0.1:8080 ``` 3. Restart the `sigsci-agent` service. This can be done manually using `regedit.exe` or a similar utility or via the command line with something like the following, replacing the URLs with the correct proxy URLs: ```term $ reg add HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\sigsci-agent /v Environment /t REG_MULTI_SZ /d "HTTPS_PROXY=http://10.0.0.1:8080" ``` If more than one variable needs to be set, be sure to separate each `var=value` with a NULL (`\0`) character in the restart command (e.g., `"HTTPS_PROXY=http://10.0.0.1:8080\0NO_PROXY=http://localhost"`). ### Configuring the agent to use a proxy for egress traffic The agent can be configured to use a local proxy for egress traffic to the Fastly cloud infrastructure by setting the `HTTPS_PROXY` environment variable. Add the following line to `/etc/default/sigsci-agent`, replacing `IP-OR-HOST-NAME` with the IP address or hostname to proxy traffic to: ``` export HTTPS_PROXY=IP-OR-HOSTNAME ``` Restart the agent and verify the configuration. ## Next steps [Explore our module options](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/about-module-agent-deployment) and install the Next-Gen WAF module.