Skip to content

Custom lists

A custom list contains one or more items of the same type (for example, IP addresses, hostnames, or ASNs) that you can reference collectively, by name, in rule expressions.

Cloudflare supports the following custom list types:

Each type has its own properties and CSV file format. Refer to the following sections for details.

For more information on lists managed by Cloudflare, such as Managed IP Lists, refer to Managed Lists.

Create a custom list

Refer to Create a list in the dashboard or to the Lists API page.

Use a custom list

Use custom lists in rule expressions with the in operator and with a field supported by the custom list:

<FIELD> in $<LIST_NAME>

The fields you can use vary according to the list item type:

List item typeAvailable fields
IP addressFields with type IP address listed in Fields
Hostnamehttp.host
ASNip.src.asnum

For more information and examples, refer to Use lists in expressions.


Custom list types

Lists with IP addresses (IP lists)

List items in custom lists with IP addresses must be in one of the following formats:

  • Individual IPv4 addresses
  • IPv4 CIDR ranges with a prefix from /8 to /32
  • IPv6 CIDR ranges with a prefix from /12 to /64

You can combine individual addresses and CIDR ranges in the same list.

You can use uppercase or lowercase characters for IPv6 addresses in lists. However, when you save the list, uppercase characters are converted to lowercase.

CSV file format

When uploading items to a custom list with IP addresses via CSV file, use the following file format (enter one item per line):

<IP_ADDRESS_1>,<DESCRIPTION>
<IP_ADDRESS_2>

The <DESCRIPTION> field is optional.

Lists with hostnames

List items in custom lists with hostnames must be Fully Qualified Domain Names (FQDNs). An item may contain a * prefix/subdomain wildcard, which must be followed by a . (period). An item cannot include a scheme (for example, https://) or a URL path.

For example, the following entries would be valid for a custom list with hostnames:

  • example.com
  • api.example.com
  • *.example.com

However, example.com/path/subfolder would not be a valid entry.

You can add any valid hostname (a valid FQDN) to a custom list with hostnames. The hostnames do not need to belong to the current Cloudflare account.

CSV file format

When uploading items to a custom list with hostnames via CSV file, use the following file format:

<HOSTNAME_1>,<DESCRIPTION>
<HOSTNAME_2>

The <DESCRIPTION> field is optional.

Lists with ASNs

List items in custom lists with autonomous system numbers (ASNs) must be integer values.

For example, the following entries would be valid for a list with ASNs:

  • 1
  • 13335
  • 64512

CSV file format

When uploading items to a custom list with ASNs via CSV file, use the following file format:

<ASN_1>,<DESCRIPTION>
<ASN_2>

The <DESCRIPTION> field is optional.