Unit testing for the cloud
Go Other
Latest commit d83b185 Jun 7, 2016 @siddharthist siddharthist Merge pull request #158 from CiscoCloud/docs/readme-glide
readme: replace godep with glide
Failed to load latest commit information.
checklists checklists: more informative error when check can't be parsed May 31, 2016
checks Register DockerRunningRegexp and DockerImageRegexp Jun 1, 2016
chkutil refactoring: caseless verbs May 23, 2016
dockerstatus dockerstatus_test: only error on non-empty lists May 31, 2016
errutil Merge branch 'master' into feature/rearchitecture Sep 16, 2015
fsstatus don't assume presence of tmpfs May 31, 2016
memstatus memstatus_test: reduce verbosity May 31, 2016
netstatus netstatus_test: test PortOpen May 31, 2016
samples Remove name stutter from checklists package May 3, 2016
systemdstatus systemdstatus_test: reduce verbosity May 31, 2016
tabular move all source to root Sep 16, 2015
.dockerignore Add .dockerignore file Oct 28, 2015
.drone.yml Support YAML checklists, as well as JSON. Apr 20, 2016
.gitignore gitignore: ignore vendor Mar 30, 2016
.travis.yml travis: working ci! May 31, 2016
Dockerfile Progress towards dockerized testing Nov 4, 2015
LICENSE Added documentation and a LICENSE May 29, 2015
Makefile remove memstatus from testing May 31, 2016
README.md readme: replace godep with glide Jun 1, 2016
fuzz.sh Support YAML checklists, as well as JSON. Apr 20, 2016
glide.lock Support YAML checklists, as well as JSON. Apr 20, 2016
glide.yaml Support YAML checklists, as well as JSON. Apr 20, 2016
main.go refactor: proper linkage of checks/ May 23, 2016
main_test.go Merge branch 'master' into feature/rearchitecture Sep 16, 2015
options.go test with Drone CI Jan 6, 2016
options_test.go Remove absolutely non-posix stuff May 19, 2016
panic.go Global panic handling a la Terraform Oct 6, 2015


Build Status

Table of Contents


This readme documents the current (development) version of distributive.

Distributive is a tool for running distributed health checks in datacenters. It was designed with Consul in mind, but is stack agnostic. It is simple to configure (with YAML checklists) and easy to deploy and run. It has no runtime dependencies, and can be shipped as a single binary.

Usually, some external server will ask the host to execute this program, reading a checklist from a YAML file, and will record this program's exit code and standard out. Distributive's output includes information about which checks in a checklist failed, and how so.

The exit code meanings are defined as Consul, Kubernetes, Sensu, and Nagios recognize them.

  • Exit code 0 - Checklist is passing
  • Exit code 1 - Checklist is warning
  • Any other code - Checklist is failing

As of right now, only exit codes 0 and 1 are used, even if a checklist fails.

Installation and Usage


To install the development version (potentially unstable):

  1. Clone this repo: git clone https://github.com/CiscoCloud/distributive && cd distributive
  2. Get Glide.
  3. Install dependencies with glide install
  4. (Optional) Test with go test $(glide novendor)
  5. Build a binary with go build .
  6. Follow the "Usage" instructions below

Distributive currently only supports Linux.


The default behavior is to run any checks specified via --file, --url, --stdin, or --directory options, or all checks in /etc/distributive.d/ if no location is specified.

$ distributive --help
   --verbosity          info | debug | fatal | error | panic | warn
   --file, -f           Read a checklist from a file
   --url, -u            Read a checklist from a URL
   --directory, -d      Read all of the checklists in this directory
   --stdin, -s          Read data piped from stdin as a checklist
   --no-cache           Don't use a cached version of a remote check, fetch it.
   --help, -h           show help
   --version, -v        print the version


$ /path/to/distributive --verbosity="warn" -f ./samples/filesystem.yml
$ distributive --f="/etc/distributive/samples/network.yaml" --verbosity=debug
$ ./distributive -u "http://pastebin.com/raw.php?i=5c1BAxcX"
$ /distributive --verbosity="info"
$ /path/to/distributive -d "/etc/distributive.d/" # same as default behavior
$ cat samples/filesystem.yml | ./distributive -d "" -s=true --verbosity=fatal

Supported Frameworks

Distributive attempts to be as framework-agnostic as possible. It is known to work well with Consul, Kubernetes, Sensu, and Nagios, which have similar design in how they detect passing and failing checks. There is documentation on how to use Distributive with Consul on our Github wiki.


For the impatient, examples of every single implemented check are available in the samples/ directory, sorted by category. There is extensive documentation for each check available on our Github wiki.

If you'd like to see how Distributive is used in production environments, take a look at the RPM source, which includes checks used in Mantl.


Distributive itself has no dependencies; it is a standalone binary. Some checks, however, rely on output from specific commands. These dependencies are outlined for each check on our Github wiki.

Comparison to Other Software

Distributive was created with the idea of pushing responsibility to the nodes, It was also designed around the idea of constantly changing infrastructure, with servers being added and destroyed constantly, changing IP addresses, and even changing roles. Integration with Consul provides even greater flexibility.


Serverspec runs on a single control server, and requires each check to be in a directory matching the hostname of the machine to run it on. Distributive was designed for dynamic systems with changing IPs, which can report into Consul, Sensu, or another framework as soon as they are ready, and require little or no centralized configuration. Additionally, Distributive attempts to rely as little as possible on external tools/commands, using mostly just the Go standard library.


Nagios is an end-to-end monitoring, security, and notification framework. It provides many services not included in Distributive, and solves a very different problem. Distributive is simple, lightweight, and easy to configure, and doesn't provide its own scheduling, dashboard, etc. It is designed to be used within frameworks such as Sensu and Consul. Luckily, Distributive conforms to Nagios exit code specifications, and can be used just like any other plugin. Its advantage over other plugins is that it is small, fast, and has no dependencies.

Contributing and Getting Help


Thank you for your interest in contributing! To get started, please check out our wiki.

Getting Help

All comments, questions, and contributions are always welcome. We strive to provide expedient and detailed support for anyone using our software. Please submit any requests via our Github Issues Page, where someone will see it and get to work promptly.


Copyright © 2015 Cisco Systems, Inc.

Licensed under the Apache License, Version 2.0 (the "License").

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.