From 68372af7d74fc6527a7d24f2af47deda4209b30d Mon Sep 17 00:00:00 2001 From: Trey Blancher Date: Thu, 24 Aug 2023 10:00:32 -0400 Subject: [PATCH] Fleshed out both documents --- CONFIGURE.md | 38 ++++++++++++++++++++++++++++++++++++++ README.md | 13 +++++++++++++ 2 files changed, 51 insertions(+) diff --git a/CONFIGURE.md b/CONFIGURE.md index 4140c28..3339355 100644 --- a/CONFIGURE.md +++ b/CONFIGURE.md @@ -25,6 +25,7 @@ Environment=EMAIL_TO="email@domain.tld" Environment=SMS_DST="phone_number@sms.domain.tld" Environment=NOTIFICATION_CMD="dunstify" Environment=NOTIFICATION_OPTS="--timeout=0 --printid --urgency=critical --icon=/usr/share/icons/breeze-dark/emblems/16/emblem-warning.svg" +Environment=NOTIFICATION_HIST_CMD="dunstctl history" Environment=NOTIFICATION_IDX=15 Environment=SSH_USER="username" Environment=SSH_HOST="localhost" @@ -49,3 +50,40 @@ Environment=CLEAR_THRESHOLD="5.0" # WantedBy=multi-user.target ``` +All of these are required except where noted, there are no default options +(defaults may be added in the future). A brief description of each: +* **EMAIL_TO**: the email address the notification should be sent to. The + output of `pidstat` will be included in the body of this email, for each + triggered resource type (CPU, I/O, Memory), at the time the monitor alerted. +* **SMS_DST**: the email-to-SMS address, as defined by your mobile carrier. + Please review your mobile carrier's documentation. For Google Fi, based in + the US, the format is + `@msg.fi.google.com`. This email address + does **not** get the output of `pidstat` in the body of the message. +* **NOTIFICATION_CMD**: The command on the remote host to run to display + notifications, e.g. `notify-send` or `dunstify`. +* **NOTIFICATION_OPTS**: Options for the `${NOTIFICATION_CMD}`. Should + include `--print-id` if supported by the command. +* **NOTIFICATION_HIST_CMD**: The command to display the notification history + (e.g. `dunst history`). +* **NOTIFICATION_IDX**: The index if the JSON structure that contains the + notification ID. `dunst`, as of version 1.9.2-1, displays its history as a + JSON structure. For other notification daemons, some other history mechanism + will likely be required; patches needed and welcome! +* **SSH_USER**: The SSH username to connect to the remote host that will + display the notifications to the system administrator. +* **SSH_HOST**: The SSH host to connect to. This is where + `${NOTIFICATION_CMD} ${NOTIFICATION_OPTS}` and `${NOTIFICATION_HIST_CMD}` + will run. +* **SSH_PORT**: The SSH port to connect to. +* **SSH_ID_PATH**: The path to the SSH id (private key file) to use for + authenticating to the remote host. This can be exluded if the local user + already has an ssh-agent running, with the necessary key and passphrase + entered. If ssh-agent is not desired, then this SSH id (private key file) + should have an empty passphrase (i.e., no passphrase). Not having this + environment variable, and no ssh-agent will disable the desktop notifications + (SMS and email will still work, as they don't use SSH) +* **CLEAR_THRESHOLD**: The percentage threshold the some avg300 threshold + should be below before considering the alert cleared. This will depend + highly on the workload running on + diff --git a/README.md b/README.md index 9ce0b06..12a451c 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,18 @@ near real time. * psi-by-example (a modified version of this is included in this project as a submodule) * a libnotify-compatible desktop notification system + * any notification program should use the `--print-id` parameter if + possible + * both `notify-send` and `dunstify` (part of + [dunst](https://dunst-project.org/)) support this + * note, this has only been tested with `dunst`, since it has the capability + of showing notification history + * `notify-send` specifically does not appear to retain a history, so the + `check_dunst_id_is_visible` function won't work with it (and the logic to + skip sending a new notification if one is already sent will be broken). + * since I don't use `notify-send`, I'm not sure how to solve this + * patches welcome! +* jq (for the aformentioned `dunst` integration) ## History @@ -98,6 +110,7 @@ below the configurable threshold for at least five minutes). * consider reworking this for a user service, not a system service * this could make desktop notifications simpler, and not having to use SSH keys without passphrases + * possibly learn how to connect to an existing ssh-agent * need to become much more familiar with user services * consider reworking all code in a compiled language (other than C) * time to learn Go