Upgrade to Fastly VCL v11

Before We Start

The HUMAN Fastly VCL Enforcer consists of a number of different components: VCL files, snippets, and logging endpoints. The majority of the Fastly VCL enforcer logic is housed in four VCL files that need to be uploaded to your service:

📘

Before Starting

These 3 custom VCL files will be provided to you by a HUMAN Solution Architect:

• px.vcl
• px_configs.vcl
• px_custom.vcl

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 11. This document serves as a comprehensive guide to the changes that must be made.

---

1. Add Async Activities and Telemetry logging endpoints.

📘

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.

How 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 v11 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

📘

Example

We've 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:

Vcl

# 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:

Vcl

# implementation in v11
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 11 and will no longer be present on the request. Any references to these headers in your Fastly VCL code should be removed.

🚧

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 11.

5. Add remote configuration parameters and dictionaries.

Version 11 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.