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    

Create and Apply Policies

Congratulations! You're now protected!

If you followed the instructions in the previous steps to protect your network and point your DNS to Umbrella, then your network or roaming computer should now be protected. That was pretty simple, right?

This section is a general overview of the policy wizard. We'll try to break down each policy component into a step by step process, which is how the policy wizard is laid out.

Policies control the level of protection and logging, including which types of sites should be blocked and whether you want to have additional levels of security like the Umbrella intelligent proxy enabled. The policy editor is designed to be a step-by-step process helping you to answer the question "What do you want this policy to do?"

This section of documentation goes into several settings and sub-settings in the policy wizard.

Table of Contents

Getting Started with Policies

  1. Navigate to Policies > Policy List and click the + (Add) icon.
  2. Select the identities that you want protected by this policy and then click Next.
    Note that some identities, such as AD Users can be made more granular by clicking through the name and selecting individual identities.
  1. The next step in the policy is simply answering the question "What should this policy do?"

There are several choices and depending on which ones you select, you'll take a different path to setting up the features and services of Umbrella that will give you the most benefit.

Once you're done configuring settings, the review screen lets you review what changes have been made and make adjustments before saving.


Policies apply to Identities on a first match basis and are not additive. The matching policy closest to the top of the order will apply. Policies are drag and drop to order! We also have a guide that outlines best practices around this. See Best Practices for Defining Policies.

By default, there's always a single policy—the default policy. This policy applies to all identities when no other policy above it covers that identity. In other words, the Umbrella default policy is a catch-all to ensure all identities within your organization receive a baseline level of protection.

Step 1: Create a Policy

  1. To start, navigate to Policies > Policy List. You'll see the Default policy. You can select this policy or click the + (Add icon) to create a new policy. The first thing you'll be asked is what you would like to protect.

  2. Select any or all of the identities that you've set up. If you chose Default Policy, all identities will be selected and you'll be brought to the Summary screen right away. This is because the default policy is already configured and being applied to any identities that have been created.

Step 2: Select Identities

The next step in editing a policy is to select the identities to which the policy will be applied. This will determine to whom these settings apply. This can be any combination of identities available in your dashboard, even if there's just one or two right now. Categories (such as AD Computers or Roaming Computers) can be clicked through to more selectively choose identities. If you only have a single identity—the Network—select that identity.

If you have already created tags, you can also select these. Tags are groupings of roaming computer identities. To set these up, see the next section of documentation for policy best practice.

NOTE: If you are editing the Default policy from the Summary screen, the ability to edit identities is restricted because the Default policy applies to all identities.

Select the identities you wish to apply this policy to and click Next.

Step 3: Pick what you want this policy to do

Next, you'll be asked what you want this policy to do. The options are below. If an option listed isn't available for you, contact your account representative for more information.

The four options shown correspond to policy features: security settings, IP layer enforcement, content category blocks and custom destination lists.

  • Enforce Security at the DNS Layer—These are settings related directly to the blocking of domains based on whether they are malicious and provides a base level of security protection. We recommend always selecting this.
  • Inspect Files—Selectively inspect files in the cloud, not on premise, so there is no need for additional hardware. The inspection is done with Cisco AMP and an antivirus. For more information, see "Enable File Inspection".
  • Limit Content Access—These settings filter types of content based on your organization's acceptable use policies. Typically, this is recommended.
  • Apply Destination Lists—If you have particular domains you'd like to allow or block, add them to a destination list. There are two by default, block or allow, and you can create more to organize groups of domains. The two defaults are the Global lists, meaning they apply to any policy. It's up to you whether you have anything in particular you'd like to block right away.

NOTE: A Global Destination List, whether Block or Allow, applies to all policies and all identities, or in other words, it is 'global' across your organization's configuration. To define a more specific list, please create a new list and add domains only to that, then apply that list to individual sets of identities.

Underneath the options for what the policy should do, you'll find Advanced Settings.

These include the intelligent proxy, SSL decryption, the "Allow-Only mode" (previously known as 'white list mode') and logging options.

The intelligent proxy is included for people with Insights and Platform, or for customers of MSPs.

Our intelligent proxy uses leading research and intelligence to evaluate web and file reputation, providing effective protection without delay. The Umbrella proxy uses Cisco Talos web reputation and other third-party feeds to determine if a URL is malicious. You can also create a list of custom URLs to be blocked based on your policies.

Our proxy also inspects files attempted to be downloaded from those risky sites using anti-virus (AV) engines and Cisco Advanced Malware Protection (AMP), providing comprehensive protection against malicious files, whether users are on or off corporate network. The AV engines have information on over a hundred file types, and through AMP, you gain visibility and threat intel from tens of thousands of deployed firewalls, routers, endpoints, email and web gateways running AMP everywhere.

It's important to note that if you choose to not have the intelligent proxy enabled, options like File Inspection are not available because they're not possible without the intelligent proxy. We encourage anyone who's not using the intelligent proxy as a part of their policies to try it out.
For more information about the intelligent proxy, and exactly how it works, including key information about enabling HTTPS inspection, see Enable the Intelligent Proxy.

The "Allow-Only" mode should be used only in cases where you wish to allow access to a small subset of domains and block all other domains. Since the result of enabling this feature is to effectively block access to the internet except for that part you've defined to allow, please use caution if enabling this feature.

Logging settings are:

  • "Log All Requests" for full logging, whether for content, security or otherwise
  • "Log Only Security Events" for security logging only, which gives your users more privacy (this is a good setting for people with the roaming client installed on personal devices)
  • "Don't Log Any Requests" to disable all logging. If you select this option, most reporting for identities with this policy will not be helpful as nothing is logged to report on.

Once you've picked what the policy should do, click Next. For the purposes of this document, we'll pick all of the options available under "What should this policy do?"

Depending on what you pick, once you click Next you'll see a progress meter with the number of steps remaining until you've fully configured the policy. You can use these to jump around if you need to make changes.

Step 4. Setting your Security and Content Details

Step 4a. Configure Security Settings

These settings determine which categories of security threat Umbrella blocks. For more information on what each category represents, see Understanding Security Categories.

When you first access Security Settings, default settings are applied. The blue shield icon indicates a selected and enabled enabled category. You can leave this setting as is, select a different setting or edit settings and create a new one if needed.

  1. To edit settings, click Edit, select or clear categories, and then click Save.

As an alternative to clicking Edit, you can select preconfigured groupings of security settings or create a new setting that you can reuse.

  1. From the Security Settings drop-down list, choose a security setting or click Add New Setting.
    If you choose Add New Setting, a window appears allowing you to add a new setting.
  1. Give your new setting a meaningful name, select how it is created and then click Create.
  2. If you select Create from Scratch, select security settings and click Save.
    Your security setting is added to the drop-down list.

If you have any custom integrations, they are listed at the bottom of the page under Integrations. Only custom integrations enabled and configured under your account appear.

  1. To enable or disable integrations settings, click Edit.
  1. Select integrations as necessary and click Save.
  2. Once you've configured security settings, click Next.

Step 4a. Configure Content Settings

These settings allow the selection of content categories to be blocked for the identities selected in Step 1 of the Policy wizard. There are High, Moderate and Low settings with the ability to create a Custom grouping of category types or select an existing Custom list.

To create a custom setting:

  1. Select the Custom Settings drop-down, click Create New Setting and define it right there in the wizard.

A list of all categories and details for each is here.

As with security settings, you can add a new content setting and modify an existing one directly from within the wizard.

Step 4c. Configure SafeSearch

SafeSearch is a feature of the major search engines that restricts and filters explicit images and results. Umbrella provides the ability to enforce traffic to Google, YouTube and Bing on a per-policy basis.

What’s SafeSearch and how does this feature work?

SafeSearch is an automated filter of pornography and other offensive content that’s built right into search engines. If anyone enters an inappropriate or suggestive phrase, no results will be returned that could be considered unsafe or problematic.

In the past, enforcing SafeSearch for internet search engines required that traffic to those domains be proxied, and URL parameters sent to them would then be modified to enforce the filtering level. The major search engines have recently begun providing DNS based methods for enforcing SafeSearch. This is done by by allowing the use of CNAMEs for their primary domains pointing to dedicated SafeSearch domains instead.

This method of enforcing SafeSearch is supported for Google, YouTube, and Bing.

How to use the SafeSearch feature in Umbrella

Turning this feature on is simple—it’s just a checkbox in the bottom of your Content Settings, under Advanced Settings. You can modify this for any existing policy by going to Policies > Policy List and clicking on a policy. From the Summary screen, click Edit under ‘Content Setting Applied.’

Under the list of categories, expand Advanced Settings and click the checkbox to enforce SafeSearch.

How to verify SafeSearch was enforced for a given query

Verification for the SafeSearch feature works slightly differently than other category blocks. The simplest and most reliable way to ensure it is working is to either visit the site that SafeSearch is enforced for and checking the SafeSearch settings are enabled. Alternatively, you can run a lookup from the command line to see if the redirection is working.

Both tests must be done on a computer whose policy has SafeSearch enabled. The two methods are outlined below.

Testing via Settings for Google, Youtube and Bing:


After searching in Google, you should see this in the top right corner:

Under Settings, you can select “Turn off SafeSearch”, but it will not have any effect:


Searching YouTube should show that “Restricted Mode” is on at the bottom of the results page. Expanding that will show that “Restricted Mode is enabled by your network administrator.

Microsoft Bing

Under the menu icon in the top right corner, Bing will show that SafeSearch is set to “Strict”:

Clicking SafeSearch takes you to page describing SafeSearch, but the page will not give you an option to disable it:

Testing via a lookup from command line:

Looking up each domain via an nslookup should return results as below:


Non-authoritative answer:

Non-authoritative answer:
Addresses:  2001:4860:4802:32::78


Non-authoritative answer:

(Note the last alias for may change based on geo-location. The important part is that it says "strict" in the domain.)

How the service works for reports and blocks

Typically, when a site is blocked for inappropriate content, Umbrella’s DNS service returns the address of the block page to a user instead of the address of the website. The SafeSearch functionality is enforced by using a CNAME to point to the SafeSearch domain, so there’s no actual blocking taking place. Instead, requests are effectively redirected to domains which will restrict the results returned by the search engine. The only request is to the search engine’s site and not to a restricted site and it is not possible to determine the intent to bypass SafeSearch. It’s also not possible to see the redirect in our reporting.

Step 4d. Configure Destination Lists

Destination lists allow the customization of filtering by creating a list of domains that are explicitly blocked or allowed. Note that each destination list can be set to be a block list (default) or an allow list.

Allow list entries will always take precedence over block list entries. Allow lists will also take precedence over security related blocks, so if you feel a domain is being blocked incorrectly, adding it to an allow list will let you access it while you investigate or report it to Umbrella support.

  • Blocking and adding to the Allow List will still allow

  • Adding to the Allow List and blocking will still allow

If you add to a block list, and add to an Allow list, assuming both lists are applied on the same policy, we will still allow

We recommend adding domains in the format "" rather than to ensure * is included (a wildcard is implicit). However, if you only wish to block, then be more specific when you define the entry here.

Creating a destination list is simple: first, pick the type of list you want, then add the domains you would like to have allowed or blocked and give the list a name.

Note: Destination lists are not saved until you click Save, although it appears in the list view after entering it.

Note:* All of these Policy Settings can also be edited from the left-hand menu, under Policy Settings.

Limited Availability – an IP Address or CIDR of IP Addresses (Roaming Client Only)

This feature is in Limited Availability and not available to all customers. It requires the Roaming Client be installed on the identities for this feature in the policy. If you are running IP Layer Enforcement and would like to try this feature out, please contact to see if you are eligible.

For Destination Allow Lists only (for now), you can add an IP address or a block of IP addresses. The format for the block of IP addresses is standard CIDR notation.

The size of the CIDR cannot exceed a /8, otherwise, you'll receive this error:

If you enter an invalid subnet mask, such as, the IP will be added but the network notation will be ignored.

Otherwise, add any destination that you'd like to ensure isn't blocked now or in the future.

Step 4e. Configure Block Pages

Block Page Settings let you configure a block page that appears when a request is made to access a blocked page. You can also create a bypass so that access can be granted to the block page. You can customize the block page's appearance and redirect to a custom domain.

  • Block Page Settings—This setting let you customize the block page appearance, redirect to a custom domain, and more.
  • Bypass Users—Users who can log in to bypass block pages on this policy. A Bypass User must be checked on a policy in order for it to be active.
  • Bypass Codes—Codes who can log in to bypass block pages on this policy. A Bypass Code must be checked (as above) on a policy in order for it to be active.


Not all categories can be bypassed. If a user is blocked for a Security or Malware category, the site is considered malicious and should not be accessed under any circumstances. If you think a domain shouldn't be blocked, please email us at

If you'd like to know more about a block or have us review it in more detail, open a case by emailing with information about the domain and our support and security teams will review it.

Block Page Settings

If you do not wish to change anything, just use the Umbrella Default Appearance, but this setting also allows for the customization of the block page.

You can edit an existing block page by hovering over the name and clicking the Edit pen icon.

Select Use a Custom Appearance, then choose Create new Appearance from the drop-down list.

When you create or edit a page, give your settings an easy to remember name, such as "Corporate Block Policy."

Choose a generic message across all block pages, or customize the message per type of block page by selecting whether Blocked requests should be treated the same or differently. If you set a custom message, you may insert the [domain] variable into a custom message, which is substituted with the actual domain name that the end user attempted to browse to. You may also insert the [client_ip] variable, which shows the external IP address of the client that is hitting the block page.

If you set a custom message, you may insert the [domain] variable into a custom message, which is substituted with the actual domain name that the end user attempted to browse to

The block can also redirect to a custom URL.

If not redirecting to a custom URL, a contact form can be added to allow blocked users to contact the administrator at the email provided.

Finally, a custom logo can be uploaded to be displayed on the block page in place of the Umbrella logo.

Bypass Users

A bypass user can log in (when added to the policy) to bypass the selected type of block pages. The option to bypass the block page is encountered when the block page is presented and the user can then authenticate in order to bypass it. For people without these credentials, the block remains in place.

Note: Not all categories can be bypassed. If a user is blocked for a Security or Malware category, the site is considered malicious and should not be accessed under any circumstances.

  1. To add a user, navigate to Settings > Accounts.
    Note: The user must already exist in Umbrella to be added as a Bypass User.

  2. Once you have users, under Bypass Users, select a user or click Create New.

If you wish, the bypass user can be applied to specific category filters or destination lists. Note that it is not possible for a bypass user to bypass a security block.

Again, it's essential that this bypass user be applied to the policy that matches the identity that will hit the block page.

Bypass Codes
Bypass codes can be created to allow blocked users to bypass the block page. The bypass code is available for a specified period of time.

When enabled (with the check mark) on the policy, the selected categories and/or domains can be bypassed. Ensure to set an expiration for the code or the default is that it will expire within an hour.

Again, it's essential that this code be applied to the policy that matches the identity that will hit the block page.

Once you've set your block page and bypass settings, click Next.

Step 5: Set Policy Details

Lastly, you'll reach the Policy Summary. It covers all of the modifications to the policy you just made. If you want to change anything, click the relevant Edit button and you'll jump right back to that step, or disable the feature directly from the Summary screen. When you've made the change, you can jump back to the summary directly without having to click through all the other steps (neat, right?).

You should give the policy a name before saving it. You can also modify any advanced settings directly from this screen. Once you've got everything the way you want it, just click Save.

And that's it—you've got your first policy all set up. As you set up additional identities and configurations for Umbrella, you may need to tweak your policy. When you open an existing policy, it will go directly to the Summary screen, and you can jump between steps in order to make the change you need to make immediately without having to do redo the entire wizard.

Point Your DNS to Cisco Umbrella > Create and Apply Policies > Best Practices for Defining Policies

Create and Apply Policies