Upgrade to Fastly VCL v12

If you have an existing Fastly VCL Enforcer configuration, you can learn how to upgrade to v12 in this article.

Prerequisites

If you are using the Deploy Tool method, you may need:

• Depending on your preferred deployment method, the following tools:
  • Docker method:
    • Docker. See how to install Docker with their documentation.
  • Script method:
    • Node.js 20.x or later and npm 10.x or later. See how to install both with npm’s documentation.
    • Git CLI. You can download it directly from Git.
    • GNU Wget. See how to install with their documentation.
• Any custom Fastly files you would like to deploy. These are optional, but can be used to include any custom configurations you may need. Ensure they align with the latest version. If you are using the Docker method, make sure they are saved in the /deploy folder. Possible files include:
  • main.vcl (MAIN): Ensure all the px_* subroutines are invoked where needed.
  • px.vcl (PX)
  • px_configs.vcl (PX_CONFIGS): Ensure it aligns with the information in the enforcerConfig.json provided.
  • px_custom.vcl (PX_CUSTOM): Use the latest version and add any custom implementations as needed.

If you are upgrading manually, have the following ready, including with any custom implementations if needed:

• main.vcl (MAIN): Fastly's default main VCL with HUMAN logic already integrated. This file can be used as the main VCL file for Fastly services that don't have one, or as a basic example for how to integrate the HUMAN logic into an existing main VCL file.
• px.vcl (PX): All HUMAN core logic. This file should not be customized or modified in any way. Provided by HUMAN.
• px_configs.vcl (PX_CONFIGS): Contains Enforcer configuration table and additional backend configs. This file can be modified based on the desired Enforcer configuration. Provided by HUMAN.
• px_custom.vcl (PX_CUSTOM): Contains Enforcer custom code, defined custom behavior, and Enforcer features. This file can be modified based on the desired Enforcer configuration or desired custom logic that should be executed within the Enforcer. Provided by HUMAN.

Upgrade with the Deploy Tool

You can use HUMAN's Deploy Tool to quickly walk through the necessary configuration changes needed to upgrade your Enforcer version. This reduces the manual work you need to complete to upgrade the Enforcer.

🚧

Warning

Be aware that if your Enforcer version is very old, then some features and configurations may not completely carry over. Especially in these cases, the best practice is to review the upgraded Fastly service thoroughly before activating it.

Download the Enforcer configuration file

The Enforcer configuration file, enforcerConfig.json, has important information about your HUMAN account such as your Application ID or server token that the Enforcer uses to work with your application. If you don’t have one already, you need to download this file from the HUMAN console. Otherwise, move on to Create a Fastly API token.

1. Navigate to Platform Settings > Configurations > Enforcers.
2. Click the Enforcer that you’re currently updating.
3. Click the download button to download enforcerConfig.json.
4. Save the file in a directory that you’ll remember, such as /deploy.

Create a Fastly API token

If you do not have a Fastly API token yet, create one with the following steps. If you have one, move on to Run the Deploy Tool.

1. Log in to your Fastly account.
2. Navigate to Account > API Tokens > Personal tokens.
3. Click Create token.
4. Enter a name for your token, then fill out the remaining fields according to the following:
   • Type: User token. Only available for Fastly Superusers. If you don't see this field, you can skip this step.
   • Scope: Global API access (global) . Be sure to also deselect Read-only access (global:read), which is selected by default.
   • Access: All services or the specific services you want to deploy the Enforcer on
5. Click Create Token.
6. Copy and save the token in a secure location.

🚧

Warning

This will be the only time you’ll see your token, so be sure to save it before closing the page!

Run the Deploy Tool

You can run the Deploy Tool with either of the following methods:

• Docker method
• Script method

Docker method

📘

Note for Windows users

Windows users also need to complete additional setup for Docker:

1. In your Windows search bar, search for and open “Turn Windows features on or off”.
2. Find the Windows Hypervisor Platform feature and enable it.
3. Click OK to save your changes.
4. Open Windows PowerShell as an Administrator.
5. Copy and paste in C:\Windows\System32\wsl.exe --update --web-download, then hit Enter.

1. Pull the Docker Image by running:

docker pull us-docker.pkg.dev/hmn-registry/docker-public/cdn-enforcer-deploy-tool

2. Navigate to the directory where you created enforcerConfig.json. Based on our example from above, this would be the /deploy directory.
3. Run the deploy tool with the following:

docker run --rm -v $PWD:/app/local -it us-docker.pkg.dev/hmn-registry/docker-public/cdn-enforcer-deploy-tool

Script method

1. Navigate to the directory where you created enforcerConfig.json. Based on our example from above, this would be the /deploy directory.
2. Pull the HUMAN Deploy Tool zip from Google Artifact Registry using:
3. Unzip cdn-enforcer-deploy-tool.zip to the same directory you saved enforcerConfig.json in.
4. Run the tool by opening the appropriate script for your system:
   • Windows: cdn-enforcer-deploy-tool.bat
   • Mac or Linux: cdn-enforcer-deploy-tool.command

Upgrade and deploy the Enforcer

1. When prompted, select Fastly VCL and hit Enter. The Deploy Tool will detect if you have an existing Fastly Enforcer version and automatically start the process to upgrade to the latest version.

🚀 HUMAN CDN Enforcer Deploy Tool 🚀
? Which platform do you want to deploy to? (Use arrow keys)
❯ Fastly VCL
  Cloudflare Workers
  ...

2. Continue to follow the steps that appear to complete your deployment.

📘

Note

If you have any custom VCL files that are different from the default, such as custom subroutines in PX_CUSTOM, be sure to choose to deploy custom VCL files and choose those files.

3. When you finish the setup, confirm that the displayed details are correct, then enter y to deploy the Enforcer.

Upgrade manually

To ensure that you are taking advantage of the latest features, several configurations and deploy changes need to be made in order to upgrade your Fastly VCL Enforcer to version 12. This document serves as a comprehensive guide to the changes that must be made.

1. Add Async Activities and Telemetry logging endpoints

📘

Note

This change is required if upgrading from version <9.x.

Instead of using a Syslog log streaming endpoint, we've changed our async activities and telemetry logs to use Fastly's HTTP logging endpoint.

This change requires removing the older PX-Syslog logging endpoint and configuring two new logging endpoints instead. For more information about Fastly log streaming, see here.

Delete the PX-Syslog Logging Endpoint

1. In your Fastly service, go to "Logging" tab.
2. Delete the TCP logging endpoint named PX-Syslog.

Add the Async Activities Logging Endpoint

1. On your Fastly service, go to "Logging" tab

2. Add a new Logging endpoint with the information below:

   • Name: PX-Async-Activities
   • URL: https://collector-<px_app_id>.perimeterx.net/api/v1/collector/s2s
   • Placement: none
   • Maximum bytes: 500000
   • Advanced options:
     • Content type - application/json
     • JSON log entry format - Array of JSON
     • All other fields: No change is needed, use the default values.

Add the Telemetry Logging Endpoint

1. On your Fastly service, go to "Logging" tab
2. Use the following settings to define a new additional logger:
   • Name: PX-Telemetry
   • URL: https://collector-<px_app_id>.perimeterx.net/api/v2/risk/telemetry
   • Placement: none
   • Maximum Logs: 1
   • Advanced options
     • Content type - application/json
     • All other fields: No change is needed, use the default values.

2. Validate the px_configs configuration table in the PX_CONFIGS VCL file

Several configuration options were deprecated in Fastly VCL v10. If one or more configurations in the list below are present in the px_configs table of the PX_CONFIGS VCL file, please modify them accordingly.

3. Validate the subroutines and tables in the PX_CUSTOM VCL file

To change the PX_CUSTOM file:

1. Make a copy of your PX_CUSTOM VCL file on your local computer for safekeeping.
2. Upload the new v12 PX_CUSTOM VCL file to your Fastly service.
3. One by one, compare each custom subroutine in your old PX_CUSTOM VCL with the new subroutine. Transfer the previously existing implementation to the new PX_CUSTOM VCL file, modifying it as needed. All desired logic should remain the same (pay special attention to conditionals and regular expressions!); most if not all the changes will likely be related to header names and return values. See the table below for details about specific subroutines.

Some tables and dictionaries in the PX_CUSTOM VCL file have also changed. See the table below for details.

If upgrading from 9.x and earlier

As part of an effort to reduce HUMAN's Fastly VCL workspace footprint, many custom subroutines in the PX_CUSTOM VCL file have been changed to return boolean values instead of setting headers.

Please pay special attention to these custom subroutines:

• px_custom_check_sensitive_route
• px_custom_check_sensitive_graphql_operation
• px_custom_filter_by_http_method
• px_custom_filter_by_user_agent
• px_custom_filter_by_route
• px_custom_filter_by_extension
• px_custom_filter_by_ip
• px_custom_enforced_routes
• px_custom_monitored_routes
• px_custom_check_enabled_route

We've also adjusted px_custom_check_sensitive_route subroutine to return a boolean value instead of setting a header. Here is the previous implementation of this subroutine:

# implementation in v9.x and below
sub px_custom_check_sensitive_route {
    if (req.url.path ~ {"<sensitive_routes>"}) {
        set req.http.X-PX-sensitive-route = "1";
    }
}

Compare this with the newer implementation of the subroutine:

# implementation in v12
sub px_custom_check_sensitive_route BOOL {
    if (req.url.path ~ {"<sensitive_routes>"}) {
        return true;
    }
    return false;
}

The regular expression in the condition (i.e., <sensitive_routes>) should stay the same for both implementations. The difference is that instead of setting the X-PX-sensitive-route header, we can simply return true.

4. Remove references to X-PX-* headers

In version 9.x and earlier, HUMAN used headers beginning with x-px-* to store information during the duration of the Fastly request life cycle. These headers have been renamed in version 12 and will no longer be present on the request. Any references to these headers in your Fastly VCL code should be removed.

🚧

Warning

If you have logic in your Fastly VCL files that relies on these x-px-* headers, please reach out to your HUMAN Solution Architect or Customer Support for guidance on how to align this code with version 12.

5. Add remote configuration parameters and dictionaries

Version 12 includes the new remote configuration feature. Remote configuration is a feature that lets you access and modify your Enforcer’s configuration remotely without redeploying. This also allows the HUMAN team to troubleshoot or customize your Enforcer directly. Remote configuration is required as part of your Enforcer setup.

📘

Note

HUMAN will never change your Enforcer configuration without your permission. You can learn more about remote configurations with our help article.

• Please refer to the instructions here for how to add the new remote configuration fields to your PX_CONFIGS VCL file.
• Please refer to the instructions here for how to add in the required dictionaries to your Fastly VCL service.

6. Add a call to px_log in the vcl_log subroutine

As part of version 12 we have moved the sending of our async activities to the px_log subroutine, which should be called at the beginning of the vcl_log subroutine. Please add a call to the px_log subroutine at the beginning of the vcl_log subroutine (see Install the Fastly VCL Enforcer v12 for an example).