Enhanced Script NetScan

Use the LogicMonitor Enhanced Script NetScan for improved output formatting, additional group assignment options, and resource filtering. You can inherit device credentials from a specific resource or resource group or 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. Navigate to Settings > NetScans > Add > Advanced NetScan.
   
   
   
   
2. On the Add NetScan window, enter a Name and a Description.
   
3. In the NetScan Group field, enter the group name. You can select from a list of existing groups or leave the field blank to add it to the @default group. For more information, see Creating NetScans.
   
4. From the Collector Group and Collector options, select a collector group and a collector respectively. This is the collector that runs the NetScan. Options in the Collector field are filtered based on the selected 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 – Select Add [+] to provide a property and property value. You can select a property from the provided list or type a custom key name.
     

7. In the Filters section, exclude a resource or resources 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. In the Parent Group field, 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 — Excludes any discovered resource with the same IP address as a resource that is already being monitored.
    • 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 with 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 with 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 NetScanon 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 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 Enhanced Script 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.

Viewing Resource Status Information

1. Navigate to Settings > NetScans > select the required NetScan for the enhanced script.
   
2. Select Scan History.
   You can view the resources added or updated in the Resource Status column.
   
3. Select the required NetScan.
   You can also view the status of the selected resource in the details panel.

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
lm.emit(resources)