Banning paths

This tutorial expects you to have setup a working VCLGroup, if you have not please follow the Deploying VCL files tutorial. The purging and banning in the Varnish Controller makes use of HTTP purging and banning, meaning you need to have additional configuration in your VCL. Please make sure you have setup the banning over HTTP correctly, here is an example.

In these examples we will send a ban request. We will send the regular expression in a header just like the example in the introduction of this example.

Based on a VCLGroup

In this example we have a VCLGroup deployed to 2 agents. The VCLGroup has ID: 1.

$ vcli inv new --vg 1 -p / -H x-invalidate-pattern=".*/.jpg$" -m BAN

This invalidation request will be send to all agents that have VCLGroup 1 deployed, the Varnish Controller Agent will send a HTTP request for each path and for each domain configured in the VCLGroup to Varnish with the defined HTTP method (in this case BAN).

Argument	Description
`--vg 1`	Defines the VCLGroup ID to invalidate, the Varnish Controller will send the invalidation request to all agents connected to the VCLGroup.
`-p /`	Defines the path to invalidate. Per defined path an invalidation request is send, in order for our BAN request to be send we need to define at least 1 path.
`-H x-invalidate-pattern=".*/.jpg$"`	Defines the `x-invalidate-pattern` header. Here we defined it with a regex that is used for banning.
`-m BAN`	Defines the HTTP method, it needs to correspond with the method you defined in your VCL. Here we use the method `BAN`.

Go to the Invalidations page and click the button New invalidation.

Select the VCLGroup you want to invalidate.
Add the x-invalidate-pattern header and the corresponding .*/.jpg$ as a value.
Enter or select the method you want to send the invalidation request with. Usually for banning you use BAN.
Enter the paths you want to invalidate. Here we need to define 1 path so 1 request is send per Varnish instance.
Click the Invalidate button.

Within a few seconds or less depending of the size of invalidation you will see if it succeeded or failed. To inspect why it failed, click the invalidation request. You will see the error code or possible error message.

image alt >

Option	Description
VCLGroup	Defines the VCLGroup to invalidate, the Varnish Controller will send the invalidation request to all agents connected to the VCLGroup.
Headers	Defines the headers that need to be send with the HTTP request to Varnish.
Invalidation method	Defines the HTTP method, it needs to correspond with the method you defined in your VCL. Here we use the method `BAN`.
Paths	Defines the paths to invalidate.

The CLI and the UI use the API of the controller to send invalidations. There is also the possibility to send in the banning request directly to the API instead and integrate it with for example your CMS or other pipeline. To achieve the same BAN request as the CLI you can send in the following API request to the API-GW. More examples.

POST /api/v1/invalidations

{
    "method": "BAN",
    "paths": ["/"],
    "headers": {"x-invalidate-pattern": ".*/.jpg$"},
    "vclGroup": {"id": 1}
}

Based on a root deployed VCLGroup

In this example we have a root deployed VCLGroup deployed to 2 agents. The VCLGroup has ID: 2. When invalidating a root deployed VCLGroup the Varnish Controller does not know what domains are running. Therefore it is required to add domains to the invalidation command.

$ vcli inv new --vg 2 -d fqdn=example.org -p / -H x-invalidate-pattern=".*/.jpg$" -m BAN

This invalidation request will be send to all agents that have VCLGroup 2 deployed, the Varnish Controller Agent will send a HTTP request for each path with the example.org domain to Varnish with the defined HTTP method (in this case BAN).

Argument	Description
`--vg 2`	Defines the VCLGroup ID to invalidate, the Varnish Controller will send the invalidation request to all agents connected to the VCLGroup.
`-d fqdn=example.org`	Defines domain(s) to invalidate. The domains do not have to exists in the controller, with root deployments a domain is required to define.
`-p /`	Defines the path to invalidate. Per defined path an invalidation request is send, in order for our BAN request to be send we need to define at least 1 path.
`-H x-invalidate-pattern=".*/.jpg$"`	Defines the `x-invalidate-pattern` header. Here we defined it with a regex that is used for banning.
`-m BAN`	Defines the HTTP method, it needs to correspond with the method you defined in your VCL. Here we use the method `BAN`.

Go to the Invalidations page and click the button New invalidation.

Select the VCLGroup you want to invalidate.
Enter or select the domains you want to invalidate.
Add the x-invalidate-pattern header and the corresponding .*/.jpg$ as a value.
Enter or select the method you want to send the invalidation request with. Usually for banning you use BAN.
Enter the paths you want to invalidate.
Click the Invalidate button.

image alt >

Option	Description
VCLGroup	Defines the VCLGroup to invalidate, the Varnish Controller will send the invalidation request to all agents connected to the VCLGroup.
Domains	Defines domain to send the BAN requests for. You can either select domains or enter the FQDN manually.
Headers	Defines the headers that need to be send with the HTTP request to Varnish.
Invalidation method	Defines the HTTP method, it needs to correspond with the method you defined in your VCL. Here we use the method `BAN`.
Paths	Defines the paths to invalidate.

POST /api/v1/invalidations

{
    "method": "BAN",
    "paths": ["/"],
    "headers": {"x-invalidate-pattern": ".*/.jpg$"},
    "domains": {"fqdn": "example.org"},
    "vclGroup": {"id": 2}
}