Umbrella Network Devices Integration Guide, DNS

Network Devices With Umbrella (DNS)

Umbrella can manage network devices that support Extension Mechanisms for DNS (EDNS) packet forwarding. This guide provides best practices for integrating network devices with Umbrella, registering internal domains, and identifying DNS traffic using the EDNS0 packet format. For more information about network devices that integrate with Umbrella, see Network Device Guides.

Best Practices

When you create an Extension Mechanisms for DNS (EDNS) packet, set the destination to or You can not send an EDNS packet to another DNS server for forwarding. DNS servers remove incoming EDNS data before forwarding queries.

Note: Since the forwarded query uses plain DNS, you can not apply a policy.

For conditional forwarding, consider internal domain resolution. There are two integration methods:

conditional forwarding diagram

DNS Stub Resolver Mode

In the DNS Stub Resolver mode, the network device creating EDNS packets appears as a DNS resolver to all clients on the network. Clients on the network use the network device’s IP address as their DNS server (set through DHCP or statically) and generate queries to the network device. Upon receiving the request, the network device does the following:

  • Determines if domains are local and forwards them to the local DNS server (Active Directory or BIND) for resolution; or
  • Adds EDNS and forwards them to
Note: Do not send internal domains to Umbrella.

Our resolvers return either an NXDOMAIN response (in the case of domains like mycorp.local), or the public IP (in the case of split-horizon DNS).

Advantages: You can use dnsmasq (DNS masquerade) or a similar software to handle most requests.

Disadvantages: When queries forward to the internal DNS server, endpoint IP addresses are obscured. This is problematic in enterprise scenarios that have complex internal DNS requirements. For example, if you are using Infoblox, the DNS logs in Infoblox show all internal DNS queries coming from the network device instead of the originating devices.

stub resolver mode diagram

Transparent DNS Hijacking (Preferred)

With Transparent DNS Hijacking, the network device creating EDNS packets appears on the network as a gateway or router, not a DNS server. The endpoints continue to point their DNS to the local DNS server, but the network device is in the data path between the endpoints and the local DNS server. The network device intercepts DNS packets (at layer 3 by looking for UDP/53, or with DPI) and determines to direct those queries to Umbrella, or let them continue to the internal DNS server. If the destination matches the internal domains list, the packet remains untouched and continues through to the internal DNS server. Otherwise, the network device adds EDNS to the packet and the destination changes to or (IPv6 is supported as well).

Advantages: When you send external queries to Umbrella and internal queries to the internal DNS server, the network device preserves the endpoint private IP address information. You do not have to change the DNS server setting on your endpoints.

Disadvantages: The network device must be in the data path between the endpoint and the internal DNS server. The implementation may be more complex.

dns hijacking diagram

Specify Internal Domains

  • Assumed Domains

    You can assume some internal domains, but these domains are not guaranteed, for example:

    • .local
    • .internal
    • .localhost
    • reverse RFC-1918 (*, *
  • Programmatically

    Programmatically discover some internal domains from the domain search DHCP options (DHCP Option 015 and 119).

  • User Specified

    Provide a mechanism to the user to specify the internal domains for their network. This mechanism should support left-hand wildcards such as *

  • Umbrella Dashboard

    Register internal domains with Umbrella. An integrated network device can use the Umbrella v1 Internal Domains API to manage the internal domains added to Umbrella.

Set Up Network Devices

  1. Set up your device or console to interact with the Umbrella Network Devices and Policies API. Each device or segment requires a device ID that is unique within Umbrella.
  2. Create an Umbrella Network Devices API key and secret in the Umbrella dashboard. For more information, see Network Devices API Authentication. Add the key and secret pair into the device or management console. The network device registers with Umbrella using these credentials.
  3. Register a network device with Umbrella. For more information, see Register a network device. After you register a network device, Umbrella provides a unique device ID.
  4. Add EDNS information to a request before forwarding to the Umbrella DNS resolvers. With EDNS, a registered network device sends the internal IP to Umbrella instead of the public IP address.
    Note: We recommend that you use the internal IP address for reporting.

Benefits of Device Integration

To get started with Umbrella, configure your DNS server to point at the Umbrella resolvers, and register your public IP address in Umbrella. You can also integrate with Umbrella by registering a network device. A network device provides the following benefits:

  • Dynamic IP address

    If you have a dynamic public IP, as assigned by your ISP, then you must keep this IP address updated in Umbrella. The Umbrella Dynamic Network Update API provides an endpoint to manage dynamic public IP addresses. For more information, see Umbrella Dynamic Network Update API. When you integrate a network device with Umbrella, the device embeds the customer information in the EDNS packet, allowing our resolvers to apply the proper policy.

  • Internal IP reporting

    Without sending EDNS packets (like the Roaming Client and Virtual Appliance), every query in the dashboard reports only the public IP address. Compared to the public IP address, the EDNS packet information can help identify the source of any malicious traffic. The registered network device implements EDNS to send the internal IP to Umbrella.

  • Multiple policies

    Without a network device identifier for a Roaming Client or Virtual Appliance, you can only apply a single policy per public IP address. Network device integrations allow for more granular policy creation, for example: policy per SSID, policy per VLAN, or policy per interface. Meraki uses SSID and Viptela uses VPN.

  • Encryption

    We recommend that you encrypt DNS traffic, but do not require a certain encryption method or protocol. Umbrella accepts EDNS options across DNSCrypt, DNS over HTTPS (DoH), and DNS over TLS (DoT). For more information, see Enhancing Support of DNS Encryption with DNS over HTTPS.

    DNSCrypt is complementary to DNSSEC, but not a replacement. Many devices and DNS software suites support DNSCrypt. All Umbrella subscriptions support DNSCrypt, even the no-cost Umbrella service. For more information, see DNSCrypt FAQ.

Note: The Umbrella DNS resolvers only support v1 of DNSCrypt.

Identify DNS Traffic

In Umbrella, you can associate DNS traffic with a device ID or an internal IP address.

Note: You can apply a policy to the device ID. Use the local IP address for visibility and reporting only.

After you register a network device with Umbrella, add your device ID or an internal IP address to the DNS packet to create an EDNS0 packet. The EDNS0 packet format is specified by RFC6891. Umbrella defines a custom EDNS0 data option code.

OPT RR Description

Umbrella EDNS0 data option code.

Field Type Description
Name Domain Name Empty (root domain, 0)
Type u_int16 OPT (41)
Class u_int16 Sender’s UDP payload size (default 512; Umbrella supports up to 4096)
TTL u_int32 Extended RCODE and flags (default 0)
RDLEN u_int16 Combined size in bytes of RDATA options
RDATA octet stream One or two RDATA options, formatted in {attribute,value} pairs

RDATA Description

Field Type Description
OPTION-CODE u_int16 0x4F44 (hex) or 20292 (decimal)
OPTION-LENGTH u_int16 Size in octets of OPTION-DATA
OPTION-DATA octet stream See the Option-Data header and body format


Initial header (6B) is composed of a 4B "magic value", a 1B VERSION field, and a 1B FLAGS field.

|                             MAGIC                         |
|            VERSION            |           FLAGS           |
  • The MAGIC value distinguishes an EDNS0 message from a message with the same OPTION-CODE from another source. The value of this field must be 0x4F444E53 ("ODNS").
  • The VERSION must be 0x01.
  • The FLAGS must be 0x00.

After the header, each additional field starts with a 2B field type (bit values) followed by a fixed-length value.

Type Length Contents Comments/Restrictions
0x00 0x08 4 Organization ID Required
0x00 0x10 4 Remote IPv4 The "internal" site address that is invisible to the DNS resolver
0x00 0x20 16 Remote IPv6 The "internal" site address that is usually invisible to the DNS resolver
0x00 0x40 8 Device ID Device ID provided by Registering a device with Umbrella

Note: Provide organization ID and IP addresses in network-endian byte order.


If the organization ID is 012345678, remote IPv4 is, remote IPv6 is not sent, and the device ID is 0123456789abcdef, then the OPTION-DATA consists of the following array of bytes:

0x4F, 0x44, 0x4E, 0x53 0x01 0x00 0x00, 0x08 0x00, 0xBC, 0x61, 0x4E 0x00, 0x10 0xC0, 0xA8, 0x01, 0x37 0x00, 0x40 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF
Magic (ODNS) Version Flags Type Organization ID (012345678) Type Remote IPV4 ( Type Device ID (0123456789abcdef)

With the same OPTION-DATA containing the IPv6 address FE80::0202:B3FF:FE1E:8329, the IPv4 address consists of the following array of bytes:

0x4F, 0x44, 0x4E, 0x53 0x01 0x00 0x00, 0x08 0x00, 0xBC, 0x61, 0x4E 0x00, 0x20 0xFE, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0x02, 0xB3, 0xFF, 0xFE, 0x1E, 0x83, 0x29 0x00, 0x40 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF
Magic (ODNS) Version Flags Type Organization ID (012345678) Type Remote IPV6 (FE80::0202:B3FF:FE1E:8329) Type Device ID (0123456789abcdef)

Network Device Guides

For more information about Meraki and Umbrella, see Integrating Meraki with Umbrella Networks.