Other LogicModules

Creating a ConfigSource

This page will walk you through the process of creating your own ConfigSources.

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

Creating your own ConfigSources is analogous to the process for creating DataSources. Like DataSources, this process can be broken-down into four segments: General Information, Active Discovery, Collector Attributes, and Config Checks.

Note: In order for ConfigSource data collection to work properly for cloud resources, you'll need to first enable monitoring via local Collector

General Information

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 defines which devices will be associated with this ConfigSource. This field needs to be in AppliesTo Scripting Language syntax.  

Test Applies to

Select the "Test" option to display a list of all devices which will be impacted by the new Applies To configuration 


Collect Every

The Collect Every field defines how frequently data will be collected.  

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. 

Enable 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

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:

Collector Attributes
  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 it's 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

Config Checks are analogous to datapoints. They specify both the config files that should be monitored as well as how they should be monitored, i.e., alert is the file can not be retrieved, if a change is detected, etc. 

Config Checks

There are four specialized checks that can run on your config files:

1. Config cannot be retrieved

If this option is selected, you will be alerted if the config file can not be located.

1. Config cannot be retrieved

2. Any Change

If this option is selected, you will be notified of ANY change made to your config files.

If you do not want to be notified of certain expected or routine changes to your configs, you can enumerate those changes in the "ignore these" field.  

Exmple: Items such as NTP clock period are expected to change constantly. If your script does not strip these values, setting "ignore lines that start with" to "ntp clock-period" will ensure that you will not be notified for these changes.

2. Any Change

3. Missing Field

If this option is chosen, an alert can be triggered if a config no longer contains the specified field (i.e. string). Regular expressions can also be used.

Example: If all passwords need to be encrypted and not displayed in plain text, you can run a configcheck for "service password encryption" to ensure that this configuration did not get turned off.

Missing Field

4. Value

If this option is selected, you will be notified if a value for your config file changes beyond the designated acceptable range.

Example: If you wanted to ensure that a particular port remains in access mode, you would set the following:

When Value of: switch(config-if)

is Not Equal to (!=) Value:  switchport mode access

then trigger this type of alert: Warning

4. Value

5. Use Groovy Script 

This option allows you to embed a Groovy script which will check a designated config file based of your specified parameters. This enables maximum customization of your Config Checks.  Please note that this option requires Collector version 25.200 or higher.