go-nagios

Shared Golang package for Nagios plugins

Table of contents

• Overview
• Status
• Features
• Changelog
• Examples
• Troubleshooting
  • General
  • Encoded payloads
• License
• Used by
• References

Overview

This package provides support and functionality common to monitoring plugins. While Nagios (Core and XI) are primary monitoring platform targets, the intent is to support (where feasible) all monitoring platforms compatible with Nagios plugins.

Status

While attempts are made to provide stability, this codebase is subject to change without notice and may break client code that depends on it. You are encouraged to vendor this package if you find it useful until such time that the API is considered stable.

Features

• Nagios state constants
  • state labels (e.g., StateOKLabel)
  • state exit codes (e.g., StateOKExitCode)
• Nagios CheckOutputEOL constant
  • provides a common newline format shown to produce consistent results for both Nagios Core and Nagios XI (and presumably other similar monitoring systems)
• Nagios ServiceState type
  • simple label and exit code "wrapper"
  • useful in client code as a way to map internal check results to a Nagios service state value
• Support for evaluating a given performance data value and setting the final plugin state exit code
• Support for parsing a given performance data metric string and generating one or more PerformanceData values
• Support for using a "branding" callback function to display application name, version, or other information as a "trailer" for check results provided to Nagios
  • this could be useful for identifying what version of a plugin determined the service or host state to be an issue
• Panics from client code are captured and reported
  • panics are surfaced as CRITICAL state
  • service output and error details are overridden to make panics prominent
• Optional support for emitting performance data metric for plugin output size
  • disabled by default
  • can be toggled on by client code as desired
• Optional support for emitting performance data generated by plugins
  • if not overridden by client code and if using the provided nagios.NewPlugin() constructor, a default time performance data metric is emitted to indicate total plugin runtime
• Support for collecting multiple errors from client code
• Support for explicitly omitting Errors section
  • this section is automatically omitted if no errors were recorded (by client code or panic handling code)
• Support for explicitly omitting Thresholds section
  • this section is automatically omitted if no thresholds were specified by client code
• Automatically omit LongServiceOutput section if not specified by client code
• Support for overriding text used for section headers/labels
• Support for adding/embedding a compressed and encoded payload in plugin output
• Support for decoding and decompressing encoded input (payload)
• Support for extracting (without decoding & decompressing) an encoded payload from captured plugin output
• Support for extracting, decoding and decompressing an encoded payload (into the original non-encoded form) from captured plugin output
• Optional debug logging for plugin activity
  • debug log output is sent to stderr by default but can be redirected to a custom target
  • toggles are provided to enable debug logging for all plugin activity or for select types

Changelog

See the CHANGELOG.md file for the changes associated with each release of this application. Changes that have been merged to master, but not yet an official release may also be noted in the file under the Unreleased section. A helpful link to the Git commit history since the last official release is also provided for further review.

Examples

Add this line to your imports like so:

package main

import (
  "fmt"
  "log"
  "os"

  "github.com/atc0005/go-nagios"
)

and pull in a specific version of this library that you'd like to use.

go get github.com/atc0005/go-nagios@v0.9.0

Alternatively, you can use the latest stable tag available to get started:

go get github.com/atc0005/go-nagios@latest

See https://pkg.go.dev/github.com/atc0005/go-nagios for specific examples.

See https://pkg.go.dev/github.com/atc0005/go-nagios?tab=importedby for projects that are using this library.

Troubleshooting

General

Enable debug logging.

While this output is sent to stderr by default, it can be redirected to a custom target to prevent debugging details from this library from mixing with stderr content emitted directly by your plugin.

Encoded payloads

The current encoding format is Ascii85. The character set used complies with Nagios character set restrictions and in general doesn't cause issues either when consumed by monitoring systems (when emitted as part of plugin output) or downstream systems consuming notifications.

One notable exception is when Nagios notifications are sent to a Mailman mailing list.

In at least one case Mailman heuristics incorrectly detected an email notification with an embedded payload as binary. The hotfix for that situation for a Nagios XI instance running on RHEL 8 was:

1. Install the mutt email CLI package
2. Update Nagios to use /usr/bin/mutt in place of /bin/mail (provided by the mailx package)
3. Explicitly add a Content-Type header with value of text/plain

Prior to those changes the custom notify-service-by-email-verbose command definition was:

/usr/bin/printf "%b" "\n***** Nagios Monitor XI Alert *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTNAME$\nHost Description: $HOSTALIAS$\nHost Notes: $HOSTNOTES$\nService Notes: $SERVICENOTES$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nService Output:\n\n$SERVICEOUTPUT$\n\nAdditional Service Output (if available):\n\n$LONGSERVICEOUTPUT$\n" | /bin/mail -r "sender@example.com" -s "** $NOTIFICATIONTYPE$ Service Alert: \"$SERVICEDESC$\" for $HOSTNAME$ is $SERVICESTATE$ **" $CONTACTEMAIL$

This replaced the stock notify-service-by-email command which did not expose LongServiceOutput details.

After swapping /bin/mail for /usr/bin/mutt the command definition looks like:

/usr/bin/printf "%b" "\n***** Nagios Monitor XI Alert *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTNAME$\nHost Description: $HOSTALIAS$\nHost Notes: $HOSTNOTES$\nService Notes: $SERVICENOTES$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nService Output:\n\n$SERVICEOUTPUT$\n\nAdditional Service Output (if available):\n\n$LONGSERVICEOUTPUT$\n" | /usr/bin/mutt -e 'my_hdr From:sender@example.com' -e 'set content_type=text/plain' -s "** $NOTIFICATIONTYPE$ Service Alert: \"$SERVICEDESC$\" for $HOSTNAME$ is $SERVICESTATE$ **" $CONTACTEMAIL$

Specifically, this is the replacement command for /bin/mail:

-/bin/mail -r "sender@example.com" -s "** $NOTIFICATIONTYPE$ Service Alert: \"$SERVICEDESC$\" for $HOSTNAME$ is $SERVICESTATE$ **" $CONTACTEMAIL$
+/usr/bin/mutt -e 'my_hdr From:sender@example.com' -e 'set content_type=text/plain' -s "** $NOTIFICATIONTYPE$ Service Alert: \"$SERVICEDESC$\" for $HOSTNAME$ is $SERVICESTATE$ **" $CONTACTEMAIL$

License

From the LICENSE file:

MIT License

Copyright (c) 2020 Adam Chalkley

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Used by

See the Known importers lists below for a dynamically updated list of projects using either this library or the original project.

• Known importers (pkg.go.dev)
• https://github.com/infraweavers/monitoring-agent-check-nt-replacement

References

• Nagios
  • https://github.com/nagios-plugins/nagios-plugins/blob/master/plugins-scripts/utils.sh.in
  • https://nagios-plugins.org/doc/guidelines.html
  • https://www.monitoring-plugins.org/doc/guidelines.html
  • https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/4/en/pluginapi.html
  • https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/4/en/perfdata.html
  • https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/4/en/macrolist.html
  • max plugin output length
  • character restrictions applicable to LongServiceOutput macro
• Icinga
  • https://icinga.com/docs/icinga-2/latest/doc/05-service-monitoring/#plugin-api
  • https://icinga.com/docs/icinga-2/latest/doc/05-service-monitoring/#service-monitoring-plugin-api-performance-data-metrics
• Go Modules
  • https://www.ardanlabs.com/blog/2020/04/modules-06-vendoring.html
  • https://github.com/golang/go/wiki/Modules
• Panics, stack traces
  • https://www.golangprograms.com/example-stack-and-caller-from-runtime-package.html

See also the Used by section for projects known to be using this package. Please report any additional projects that we've missed!