| Name | fletchck JSON |
| Version |
1.0.5
JSON |
| download |
| home_page | None |
| Summary | Machine monitor |
| upload_time | 2024-07-29 05:57:30 |
| 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 supported:
- smtp: SMTP with optional starttls
- submit: SMTP-over-SSL/Submissions
- imap: IMAP4-SSL mailbox
- https: HTTP request
- cert: Check TLS certificate validity and/or expiry
- ssh: SSH pre-auth connection with optional hostkey check
- disk: Disk space check, fails when usage exceeds percentage
- 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
- sequence: A sequence of checks, fails if any one check fails
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 SMS Central API
- mqtt: Publish a one-shot MQTT message to the configured broker
## 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
## 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
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) Request method: HEAD, GET, POST, PUT, DELETE, etc
reqPath | str | (https) Request target resource
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": 443 },
"actions": [ "Tell Alice" ]
}
}
Define a single check named "Home Cert" which performs
a certificate verification check on port 443 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.
### Example Config
The following complete configuration describes
a fletchck site with no web ui that runs a set
of checks for a single site with a web site and
SMTP, IMAP services behind a router.
Router connectivity is checked every 5 minutes while
the other services are checked in a sequence once per hour
during the day. Failures of the router will trigger
an sms, while service failures send an email.
{
"actions": {
"sms-admin": {
"type": "sms",
"options": { "recipient": "+1234234234" }
},
"email-all": {
"type": "email",
"options": {
"hostname": "mail.place.com",
"sender": "monitor@place.com",
"recipients": [ "admin@place.com", "info@place.com" ]
}
}
},
"checks": {
"place-gateway": {
"type": "ssh",
"trigger": { "interval": { "minutes": 5 } },
"options": { "hostname": "gw.place.com" },
"actions": [ "sms-admin" ]
},
"place-svc": {
"type": "sequence",
"trigger": { "cron": { "hour": "9-17", "minute": "0" } },
"options": { "checks": [ "place-email", "place-mbox", "place-web" ] },
"actions": [ "email-all" ]
},
"place-email": {
"type": "smtp",
"options": { "hostname": "mail.place.com" },
"depends": [ "place-gateway" ]
},
"place-mbox": {
"type": "imap",
"options": { "hostname": "mail.place.com" },
"depends": [ "place-gateway" ]
},
"place-web": {
"type": "https",
"options": { "hostname": "place.com" }
}
}
}
## 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 2025-06-15 start
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. Optionally provide a start time
to adjust the initial trigger.
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
--- | --- | ---
debug | bool | Include debugging information on web interface
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/f7/4a/806f43b2e9214586a3164f698a32e65671dfa1d6bc2728a5bc92fe35cbc6/fletchck-1.0.5.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.\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 supported:\n\n - smtp: SMTP with optional starttls\n - submit: SMTP-over-SSL/Submissions\n - imap: IMAP4-SSL mailbox\n - https: HTTP request\n - cert: Check TLS certificate validity and/or expiry\n - ssh: SSH pre-auth connection with optional hostkey check\n - disk: Disk space check, fails when usage exceeds percentage\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 - sequence: A sequence of checks, fails if any one check fails\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 SMS Central API\n - mqtt: Publish a one-shot MQTT message to the configured broker\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## Setup\n\nCreate a new empty site configuration in the current\ndirectory with the -init option:\n\n\t$ ./venv/bin/fletchck -init\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### 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\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) Request method: HEAD, GET, POST, PUT, DELETE, etc\nreqPath | str | (https) Request target resource\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\": 443 },\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 443 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### Example Config\n\nThe following complete configuration describes\na fletchck site with no web ui that runs a set\nof checks for a single site with a web site and\nSMTP, IMAP services behind a router.\nRouter connectivity is checked every 5 minutes while\nthe other services are checked in a sequence once per hour\nduring the day. Failures of the router will trigger\nan sms, while service failures send an email.\n\n\t{\n\t \"actions\": {\n\t \"sms-admin\": {\n\t \"type\": \"sms\",\n\t \"options\": { \"recipient\": \"+1234234234\" }\n\t },\n\t \"email-all\": {\n\t \"type\": \"email\",\n\t \"options\": {\n\t \"hostname\": \"mail.place.com\",\n\t \"sender\": \"monitor@place.com\",\n\t \"recipients\": [ \"admin@place.com\", \"info@place.com\" ]\n\t }\n\t }\n\t },\n\t \"checks\": {\n\t \"place-gateway\": {\n\t \"type\": \"ssh\",\n\t \"trigger\": { \"interval\": { \"minutes\": 5 } },\n\t \"options\": { \"hostname\": \"gw.place.com\" },\n\t \"actions\": [ \"sms-admin\" ]\n\t },\n\t \"place-svc\": {\n\t \"type\": \"sequence\",\n\t \"trigger\": { \"cron\": { \"hour\": \"9-17\", \"minute\": \"0\" } },\n\t \"options\": { \"checks\": [ \"place-email\", \"place-mbox\", \"place-web\" ] },\n\t \"actions\": [ \"email-all\" ]\n\t },\n\t \"place-email\": {\n\t \"type\": \"smtp\",\n\t \"options\": { \"hostname\": \"mail.place.com\" },\n\t \"depends\": [ \"place-gateway\" ]\n\t },\n\t \"place-mbox\": {\n\t \"type\": \"imap\",\n\t \"options\": { \"hostname\": \"mail.place.com\" },\n\t \"depends\": [ \"place-gateway\" ]\n\t },\n\t \"place-web\": {\n\t \"type\": \"https\",\n\t \"options\": { \"hostname\": \"place.com\" }\n\t }\n\t }\n\t}\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 2025-06-15 start\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### Interval\n\nThe check is scheduled to be run at a repeating interval\nof the specified number of weeks, days, hours, minutes\nand seconds. Optionally provide a start time\nto adjust the initial trigger.\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### 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## 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--- | --- | ---\ndebug | bool | Include debugging information on web interface\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## 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.0.5",
"project_urls": {
"homepage": "https://github.com/ndf-zz/fletchck"
},
"split_keywords": [
"system",
" monitor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "57cb305b5c8d6f212270327bf6ecba6f5131817b7eed20eca5be9332b966be64",
"md5": "51638eaf2987d348692c1386cb241781",
"sha256": "71c9f59564c7f5f98dba4e965c85cd7494eed5b55cd288027c98859e09416c50"
},
"downloads": -1,
"filename": "fletchck-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "51638eaf2987d348692c1386cb241781",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 87793,
"upload_time": "2024-07-29T05:57:26",
"upload_time_iso_8601": "2024-07-29T05:57:26.746982Z",
"url": "https://files.pythonhosted.org/packages/57/cb/305b5c8d6f212270327bf6ecba6f5131817b7eed20eca5be9332b966be64/fletchck-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f74a806f43b2e9214586a3164f698a32e65671dfa1d6bc2728a5bc92fe35cbc6",
"md5": "ee331ead93b3626ac7d625966d421233",
"sha256": "a343f34535035bcb9fd8cad48268be59fe68aa5f964adab2d8d198350ecf459e"
},
"downloads": -1,
"filename": "fletchck-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "ee331ead93b3626ac7d625966d421233",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 84350,
"upload_time": "2024-07-29T05:57:30",
"upload_time_iso_8601": "2024-07-29T05:57:30.724969Z",
"url": "https://files.pythonhosted.org/packages/f7/4a/806f43b2e9214586a3164f698a32e65671dfa1d6bc2728a5bc92fe35cbc6/fletchck-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 05:57:30",
"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"
}
