Skip to content

Checks and Checklists

Jump to bottom Edit New page
Langston Barrett edited this page Apr 13, 2016 · 21 revisions

Distributive checks are written in an extraordinarily simple JSON structure. Samples are aviailible in the samples/ folder.

General structure

A checklist is a single JSON file. It contains a list of logically grouped checks (according to the software they examine, for instance). Checklists have the following fields:

  • "Name"
  • Description: string : Descriptive, human readable name (optional, but recommended)
  • "Notes"
  • Description: string : Human-readable description of this checklist (optional, not used by Distributive).
  • "Checklist"
  • Description: [check] : List of checks to be run, with a structure as outlined below

A truncated example:

{
    "Name": "My first checklist",
    "Notes": "A checklist that has checks, really!",
    "Checklist": [
          ...
    ]
}

The Details

This section contains an outline of every single check that Distributive provides. For information on how to create new checks, please see THIS PAGE.

Every entry in a checklist has the following fields:

  • "Check"
  • Description: string : Type of check to be run
  • "Parameters"
  • Description: [string] : Parameters to pass to the check

Every check can also have a "Name" and "Notes", as described above.

An example:

{
    "Name": "Git installation check",
    "Notes": "If I don't have git, I don't know what I'll do.",
    "Check": "Installed",
    "Parameters": ["git"]
}

Checks

docker.go

DockerImage

Description: Is this Docker image present? Parameters:

  • Name (string): Name of the image

Example parameters:

  • "user/image", "ubuntu"

DockerImageRegexp

Description: Works like DockerImage, but matches via a regexp, rather than a string.

DockerRunning

Description: Is this Docker container running? Parameters:

  • Name (string): Name of the container

Example parameters:

  • "user/container", "user/container:latest"

DockerRunningAPI

Description: Works like DockerRunning, but fetches information from the Docker API endpoint instead. Parameters:

  • Path (filepath): Path to Docker socket

  • Name (string): Name of the container

Example parameters:

  • "/var/run/docker.sock", "/path/to/docker.sock"

  • "user/container", "user/container:latest"

DockerRunningRegexp

Description: Works like DockerRunning, but matches with a regexp instead of a string. Parameters:

  • Regexp (regexp): Regexp to match names with

Example parameters:

  • "user/.+", "user/cC{2,3}[nta]taiw{2}r"

filesystem.go

file

Description: Does this regular file exist? Parameters:

  • Path (filepath): Path to file

Example parameters:

  • "/var/mysoftware/config.file", "/foo/bar/baz"

directory

Description: Does this regular directory exist? Parameters:

  • Path (filepath): Path to directory

Example parameters:

  • "/var/run/mysoftware.d/", "/foo/bar/baz/"

symlink

Description: Does this symlink exist? Parameters:

  • Path (filepath): Path to symlink

Example parameters:

  • "/var/run/mysoftware.d/", "/foo/bar/baz", "/bin/sh"

checksum

Description: Does this file match the expected checksum when using the specified algorithm? Parameters:

  • Algorithm (string): MD5 | SHA1 | SHA224 | SHA256 | SHA384 | SHA512 |

SHA3224 | SHA3256 | SHA3384 | SHA3512

  • Expected checksum (checksum/string)

  • Path (filepath): Path to file to check the checksum of

Example parameters:

  • MD5, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3224, SHA3256, SHA3384,

  • d41d8cd98f00b204e9800998ecf8427e, c6cf669dbd4cf2fbd59d03cc8039420a48a037fe

  • /dev/null, /etc/config/important-file.conf

FileMatches

Description: Does this file match this regexp? Parameters:

  • Path (filepath): Path to file to check the contents of

  • Regexp (regexp): Regexp to query file with

Example parameters:

  • /dev/null, /etc/config/important-file.conf

  • "str", "myvalue=expected", "IP=d{1,3}.d{1,3}.d{1,3}.d{1,3}"

Permissions

Description: Does this file have the given Permissions? Parameters:

  • Path (filepath): Path to file to check the Permissions of

  • Mode (filemode): Filemode to expect

Example parameters:

  • /dev/null, /etc/config/important-file.conf

  • -rwxrwxrwx, -rw-rw---- -rw-------, -rwx-r-x-r-x

misc.go

Command

Description: Does this Command exit without error? Parameters:

  • Cmd (string): Command to be executed

Example parameters:

  • "cat /etc/my-config/", "/bin/my_health_check.py"

CommandOutputMatches

Description: Does the combined (stdout + stderr) output of this Command match the given regexp? Parameters:

  • Cmd (string): Command to be executed

  • Regexp (regexp): Regexp to query output with

Example parameters:

  • "cat /etc/my-config/", "/bin/my_health_check.py"

  • "value=expected", "[rR]{1}ewe[Xx][^oiqnlkasdjc]"

Running

Description: Is a process by this exact name Running (excluding this process)? Parameters:

  • Name (string): Process name to look for

Example parameters:

  • nginx, [kthreadd], consul-agent, haproxy-consul

Depedencies:

  • ps aux

Temp

Description: Is the core Temperature under this value (in degrees Celcius)? Parameters:

  • Temp (positive int16): Maximum acceptable Temperature

Example parameters:

  • 100, 110C, 98°C, 100℃

Depedencies:

  • A configured lm-sensors (namely, sensors)

Module

Description: Is this kernel module installed? Parameters:

  • Name (string): Module name

Example parameters:

  • hid, drm, rfkill

Depedencies:

  • /sbin/lsmod

KernelParameter

Description: Is this kernel parameter set? Parameters:

  • Name (string): Kernel parameter to check

Example parameters:

  • "net.ipv6.route.gc_interval", "fs.file-max"

Depedencies:

  • /sbin/sysctl

PHPConfig

Description: Does this PHP configuration variable have this value? Parameters:

  • Variable (string): PHP variable to check

  • Value (string): Expected value

Example parameters:

  • "default_mimetype"

Depedencies:

  • php

network.go

Port

Description: Is this port open? Parameters:

  • Number (uint16): Port number (decimal)

Example parameters:

  • 80, 8080, 8500, 5050

Dependencies:

  • /proc/net/tcp

  • /proc/net/udp

PortTCP

Description: Is this port open on the TCP protocol? Parameters:

  • Number (uint16): Port number (decimal)

Example parameters:

  • 80, 8080, 8500, 5050

Dependencies:

  • /proc/net/tcp

PortUDP

Description: Is this port open on the UDP protocol? Parameters:

  • Number (uint16): Port number (decimal)

Example parameters:

  • 80, 8080, 8500, 5050

Dependencies:

  • /proc/net/udp

InterfaceExists

Description: Does this interface exist? Parameters:

  • Name (string): name of the interface

Example parameters:

  • lo, wlp1s0, docker0

Up

Description: Is this interface up? Parameters:

  • Name (string): name of the interface

Example parameters:

  • lo, wlp1s0, docker0

IP4

Description: Does this interface have this IPV4 address? Parameters:

  • Interface name (string)

  • Address (IP address)

Example parameters:

  • lo, wlp1s0, docker0

  • 192.168.0.21, 222.111.0.22

IP6

Description: Does this interface have this IPV6 address? Parameters:

  • Interface name (string)

  • IP (IP address)

Example parameters:

  • lo, wlp1s0, docker0

  • FE80:0000:0000:0000:0202:B3FF:FE1E:8329, 2001:db8:0:1:1:1:1:1

Gateway

Description: Does the default Gateway have this IP? Parameters:

  • IP (IP address)

Example parameters:

  • 192.168.0.21, 222.111.0.22

GatewayInterface

Description: Is the default Gateway is using a specified interface? Parameters:

  • Name (string)

Example parameters:

  • lo, wlp1s0, docker0

Host

Description: Host checks if a given host can be resolved Parameters: Example parameters:

TCP

Description: Can a given IP/port can be reached with a TCP connection Parameters: Example parameters:

  • 192.168.0.21, 222.111.0.22

UDP

Description: Like TCP but with UDP instead.

TCPTimeout

Description: Like TCP, but with a second parameter of a timeout Example parameters:

  • 5s, 7μs, 12m, 5h, 3d

UDPTimeout

Description: Like TCPTimeout, but with UDP

RoutingTableDestination

Description: Is this IP address in the kernel's IP routing table? Parameters:

  • IP (IP address)

Example parameters:

  • 192.168.0.21, 222.111.0.22

Dependencies:

  • route -n

RoutingTableInterface

Description: Is this interface in the kernel's IP routing table? Parameters:

  • Name (string)

Example parameters:

  • lo, wlp1s0, docker0

Dependencies:

  • route -n

RoutingTableGateway

Description: Is this the Gateway's IP address, as listed in the routing table? Parameters:

  • IP (IP address)

Example parameters:

  • 192.168.0.21, 222.111.0.22

ResponseMatches

Description: Does the response from this URL match this regexp? Parameters:

  • URL (URL string)

  • Regexp (regexp)

Example parameters:

ResponseMatchesInsecure

Description: Like ResponseMatches, but without SSL certificate validation

packages.go

PacmanIgnore

Description: Are upgrades to this package ignored by pacman? Parameters:

  • Package (string): Name of the package

Example parameters:

  • node, python, etcd

Depedencies:

  • pacman, specifically /etc/pacman.conf

Installed

Description: Is this package Installed? Parameters:

  • Package (string): Name of the package

Example parameters:

  • node, python, etcd

Depedencies:

  • pacman | dpkg | rpm | apk

systemctl.go

SystemctlLoaded

Description: Is systemd module loaded? Parameters:

  • Service (string): Name of the service

Example parameters:

  • TODO

SystemctlActive

Description: Is systemd module active? Parameters:

  • Service (string): Name of the service

Example parameters:

  • TODO

SystemctlSockListening

Description: Is the systemd socket at this path in the LISTEN state? Parameters:

  • Path (filepath): Path to socket

Example parameters:

  • /var/lib/docker.sock, /new/striped.sock

SystemctlTimer

Description: Is a timer by this name running? Parameters:

  • Unit (string): Name of systemd unit

Example parameters:

  • TODO

SystemctlTimerLoaded

Description: Is a timer by this name loaded? Parameters:

  • Unit (string): Name of systemd unit

Example parameters:

  • TODO

SystemctlUnitFileStatus

Description: Does this unit file have this status? Parameters:

  • Unit (string): Name of systemd unit

  • Status (string): "static" | "enabled" | "disabled"

Example parameters:

  • TODO

  • "static", "enabled", "disabled"

usage.go

MemoryUsage

Description: Is system memory usage below this threshold? Parameters:

  • Percent (int8 percentage): Maximum acceptable percentage memory used

Example parameters:

  • 95%, 90%, 87%

SwapUsage

Description: Like MemoryUsage, but with swap

FreeMemory

Description: Is at least this amount of memory free? Parameters:

  • Amount (string with byte unit): minimum acceptable amount of free memory

Example parameters:

  • 100mb, 1gb, 3TB, 20kib

FreeSwap

Description: Like FreeMemory, but with swap instead.

CPUUsage

Description: Is the cpu usage below this percentage in a 3 second interval? Parameters:

  • Percent (int8 percentage): Maximum acceptable percentage used

Example parameters:

  • 95%, 90%, 87%

DiskUsage

Description: Is the disk usage below this percentage? Parameters:

  • Path (filepath): Path to the disk

  • Percent (int8 percentage): Maximum acceptable percentage used

Example parameters:

  • /dev/sda1, /mnt/my-disk/

  • 95%, 90%, 87%

InodeUsage

Description: Is the inode usage below this percentage? Parameters:

  • Filesystem (string): Filesystem as shown by df -i

  • Percent (int8 percentage): Maximum acceptable percentage used

Example parameters:

  • /dev/sda1, /mnt/my-disk/, tmpfs

  • 95%, 90%, 87%

users-and-groups.go

GroupExists

Description: Does this group exist? Parameters:

  • Name (group name): Name of the group

Example parameters:

  • sudo, wheel, www, storage

UserInGroup

Description: Is this user in this group? Parameters:

  • User (user name): Name of the group

  • Group (group name): Name of the group

Example parameters:

  • siddharthist, siddharthist, root, centos

  • sudo, wheel, www, storage

GroupID

Description: Does this group have this integer ID? Parameters:

  • Group (group name): Name of the group

  • ID (int): Group ID

Example parameters:

  • sudo, wheel, www, storage

  • 0, 20, 50, 38

UserExists

Description: Does this user exist? Parameters:

  • Username

Example parameters:

  • siddharthist, root, user, 10

UserHasUID

Description: Does this user have this UID? Parameters:

  • Username

  • Expected UID (UID)

Example parameters:

  • siddharthist, root, user, 10

  • 11, 13, 17

UserHasGID

Description: Does this user have this GID? Parameters:

  • Username

  • Expected GID (GID)

Example parameters:

  • siddharthist, root, user, 10

  • 11, 13, 17

UserHasHomeDir

Description: Does this user have this home directory? Parameters:

  • Username

  • Expected home directory (path)

Example parameters:

  • siddharthist, root, 0

  • /home/siddharthist, /root, /mnt/my/custom/dir

zookeeper.go

ZooKeeperRUOK

Description: Are these Zookeeper servers responding to "ruok" requests? Parameters:

  • Timeout (time.Duration): Timeout for server response

  • Servers ([]string): List of zookeeper servers

Example parameters:

  • "5s", "20ms", "2h"

  • "localhost:2181", "zookeeper.service.consul:2181"

Add a custom footer
Add a custom sidebar
Clone this wiki locally