Enhanced Script NetScan

Use the LogicMonitor Enhanced Script NetScan for improved output formatting, additional group assignment options, and device filtering. You can choose to inherit device credentials from a specific device, device group, or you can set custom credentials in the Netscan configuration.

Requirements

To use Enhanced Script NetScan, you must have LM Collector version 32.400 or higher installed on the collector that runs the Netscan.

Adding an Enhanced Script NetScan

1. Go to Settings > NetScans > Add > Advanced NetScan.
2. On the Add NetScan window, enter a Name and a Description .
3. Enter a Group. You can select from a list of existing groups or you can leave the field blank to add it to the @default group. For more information, see Creating NetScans.
4. Use the Collector Group and Collector fields to select a collector. This is the collector that runs the NetScan. Options in the Collector field are filtered based on the Collector Group.
5. Select Enhanced Script Netscan from the Method drop-down list.
6. From Device Credentials, select one of the following options:
   • Inherit credentials from Device Group
   • Inherit credentials from Device
   • Use custom credentials for this scan. If you select this option, select Add [+] to provide a property and property value. You can select from a list provided or type your own custom key name. 

7. Use the Filters feature to exclude a device or devices from the scan. Filtering is based on the device attributes and values that are assigned in the Netscan script.
8. To supply a script, select one of the following methods:
   • Upload script file. Select Upload Script to upload a script from your local machine.
   • Upload script file from the network. Enter a path/filename to upload a script from a network location.
   • Embed a Groovy script. Paste the Groovy script into the field provided. For more information, see Script Formatting.
9. Enter a Default Group. If a group is not specified in the script output, the resource will be added to the Default Group. If a group is specified in the script output, the Default Group is ignored.
10. You can Exclude Duplicate IP Addresses from the NetScan by selecting one of the following options:
    • Matching any monitored resources/devices— Only when adding new resources, the system will exclude discovered resources that have the same IP address (to avoid monitoring the same resource again). However, next time while running the Enhanced Script NetScan on the added resources, the criteria of ‘excluding IP address of resources that match any monitored resources’ does not apply. After adding resources, when you update their properties and then run the Enhanced Script NetScan, the resources will be updated.
    • Matching resources/devices already discovered by this NetScan— Excludes any discovered resource that has already been moved into monitoring by this NetScan.
    • Matching resources/devices in these resource groups— Excludes any discovered resource that has the same IP address as a resource belonging to a specified resource group. When this option is selected, an additional field appears so that you can specify one or more resource groups.
    • Matching resources/devices currently assigned to these Collectors— Excludes any discovered resource that has the same IP addresses as a resource that is assigned to a specified collector. When this option is selected, an additional field appears so that you can specify one or more collectors.
11. Enable the Run this NetScan on a schedule checkbox to run the Enhanced Script Netscan on a schedule.
    • Frequency— Hourly, daily, weekly, or monthly.
    • Start time— Enter the start time in the field provided.
    • Time Zone— Select a time zone from the Event time zone pop-up window.
12. Do one of the following to save the scan:
    • Select Save and Run to save your changes and to run the Netscan.
    • Select Save to save the Netscan without running it.

Using Enhanced NetScan Script to Update Properties 

1. Navigate to Settings > NetScans and select the required resource.
   
2. On the Manage NetScan page, navigate to the Device Credentials section to add sensitive data.
   
3. Select Use custom credentials for this scan.
   
4. Enter the required property and property value information in the respective fields.
   
   
   
5. Modify the Groovy script as required.
   
   Note: Ensure that sensitive information is not included in the Groovy script. 
6.  Select Save.

Collector Assignment

Devices created from an Enhanced Script Netscan can be assigned to any collector. The precedence for collector assignment is as follows, checking for both existence and validity at each step and taking the first match found:

Script Formatting

Enhanced Script Netscan requires JSON format for output. Devices should be formatted as a list of objects using only the following keys:

Script Formatting Example

The following example  provides script output formatting guidance:

[

{
    "hostname" : "1.1.1.1",
    "displayname" : "Server 123",
    "hostProps" : {
        "custom.prop"  : "value",
        "another.prop" : "384597",
        "ya.prop"      : "null"
    },
    "groupName" : ["ParentGroup/ChildGroup", "RootLevelGroup"],
    "collectorId" : 18
},
{
    "hostname" : "1.1.1.2",
    "displayname" : "Server 456",
    "hostProps" : {
        "custom.creds.user" : varUser.toString(),
        "custom.creds.pass" : varPass.toString()
    },
    "groupName" : ["GrandparentGroup/ParentGroup/NewGroupNotYetInExistence"],
    "collectorId" : 20
}

]

Custom Properties

You can assign custom properties to devices during NetScan runs using the hostProps field. These properties are custom and you can edit them  from the Resources page. If you assign properties with any of the following prefixes, they are ignored and the device will be added without them:

• auto. 
• predef. 
• system.
  • system.categories is the only system property that may be set from Enhanced Script Netscan.

Sample Enhanced Script Netscan Script

You can use the following boilerplate code to create your own custom scripts. 

/*******************************************************************************
 * © 2007-2022 - LogicMonitor, Inc. All rights reserved.
 ******************************************************************************/
 
import com.logicmonitor.common.sse.utils.GroovyScriptHelper as GSH
import com.logicmonitor.mod.Snippets
import com.santaba.agent.AgentVersion
import java.text.DecimalFormat
 
// To run in debug mode, set to true
Boolean debug = false
 
// Import any needed credentials or properties that have been set in the UI
String netCreds = netscanProps.get("custom.property.key")
 
// Retrieve the collector version
Integer collectorVersion = AgentVersion.AGENT_VERSION.toInteger()
 
// Bail out early if we don't have the correct minimum collector version to ensure netscan runs properly
if (collectorVersion < 32400) {
    def formattedVer = new DecimalFormat("00.000").format(collectorVersion / 1000)
    throw new Exception(" Upgrade collector running netscan to 32.400 or higher to run full featured enhanced script netscan. Currently running version ${formattedVer}.")
}
 
// Bail out early if we don't have the necessary credentials
if (!netCreds) {
    throw new Exception(" Must provide credentials to run this script.  Verify necessary credentials have been provided in Netscan properties.")
}
 
// Load the lm.emit snippet to ensure proper output formatting
def modLoader = GSH.getInstance()._getScript("Snippets", Snippets.getLoader()).withBinding(getBinding())
def lmEmit = modLoader.load("lm.emit", "0.0")
 
// Get your data and build your list of resources
List<Map> resources = []
 
/*
Insert your custom code to retrieve data about the devices you want to add
*/
 
// Loop through your data to build your device map with proper keys
// in loop...
    Map resource = [
        "hostname"    : ip,          // String
        "displayname" : displayName, // String
        "hostProps"   : deviceProps, // Map<String, String>
        "groupName"   : groupName,   // List<String>
        "collectorId" : 123          // Integer
    ]
 
    resources.add(resource)
// ...end loop
 
// Output validated data in JSON format
// If errors have been made in acceptable/required keys, lm.emit will throw and inform the user
lmEmit.resource(resources)