The Umbrella Deployment Documentation Developer Hub

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

Get Started    

Appendix D – Internal Domains

Umbrella's Internal Domains feature allows DNS queries for certain domains to query the local network's DNS servers instead of Cisco Umbrella when using the Umbrella roaming client.

Without specifying internal domains, all DNS queries are sent directly to Umbrella, and as a result, can't reach your network's local resources (for example, computers, servers, printers) on internally-hosted domains that rely on local DNS servers.

To ensure uninterrupted access to these resources, administrators should add the appropriate domains to the Internal Domains section of the dashboard (Deployments > Configuration > Internal Domains). This creates an internal domain allow list that will be synced to your roaming users. Essentially, the Internal Domain list allows all added domains to resolve DNS records as if the Umbrella roaming client was not installed on the computer.

The Umbrella roaming client determines which domains it should treat as internal domains based on the following two sources: the Umbrella dashboard and DNS suffixes.

The Umbrella Dashboard –Domain Management

The Domain Management area of the Umbrella dashboard (Deployments > Configuration > Domain Management) should be populated with any domains used by your organization to access local resources while on the organization's network (at the physical location or connected via VPN). Internal Domains is pre-populated with the .local TLD and all RFC-1918 (private network) reverse DNS address space. Newly added domains will sync down to Umbrella roaming clients within about one hour.

This internal domain applies to—Allows you to specify whether the internal domains should apply to Umbrella roaming clients, Virtual Appliances (VAs), or both.

DNS Suffixes

The domains contained in the DNS suffixes configuration on a computer's adapter and global network settings are imported automatically into an individual Umbrella roaming client's Internal Domain list each time the Umbrella roaming client starts or a new network adapter (such as a VPN or Wireless connection) is initiated. This is to help Umbrella roaming clients adapt in foreign networks where they may want to access local resources without adding the domain through the dashboard.

Operational Flowchart

The following flowchart explains how the roaming client gracefully handles internal and external DNS queries:

1. Internal Domains

The Umbrella roaming client's Internal Domains list is populated by two sources:

  • Syncing the Internal Domains list located in the Umbrella dashboard
  • The DNS Suffixes list located in the local computer's networking configuration settings.

2. External Queries

External DNS queries which do not match a domain located on either of the Internal Domains lists are sent straight to Umbrella.

3. Internal Queries

DNS queries for domains contained in the Internal Domain list are sent through the local network's DNS servers.

Internal Domains which are hosted on the local network are resolved by the Internal DNS server directly (as seen with "bob-pc.zombo.com").

Internal Domains which are not hosted on the local network are resolved by Umbrella or whichever public DNS servers are used for resolution (as seen with notzombo.com).

Advanced Topics

The following section focuses on more in-depth information and logic with internal domains and expected behavior.

Unencrypted

Although the Umbrella roaming client is able to send encrypted DNS queries to Umbrella when in the encrypted state, domains listed on the Internal Domains list are sent unencrypted, because they are not sent to Umbrella.

Virtual Appliances

If virtual appliances (VAs) are deployed at one or multiple locations within your organization, the Umbrella roaming client will disable itself and DNS settings will revert to the VA while connected to the location physically or via VPN. For more information about the Umbrella roaming client's behavior with VAs, see AVirtual Appliances and the Umbrella Roaming Client.

If all of your organization's locations are using VAs, configuring the Internal Domains list for Appliances only (not Appliances and Devices) will suffice; any time the Umbrella roaming client is not connected to the network in question, it won't use Internal Domains set to "Appliances Only", and treat any DNS queries to your domain as a public query (encrypted).

DHCP/Static DNS Servers

When the computer starts or a new network connection activates, the Umbrella roaming client sets the DNS server to 127.0.0.1 and/or ::1 on each network adapter.

Upon replacing the existing DNS server configuration on the network adapters, the existing DNS addresses for each adapter are saved to the following local files on the system:

Mac OS X

/var/lib/data/opendns/resolv_orig.conf

Windows

C:\ProgramData\OpenDNS\ERC\Resolver#-GUID-of-NetworkAdaptor.conf

These addresses are where any domains in the Internal Domains allow list will be sent, emulating an environment where the Umbrella roaming client is not present.

Since the Umbrella roaming client does not cache DNS in any way, any local DNS changes made on your local DNS servers will take effect immediately and the behavior is not changed by the presence of the Umbrella roaming client.

The Umbrella roaming client reinstates the DHCP or statically configured DNS servers under the following conditions:

DNS Suffixes (Continued)

There are implications that should be considered with DNS Suffixes.

  • This could allow an organization to not add any domains to the Internal Domains list in the dashboard. If DHCP is configured to use your domains as DNS Suffixes, the Umbrella roaming client will automatically know to treat the domain as local, even without adding it to the dashboard.
  • If using DNS suffixes to rely on Internal Domains resolution instead of populating the list in the dashboard, as mentioned above, it means increased security. Since DNS queries sent to domains on the Internal Domains list are sent unencrypted, this implies that a machine performing DNS queries for domains that have been added in the dashboard are always sent unencrypted on all networks.

The behavior of adding the domains contained in the DNS suffixes list can be disabled during installation using a special command-line parameter.


Appendix C – Troubleshooting < Appendix D – Internal Domains > Appendix E – Roaming Computer Settings

Appendix D – Internal Domains


Suggested Edits are limited on API Reference Pages

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