psi-alerts/CONFIGURE.md

# CONFIGURE Included in this project are a number of systemd units:
    * psi-monitor.service
        * uses psi-monitor executable (in /usr/bin/)
    * psi-alerts@.service (systemd template service)
        * uses psi-alerts.sh script in */usr/local/bin/*
    * psi-alerts-user.service (systemd user service)
        * also uses psi-alerts.sh script in *~/bin/* (or wherever you want to
          put it)

The `psi-alerts.sh` is essentially a daemon (a systemd simple service), and for
now the systemd template needs to be instantiated with the username that will
execute `psi-alerts.sh` (if using the systemd template).  Also, a systemd unit
override should be created, like so:  

```
sudo cp psi-alerts@.service /etc/systemd/system/
sudo systemctl edit psi-alerts@<user>.service
```
--OR--
```
cp psi-alerts-user.service ~/.config/systemd/user/psi-alerts.service
systemctl --user edit psi-alerts.service
```
This will open an editor, and in later versions of systemd the comment code will be included, clearly showing where the override should be entered:

```
### Editing /etc/systemd/system/psi-alerts@trey.service.d/override.conf
### Anything between here and the comment below will become the contents of the drop-in file

[Service]
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"
Environment=SSH_PORT=5999
Environment=SSH_ID_PATH="~user/.ssh/psi-alerts"
Environment=CLEAR_THRESHOLD="5.0"
ExecStart=  # Clear ExecStart for user unit
ExecStart=/path/to/psi-alerts.sh --user # User unit

### Edits below this comment will be discarded

### /etc/systemd/system/psi-alerts@.service
# [Unit]
# Description=Pressure Stall Information (PSI) alerts
# PartOf=multi-user.target  # system template
# PartOf=default.target     # user service
# After=psi-monitor.service
#
# [Service]
# 
# User=%i # User unit will not have User=%i
# Type=simple
# ExecStart=psi-alerts.sh
#
# [Install]
# 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
  `<mobile_number_without_country_code>@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 the system.