Configure tunnel endpoints

Cloudflare recommends two tunnels for each ISP and network location router combination, one per Cloudflare endpoint. Cloudflare will assign two Cloudflare endpoint addresses shortly after your onboarding kickoff call that you can use as the tunnel destinations on your network location’s routers/endpoints.

To configure the tunnels between Cloudflare and your locations, you must provide the following data for each tunnel:

• Tunnel name: For GRE tunnels, the name must have 15 or fewer characters. IPsec tunnels have no character limit. For both GRE and IPsec tunnels, the name cannot contain spaces or special characters, and cannot be shared with other tunnels.
• Cloudflare endpoint address: The public IP address of the Cloudflare side of the tunnel.
• Customer endpoint: A public Internet routable IP address outside of the prefixes Cloudflare will advertise on your behalf. These are generally IP addresses provided by your ISP. If you intend to use a physical or virtual connection like Cloudflare Network Interconnect, you do not need to provide endpoints because Cloudflare will provide them.
  This value is not required for IPsec tunnels, unless your router is using an Internet Key Exchange (IKE) ID of type ID_IPV4_ADDR.
• Interface address: A 31-bit (recommended) or 30-bit subnet (/31 or /30 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space:
  • 10.0.0.0/8
  • 172.16.0.0/12
  • 192.168.0.0/16
  • 169.254.240.0/20

    Warning

    Especially for cloud service providers that might automatically generate prefixes for you, make sure the prefixes are always within the allowed Cloudflare ranges, or the tunnel will not work.

• TTL: Time to Live (TTL) in number of hops for the GRE tunnel. The default value is 64.
• MTU: Maximum transmission unit (MTU) in bytes for the GRE tunnel. The default value is 1476.

Ways to onboard traffic to Cloudflare

GRE and IPsec tunnels

You can use GRE or IPsec tunnels to onboard your traffic to Magic Transit, and set them up via the Cloudflare dashboard or the API. However, if you want to use the API, be sure to have your account ID and API key ready before you begin.

Note

IPsec tunnels only support Internet Key Exchange version 2 (IKEv2).

IPsec supported ciphers

Refer to Tunnels and encapsulation to learn more about the technical requirements for GRE and IPsec tunnels used in Magic Transit. In this page, you can also find the supported ciphers for IPsec.

Anti-replay protection

If you use Magic Transit and anycast IPsec tunnels, we recommend disabling anti-replay protection. This setting is disabled on Cloudflare’s side by default. However, it can be enabled via the API or the Cloudflare dashboard for devices that do not support disabling it, including Cisco Meraki, Velocloud, and AWS VPN Gateway.

Refer to Anti-replay protection for more information on this topic, or Add IPsec tunnels below to learn how to enable this feature.

Network Interconnect (CNI)

Beyond GRE and IPsec tunnels, you can also use Network Interconnect (CNI) to onboard your traffic to Magic Transit. Refer to Network Interconnect and Magic Transit for more information.

Add tunnels

Warning

Internet Control Message Protocol (ICMP) traffic is subject to Magic Firewall rules. If you have Magic Firewall enabled, ensure your rules allow ICMP traffic sourced from Cloudflare public IPs. Otherwise, health checks will fail. Refer to Magic Firewall rules for more information.

Dashboard

1. Log in to the Cloudflare dashboard ↗, and select your account.
2. Select Magic Transit > Configuration.
3. From the Tunnels tab, select Create.
4. On the Add tunnels page, choose either a GRE tunnel or IPsec tunnel.

GRE tunnel

5. In Name, give your tunnel a descriptive name. This name must be unique, must not contain spaces or special characters, and must be 15 or fewer characters. Hover the mouse over i in the dashboard for more information.
6. Give your tunnel a description in Description. You do not have character restrictions here.
7. In Interface address, enter the internal IP address for your tunnel along with the interface’s prefix length (either /31 or /30). This is used to route traffic through the tunnel on the Cloudflare side. We recommend using an RFC1918 address scheme with a /31 netmask, as it provides the most efficient use of IP address space.
8. In Customer GRE endpoint, enter your router’s public IP address. This value is not needed if you intend to use a physical or virtual connection like Cloudflare Network Interconnect because Cloudflare will provide it.
9. In Cloudflare GRE endpoint, enter the anycast address you received from your account team.
10. Leave the default values for TTL and MTU.
11. (Optional) Tunnel health checks are enabled by default. If you disable Tunnel health checks, your tunnels will appear 100% down in your tunnel health dashboard even when working. Cloudflare will keep sending traffic through the tunnel, without the means to detect if the tunnel goes down. You will have to set up your own system to detect down tunnels, as Cloudflare will not be able to warn you about down tunnels. Refer to Tunnel health checks for more information.
12. (Optional) If you keep Tunnel health checks enabled, choose the Health check rate for your tunnel. Available options are Low, Medium, and High.
13. The Health check type defaults to Reply and to creating an ICMP reply. If your firewall drops this type of packet for assuming it is a type of attack, change this option to Request which will create an ICMP request. Refer to Tunnel health checks for more information.
14. The Health check direction defaults to unidirectional for Magic Transit. Refer to Bidirectional vs unidirectional health checks for more details.
15. (Optional) Health check target is the customer end of the tunnel. This field is only visible when the Health check direction is set to Unidirectional.
16. (Optional) We recommend you test your tunnel before officially adding it. To test the tunnel, select Test tunnels.
17. To add multiple tunnels, select Add GRE tunnel for each new tunnel.
18. After adding your tunnel information, select Add tunnels to save your changes.

IPsec tunnel

5. In Name, give your tunnel a descriptive name. This name must be unique, must not contain spaces or special characters, and must be 15 or fewer characters. Hover the mouse over i in the dashboard for more information.
6. Give your tunnel a description in Description. You do not have character restrictions here.
7. In Interface address, enter the internal IP address for your tunnel along with the interface’s prefix length (either /31 or /30). This is used to route traffic through the tunnel on the Cloudflare side. We recommend using an RFC1918 address scheme with a /31 netmask, as it provides the most efficient use of IP address space.
8. In Customer endpoint, enter your router’s public IP address. This value is only required if your router is using an IKE ID of type ID_IPV4_ADDR.
9. In Cloudflare endpoint, enter the anycast address you received from your account team.
10. (Optional) Tunnel health checks are enabled by default. If you disable Tunnel health checks,, your tunnels will appear 100% down in your tunnel health dashboard even when working. Cloudflare will keep sending traffic through the tunnel, without the means to detect if the tunnel goes down. You will have to set up your own system to detect down tunnels, as Cloudflare will not be able to warn you about down tunnels. Refer to Tunnel health checks for more information.
11. (Optional) If you keep Tunnel health checks enabled, choose the Health check rate for your tunnel. Available options are Low, Medium and High.
12. (Optional) The Health check type defaults to Reply and to creating an ICMP reply. If your firewall drops this type of packet for assuming it is a type of attack, change this option to Request which will create an ICMP request. Refer to Tunnel health checks for more information.
13. (Optional) The Health check direction defaults to unidirectional for Magic Transit. Refer to Bidirectional vs unidirectional health checks for more details.
14. (Optional) Health check target is the customer end of the tunnel. This field is only visible when the Health check direction is set to Unidirectional.

Note

IPsec tunnels will not function without a pre-shared key (PSK).

14. If you do not have a pre-shared key yet:

    1. Select Add pre-shared key later.
    2. (Optional) We recommend you test your tunnel configuration before officially adding it. To test the tunnel, select Test tunnels.
    3. Select Add tunnels.
    4. The Cloudflare dashboard will load the list of tunnels you have configured. The IPsec tunnel you have just created will be listed with a warning in the form of a triangle to let you know it is not yet functional. Select Edit.
    5. Choose Generate a new pre-shared key > Update and generate a pre-shared key. Save the key to a safe place, and select Done.

15. If you already have a pre-shared key:

    1. Select Use my own pre-shared key.
    2. Paste your key in Your pre-shared key.
    3. (Optional) We recommend you test your tunnel before officially adding it. To test the tunnel, select Test tunnels.
    4. Select Add tunnels.

16. (Optional) Enable Replay protection if you have devices that do not support disabling it. Refer to Anti-replay protection for more information.

API

Note

You will need your account ID and API Key to use the API.

GRE tunnel

Create a POST request using the API to create a GRE tunnel. You will need your API Key.

Example:

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/gre_tunnels \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "gre_tunnels": [
    {
      "name": "<TUNNEL_NAME>",
      "description": "<TUNNEL_DESCRIPTION>",
      "interface_address": "<INTERFACE_ADDRESS>",
      "cloudflare_gre_endpoint": "<CLOUDFLARE_ENDPOINT>",
      "customer_gre_endpoint": "<CUSTOMER_ENDPOINT>"
    }
  ]
}'

IPsec tunnel

1. Create a POST request using the API to create an IPsec tunnel. You will need your API Key.

Note that in example below, replay protection is disabled by default. You can enable it with the flag "replay_protection": true for each IPsec tunnel, if the devices you use do not support disabling this feature. If you have already created IPsec tunnels, update them with a PUT request ↗.
Refer to Anti-replay protection for more information on this topic.

Example:

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "ipsec_tunnels": [
    {
      "name": "<TUNNEL_NAME>",
      "description": "<TUNNEL_DESCRIPTION>",
      "interface_address": "<INTERFACE_ADDRESS>",
      "cloudflare_endpoint": "<CLOUDFLARE_ENDPOINT>",
      "customer_endpoint": "<CUSTOMER_ENDPOINT>",
      "replay_protection": false
    }
  ]
}'

{
  "result": {
    "ipsec_tunnels": [
      {
        "id": "<YOUR_TUNNEL_ID>",
        "interface_address": "<INTERFACE_ADDRESS>",
        "created_on": "2023-04-21T10:42:22.138586Z",
        "modified_on": "2023-04-21T10:42:22.138586Z",
        "name": "<TUNNEL_NAME>",
        "cloudflare_endpoint": "<CLOUDFLARE_ENDPOINT>",
        "customer_endpoint": "<CUSTOMER_ENDPOINT>",
        "remote_identities": {
          "hex_id": "<HEX_ID>",
          "fqdn_id": "<FQDN_ID>.ipsec.cloudflare.com",
          "user_id": "ipsec@<USER_ID>.ipsec.cloudflare.com"
        },
        "description": " test",
        "health_check": {
          "enabled": true,
          "target": "<TARGET>",
          "type": "reply",
          "rate": "mid"
        }
      }
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}

2. Create a POST request to generate a PSK. Use the tunnel id you received from the previous command (exemplified by <YOUR_TUNNEL_ID> above):

curl --request POST \
https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels/{your_tunnel_id}/psk_generate \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"

{
  "result": {
    "ipsec_id": "<IPSEC_ID>",
    "ipsec_tunnel_id": "<IPSEC_TUNNEL>",
    "psk": "<YOUR_PSK_KEY>",
    "psk_metadata": {
      "last_generated_on": "2023-04-21T10:48:15.953887008Z"
    }
  },
  "success": true,
  "errors": [],
  "messages": []
}

3. Use the above psk value to configure the IPsec tunnel on your equipment. You do not need to take further action to use the PSK on Cloudflare’s side, as this value is automatically set.

Configure bidirectional health checks

Bidirectional health checks are available for GRE and IPsec tunnels. For Magic WAN this option defaults to bidirectional, while for Magic Transit it defaults to unidirectional.

You can enable bidirectional health checks via the API with --data '{"health_check": {"direction": "bidirectional"}}'. For example:

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/ipsec_tunnels \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{"health_check": {"direction": "bidirectional"}}'

Bidirectional vs unidirectional health checks

To check for tunnel health, Cloudflare sends a health check probe consisting of ICMP (Internet Control Message Protocol) reply packets to your network. Cloudflare needs to receive these probes to know if your tunnel is healthy.

Cloudflare defaults to bidirectional health checks for Magic WAN, and unidirectional health checks for Magic Transit (direct server return). However, routing unidirectional ICMP reply packets over the Internet to Cloudflare is sometimes subject to drops by intermediate network devices, such as stateful firewalls. Magic Transit customers with egress traffic can modify this setting to bidirectional.

If you are a Magic Transit customer with egress traffic, refer to Magic Transit egress traffic for more information on the technical aspects you need to consider to create a successful connection to Cloudflare.

Legacy health checks system

For customers using the legacy health check system with a public IP range, Cloudflare recommends that:

1. You configure the IP address for your tunnel health check target to be one from within the prefix range 172.64.240.252/30.
2. Apply a policy-based route that matches packets with source IP address equal to the configured tunnel health check target (for example 172.64.240.253/32), and route them over the tunnel back to Cloudflare.

Next steps

Now that you have set up your tunnel endpoints, you need to configure static routes to route your traffic through Cloudflare.