This page provides details about tools and files you will encounter while using GDMA Auto Setup.

The autosetup Tool

The autosetup program is designed to handle the most common tasks in a simple way. Aside from your favorite editor, which will be used to construct the content of instructions and trigger files, it is the central server-side tool for managing all interactive aspects of GDMA Auto Setup.

autosetup Commands

Many of these commands take a list of hostnames as arguments and look for filenames with those hostnames embedded. Such commands normally look for files under an alternative form of each hostname if an exact match is not found. If you want to control which hostname alternatives are considered, you may specify one of the following options:

-e to only allow an exact match to the hostname(s) given
-f to only allow a fully-qualified hostname as an alternative match
-u to only allow an unqualified hostname as an alternative match

Command	Use
`autosetup status`	`autosetup status [-t] {-a\|[-e\|-f\|-u] hostname ...}` Lists the status of all the files for the named hosts, in a compact form. This is used to answer the questions: Is the host under control of GDMA Auto-Setup? Is each type of file (instructions, trigger, results, analysis) in-place or available? Have errors been reported during auto-discovery? Use the `-t` option to print file timestamps instead of YES/no indicators for the presence of the files. Use the -a option without any hostnames to list all hosts with at least one file in any of the relevant directories.If the -a option is not given, this command normally looks for files under an alternative form of each hostname if an exact match is not found. You can control which hostname alternatives are considered by specifying one of the `-e`, `-f`, and `-u` options, which act as noted above.
`autosetup validate`	`autosetup validate file ...` Checks that the listed instructions, trigger, or results files pass validation tests (are parseable, have the right collections of content, etc.). This can help in particular when preparing auto-discovery instructions files, before putting them into play for the GDMA clients to pick up.
`autosetup install -p`	`autosetup install -p patternfile hostname ...` Safely installs the `patternfile` (instructions or trigger file) in the appropriate configured install location, creating or replacing one copy for each named host. The name of the `patternfile` must be of the general form `?_instructions` or `?_trigger` to indicate its file type, so the correct install location can be determined. In general, you will want to keep a collection of standard trigger files in your master stash for common purposes, such as for dry-run discovery-only, dry-run discovery-and-test-configuration, and live-run discovery. See Examples of Auto Setup for examples of such files. These standard trigger files can then be copied using this command as needed for individual hosts.
`autosetup install`	`autosetup install file ...` Safely installs the named instructions and/or trigger files to their respective configured locations for pickup by GDMA clients. A careful protocol is used for this copying, taking care of atomicity and timestamp concerns. That sidesteps the race conditions that would otherwise arise when a new or updated file is being installed while the GDMA client might be trying to read the same file. In this form of the command, each listed file must exist and be appropriately named, the acceptable forms being either `hostname_instructions` or `hostname_trigger`. Instructions and trigger filenames can be freely intermixed on the same command. Hint: the "`autosetup install -p patternfile`" form of the `install` command is more commonly used than this one.
`autosetup print results`	`autosetup print results [-e\|-f\|-u] hostname ...` Finds and prints the last discovery results for the named hosts. The `-e`, `-f`, and `-u` options act as noted above.
`autosetup analyze`	`autosetup analyze [-e\|-f\|-u] hostname ...` This command is not yet implemented. Finds and analyzes the last discovery results for the named hosts. The -e, -f, and -u options act as noted above.
`autosetup print analysis`	`autosetup print analysis [-e\|-f\|-u] hostname ...` Finds and prints the last discovery results analyses for the named hosts. The `-e`, `-f`, and `-u` options act as noted above.
`autosetup audit`	`autosetup audit [-e\|-f\|-u] hostname ...` This command is not yet implemented. Compares current configuration with the last discovery results for the named hosts. The `-e`, `-f`, and `-u` options act as noted above. This command is intended to execute a dry-run reconfiguration of the specified hosts based on their respective last auto-discovery results, and identify any current differences from that setup. These differences could be used to identify mistakes or unintended outside-the-box changes, or they could be ripe for inclusion in the auto-discovery instructions. They could also be used to identify what changes might come into play because host and service profiles and other server-side changes have been modified, and a new round of live-action auto-setup would change the configuration even if the auto-discovery results themselves were unchanged.
`autosetup remove`	`autosetup remove [-e\|-f\|-u] hostname ...` Removes all instructions, trigger, results, and analysis files for the named hosts, from their respective configured directories. The `-e`, `-f`, and `-u` options act as noted above. This is the standard mechanism for de-provisioning hosts from Auto-Setup processing. That said, it does not also remove the named hosts from the Nagios configuration database.
`autosetup -h`	`autosetup -h` Print the help message (i.e., a form of the same material as in the section you are reading).
`autosetup -V`	`autosetup -V` Print the program version.

autosetup Examples

Command Use

autosetup status -t -a

This will find all related files and print last-modified timestamps for them.

autosetup print results

autosetup print results myhost

autosetup install -p my_standard_instructions   host1 host2 host3
autosetup install -p standard_test_only_trigger host1 host2 host3

These two commands will copy my_standard_instructions to the instructions directory, creating host1_instructions and similar files there, followed by copying standard_test_only_trigger to the trigger directory, creating host1_trigger and similar files there. In general, this is the correct sequence to follow: make sure the proper instructions are in place before you create or update a trigger file for a given host. Using pattern files like this makes it possible to easily share the same setup across many hosts, so you can support just a few master files and don't need to maintain sets of one-per-host files.

autosetup Usage Notes

From the page Managing Auto Setup, see the the sections Invoking the autosetup Command and Installing Instructions and Trigger Files for how to run autosetup in GW7 and GW8 contexts. In general, you want to have a shell alias defined, as shown in the latter of those two sections.

Hostnames are generally supposed to be case-insensitive, but all of the handling of hostnames by this tool is case-sensitive. If you wish to know exactly what lettercase forms of hostnames are currently in play, use the autosetup status -a command.
There is an important caveat about installing files to be fetched by GDMA clients. For an instructions file to be recognized by a GDMA client, you must install a trigger file for a given host after that instructions file is installed for that host. Otherwise, the client will think that the trigger applies to some earlier copy of the instructions. In the worst case it might immediately find the trigger before you install updated instructions, and run discovery using an older copy of the instructions than the one you wanted it to use — not a scenario you want to find yourself in.

The two types of file can be installed in tandem, if desired, by specifying both of them on the "autosetup install file1 file2" command form. However, in that case, the filenames used must be exactly hostname_instructions and hostname_trigger. In general, you will not be managing your master instructions and trigger files on a host-by-host basis like that. Instead, you will keep around just a few master instructions files and a few trigger files, and you will use these two commands in sequence to install them for particular hosts:
```
autosetup install -p my_standard_instructions host1 host2 host3
autosetup install -p my_standard_trigger      host1 host2 host3
```
If you have already run auto-discovery on some hosts and simply want to trigger a new pass of discovery on those hosts using the same instructions file, it is not necessary to re-install the instructions file. You simply need to re-install the trigger file, which will update its timestamp so the GDMA client will recognize that a new pass of discovery has been requested.
```
autosetup install -p my_standard_trigger host1 host2 host3
```
That said, there is no harm in re-installing the instructions file first, and you might want to adopt that habit to ensure that you are always using the intended instructions when running a pass of discovery.

See the page Practical Advice for Auto Setup under the section Best Practices for advice on where to store your master instructions and trigger files, as well as other recommendations about how to manage them.

The discover Tool

discover is a program provided on the GDMA client that allows you to interactively and immediately run a pass of discovery. This can help when you are developing new sensor definitions.

discover Commands

Command Use

discover

discover trigger_file instructions_file [results_file [send_flag]]

Run a pass of discovery, using the specified trigger and instructions files.

trigger_file is the path to an auto-discovery trigger file
instructions_file is the path to an auto-discovery instructions file
results_file is an optional path to a file in which the auto-discovery file results will be locally stored
send_flag is an optional boolean flag (typically set to 1 if you're going to use it) that tells discover to send the auto-discovery results to the server

Diagnostic information will always be written to the standard output stream, to help with understanding the parsing and execution of the trigger and instructions files.

If the results_file and send_flag arguments are omitted, the discovery results will also be printed to the standard output stream. If the results_file is argument is provided, the diagnostic information will still be printed to the standard output stream, but the discovery results will instead be written to the stated file.

If both the results_file and send_flag arguments are provided, the discovery results will be saved to the file and also sent to the server for processing there. A much greater level of validation can be run on the server side, depending on the last_step value specified in the client-side trigger file.

discover -h

Print the help message (i.e., a form of the same material as in the section you are reading).

discover -V

Print the program version.

If you try to send results to the server but the last_step value in the trigger file is not at least send_results, the discover tool will complain that the discovery results had an inappropriate last_step value, due to the mismatch of expectations. It's not that the value was illegal, it's that it was inappropriate for the use you appear to be wanting to put it to. Use a trigger file with different content if you run into this.

The auto_wrapper Tool

The auto_wrapper tool runs on the system where GroundWork 8 is installed, as the user that installed it (the user in the docker group), and allows you to run Auto Setup commands without the need to be in the docker container. This tool also provides the capability to copy the files autosetup needs in order to function, such as instructions, triggers, and profiles into place so that they can be picked up by the agents.

auto_wrapper Options

Usage:

auto_wrapper.pl -directory /path/to/files/ -hosts /path/to/hosts.txt -import -install trigger/pattern_name -validate -remove -results -analysis -help -h -version

Where:

-directory Contains the full path to the automation subdirectories:
- profiles/ The directory containing GroundWork Monitor profiles
- trigger/ The trigger files for GDMA Auto Setup
- instructions/ The instructions files for GDMA Auto Setup
- Example (used with -import):
  ./auto_wrapper.pl -import -directory /home/gwos/autosetuplinux/
-import Imports profiles, trigger files, and instructions into the monarch container
- Requires -directory
- Example: ./auto_wrapper.pl -import -directory /home/gwos/autosetuplinux/
-install Installs instructions and trigger files for the specified pattern, for example, winpattern or linuxpattern
- Requires -hosts
- Example: ./auto_wrapper.pl -install linuxpattern -hosts /home/gwos/autosetuplinux/hosts.txt
-validate Validates instructions for the specified pattern, for example, winpattern or linuxpattern
- Combined with -import to validate instructions directly after install
- Example: ./auto_wrapper.pl -import -directory /home/gwos/autosetuplinux/ -validate
-remove Removes Auto Setup configuration from hosts in the host list
- Requires -hosts
- Example: ./auto_wrapper.pl -remove /home/gwos/autosetuplinux/hosts.txt
-results Prints sensor results of GDMA Auto Setup
- Requires -hosts
- Example: ./auto_wrapper.pl -results -hosts /home/gwos/autosetuplinux/hosts.txt
-analysis Prints sensor analysis of GDMA Auto Setup
- Requires -hosts
- Example: ./auto_wrapper.pl -analysis -hosts /home/gwos/autosetuplinux/hosts.txt
-version Prints version information
- Example: ./auto_wrapper.pl -version
-help Prints help information
- Example: ./auto_wrapper.pl -help

An Example Workflow

Go to the Downloads page under the Tools section to download the auto_wrapper ansible playbook tool, expand the file and place it in the home directory of the gwos user (e.g., /home/gwos, or other user that was created during your GroundWork installation).
Change to the directory where the auto_wrapper.pl resides, and run the following status command to ensure a valid output in the form of a (likely empty) table is returned:
```
cd /home/gwos/autosetuplinux
./auto_wrapper.pl -status
```
CODE

Adjust instructions/linuxpattern_instructions if desired:

cd /home/gwos/autosetuplinux/instructions
vi linuxpattern_instructions

CODE

Adjust instructions/linuxpattern_trigger if desired:

cd /home/gwos/autosetuplinux/trigger
vi linuxpattern_trigger

CODE

Add desired hosts by DNS name to hosts.txt, one host per line in the file is all that is required here:
```
cd /home/gwos/autosetuplinux
vi hosts.txt
```
CODE
If using new services (not already existing in your GroundWork Monitor instance), copy the profile XML to the profiles directory.

Import the instructions, triggers, and profiles with the following:

cd /home/gwos/autosetuplinux
./auto_wrapper.pl -import -directory /home/gwos/autosetuplinux/

CODE

Install the instructions and trigger file for a host:

./auto_wrapper.pl -hosts /home/gwos/autosetuplinux/hosts.txt -install linuxpattern

CODE

Ensure the status returns an install time for instructions and trigger for the new host:
```
./auto_wrapper.pl -status
```
CODE
Install GDMA on the host, selecting Auto Setup as the installation option.
Check status again after installation, the host should now have a timestamp for the results and analysis columns:
```
./auto_wrapper.pl -status
```
CODE

If desired, more detail on the results and analysis can be found using the following:

./auto_wrapper.pl -hosts /home/gwos/autosetuplinux/hosts.txt -results

CODE

or

./auto_wrapper.pl -hosts /home/gwos/autosetuplinux/hosts.txt -analysis

CODE

Using the Ansible Playbook for Automated GDMA Installation

Ansible is a powerful tool for automation, we'll use it to install GDMA, and when combined with Auto Setup, you can monitor all of the services within your Linux environment without having to assign profiles manually to hosts, or even check to see which hosts are running what software. The provided playbook will allow you to install or uninstall GDMA on a host via shared-key authentication. You can use this process of uninstall and install to upgrade all of your agents.

Prerequisites

Ansible playbook in Downloads
Ansible installed on the host and accessible by the user which is running it
Shared-key authentication to the host(s)
64-bit Linux is the only architecture currently supported by this playbook
The endpoint we install GDMA on must have python2 installed. It is possible to install python2 using Ansible to allow you to use the more advanced functions required for this playbook
If this is a requirement for your environment, please see the Ansible documentation under Managed Node Requirements, or contact GroundWork Support for an example

Steps

Adjust hosts.ini:
1. Under the [linux] directive, input the list of hosts, one per line, using the DNS name of the hosts you wish to install GDMA.
2. Under the [linux:vars] directive, input the path to your SSH shared-key (e.g., ansible_ssh_private_key_file=/home/ubuntu/.ssh/mykey.pem).
3. Under the [linux:vars] directive, input the user (which must have sudo rights to install GDMA) (e.g., ansible_ssh_user=ec2-user).
Update the agent (if necessary):
- Change directory to the agents directory.
- Copy the download link of the latest version of 64-bit GDMA.
- Download the agent to the system (e.g., wget [download link]).
- Make the installer executable:
```
chmod +x groundworkagent-*.run
```
  CODE
Adjust agents/options.txt file:
- The options gdma_target_server, gdma_autoregistration_username, and gdma_autoregistration_password should be adjusted for your environment
- Further customization of this file is possible, but not necessary to ensure the playbook runs in the context of Auto Setup, but will require adjustment should you choose to use Auto Registration instead (such as specifying a host profile)

Run the playbook

To install GDMA, run:

ansible-playbook -i hosts.ini main.yml --extra-vars 'use_hosts=linux install=true'

CODE

To uninstall GDMA run:

ansible-playbook -i hosts.ini main.yml --extra-vars 'use_hosts=linux uninstall=true'

CODE

Registration Script and Config File

Server-side actions for GDMA Auto Setup are undertaken by the registerAgentByDiscovery.pl script, which has an accompanying register_agent_by_discovery.conf config file. There may be a need to adjust options in the configuration file.

Related Resources

Page:

Auto Setup Troubleshooting
Page:

Background of Auto Setup
Page:

Configuration Reference for Auto Setup
Page:

Examples of Auto Setup
Page:

GDMA Advanced
Page:

GDMA Installation
Page:

Managing Auto Setup
Page:

Overview of Auto Setup
Page:

Practical Advice for Auto Setup
Page:

Quick Reference for Auto Setup