check-illiad

Go-based tooling to check/verify an ILLiad server instance.

Table of Contents

• Project home
• Overview
• Features
• Status
• Changelog
• Requirements
  • Building source code
  • Running
• Installation
  • From source
  • Using release binaries
• Configuration
  • Precedence
  • Command-line Arguments
  • Environment Variables
• Example
  • Default thresholds
• License
• Related projects
• References

Project home

See our GitHub repo for the latest code, to file an issue or submit improvements for review and potential inclusion into the project.

Overview

This repo is intended to provide Nagios plugins that may be used to monitor an ILLiad instance. As of this writing, a plugin named check_illiad_emails is available that may be used to monitor email notifications.

Features

The check_illiad_emails plugin supports monitoring Pending email notifications:

• with a greater number queued than specified
• that have remained "in the queue" for longer than a specified amount of time

Default values are provided, but are easily overridden with custom values in order to match usage patterns for each instance.

Status

As of this writing, this plugin is just leaving the bench for real-world use. There may be bugs or minor issues present. Please report any issues that you encounter.

Changelog

See the CHANGELOG.md file for the changes associated with each release of this application.

Requirements

The following is a loose guideline. Other combinations of Go and operating systems for building and running tools from this repo may work, but have not been tested.

Building source code

• Go
  • see this project's go.mod file for preferred version
  • this project tests against officially supported Go releases
    • the most recent stable release (aka, "stable")
    • the prior, but still supported release (aka, "oldstable")
• GCC
  • if building with custom options (as the provided Makefile does)
• make
  • if using the provided Makefile

Running

• Windows 10
• Ubuntu Linux 18.04+

Installation

From source

1. Download Go
2. Install Go
   • NOTE: Pay special attention to the remarks about $HOME/.profile
3. Clone the repo
   1. cd /tmp
   2. git clone https://github.com/atc0005/check-illiad
   3. cd check-illiad
4. Install dependencies (optional)
   • for Ubuntu Linux
     • sudo apt-get install make gcc
   • for CentOS Linux
     • sudo yum install make gcc
   • for Windows
     • Emulated environments (easier)
       • Skip all of this and build using the default go build command in Windows (see below for use of the -mod=vendor flag)
       • build using Windows Subsystem for Linux Ubuntu environment and just copy out the Windows binaries from that environment
       • If already running a Docker environment, use a container with the Go tool-chain already installed
       • If already familiar with LXD, create a container and follow the installation steps given previously to install required dependencies
     • Native tooling (harder)
       • see the StackOverflow Question 32127524 link in the References section for potential options for installing make on Windows
       • see the mingw-w64 project homepage link in the References section for options for installing gcc and related packages on Windows
5. Build binaries
   • for the current operating system, explicitly using bundled dependencies in top-level vendor folder
     • go build -mod=vendor ./cmd/check_illiad_emails/
   • for all supported platforms (where make is installed)
     • make all
   • for use on Windows
     • make windows
   • for use on Linux
     • make linux
6. Copy the newly compiled binary from the applicable /tmp subdirectory path (based on the clone instructions in this section) below and deploy where needed.
   • if using Makefile
     • look in /tmp/check-illiad/release_assets/check_illiad_emails/
   • if using go build
     • look in /tmp/check-illiad/

NOTE: Depending on which Makefile recipe you use the generated binary may be compressed and have an xz extension. If so, you should decompress the binary first before deploying it (e.g., xz -d check_illiad_emails-linux-amd64.xz).

Using release binaries

1. Download the latest release binaries
2. Decompress binaries
   • e.g., xz -d check_illiad_emails-linux-amd64.xz
3. Rename binaries
4. Deploy
   • Place check_illiad_emails in the same location where your distro's package manager places other Nagios plugins
     • as /usr/lib/nagios/plugins/check_illiad_emails on Debian-based systems
     • as /usr/lib64/nagios/plugins/check_illiad_emails on RedHat-based systems

NOTE:

DEB and RPM packages are provided as an alternative to manually deploying binaries.

Configuration

Precedence

The priority order is:

1. Command line flags (highest priority)
2. Environment variables
3. Default settings (lowest priority)

In general, command-line options are the primary way of configuring settings for this application, but environment variables are also a supported alternative. Most plugin settings require that a value be specified by the sysadmin, though some (e.g., logging) have useful defaults.

Command-line Arguments

• Flags marked as required must be set via CLI flag or environment variable.
• Flags not marked as required are for settings where a useful default is already defined.

Option	Required	Default	Repeat	Possible	Description
h, help	No	false	No	h, help	Show Help text along with the list of supported flags.
emit-branding	No	false	No	true, false	Toggles emission of branding details with plugin status details. This output is disabled by default.
log-level	No	info	No	disabled, panic, fatal, error, warn, info, debug, trace	Log message priority filter. Log messages with a lower level are ignored.
host	Yes	empty list	No	valid fqdn or IP Address	The hostname of the database server hosting the database used by the ILLiad software. If using encryption, this value should match one of the Subject Alternate Name (SANs) values listed on the certificate.
port	No	false	No	true, false	The TCP port used to connect to the database server. If not specified, the default port will be used.
instance	No	empty string	No	valid instance name	The database server instance name. This may be blank.
db-name	Yes	empty string	No	valid database name	The name of the database used by ILLiad software and checked by plugins from this project.
username	Yes	empty string	No	valid username	The username used to connect to the database server. An account with read-only access to the database used by the ILLiad software is sufficient.
password	Yes	empty string	No	valid password	The plaintext password used to connect to the database server. An account with read-only access to the database used by the ILLiad software is sufficient.
encrypt-mode	No	false	No	true, false, disable	Whether data sent between client and server is encrypted. true for yes, false for login packet only and disable for no encryption.
trust-cert	No	false	No	true, false	Whether the certificate should be trusted as-is without validation. WARNING: TLS is susceptible to man-in-the-middle attacks if enabling this option.
ignore-missing-emails	No	false	No	true, false	Whether finding zero email notifications recorded in the database used by ILLiad software should be treated as an OK state. Legitimate scenarios include fresh ILLiad installations or recent purge of history.
count-warning	No	1	No	1+ (minimum of 1)	The number of pending email notifications when this plugin will consider the service check to be in a WARNING state.
count-critical	No	3	No	2+ (minimum 1 greater than warning)	The number of pending email notifications when this plugin will consider the service check to be in a CRITICAL state.
age-warning	No	5	No	1+ (minimum of 1)	The number of minutes an email notification has been in a pending status when this plugin will consider the service check to be in a WARNING state.
age-critical	No	10	No	2+ (minimum 1 greater than warning)	The number of minutes an email notification has been in a pending status when this plugin will consider the service check to be in a CRITICAL state.

Environment Variables

If used, command-line arguments override the equivalent environment variables listed below. See the Command-line Arguments table for more information.

Flag Name	Environment Variable Name	Notes	Example (mostly using default values)
emit-branding	CHECK_ILLIAD_EMAILS_EMIT_BRANDING		CHECK_ILLIAD_EMAILS_EMIT_BRANDING="false"
log-level	CHECK_ILLIAD_EMAILS_LOG_LEVEL		CHECK_ILLIAD_EMAILS_LOG_LEVEL="info"
host	CHECK_ILLIAD_DBSERVER_HOST		CHECK_ILLIAD_DBSERVER_HOST="mssql52.example.com"
port	CHECK_ILLIAD_DBSERVER_PORT		CHECK_ILLIAD_DBSERVER_PORT="1433"
instance	CHECK_ILLIAD_DBSERVER_INSTANCE		CHECK_ILLIAD_DBSERVER_INSTANCE="mssql07"
db-name	CHECK_ILLIAD_DATABASE_NAME		CHECK_ILLIAD_DATABASE_NAME="ILLData"
username	CHECK_ILLIAD_DBSERVER_USERNAME		CHECK_ILLIAD_DBSERVER_USERNAME="dbuser"
password	CHECK_ILLIAD_DBSERVER_PASSWORD		CHECK_ILLIAD_DBSERVER_PASSWORD="dbPasW0rdZ"
encrypt-mode	CHECK_ILLIAD_DBSERVER_ENCRYPT_MODE		CHECK_ILLIAD_DBSERVER_ENCRYPT_MODE="false"
trust-cert	CHECK_ILLIAD_TRUST_CERT		CHECK_ILLIAD_TRUST_CERT="false"
ignore-missing-emails	CHECK_ILLIAD_IGNORE_MISSING_EMAILS		CHECK_ILLIAD_IGNORE_MISSING_EMAILS="false"
count-warning	CHECK_ILLIAD_COUNT_WARNING		CHECK_ILLIAD_COUNT_WARNING="1"
count-critical	CHECK_ILLIAD_COUNT_CRITICAL		CHECK_ILLIAD_COUNT_CRITICAL="3"
age-warning	CHECK_ILLIAD_AGE_WARNING		CHECK_ILLIAD_AGE_WARNING="5"
age-critical	CHECK_ILLIAD_AGE_CRITICAL		CHECK_ILLIAD_AGE_CRITICAL="10"

Example

Default thresholds

$ ./check_illiad_emails --host mssql52.example.com --port 1433 --instance mssql07 --username dbuser --password 'dbPasW0rdZ' --encrypt-mode false --trust-cert --db-name illdata
OK: 0 email notifications in a pending state found without crossing specified thresholds

**ERRORS**

* None

**THRESHOLDS**

* CRITICAL: [Age: 10m0s, Count: 3]
* WARNING: [Age: 5m0s, Count: 1]

**DETAILED INFO**

* Database Connection
** Host: "mssql52.example.com"
** Port: 1433
** Instance: "mssql07"
** Database: "illdata"
** Encryption Mode: "false"
** Trust Server Cert (disable verification): true

License

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.

Related projects

• https://github.com/atc0005/go-nagios
• https://github.com/atc0005/check-mail
• https://github.com/atc0005/check-cert
• https://github.com/atc0005/check-path

References

• https://github.com/denisenkom/go-mssqldb

• https://github.com/rs/zerolog

• https://github.com/alexflint/go-arg

• https://github.com/phayes/permbits

• https://github.com/atc0005/go-nagios

• https://support.atlas-sys.com/hc/en-us/categories/360000716874-ILLiad

• https://nagios-plugins.org/doc/guidelines.html