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    

Appendix C – Troubleshooting

Table of Contents

The purpose of this appendix is to help provide context and actionable steps for resolving commonly experienced issues with the Cisco Umbrella roaming client before reaching out to Support or having to search the Knowledge Base. Most of the commands below require administrative access to the computer for troubleshooting. We recommend that you log in to an administrator account to perform these tasks.

Scenarios

Did the Umbrella Roaming Client not install?

There are several reasons why the Umbrella roaming client won't install correctly.

Scenario 1: You installed the Umbrella roaming client using a distributed/mass deployment method, such as GPO, Apple Remote Desktop, using a standardized image, etc.

In this case, try installing the Umbrella roaming client on a machine locally through the manual installation method. If the Umbrella roaming client installs correctly, double-check our mass deployment articles (Using Standardized Images and Using Apple Remote Desktop in OS X) and make sure each step was followed precisely. If the Umbrella roaming client did not install, proceed to Scenario 2.

Scenario 2: You installed the Umbrella roaming client using the manual installation method, performing a single installation.

Confirm that all prerequisites are met. If you meet the minimum requirements listed and the Umbrella roaming client does not install correctly, open a ticket with Support.

Unable to Resolve Internal Resources

If you cannot resolve internal resources (domains), ensure you've added all domains which host local resources to the Internal Domains list.

If the domain in question has been added to the Internal Domains list, check to make sure all of your DHCP-delegated DNS servers are returning the private IP by running the following commands (in Terminal or Command Prompt) and compare the results. These commands should be run from a machine experiencing the issue with the Umbrella roaming client install. Be sure to substitute the internal domain name and local DNS server as applicable:

nslookup resource.internal-domain.com 127.0.0.1
Or
nslookup resource.internal-domain.com ::1
nslookup resource.internal-domain.com $LOCAL_DNS_SERVER_1
nslookup resource.internal-domain.com $LOCAL_DNS_SERVER_2

If one of the local DNS servers is returning a public IP address, you'll need to rectify that, as the Umbrella roaming client might be passing the Internal Domain DNS lookup to that server and using the response as the result.

If the Umbrella roaming client (127.0.0.1 and/or ::1) is returning a public IP and querying the local DNS servers is returning a private IP, contact support.

Installations Failures

A failed installation refers to the Umbrella roaming client installer exiting suddenly with or without an error code or crashing during installation. If the Umbrella roaming client installs successfully but fails to register or become "Protected", that's a separate issue and this section should be skipped.

The Umbrella roaming client installer rarely fails, but if it does there are a few common causes. We encourage you to perform these checks before taking any additional action:

  • If attempting to install by way of the command line or a deployment system, try installing with the single machine or manual install method. If a single installation is successful, but installing through the command line or deployment system is not, verify your command line parameters and review distrubuted installation methods.
    Typically, parameters such as the "OrgInfo" information were not passed correctly, or the installation method was missing source files.
  • If you are running antivirus software or other security-based software products, check the security logs to make sure the installation was not blocked by the security software in question.
For Windows Only

The only software required by the Umbrella roaming client for Windows operating systems is .NET Framework 3.5 (4.5 for Windows 8/8.1), making the absence of .NET Framework the most likely cause. As such, confirm the appropriate version of .NET Framework is installed.

If the installer is crashing or completes without installing the Umbrella roaming client and without displaying any error, perform the following steps to generate an installer error:

  1. Open the Command Prompt as an Administrator.
  2. Change directory to the folder which has the Setup.msi and OrgInfo.json files (typically the extraction folder from the download).
  3. Run the command: > msiexec /i Setup.msi /L*v install.log
  4. Once the installation finishes, open a support ticket and attach the install.log, which will be in the same folder as Setup.msi.

For TLS 1.2 support, you will need .Net Framework 4.6.2 or later, or a package for .Net 3.5 SP1, see Microsoft KB3154518.

Unregistered Umbrella Roaming Clients

After installation, the Umbrella roaming client tray icon may be gray or red. Alternately, the Umbrella roaming client may not show as registered in the dashboard. This is considered to be an "unregistered" Umbrella roaming client.

The cause for an unregistered Umbrella roaming client is almost always one of three reasons:

Config File User ID—When an admin user downloads the config file (OrgInfo.json or OrgInfo.plist) for registering the Roaming Client, the user's ID is embedded into the file. If the user is later deleted from org, the config file will no longer function because the user validation will fail. In this case, another user with admin credentials would need to download a new config file.

HTTP Proxy (Windows Only)—There is an HTTP/HTTPS proxy at the local computer level, or there may be stale proxy settings leftover from a previous proxy configuration. For more information, see the "HTTP and HTTPS" section of Prerequisites and Umbrella Roaming Client and HTTP Proxies.

Command Line/Mass Deployments —If you deployed the Umbrella roaming client through a distribution tool like GPO, Apple Remote Desktop, or Kaseya, it's likely the information from OrgInfo.json/.plist was not copied correctly. Confirm that you are using a supported method:

Unprotected/Unencrypted

In either the Umbrella roaming client's tray/menu bar icon, or in the Umbrella dashboard, the status is yellow, showing Unprotected/Unencrypted. For more information about this state, including tests and potential fixes, see Umbrella Roaming Client: Unprotected and Unencrypted.

Switching States or Statuses Frequently (Flapping)

Locally on an endpoint, you may see that the Umbrella roaming client's state is constantly changing or 'flapping'. This is observable via the tray/menu bar icon messaging. When flapping occurs, there may or may not be network connectivity issues. If the Umbrella roaming client is rapidly changing states and causing internet connectivity issues, consider disabling the Umbrella roaming client temporarily and contacting support.

If there are no connectivity issues, but 'flapping' or state change was noticed by the user via the tray/menu bar icon, this can usually be attributed to one of the following two scenarios:

Scenario #1: You are utilizing a VPN client which is on our Incompatible VPN Clients list. If so, there is currently no resolution, and you'll have to utilize a different VPN client.

Scenario #2: There is significant packet loss on the network, which in turn causes the Umbrella roaming client's health checks to fail. We recommend using ping or MTR/WinMTR to verify if there is packet loss between 208.67.222.222 / 208.67.220.220 / 2620:119:53::53 / 2620:119:35::35 and the client computer. If the packet loss is high enough, or concentrated—even something above 2% is significant—the Umbrella roaming client may temporarily transition to a different state and provide irregular protection. If there is no packet loss, or you're unable to resolve your packet loss issue, contact support.

Logs

Currently, the Umbrella roaming client logs are not easily read as they are highly verbose, which allows for advanced troubleshooting. Umbrella collects the logs automatically when an issue is reported in a support ticket, which sometimes will require the end-user running our Diagnostic tool manually—see below for information about the diagnostic tool.

At this time, we don't recommend attempting to interpret the logs to troubleshoot. In the near future, we're hoping to provide two sets of logs—advanced logging for Support and developers, but also a set of less verbose logs so you can do your own troubleshooting.

If you'd like to look at the Umbrella roaming client service logs, they're located here:

  • Windows—Open the following file with a text editor: C:\ProgramData\OpenDNS\ERC\OpenDNS_ERC_Service.log
  • Mac—Use the following command in the Terminal application to extract Roaming Client logs from the system log: grep dns-updater /var/log/system.log

Diagnostic Tool

The Diagnostic tool is built into the Umbrella roaming client. In most cases, Support can run this tool and obtain the logs of the Umbrella roaming client automatically. In a few cases, you'll be required to run the tool on behalf of Support or at their request.

Providing diagnostic output when initially opening a support request will greatly increase the speed at which an issue can be troubleshot by Support. You can run the diagnostic tool a number of ways. For more information, see Umbrella Roaming Client: Provide Diagnostic Information to Support.

For more information about what data Umbrella collects, see Appendix H – Remote Logging and Diagnostics.


Appendix B – Virtual Appliances < Appendix C – Troubleshooting > Appendix D – Internal Domains

Updated 7 days ago

Appendix C – Troubleshooting


Suggested Edits are limited on API Reference Pages

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