How to define groups

WAS THIS PAGE HELPFUL? Leave Feedback

Overview


This page cover the Groups option and walks through how to using groups to set up Multiple WMI Proxy hosts.

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. As a novelty, you can use groups to run a pre-flight test against a host group or even a single host. Note that the Test will fail if its parents are not included in the group. Groups also provide an alternate way to assign contact groups to hosts and services.

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 Instance 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's Nagios CGI configuration.
  • Nagios cfg - Use this option to configure the instance's main Nagios configuration.
  • Resource cfg - Use this option to configure the instance's 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. This module can be locally modified if need be, to implement alternate or specialized deployment actions.
  • Export - This option generates a downloadable set of Nagios configuration files for the instance.
Steps
New Group
  1. Go to Configuration > Groups, and select New. The New Monarch Group screen will be displayed.
  2. 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 must conform to file naming standards and cannot include spaces, illegal characters (anything other than a-z, A-Z, 0-9, hyphen, and dot)
  3. Select Add to go to the next screen, Manage Group.

    Figure: New Group
Manage Group Detail
  1. In the Detail tab, enter the properties, see the table below.
  2. Select Save to add the new Group. Delete will remove the Group. Select Rename to change the name of the current Group. The Close option exits the Manage Group screen without saving.

    Figure: Group Detail

    Table: Detail
    Monarch group name Group name (e.g. unix-gdma-2.1).
    Description [Optional] Store comments or instructions here.
    Contact groups Contact Groups assigned to Groups provide the default Contact Group for Hosts and Services where no Contact Group has been defined at the Host Group, Host, or Service levels. With Nagios, Contact Groups are assigned separately to Hosts and to Services or Host Groups. GroundWork still allows the Nagios 1.2 method of assigning Contact Groups to Host Groups. Even when they share the same Contact Group it still requires administration at two points. Setting the Contact Group on a Group eliminates this redundancy.
    Contact Groups defined on a Group WILL OVERRIDE the Contact Groups defined on Host Templates and Service Templates. Also, Contact Groups assigned to Child Sub Groups will in turn override Contact Groups on a Parent Group.
    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. This might be useful for hosts which are monitored via some non-Nagios mechanism which feeds its results directly 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/groundwork/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/apache2/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/groundwork/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. Typically, in a multi-instance Nagios implementation, the parent monitoring host runs with passive checks while the child monitoring hosts run with active checks.
Manage 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.

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

    Figure: Host Assignment
Manage Groups 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 last dictionary sorted child group in which they are found. 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, it will no longer be recognized as a Macro when subsequent groups are processed.

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

    Figure: Sub Groups
Manage Groups Macros

The following steps and figures will walk you through an example of a service check that is performed through multiple proxies (WMI proxies in our example).

Step 1 - Commands

Group macros extend the Nagios $ARG#$ macros on service checks. The next two screens show how the macro %PROXY% extends the definitions from the command syntax through the service check.

Figure: Macros

Step 2 - Services
  1. By creating a service and using a macro in place of the proxy argument, you can apply the service to multiple hosts and each host will inherit the value from the group to which it is assigned. Normally you would assign real values to command arguments in service checks. Group macros allow you to set and manage these values at the group level.
  2. Here we replace the previous command line with macros with the group macro %PROXY%.
  3. For our example, you will need to create host groups; Windows HostGroup1 and Windows HostGroup2 with Hosts Windows1 and Windows2 assigned, respectively.

    Figure: Services
Step 3 - Service to Host Assignment
  1. In the Service tab of Manage Host you can add, modify, and remove services for the current host.
    Managing services from this page will in all likelihood put the host out of sync with its service profiles. After making changes, use caution when applying profiles to this host. Continuing with our proxy example we add the service wmi_exchange_mailbox_sendq to the hosts Windows1 and Windows2


    Figure: Add service to host Windows1


    Figure: Add service to host Windows2

Step 4 - Add Macro
  1. Here we will create our group macro %PROXY%. Enter a Name, Description, and Value for the macro, then select Add New Macro.
    Great care needs to be taken in macro names. Do not use any names from the list of Nagios macros for instance. Use names that are unique and not likely in the least to match some other part of the check command string. For example, a naming scheme that uses a special character such as % in the prefix and suffix of the name will likely maintain uniqueness, so a proxy macro might be named %PROXY%. It is not a good idea to use $ as that is the special character Nagios uses in macros.


    Figure: Macros

Step 5 - New Group, Assign Host Group, Set Macros (Group 1: WindowsWMIProxy1)

New Group (Group 1: WindowsWMIProxy1)

In the next set of steps we will create our new groups (WindowsWMIProxy1 and WindowsWMIProxy2), assign a host group to our groups (Windows HostGroup1 and Windows HostGroup2), and set the %PROXY% Macro to each group.

The name field cannot be blank or contain illegal characters (anything other than a-z, A-Z, 0-9, hyphen, and dot), begin or end with a hyphen or dot, and cannot already exist.
  1. Select Configuration > Groups, select New, and the New Monarch Group screen will be displayed.
  2. Enter the group WindowsWMIProxy1.
  3. Select Add to go to the next screen, Manage Group.

    Figure: New Group

Assign Host Group (Host Group 1: Windows HostGroup1)

  1. Select the Hosts tab.
  2. Select Windows HostGroup1 from the list of host groups at the bottom of the screen, and choose Add HostGroup(s), you will see the group now listed at the top of the screen.
  3. Continue with Set Macros below.

    Figure: Assign Host Group

Set Macros (Group 1: WindowsWMIProxy1)

  1. Select the %PROXY% macro from the list at the bottom of the screen and click Add Macro(s) to assign it to the WindowWMIProxy1 group.
  2. Adjust the values as needed and select Save to apply it to the group.
  3. To use the Label option you must 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, so we suggest using an underscore as the first character.
    The Enable Label option can be useful where there is a need for redundant checks.

    To illustrate, using our proxy example, it may be beneficial to run the 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, so we suggest using an underscore at the start of the label value.* Repeat the last three steps for the second group starting with New Group (Group2: WindowsWMIProxy2) below.

    Figure: Macros

New Group (Group 2: WindowsWMIProxy2)

  1. Create the group WindowsWMIProxy2.

    Figure: New Group

Assign Host Group (Host Group 2: Windows HostGroup2)

  1. Assign the host group Windows HostGroup2 to the group WindowsWMIProxy2.

    Figure: Assign Host Group

Set Macros (Group 2: WindowsWMIProxy2)

  1. Assign the %PROXY% Macro to the WindowsWMIProxy2 Group.
  2. Adjust the values as needed and select Save to apply it to the group.

    Figure: Macros
Step 6 - Export

Tools Export (Group 1: WindowsWMIProxy1_services.cfg)
Macro values are substituted during a Pre flight test, Commit, and Export; in each case, Nagios reads them from the files that have been generated. Group macros are virtually unlimited but unlike Nagios macros, they can only be used on service checks and not in command definitions.

Figure:

Tools Export (Group 2: WindowsWMIProxy2_services.cfg)

Figure:

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.

Group Tool

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 (in the original scheme we were 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. At the time that Monarch generates the Nagios configuration files the group macro is given its value and this is embedded as an argument along with thresholds, disk names, etc. 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$

    *vService 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
Under Commands
  1. Modify WMI based commands to replace every use of the USER21 macro with $ARG1$.
  2. Adjust all Arguments numbering to be consistent with canonical 1, 2, 3. Generally this means each argument number increases by 1 (because USER21 has become ARG1 in all cases and the prior ARG1 must become ARG2 and so forth).
Under Services
  1. Modify each WMI based service so that the command line reflects the addition in the first argument position of the value %PROXY%.
  2. Use the Apply Hosts feature to distribute the changed service check to all hosts that used it.
  3. It may be necessary to check the Replace Existing service properties box if on inspection of the Pre flight configuration files you find %PROXY% is still present; in this case overrides of thresholds may require to be reset manually.
Under Hosts
  1. Create a host group to hold the hosts for each WMI Proxy servers domain.
  2. Assign hosts to the created host groups appropriately,
Under Groups
  1. In the macro section create the macro PROXY and assign it a dummy value.
Groups Section
  1. Create a group for the first WMI Proxy in use.
  2. Assign the hosts by host group this group.
  3. In the macros section of this group select the PROXY macro and add it to this group.
  4. Change the value to the IP address of this group’s WMI Proxy server.
  5. Select Save.
  6. Repeat the Groups Section Steps 1 - 5 for each WMI Proxy set.
Under Control
  1. Run Pre flight and observe no errors.
  2. Examine the configuration files to determine if the PROXY macro was replaced in all cases.
  3. Run Commit.
Troubleshooting

Use the Pre flight feature in configuration and upon completion use a Linux shell to log in to the server and navigate to the /usr/local/groundwork/core/monarch/workspace directory. Examine the services.cfg file looking for an unsubstituted group macro (PROXY in this example). If you locate any, the failure is that the host is not in a host group assigned using the group feature, or the macro has not been added to that group or has not been assigned a value.

  • Changes to service names, especially in existing systems, will not propagate to use case in hosts already assigned unless the Apply to Hosts feature is exercised.
  • In the group feature there is no need to perform the Build Instance or Pre flight functions (under group). It will produce an error, and will have no effect. These features are applicable only to multiple GroundWork/Nagios instances.
  • In the macros option under groups DO NOT check the Assign Label checkbox. This feature is not useful with the WMI Proxy usage of the tool and it will create an error.
  • In naming the group and the host group use a naming convention that is easy to understand. If the WMI Proxy for a set of hosts is for example dmz-monitor-wmi then name the group the same, and the host group that contains all the hosts to be monitored by that WMI Proxy, the same. WMI Proxy server is dmz-monitor-proxy, host group is dmz-monitor-proxy, group is dmz-monitor-proxy.

Labels

configuration configuration Delete
monarch monarch Delete
groups groups Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.