ncr

README

Nagios check runner

Run nagios-compatible plugins locally and publish their results anywhere you can think of.

Nagios check runner was originally conceived as a replacement for NRPE, designed to run checks locally and publish their results as passive checks using NSCA-ng.

It has grown to support multiple output plugins, potentially making it useful even without a traditional Nagios/Icinga setup. Small one-person shop with just one or two servers to monitor? Receive reports by email when services go down or transmit them to Sentry.

Using a PAAS monitoring solution but want to tap into the thousands of Nagios plugins already available? Publish results to a webhook as HTTP events.

Submitting passive check results to Icinga using NSCA-ng

Note: If you look closely you'll see a delay in between the check result being submitted and the service state updating in Icinga. This is not a bug in the runner but a delay in NSCA-ng submitting the event to Icinga and Icinga's event loop picking up the change.

Submitting check results to Sentry

Configuration

Configuration is split up in two parts, checks and publishers. For example:

publishers:
  nsca_ng:
    type: ExecPublisher
    cmd: /usr/sbin/send_nsca
    stdin: |
        myhost	{{ .Name }}	{{ .Returncode }}	{{ .Output | printf "%s" }}

checks:
  Local SMTP:
    command: /usr/lib/nagios/plugins/check_smtp -H localhost
    interval: 30
    retry: 10
    timeout: 3

  System load:
    command: /usr/lib/nagios/plugins/check_load -r -w 3,2,2 -c 5,3,3
    interval: 60
    retry: 60
    timeout: 10

Checks define the checks to be run. The title is the service name and the options it takes are as follows:

• command: The command to be run.
• interval: The interval to run this plugin when it is in OK state.
• retry: The interval to run this plugin when it returns a state other than OK.
• timeout: Kills the process if it does not finish within this time limit.

Publishers defines the publishers to which check results should be published. The available publishers and their options are detailed below. All entries under publishers take a descriptive name of your own choosing and must have a type element listing the publisher to be used from the list below.

SpewPublisher

This is a debug publisher, useful for local development. It prints check results to stdout.

ExecPublisher

Executes an external command for every received result. This allows for complete freedom in what to do with check results and can be used to publish results as passive checks using nsca-ng, as email by feeding it to mail/sendmail or some other custom script of your choosing.

Options:

• cmd: The path to the script/binary to be run.

• stdin: A text template describing what data is to be fed as input over stdin to the specified cmd. It uses Go text/template templating.

  Available template values are .Name, .Returncode, and .Output.

SentryPublisher

Publishes results as messages to the exception tracking system Sentry.

Options:

• dsn: The DSN of the project to submit to.
• hostname (optional): The hostname to report to sentry.

Building

• Make sure you have setup Go.
• Make sure you have setup a workspace.
  • If you haven't:
  • mkdir ~/go
  • export GOPATH=~/go
• Get the source: go get github.com/zoni/nagios-check-runner
• Change into the source directory: cd $GOPATH/src/github.com/zoni/nagios-check-runner
• Get missing dependencies: go get ./...
• Build the binary: go build cmd/ncr.go
• The binary will be available as ./ncr

Testing

• Follow the instructions under Building to set up a correct source tree.
• Then: go test -race -cover

License

The MIT license. See LICENSE for full license text.

Documentation

Index

• Constants
• Variables
• type Check
• type CheckResult
• type Checker
• type Config
  • func ReadConfig(src io.Reader) (*Config, error)
• type Error
  • func (e Error) Error() string
• type ExecPublisher
  • func (p *ExecPublisher) Configure(cfg map[string]interface{}) error
  • func (p *ExecPublisher) Publish(result *CheckResult) error
  • func (p *ExecPublisher) Start() error
  • func (p *ExecPublisher) Stop() error
• type ExecPublisherConfig
• type MemoryPublisher
  • func (p *MemoryPublisher) Configure(cfg map[string]interface{}) error
  • func (p *MemoryPublisher) EventCount(checkname string) int
  • func (p *MemoryPublisher) GetEvent(checkname string, index int) *CheckResult
  • func (p *MemoryPublisher) Publish(result *CheckResult) error
  • func (p *MemoryPublisher) Start() error
  • func (p *MemoryPublisher) Stop() error
• type Publisher
• type Runner
  • func NewRunner(cfg Config) (*Runner, error)
  • func NewRunnerFromFile(filename string) (*Runner, error)
  • func (r *Runner) Init(cfg Config) error
  • func (r *Runner) Run() error
  • func (r *Runner) Start() error
  • func (r *Runner) Stop() error
• type SentryPublisher
  • func (p *SentryPublisher) Configure(cfg map[string]interface{}) error
  • func (p *SentryPublisher) Publish(result *CheckResult) error
  • func (p *SentryPublisher) Start() error
  • func (p *SentryPublisher) Stop() error
• type SentryPublisherConfig
• type SpewPublisher
  • func (p *SpewPublisher) Configure(cfg map[string]interface{}) error
  • func (p *SpewPublisher) Publish(result *CheckResult) error
  • func (p *SpewPublisher) Start() error
  • func (p *SpewPublisher) Stop() error
• type SpewPublisherConfig

Constants

const (
	StateOk       = 0
	StateWarning  = 1
	StateCritical = 2
	StateUnknown  = 3
)

const (
	ErrInvalidConfig = iota
)

Variables

var Log = log.New()

Types

type Check

type Check struct {
	Name    string
	Command string
	Args    []string // Command after being parsed according to shell quoting rules

	Interval int
	Retry    int
	Timeout  int
}

Check describes an individual nagios check.

type CheckResult

type CheckResult struct {
	Name       string // Check name
	Output     []byte // Output returned by the command
	Returncode int    // Exitcode of the command
}

CheckResult describes the result of a given check.

type Checker

type Checker interface {
	Start() (chan *CheckResult, error)
	Stop() error
	RegisterChecks(checks map[string]Check)
}

Checker schedules and executes checks to be run.

type Config

type Config struct {
	Publishers map[string]map[string]interface{}
	Hostname   string
	Checks     map[string]Check
}

Config describes the full agent configuration.

func ReadConfig

func ReadConfig(src io.Reader) (*Config, error)

ReadConfig loads configuration from the given source and returns a fully initialized Configuration struct from it.

type Error

type Error struct {
	Code    int
	Message string
}

func (Error) Error

func (e Error) Error() string

type ExecPublisher

type ExecPublisher struct {
	// contains filtered or unexported fields
}

ExecPublisher is a Publisher which executes an external program whenever a check result is received.

func (*ExecPublisher) Configure

func (p *ExecPublisher) Configure(cfg map[string]interface{}) error

Configure sets the configuration to be used by the publisher.

func (*ExecPublisher) Publish

func (p *ExecPublisher) Publish(result *CheckResult) error

Publish prints the result of a check to stdout.

func (*ExecPublisher) Start

func (p *ExecPublisher) Start() error

Start starts this publisher.

func (*ExecPublisher) Stop

func (p *ExecPublisher) Stop() error

Stop stops this publisher.

type ExecPublisherConfig

type ExecPublisherConfig struct {
	Cmd   string // The command to execute on Publish
	Stdin string // Template to use to format stdin to Cmd
}

ExecPublisherConfig describes the configuration used by the ExecPublisher.

type MemoryPublisher

type MemoryPublisher struct {
	sync.Mutex
	// contains filtered or unexported fields
}

MemoryPublisher is a simple Publisher which stores all check results in memory. This publisher is used for testing and is not meant to be used normally.

func (*MemoryPublisher) Configure

func (p *MemoryPublisher) Configure(cfg map[string]interface{}) error

Configure sets the configuration to be used by the publisher.

func (*MemoryPublisher) EventCount

func (p *MemoryPublisher) EventCount(checkname string) int

func (*MemoryPublisher) GetEvent

func (p *MemoryPublisher) GetEvent(checkname string, index int) *CheckResult

func (*MemoryPublisher) Publish

func (p *MemoryPublisher) Publish(result *CheckResult) error

func (*MemoryPublisher) Start

func (p *MemoryPublisher) Start() error

Start starts this publisher.

func (*MemoryPublisher) Stop

func (p *MemoryPublisher) Stop() error

Stop stops this publisher.

type Publisher

type Publisher interface {
	// Start tells a Publisher to start so it can begin accepting check results.
	// It should be called after Configure.
	Start() error

	// Stop tells a Publisher to shut down.
	// No more check results may be published to it after calling Stop.
	Stop() error

	// Configure sets the configuration to be used by the Publisher.
	// It should be called before Start.
	Configure(cfg map[string]interface{}) error

	// Publish accepts a CheckResult to be published.
	// It should be safe for concurrent calling by multiple goroutines.
	Publish(*CheckResult) error
}

Publisher publishes CheckResults.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner is the main component of the application. It runs the Checker and Publisher subcomponents and facilitates communication between them.

func NewRunner

func NewRunner(cfg Config) (*Runner, error)

NewRunner creates a new Runner with the given configuration.

func NewRunnerFromFile

func NewRunnerFromFile(filename string) (*Runner, error)

NewRunnerFromFile creates a new Runner using the configuration loaded from the given file.

func (*Runner) Init

func (r *Runner) Init(cfg Config) error

Init initializes the Runner with the given configuration.

func (*Runner) Run

func (r *Runner) Run() error

Run starts the runner and blocks until an interrupt signal is received.

func (*Runner) Start

func (r *Runner) Start() error

Start starts the Runner and begins running checks, publishing them as they complete.

func (*Runner) Stop

func (r *Runner) Stop() error

Stop stops and shuts down the Runner.

type SentryPublisher

type SentryPublisher struct {
	// contains filtered or unexported fields
}

SentryPublisher is a Publisher which publishes non-OK check results to Sentry (https://getsentry.com/)

func (*SentryPublisher) Configure

func (p *SentryPublisher) Configure(cfg map[string]interface{}) error

Configure sets the configuration to be used by the publisher.

func (*SentryPublisher) Publish

func (p *SentryPublisher) Publish(result *CheckResult) error

Publish publishes the CheckResult to Sentry if it has a state other than StateOk.

func (*SentryPublisher) Start

func (p *SentryPublisher) Start() error

Start starts this publisher.

func (*SentryPublisher) Stop

func (p *SentryPublisher) Stop() error

Stop stops this publisher.

type SentryPublisherConfig

type SentryPublisherConfig struct {
	Dsn      string // The project DSN to use
	Hostname string // The hostname to report to sentry
}

SentryPublisherConfig describes the configuration used by the SentryPublisher.

type SpewPublisher

type SpewPublisher struct {
	// contains filtered or unexported fields
}

SpewPublisher is a publisher which simply spews check results to stdout. This publisher is mainly useful for debugging and to use as a simple reference implementation for a Publisher.

func (*SpewPublisher) Configure

func (p *SpewPublisher) Configure(cfg map[string]interface{}) error

Configure sets the configuration to be used by the publisher.

func (*SpewPublisher) Publish

func (p *SpewPublisher) Publish(result *CheckResult) error

Publish prints the result of a check to stdout.

func (*SpewPublisher) Start

func (p *SpewPublisher) Start() error

Start starts this publisher.

func (*SpewPublisher) Stop

func (p *SpewPublisher) Stop() error

Stop stops this publisher.

type SpewPublisherConfig

type SpewPublisherConfig struct {
}

SpewPublisherConfig describes the configuration used by the SpewPublisher.