fletchck


Namefletchck JSON
Version 1.1.1 PyPI version JSON
download
home_pageNone
SummaryMachine monitor
upload_time2025-02-01 08:48:04
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseMIT
keywords system monitor
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # fletchck

Fletchck is a self-contained network service monitor.
It provides a suite of simple internet service
checks with flexible scheduling provided by
[APScheduler](https://apscheduler.readthedocs.io/en/master/)
and optional remote notification via MQTT.

Service checks trigger notification actions
as they transition from pass to fail or vice-versa.
Configuration is via JSON file or an in-built web
user interface.

The following checks are provided:

   - cert: Check TLS certificate validity or self-signed expiry
   - smtp: SMTP with optional starttls
   - submit: SMTP-over-SSL/Submissions
   - imap: IMAP4-SSL mailbox
   - https: HTTP/HTTPS request
   - ssh: SSH pre-auth connection with hostkey check
   - sequence: A sequence of checks, fails if any one member check fails
   - ups: Monitor a "QS" serial UPS status
   - upstest: Perform a "QS" serial UPS self-test and report faults
   - remote: Tracks the state of a check running on a remote instance
     fletchck over MQTT
   - disk: Disk space check, fails when usage exceeds percentage
   - memory: Check free memory space on host system
   - cpu: Check local average CPU load on host system
   - temp: Comet temperature probe
   - dns: DNS query

Service checks that use TLS will verify the service certificate
and hostname unless the selfsigned option is set.
If expiry of a self-signed certificate needs to be checked, use
the cert check with selfsigned option.

The following notification actions are supported:

   - email: Send an email
   - sms: Post SMS via Cloudkinnekt API
   - log: Log PASS/FAIL


## Installation

Create a python virtual env, and install from pypi using pip:

	$ python3 -m venv --system-site-packages venv
	$ ./venv/bin/pip3 install fletchck


## Setup

Create a new empty site configuration in the current
directory with the -init option:

	$ ./venv/bin/fletchck -init

Open a web browser with the displayed credentials to continue
setup.


## Configuration

Configuration is read from a JSON encoded dictionary
object with the following keys and values:

key | type | description
--- | --- | ---
base | str | Full path to location of site configuration file
timezone | str | Time zone for notifications, schedules and interface
webui | dict | Web user interface configuration (see Web UI below)
mqtt | dict | Persistent MQTT client connection (see MQTT below)
actions | dict | Notification actions (see Actions below)
checks | dict | Service checks (see Checks below)

Notes:

   - All toplevel keys are optional
   - If webui is not present or null, the web user interface
     will not be started.
   - If mqtt is not present or null, the MQTT client is not started.
   - Action and check names may be any string that can be used
     as a dictionary key and that can be serialised in JSON.
   - Duplicate action and check names will overwrite earlier
     definitions with the same name.
   - Timezone should be a zoneinfo key or null to use host localtime


### Actions

Each key in the actions dictionary names a notification
action dictionary with the following keys and values:

key | type | description
--- | --- | ---
type | str | Action type, one of 'log', 'email' or 'sms'
options | dict | Dictionary of option names and values

The following action options are recognised:

option | type | description
--- | --- | ---
hostname | str | Email submission hostname
url | str | API Url for SMS sending
port | int | TCP port for email submission
username | str | Username for authentication
password | str | Password for authentication
sender | str | Sender string
timeout | int | TCP timeout for email submission
recipients | list | List of recipient strings
site | str | Site identifier (default is Fletchck)


### Checks

Each key in the checks dictionary names a service check
with the following keys and values:

key | type | description
--- | --- | ---
type | str | Check type: cert, smtp, submit, imap, https, ssh, remote, disk, ups, upstest or sequence
subType | str | Optional subtype, set on update for remote checks
trigger | dict | Trigger definition (see Scheduling below)
threshold | int | Fail state reported after this many failed checks
failAction | bool | Send notification action on transition to fail
passAction | bool | Send notification action on transition to pass
publish | str | MQTT topic to log check state to
remoteId | str | Name of remote check if different to local check name
options | dict | Dictionary of option names and values (see below)
actions | list | List of notification action names
depends | list | List of check names this check depends on
data | dict | Runtime data and logs (internal)

Note that only the type is required, all other keys are optional.
The following check options are recognised:

option | type | description
--- | --- | ---
hostname | str | Hostname or IP address of target service
port | int | TCP port of target service
timeout | int | Timeout in seconds
timezone | str | Timezone for schedule and notification
selfsigned | bool | If set, TLS sessions will not validate service certificate
tls | bool | (smtp) If set, call starttls to initiate TLS
probe | str | (cert) send str probe to service after TLS negotiation
reqType | str | (https/dns) Request method: HEAD, GET, POST, TXT, SOA, AAAA, etc
reqPath | str | (https) Request target resource
reqName | str | (dns) Name to request from dns server
reqTcp | bool | (dns) If true, use TCP
hostkey | str | (ssh) Target service base64 encoded public key
checks| list | (sequence) List of check names to be run in-turn
volume | str | (disk) Path of disk volume to be checked
level | int | (disk) Disk space failure percentage
serialPort | str | (ups*) Serial port to use for UPS communication

Unrecognised options are ignored by checks.

Example:

	"checks": {
	 "Home Cert": {
	  "type": "cert",
	  "passAction": false,
	  "trigger": { "cron": {"day": 1, "hour": 1} },
	  "options": { "hostname": "home.place.com", "port": 8443 },
	  "actions": [ "Tell Alice" ]
	 }
	}

Define a single check named "Home Cert" which performs
a certificate verification check on port 8443 of
"home.place.com" at 1:00 am on the first of each month,
and notifies using the action named "Tell Alice" on
transition to fail.


## Scheduling

Job scheduling is managed by APScheduler. Each defined
check may have one optional trigger of type interval or cron.

Within the web interface, trigger schedules are entered
using a plain text whitespace separated list of value/unit pairs.

An interval trigger with an explicit start:

	interval 1 week 2 day 3 hr 5 min 15 sec

A cron trigger with an explicit timezone:

	cron 9-17 hr 20,40 min mon-fri weekday Australia/Adelaide z


### Interval

The check is scheduled to be run at a repeating interval
of the specified number of weeks, days, hours, minutes
and seconds.

For example, a trigger that runs every 10 minutes:

	"interval": {
	 "minutes": 10
	}

Interval reference: [apscheduler.triggers.interval](https://apscheduler.readthedocs.io/en/3.x/modules/triggers/interval.html)


### Cron

The configured check is triggered by UNIX cron style
time fields (year, month, day, hour, minute, second etc).
For example, to define a trigger that is run at 5, 25
and 45 minutes past the hour between 5am and 8pm every day:

	"cron": {
	 "hour": "5-20",
	 "minute": "5,25,45"
	}

Cron reference: [apscheduler.triggers.cron](https://apscheduler.readthedocs.io/en/3.x/modules/triggers/cron.html)


## Web UI

The web user interface is configured with the webui key 
of the site config. The keys and values are as follows:

key | type | description
--- | --- | ---
cert | str | path to TLS certificate
key | str | path to TLS private key
host | str | hostname to listen on
port | int | port to listen on
name | str | site name displayed on header
base | str | path to configuration file
users | dict | authorised usernames and hashed passwords


## MQTT

The fletchck instance can be configured to maintain a persistent
MQTT connection using the mqtt configuration object:

key | type | description
--- | --- | ---
hostname | str | MQTT broker hostname or IP
port | int | MQTT broker port
tls | bool | Use TLS for client connection
username | str | Login username
password | str | Login password
clientid | str | Client id for persistent connection (None for automatic)
persist | bool | Use a persistent connection (default: True)
qos | int | QoS for publish and subscribe (default: 1 "at least once")
retain | bool | Publish check updates with retain flag (default: True)
basetopic | str | Topic to receive remote updates
autoadd | bool | Automatically add remote checks on reception of update message
debug | bool | Include debugging information on MQTT client

Checks are configured to report to MQTT by entering a topic
in the "publish" option. Reception of valid notifications
to the configured "basetopic" option (which may include a trailing
wildcard) will trigger update of the remote check state.

To monitor a remote check for lack of update, add an interval
or cron trigger to the remote entry and edit the timeout time
to set an update expiry.


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "fletchck",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "system, monitor",
    "author": null,
    "author_email": "Nathan Fraser <ndf-zz@6-v.org>",
    "download_url": "https://files.pythonhosted.org/packages/45/ec/61e89502d713d4b274635412f14bee5ac0b31e43731121f62e8c281bd716/fletchck-1.1.1.tar.gz",
    "platform": null,
    "description": "# fletchck\n\nFletchck is a self-contained network service monitor.\nIt provides a suite of simple internet service\nchecks with flexible scheduling provided by\n[APScheduler](https://apscheduler.readthedocs.io/en/master/)\nand optional remote notification via MQTT.\n\nService checks trigger notification actions\nas they transition from pass to fail or vice-versa.\nConfiguration is via JSON file or an in-built web\nuser interface.\n\nThe following checks are provided:\n\n   - cert: Check TLS certificate validity or self-signed expiry\n   - smtp: SMTP with optional starttls\n   - submit: SMTP-over-SSL/Submissions\n   - imap: IMAP4-SSL mailbox\n   - https: HTTP/HTTPS request\n   - ssh: SSH pre-auth connection with hostkey check\n   - sequence: A sequence of checks, fails if any one member check fails\n   - ups: Monitor a \"QS\" serial UPS status\n   - upstest: Perform a \"QS\" serial UPS self-test and report faults\n   - remote: Tracks the state of a check running on a remote instance\n     fletchck over MQTT\n   - disk: Disk space check, fails when usage exceeds percentage\n   - memory: Check free memory space on host system\n   - cpu: Check local average CPU load on host system\n   - temp: Comet temperature probe\n   - dns: DNS query\n\nService checks that use TLS will verify the service certificate\nand hostname unless the selfsigned option is set.\nIf expiry of a self-signed certificate needs to be checked, use\nthe cert check with selfsigned option.\n\nThe following notification actions are supported:\n\n   - email: Send an email\n   - sms: Post SMS via Cloudkinnekt API\n   - log: Log PASS/FAIL\n\n\n## Installation\n\nCreate a python virtual env, and install from pypi using pip:\n\n\t$ python3 -m venv --system-site-packages venv\n\t$ ./venv/bin/pip3 install fletchck\n\n\n## Setup\n\nCreate a new empty site configuration in the current\ndirectory with the -init option:\n\n\t$ ./venv/bin/fletchck -init\n\nOpen a web browser with the displayed credentials to continue\nsetup.\n\n\n## Configuration\n\nConfiguration is read from a JSON encoded dictionary\nobject with the following keys and values:\n\nkey | type | description\n--- | --- | ---\nbase | str | Full path to location of site configuration file\ntimezone | str | Time zone for notifications, schedules and interface\nwebui | dict | Web user interface configuration (see Web UI below)\nmqtt | dict | Persistent MQTT client connection (see MQTT below)\nactions | dict | Notification actions (see Actions below)\nchecks | dict | Service checks (see Checks below)\n\nNotes:\n\n   - All toplevel keys are optional\n   - If webui is not present or null, the web user interface\n     will not be started.\n   - If mqtt is not present or null, the MQTT client is not started.\n   - Action and check names may be any string that can be used\n     as a dictionary key and that can be serialised in JSON.\n   - Duplicate action and check names will overwrite earlier\n     definitions with the same name.\n   - Timezone should be a zoneinfo key or null to use host localtime\n\n\n### Actions\n\nEach key in the actions dictionary names a notification\naction dictionary with the following keys and values:\n\nkey | type | description\n--- | --- | ---\ntype | str | Action type, one of 'log', 'email' or 'sms'\noptions | dict | Dictionary of option names and values\n\nThe following action options are recognised:\n\noption | type | description\n--- | --- | ---\nhostname | str | Email submission hostname\nurl | str | API Url for SMS sending\nport | int | TCP port for email submission\nusername | str | Username for authentication\npassword | str | Password for authentication\nsender | str | Sender string\ntimeout | int | TCP timeout for email submission\nrecipients | list | List of recipient strings\nsite | str | Site identifier (default is Fletchck)\n\n\n### Checks\n\nEach key in the checks dictionary names a service check\nwith the following keys and values:\n\nkey | type | description\n--- | --- | ---\ntype | str | Check type: cert, smtp, submit, imap, https, ssh, remote, disk, ups, upstest or sequence\nsubType | str | Optional subtype, set on update for remote checks\ntrigger | dict | Trigger definition (see Scheduling below)\nthreshold | int | Fail state reported after this many failed checks\nfailAction | bool | Send notification action on transition to fail\npassAction | bool | Send notification action on transition to pass\npublish | str | MQTT topic to log check state to\nremoteId | str | Name of remote check if different to local check name\noptions | dict | Dictionary of option names and values (see below)\nactions | list | List of notification action names\ndepends | list | List of check names this check depends on\ndata | dict | Runtime data and logs (internal)\n\nNote that only the type is required, all other keys are optional.\nThe following check options are recognised:\n\noption | type | description\n--- | --- | ---\nhostname | str | Hostname or IP address of target service\nport | int | TCP port of target service\ntimeout | int | Timeout in seconds\ntimezone | str | Timezone for schedule and notification\nselfsigned | bool | If set, TLS sessions will not validate service certificate\ntls | bool | (smtp) If set, call starttls to initiate TLS\nprobe | str | (cert) send str probe to service after TLS negotiation\nreqType | str | (https/dns) Request method: HEAD, GET, POST, TXT, SOA, AAAA, etc\nreqPath | str | (https) Request target resource\nreqName | str | (dns) Name to request from dns server\nreqTcp | bool | (dns) If true, use TCP\nhostkey | str | (ssh) Target service base64 encoded public key\nchecks| list | (sequence) List of check names to be run in-turn\nvolume | str | (disk) Path of disk volume to be checked\nlevel | int | (disk) Disk space failure percentage\nserialPort | str | (ups*) Serial port to use for UPS communication\n\nUnrecognised options are ignored by checks.\n\nExample:\n\n\t\"checks\": {\n\t \"Home Cert\": {\n\t  \"type\": \"cert\",\n\t  \"passAction\": false,\n\t  \"trigger\": { \"cron\": {\"day\": 1, \"hour\": 1} },\n\t  \"options\": { \"hostname\": \"home.place.com\", \"port\": 8443 },\n\t  \"actions\": [ \"Tell Alice\" ]\n\t }\n\t}\n\nDefine a single check named \"Home Cert\" which performs\na certificate verification check on port 8443 of\n\"home.place.com\" at 1:00 am on the first of each month,\nand notifies using the action named \"Tell Alice\" on\ntransition to fail.\n\n\n## Scheduling\n\nJob scheduling is managed by APScheduler. Each defined\ncheck may have one optional trigger of type interval or cron.\n\nWithin the web interface, trigger schedules are entered\nusing a plain text whitespace separated list of value/unit pairs.\n\nAn interval trigger with an explicit start:\n\n\tinterval 1 week 2 day 3 hr 5 min 15 sec\n\nA cron trigger with an explicit timezone:\n\n\tcron 9-17 hr 20,40 min mon-fri weekday Australia/Adelaide z\n\n\n### Interval\n\nThe check is scheduled to be run at a repeating interval\nof the specified number of weeks, days, hours, minutes\nand seconds.\n\nFor example, a trigger that runs every 10 minutes:\n\n\t\"interval\": {\n\t \"minutes\": 10\n\t}\n\nInterval reference: [apscheduler.triggers.interval](https://apscheduler.readthedocs.io/en/3.x/modules/triggers/interval.html)\n\n\n### Cron\n\nThe configured check is triggered by UNIX cron style\ntime fields (year, month, day, hour, minute, second etc).\nFor example, to define a trigger that is run at 5, 25\nand 45 minutes past the hour between 5am and 8pm every day:\n\n\t\"cron\": {\n\t \"hour\": \"5-20\",\n\t \"minute\": \"5,25,45\"\n\t}\n\nCron reference: [apscheduler.triggers.cron](https://apscheduler.readthedocs.io/en/3.x/modules/triggers/cron.html)\n\n\n## Web UI\n\nThe web user interface is configured with the webui key \nof the site config. The keys and values are as follows:\n\nkey | type | description\n--- | --- | ---\ncert | str | path to TLS certificate\nkey | str | path to TLS private key\nhost | str | hostname to listen on\nport | int | port to listen on\nname | str | site name displayed on header\nbase | str | path to configuration file\nusers | dict | authorised usernames and hashed passwords\n\n\n## MQTT\n\nThe fletchck instance can be configured to maintain a persistent\nMQTT connection using the mqtt configuration object:\n\nkey | type | description\n--- | --- | ---\nhostname | str | MQTT broker hostname or IP\nport | int | MQTT broker port\ntls | bool | Use TLS for client connection\nusername | str | Login username\npassword | str | Login password\nclientid | str | Client id for persistent connection (None for automatic)\npersist | bool | Use a persistent connection (default: True)\nqos | int | QoS for publish and subscribe (default: 1 \"at least once\")\nretain | bool | Publish check updates with retain flag (default: True)\nbasetopic | str | Topic to receive remote updates\nautoadd | bool | Automatically add remote checks on reception of update message\ndebug | bool | Include debugging information on MQTT client\n\nChecks are configured to report to MQTT by entering a topic\nin the \"publish\" option. Reception of valid notifications\nto the configured \"basetopic\" option (which may include a trailing\nwildcard) will trigger update of the remote check state.\n\nTo monitor a remote check for lack of update, add an interval\nor cron trigger to the remote entry and edit the timeout time\nto set an update expiry.\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Machine monitor",
    "version": "1.1.1",
    "project_urls": {
        "homepage": "https://github.com/ndf-zz/fletchck"
    },
    "split_keywords": [
        "system",
        " monitor"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6e24b7a14f9afb8665b17832968840e250a4cd645b883b52b0fcaddeee35e88c",
                "md5": "2ce2e83cb28696f45689b6244910fa1f",
                "sha256": "578fe63199014a609493d13668b932e44a21321ededbf75a1d137b7dfa7952a4"
            },
            "downloads": -1,
            "filename": "fletchck-1.1.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2ce2e83cb28696f45689b6244910fa1f",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 105800,
            "upload_time": "2025-02-01T08:48:00",
            "upload_time_iso_8601": "2025-02-01T08:48:00.579614Z",
            "url": "https://files.pythonhosted.org/packages/6e/24/b7a14f9afb8665b17832968840e250a4cd645b883b52b0fcaddeee35e88c/fletchck-1.1.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "45ec61e89502d713d4b274635412f14bee5ac0b31e43731121f62e8c281bd716",
                "md5": "24c77305c55ccc907284e2ed9f68d13c",
                "sha256": "ab4a5fbb02bb888e96eb167ad23fc0192837693f15b6eeda665bb63647e46045"
            },
            "downloads": -1,
            "filename": "fletchck-1.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "24c77305c55ccc907284e2ed9f68d13c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 98556,
            "upload_time": "2025-02-01T08:48:04",
            "upload_time_iso_8601": "2025-02-01T08:48:04.074105Z",
            "url": "https://files.pythonhosted.org/packages/45/ec/61e89502d713d4b274635412f14bee5ac0b31e43731121f62e8c281bd716/fletchck-1.1.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-01 08:48:04",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ndf-zz",
    "github_project": "fletchck",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "fletchck"
}
        
Elapsed time: 1.16390s