What are Monarch groups?

Monarch Groups are very flexible and powerful. With great power comes great responsibility, so care should be considered in administering them. In the simplest form, groups can be used to split hosts into different Nagios configuration files, in their most complex implementation they extend the configuration to multiple instances of Nagios, and in between, groups can determine group macro values applied to service checks.

Apart from file management and managing multiple instances of Nagios, the real advantage of groups to most users is to scale the number of services required to manage hosts. Properly implemented, group macros will help reduce the number of redundant services that were required in the past. Groups also provide an alternate way to assign contact groups to hosts and services, and are essential in the management of Parent Managed Child configurations, as well as GDMA Multihost configurations.

This page reviews the Groups options and describes some use cases.

Multiple instances

Groups provide the means to centrally administer multiple instances of Nagios. Each instance is a group and a group can be a parent to a group of child sub groups. With each group, the left tree navigation provides links to its own Nagios CGI configuration, its own main Nagios configuration and its own set of Nagios resource Macros. The Build Instances option will generate the appropriate set of files for the instance in the writable folder specified, and then call the deployment module MonarchDeploy.pm. There is also the option to simply export these files.

Nagios cgi - Use this option to configure the instance Nagios CGI configuration.
Nagios cfg - Use this option to configure the instance main Nagios configuration.
Resource cfg - Use this option to configure the instance Nagios resource macros.
Pre flight test - This option performs a Nagios pre flight test (nagios -v) of the group or instance.
Build instance - Use this option to generate the Nagios configuration files for this instance, and to call the Deployment module. You will find the MonarchDeploy.pm module in the core/monarch/lib folder of your installation. The module is called for a particular group from the Build instance option under the group, and the standard GroundWork Enterprise version of this module will push the group configuration to a corresponding child server whose hostname is exactly the group name.
Export - This option generates a downloadable set of Nagios configuration files for the instance.

Creating a new group

From the Configuration menu item, choose Nagios Monitoring > Groups.
Select New.
In the New Monarch Group screen, enter a Monarch group name. As hosts are assigned to groups they will be found in files named <group_name>_hosts.cfg and their services will be found in <group_name>_services.cfg.
Group names

Group names must conform to file naming standards and cannot include spaces, illegal characters (anything other than a-z, A-Z, 0-9, hyphen, and dot).
Select Add to go to the next screen, Manage Group.

Group detail, hosts, sub groups, and macros

Group detail

The Detail tab is where you define the group directives including the default contact group for the group, the group status of active or inactive, and the build instance properties to be used in a distributed environment. The table below outlines each directive.

managing monarch groups

Monarch group name	Group name (e.g., unix-gdma-2.1).
Description	Store comments or instructions.
Group type	Setting the group type declares whether this group is to model child inventory, or is for other purposes. Only Child Instance type groups can be used with Build Instance.
Profile type	For a Child Instance type group, a "Standalone" profile type will create self-monitoring hosts on the child, and institute ping checks of all the containers running there. These will appear on the parent with a prefix prepended. If you don't want to generate these hosts. select None. See Deploying Parent child.
Contact groups	Selecting a contact group here will provide the default contact group for hosts and services where no contact group has been defined, and it WILL OVERRIDE the contact groups defined on host templates and service templates. Contact groups assigned to sub groups will in turn override these contact groups.
Group Status	Set group inactive in Nagios - Setting the group inactive will remove the member hosts and their services from Nagios, along with any parent relationships, host dependencies, service dependencies, and similar setup. This can be useful, for instance, in the early stages of setting up new hosts, before their configuration is complete. Sync hosts to Foundation - If the group is inactive, the Status viewer (GroundWork Monitor) will also not show these hosts, unless you Sync hosts to Foundation.
Build Instance Properties	These properties are required only if you wish to use this group as part of a distributed Nagios environment. It is not necessary to set these values to perform a pre-flight check for this group. The build folder is usually `/usr/local/nagios/etc/hostname` where you have replaced `hostname` with the actual standby or child server hostname used to name the group. In general, this may be any directory writeable by the 'nagios' user where you wish to store the configuration files. An incorrect entry or a directory with incorrect permissions will cause the build instance to fail. For a Monarch group used simply to reference hosts for generating externals, you must specify `/usr/local/groundwork/monarch/htdocs/GDMAConfigDir` instead, where you have replaced `GDMAConfigDir` with the value of the `GDMAConfigDir` option in the GDMA client `gdma_auto.conf` config file (usually just 'gdma'). Nagios etc folder: For a Monarch group used to manage a child server, enter the path of the Nagios configuration directory on the target host (usually `/usr/local/nagios/etc`). This value will only be used to construct pathnames for entries inside the generated nagios.cfg file, but it must reflect the actual location on the target host where the Nagios object configuration files will reside. For a Monarch group used simply to reference hosts for generating externals, you must leave this field empty. Select Force hosts to dictate the list of Hosts to be included in this instance. This option will override the Sub Group Host lists while still applying the Macros from those Groups where common members reside. Host active checks enabled, Host passive checks enabled, Service active checks enabled, Service passive checks enabled: Use these options to accept or modify the configuration of all host and service checks as established either in the Main configuration (for a top-level group) or in the parent group(s) (for a sub-group), for the hosts (and services on them) that are associated with this group. In general, settings in a sub-group will override any conflicting settings in a parent group.

Group host assignment

Hosts and services are written to Nagios configuration files based on group names. By default all hosts are written to hosts.cfg and all services are written to services.cfg. As previously mentioned, as hosts are assigned to groups they will be found in files named <group_name>_hosts.cfg and their services will be found in <group_name>_services.cfg. Group names must therefore conform to file naming standards.

If you are using groups to distribute hosts and services into different Nagios configuration files, you will want to use host groups where host members don't overlap, or add hosts individually to each group. The drawback to the latter option is that with each new host you will need to assign it manually to a group, whereas host assignment with host groups is automatic (e.g., when the host is assigned to the host group). Where host membership overlaps one or many groups, the host is assigned to the file of the last group read. Groups are read in dictionary sorted order.

In the Hosts tab, check a box for host assignment by Hosts individually or by Host Group. The preferred method is to assign host groups as new hosts will be included here when they are assigned to the host group.

group host assignment

Sub groups

Sub Groups are useful only in special circumstances, in particular to build multiple instances of Nagios. Should one find the need for them bear in mind that hosts and services will be assigned to the file of the last child group in which they are found, in dictionary order. Conversely, where macros overlap, the value is taken from the first dictionary sorted parent group. In other words, once a match has been made and the macro replaced by its value, it will no longer be recognized as a Macro when subsequent groups are processed.

To add hosts to Sub Groups, in the Sub Groups tab, select from the bottom list of existing groups and select Add Group(s) to assign groups. Select from the top list and select Remove to un-assign groups.

monarch sub groups

Group macros

Group Macros can be used to substitute values into service check commands that change based on the Group (or sub group) membership. For example, if you wanted to check a service on one host using a particular proxy server, and the same service on a different host using a different proxy server, you could define the %Proxy% macro, and set it to one value in the main group, and another value in a subgroup. The hosts in the main group would get the first value, unless they were in a subgroup, in which case they would get the second.

Thus Group macros allow you to set and manage service check argument values at the group level. Group macros are virtually unlimited, but unlike Nagios macros, they can only be used on service checks and not in command definitions.

Adding Group Macros

To create a group macro called %WMIProxy%, for example, click the Macros item in the left-hand tree menu of the Groups screen. You can then fill in the form with a Name, Description, and Value for the macro, then select Add New Macro.

Macro names

Do not use any names from the list of Nagios macros, or any names likely to match some other part of the check command string. For example, use a special character such as % in the prefix and suffix of the name, like %PROXY%. It is not a good idea to use $ as that is the special character Nagios uses in macros.

adding group macros

Assigning Macros to Groups

Once you have defined your macros, you can add them to specific (sub) groups.

For the group where you want to use the macro, in the Group Detail, select the Macros tab.

Select the macro from the list at the bottom of the screen and click Add Macro(s). If you want to use an alternate value than the one you assigned when you created the macro, adjust the value as needed and select Save to apply it to the group.

You can also label service descriptions with specific suffixes based on the macros you add. Select Enable label and enter a value, then click Save to apply it to the group. The value is appended to the service description on services where the macro is found. We suggest using an underscore as the first character.

Enable Label

The Enable Label option can be useful where there is a need for redundant checks.

For example, it may be beneficial to run checks through a second proxy as a failover measure. Using this option eliminates the necessity of creating a second set of services. By assigning a host to two groups, each with the %PROXY% macro but assigned different values, enabling the label option and assigning a value will generate a second set of checks on services where the %PROXY% macro is found. The label is appended to the service description on the second set of checks, enabling you to tell that the source of the check result is in fact the alternate (failover) proxy.

Troubleshooting

Use the Pre flight feature in the Groups menu for your group, and then click on the config files in the resulting list to see the contents onscreen. You can test and verify the substituted values are as you expect. Using macros can be complex, but it is extremely powerful.

Important notes

Changes to service names, especially in existing systems, will not propagate to hosts already where the service is assigned unless the Apply to Hosts feature is exercised.
In naming the group and the host group use a naming convention that is easy to understand. If the proxy for a set of hosts is, for example: dmz-monitor, then name the group the same, and the host group that contains all the hosts to be monitored by that proxy the same.

Use Case: Using Groups to set up multiple WMI proxy hosts

The standard way a WMI Proxy host is implemented relies upon a Nagios resource macro (USER21) to be assigned the IP address of the WMI Proxy server. All the standard WMI check commands are coded with this macro name in the -H position so that the check_nrpe command sends the request to run a VBScript check to that proxy. Within the rest of the WMI command the -c argument is followed by an argument identifying the VBScript check to be run (from the WMI proxy) and the -a argument indicates the list of parameters to be passed to the VBScript, generally the IP address of the target host to be queried, the performance counter, instance, and thresholds to be checked.

Summary

-H WMI Proxy address in the USER21 Macro
-c name of check WMI VBScript to be run on Proxy
-a arguments to pass to check WMI VBScript (Host IP Address to be queried by Proxy, Performance counter, Instance, Threshold values)

The limitation here is that more than one proxy server can not be supported easily. Each new WMI Proxy must have an additional USERX macro assigned for the WMI Proxy IP address and moreover every check command, service, and profile using a check command that involves the USERX macro must be duplicated leading to the difficulty of many additional objects to be configured and maintained.

Using Groups and Group Macros for WMI proxies

The GroundWork Monitor administrator can use the Group option in Monarch to build an association of check commands and services to be applied to an arbitrary set of hosts. The key concept is an additional set of macros separate from the Nagios resource macros.These group macros are interpreted at the point that the configuration Pre flight or Commit is executed, so that the value of each group macro is substituted into any command or service where it may be used in association with the group. Because the group macro is not a Nagios construct, we have to pass it in to the configuration files as an argument as opposed to using the Nagios resource macro.

Thus a command can include the group macro %PROXY% passed in as an ARG where originally we would have placed $USER21$ . Within one group definition, that group macro %PROXY% is assigned an IP address of 10.1.1.1 appropriate to the WMI Proxy for a set of hosts. Those hosts are also associated with the same group and at Pre flight or Commit time, Monarch substitutes the value 10.1.1.1 into the command and service check for those Hosts only. By the same mechanism, a second Group definition would have a different IP Address assigned, say 10.2.1.1 to the Group Macro %PROXY%. The different set of hosts associated with the second Group gets this 10.2.1.1 value substituted wherever %PROXY% occurs.

In this way, a single set of commands will employ no Nagios macro, just a passed ARG value for the WMI Proxy IP address. These commands are used in a single set of service checks, which in turn can be assigned to multiple sets of hosts directly or through service profiles. The administrator most commonly creates a host group for each WMI Proxy and places the hosts that will be served into the appropriate host group. The following WMI service profiles are delivered with GroundWork Monitor and have been modified to use Monarch groups for assignment of the Proxy IP address.

service-profile-wmi-citrix.xml
service-profile-wmi-dc.xml
service-profile-wmi-dns.xml
service-profile-wmi-exchange.xml
service-profile-wmi-exhange-virus,xml
service-profile-wmi-ftp.xml
service-profile-wmi-http.xml
service-profile-wmi-https.xml
service-profile-wmi-iis.xml
service-profile-wmi-imap.xml
service-profile-wmi-ldap.xml
service-profile-wmi-mssql.xml
service-profile-wmi-pop3.xml
service-profile-wmi-proxy.xml
service-profile-wmi-smtp.xml
service-profile-wmi-windows.xml

Example of a check command and service

Command check_wmi_cpu

check_nrpe --H $ARG1$ -c get_cpu --a $HOSTADDRESS$ $ARG2$ $ARG3$

Service Check for check_wmi_cpu

check_wmi_cpu --H $ARG1$ -c get_cpu --a $HOSTADDRESS$ $ARG2$ $ARG3$

Command Line for same
```
check_wmi_cpu!%PROXY%!_Total!80,90
```
A similar approach can be used to differentiate the arguments passed to other service checks based on Group or Sub Group membership.

How to manage monarch groups