Skip to content

Checks and Checklists

Jump to bottom Edit New page
siddharthist edited this page Jun 25, 2015 · 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"]
}

Filesystem

"file"

  • Description: Is there a file at this path?
  • Inputs:
    • Path to file

"directory"

  • Description: Is there a directory at this path?
  • Inputs:
    • Path to directory

"symlink

  • Description: Is there a symbolic link at this path?
  • Inputs:
    • Path to symlink

"checksum"

  • Description: Does this file's checksum match the expected value?
  • Inputs:
    • Algorithm: SHA1 | SHA224 | SHA256 | SHA384 | SHA512 | MD5
    • Expected value (original, valid checksum)
    • Path to file

"permissions"

  • Description: Do this file's Unix permisisons match the given string?
  • Inputs:
    • Path to file
    • Permissions string (in the form "-rwxrwxrwx", e.g. "-rw-r-----")

"fileContains"

  • Description: Does this file match against this regex?
  • Inputs:
    • Path to file
    • Golang regular expression

"diskUsage"

  • Description: Is disk usage below this percentage?
  • Inputs:
    • Path to check (e.g., "/" or "/mnt/my-disk")
    • Maximum acceptable disk usage, a percentage (must be parseable as base 10 integer, of <64 bit width)

Packages

Supported package managers for checks "installed", and "repoExistsURI" are yum, apt, and pacman. Only pacman and yum are supported for "repoExists". Currently, "repoExists" is having some difficult errors with yum.

"installed"

  • Description: Is this package installed on the server?
  • Inputs:
    • Name of package
  • Dependencies: yum | apt | pacman

"repoExists"

  • Description: Is this repo active?
  • Inputs:
    • Name of package manager: yum | apt | pacman
    • Name of repo (given as a Golang regexp)
  • Dependencies: yum | apt | pacman

"repoExistsURI"

  • Description: Does the configuration file for this package manager specify this repo?
  • Inputs:
    • Name of package manager: apt | pacman
    • URI of repo. Either in the form of a URL or a path.
  • Dependencies: apt | pacman

"pacmanIgnore"

  • Description: Is this package listed in pacman's configuration's IgnorePkg field?
  • Inputs:
    • Name of package
  • Dependencies: pacman

Network

"port"

  • Description: Is this port in an open state? Reads from /proc/net/tcp
  • Inputs:
    • Port number (must be parseable as base 10 integer, of <64 bit width)

"interface"

  • Description: Does this network interface exist?
  • Inputs:
    • Interface name

"up"

  • Description: Is this network interface up?
  • Inputs:
    • Interface name

"ip4"

  • Description: Does this interface have the specified IP address?
  • Inputs:
    • Interface name
    • IPv4 address

"ip6"

  • Description: Does this interface have the specified IP address?
  • Inputs:
    • Interface name
    • IPv6 address

"gateway"

  • Description: Does the default gateway have the specified IP address?
  • Inputs:
    • IPv4 address

"gatewayInterface"

  • Description: Is the default gateway operating on this interface?
  • Inputs:
    • Interface name

"TCP"

  • Description: Can this host be reached via a TCP connection?
  • Inputs:
    • Hostname/IP address (with port number)

"UDP"

  • Description: Can this host be reached via a UDP connection?
  • Inputs:
    • Hostname/IP address (with port number)

"tcpTimeout"

  • Description: Can this host be reached via a TCP connection before a set timeout?
  • Inputs:
    • Hostname/IP address (with port number)
    • Timeout, expressed as a string (per Golang's time.ParseDuration)

"udpTimeout"

  • Description: Can this host be reached via a UDP connection before a set timeout?
  • Inputs:
    • Hostname/IP address (with port number)
    • Timeout, expressed as a string (per Golang's time.ParseDuration)

"responseMatches"

  • Description: Does the response from this server match this regexp?
  • Inputs:

"responseMatchesInsecure"

  • Description: Just like "responseMatches", but it doesn't verify the TLS/SSL certificate of the server.
  • Inputs:

Users and Groups

For all of the following checks, the user can either be specified by their username or by their UID. Except "userInGroup", which requires a username. Several of the group-related checks read from /etc/group.

"groupExists"

  • Description: Does a group by this name exist on the host?
  • Inputs:
    • Group name

"groupId"

  • Description: Does a group by this name have this group id?
  • Inputs:
    • Group name
    • GID (must be parseable as base 10 integer, of <64 bit width)

"userInGroup"

  • Description: Is this user a member of this group?
  • Inputs:
    • Username
    • Group name

"userExists"

  • Description: Does this user exist?
  • Inputs:
    • Username | UID

"userHasUID"

  • Description: Does this user have this UID?
  • Inputs:
    • Username | UID
    • UID

"userHasGID"

  • Description: Does this user have this primary GID?
  • Inputs:
    • Username | UID
    • GID

"userHasUsername"

  • Description: Does this user have this username?
  • Inputs:
    • Username | UID
    • Username

"userHasName"

  • Description: Does this user have this name?
  • Inputs:
    • Username | UID
    • Name

"userHasHomeDir"

  • Description: Is this the path of this user's home directory?
  • Inputs:
    • Username | UID
    • Path to home dir

Systemctl

All of the below depend on systemd and systemctl (obviously).

"systemctlLoaded"

  • Description: Is this service loaded?
  • Inputs:
    • Unit name

"systemctlActive"

  • Description: Is this service active?
  • Inputs:
    • Unit name

"systemctlSockPath"

  • Description: Is the socket at this path registered with systemd?
  • Inputs:
    • Path to socket

"systemctlSockUnit"

  • Description: Is the sock with this unit registered with systemd?
  • Inputs:
    • Unit name

"systemctlTimer"

  • Description: Is this timer active?
  • Inputs:
    • Timer unit name

"systemctlTimerLoaded"

  • Description: Is this timer loaded?
  • Inputs:
    • Timer unit name

"systemctlUnitFileStatus"

  • Description: Does this unit file have this status?
  • Inputs:
    • Unit file
    • Status: enabled | disabled | static

Miscellaneous

"command"

  • Description: Run a shell command. Has non-zero exit code when the command has a non-zero exit code.
  • Inputs:
    • Command to be run

"commandOutputMatches"

  • Description: Run a shell command, and check whether its output is matched by the given regexp.
  • Inputs:
    • Command to be run
    • Golang regexp to match against

"running"

  • Description: Is this program running on the server? Reads from ps aux.
  • Inputs:
    • Program name

"temp"

  • Description: Does the CPU temp exceed this integer (Celcius)?
  • Inputs:
    • Temperature in degrees celcius (must be parseable as base 10 integer, of <64 bit width)

"module"

  • Description: Is this kernel module activated?
  • Inputs:
    • Module name

"kernelParameter"

  • Description: Is this kernel parameter specified?
  • Inputs:
    • Parameter name

"dockerImage"

  • Description: Does this Docker image exist on the host?
  • Inputs:
    • Image name, as presented by docker ps -a.

"dockerImageRegexp"

  • Description: Just like "dockerImage", but with a Golang regexp match
  • Inputs:
    • Image name, as presented by docker ps -a, as a Golang regexp

"dockerRunning"

  • Description: Is this Docker container running (must include version, e.g. user/container:latest)?
  • Inputs:
    • Container name (optionally including version number)

"dockerRunningRegexp"

  • Description: Just like "dockerRunning", but with a Golang regexp match
  • Inputs:
    • Container name (optionally including version number), as a Golang regexp

"phpConfig"

  • Description: Does this PHP variable have this value?
  • Inputs:
    • Variable name
    • Expected value

"memoryUsage"

  • Description: Is the memory usage below this threshold?
  • Inputs:
    • Maximum acceptable memory usage, a percentage (must be parseable as base 10 integer, of <64 bit width)

"swapUsage"

  • Description: Is the swap usage below this threshold?
  • Inputs:
    • Maximum acceptable swap usage, a percentage (must be parseable as base 10 integer, of <64 bit width)

"cpuUsage"

  • Description: Is the CPU usage below this threshold?
  • Inputs:
    • Maximum acceptable CPU usage, a percentage (must be parseable as base 10 integer, of <64 bit width)
Add a custom footer
Add a custom sidebar
Clone this wiki locally