Running Command Lines

Home  Previous  Next

Even though Monitoring Studio KM for PATROL offers a variety of monitoring methods (Monitors), there might be an in-house script or command that you need to run and analyze on a regular basis to monitor a specific technology.

The Command Line Monitor allows you to trigger the periodic execution of a specified command line on the targeted host. This command can be a shell command, a shell script or an executable file with arguments.

Once the Command Line Monitor is executed and its result displayed in the PATROL Console, you can define String Searches, Numeric Value Extractions and Value Map criteria to retrieve strings or numeric value from the result output.

Monitoring Studio enables you to create Command Line Monitors to execute the OS command/script on the local system where the PATROL Agent KM is installed through the Command Line: Local Execution Monitor; or if the command is run on the remote target, different from the PATROL Agent system, through the Command Line: Remote Execution Monitor.

To run a command line (Local Execution)

1.In the PATROL Console, right-click the Host or Monitor Group icon and select KM Commands > New > Monitor...
2.Select Command Line: Local Execution from the drop-down list and click Next.

Monitoring_Command_Line_1_local

Running Command Lines - Command Line Information  (Remote Execution)

3.Credentials: Select the credentials that you want to use to execute the command line:
Agent's Default Account: Uses the PATROL Agent credentials for localhost monitoring (Default).
System Credentials (default): Uses the credentials previously specified when creating the Host.
Add new credentials...: Lets you provide new credentials for the current command line instance. Refer to the Setting Credentials chapter for detailed information.
4.Enter the command line to execute:
Command line: Enter the command line or the path to the script that Monitoring Studio will execute. You can use the following macros in the command line that will be executed:
%{SEN_TIME:<date-time-format>}: Use this macro to insert the current date and time in the command line. You can specify the format of the date and time string that will be inserted, which follows UNIX asctime() format (%Y for year, %m for month, %D for day, %H for hours, %M for minutes, %S for seconds, etc.).
%{SEN_LASTTIME:<date-time-format>}: Use this macro to insert the date and time at which the command was last executed. This can be particularly useful when you need to specify a time range for the command, like listing events since the last time we checked. The format is the same as the UNIX asctime() format (%Y for year, %m for month, %D for day, %H for hours, %M for minutes, %S for seconds, etc.).

ImportantWhen using the %{SEN_LASTTIME:<date-time-format>} macro, the execution is skipped entirely the first time the Monitor runs (after the PATROL Agent starts). This is to ensure that an actual date and time is inserted with an actual value for this macro.

%{SEN_SCRIPTPATH:<local-script-path>}: Use this macro to copy a file stored on the PATROL Agent's system to the monitored host before the command is executed. When the command is executed, the macro is replaced by the path to the copied file on the targeted host. This is particularly useful to trigger the execution of scripts that are stored on the PATROL Agent's system without having to install these scripts on each monitored host. This macro is irrelevant when monitoring the localhost.

NoteThe %{SEN_SCRIPTPATH} macro should provide the script file path on the local Agent system.

ImportantThe %{SEN_SCRIPTPATH} macro does not support local environment variables (e.g., %PATROL_HOME%).

%{HOSTNAME}: This macro inserts the hostname of the targeted system, as specified in the host configuration (it may be an IP address, a FQDN or a short name).
%{USERNAME}: Use this macro to insert the username of the specified credentials in the command line to be executed.
%{PASSWORD}: Use this macro to insert the password of the specified credentials in the command line to be executed. The password is inserted in clear text.

WarningPasswords should never be sent in clear text. Passwords in command lines may be visible to non-root users. Use at your own risk.

Command launched once and runs continuously: Check this option if you want Monitoring Studio to automatically run the command line continuously without having to repeatedly relaunch it manually.
Click Next.
5.If you have enabled the Command launched once and runs continuously option, Monitoring Studio prompts you to confirm your choice:

WIZ_CommandLine_6NeverEndingCmd2

Running Command Lines - Confirmation Message

Click Yes, and configure the Command Termination settings:

Monitoring_Command_Line_2

Running Command Lines — Command Termination

(Optional) Termination command line: Enter a specific command that will be used to stop the execution of the never-ending command. This command runs when the command instance  is deleted from the PATROL configuration or when the Terminate at Agent restart option is selected. It is required to properly end the execution of the command.
Terminate at Agent restart: Select this option if you wish the never-ending command to be stopped upon the next PATROL Agent restart.
Click Next.
6.If you have not enabled the Command launched once and runs continuously option, configure the Command Execution Validation settings:

Monitoring_Command_Line_3

Running Command Lines — Command Execution Validation

7.Set the following Command Execution Validation options:
Timeout: Enter the time in seconds after which the command will be stopped (Default: 30 seconds). If the timeout is reached, the value of the Status parameter will be set to 2 (Failed), indicating that the command failed to execute properly. No further analysis will be performed (String or Numeric Value searches).
(Optional) Recovery Command: Click this button to type a command similar to a recovery/cleaning action that will be executed when the timeout is reached. The %{SEN_PID} macro can be used to indicate the PID of the command line process being interrupted.

Monitoring_Command_Line_4

Running Command Lines - Recovery Command

(Optional) Execution is validated when output contains: Enter the regular expression to be found in the command output that will confirm that the command is successful. The regular expression entered here will be searched in the output of the command. If it is not found, the value of the Status parameter will be set to 2 (Failed), indicating that the command failed to execute properly. No further analysis will be performed (String and Numeric Value searches).

TipThis option can be particularly useful to ensure that the command has been properly executed and avoid false alerts triggered by the associated String Search/Numeric Value Extraction when an error is encountered during the command execution. For example, if the specified command must print a text banner, you will want to make sure that the text banner is found in the command output instead of an error message).

Exit codes below mean the command execution: Select an execution option (succeeded/failed), to state if the command line was properly executed or not. When one of the exit codes is found or not found, depending on the option selected, the ExitStatus parameter of the Command Line monitor is automatically set to 1 (Failed) or 0 (Succeeded) indicating that the command failed or succeed to execute properly.
(Optional) Exit codes separated by commas: Enter one or several exit codes separated by commas. When one of the exit codes is found or not depending on the selected execution option, the ExitStatus parameter will be set to 1 (Failed) or 0 (Successful).

NoteThe ExitCode and ExitStatus parameters are deactivated for never-ending commands and commands for which no exit code is specified or when the exit code is ignored. Also, the ExecutionTime parameter is deactivated for never-ending command lines to avoid meaningless alerts (SEN_MS_COMMANDLINE).

Report execution errors in Group's CollectionErrorCount: Select this option to have the CollectionErrorCount parameter of the Group reflect possible alerts triggered upon the Command Line execution. The CollectionErrorCount parameter of the Group reports on the collection errors of any Monitor, associated to the Group, for which this option is available and selected, providing a global view of the collection errors for the whole Group.
8.Click Next.
9.Configure the Monitor settings.
10.Click Finish. The corresponding Command Line instance (Command Line: <Display Name>) is created in the PATROL Console. The collected parameters for Command Line Monitors are listed in the SEN_MS_COMMANDLINE chapter.

 

To run a command line (Remote Execution)

3.In the PATROL Console, right-click the Host or Monitor Group icon and select KM Commands > New > Monitor...
4.Select Command Line: Remote Execution from the drop-down list and click Next.

Monitoring_Command_Line_1_Remote

Running Command Lines - Command Line Information (Remote Execution)

5.Credentials: Select the type of credentials that you want to use to execute the command line:
System Credentials: Uses the credentials previously specified when creating the Host (Default).
Add new credentials...: Lets you provide new credentials for the current command line instance. Refer to the Setting Credentials chapter for detailed information.
6.Enter the command line to execute:
Command line: Enter the command line or the path to the script that Monitoring Studio will execute. You can use the following macros in the command line that will be executed:
%{SEN_TIME:<date-time-format>}: Use this macro to insert the current date and time in the command line. You can specify the format of the date and time string that will be inserted, which follows UNIX asctime() format (%Y for year, %m for month, %D for day, %H for hours, %M for minutes, %S for seconds, etc.).
%{SEN_LASTTIME:<date-time-format>}: Use this macro to insert the date and time at which the command was last executed. This can be particularly useful when you need to specify a time range for the command, like listing events since the last time we checked. The format is the same as the UNIX asctime() format (%Y for year, %m for month, %D for day, %H for hours, %M for minutes, %S for seconds, etc.).

ImportantWhen using the %{SEN_LASTTIME:<date-time-format>} macro, the execution is skipped entirely the first time the Monitor runs (after the PATROL Agent starts). This is to ensure that an actual date and time is inserted with an actual value for this macro.

%{SEN_SCRIPTPATH:<local-script-path>}: Use this macro to copy a file stored on the PATROL Agent's system to the monitored host before the command is executed. When the command is executed, the macro is replaced by the path to the copied file on the targeted host. This is particularly useful to trigger the execution of scripts that are stored on the PATROL Agent's system without having to install these scripts on each monitored host. This macro is irrelevant when monitoring the localhost.

NoteThe %{SEN_SCRIPTPATH} macro should provide the script file path on the local Agent system.

ImportantThe %{SEN_SCRIPTPATH} macro does not support local environment variables (e.g., %PATROL_HOME%).

%{HOSTNAME}: This macro inserts the hostname of the targeted system, as specified in the host configuration (it therefore may be an IP address, a FQDN or a short name).
%{USERNAME}: Use this macro to insert the username of the specified credentials in the command line to be executed.
%{PASSWORD}: Use this macro to insert the password of the specified credentials in the command line to be executed. The password is inserted in clear text.

WarningPasswords should never be sent in clear text. Passwords in command lines may be visible to non-root users. Use at your own risk.

7.Configure the settings for the Command Execution Validation:

Monitoring_Command_Line_3_Remote

Running Command Lines — Command Execution Validation

8.Set the following Command Execution Validation options:
Timeout: Enter the time in seconds after which the command will be stopped (Default: 30 seconds). If the timeout is reached, the value of the Status parameter will be set to 2 (Failed), indicating that the command failed to execute properly. No further analysis will be performed (String or Numeric Value searches).
(Optional) Execution is validated when output contains: Enter the regular expression that needs to match the command output for the command to be considered successful. The regular expression entered here will be searched in the output of the command. If it is not found, the value of the Status parameter will be set to 2 (Failed), indicating that the command failed to execute properly. No further analysis will be performed (String and Numeric Value searches).

TipThis option can be particularly useful to ensure that the command has been properly executed and avoid false alerts triggered by the associated String Search/Numeric Value Extraction when an error is encountered during the command execution. For example, if the specified command must print a text banner, you will want to make sure that the text banner is found in the command output instead of an error message).

Exit codes below mean the command execution: Select an execution option (succeeded/failed), to state if the command line was properly executed or not. When one of the exit codes is found or not found, depending on the option selected, the ExitStatus parameter of the Command Line monitor is automatically set to 1 (Failed) or 0 (Succeeded) indicating that the command failed or succeed to execute properly.
(Optional) Exit codes separated by commas: Enter one or several exit codes separated by commas. When one of the exit codes is found or not depending on the selected execution option, the ExitStatus parameter will be set to 1 (Failed) or 0 (Successful).
NoteThe ExitCode and ExitStatus parameters are deactivated for never-ending commands and commands for which no exit code is specified or when the exit code is ignored. Also, the ExecutionTime parameter  is deactivated for never-ending command lines to avoid meaningless alerts (SEN_MS_COMMANDLINE).
Report execution errors in Group's CollectionErrorCount: Select this option to have the CollectionErrorCount parameter of the Group reflect possible alerts triggered upon the Command Line execution. The CollectionErrorCount parameter of the Group reports on the collection errors of any Monitor, associated to the Group, for which this option is available and selected, providing a global view of the collection errors for the whole Group.
9.Click Next.
11.Configure the Monitor settings.
12.Click Finish. The corresponding Command Line instance (Command Line: <Display Name>) is created in the PATROL Console. The collected parameters for Command Line Monitors are listed in the SEN_MS_COMMANDLINE chapter.