External Process monitor

The External Process monitor launches an external program or script. It can also launch a script using an executable program, such as a PuTTY link (plink.exe) or a Windows script (cscript.exe). Any required command line parameters can be passed to the third party executable on startup.

The External Process monitor supports the Process Return Value and Environmental Variable modes of operation. In the Process Return Value mode, the third-party executable reports an exit code to the ipMonitor using a numeric value. In the Environment Variable mode, the third-party executable sets the value of an environment variable to be read only by the monitor.

When configured using Process Return Value mode, the test passes if:

• The program finishes executing within the Maximum Test Duration timeout interval
• The exit code returned matches the Expected Return Value

When configured using Environment Variable mode, the test passes if:

• The program finishes executing within the Maximum Test Duration timeout interval
• The monitor was able to read the Environment Variable in question and determined that its value is correct

Administrators can use the External Process monitor to simplify routine or repetitive tasks and create custom monitors to work with ipMonitor.

Create an External Process monitor

1. Click Devices in the toolbar.
2. Locate and click the targeted device you want to monitor.

3. In the toolbar, click Add > Add New Monitor.

4. In the menu, click External Process.

5. Complete the fields in the Identification section.

   

   1. Under Identification, enter a monitor name using up to 64 characters.

      This name will appear in the Monitors List, Monitor Status, Logs pages, and your reports.

      You can change this name later, if necessary. ipMonitor does not use this field to internally identify this monitor.

   2. Select Enabled to enable the monitor.

      When enabled, the monitor tests the specified resource using the settings you enter under Test Parameters. You can disable the monitor later if required.

   3. (Optional) Select Store Monitor Statistics for Recent Activity and Historical Reports to enable this functionality.

6. Complete the fields in the Test Parameters section.

   This section specifies the location of the executable or script and its associated parameters.

   

   1. In the Executable Name field, enter the name of the file or script that this monitor will execute.

   2. In the Directory field, enter the Local or UNC path to the file.

      An example UNC path would be \\ServerName\ShareName.

      An example of a local path would be C:\\Windows\.

   3. In the Command Line Parameters field, enter the application variables or command line switches used to pass specific data to the program.

      For example, if the monitor were running Windows Cscript.exe, you could use the following switches:

      • //B - specifies batch mode to prevent alerts, scripting errors, and input prompts.
      • //T:nn - specifies the maximum time (in seconds) the script can run.

   4. In the Startup Directory field, enter a fully qualified local file path to the directory where the third-party executable will run. For example, C:\scripts\.

      Even though the file or script is located in another directory, the start-up directory security permissions control the behavior of the third-party executable or script. Any passed command line parameters must relate to the start-up directory where the script or executable is launched, and not where the script or executable is located.

   5. (Optional) Click Select and assign a credential. When the monitor runs the executable file, it will use the credential account and password combination to authenticate to the machine, directory, or file.

      To create a new credential, click New Credential and complete the wizard.

   6. (Optional) Click Enable and enter the environmental variables.

7. Complete the fields and options in the Analysis of Test Results section.

   

   1. Select the appropriate mode.
   2. Enter the expected return value.

8. Under Timing, configure the fields for the monitor testing states.

   

   1. In the Maximum Test Duration field, enter the maximum test duration rate (in seconds) that the monitor times out before the test is considered a failure.

   2. In the remaining fields, enter the number of second between each test while the monitor is in an OK state (Up), a failed state while alerts are processed (Down), and a failed state and the maximum number of alerts have been processed (Lost).

      In the Lost state, no additional failure alerts are processed. However, a recovery notification is sent if the monitor recovers.

9. Enter the amount of time delay for each monitor testing state. For example, you may choose to intensify testing when a monitor enters a Warn state and reduce testing when the monitor enters a Lost state.

10. Under Notification Control, complete the fields to determine how many test failures must occur before an alert is sent.

    

    1. Enter the number of test failures that occur for each alert before ipMonitor generates an alert for the monitor. The default option is 3.

    2. Enter the maximum number of alerts to send before the monitor enters a Lost state.

       The monitor must be assigned to a notification alert to generate an action.

11. Under Recovery Parameters, complete the fields to indicate the corrective action used to automatically restore a resource using the External Process Recovery, Reboot Server Recovery, or Restart Service Recovery action.

    

    1. Enter the Fully Qualified Domain Name (FQDN), NetBIOS, or IP Address of the machine hosting the service that needs a restart or the machine that needs a restart. You can also click Browse to locate and select the machine.
    2. Select the set of credentials used by the recovery alert. You can select a specific credential to execute recovery alerts that require access to restricted resources, such as Reboot Server, Restart Service, or External Process.
    3. Select the list of services to restart on the target machine specified in the FQDN/NetBIOS/IP Address field. This field is only required for the Restart Service alert. If a service has dependencies, select all dependent services.
12. Click OK.

Analysis of test results

The External Process monitor supports two modes of operation:

• Analyze a Process Return Value
• Analyze an Environment Variable

Process Return Value

The third-party executable reports an exit code to the ipMonitor process in the form of a numeric value.

When you create the third-party executable or script, design it so it produces an exit code when it shuts down.

Although exit codes can be any number you choose in your program design, 0 is a standard success exit code used when an executable returns the expected value.

For example, if the target log file did not exist, the exit code 1 is returned to the ipMonitor process. This result does not match the Expected Return Value, causing the External Process monitor test to fail.

Alternatively, if exit code 0 is returned, the result matches and the External Process monitor continues in an Up state.

Environment Variable

The third-party executable sets the value of an Environment Variable, which is subsequently read by the External Process monitor.

Use Environment Variables when the content must contain file paths or special characters, such as less than ( < ) or greater than ( > ) symbols.

After setting the Environment Variable value, the third-party executable or script calls signal_env.exe for the variable to be available to the ipMonitor process.

The signal_env.exe tool is located in the root folder of the ipMonitor installation. These steps describe how signal_env.exe works:

1. The monitored application or script runs.
2. During execution, the application sets the necessary Environment Variable and calls signal_env.exe.
3. The External Process monitor reads the Environment Variable and performs a comparison based on the monitor configuration.

In the following example, ipMonitor expects the result to be successful for the test to pass. Any other text string will cause the test to fail. This example illustrates the third-party executable or script environment.

In this example, the ipMonitor executable is running under the IPM account. A credential named LOG was created to impersonate an account with the necessary permissions. ipMonitor impersonates the LOG account to run the third-party program. When the third-party executable runs, it calls signal_env.exe to communicate back to ipMonitor that was run under the LOG account context. As a result, ipMonitor retrieves the LOG environment variables for comparison.

In the supported Windows operating systems, environment variables are grouped internally into four variable categories, as described below.

Category	Description
System	Defines the behavior of the global operating system environment. These variables apply to all machine users and are recorded in the registry at HKLM\System\CurrentControlSet\Control\Session Manager\Environment.
Process	Defines the environment in which a process runs. These apply to the current process, and may be passed on to child processes. These are not stored in the registry. ipMonitor can only set the PROCESS Environment variables to launch a script or executable through the External Process monitor or External Process alert.
User	Only available when the user is logged in to the machine. Local variables set in the HKEY_CURRENT_USER hive are valid only for the current user. These are recorded in the registry in the registry at HKEY_CURRENT_USER\Environment.
Volatile	Created during login script execution. These apply to the current login session and are recorded in the registry at HKCU\VolatileEnvironment.

You can configure the External Process monitor to determine the test success or failure by reading a Process environment variable rather than basing its status on the script or the executable exit code.

If the third party executable or script fails to finish within the Maximum Test Duration interval, ipMonitor terminates the process.

SolarWinds recommends that the third-party executable be located on the same machine that hosts ipMonitor. The third-party executable or script runs in the memory space and environment of the ipMonitor host machine. Even if it is called across the network using a UNC path, it still runs locally.

Test results

The test results include return, which is the numeric exit code reported by the third-party executable.