Skip to content

Latest commit

 

History

History
145 lines (96 loc) · 3.62 KB

README.rst

File metadata and controls

145 lines (96 loc) · 3.62 KB
Raw

Chkok

"chkok" checks if attributes of files and sockets match the provided conditions to ensure system state is as expected. It can be used to monitor system health and resource availability. Provides different running modes, useful for reporting to local and remote monitoring. It's written in Go, has a small resource overhead with no runtime dependencies.

Main target platforms are modern GNU/Linux systems, but other operating systems may work as well.

Installation

Download the latest release from the releases page. Released artifacts can be verified with the checksum file containing sha256 hashes.

sha256sum -c chkok-*SHA256SUMS

Or build and install from source (requires Go 1.22+):

sudo make install
# or to install in a custom location (e.g. for packaging)
env DESTDIR=/tmp make install

Usage

Run in CLI mode (default):

chkok -conf examples/config.yaml

Run in HTTP mode, starting an HTTP server on the configured port:

chkok -conf examples/config.yaml -verbose -mode http

The HTTP mode is useful for checking the results remotely, for example, from a monitoring system. Currently there is no encryption supported, so it's recommended to use only in trusted networks, or behind a local SSL terminating service.

Configuration

Configuration is done via a YAML file.

runners section configures how the checks should be run. The runner configurations are merged with the default runner configuration.

runners:
    default:
        timeout: 5m
        # response_ok: "OK"
        # response_fail: "FAILED"
        # response_timeout: "TIMEOUT"
    cli: {}  # override default runner only for CLI mode
    http:  # override default runner only for HTTP mode
        listen_address: "127.0.0.1:51234"
        # request_read_timeout: 2s
        # response_write_timeout: 2s
        # timeout: 5s
        # max_header_bytes: 8192
        # max_concurrent_requests: 1  # 0 means no limit
        # request_required_headers:
        #   "X-Required-Header": "required-value"
        #   "X-Required-Header2": ""  # header existence is required, not value

The check_suites section defines the checks to be run. Each check suite is a logical group of checks that should run sequentially. Each check defines the expected properties of the resource (file or socket) to be checked.

check_suites:
  etc:
    - type: dir
      path: /etc
      mode: 0755
      user: root
      group: root
    - type: file
      path: /etc/passwd
      min_size: 10
    - type: file
      path: /etc/group
      min_size: 5
      max_size: 10000
  default:
    - type: file
      path: /unwanted/file
      absent: true
    - type: dial
      network: tcp
      address: "localhost:22"
      timeout: 500ms

See the examples directory for sample configuration files.

Development

Make sure you have Go 1.22+ installed. Most of the development and build tasks are automated with the Makefile.

To build the binary from source, run:

make clean build

To run the tests and static checks, run:

make test

License

"chkok" is an open source project released under the terms of the MIT license. It uses yaml.v3 library which is licensed under the MIT and Apache License 2.0 licenses. See LICENSE file for more details.