Need help or have more questions?

Go To Our Support Page

Layer8Insight

Layer8Insight provides a Windows agent and browser extensions that are easily installed using a manual process for trials / evaluations. Larger deployments should leverage management tools such as Splunk Deployment Server applications, Group Policy, SCCM, template system images, etc.

The following reviews the installation, uninstallation and troubleshooting of the Layer8Insight agents.

Splunk is the most popular tool for collecting and analyzing Layer8Insight data. Much of what follows will assume Splunk as the target.

Requirements & Components

The Layer8Insight endpoint agent will ONLY run on Windows-based systems: 32-bit or 64-bit, physical or virtual.

Layer8Insight supports operating systems as early as Windows XP SP3 and Windows Server 2003 SP2 up the current state of the art (Window 10 and Server 2016).

The Layer8Insight Windows agent installation package includes the following components:

  • dcac.exe: 32-bit system-level data forwarding and watchdog service
  • uxmtr.exe: 32-bit agent that collects UX data for each user session

Layer8Insight also provides browser extensions for Internet Explorer, Chrome, and Firefox.

Endpoint / Client Setup

To install Layer8Insight on the endpoint or client you will need the following:

  • Local Administrator privileges for the endpoint / client.
  • Layer8Insight installation files. Get them here.

To prepare for the installation do the following:

  • Move the Layer8Insight installation package / files to the target endpoint or to a network share.
  • Disable any anti-virus software on the endpoint / client.
  • Update the endpoint configuration file as needed.

The Layer8Insight endpoint configuration guide is here.

Installation

The installation of Layer8Insight is very straightforward and should not require any special reconfiguration of an endpoint / client.

NOTE: One must be sure to update the Layer8Insight configuration file to make sure Layer8Insight data is outputed in the desired format and protocol. Find the installation package and open the file "endpoint\config.ini" in a text editor. For the default Splunk setup, edit the "Address" field and set them to the IP address or hostname of your target Splunk server. Save and close the file.

NOTE: properly installing the Firefox extension requires closing all running instances of Firefox before proceeding.

Manual Installation

Double-click the top-level "install.bat" batch script and follow prompts to control which components are installed on the endpoint / client.

Confirm the installation was successful by inspecting the output of the installation process. The Layer8Insight agent will start running assuming the installation was succesful.

Group Policy Installation

The Layer8Insight components can be easily packaged as a Group Policy Object using the Group Policy Management Configuration tool. This is the recommended installation method for larger deployments that do not use base / template system images or Splunk Deployment Server applications.

Please review the command-line output and options in the file "endpoint\manual-install.bat" as a template for installing the components via Group Policy.

Suspending Layer8Insight on Endpoints

The Layer8Insight service "dcacSvc" controls the starting and stopping of the user-space process "uxmtr.exe". This includes the ability to suspend and resume the user-space process based on certain Windows configurations.

The Layer8Insight service looks for either a Windows Registry setting or a specified Active Directory (AD) group to determine if it should suspend the user-space process for a given user or the entire host.

By default, the Layer8Insight service will start the user-space process for all users on the installed host. One does not need to make any registry or AD group changes to make Layer8Insight run for a user.

Registry Settings

The Layer8Insight service supports host-level and user-specific suspending via the Windows Registry.

Note, the Layer8Insight service immediately detects changes to the suspension settings, so the service will enact the new settings shortly after they are changed on a live host.

To enable host-level suspension, the expected value is a DWORD named "Suspended" and it should be set to a value of "1". The specific registry values are as follows. Remove this value or set it to "0" to re-enable Layer8Insight for all users on a host.

  • 64-bit Key: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OctoInsight\Layer8Insight
  • 32-bit Key: HKEY_LOCAL_MACHINE\SOFTWARE\OctoInsight\Layer8Insight
  • Value Name: Suspended
  • Type: REG_DWORD
  • Value: 0 (un-suspend Layer8Insight, default), 1 (suspend Layer8Insight)

To enable user-level suspension, the expected values are the same as above for host-level suspension, except the root of HKEY_LOCAL_MACHINE should be replaced with the user-specific entry in the Registry. For example, the settings for a specific Security ID (SID) would look like the following. Remember, one must either delete this entry or change the value to "0" to re-enable Layer8Insight for the specific user.

  • 64-bit Key: HKEY_USERS\S-1-5-21-<XXXXXXXX>\Software\Wow6432Node\OctoInsight\Layer8Insight
  • 32-bit Key: HKEY_USERS\S-1-5-21-<XXXXXXXX>\Software\OctoInsight\Layer8Insight
  • Value Name: Suspended
  • Type: REG_DWORD
  • Value: 0 (un-suspend Layer8Insight, default), 1 (suspend Layer8Insight)
AD Group Settings

The Layer8Insight user-space process can be suspended based on the user's membership in a specific AD group. The particular AD group that the Layer8Insight service looks for is set in the Layer8Insight configuration file (config.ini). The setting is labeled "SuspendedUserGroupFilters" under the "commonConfig" stanza.

By default the suspension AD group is "Layer8InsightSuspended". So, for any user that belongs to an AD group called "Layer8InsightSuspened", the Layer8Insight service will not start the user-space Layer8Insight agent when the user logs in.

Note, the Layer8Insight service must be restarted in order to detect changes to AD group settings for a user.

Updating Layer8Insight

Prior to performing an update, one must do one of the following if you are planning to keep the current configuration and license files.

  • Copy the desired configuration and license files into the installation directory and then invoke the installation scripts, or
  • Confirm your desired configuration and license files are in the "OctoInsight\Layer8Insight" folder under the 32-bit Program Files directory, then delete the pre-packaged "ini" files from the installation package, and then invoke the installation scripts.

It is recommended to keep copies of the desired configuration and license files in a safe place in case anything unexpected happens.

Configuration Options

The Layer8Insight endpoint configuration guide is here.

Virtualization & VDI Notes

Layer8Insight is compatible with all popular virtualization platforms: Citrix, VMWare, Microsoft, Symantec, etc. Layer8Insight does not interfere or instrument anything in the virtualization layers, so no future incompatibilities are expected. Please let us know if you discover anything to the contrary.

Uninstallation

All Layer8Insight components can be uninstalled using the Windows Control Panel application. Running any of the uninstallers will require Local Administrator privileges.

NOTE: properly uninstalling the Firefox extension requires closing all running instances of Firefox before proceeding.

Alternatively, a batch script, "endpoint\manual-uninstall.bat", is included with the installation package. Running the uninstalling batch script requires Local Administrator privileges. Review the script for the various input options.

Known Issues

  • Google Chrome requires that a target host be part of Active Directory domain in order to enable "managed" or "Enterprise" extensions. Installing the Layer8Insight Extension for Google Chrome via the included MSI will not be successful on a standalone, non-AD host. For standalone, non-AD hosts, one must install the extension via another mechanism (e.g., through the Google Chrome extension store or using a non-managed extension Windows Registry string).
  • Layer8Insight Extensions for Firefox cannot be installed as "managed" or "Enterprise" extensions. This is a design choice by Mozilla.
  • Layer8Insight Extensions for Firefox have to either be enabled by opening the browser after installation or by using configuration settings in Firefox (extensions.autoDisableScopes set to 11, extensions.enabledScopes set to 4) that will auto-enable the extensions without user prompting.
  • Layer8Insight Extensions for Firefox require Firefox to be completely closed in order to properly install and uninstall the Layer8Insight extensions using the included MSI files. Firefox does not support loading and unloading MSI-based extensions while Firefox is running.
  • URL capture in the Microsoft Edge browser is only reliable for Windows systems when English is set as the display language.
  • The agent incorrectly reports logon type "2" or "console" for some remote sessions in Windows 10.

Splunk

Requirements

Splunk is not required to store or analyze Layer8Insight data, but it is the most popular tool to do so. Two applications, the Layer8Insight Indexer App for Splunk and the Layer8Insight App for Splunk, are available to help consume and analyze Layer8Insight data in Splunk.

Here are the main considerations when using Splunk with Layer8Insight:

  • Splunk Enterprise, Splunk Free and Splunk Cloud are all compatible with Layer8Insight data.
  • Splunk Light is not supported due to its limitation on installing applications.
  • The Layer8Insight apps requires Splunk version 6.2 or newer.
  • The Layer8Insight apps have no requirements on the server type, architecture or operating system of the Splunk server(s).
  • Layer8Insight typically produces ~0.5 MB of data per user per workday. As such, monitoring hundreds of users with Layer8Insight can be done while staying under the Splunk Free indexing volume limit of 500 MB per day. Review the Splunk Products Comparison Table to see which option fits your use case and requirements.

Installation & Setup

Installation
  • Download and install Splunk from here.
  • Download both the Layer8Insight Indexer App for Splunk and the Layer8Insight App for Splunk to your local system.
  • Open a browser and go to the Splunk login page (typically "http://IP_ADDRESS_OF_SPLUNK_SERVER:8000")
  • Use the username and password on the landing page to log in for the first time, and then change the default password.
  • Go to http://IP_ADDRESS_OF_SPLUNK_SERVER:8000/manager/launcher/apps/local, and click "Install app from file"
  • Click "Choose file", select the Layer8Insight Indexer App for Splunk installation file, and click "Upload"
  • Click "Install app from file" again.
  • Click "Choose file", select the Layer8Insight App for Splunk installation file, and click "Upload"
  • Under the "Settings" menu in Splunk, use the "Indexes" and "Data Inputs" menus to create the expected indexes and inputs for Layer8Insight agent data to be received and stored in Splunk. Review the documentation in the Layer8Insight Indexer App for Splunk for more details.
Network Setup

Ensure your firewall will allow the Layer8Insight data to reach the Splunk server. By default, Layer8Insight uses TCP over port 8050 to send data to the Splunk server, but a customer can change the port or protocol as necessary.

The Splunk Universal Forwarder or the Splunk HTTP Event Collector can be used to collect data from Layer8Insight agents. Review Splunk documentation about setting up these data sinks.

Perfmon and Windows Event Log Data

The Layer8Insight App for Splunk is designed to work directly with perfmon and Windows Event Log data collected by the Splunk Universal Forwarder. Accessing this data in the Layer8Insight App for Splunk requires two steps:

  • Make sure you are using the setting "mode=multikv" in the "inputs.conf" file of the Splunk Add-On for Windows.
  • Log into the Splunk Server where the Layer8Insight App for Splunk is installed, and make sure the Layer8Insight app's macros named "perfmonrawindexpattern" and "wineventlogindexpattern" point to the indexes that store the perfmon and event log data, respectively. No changes are needed if the default index names were unmodified.

Universal Forwarder

Use of the Splunk Universal Forwarder to move data from the endpoint to the Splunk deployment is supported by Layer8Insight. If the Splunk Universal Forwarder is installed on the endpoint, the Layer8Insight configuration file (config.ini) will need to be updated to send the data to the forwarder on the local system.

The simplest approach is to set the "Address" field in the Layer8Insight configuration file to 127.0.0.1, and then configuring the Splunk Universal Forwarder to listen on port 8050 for incoming Layer8Insight data. An example segment of "inputs.conf" for the Splunk Universal Forwarder is included here. This would be added to the local version of "inputs.conf" found at the following location <SPLUNK_FORWARDER_ROOT>\etc\system\local\inputs.conf

[tcp://127.0.0.1:8050]
sourcetype = layer8data
index=layer8
disabled = 0

HTTP Event Collector

Use of the Splunk HTTP Event Collector to move data from the endpoint to the Splunk deployment is supported by Layer8Insight. The Layer8Insight configuration file (config.ini) will need to be updated to send the data to the HTTP Event Collector.

An example stanza from the Layer8Insight configuration file is provided below. In this example, you would need to update the "URL" and "Authorization" fields to use the values that match your Splunk configuration. Note, the fields "sourcetype", "source" and "index" can be changed if need be. The "source" and "index" fields can be omitted assuming the Splunk receiver is configured to set the values appropriately.

[DataOutput#1]
DataCollectionScope=All
Protocol=SPLUNKHTTPS
DataFormat=SPLUNKJSON
URL=https://<INSERT_HEC_ADDRESS_AND_PORT>/services/collector/event
Authorization=Splunk XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
sourcetype=layer8:hecjson
source=layer8:https:json
index=layer8

Troubleshooting

Installation

Note that the manual installation batch script included with this package will log messages to log files found in the %TEMP%\OctoInsight directory (typically the folder for Local Administrator is: ~\AppData\Local\Temp\OctoInsight).

For issues with installation, confirm the following requirements are met:

  • You are running the manual installation script from a command prompt with Local Administrator privileges
  • The config.ini file has been updated from its default state (e.g., the configuration setting for the "Address" fields point to your target server)
  • Close all running instances of Firefox if you are installing the Firefox extension
  • Be sure to read the debug output from the installation script

After you inspect the log file output, be sure to inspect the Windows Event logs for any indications of errors. The Event Logs can be viewed with the shortcut Windows Key, type event viewer, and hit Enter. Any errors should appear in the top-level Windows Log folders.

Configuration Changes

Editing the Layer8Insight configuration file (config.ini) in the installation folder (e.g., under Program files) will require Local Administrator privileges. It is recommended to open a command prompt as Local Administrator and then entering notepad.exe and opening the target "config.ini" file.

You MUST restart the "dcacsvc" service anytime you update the "config.ini" file on a live system with running a instance of Layer8Insight.

The Layer8Insight endpoint configuration guide is here.

Runtime

When Layer8Insight is installed, the "dcacSvc" service (process "dcac.exe") and the "uxmtr.exe" process must be running for data to be captured and reported. The "dcacSvc" service acts as a watchdog to restart "uxmtr.exe" if it stops for any reason.

The "dcacsvc" service should automatically restart if it stops from an error.

There are a number of ways to get debug information about Layer8Insight.

  • Status page: open a browser on the client and go to the page http://127.0.0.1:50291/status. This page prints out status information for a given client. It is enabled if the config.ini file includes the setting StatusReport=1 in the [dcacConfig] stanza.
  • DbgView output: both the "dcacsvc" service and the "uxmtr.exe" process will produce debug output that is visible using the Windows' debug utility, DbgView. This tool can be obtained from the SysInternals package found here. Download this tool and run it as Administrator and hit Ctrl + K to enable kernel output capture. The DbgView output is enabled in the "config.ini" file by setting the option DebugOutput=1 in both [dcacConfig] and [uxmtrConfig] sections.
  • Diagnostic Log Viewer: both the "dcacSvc" service and the "uxmtr.exe" process will produce debug output that is visible using the included Layer8Insight diagnostic viewer application found in the 32-bit Program Files folder "OctoInsight\Layer8Insight". The diagnostic output to the Layer8Insight Diagnostic Viewer is enabled in the config.ini file by setting the options DebugOutput=1 and DCACDiagLogEnabled=1 in the [dcacConfig] stanza and the option UXMTRDiagLogEnabled=1 in the [uxmtrConfig] stanza.
  • Windows Event Log: by default the Layer8Insight software will output debug information to the Windows Event Log. There is a specific folder named "OctoInsight" under the "Application and Service Logs" folder that will contain all events emitted by the Layer8Insight agents. The setting "ErrorEventLog" under the [commonConfig] section of the "config.ini" file controls the Windows Event Log output. It is enabled by default, but it can be forced using ErrorEventLog=1.

If the Layer8Insight agents stop running or don't seem to be producing data, double-check that your license has not expired. License expiration errors should be in the Windows Event Log and produced as logged events in the Layer8Insight data output (e.g., you should be able to search for license expiration messages in Splunk).

Uninstallation

Note that the manual uninstallation batch script included with this package will log messages to log files found in the %TEMP%\OctoInsight directory (typically the folder for Local Administrator is: ~\AppData\Local\Temp\OctoInsight).

For issues with uninstallation, confirm the following requirements are met:

  • You are running the manual uninstallation script from a command prompt with Local Administrator privileges
  • Close all running instances of Firefox if you are uninstalling the Firefox extension
  • Be sure to read the debug output from the uninstallation script

After you inspect the log file output, be sure to inspect the Windows Event logs for any indications of errors. The Event Logs can be viewed with the shortcut Windows Key, type event viewer, and hit Enter. Any errors should appear in the top-level Windows Log folders.