Manually creating access control lists

Varnish allows you to use access control lists (ACLs), a feature that enables fast matching of a client's IP address against a list of defined IP addresses. An ACL in Varnish looks like this:

1
2
3
4
5
6

# Who is allowed access ...
acl local {
  "localhost";
  "192.0.2.0"/24; /* and everyone on the local network */
  ! "192.0.2.1"/32; /* except for the dial-in router */
}

Before you begin

Be sure you understand how ACLs work in Fastly.

Limitations and considerations

Note the following limitations and considerations for ACLs manually created with custom VCL:

• ACLs created with custom VCL are always versioned. ACLs created with custom VCL are always tied to a service and require a new service version each time they are updated in any way. This is true for both the ACLs created using custom VCL and for any logic created to interact with those ACLs.
• ACLs created with custom VCL cannot be manipulated using the API. If you create an ACL using custom VCL, that ACL must always be manipulated via custom VCL and can never be manipulated using the Fastly API. ACLs created using the API, however, can be manipulated using both the API and custom VCL.

Defining an ACL

Using ACLs requires you to create and add custom VCL to Fastly's boilerplate VCL. To define an ACL in your Fastly configuration:

1. Read about how to mix and match custom VCL with Fastly VCL.

2. Create a custom VCL file with your ACL definitions included in the appropriate location. Use the example shown below as a guide. You can reference the ACL in your configuration (vcl_recv) using a match operation that can be located above or below #FASTLY recv. The placement only matters for the order of operations within Varnish's execution of your configuration.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16

   # If you are using the "include" keyword
   include "myACL1.vcl";
   
   # And/or if you are using an actual ACL block
   acl local {
     "localhost";
     "192.0.2.0"/24; /* and everyone on the local network */
     ! "192.0.2.1"/32; /* except for the dial-in router */
   }
   
   sub vcl_recv {
     # block any requests to Admin pages not from local IPs
     if (req.url ~ "^/admin" && req.http.Fastly-Client-IP !~ local) {
       error 403 "Forbidden";
     }
   }

3. Upload the file in the Varnish Configuration area of your service.

Example ACL use

Let's suppose you've used the Fastly API to create an ACL and add ACL entries, after which the VCL for the ACLs and ACL entries will be automatically generated, as shown below. For example, this VCL shows an ACL called office_ip_ranges has been created:

1
2
3
4
5
6
7

# This VCL is automatically generated when you create an ACL container and entries
# using the Fastly API. In this example, the ACL name is office_ip_ranges.
acl office_ip_ranges {
  "192.0.2.0"/24;                              # internal office
  "198.51.100.4";                              # remote VPN office
  "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff";    # ipv6 address remote
}

Once created, you can add logic to interact with your ACL at the edge by uploading custom VCL. You could use the office_ip_ranges ACL as an allow list by uploading the following custom VCL:

1
2
3
4
5
6

sub vcl_recv {
  # block all requests to Admin pages from IP addresses not in office_ip_ranges
  if (req.url ~ "^/admin" && client.ip !~ office_ip_ranges) {
    error 403 "Forbidden";
  }
}

With this VCL, access to /admin is denied for everyone by default, but the IP addresses listed in the ACL are allowed to access /admin without restriction.