About ACLs

Malicious actors can present themselves in a variety of ways on the internet. Automated tools can scrape information from your website, bots can probe your application for vulnerabilities, and hackers can exploit them. Using access control lists (ACLs) at the edge can help prevent the offending IP addresses they use from ever accessing your information resources.

When ACLs can be useful

Access control lists at the edge might be useful for:

• E-commerce companies preventing scraping from certain IP ranges
• Offices restricting access to their administrative portals
• Advertising technology companies blocking bad-actors at the edge
• Mobile applications accepting only calls from specific proxies or IP ranges
• System administrators restricting access to groups of backends from an office IP address or subnet range

How ACLs work

ACLs have two parts: an ACL container and the ACL entries within it. In combination, containers and entries allow you to store a list of permissions that Varnish will use to grant or restrict access to URLs within your services.

Once you attach an ACL container to a version of your service and that service is activated, the data in the container (the ACL entries) becomes versionless. This means that once your service is activated, any further changes to the data within, such as the addition of ACL entries, will become effective immediately.

Ways to create ACLs

To create an ACL at the edge and use it within your service, start by creating an empty ACL container and then add its entries in a working version of a service that's unlocked and not yet activated. You can create ACLs in several ways:

• Via Fastly's web interface or API: You can create your ACLs at the edge via the Fastly web interface or via the Fastly API. We recommend these options for most configurations that integrate websites or applications with an ACL at the edge.
• Using custom VCL: You can manually create an ACL using VCL. We recommend this option only if you have simple access control requirements and can hardcode a few IP addresses in your VCL. Manually created ACLs are versioned with your services and any changes to the ACL will require changes to your VCL.

Example ACL use

After you've used the Fastly API to create an ACL and add ACL entries, 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.

Limitations

When working with ACL containers and entries specifically, remember the following:

• ACL entry changes via the API don't appear in the event logs. If you use the API to add, update, or remove an ACL entry, there will be no record of it in the audit log or event log. The only record of a change will exist when you compare service versions and view the exact point at which the ACL was associated with the service version in the first place.
• ACL entry deletions are permanent. ACL entries are versionless. This means that if you delete an entry within an ACL container, that entry is permanently removed from all service versions and cannot be recovered.
• ACL containers are limited to 1000 ACL entries. If you find your containers approaching this entry limit, contact support. We may be able to help you figure out an even more efficient way to do things with your ACLs at the edge.
• Deleted ACL containers are only removed from the service version you're editing. ACL containers are tied to versions of services, which can be cloned and reverted. When you delete an ACL container, only the configuration of the service version you're editing will be affected. We remove the ACL entries inside a container but only for the specific service version you're editing. The ACL entries themselves are not deleted from the ACL in earlier versions of your service's configuration. This allows you to revert your configuration to a previous version in as few steps as possible.

When creating and manipulating ACLs at the edge, keep the following limitations in mind as you develop your service configurations:

• 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 both using the API and custom VCL.