Opsview Knowledge Center

Variables

Overview of Variables in Opsview Monitor

This section provides an overview of variables: what they are, how to use them and how they work.

What are Variables and How Do They Work?

This document explains the concept of variables, explaining what a variable is, how to configure a variable, how to configure 'multiple service checks' and more.

After reading this User Guide, Users should be able to create their own variables, variable-based Service Checks, add variables to a host and use the 'multiple service checks' feature of Opsview Monitor.

'Variables' within Opsview Monitor act very similar to variables within well-known software languages. To understand the benefit of variables, readers must first understand the scenario that requires them.

With Nagios © / Monitoring plugin-based service checks, the syntax is two-part:

<plugin> <arguments>

Using a plugin of 'check_nrpe' and the arguments below gives us the standard Opsview Monitor service check 'Unix Load Average':

check_nrpe -H $HOSTADDRESS$ -c check_load -a '-w 5,5,5 -c 9,9,9'

Here we can see a system-defined variable, known as a 'Macro', which is $HOSTADDRESS$. Note the dollar signs which depict a macro. The $HOSTADDRESS$ macro tells Opsview Monitor to fill this field in using the 'Primary Hostname/IP:' value of the host it is running against. In the example of the Host 'opsview' (which is on all Opsview Monitor systems and uses 'localhost' for its 'Primary Hostname/IP'), this service check and plugin becomes:

check_nrpe 'H localhost -c check_load -a '-w 5,5,5 -c 9,9,9'

This tells the Opsview Monitor software to connect to the host 'localhost' using NRPE (check_nrpe), run the command 'check_load' on that host locally, and pass the 'check_load' command the arguments '-w 5,5,5 'c 9,9,9'.

In another scenario we want to monitor a Windows 2008 server using WMI. To do this we have to pass the login credentials (username and password) to Opsview Monitor so that it can authenticate with the host:

check_wmi_plus.pl -H 192.168.0.2 -u Administrator 'p 5uper5ecretDocsPassword -m checkdrivesize -a C:

In the example above, Opsview Monitor logs in to the host '192.168.0.2' using the username 'Administrator' and password '5uper5ecretDocsPassword', and executes the command 'checkdrivesize' with the argument 'C:' locally.

There are two main issues with the above:

  1. Security ' The username and password are visible to anyone who can log in to the Opsview Monitor system (with valid user credentials).
  2. Scalability: The username and password are hard-coded. This means if we want to monitor another Windows 2008 server that has a different username/password, we must create another Service Check, etc. If we have 10 hosts with different usernames and passwords, we must create 10 separate Service Checks ' just to run the one function.

To overcome these issues, Opsview created Variables. A Variable is defined within the 'Settings > Variables' and is used within Service Checks 'wrapped' within percentage symbols, i.e. %VARIABLE% (Note: this is different to macros which are wrapped in dollar signs, i.e. $MACRO$).

A variable is structured with a value and then four 'arguments', as shown below:

  • Value
  • Variable argument 1:
  • Variable argument 2:
  • Variable argument 3:
  • Variable argument 4:

Note: There are restrictions on what character can be placed within the 'value' field. The value field can only consist of alphanumeric characters, space, a period ('.'), a forward slash ('/') or a dash ('-'), up to 63 characters (this is because the value could be used in the Service Check name, which has restrictions on the characters used). Any trailing spaces will be removed. Also, the argument field allows any characters, but be aware that Nagios Core may process some special characters like !, $ and \. These special characters must be 'escaped', for example 'Password11!' becomes 'Password11\!', and 'PAS$WORD' becomes 'PAS$$WORD'.

In the Windows Server 2008 example specified earlier, we could create a variable called %WINUSER% and %WINPASSWORD%, and change the Service Check from:

check_wmi_plus.pl -H $HOSTADDRESS$ -u Administrator 'p 5uper5ecretDocsPassword -m checkdrivesize -a C

to

check_wmi_plus.pl -H $HOSTADDRESS$ -u %WINUSER% 'p %WINPASSWORD% -m checkdrivesize -a C:

We then need to have only one Service Check which we can apply to multiple Hosts. Administrators can set the WINUSER and WINPASSWORD 'value' in the global 'Settings > Variables > WINUSER/WINPASSWORD' variables respectively; this means that if this Service Check is applied to a Host and is executed, it will inherit the $HOSTADDRESS$ value from the hosts 'Primary Hostname/IP:' field, and the values for the WINUSER and WINPASSWORD variables from the values set within Settings > Variables. This basically means that the username and password (WINUSER and WINPASSWORD) are set in one location and used by one or more Hosts, which is a perfect example of a Windows domain with a single user created for monitoring purposes only.

However, if there are multiple usernames needed to log in (i.e. three different networks), then setting a central username and password doesn't work. In this example local Variables are the answer. By adding a Variable locally to the host, as outlined in Configuring a host: 'Variables' tab', we can specify what username and password values to use for %WINUSER% and %WINPASSWORD% for just that host, and all other hosts will use the global defaults.

The logic works as follows:

  • Is there a local Variable added? If yes, use the value set here
  • Is there a value in the global Variable? If yes, use the value set here
  • If no local Variable and the global Variable is blank, then populate the Variable with a blank value.

Further simplified
We can further simplify the example below:

check_wmi_plus.pl -H $HOSTADDRESS$ -u %WINUSER% 'p %WINPASSWORD% -m checkdrivesize -a C:

to

check_wmi_plus.pl -H $HOSTADDRESS$ -u %WINCREDENTIALS:1% 'p % WINCREDENTIALS:2% -m checkdrivesize -a C:

So what do %WINCREDENTIALS:1 % and %WINCREDENTIALS:2% mean? The number after the colon denotes the argument within the variable, for example :1 means argument 1, etc. By placing the username in argument 1 (arg1) and the password in argument 2 (arg2), an administrator now only needs to add a single Variable to a Host instead of two.

The other benefit of using arguments of a Variable instead of the value of the Variable is that the arguments can be encrypted. This means an administrator can enter the password into 'Arg2', and when the variable is saved/updated, that password can never be retrieved in a plain text format; however, it will be stored and handled by Opsview Monitor in a secure fashion. This is another benefit over hard coding the username and password within the Service Check, which can be retrieved by any authenticated user (given the wrong configuration).

In summary, Variables allow for the secure storage and handling of values that are unique to a Host(s) removing the need to create multiple, duplicate service checks. They provide great security benefits also.

Variables

Overview of Variables in Opsview Monitor