<host "unique tag">    sensor directives</host>

host_profile = "my-host-profile"

This is the form for applying a host profile and whatever service profiles are attached to that host profile.

<service "unique tag">    sensor directives</service>

service_profile = "my‑service‑profile"

Apply the given service profile to the host if the sensor matches.  This form leads to a proliferation of service profiles and is therefore not often used.

service = "my_service"

This is the common form for configuring services.

Fixed sensors

type = os_type

Yields one of:  aix linux solaris windows

type = os_version

Yields an OS-specific string, such as 7.9.2009 on one particular release of CentOS 7.

type = os_bitwidth

Yields one of:  32 64

type = machine_architecture

Yields one of:  arm intel powerpc sparc

Static sensors

type = file_name
type = symlink_name
type = directory_name

resource = "fileglobs"
Searches the filesystem and matches file paths, symlink paths, or directory paths, respectively, against the provided fileglobs.  Yields the full filepaths of the specified resources.

type = mounted_filesystem

resource = "filesystem types" (optional)

Searches active filesystem mount points and matches the specified filesystem types.  Yields their respective mount-point filepaths.

type = file_content

resource = "fileglobs"

Yields every line of every file specified by the resource.

Dynamic sensors

type = running_system_service

Yields OS-specific strings representing all services currently running on the machine.

type = full_process_command

resource = "userlist" (optional)

Yields the full command lines of all processes being run as one of the specified users.

type = open_local_port

resource = "IP address blocks"

Yields the port numbers of all listening ports on the GDMA client machine within the specified IP address block(s), which represent networks to which the machine might be connected.  IP address ranges can also be negated and thereby excluded from consideration via the resource directive.

type = open_named_socket

Yields strings usually (but not always) representing filesystem paths, of all open named sockets on the GDMA client machine.

type

Specifies what kind of resource you will be probing.  See the Sensor Types table above.

resource

Limits the resources against which the pattern will be matched.  The particular form of the resource specification depends on the sensor type; see the Sensor Types table above.

cardinality

Specifies how many times the pattern is allowed to be matched.  Must be either single, first, or multiple.  If omitted, defaults to single.  Requires a companion instance_suffix directive if set to multiple.

pattern

Specifies a Perl regular expression to be matched against whatever the sensor type yields, as qualified by the specified resource (if any).  Captured sub-expression fields will be further processed in the course of generating the rest of the object configuration.

transliteration

Specifies character-level substitutions, deletions, and consecutive-duplicate-character squashing that should be carried out on strings captured by pattern matching, before further processing.  May be specified zero or more times in a single sensor definition.

sanitization

Specifies which characters in pattern-match string results are to be preserved after all transliteration transforms are applied.  Optional.  Often used to filter out possible shell metacharacters, as a security precaution.

host_profile

Name of the host profile to be applied to this GDMA machine if the sensor matches resources on the machine.

service_profile

Name of the service profile to be applied to this GDMA machine if the sensor matches resources on the machine.

service

Name of the service to be applied to this GDMA machine if the sensor matches resources on the machine.  More than one instance of the service may be applied, if the cardinality is multiple.

check_command

Overrides the server-side check command in every host service generated by this sensor.

command_arguments

Arguments to be applied to the check command.

externals_arguments

Arguments to be substituted into the service externals for each service generated by this sensor.  Optional, no default.

instance_suffix

Specifies how a service-instance suffix is constructed for every service generated from this sensor.  Optional if cardinality is single or first; mandatory if cardinality is multiple.

instance_cmd_args

Specifies the service-instance command arguments for each service generated from this sensor.  Optional.

instance_ext_args

Optional; if not supplied, service-instancel-level instance arguments will be inherited from those for the base base service.

enabled

Specifies whether matching of this sensor definition should be attempted.  May be yes, on, true, 1, no, off, false, or 0.  Optional; defaults to yes.

if_duplicate

Specify how discovery results are to be handled if they duplicate what happened in the last round of similar-type (dry-run or live-action) discovery.  In all cases, the discovery results are logged on the GDMA client.  Optional; defaults to optimize.

ignore

Stop after logging results on the client.  Do not send results to the server even if last_step is send_results or a later value in the table below.

optimize

Stop after logging results on the client, unless this is a live-action discovery (last_step is do_configuration) and the client has not yet seen updated externals on the server.  This allows overriding possible residual blockage from previous failures, but only in cases where it might do some good, so no effort is wasted on the server.

force

After logging results on the client, carry on and do exactly what last_step specifies.  This may result in wasted effort, but it also provides a means to forcibly override possible residual blockage from previous failures and run the auto-setup processing to completion.

soft_error_reporting

Specify how error reporting is to be handled if problems occur while analyzing discovery results or applying configuration changes in a dry run (i.e., when last_step is either do_analysis or test_configuration).  Optional; defaults to ignore.

ignore

Ignore errors, except for saving them where they can be seen with the autosetup tool.

post

Save errors where they can be seen with the autosetup tool, and also post them to the GroundWork server as a WARNING-level event (since this was just a dry run).

change_policy

Override the server-side specification of the change_policy in its entirety, for processing discovery results from this one pass of auto-discovery.  The change_policy directive in a trigger file is optional; the server's configured change_policy is already set to non_destructive.  This directive is provided only as a first step toward possible future elaboration of the supported change policies.

non_destructive

Make no changes to any existing configuration setup; only add new objects to the configuration.

last_step

Specify how far the auto-discovery and auto-setup processing should proceed.  This directive is required in all trigger files.

ignore_instructions

The GDMA client should not attempt to download or process the instructions file.  Used to test that the client can locate and download the trigger file.  Since nothing is sent back to the server, you would need to look in the GDMA poller logfile on the client to see the result of this test.

fetch_instructions

The GDMA client should attempt to download the instructions file, but stop there.  Used to test that the client can locate and download the instructions file in addition to the trigger file.  Since nothing is sent back to the server, you would need to look in the GDMA poller logfile on the client to see the result of this test.

do_discovery

The GDMA client should run auto-discovery, but just capture them in a local file and not send them to the GroundWork server.  May be used to test the discovery process if you would rather edit a copy of the instructions file on the client and use the discover program locally there.  Such usage can speed up initial development of sensor definitions.

send_results

The GDMA client should send discovery results to the GroundWork server, whether or not discovery worked.  The server will perform minimal validation of the results and store them if the data is not corrupted, but stop there.

do_analysis

The GroundWork server should perform full validation of the discovery results and store the analysis for forensic purposes, but stop there.

test_configuration

The GroundWork server should perform a dry run of configuration database changes, then roll them back out.  Used to test end-to-end validity of discovery instructions and compatibility of the discovery results with profiles and service definitions on the server, without risking any changes to the current configuration.

do_configuration

The GroundWork server should fold all configuration changes into the database, commit them there, and build externals for the GDMA client.  Thereafter, the client will pick up the new externals and begin monitoring with them, while Nagios will not see the new setup until the next time the administrator runs a Monarch Commit operation.

discovery_trigger

# local trigger file, for use with
# the gdma/bin/discover tool on a
# GDMA client
last_step = "do_discovery"

Parked on the GDMA client itself and used when developing sensor definitions there, for fast turnaround (not waiting for the GDMA polling cycle to come around, but initiating discovery whenever you want via the discover tool on the client).  This trigger file is appropriate when individual sensor definitions are at issue.

analysis_trigger

# local trigger file, for use with
# the gdma/bin/discover tool on a
# GDMA client
soft_error_reporting = "ignore"
change_policy = "non_destructive"
last_step = "do_analysis"

Parked on the GDMA client itself and used when developing sensor definitions there, for fast turnaround (not waiting for the GDMA polling cycle to come around, but initiating discovery whenever you want via the discover tool on the client).  The analysis on the server goes beyond separately validating discovery results from individual sensors, and compares results of multiple sensors to verify that they do not collide.  While discovery will be initiated on the client, the analysis can be viewed using the autosetup tool on the server.

dry_run_forced_trigger

# dry-run trigger file that forces
# end-to-end operation even in the
# presence of repeated discovery
# results, for use either with the
# gdma/bin/discover tool on a GDMA
# client or from the server
if_duplicate = "force"
soft_error_reporting = "ignore"
change_policy = "non_destructive"
last_step = "test_configuration"

Parked either on the GDMA client or the GroundWork server.  Used when the discovery instructions seem to be working as intended, but there is some trouble on the server side with configuration objects in Monarch that prevents final configuration based on the discovery results.  Forcing duplicate discovery results to be sent to the server allows repeated dry-run tests as the server-side configuration objects (profiles and services) are adjusted.

dry_run_trigger

# dry-run trigger file,
# for tentative testing
if_duplicate = "optimize"
soft_error_reporting = "ignore"
change_policy = "non_destructive"
last_step = "test_configuration"

Parked on the GDMA server and installed by the autosetup tool.  Used for dry runs when applying discovery instructions to a GDMA client and you are satisfied with waiting for the GDMA polling cycle to start again, at which point another pass of discovery can proceed.

live_action_trigger

# live-action trigger file,
# for production use
if_duplicate = "optimize"
change_policy = "non_destructive"
last_step = "do_configuration"

Parked on the GDMA server and installed by the autosetup tool.  Used for production runs when applying discovery instructions to a GDMA client.  Discovery will begin when the GDMA client starts its next polling cycle.