Centinel AnalyticaCentinel Analytica
Platforms

Fastly VCL

Deploy Centinel Analytica on your Fastly service via VCL snippets or Terraform.

Overview

This guide covers the Centinel Fastly integration. You can deploy using the Fastly Web UI (manual VCL upload) or Terraform. VCL changes propagate in 2-3 minutes.

Prerequisites

  • Centinel API key (for validator authentication)
  • Fastly account with a service configured
  • Access to Fastly dashboard or Terraform CLI
  • Origin backend named origin in your Fastly service

Method 1: Manual installation via Fastly Web UI

Step 1: Download the VCL snippets

  1. Download or copy all VCL snippet files from the snippets/ directory:

    • init.vcl
    • recv.vcl
    • fetch.vcl
    • deliver.vcl
    • miss.vcl
    • pass.vcl
    • error.vcl

  2. Keep your CENTINEL_API_KEY ready (you'll add it to init.vcl in Step 3).

Step 2: Prepare your service

  1. Log into your Fastly dashboard.
  2. Select your service or create a new one.
  3. Click Clone version to create a draft (you can't edit active versions).
  4. Make sure your origin backend is named origin (or update VCL references to match).

Step 3: Upload init.vcl

  1. Go to VCL Snippets → Create snippet.
  2. Configure:
    • Name: centinel_init
    • Type: init
    • Priority: 50
  3. Paste the contents of init.vcl.
  4. Replace YOUR_CENTINEL_API_KEY on line 38 with your actual API key: 
    set bereq.http.X-API-Key = "your-actual-api-key-here";
  5. Click Create.

Step 4: Upload recv.vcl

  1. Click Create snippet again.
  2. Configure:
    • Name: centinel_recv
    • Type: recv
    • Priority: 50
  3. Paste the contents of recv.vcl.
  4. Click Create.

Step 5: Upload fetch.vcl

  1. Click Create snippet again.
  2. Configure:
    • Name: centinel_fetch
    • Type: fetch
    • Priority: 50
  3. Paste the contents of fetch.vcl.
  4. Click Create.

Step 6: Upload deliver.vcl

  1. Click Create snippet again.
  2. Configure:
    • Name: centinel_deliver
    • Type: deliver
    • Priority: 50
  3. Paste the contents of deliver.vcl.
  4. Click Create.

Step 7: Upload miss.vcl, pass.vcl, and error.vcl

Repeat for the remaining snippets:

miss.vcl:

  • Name: centinel_miss
  • Type: miss
  • Priority: 50

pass.vcl:

  • Name: centinel_pass
  • Type: pass
  • Priority: 50

error.vcl:

  • Name: centinel_error
  • Type: error
  • Priority: 50

Step 8: Activate the service

  1. Review all snippets to make sure they're uploaded correctly.
  2. Click Activate to deploy the new version.
  3. Wait 2-3 minutes for changes to propagate globally.

Step 9: Verify deployment

  • Visit your site to confirm traffic flows normally.
  • Test that requests to protected paths are validated by Centinel.
  • Check Fastly real-time stats for requests to the centinel backend.
  • Monitor for 403 responses (blocked requests) in your analytics.

Step 1: Install prerequisites

# Install Terraform (if not already installed)
brew install terraform  # macOS
# or download from https://terraform.io

# Verify installation
terraform --version

Step 2: Set up authentication

# Set your Fastly API token
export FASTLY_API_KEY="your-fastly-api-token"

You can create an API token in your Fastly dashboard under Account → Personal API tokens.

Step 3: Configure variables

Navigate to the snippets/ directory and create terraform.tfvars:

cd Centinel-Fastly/snippets

Create terraform.tfvars:

# Required variables
centinel_api_key = "your-centinel-api-key"
domain_name      = "www.example.com"
origin_address   = "origin.example.com"

# Optional variables
service_name     = "Production Web Service"
origin_port      = 443
origin_use_ssl   = true

Step 4: Initialize Terraform

terraform init

This downloads the Fastly provider and prepares your workspace.

Step 5: Review the plan

terraform plan

Review what gets created:

  • Fastly service with your domain
  • Origin backend
  • 7 VCL snippets (init, recv, fetch, deliver, miss, pass, error)

Step 6: Deploy

terraform apply

Type yes to confirm.

Step 7: Verify deployment

# View the service ID and domain
terraform output service_id
terraform output service_domain

# Check the active version
terraform output service_version

Visit your domain to test.

Advanced configuration

Option 1: Customize path exclusions

Edit recv.vcl line 10 to modify which paths are protected:

# Protect all paths except static assets (default)
set var.centinel_exclusion_regex = "(?i)\.(avi|avif|bmp|css|eot|...)$";

# Protect only API and admin paths
set var.centinel_exclusion_regex = "^/(?!api|admin)";

# Exclude specific paths
if (req.url.path ~ "^/(health|status|metrics)") {
  set req.http.X-Centinel-Skip = "monitoring";
}

Option 2: Adjust timeouts

Edit init.vcl lines 66-68 to modify validator API timeouts:

.connect_timeout = 500ms;      # Increase from 300ms
.first_byte_timeout = 500ms;   # Increase from 300ms
.between_bytes_timeout = 150ms; # Increase from 100ms

Higher timeouts reduce false positives but add latency.

Option 3: Enable debug logging

Add a logging endpoint in recv.vcl to track Centinel decisions:

# Add after line 15
if (req.http.X-Centinel-Original-Method) {
  log "syslog " req.service_id " centinel :: "
    "url=" req.url
    " ip=" client.ip
    " decision=" req.http.X-Centinel-Decision;
}

Then configure a logging endpoint in your Fastly service to capture these logs.

Option 4: Custom block pages

The validator API returns HTML via the X-Centinel-Response-HTML header. Configure custom pages in your Centinel dashboard.

To modify fallback pages, edit fetch.vcl:

Default block page (lines 96-103):

set var.block_html = {"<!DOCTYPE html>
<html>
<head><title>Access Denied</title></head>
<body>
<h1>Access Denied</h1>
<p>Your request has been blocked by Centinel bot protection.</p>
</body>
</html>"};

Default verification page (lines 124-131):

set var.redirect_html = {"<!DOCTYPE html>
<html>
<head><title>Verification Required</title></head>
<body>
<h1>Verification Required</h1>
<p>Please complete the verification to continue.</p>
</body>
</html>"};

After editing, activate the new service version or run terraform apply.

Configuration reference

Environment variables (Terraform)

VariableTypeRequiredDefaultDescription
centinel_api_keystringYes–Centinel API key for validator authentication.
domain_namestringYes–Your service domain (e.g. www.example.com).
origin_addressstringYes–Origin backend address.
service_namestringNocentinel_protected_serviceFastly service name.
origin_portnumberNo443Origin backend port.
origin_use_sslbooleanNotrueUse SSL for origin connection.

VCL configuration (manual)

Edit these directly in the VCL files:

init.vcl:

  • Line 38: X-API-Key - Your Centinel API key
  • Line 66-68: Timeout values
  • Line 59: Validator hostname (advanced users only)

recv.vcl:

  • Line 10: centinel_exclusion_regex - Path exclusion pattern
  • Line 8: centinel_enable_protection - Enable/disable protection

Changelog

  • 1.0.0 - Initial release with VCL snippets and Terraform support

Fastly Compute (Rust)

Add Centinel Analytica bot protection to your Fastly Compute service using the Rust SDK.

Next.js

Add Centinel Analytica to your Next.js application.

On this page

Method 1: Manual installation via Fastly Web UIStep 1: Download the VCL snippetsStep 2: Prepare your serviceStep 3: Upload init.vclStep 4: Upload recv.vclStep 5: Upload fetch.vclStep 6: Upload deliver.vclStep 7: Upload miss.vcl, pass.vcl, and error.vclStep 8: Activate the serviceStep 9: Verify deploymentMethod 2: Terraform deployment (recommended)Step 1: Install prerequisitesStep 2: Set up authenticationStep 3: Configure variablesStep 4: Initialize TerraformStep 5: Review the planStep 6: DeployStep 7: Verify deploymentAdvanced configurationOption 1: Customize path exclusionsOption 2: Adjust timeoutsOption 3: Enable debug loggingOption 4: Custom block pagesConfiguration referenceEnvironment variables (Terraform)VCL configuration (manual)Changelog