Skip to content

baraverkstad/upstate

Repository files navigation

Upstate

Prints a report containing machine and process metrics on Linux. Also checks for the existence of a number of configured processes. A short output example:

    loadavg:  0.06 0.04 0.00             up 264 days ∙ 192 processes ∙ 1 cores
    memory:   64 MB (6.6%) free          491 MB rss ∙ 426 MB cache ∙ 981 MB total
    storage:  16.0 GB (66.6%) free       6.8 GB used ∙ 24.1 GB total ∙ on /
    ● system/cron [297]                  1 MB rss ∙ up 264 days ∙ cpu 00:01:38
    ● ntp [1402230]                      2 MB rss ∙ up 159 days ∙ cpu 00:34:48
    ● sshd [1975344]                     23 MB rss ∙ up 108 days ∙ cpu 00:00:00

Usage

    Syntax: upstate [options]

    Options:
      --summary     Report only a short machine status summary.
      --limited     Report excludes optional/hidden processes.
      --complete    Report includes all processes (default).
      --json        Prints the report in JSON output format.

    Returns:
      Non-zero if one or more configured services weren't found.

    Files:
      /etc/upstate.conf

Installation

The easiest installation is to use the installer script:

    curl -L https://raw.githubusercontent.com/baraverkstad/upstate/main/install.sh | bash

As an alternative, the ./install.sh script can also be run directly from an unpacked download directory.

A third option is to manually copy the upstate binary, man/man1/upstate.1 and etc/upstate.conf to their desired locations on the server.

Finally, it is also possible to build a Docker image (make build-docker) and run from a container with access to the host machine processes and PID files:

    docker run --rm --tty --pid host \
        -v /etc/upstate.conf:/etc/upstate.conf \
        -v /var/run:/var/run:ro \
        upstate:latest

Configuration

The processes to check are configured in /etc/upstate.conf or /usr/local/etc/upstate.conf with one line per process. Comment or blank lines are ignored. Each line contains the process or service name, pid file and an optional command-line argument to match:

    cron            /var/run/crond.pid
    sshd            /var/run/sshd.pid
    local           - local-command-match
    -rsyslog        /var/run/rsyslogd.pid

Processes with a leading - character in the name are optional. These are omitted in --limited report and always ignored if missing.

Processes with a leading + character in the name may match multiple processes (at least one).

Processes with a leading * character in the name are optional, but may match multiple processes. These are omitted in --limited report and always ignored if missing.

A pid file specified as - forces process lookup by either name or command-line match. Process lookup is also made in similar way if the pid file didn't exist or didn't match a running process.

See Also