Skip to content

Checks and Checklists

Jump to bottom Edit New page
siddharthist edited this page Jun 18, 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".

"installed"

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

"repoExists"

  • Description: Does the configuration file for this package manager specify this repo? This check reads configuration files depending on the package manager specified.
  • Inputs:
    • Name of package manager: yum | dpkg | pacman
    • Name of repo
  • Dependencies: yum | dpkg | pacman

"repoExistsURI"

  • Description: Does the configuration file for this package manager specify this repo?
  • Inputs:
    • Name of package manager: yum | dpkg | pacman
    • URI of repo. Either in the form of a URL or a path.
  • Dependencies: yum | dpkg | 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)

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

"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.

"dockerRunning"

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

"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