Page History
...
The built-in agent authentication protocol provides a quick and easy way for you to have the Uptime Infrastructure Monitor agent run commands (or any application) on your agent-side system without the fear of unknown users being able to execute the same commands. The output from the agent-side commands will be returned to the monitoring station custom script for parsing. This enables you to create a script that can monitor many different agent systems without duplicating the script many times. The following diagram illustrates the custom service monitor process:
Step 1: Creating the agent side script
When designing a custom service monitor, you should consider what information that you want the monitor to collect. For example:
- If you want to monitor the status of an application, you should first create a command line script or utility (or using an existing one) that returns the general status of a service that is on the agent system.
- If you want to gather performance metrics, ensure that the script to return a series of performance indicators to the console, otherwise simple output a message that can later be used to validate the status of the service or application.
Once you have written your agent-side script, you will need to configure your Uptime Infrastructure Monitor agent to execute it. As a minimum, you must configure the following settings for each agent-side command:
- For agents running on non-Windows systems, define a password and command pair in the agent-side password file.
- For agents running on Windows, set a password via the Agent Console.
- Verify that the agent-side command permissions allow the execution of the command by the user that the agent is run as. If the commands within your script require additional system permissions, you may have to alter the security settings for the execution of the agent.
For the purpose of this example, lets assume that we have designed an agent side script that returns information about the temperature and humidity levels around a given agent system. If we were to run this agent side script from the command line it would be executed as follows:
| Info |
|---|
These example commands are formatted for non-Windows systems. The command format is very similar on Windows systems, but require minor syntax and path changes. |
...
| Code Block | ||
|---|---|---|
| ||
su - uptime
$ |
...
/opt/uptime-agent/my-scripts/show_temp.sh temp 74 |
...
rh 30 |
To define your password and command pair on a non-Windows agent system, do the following:
- Ensure that a file named .uptmpasswd is created in the Uptime Infrastructure Monitor agent bin directory – either /opt/SPYNuptm/bin/ or /
...
- opt/uptime-agent/bin, depending the version of your agent. This file must be owned and readable by the user that the agent is run as (ex. uptimeagent or uptime users).
- Open the file .uptmpasswd in a text editor.
- Enter a password and command pair for each command that you want to run on the agent system. The following is the example format and an example of a agent-side commands:
...
...
- Format
...
- :
...
- [password
...
- ]
...
- [command
...
- path,
...
- no
...
- arguments
...
- ]
- Example file contents:
secretpassword /opt/uptime-agent/my-scripts/show_temp.sh
...
On the Custom Scripts screen, you should see an example similar to:
Custom Command: dir
Path to Script: cmd.exe /c "dir c:"
To continue this show-temp example, set the parameters to something similar to:
Custom Command: temp
Path to Script: cmd.exe /c "C:scriptsshow_temp.pl" (note: make sure to click Add/Edit before closing the window, otherwise your command will not be saved).
If you haven't done so yet, click Save, and Yes when asked to restart the agent. This will ensure that your new settings take effect.
The
...
following
...
is
...
a
...
sample
...
configuration.
...
Note
...
the
...
additional
...
folder
...
named
...
rexec_commands,
...
which
...
contains
...
a
...
key/value
...
pair
...
of
...
the
...
command
...
key.
...
!worddav81a2f5861b9291cc8f3c6eaa1054bb9b.png|height=16,width=16!
...
<span
...
style="color:
...
#333333"><strong>Note</strong></span>
...
<span
...
style="color:
...
#333333">If
...
any
...
changes
...
are
...
made
...
to
...
the
...
Windows
...
agent
...
registry
...
please
...
restart
...
the
...
"up.time
...
agent"
...
service
...
to
...
see
...
these
...
changes
...
take
...
effect.</span>\[HKEY_LOCAL_MACHINE\SOFTWARE\uptime
...
software\up.time
...
agent\]
...
"CmdsTimeout"=dword:00000014
...
\\
...
\\
...
"Port"=dword:0000270e
...
"MaxClients"=dword:00000005
...
"Debug"=dword:00000000
...
"CmdsPassword"="secretpassword"
...
"LogFile"="log.txt"
...
\\
...
\[HKEY_LOCAL_MACHINE\SOFTWARE\uptime
...
software\up.time
...
agent\rexec_commands\]
...
"dir"=
...
cmd.exe
...
/c
...
"dir
...
c:"
...
"show-temp"=
...
cmd.exe
...
/c
...
"C:\scripts\show_temp.pl"
...
\\
...
\\
| Anchor | ||||
|---|---|---|---|---|
|
...
- The script must return at least one line of output to the system console. Uptime Infrastructure Monitor will use this output to determine the status of the custom service monitor.
- The script must exit with a success status, unless there has been a problem during the execution of the script or you want to force a status for the service monitor. Acceptable return codes are:
exit 0 - The script executed without any errors, all output produced from the script will be parsed by Uptime Infrastructure Monitor to determine the service monitor status.
exit 1 - The service monitor status will be set to WNG (warning) and an outage will be recorded. The console output from the script will be placed in the custom service monitor status message.
exit 2 - The service monitor status will be set to CRIT (critical) and an outage will be recorded. The console output from the script will be placed in the custom service monitor status message.
...
echo -n rexec secretpassword /opt/uptime-agent/my-scripts/show_temp.sh my-arguments | /usr/local/uptime
/bin/netcat my-agent 9998
Note
The 'rexec' text below does not indicate use of the 'rexec' system utility, it is simply a key word used to indicate to the agent that you are attempting to run a predefined command.
You will normally use netcat or agentcmd in the monitoring station script to return the results of an agent-side script, validate the status of those results, and return the status to Uptime Infrastructure Monitor. The following is an example of a monitoring station script:
#!/bin/sh
- This script takes the following arguments:
Wiki Markup check_temp.sh hostname port \[temp|rh\] wng crit # Example execution:
- ./check_temp.sh my-agent 9998 temp 60 80
- ./check_temp.sh my-agent 9998 rh 20 30
- This script can be placed anywhere on the monitoring station system as long as it is # executable by the uptime user.
#First, collect our arguments AGENT=$1
PORT=$2 TYPE=$3 WNG=$4 CRIT=$5
TMPFILE=/tmp/$$.temp Wiki Markup now use the info above to contact our agent, store the output in a file for parsing `echo -n rexec secretpassword /opt/uptime-agent/my-scripts/show_temp.sh my-arguments | /usr/local/uptime4/bin /netcat $AGENT $PORT > $TMPFILE` !worddav81a2f5861b9291cc8f3c6eaa1054bb9b.png|height=16,width=16! <span style="color: #333333"><strong>Note</strong></span> <span style="color: #333333">The syntax to use agentcmd is different than netcat. When using agentcmd, the above netcat example would like this:</span>'/usr/local/uptime/scripts/agentcmd my-agent -p 9998 rexec secretpassword /opt/uptime-agent/my-scripts /show_temp.sh my-arguments > $TMPFILE'# we have the output from the agent. If it is ERR that means there was a problem running the script on the agent `grep ERR $TMPFILE` if \[ $? -eq 0 \] then echo "Could not execute agent side script!"
Wiki Markup by exiting with a 2 we are forcing a CRIT service outage exit 2 fi# given our parameters we can now extract the correct value from the agent output if \[ $TYPE -eq "temp" \] then VALUE=`head -1 $TMPFILE | awk '\{print $2\}'` MSG="temperature" else VALUE=`tail -1 $TMPFILE | awk '\{print $2\}'` MSG="humidity" fi# now lets check our values to see if they are over the thresholds and set our status message RET="OK - $msg is $VALUE on $AGENT" \\ if \[ $VALUE -ge "$WNG" \] \\ \\ \\ \\ \\ \\ then- this is our warning message
Wiki Markup include WARNING for use in the web interface thresholds RET="WARNING - $MSG is $VALUE on $AGENT" fi if \[ $VALUE -ge "$CRIT" \] then
- this is our critical message
- include CRITICAL for use in the web interface thresholds echo "CRITICAL - $MSG is $VALUE on $AGENT"
fi - here we simply print our status message to the console and exit with a 0,
- the thresholds provided in the up.time web interface will be used to set the monitor status rm $TMPFILE
echo "$RET" exit 0
Step 3 - Adding your Custom Service Monitor to Uptime Infrastructure MonitorThe next step is to add a custom service monitor to the Uptime Infrastructure Monitor Web interface using the same process that you would use to add a standard custom service monitor to Uptime Infrastructure Monitor. The Custom monitor option is found in the List Other Monitors section of the Add New Service Instance page..Anchor _bookmark28 _bookmark28
The Custom service monitor template has the following monitor specific settings available:Based on the settings used in the example monitoring station script, configure the monitor with the following setting:Op tio n Na me
Description
Example
Scr ipt Na me
The script name is the path to your monitoring station script, this is the script that Uptime Infrastructure Monitor will execute when running this service monitor. Be sure to use the complete path wherever possible and that the path is to a locally mounted volume. For Windows script paths you must use UNIX style directory separators (/ instead of ) and also place double quotes around the entire script name
UNIX
/Linux Example:/usr/local
/uptime
/check_t emp.shWindows Example:
"C:/my scripts
/check_t emp.bat"Arg um ents
These are the arguments that you would like Uptime Infrastructure Monitor to pass into your monitoring station script. No arguments are required but please be aware that Uptime Infrastructure Monitor will automatically include the selected hostname as the first argument to your script.
temp 60
80Out
This is the warning threshold used against the output returned from your monitoring station script. This is a textual comparison. You
Output
put
must select both a comparison method and a search string to enable the warning level threshold
contains:
Wa
"warning"
rni
ng
Out
This is the critical threshold used against the output returned from your monitoring station script. This is a textual comparison. You
Output
put
must select both a comparison method and a search string to enable the critical level threshold
contains:
Crit
"critical"
ical
Enter a name and description for the monitor. Select a host from the dropdown menu. Be sure to select the same host that your agent side script is on In the Script Name field, enter the path to the custom script on your monitoring station. On Windows systems be sure to use UNIX style / instead of \ and put quotation marks around your path. For example: "C:/my files/check_temp.bat" In the Arguments field, enter the arguments for the script. Uptime Infrastructure Monitor adds the agent name as the first argument automatically so do not include it. Select contains from the Warning dropdown and enter WARNING as the search text.
Select contains from the Critical drop down and enter CRITICAL as the search text. Complete the remainder of the monitor template as you would for a normal service monitor.
Example monitor configuration
The image below illustrates a sample monitor configuration. This service monitor will indicate a WARN or CRIT whenever the monitoring station custom script returns WARNING or CRITICAL in its output.