Blocking visitors

Blocking lets a zone refuse traffic you do not want. You set the rules on the zone and every location enforces them, so a refused request never reaches your origin and never costs you bandwidth.

What you can block#

• Addresses: individual IP addresses or ranges in CIDR form, IPv4 and IPv6, one per line, up to 1,000 entries.
• Countries: either the countries to refuse, or the only countries to serve. Which of the two is a setting, and the box says in words which way round your list is being read.
• Networks: AS numbers, up to 200. One AS number is one network, so blocking AS16509 refuses the addresses Amazon announces from that network; a large provider announces from several AS numbers, so blocking a whole provider takes each of them.
• Tor exit nodes: visitors arriving through the Tor network, whether the exit reaches you over IPv4 or IPv6.
• VPN networks: visitors using a commercial VPN service.
• Hosting and datacenter networks: visitors from cloud and hosting providers rather than home and mobile connections.

All of it is one box on the zone page, saved with Save blocking rules. The address that is judged is the one that connects to us. A visitor behind a corporate proxy or a VPN is judged by the proxy's address, and a country rule places that address, not the person behind it.

The always allow list comes first#

Every address in the always allow list is served, whatever else your rules say. Put your own office, your monitoring and your deploy machines in it before you switch anything else on. This matters most with the hosting and datacenter switch: your staging site, your uptime checker and your CI runner almost certainly live in a datacenter, and without an exception they are refused along with everyone else.

Blocking countries, and serving only some#

Block these countries refuses visitors the country data places in the countries you listed, and serves everyone else, including anyone it cannot place.

Serve only these countries refuses everyone the data does not place in your list, including anyone it cannot place. That is the stricter reading, and the right one when you are allowed to serve a named set of countries and nobody else. The list cannot be empty in this mode: serving only the countries on an empty list would refuse everyone, so the zone page and the API both refuse to save it.

What a refused visitor sees#

A 403 page on your own hostname, saying that the owner of the site has restricted access from their network, and suggesting they contact you. It never says which rule caught them, and it carries the CacheGenie mark and nothing else of ours.

A request that did not ask for a web page, such as a video player fetching a segment, gets one line of plain text instead of the page. The rule that fired is in the X-CDN-Block response header on every refusal, so one request tells you which it was, and so can a visitor with the browser's developer tools open.

Where the data comes from#

Country data comes from DB-IP, network data from iptoasn, the Tor exits from the Tor Project (its bulk exit list for IPv4 and its Onionoo relay data for IPv6), and the VPN and hosting lists from the X4BNet project. We refresh all of them daily.

Country data is an estimate, not a measurement: it is right for the overwhelming majority of addresses and occasionally wrong for one, particularly on mobile networks that move addresses between regions. And the VPN list does not cover every provider in the world, only the common ones, and it cannot see a private VPN somebody runs themselves.

What the statistics show#

The Where visitors came from box on the zone's statistics page says how many of the requests you served came from VPN networks, hosting and datacenter networks and Tor exit nodes over the period, which is what switching a rule on would have refused: read it before you switch one on. Once something has been refused, a Served and Blocked switch in that box shows the countries refused, the refusals by each network rule and every AS number you block, with its registered name and how many requests from it were refused, and a Blocked tile at the top of the page counts refusals by rule. Blocked requests are counted but never billed: the refusal is our response, not your content, so it carries no bandwidth.

Through the API#

Every rule is a field on the zone, so a deploy script can set them with the same call it already makes.

curl -X POST https://api.cachegenie.com/v1/cdn/AB12CD34E \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "COUNTRIES": "GB,IE",
    "COUNTRY_MODE": "ALLOW",
    "BLOCK_ASNS": "16509,13335",
    "BLOCK_IPS": "203.0.113.0/24\n2001:db8::/32",
    "ALLOW_IPS": "198.51.100.7",
    "BLOCK_TOR": 1
  }'

The lists are strings rather than arrays. A field you leave out keeps whatever the zone already has, and a field you send empty clears it, so a call that means to change one thing cannot wipe your rules by not mentioning them. Zones lists every field and every message a bad value gets.

The statistics endpoint returns the same breakdowns as the page, in CDN_COUNTRIES and CDN_NETWORKS.

What it is not#

There is no rule per path: blocking applies to the whole zone, so different rules for different parts of a site take a second zone. There is no rate limiting. The always allow list is the only bypass. And your own certificate renewals keep working: the ACME challenge path is exempt from every rule.

Country data: IP Geolocation by DB-IP. Network data: iptoasn.