Layer8Insight Endpoint Configuration File Specification

The Layer8Insight endpoint components are controlled by the settings found in the Layer8Insight configuration file "config.ini".

Before Layer8Insight is installed, the configuration file in the installation package can be updated to suit the needs of the planned deployment.

After Layer8Insight is installed, the configuration file is found in the 32-bit Program Files folder "OctoInsight\Layer8Insight". This file can be updated by a user with local administrator privileges. Once the updates are saved, the Layer8Insight service "dcacsvc" must be restarted in order for the changes to be applied.

The configuration file is organized into sections or stanzas. The following will detail the configuration options found in each stanza.

DCAC Service Options

The Layer8Insight Windows service "dcacSvc" configuration options appear under the stanza titled "dcacConfig", and only one such stanza should appear in a configuration file.

[dcacConfig]
DebugOutput = [ 1 | 0 ]
* When set to 1 (enabled), DCAC outputs debug data via Windows's OutputDebugString, which is visible using tools such as DebugView or the Layer8Insight diagnostic viewer (see DCACDiagLogEnabled).
* Defaults to 0.

DCACDiagLogEnabled = [ 1 | 0 ]
* When set to 1 (enabled) and DebugOutput is enabled, DCAC outputs debug data visible using Layer8Insight's built-in debug utility.
* Diagnostic output written to folder %PROGRAMDATA%\OctoInsight\Layer8Insight\l8-diag
* Defaults to 0.

DCACDiagReportingLevel = [ 1 – 4 ]
* Controls debug output, where the higher the number the greater the detail in the debug output.
* Defaults to 1.

DCACStatusReport = [ 1 | 0 ]
* When set to 1 (enabled), DCAC will provide a status report on port 50291 using the URL http://127.0.0.1:50291/status.
* Defaults to 0.

UploadInterval = <integer>
* The number of seconds DCAC waits between checking its internal event queue in case the queue processing has stalled.
* Defaults to 15.

DataFolderMaxSize = <integer>
* The maximum size in Kilobytes of the local data folder DCAC uses as a data store when writing events to disk.
* Defaults to 10000.

RetryFolderMaxSize = <integer>
* The maximum size in Kilobytes of the local data folder DCAC uses for caching data.
* Setting this value to 0 will disable caching and limit disk I/O - useful for VDI installations.
* Defaults to 10000.

DCACRetryCachePurgeRepeatInterval = <integer>
* The number of seconds DCAC waits between attempts to purge cached data files.
* Defaults to 30.

DCACRetryCachePurgeMaxProcessingTime = <integer>
* The number of seconds DCAC can take to purge cached data files in a given cycle.
* Defaults to 5.

DCACRetryCacheFileMaxAge = <integer>
* The number of hours a cached data file is kept before becoming eligible for purging from the retry cache.
* Defaults to 24.

UploadFailureRecoveryPeriod = <integer>
* The number of seconds to wait before reattempting a failed data upload.
* A retry is only attempted if a data channel is shown to be working again, i.e., a data upload has successfully completed.
* Defaults to 0.

ThinDCADataPort = <integer>
* The TCP input port DCAC listens on for incoming data from UXMTR and browser extensions.
* Defaults to 50291.

UXMTR Agent Options

The Layer8Insight agent process "uxmtr" configuration options appear under the stanza titled "uxmtrConfig", and only one such stanza should appear in a configuration file.

[uxmtrConfig]
DebugOutput = [ 1 | 0 ]
* When set to 1 (enabled), UXMTR outputs debug data via Windows's OutputDebugString, which is visible using tools such as DebugView or the Layer8Insight diagnostic viewer (see UXMTRDiagLogEnabled).
* Defaults to 0.

UXMTRDiagLogEnabled = [ 1 | 0 ]
* When set to 1 (enabled) and DebugOutput is enabled, UXMTR outputs debug data visible using Layer8Insight's built-in debug utility.
* Diagnostic output written to folder %PROGRAMDATA%\OctoInsight\Layer8Insight\l8-diag
* Defaults to 0.

UXMTRDiagReportingLevel = [ 1 – 4 ]
* Controls debug output, where the higher the number the greater the detail in the debug output.
* Defaults to 1.

RealtimeDashboard = [ 1 | 0 ]
* When set to 1 (enabled), UXMTR will provide a GUI dashboard in the user context with a summary of the user's data.
* Defaults to 0.

IncludeURL = [ 1 | 0 ]
* When set to 1 (enabled), the raw Layer8Insight data will include URL strings from browser windows.
* Defaults to 1.

IncludeWindowTitle = [ 1 | 0 ]
* When set to 1 (enabled), the raw Layer8Insight data will include Window Title strings from application windows.
* Defaults to 1.

IncludeIPAddress = [ 1 | 0 ]
* When set to 1 (enabled), the raw Layer8Insight data will include the IP address for the host.
* When set to 0 (disabled), the value 127.0.0.1 is reported as the IP address.
* Defaults to 1.

NonBrowserExesExcludeFilters = <string>
* A semicolon delimited string of executable names UXMTR should ignore.
* Defaults to empty.

WindowClassExcludeFilters = <string>
* A semicolon delimited string of window class names UXMTR should ignore.
* Defaults to empty.

URLCacheMaxAge = <integer>
* The number of days before entries in the local URL cache are aged out.
* Defaults to 30.

URLScanMaxTime = <integer>
* The maximum amount of time in milliseconds UXMTR can take to scan for a URL value.
* Defaults to 3000.

UXMTRToDCACUploadErrorsTimeout = <integer>
* This maximum amout of time in seconds UXMTR will keep trying to send data to DCAC service.
* UXMTR will terminate itself if the timeout value is reached.
* Defaults to 60.

UXMTRPriorityLevelSetting = [NORMAL | LOWER-1 | DYNAMIC] 
* The scheduling priority for the UXMTR processes. 
* Defaults to NORMAL.

UXMTRHighCPUThreshold = <integer>
* If UXMTRPriorityLevelSetting is set to DYNAMIC, this value defines the high CPU threshold in the formula: UXMTR priority is set to LOWER-1 if the UXMTRHighCPUThreshold is hit UXMTRHighCPUSampleCount times.
* Defaults to 25.

UXMTRLowCPUThreshold = <integer>
* If UXMTRPriorityLevelSetting is set to DYNAMIC, this value defines the low CPU threshold in the formula: UXMTR priority is set to NORMAL if the UXMTRLowCPUThreshold is hit UXMTRLowCPUSampleCount times.
* Defaults to 5.

UXMTRHighCPUSampleCount = <integer>
* The number of samples to trigger dynamic priority adjustment based on the threshold set in UXMTRHighCPUThreshold.
* Defaults to 5.

UXMTRLowCPUSampleCount = <integer>
* The number of samples to trigger dynamic priority adjustment based on the threshold set in UXMTRLowCPUThreshold.
* Defaults to 5.

UXMTRUXMEventQueueProcessingDelay = <integer>
* The number of milliseconds to add as a delay between processing events in the event queue once the threshold value in UXMTRUXMEventQueueLengthDelayTrigger is exceeded.
* This setting is not introduced if UXMTRUXMEventQueueLengthDelayTrigger is set to 0.
* Defaults to 500.

UXMTRUXMEventQueueLengthDelayTrigger = <integer>
* The number of items in the event queue which, if exceeded, will trigger the introduction of the delay in UXMTRUXMEventQueueProcessingDelay between processing other queued events (limits CPU).
* Set this value to 0 to disable the delay mechanism.
* Defaults to 0.

Common Options

The common Layer8Insight configuration options appear under the stanza titled "commonConfig", and only one such stanza should appear in a configuration file.

[commonConfig]
ErrorEventLog = [ 1 | 0 ]
* When set to 1 (enabled), Layer8Insight will record errors to the Windows Event Log under the application folder "OctoInsight".
* Defaults to 1.

WERL8UIPopupsDisabled = [ 1 | 0 ]
* When set to 1 (enabled), the Layer8Insight executables "dcac.exe" and "uxmtr.exe" are added to the Windows Error Reporting exclusion list in the Windows Registry.
* Defaults to 1.

SuspendedUserGroupFilters = <string>
* A semicolon delimited string of Active Directory groups whose members will not run UXMTR upon logging on.
* The "*" character can be used as a wildcard.
* Defaults to empty.

UserGroupIncludeFilters = <string>
* A semicolon delimited string of Active Directory groups that should be reported in Layer8Insight events.
* The "*" character can be used as a wildcard.
* Defaults to empty.

UXMTRMaxRestarts = <integer>
* The maxiumum number of times DCAC will restart UXMTR if the latter stops running.
* Defaults to 5.

AnonymizeAllNames = [ 1 | 0 ]
* When set to 1 (enabled), all identifiable fields (UserName, ComputerName and DomainName) will be anonymized.
* Defaults to 0.

AnonymizeComputerNames = [ 1 | 0 ]
* When set to 1 (enabled), the ComputerName field will be anonymized.
* Defaults to 0.

AnonymizeDomainNames = [ 1 | 0 ]
* When set to 1 (enabled), the DomainName field will be anonymized.
* Defaults to 0.

AnonymizeUserNames = [ 1 | 0 ]
* When set to 1 (enabled), the UserName field will be anonymized.
* Defaults to 0.

Data Output Options

The Layer8Insight data output configuration options appear under the stanza(s) titled "DataOutput#<NUMBER>" where <NUMBER> can be any integer. You can include more than one data output stanza, e.g., sending data to multiple receivers in various formats.

[DataOutput#<NUMBER>]
DataCollectionScope = [ All | DesktopAppMeter | WaitTimeMeter | LogonDelayMeter | PageLoadMeter | SubPageLoadMeter | AlertMeter ]
* The Layer8Insight meter output to include in this output channel.
* No default.

Protocol = [ HTTP | HTTPS | SPLUNKHTTP | SPLUNKHTTPS | TCP | UDP | FTP | SYSLOG | EVENTLOG | LOCALFILE | FILEAPPEND ]
* The protocol to output Layer8Insight data.
* LOCALFILE and FILEAPPEND will write to local disk in the folder %PROGRAMDATA%\OctoInsight\Layer8Insight\l8-data
* When targeting the Splunk HTTP Event Collector, either the SPLUNKHTTP and SPLUNKHTTPS option should be selected.
* No default.

DataFormat = [ NVP | SPLUNKJSON | JSON | CSV | XML ]
* Layer8Insight data output format.
* NVP stands for Name-Value Pairs, also known as Key-Value Pairs.
* When targeting the Splunk HTTP Event Collector, the SPLUNKJSON option should be selected to ensure the expected metadata envelope is transmitted with each event.
* No default.

###########################################
The following paramerters are required depending on the chosen setting for the Protocol option.

Address = <string>
* IP address or hostname of data receiver.
* Only applicable for non-HTTP network protocols: TCP, UDP, FTP, and SYSLOG.
* No default.

Port = <integer>
* IP port number of data receiver.
* Only applicable for non-HTTP network protocols: TCP, UDP, FTP, and SYSLOG.
* No default.

Username = <string>
* Authentication username for FTP Protocol setting.
* No default.

Password = <string>
* Authentication password for FTP Protocol setting.
* No default.

Folder = <string>
* Sub-folder to store files.
* Only applicable for file-based Protocol settings: FILEAPPEND, LOCALFILE, and FTP.
* Default is empty string (i.e., store in default root folder for Protocol).

URL = <string>
* Full URL string for HTTP-based protocols.
* Replaces Address, Port, Username and Password fields.
* Only applicable for HTTP-based network protocols: SPLUNKHTTP, SPLUNKHTTPS, HTTP, and HTTPS.
* SPLUNKHTTP and SPLUNKHTTPS differ from HTTP and HTTPS in that the former two include the Splunk-required metadata envelope that is expected by the Splunk HTTP Event Collector.
* No default.

Authorization = <string>
* Authroization header required by Splunk HTTP event collector.
* Only applicable for Splunk HTTP-based network protocols: SPLUNKHTTP and SPLUNKHTTPS.
* Example: Splunk XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
* No default.

EscapeEncodeJSONData = [ 1 | 0 ]
* When set to 1 (enabled) and using JSON-based output settings (see "DataFormat"), special characters will be escaped based on the ECMA standard for encoding strings (see ECMA reference document).
* Defaults to 1.

index = <string>
* A specific index value to include in the Splunk HTTP Event Collector metadata envelope (see Splunk documentation).
* Only applicable for Splunk HTTP-based network protocols (SPLUNKHTTP and SPLUNKHTTPS) and the SPLUNKJSON output format for "DataFormat".
* Defaults to empty (i.e., no index value is included).

sourcetype = <string>
* A specific sourcetype value to include in the Splunk HTTP Event Collector metadata envelope (see Splunk documentation).
* Only applicable for Splunk HTTP-based network protocols (SPLUNKHTTP and SPLUNKHTTPS) and the SPLUNKJSON output format for "DataFormat".
* Defaults to empty (i.e., no sourcetype value is included).

source = <string>
* A specific source value to include in the Splunk HTTP Event Collector metadata envelope (see Splunk documentation).
* Only applicable for Splunk HTTP-based network protocols (SPLUNKHTTP and SPLUNKHTTPS) and the SPLUNKJSON output format for "DataFormat".
* Defaults to empty (i.e., no source value is included).