Creating ConfigSources

Overview

ConfigSources are templates based on Groovy or Powershell scripts that define how LogicMonitor should access, collect, and alert on your devices’ configuration files.

Similar to other LogicModules, LogicMonitor installs with pre-configured ConfigSources for many common systems and applications. However, you can also create your own custom ConfigSources.

Note: In order for ConfigSource data collection to work properly for cloud resources, you’ll need to first enable monitoring via local Collector, as discussed in Enabling Monitoring via Local Collector.

Note: Monitored configuration files cannot exceed 3MB in size per individual file.

Note: The .config files are available on the Resource page till the LMES data view period. If you want to view the .config files later, you must use the API tokens to download the .config files within the LMES data storage period. You can contact the support team for further assistance.

Creating a ConfigSource

Note: If the ability to monitor and alert on configuration files is not currently available in your LogicMonitor platform and you would like to learn more, reach out to your customer success manager.

To create a ConfigSource, navigate to Settings | LogicModules | ConfigSources | Add | ConfigSource. From the Create New ConfigSource dialog that displays, there are four categories of settings that must be configured:

• General Information
• Active Discovery
• Collector Attributes
• Config Checks

General Information

1. Name: The unique name of the ConfigSource.  As a best practice, this name should be descriptive: specify the platform or application name, then, if necessary, a specific component of the platform.  
2. Displayed as: The name the ConfigSource will be displayed with in the Device page. This name does not need to be unique.
3. Description: The description that will be associated with this ConfigSource. As a best practice, if the ConfigSource name is not unambiguous as to what the ConfigSource is collecting, the description field should provide enough information that someone seeing the name and the description will be clear what the ConfigSource does.
4. Search keywords: Tag the ConfigSource with keywords (related to its name, purpose, scope, etc) that will facilitate a search for it.
5. Technical Notes: This field can contain any miscellaneous technical notes associated with the ConfigSource, beyond what is included in its description.
6. Group: The ConfigSource Group to which the ConfigSource will be added. If this field is left empty, the ConfigSource will not be added to a group. If you enter text that does not match an existing ConfigSource Group, one will be created.

Applies To

The Applies To field accepts LogicMonitor’s AppliesTo scripting as input to determine which resources will be associated with this ConfigSource. For detailed information on using this field (including its wizard and test functionality), along with an overview of the AppliesTo scripting syntax, see AppliesTo Scripting Overview.

Collect Every

The Collect Every field defines how frequently data will be collected (i.e. the data collection interval).

This field should be set to an interval appropriate for the Configs being checked. For example, items that change frequently or require immediate attention in the event of an error  (e.g. supervisor/management CPU is overloaded) should have a short poll cycle, such as one hour.

Note that longer poll cycles impose less load on both the server being monitored and the Collector. 

Multi-instance?

If this option is checked, the ConfigSource will be multi-instance.

Multi-instance means there are multiple occurrences of a config file, e.g. for multiple network interfaces on a Fortigate firewall, each containing its own config file.

Active Discovery

Active Discovery is used to manage the monitored instances of a ConfigSource. This is only applicable for multi-instance ConfigSources. If Active Discovery is enabled, LogicMonitor will automatically find a Configsource’s instances on your device, determine their display names or aliases, and keep them up to date

Enable Active Discovery

Check Enable Active Discovery to automatically manage a ConfigSource’s instances. This option is only available if the Multi-instance? option is checked.

Parameters

The Active Discovery Parameters script is an embedded Groovy or PowerShell script which determines what device configuration files are available and creates ConfigSource instances for them. Exactly how the script discovers instances varies according to device type. For an example, see this ConfigSource discovery script for Cisco ASA devices. 

Collector Attributes

Here, you will need to embed the Groovy or PowerShell script used to retrieve your config files. If you would like to use a scripting language other than Groovy or Powershell, you also have the option to upload a script file. Please note that, when possible, best practice is to use an embedded Groovy script so you can take advantage of the EXPECT syntax.

The syntax for ConfigSource scripts is largely standardized. When writing your own ConfigSource script, LogicMonitor best practices suggest you copy-and-paste an existing ConfigSource template from the LogicMonitor repository and make the necessary syntactical changes to fit your environment. For instance, if you are working with Juniper devices, you would substitute the expect (“#”) command used in the screenshot below to identify Cisco configs for an expect (“<“) command.

Prior to running your script, you must set your SSH authentication credentials as properties on the device(s) you wish to implement config monitoring. These properties should take the form of ssh.user/ssh.pass if the applied devices permit SSH  or config.user/config.pass for non-SSH devices (ie. telnet/FTP). The script is designed to pull-in these properties and use them to SSH in to your device. In devices that do not automatically have SSH authentication privileges enabled (ie. Cisco ASAs), a third credential may need to be saved as a property, ssh.enable.pass.

For the sake of understanding a ConfigSource script’s structure, here is a broken-down view of an example script written in Groovy:

1. Obtains the SSH authentication credentials set in the device’s properties.
2. SSHs into the device. Expect that “#” will indicate a successful connection and that the device is ready to receive commands.
3. Disables pagination for the device’s config file. This ensures the file is obtained in a single uninterrupted view.
4. Requests the config file.
5. Logs out of the SSH session with the device.
6. Strips the NTP clock period value from the retrieved config file. This value constantly changes and these changes are typically of no concern. Removing this value prevents the ConfigChecks from generating unnecessary alerts.
7. Closes the SSH connection and imports the script’s output (the config file) into your LogicMonitor account.

Note that this particular script assumes that the provided SSH authentication credentials are sufficient for viewing the running config. Some devices, such as Cisco ASAs, will require an extra step to enable these elevated permissions.

In these cases, if there is an additional device property defined called “ssh.enable.pass”, the script will attempt to use that to escalate its privileges. If the “ssh.enable.pass” property does not exist, then the script will attempt to use the standard “ssh.pass” property to escalate its privileges:

try
{
    pass = hostProps.get("ssh.pass")
}
catch (all)
{
    println "(debug::fatal) Could not retrieve the config.pass device property.  This is required for authentication.  Exiting."
    return 1
}
try
{
    enable_pass = hostProps.get("ssh.enable.pass")
}
catch (all)

Config Checks

ConfigSources generate alerts based on config checks. Much like a datapoint and threshold in a DataSource, a config check monitors the availability of a config file, or specific contents of the file, and triggers an alert when defined criteria are met. There are five types of config checks, each providing a specific method to monitor the config file.

The options available for each type of config check vary depending on the file format selected in the ConfigSource definition. Selecting the file format most appropriate to the config file you are monitoring can make the process of defining config checks easier and less prone to error.

File Formats

Three file formats are available: arbitrary text, java-properties, and Unix. Using the java-properties or Unix file format provides some implicit checks that may make it easier to set up your ConfigSource. The default file format is arbitrary text.

Note: The file format must be selected when the ConfigSource is created and cannot be modified once the ConfigSource has been saved.

File Format Descriptions

Unix. Lines are separated by the line feed character (\n), as opposed to the DOS format which uses a combination of carriage return and line feed characters (\r\n) to separate lines. Lines starting with “#” are treated as comments.

java-properties. Also referred to as “.properties”. Lines starting with “#” or “!” are treated as comments. Text preceding “=” is treated as a key (field), text following “=” is treated as a value. Below is a sample of text in java-properties format.

# You are reading the ".properties" entry.
! The exclamation mark can also mark text as comments.
website = https://en.wikipedia.org/
language = English
# The backslash below tells the application to continue reading
# the value onto the next line.
message = Welcome to \
          Wikipedia!
# Add spaces to the key
key\ with\ spaces = This is the value that could be looked up with the key "key with spaces".
# Unicode
tab : \u0009

Implicit Checks by File Format

Config Check Types

There are five types of config checks, each providing a specific method to monitor the config file.

Check Type: Config cannot be retrieved

Description: Generates an alert if the collection script fails to complete successfully.

Options: You can select the severity of the alert generated.

Comments: An alert will remain active until the collection script completes successfully.

Example

This config check will generate an Error alert if the config file cannot be retrieved.

Check Type: Any Change (diff check)

Description: Generates an alert if any change is detected in the content of the config file.

Options: You can add filters to ignore certain changes such as timestamps or the addition or removal of blank lines. If the file format is Unix or java-properties, some filters will be included by default, though you can remove them if needed. You can configure the alert to clear upon acknowledgment, after a set period of time has passed, or either (i.e. whichever event occurs first). You can select the severity of the alert generated.

Comments: If neither of the alert clear options is enabled, an alert will clear when the collected config file is identical to the current version.

Example

This config check will generate a Warning alert if any changes are detected in the config, with default ignore filters for the unix file format. The option to clear the alert when it is acknowledged has been enabled.

Check Type: Missing Field

Description: Generates an alert if a specified field is not present in the config file.

Options: You can select the severity of the alert generated.

Comments: If the file format is set to arbitrary or unix, this check simply searches the file contents for the specified string. A regular expression may be necessary to unambiguously identify the field in question. If the file format is java-properties, the check compares the specified string with the list of field (key) names in the file. An alert will clear when the specified field is found in the config file.

Example

This config check will generate a Warning alert if the text “Ubuntu17-9ab76122-” is not present in the config file.

Check Type: Value

Description: Generates an alert if the value of a field does not meet the specified criteria.

Options: You may select a comparison operator for the value or simply alert if the value changes from one version of the config file to the next. If the alert is generated by a change in the value, you can configure the alert to clear upon acknowledgment, after a set period of time has passed, or either (i.e. whichever event occurs first). You can select the severity of the alert generated.

Comments: If the file format is set to arbitrary or Unix, this check simply searches the file contents for the specified string. You will need a regular expression with a capture group to extract the field value. If the file format is java-properties, the check compares the specified string with the list of key values in the file. If neither the clear when acknowledged or clear after a set period of time options is enabled, an alert will clear when the value meets the specified criteria.

Example

This config check will generate a Critical alert if the value of the community string changes. Note the use of a regular expression with the value of the community string specified as a capture group.

Check Type: Groovy script

Description: Generates an alert if the Groovy script returns 1. The contents of the config file are made available to the config check via the built-in text variable “config” which provides standard Groovy string methods such as contains, matches, and size. Note that Groovy script config checks require Collector version 25.200 or higher.

Options: You can select the severity of the alert generated.

Comments: All of the logic for determining whether an alert should be generated is contained in the script. The check itself merely looks at the value returned by the script: 1 triggers an alert, 0 does not. An alert will clear when the script returns 0.

Example

This config check uses a Groovy script to retrieve the value of the system.hostname device property and then checks to see if this value is present in the config file. If it is not, an Error alert is generated.