Using the Next-Gen WAF core command line utility

  Last updated 2024-03-05

IMPORTANT

This guide only applies to Next-Gen WAF customers with access to the Next-Gen WAF control panel. If you have access to the Next-Gen WAF product in the Fastly control panel, you can only deploy the Next-Gen WAF with the Edge WAF deployment method.

The Next-Gen WAF core command line utility (ngwafctl) can help troubleshoot Next-Gen WAF Core WAF installations within Kubernetes environments. Much like Kubernetes kubectl, our utility reads from your cluster's Kubernetes API. It then collects infrastructure information about your Kubernetes environment and cloud provider as they relate to your Next-Gen WAF Core WAF installation, performs local analysis of the configuration, and writes the information to a local archive file on disk.

You can use the collected information and suggestions from ngwafctl to help diagnose issues with your Kubernetes Next-Gen WAF installation. You can also send the collected information to our Support team for additional help.

About the utility

ngwafctl collects information about how your Next-Gen WAF Core WAF deployment is integrated with your Kubernetes cluster and cloud provider. The utility doesn't fetch Kubernetes secrets, and it redacts environment variables that don't have a SIGSCI prefix.

The gathered information is temporarily held in program memory and then written to disk as a TAR.GZ archive file. The utility doesn't send any of the gathered information to Fastly. You can inspect the type of information the utility collects by opening the generated TAR.GZ file prior to submitting the archive to Fastly.

In some cases the utility may be able to automatically detect simple misconfigurations in the Next-Gen WAF deployment, which would be reported during the utility's execution. In addition to these automated checks, submitting the generated support bundle archive to the Fastly Support team can simplify the troubleshooting process for more complex situations.

Prerequisites

For ngwafctl to access and fetch information about your Kubernetes environment, the computer running the utility needs read access to your cluster's Kubernetes API. If you have a working kubectl CLI, the ngwafctl utility should be able to connect to your cluster.

If you want the utility to collect information from your cloud provider, such as load balancer information, the computer running the utility needs a working CLI for the cloud provider (e.g., AWS CLI, Google Cloud CLI, or Azure CLI).

Installing the utility

To install ngwafctl, complete the following steps:

  1. Download the utility from the package downloads site.

  2. Extract the contents of the downloaded file by running the following command, being sure to replace <utility-file-name> with the file name (including the extension) of the downloaded file:

    $ tar -xzvf <utility-file-name>

  3. If you use Linux, make the downloaded file executable by running the following command, being sure to replace <utility-file-name> with the file name (including the extension) of the downloaded file:

    $ chmod +x <utility-file-name>

  4. If you use macOS, remove the com.apple.quarantine extended attribute from the utility by running the following command:

    $ xattr -d com.apple.quarantine ngwafctl

  5. Verify that the utility can connect to your Kubernetes cluster by running the following command:

    $ ngwafctl diagnose

    If you have a working kubectl CLI, our utility can likely find the credentials it may need. If the credentials for your kubectl CLI aren't in a standard location or you don't have a working kubectl CLI, provide ngwafctl with the location of the Kubernetes cluster credentials. Check out Kubernetes' Accessing Clusters guide for more information.

Configuring the utility

After installing the utility, you can optionally change the default value of the following configuration options by specifying the flags on the command line, setting the corresponding environment variable, or creating a config file in ~/.ngwafctl-diagnose:

CLI config optionEnvironment variableDescription
--debugNGWAFCTL_DEBUGWhether debug level logging is enabled. By default, debug logging is disabled (false).
--namespacesNGWAFCTL_NAMESPACESComma separated list of namespaces to collect. Unless changed, the default namespace is used.
--outNGWAFCTL_OUTLocation to output the support bundle. The default location is ./fastly-support-bundle_<timestamp>.tar.gz.
--traceNGWAFCTL_TRACE Whether trace level logging is enabled. By default, trace logging is disabled (false).

Running the utility

To gather information about your Kubernetes environment, complete the following steps:

  1. Run the diagnose command:

    $ ngwafctl diagnose

  2. Retrieve the support bundle. By default, the support bundle will be located in the same directory as the utility and will be named fastly-support-bundle_<timestamp>.tar.gz (e.g.,fastly-support-bundle_2024-03-05T16-07-05Z.tar.gz).

  3. (Optional) Send the support bundle, along with a detailed description of the issue to our Support team.

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