h4. Tech Tip 7 (11/2018) --- Using GDMA Auto-Setup for Windows Drive Letter Detection
GDMA has a lot of features, and one of the newest ones is "Auto-Setup". What this feature does is detect configuration of systems through a variety of means, and then sets up the GDMA client to monitor that configuration. It is done at the host level, so while your auto-setup "instructions" can be the same for all hosts, every host can be configured and monitored differently. You can "trigger" auto-setup to update the configuration whenever you like, so you can get very, very close to fully automated monitoring.
As of this writing, the auto-setup instructions are still being reviewed, so there's no extensive documentation yet. That's no reason not to get started with a useful example, so in this tech tip, we will go over how you set up your Windows hosts to use auto-setup to detect the drive letters on your systems and monitor them.
h5. Use GWME 7.2.1 and GDMA 2.6.2
If you don't have GroundWork Monitor 7.2.1 installed yet, you will want to do that first. This tech tip assumes a fully-patched (as of this writing) 7.2.1 system. So, go ahead and download the latest version of GroundWork Monitor, run through all the technical bulletins, especially the Rollup Patch Installer, and download the latest GDMA 2.6.2 (recommended) version. The GDMA version 2.6.2 was released after the GWME 7.2.1 version and therefore will not be available locally on your 7.2.1 system.
* For GroundWork Monitor 7.2.1 release see [Downloads|https://kb.groundworkopensource.com/display/FLEX/Downloads]
* For patches see [Technical Bulletins|https://kb.groundworkopensource.com/display/FLEX/Technical Bulletins]
* For GDMA 2.6.2 release see [Downloads|https://kb.groundworkopensource.com/display/FLEX/Downloads]
h5. Import the profile
We are attaching a new {{gdma?win?host}} host profile and {{gdma?windows}} service profile to this tech tip. This is a more generalized version of the {{gdma?21?windows}} service profile. Its name is different, so it won't conflict with the default, and the main difference besides the profile name is a new service called "{{gdma_wmi_disk\_}}", along with a service external of the same name. Why the trailing underscore? Well, it's a style choice, but you will see why it makes sense, below.
{attachments:patterns=profile-gdma-win-auto.tgz}
# To do this, copy this file to your GroundWork server.
# Then enter the following command:
{noformat}
tar zxvf profile-gdma-win-auto.tgz -C /
{noformat}
This will put the three files you need into the _Uploaded_ directory of the profile store.
# Then just import all the profiles in the _Uploaded_ section using the [Profile Importer|DOC721:How to import profiles].
h5. Install GDMA on a Windows system
This example works best on a system with at least two drive letters. Let's say you have drives C: and Q: on your Windows system.
* When you install GDMA, several options need to be established so that Auto-Setup will run and so that Auto-Register will not run.
** You will need to supply a Registration username and a Registration password.
** For the Host profile name, enter the literal string "{{none}}" (without those quotes). (A host profile specified here will not be used for Auto-Setup, but if you leave this field blank, it will be filled in instead with a valid default value, which is not what you want to have happen.)
** Be sure to say no to the question "Start GDMA after installation?".
* You can also use the command line option "{{??gdma_service_start no}}" if you prefer using the command line (who doesn't?).
* If you need help getting GDMA installed, see [GDMA installation and upgrade notes|https://kb.groundworkopensource.com/display/FLEX/GDMA installation and upgrade notes].
h5. Tell GDMA to use Auto-Setup
Off by default, this option is in the {{gdma_auto.conf}} file starting with the GDMA 2.6.1 release. It must be set in the {{gdma_auto.conf}} file; it cannot be set in host externals.
# Find the file here, {{C:\Program Files (x86)\groundwork\gdma\config\gdma_auto.conf}}, and open it with WordPad or a similar tool.
# Change the following:
{noformat}Enable_Auto_Setup = "off"{noformat}
to:
{noformat}Enable_Auto_Setup = "on"{noformat}
# Save the file.
h5. Install the instructions on the GroundWork server
The instructions and trigger files are really short, but it's a good idea to keep them somewhere consistent. This is what we recommend:
# Log in to the GroundWork server and become user {{nagios}}:
{noformat}
su - nagios
{noformat}
# Make an {{autosetup}} directory under the {{nagios}} home directory:
{noformat}
mkdir autosetup
cd autosetup
{noformat}
# Create the instructions file in this directory with the following contents:
{noformat}
format_version = "1.0"
<host "Windows">
type = os_type
pattern = "windows"
host_profile = "gdma-win-host"
</host>
<service "Windows Drive Letters">
type = mounted_filesystem
cardinality = multiple
pattern = "([A-Z]):/"
service = "gdma_wmi_disk_"
instance_suffix = "$SANITIZED1$"
</service>
{noformat}
You need to name it something that ends with "{{\_instructions}}". We will use "{{winpattern_instructions}}".
\\
\\
# Create the trigger file with the following contents:
{noformat}
last_step = "do_configuration"
if_duplicate = "optimize"
soft_error_reporting = "ignore"
{noformat}
Similarly, you need to name trigger files to end with "{{\_trigger}}", so we will use "{{winpattern_trigger}}".
h5. Install the instructions and trigger files for your first host
Auto-Setup needs to have the instructions and trigger files in a specific location, and manage them itself. You always install the instructions first, then the trigger. This is so the trigger can be used and then ignored until re-installed (thus triggering another pass of discovery). Here's how you do it, with the {{autosetup}} command:
{panel:borderStyle=solid|borderColor=#CCCCCC|bgColor=white}
{{/usr/local/groundwork/gdma/bin/autosetup install \-p ./winpattern_instructions }}{_}hostname(s)_
{{/usr/local/groundwork/gdma/bin/autosetup install \-p ./winpattern_trigger }}{_}hostname(s)_
{panel}
Use the hostname for the Windows host where you have GDMA installed, set to use auto-setup.
h5. Start the client GDMA
Now, whenever you are ready, start GDMA on the client system ({{net start gdma}}), and the host will show up in Monarch with the following services:
* gdma_wmi_cpu
* gdma_wmi_disk\_ _(This will expand on Commit to have service instances for_ {{{_}C:_}} _and_ {{{_}Q:_}} _in our case. Your system may be different.)_
* gdma_wmi_disktransfers
* gdma_wmi_mem
* gdma_wmi_memory_pages
* gdma_wmi_uptime
Run a Control > Commit operation to instantiate the services.
You will have also imported performance definitions with the profile, so all these services should have graphs associated in the Status and Grafana applications.
How does it work? Well, the detected drive letter is found by the auto-setup discovery processing on the Windows host, and passed as a macro to the service definition in Monarch. There, it's used as an _instance_ name for a service _instance_ on the {{gdma_wmi_disk\_}} service. (Which is to say, we will end up with monitoring for {{gdma_wmi_disk_C}} and {{gdma_wmi_disk_Q}} service instances in our example.) That's why we left the trailing underscore, but more importantly, that trailing underscore is something we like to use to signal that the service is intended to be used with auto-setup and instances. You certainly *could* not do it that way, and instead carry along the underscore in the instructions, like this:
{noformat}
instance_suffix = "_$SANITIZED1$"
{noformat}
Thus, using the underscore directly in the base service name is a style choice.
h5. More hosts?
You can now apply auto-setup to more hosts. What you will want to do next is add instructions and then triggers for all your hosts. If you have a list of hostnames, you can use {{xargs}} to loop over the list, installing the instructions files for all of those hosts in bulk, using a command like the following. Here we assume your list is in a file in the current directory called "{{listofhosts}}", with one host per line.
{noformat}
xargs -a ./listofhosts /usr/local/groundwork/gdma/bin/autosetup install -p ./winpattern_instructions
{noformat}
You can use a similar command to install the triggers:
{noformat}
xargs -a ./listofhosts /usr/local/groundwork/gdma/bin/autosetup install -p ./winpattern_trigger
{noformat}
You can check the status of the hosts you prepare in this way with:
{noformat}
/usr/local/groundwork/gdma/bin/autosetup status -t -a
{noformat}
See the {{autosetup ??help}} command for a nice description of all the options.
{note}
The {{autosetup ??help}} output requires your terminal type (the {{TERM}} environment variable) to be set properly. This is normally taken care of for you when you log in, say by {{ssh}} copying the terminal type from your local terminal window or terminal emulator to the remote login setup, (for logging in from an ordinary Linux terminal these days, {{xterm?256color}} is a common terminal type). If you see strange characters in the help text, just adjust your terminal type. You'll want that anyway so other commands like {{man}} and {{vim}} work properly.
{note}
As of GDMA 2.6.2, there's no option to enable auto-setup automatically when you install GDMA, though we do plan to add that to a future release. For now, just create your own {{gdma_auto.conf}} file and supply it as part of your GDMA install, turning on auto-setup in that file as you did above. Just install GDMA without starting it, replace the {{gdma_auto.conf}} file, and start GDMA. Auto-Setup will then do the rest.
Questions? Problems? Let us know at [GroundWork Support|mailto:[email protected]].
GDMA has a lot of features, and one of the newest ones is "Auto-Setup". What this feature does is detect configuration of systems through a variety of means, and then sets up the GDMA client to monitor that configuration. It is done at the host level, so while your auto-setup "instructions" can be the same for all hosts, every host can be configured and monitored differently. You can "trigger" auto-setup to update the configuration whenever you like, so you can get very, very close to fully automated monitoring.
As of this writing, the auto-setup instructions are still being reviewed, so there's no extensive documentation yet. That's no reason not to get started with a useful example, so in this tech tip, we will go over how you set up your Windows hosts to use auto-setup to detect the drive letters on your systems and monitor them.
h5. Use GWME 7.2.1 and GDMA 2.6.2
If you don't have GroundWork Monitor 7.2.1 installed yet, you will want to do that first. This tech tip assumes a fully-patched (as of this writing) 7.2.1 system. So, go ahead and download the latest version of GroundWork Monitor, run through all the technical bulletins, especially the Rollup Patch Installer, and download the latest GDMA 2.6.2 (recommended) version. The GDMA version 2.6.2 was released after the GWME 7.2.1 version and therefore will not be available locally on your 7.2.1 system.
* For GroundWork Monitor 7.2.1 release see [Downloads|https://kb.groundworkopensource.com/display/FLEX/Downloads]
* For patches see [Technical Bulletins|https://kb.groundworkopensource.com/display/FLEX/Technical Bulletins]
* For GDMA 2.6.2 release see [Downloads|https://kb.groundworkopensource.com/display/FLEX/Downloads]
h5. Import the profile
We are attaching a new {{gdma?win?host}} host profile and {{gdma?windows}} service profile to this tech tip. This is a more generalized version of the {{gdma?21?windows}} service profile. Its name is different, so it won't conflict with the default, and the main difference besides the profile name is a new service called "{{gdma_wmi_disk\_}}", along with a service external of the same name. Why the trailing underscore? Well, it's a style choice, but you will see why it makes sense, below.
{attachments:patterns=profile-gdma-win-auto.tgz}
# To do this, copy this file to your GroundWork server.
# Then enter the following command:
{noformat}
tar zxvf profile-gdma-win-auto.tgz -C /
{noformat}
This will put the three files you need into the _Uploaded_ directory of the profile store.
# Then just import all the profiles in the _Uploaded_ section using the [Profile Importer|DOC721:How to import profiles].
h5. Install GDMA on a Windows system
This example works best on a system with at least two drive letters. Let's say you have drives C: and Q: on your Windows system.
* When you install GDMA, several options need to be established so that Auto-Setup will run and so that Auto-Register will not run.
** You will need to supply a Registration username and a Registration password.
** For the Host profile name, enter the literal string "{{none}}" (without those quotes). (A host profile specified here will not be used for Auto-Setup, but if you leave this field blank, it will be filled in instead with a valid default value, which is not what you want to have happen.)
** Be sure to say no to the question "Start GDMA after installation?".
* You can also use the command line option "{{??gdma_service_start no}}" if you prefer using the command line (who doesn't?).
* If you need help getting GDMA installed, see [GDMA installation and upgrade notes|https://kb.groundworkopensource.com/display/FLEX/GDMA installation and upgrade notes].
h5. Tell GDMA to use Auto-Setup
Off by default, this option is in the {{gdma_auto.conf}} file starting with the GDMA 2.6.1 release. It must be set in the {{gdma_auto.conf}} file; it cannot be set in host externals.
# Find the file here, {{C:\Program Files (x86)\groundwork\gdma\config\gdma_auto.conf}}, and open it with WordPad or a similar tool.
# Change the following:
{noformat}Enable_Auto_Setup = "off"{noformat}
to:
{noformat}Enable_Auto_Setup = "on"{noformat}
# Save the file.
h5. Install the instructions on the GroundWork server
The instructions and trigger files are really short, but it's a good idea to keep them somewhere consistent. This is what we recommend:
# Log in to the GroundWork server and become user {{nagios}}:
{noformat}
su - nagios
{noformat}
# Make an {{autosetup}} directory under the {{nagios}} home directory:
{noformat}
mkdir autosetup
cd autosetup
{noformat}
# Create the instructions file in this directory with the following contents:
{noformat}
format_version = "1.0"
<host "Windows">
type = os_type
pattern = "windows"
host_profile = "gdma-win-host"
</host>
<service "Windows Drive Letters">
type = mounted_filesystem
cardinality = multiple
pattern = "([A-Z]):/"
service = "gdma_wmi_disk_"
instance_suffix = "$SANITIZED1$"
</service>
{noformat}
You need to name it something that ends with "{{\_instructions}}". We will use "{{winpattern_instructions}}".
\\
\\
# Create the trigger file with the following contents:
{noformat}
last_step = "do_configuration"
if_duplicate = "optimize"
soft_error_reporting = "ignore"
{noformat}
Similarly, you need to name trigger files to end with "{{\_trigger}}", so we will use "{{winpattern_trigger}}".
h5. Install the instructions and trigger files for your first host
Auto-Setup needs to have the instructions and trigger files in a specific location, and manage them itself. You always install the instructions first, then the trigger. This is so the trigger can be used and then ignored until re-installed (thus triggering another pass of discovery). Here's how you do it, with the {{autosetup}} command:
{panel:borderStyle=solid|borderColor=#CCCCCC|bgColor=white}
{{/usr/local/groundwork/gdma/bin/autosetup install \-p ./winpattern_instructions }}{_}hostname(s)_
{{/usr/local/groundwork/gdma/bin/autosetup install \-p ./winpattern_trigger }}{_}hostname(s)_
{panel}
Use the hostname for the Windows host where you have GDMA installed, set to use auto-setup.
h5. Start the client GDMA
Now, whenever you are ready, start GDMA on the client system ({{net start gdma}}), and the host will show up in Monarch with the following services:
* gdma_wmi_cpu
* gdma_wmi_disk\_ _(This will expand on Commit to have service instances for_ {{{_}C:_}} _and_ {{{_}Q:_}} _in our case. Your system may be different.)_
* gdma_wmi_disktransfers
* gdma_wmi_mem
* gdma_wmi_memory_pages
* gdma_wmi_uptime
Run a Control > Commit operation to instantiate the services.
You will have also imported performance definitions with the profile, so all these services should have graphs associated in the Status and Grafana applications.
How does it work? Well, the detected drive letter is found by the auto-setup discovery processing on the Windows host, and passed as a macro to the service definition in Monarch. There, it's used as an _instance_ name for a service _instance_ on the {{gdma_wmi_disk\_}} service. (Which is to say, we will end up with monitoring for {{gdma_wmi_disk_C}} and {{gdma_wmi_disk_Q}} service instances in our example.) That's why we left the trailing underscore, but more importantly, that trailing underscore is something we like to use to signal that the service is intended to be used with auto-setup and instances. You certainly *could* not do it that way, and instead carry along the underscore in the instructions, like this:
{noformat}
instance_suffix = "_$SANITIZED1$"
{noformat}
Thus, using the underscore directly in the base service name is a style choice.
h5. More hosts?
You can now apply auto-setup to more hosts. What you will want to do next is add instructions and then triggers for all your hosts. If you have a list of hostnames, you can use {{xargs}} to loop over the list, installing the instructions files for all of those hosts in bulk, using a command like the following. Here we assume your list is in a file in the current directory called "{{listofhosts}}", with one host per line.
{noformat}
xargs -a ./listofhosts /usr/local/groundwork/gdma/bin/autosetup install -p ./winpattern_instructions
{noformat}
You can use a similar command to install the triggers:
{noformat}
xargs -a ./listofhosts /usr/local/groundwork/gdma/bin/autosetup install -p ./winpattern_trigger
{noformat}
You can check the status of the hosts you prepare in this way with:
{noformat}
/usr/local/groundwork/gdma/bin/autosetup status -t -a
{noformat}
See the {{autosetup ??help}} command for a nice description of all the options.
{note}
The {{autosetup ??help}} output requires your terminal type (the {{TERM}} environment variable) to be set properly. This is normally taken care of for you when you log in, say by {{ssh}} copying the terminal type from your local terminal window or terminal emulator to the remote login setup, (for logging in from an ordinary Linux terminal these days, {{xterm?256color}} is a common terminal type). If you see strange characters in the help text, just adjust your terminal type. You'll want that anyway so other commands like {{man}} and {{vim}} work properly.
{note}
As of GDMA 2.6.2, there's no option to enable auto-setup automatically when you install GDMA, though we do plan to add that to a future release. For now, just create your own {{gdma_auto.conf}} file and supply it as part of your GDMA install, turning on auto-setup in that file as you did above. Just install GDMA without starting it, replace the {{gdma_auto.conf}} file, and start GDMA. Auto-Setup will then do the rest.
Questions? Problems? Let us know at [GroundWork Support|mailto:[email protected]].