<tool> Section

Use the <tool> section of a command-line probe to embed a script code directly into a command-line probe. The <tool> section provides a convenient way to maintain the probe and the script in a single file.

<tool:scriptname>
  [script code]
</tool:scriptname>

Replace scriptname with the executable you want to use for the script.

Replace [script code] with the code of the script.

What happens when you load a probe with a <tool> section?

When the Intermapper server starts or when you import or reload a probe, if a tool section appears for a probe, Intermapper a subdirectory of Tools is created with the canonical name of the probe and writes the script to that subdirectory, using scriptname as the file name.

If a subdirectory of that name already exists, all non-hidden files are deleted before the script is writtern. For this reason, you should not edit scripts directly in the subdirectories of the Tools directory, since they are overwritten when probes are reloaded.

For example, given the example of a command-line probe where the canonical name is com.dartware.cmdline.test, where the cmd clause in the <command-line> section is as follows:

cmd="python test.py"

or, using the ${PYTHON} macro:

cmd="${PYTHON}  test.py"

and the tool section is as follows:

<tool:test.py>

  # Trivial example
  
  print (“okay”)
  sys.exit(0)

</tool:test.py>

When Intermapper starts or reloads probes, a subdirectory of Tools named com.dartware.cmdline.test is created if it does not exist, and (in this case) a file named test.py is written into it, containing the text between <tool:test.py> and </tool:test.py>.

WMI probes provide a number of good examples of this feature.

Calling External Scripts and Other Executables

While using the <tool> section is recommended, it is optional. You can call an external script or other executable by providing the correct path to it in the cmd property of the <command-line> section of the probe. If you provide a path to multiple directories in the path parameter, Intermapper looks in the specified directories for the executable. The <tool> section is appropriate only for scripts, not for compiled programs.

Python Example

<!--
check_connect (com.dartware.commandline.check_connect.txt)
Copyright© Fortra, LLC. All rights reserved.

1.2  22 Mar 2021 Convert Python2 to Python3 -Jerry
-->

<header>
          type = "cmd-line"
          package = "com.dartware"
          probe_name = "commandline.check_connect"
          human_name = "Check Connect"
          version = "1.2"
          address_type = "IP"
          display_name = "Miscellaneous/Test/Check Connect"
</header>

<description>
\GB\Check for connect\p\

This probe checks to see if you can connect to the given address and port.
</description>

<parameters>
"CHECK_PORT" = "80"
</parameters>

<command-line>
          cmd=${PYTHON}
          arg="check_connect.py ${ADDRESS} ${CHECK_PORT}"
</command-line>

<command-data>
-- Currently unused.
</command-data>

<command-exit>
           -- These are the exit codes used by Nagios plugins
           down: ${EXIT_CODE}=4
           critical: ${EXIT_CODE}=3
           alarm: ${EXIT_CODE}=2
           warn: ${EXIT_CODE}=1
           okay: ${EXIT_CODE}=0
</command-exit>

<command-display>
</command-display>

<tool:check_connect.py>
import sys
import socket

# constant return codes for Intermapper
OKAY = 0
WARNING = 1
ALARM = 2
CRITICAL = 3
DOWN = 4

retcode = OKAY
output = ""

try: 
          host = sys.argv[1] # The remote host  
          port = int(sys.argv[2]) # The port
except:
          print("Usage: check_connect HOST PORT")
          sys.exit(DOWN)

try:
          s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
          s.connect((host, port))
          s.close()
except IOError as e:
          retcode = DOWN
          if hasattr(e, 'reason'):
                      reason = 'Reason: ' + e.reason
          elif hasattr(e, 'code'):
                      reason = str(e.code)
          else:
                      reason = "unknown"
          output = "Error (" + reason + ") connecting to " + str (host) + ":" + str(port)

print(output)
sys.exit(retcode)
</tool:check_connect.py>

Cscript Example

<!-- 
Check Web 
Copyright© Fortra, LLC. All rights reserved. 
--> 

<header> 
  type = "cmd-line" 
  package = "com.dartware" 
  probe_name = "commandline.check_web" 
  human_name = "Check Web" 
  version = "1.1" 
  address_type = "IP" 
  display_name = "Miscellaneous/Test/Check Web" 
visible_in = "Windows" 
</header> 

<description> 
  \GB\Check Web\p\ 
  
  Given an address or hostname, attempts to connect to a web server. 
</description> 

<parameters> 
</parameters> 


<command-line> 
  -- Empty path forces the Intermapper Settings:Tools directory 
  path= 
  cmd="${CSCRIPT} check_web.vbs" 
  arg="${address}" 
  timeout = ${Timeout (sec)} 
</command-line> 

<command-data> 
  -- Currently unused. 
</command-data> 

<command-exit> 
  down:${EXIT_CODE}=4 
  critical:${EXIT_CODE}=3 
  alarm:${EXIT_CODE}=2 
  warning: ${EXIT_CODE} = 1 
  okay:${EXIT_CODE}=0 
</command-exit> 

<command-display> 
  ${^stdout} 
</command-display> 

<tool:check_web.vbs> 
  Dim web 
  Set web = Nothing 
  Set web = CreateObject("WinHttp.WinHttpRequest.5.1") 
  
  numargs = wscript.arguments.count 
  If (numargs < 1) Then 
  wscript.Echo "Usage: check_web hostname" 
  wscript.quit(4) 
  End If 
  
  URL = "http://" + wscript.arguments(0) 
  
  on error resume next 
  web.Open "GET", URL, False 
  on error resume next 
  web.Send 
  If err.Number <> 0 Then 
  returncode = 4 
  Else 
  If err.Number = 0 and web.Status = "200" Then 
  returncode = 0 
  Else 
  returncode = 4 
  End If 
  End If 
  
  If returncode <> 0 Then 
  wscript.Echo "Error connecting to " + URL +"." 
  Else 
  wscript.Echo "" 
  End If 
  wscript.quit(returncode) 
</tool:check_web.vbs>