Getting started with the agent
The Next-Gen WAF agent (formerly known as the Signal Sciences agent) is an architecture component. It uses your active rules and threshold configurations to determine how to handle requests (e.g., allow or block) and communicates with our cloud engine. For deployments where the Next-Gen WAF module component is not present, the agent also performs the module's responsibilities, including executing decisions made during analysis.
All Next-Gen WAF deployment methods use the agent component, but you only need to install and manage the component for On-Prem WAF deployments (i.e., module-agent or reverse proxy deployments). Fastly manages Edge WAF and Cloud WAF deployments.
Installing the agent
To install the agent for an On-Prem WAF deployment, complete the following steps:
Follow the agent installation instructions for your operating system.
(Optional) Configure the agent for your environment.
(Optional) Set up agent alerts to inform you when:
- the number of online agents reaches a specified threshold.
- the average number of requests per second (RPS) for all agents across all sites (workspaces) reaches a specified threshold.
Upgrading the agent
Per our agent end-of-support policy, we support agent versions that are under two years old. On a quarterly cadence, we deprecate and no longer support agent versions that are older than two years. If you want to upgrade your agent to a newer version, you can:
- manually upgrade the agent and then restart the agent.
- enable the agent auto-update service. The agent auto-update service checks at regularly occurring intervals for a new version of the agent and updates the agent when a new version is available.
Using agent configuration management systems
The agent can be managed via various configuration management systems (e.g., Chef, Puppet, and Ansible). To use a configuration management system, construct or expand an agent configuration file (typically agent.conf) or use environment variables. For a list of values that can be configured, check out our Configuring the agent guide.
Agent start-up behavior
When the agent starts up, it will send http requests to one or more addresses in order to determine what environment it is running in and optimize for that environment. The addresses are:
http://169.254.169.254/latest/api/tokenhttp://169.254.169.254/latest/meta-data/instance-typehttp://metadata.google.internal/computeMetadata/v1/instance/machine-typehttp://169.254.169.254/metadata/instance/compute/vmSize
Agent reliability
To optimize performance and improve reliability, the Next-Gen WAF architecture is split between the agent and module. If the agent experiences issues or unavailability, your application will continue to function because the module fails open if it doesn’t hear back from the agent within a set time limit. The default timeouts vary by module type and are as follows:
| Module | Timeout |
|---|---|
| Windows IIS | 200ms |
| .NET | 200ms |
| .NET Core | 200ms |
| All other modules | 100ms |
If the agent loses the ability to communicate with the cloud engine, the agent will continue to function with the following caveats:
- The agent will continue to detect attacks, anomalies, and any custom rules or signals based on local configurations at time of communication failure.
- The agent will continue to enforce existing blocking decisions.
- For On-Prem WAF and Cloud WAF deployments, the agent's local counters will continue to tally requests that count towards configuration limits (i.e., attack thresholds, site alerts (signal thresholds) and advanced rate limiting rules). When multiple agents are deployed, aggregation will not occur until communication resumes.
- The agent will not queue request logs and there will be an outage of data shown in the control panel. The ability to look at individual requests or aggregate data will be lost until the connection is reestablished.
- The agent will not receive configuration updates made via the control panel and API you have access to.
- The agent will not receive updates for new detections or enforcement decisions.
- The agent will not receive updated geolocation data.
Threshold counting
For On-Prem WAF and Cloud WAF deployments, the agent has local counters and is immediately able to determine when a request violates an attack threshold, site alert (signal threshold), or advanced rate limiting rule. The agent uses aggregation from the cloud engine when multiple agents are deployed.
For information on how threshold counting works for Edge WAF deployments, check out How the Edge WAF works.
Agent language
The agent is written in Go. We chose Go because of its combination of performance, ease of deployment, and memory safety guarantees. In addition, Go doesn't have the security issues associated with C/C++ (e.g., buffer overflows).
