| Name | fletchck JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | None |
| Summary | Machine monitor |
| upload_time | 2025-02-01 08:48:04 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| 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"
}
