Page History

...

The first section of the XML file contains details about the name of the plugin/service monitor and which category its shows up under on the Add Service Monitor screen.

<?xml version="1.0" encoding="UTF-8"?>
<uptime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.uptimesoftware.com
/erdc/erdc erdc" xmlns="http://www.uptimesoftware.com/erdc/erdc" xmlns:upt="http://www.uptimesoftware.com/erdc
/erdc" version="4.0" target_grouping="other">
     <class>Custom Remote Monitor</class>
     <exec>com.uptimesoftware.uptime.erdc.MonitorCustomScriptRunner</exec>
     <erdc_version>3.01</erdc_version>
     <category>Advanced and Script Monitors</category>
     <category_related>Applications - General</category_related>
     <grid_info>
          <supported_versions>7.3</supported_versions>
          <supported_platforms>windows, linux</supported_platforms>
          <upgrade_in_place>true</upgrade_in_place>
          <requires_agent_scripts>false</requires_agent_scripts>
     </grid_info>

Let's talk about each of these tags, and what they represent:

• <class>

...

• . This is the service monitor's name as seen on the 'Add Service Monitor' screen in the Uptime Infrastructure Monitor GUI.
• <exec>

...

• . This tells Uptime Infrastructure Monitor that our plugin is a

...

• MonitorScriptRunner. There are also java type plugins, but this doc will only focus on Custom Scripts.
• <erdc_version>

...

• . This is the version number of the plugin which is used to identify when new versions are available.

...

• <category>

...

• . This is the primary category on the 'Add Service Monitor' screen where you'll be able to find this monitor.
• <category_related>

...

• . This is a secondary category where the monitor will be displayed in the 'Related Monitors' list.

...

• The <grid_info> section outlines details about which OS platforms this monitor can run on, as well as which versions of Uptime Infrastructure Monitor. Which is used by the Extension Manager to filter which plugins to show as available for installed.
  • <supported_versions>

...

• • . This is the version of Uptime Infrastructure Monitor monitoring station this plugin is compatible with.
  • <supported_platforms>

...

• • . This is a list of which monitoring station platform a monitor can run on. This can either windows or linux, or both like in the example above.
  • <upgrade_in_place>

...

• • . This tells Uptime Infrastructure Monitor that the plugin can be updated without having to re-define the services monitors assigned to it. In most cases you'll want to set this to true.

Next comes the elements section of the XML file. This is a list of element tags which define the input and output variables you see when editing a service monitor in the Uptime Infrastructure Monitor GUI. The contents of these variables are stored in the Uptime Infrastructure Monitor datastore just like regular service monitors.

...

The first of these elements are the the process_linux & process_windows which control which script actually gets run on the monitoring station when a service monitor is triggered.

...

<elements>
     <element name="process_linux" parameter_type="input" data_type="string" gui_basic="1" range_type="0" hidden="true">

...

            <control_options> size:40 </control_options>

...

            <default_value>plugins/scripts/monitor-custom-remote/monitor-custom-remote.sh<

...

/default_value>

...

            <short_description>Script Name</short_description>

...

            <long_description>Name of the script/binary/process to be executed by up.time <

...

/long_description>

...

            <validation_rule>

...

                  <alphanumeric/>

...

            </validation_rule>

...

            <error_message>

...

                  <alphanumeric>required field</alphanumeric>
            </error_message>

...

            <gui_type>

...

                  <string/>

...

            </gui

...

_type>
      </element>

...

      <element name="process_windows" parameter_type="input" data_type="string" gui_basic="1" range_type="0" hidden="true">

...

            <control_options> size:40 </control_options>

...

            <default_value>plugins/scripts/monitor-custom-remote/monitor-custom-remote.bat<

...

/default_value>

...

            <short_description>Script Name</short_description>

...

            <long_description>Name of the script/binary/process to be executed by up.time <

...

/long_description>

...

            <validation_rule>

...

                  <alphanumeric/>

...

            </validation_rule>

...

            <error_message>
                  <alphanumeric>required field</alphanumeric>
            </error_message>

...

            <gui_type>

...

                  <string/>

...

            </gui_type>

...

      </element>

Full details about what the various attributes of the XML file's element tag control are available here: 'Integration Guide - > Plugin Guide'. But for now, we'll just cover the most important details from the example above:

• name

...

• . This is the name of variable itself. In the examples above, you can see this is either set

...

• to process_windows or process_linux. You need to have at least one of these defined for every plugin.
• parameter_type

...

• . This can be either input or output. Input parameters will be set as an environment variable at run time. We'll talk more about output type parameters below.
• data_type

...

• . This can be either string or integer. This usually more important on the output variable side of things, as it also controls what WARN

...

• /CRIT threshold comparisons can made against it.
• hidden

...

• . This can either be true or false . This controls whether or not a parameter is displayed on the Edit Service Monitor Screen. A hidden variable can not be edited by a user in the GUI, but can still be updated in the

...

• database directly.
• <default_value>

...

• . This provides the default value for a variable. Which is especially important for the examples above, as both are set as hidden and are not editable from the GUI.

Now that we've looked at the process_windows and or process_linux fields, let's take a look at some 'input' variables for this monitor. If your familiar with the 'Custom Remote Monitor' in Uptime Infrastructure Monitor, you've likely seen this combination of Agent Port, Agent Password, Remote Script fields before, as these are commonly used to trigger custom agent scripts.

• We can see the 'Agent Port' parameter is setup as type integer, and has the default port 9998 already set for us.
• The password parameter is setup as a data_type of string, but also has the gui_type set to <password /> which as mentioned above, tells Uptime Infrastructure Monitor to encrypt this value when it's stored in the database, as well as blank out the field itself when displayed in the GUI.
• The remote_script & args fields are both

...

• set up as basic string fields with nothing special about them. 

<element name='port' parameter_type='input' data_type='integer' 
gui_basic='1' range_type='0' units=''>

...

     <control_options>size:8</control_options>

...

      <default_value>9998</default_value>

...

      <short_description>Agent Port</short_description>

...

      <long_description>up.time Agent Port (default is 9998)</long_description>

...

      <validation_rule/>

...

      <error_message/>
      <gui_type>
            <integer/>
      </gui_type>

...

</element>

...

<element name='password' parameter_type='input' data_type='string' 
gui_basic='1' range_type='0' units=''>

...

      <control_options>size:8</control_options>

...

      <default_value></default_value>

...

      <short_description>up.time Agent Password</short_description>

...

      <long_description>Password setup on the agent system</long_description>

...

      <validation_rule/>

...

      <error_message/>

...

      <gui_type>

...

            <password/>

...

      </gui_type>

...

</element>

...

<element name='remote_script' parameter_type='input' data_type='string' 
gui_basic='1' range_type='0' units=''>

...

      <control_options>size:8</control_options>

...

      <default_value></default_value>

...

      <short_description>Remote Script / Command</short_

...

description>
      <long_description>Script name (posix) or command (win) setup on the agent<

...

/long_description>

...

      <validation_rule/>

...

      <error_message/>

...

      <gui_type>

...

            <string/>

...

      </gui_type>

...

</element>

...

<element name='args' parameter_type='input' data_type='string' 
gui_basic='1' range_type='0' units=''>

...

      <control_options>size:8</

...

control_options>
      <default_value></default_value>

...

      <short_description>Arguments</short_description>

...

      <long_description>Arguments that will be sent to the remote script</long_description>

...

      <validation_rule/>

...

      <error_message/>

...

      <gui_type>

...

            <string/>

...

      </gui_type>

...

</element>

Editing the Service Monitor view

Now that we've talked about the details that go into a plugin's XML file, let's take a look at how these input variables are displayed in the Uptime Infrastructure Monitor GUI when creating an instance of the 'Custom Remote Monitor':

• The first thing you'll notice is that we don't see either the process_windows or process_linux fields, but that's to be expected here, as those fields where set as hidden.
• The contents of the password field are obscured as expected. 
• The Remote Script & Arguments fields are basic string fields.
• You can also see the two output values for this monitor, but we'll talk about those more later. 

Environment variables

Next let's take a look at how all these parameters and input fields come together as the environment variables that are used by the script itself. Environment variables aren't normally/displayed or retained by the service monitor when it runs, but they're easy to capture for testing/debugging purposes by adding the appropriate command to your shell/bat script:
Linux: printenv > /var/tmp/envvars.txt
Windows set > C:\envvars.txt 
There's normally plenty of other environment variables that are set, but we've filtered those out to only look at the uptime values that are coming from our service monitor's XML definition.
UPTIME_ARGS=test-args UPTIME_TIMEOUT=60 UPTIME_SYSTEM_TYPE=NODE UPTIME_PORT=9998
UPTIME_PROCESS_WINDOWS=plugins/scripts/monitor-custom-remote/monitor-custom-remote.bat UPTIME_PROCESS_LINUX=plugins/scripts/monitor-custom-remote/monitor-custom-remote.sh UPTIME_REMOTE_SCRIPT=test-script
UPTIME_HOSTNAME=cat1.uptimesoftware.com UPTIME_PASSWORD=test-pass
Here's a few things you should notice about these:
They all start with UPTIME_ and the contents of the name attribute from the element tag. 

...

Now let's take a quick look at what the custom_remote.bat & custom_remote.sh scripts actually do with these environment variables. As mentioned above, most of the Uptime Infrastructure Monitor provided plugins rely on a common PHP script to perform the actual task of monitoring. As such the bat & sh scripts are just responsible for telling Uptime Infrastructure Monitor's bundled php executable to run the required script, pass along the environment variables in the correct order. The specifics of how this done obviously varies between both Windows and Linux, so let's take a look at both methods.
See monitor-custom-remote.bat on GitHub:
@echo off
..\..\..\apache\php\php.exe rcs.php -h=%UPTIME_HOSTNAME% -p=%UPTIME_PORT% -s=%UPTIME_PASSWORD% -c=% UPTIME_REMOTE_SCRIPT% -a=%UPTIME_ARGS%
From the example here, you can see that windows allows you access environment variables by wrapping the name in % characters, ie % UPTIME_HOSTNAME% . So we've used that to arrange the input variables from xml into the order expected by the rcs.php script. You may also notice the .
.\..\..\apache\php\php.exe path used to start php. Whenever a script monitor is triggered the current working directory is set to the location of the
script itself, which is in this case is 'C:\Program Files\uptime software\uptime\plugins\scripts\monitor-custom-remote\monitor- custom-remote.bat' But the location of the uptime directory can vary depending on where it was initially installed. So we use a relative path from the plugin's location to find <uptime_dir>\apache\php\php.exe . When making your own plugins, you can usually simplify this by using the hardcoded path of your uptime directory.

See monitor-custom-remote.sh on GitHub:
#!/bin/sh

inst=`grep ^inst /etc/init.d/uptime_httpd | cut -d= -f2` MIBDIRS=$inst/mibs
export MIBDIRS

/usr/local/uptime/apache/bin/php rcs.php -h=$UPTIME_HOSTNAME -p=$UPTIME_PORT -s=$UPTIME_PASSWORD - c=$UPTIME_REMOTE_SCRIPT -a=$UPTIME_ARGS
In the case of the linux shell script, we can access the contents of our environment variables by prefacing the name with the $ symbol. We then pass the same input variables along to php in the same order as in the bat script above. Just like on Windows the current working directly is set to the location of plugin script itself, but in this case we can use the contents of the /etc/init.d/uptime_httpd script to find the location the Uptime Infrastructure Monitor install directory and use to that to set the location of an extra MIBDIRS environment. This only required for PHP scripts on linux, so that the php_snmp library doesn't complain about being unable to find it's mibdirs. If your not using php in your own script, you can ignore this completely. The other thing worth noticing here is that we've hardcoded the path of Uptime Infrastructure Monitor's bundled php executable, as uptime's Apache folder is always installed into the default location of /usr/local/uptime/apache even if Uptime Infrastructure Monitor was installed elsewhere, this prevents us from using the same relative path method as we did on Windows.
We won't get into the details of the rcs.php script itself as this will typically change depending on the details of the plugin itself. But the full contents of this file on GitHub  here GitHub here if your you are interested.

Output variables

...