Fastly VCL Integration

Overview

This quickstart outlines the installation workflow for the Centinel Fastly integration. You can deploy using either the Fastly Web UI (manual VCL upload) or Terraform (infrastructure-as-code). Allow 2-3 minutes for VCL changes to propagate across Fastly's edge network.

Prerequisites

• Centinel API key (for validator authentication)
• Fastly account with a service configured
• Access to the 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 version (you cannot edit active versions).
4. Ensure your origin backend is named origin (or update VCL references accordingly).

Step 3 · Upload init.vcl

1. Go to VCL Snippets → Create snippet.
2. Configure the snippet:
   • Name: centinel_init
   • Type: init
   • Priority: 50
3. Paste the contents of init.vcl.
4. IMPORTANT: 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 the upload process 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 ensure 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 website to confirm normal traffic flow.
• 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.

Method 2: Terraform Deployment (Recommended)

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 a terraform.tfvars file:

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 the resources that will be 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 when prompted to confirm the deployment.

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 the integration.

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 the chance of false positives but increase 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 the default 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 making changes, activate the new service version or run terraform apply.

Configuration Reference

Environment Variables (Terraform)

VCL Configuration (Manual)

Edit these values 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