Variables and macros

Overview Copied

Variables within Opsview Cloud act similarly to variables within well-known software languages. Variables allow secure storage and handling of values that are unique to a Host, which removes the need to create multiple and duplicate Service Checks. To further understand the benefit of variables, you must first understand the scenarios that require them.

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

<plugin> <arguments>

Using a plugin of check_nrpe and the following arguments gives us the standard Opsview Cloud 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 Cloud 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 Cloud 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 Cloud 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 Cloud so that it can authenticate with the host:

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

With that example, Opsview Cloud 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.

The preceding example has two main issues:

1. Security — username and password are exposed to anyone with valid user credentials and can log in to the Opsview Monitor system.

2. Scalability — username and password are currently hardcoded. This means that to monitor a Windows 2008 server with different credentials, you must create a separate Service Check. If there are 10 hosts with unique usernames and passwords, you must create 10 individual Service Checks, solely for the purpose of running this single function.

3. Security: The username and password are visible to anyone who can log in to the Opsview Cloud system (with valid user credentials).

4. 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.

Note

This is different from macros that are wrapped in dollar signs, such as $MACRO$.

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

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

The Value field is subject to certain character restrictions. It can only contain alphanumeric characters, spaces, periods, underscores, forward and backward slashes, parentheses, and dashes. The value must not be longer than 63 characters as it may be used in Service Check names. Any trailing spaces will be automatically removed.

Note

For backwards compatibility with argument strings, any occurrences of $$ will be replaced with $ when processed by the system to run checks.

However, this behavior will be removed in a future version. We recommend using single $, which will be processed as it is. This ensures future compatibility and avoids potential issues.

In the Windows Server 2008 example, a variable called %WINUSER% and %WINPASSWORD% can be created, and Service Check arguments can be changed from:

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

to the following new arguments:

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

Note

This also affects SNMP passwords.

With that example, one Service Check can be applied to multiple Hosts. Administrators can set the default WINUSER and WINPASSWORD value in the global Configuration > 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 default values for the WINUSER and WINPASSWORD variables from the values set within Configuration > Variables. This means that the username and password WINUSER and WINPASSWORD are set in one location and are used by one or more hosts, which is an example of a Windows domain with a single user created for monitoring purposes only.

However, if there are multiple usernames that must be logged in, (for example, three different networks), then setting a central username and password doesn’t work. In this example, local variables must be added. By adding a variable locally to the host, as outlined in Configuring a host: ‘Variables’ tab’, username and password values can be specified to use for %WINUSER% and %WINPASSWORD% for that host (as the default values are overridden), 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 default value in the global variable? If yes, use the value set here.
• If there is no local variable and the global variable is blank, then populate the variable with a blank value.

Note

The preceding logic does not apply to Service Checks that have been defined as a Multiple Service Check. In this instance, a local variable must be defined under the host.

The following Service Check can be simplified:

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

to

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

In the %WINCREDENTIALS:1% and %WINCREDENTIALS:2% variables, the number after the colon denotes the argument within the variable. For example, :1 means argument 1. By placing the username in argument 1 (arg1) and the password in argument 2 (arg2), an administrator must only add a single variable to a host instead of two variables.

Another 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 or updated, that password cannot be retrieved in a plain text format. However, it will be securely stored and handled by Opsview Cloud. This is another benefit over hardcoding the username and password within the Service Check, which can be retrieved by any authenticated user (given the wrong configuration).

Macros and variables reference Copied

The following is a list of currently permitted macros and variables:

$HOSTADDRESS$ - Primary address/ip of host
$ADDRESSES$ - Full comma separated list of other addresses for host
$ADDRESS1$ - First address listed in other addresses
$ADDRESSn$ - Nth address listed in other addresses
$SNMP_VERSION$ - SNMP version (1, 2c or 3)
$SNMP_COMMUNITY$ - SNMP community string for host
$SNMP_PORT$ - SNMP port
$SNMPV3_USERNAME$ - SNMP V3 username
$SNMPV3_AUTHPROTOCOL$ - SNMP V3 authentication protocol
$SNMPV3_AUTHPASSWORD$ - SNMP V3 authentication password
$SNMPV3_PRIVPROTOCOL$ - SNMP V3 privacy protocol
$SNMPV3_PRIVPASSWORD$ - SNMP V3 privacy password
%NAME% - Substitute with the value of the host variable called NAME
%NAME:1% - Substitute with the first argument of host variable NAME

Note

NAME is a placeholder for any variables that either exist by default within Opsview or have been created by a user.