The Umbrella User Guide Developer Hub

Welcome to the Umbrella User Guide developer hub. You'll find comprehensive guides and documentation to help you start working with Umbrella User Guide as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Network Tunnel Configuration

You can establish an IPsec (Internet Protocol Security) IKEv2 (Internet Key Exchange, version 2) tunnel from a network device to Umbrella. IPsec tunnels created for the cloud-delivered firewall (CDFW) automatically forward HTTP/HTTPS traffic on ports 80 and 443 to the Umbrella secure web gateway (SWG). You can use IPsec tunnels to deploy the secure web gateway even if you choose not to use the IP, port, and protocol controls in the cloud-delivered firewall.

RFC 1918

The Cloud-delivered firewall (CDFW) expects a private RFC 1918 address as the source IP for outbound packets. If you use non-RFC 1918 addresses, you can add them under Client Reachable Prefixes when configuring your tunnel. Without this information, Umbrella can't determine the IP address and may drop packets. For information about address allocation and private networks, see RFC 1918.

Table of Contents


  • Umbrella SIG data center (DC) public IP address, to which the tunnel will connect. For the latest Umbrella SIG DC locations and their IPs, see Connect to Cisco Umbrella Through Tunnel.
  • An Umbrella organization ID. For more information, see Find Your Organization ID.
  • A router (ISR-G2, ISR4K or CSR, or Cisco ASA) with a security K9 license to establish an IPsec tunnel. Other devices may work but have not been tested.
  • A valid Cisco Umbrella SIG Essentials subscription or a free SIG trial.
  • Allow ports on any upstream device: UDP ports 500 and 4500.

Note: Organizations have a default limit of 50 network tunnels. To increase this limit, contact support or your account manager.

Establish a Tunnel

With the certificate or passphrase credentials generated in the Umbrella portal, establish an IPsec IKEv2 tunnel to the Umbrella head end of the tunnel—the Umbrella data center IP address. The sample commands use umbrella_dc_ip to represent the public IP address for the Umbrella data center.

Maximum Transmission Unit (MTU) Size

Umbrella does not support the reassembly of fragmented IPsec traffic or IP packets. Thus, when a network device sends fragmented IPsec or IP packets to Umbrella, Umbrella drops the fragmented packets.

IPsec tunnels for Secure Internet Access must have an MTU no larger than 1400 bytes, with an MSS no larger than 1360 bytes. Fragmented packets in underlay or overlay are dropped. Slightly larger MTU and MSS may work depending on your specific IPsec configuration.

Tunnel Size

Umbrella supports the following tunnel size ranges:

  • The maximum concurrent loads is 250 Mbps down and 80 Mbps up, based on 900 byte average packet size.
  • The maximum combined throughput is 50,000 packets per second.
  • Depending on traffic profile, we recommend no more than 1000 to 2500 users per tunnel.

Note: Exceeding these limits will result in degraded performance such as increased latency and packet loss.

Client Reachable Prefixes

The cloud-delivered firewall (CDFW) expects a private RFC 1918 address as the source IP for outbound packets. If you use non-RFC 1918 addresses, you can add them under Client Reachable Prefixes when configuring your tunnel. This overrides the default behavior, which allows all traffic destined for RFC 1918 addresses to return through the tunnel. For information about address allocation and private networks, see RFC 1918.

Client reachable prefixes can be configured in the following ways. Each option overrides the next.

  • Option 1 – Umbrella Dashboard
    This configuration is done through the Umbrella dashboard on a per tunnel basis. You can configure client reachable prefixes when creating a new tunnel or when updating the settings for an existing tunnel. If you update client reachable prefixes through the dashboard for a tunnel, these client reachable prefixes are the ones used. These prefixes are used regardless of setting client reachable prefixes through the backend (Option 2), the traffic selector (Option 3), or default ranges (Option 4).
    Note: The Umbrella dashboard does not display configurations set through the backend or the traffic selector (Option 2 and Option 3). However, default ranges (Option 4) can be removed through the dashboard.
  • Option 2 – Backend
    You cannot add client reachable prefixes across all tunnels through the Umbrella dashboard. Client reachable prefixes across all tunnels can only be added through Umbrella’s ‘backend.” To add client reachable prefixes across all tunnels, contact Support. Client reachable prefixes configured through the backend are not displayed in the dashboard. Any changes made through the dashboard override the backend configuration.
  • Option 3 – Traffic Selector:
    Client reachable prefixes can be set at the device level: for example, ASAs. These prefixes are only enforced if they are not overridden by Option 1 or Option 2.
    When setting up tunnels, the traffic selectors are added as client reachable prefixes. They are not displayed in the Umbrella dashboard unless they are added when a tunnel is created.
  • Option 4 – Not Configured (Default)
    By default, there are four ranges added as client reachable prefixes. The RFC 1918 and RFC 6598 addresses are required for the tunnel to function properly and to ensure packets will not be dropped for these ranges. Do not remove these addresses.
    If the field is left empty, RFC 1918 and RFC 6598 addresses are assumed. If you add routable prefixes, these non-routable prefixes need to be explicitly added. These ranges are displayed in the Umbrella dashboard, but are overridden by any of the options listed here.

Note: After updating Client Reachable Prefixes for an established tunnel, wait at least five minutes, disconnect and shut down the tunnel for at least 10 seconds, and then reconnect the tunnel.

Throughput and Multiple Tunnels

Each tunnel is limited to approximately 250 Mbps. To achieve higher throughput, you can establish multiple tunnels. If you set up multiple tunnels, we recommend that you divide the traffic between the tunnels either through load balancing with ECMP (Equal-cost multi-path routing) or assigning traffic through policy-based routing. For information about ECMP, see RFC 2991.

Network Tunnel Identities

A unique set of Network Tunnel credentials must be used for each IPsec tunnel. Two IPsec tunnels cannot connect to the same datacenter with the same credentials. Using unique credentials for every tunnel prevents inadvertent outages should one tunnel get rerouted to a nearby datacenter through anycast failover.

Network Tunnel and Secure Web Gateway

For web traffic sent through the Network Tunnel to the secure web gateway (SWG), we do not require that you exclude certain destinations.

If you choose to exclude traffic through the Network Tunnel, follow these general guidelines:

  • You can not exclude a destination for the IPsec tunnel in the Umbrella dashboard. Instead, exclude a destination on the network device which establishes the IPsec tunnel to Umbrella.
  • You must not exclude traffic to ( in the Network Tunnel. You must route SAML traffic through the same path as the secure web gateway traffic.

Traffic sent through the IPsec tunnel to the secure web gateway functions in two modes: Transparent and Explicit.

Transparent Mode

The secure web gateway (SWG) transparent mode is the default mode. Umbrella transparently filters web traffic that crosses the IPsec tunnel.

Explicit Mode

  • In explicit mode, Umbrella does not require configuration changes to send traffic through the IPsec tunnel to the secure web gateway.
  • If you use a PAC file, you must host a copy of the PAC file downloaded from Umbrella on an internal web server. You cannot use the secure web gateway in explicit mode with Umbrella's hosted PAC file.
  • If you exclude the secure web gateway ingress destination ranges ( and from the IPsec tunnel, you can choose not to send web traffic through the IPsec tunnel. As a result, traffic sent to the secure web gateway is not affected by the bandwidth of the IPsec tunnel.

Configure the IPsec tunnel to exclude SWG traffic

  • On the network device, exclude the IP address ranges ( and to the IPsec tunnel.
  • You must control web traffic with a PAC file, proxy chaining, or AnyConnect secure web gateway (SWG) security module.
  • If you configure web traffic with a PAC file, you must not bypass in the PAC file. Traffic configured with a PAC file must follow the same route as the secure web gateway traffic.
  • Umbrella only supports proxy chain traffic for Network deployments. You should not send proxy chain traffic through IPsec tunnels as features such as the X-Forwarded-For (XFF) header are not supported.

Note: Umbrella sends SAML authentication requests to the domain through the secure web gateway using a PAC file or an on-premise proxy chaining configuration. For more information, see Manage Umbrella's PAC File and Manage Proxy Chaining.

Configuration Guides

We provide configuration guides for various network devices. For devices in which the setup is not documented, we cannot guarantee that the device can establish an IPsec tunnel to Umbrella.

Supported IPSec Parameters < Network Tunnel Configuration > Configure Tunnels Manually with Viptela vEdge

Updated 4 months ago

Network Tunnel Configuration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.