# dwatch
## Overview
dwatch (*diff watch*) is a tool to monitor the output of a given command and notify the user on changes by sending an
email with a diff view.
## Installation
dwatch is available on PyPI and can be installed with `pip`:
```bash
python3 -m pip install dwatch
```
At least Python 3.6 is required.
If you run an Arch-based system, you can also install `dwatch` from the
[AUR](https://aur.archlinux.org/packages/dwatch/):
```bash
yay -S dwatch
```
You can also download self-contained executables (no Python installation required) for Linux x64 and macOS x64 from the
[releases page](https://github.com/IngoMeyer441/dwatch/releases).
## Usage
By default, dwatch runs a commmand passed on the command line every 60 seconds and notifies the user on any changes. You
can run a first test with:
```bash
dwatch -i 2 --stdout "date"
```
This runs the `date` command every 2 seconds and prints the output differences to stdout.
Pass the `--run-once` option to run one check, print a diff if necessary and exit. The diff is created against the
output from the previous run (command outputs are stored in the file `~/.dwatch_command_output.json`). This is
especially useful in cron jobs.
Without `--stdout` the diff output is sent as an HTML email. By default, dwatch uses the `sendmail` tool for this, which
is available if a local email server like Postfix or Exim is installed or if a simple mail forwarder like
[ssmtp](https://packages.debian.org/stable/ssmtp) is present. As an alternative, dwatch supports direct communication
with a mail server with Python's builtin [smtplib](https://docs.python.org/3/library/smtplib.html). This can be used if
no email server is installed locally. In either case, run
Use the `--description` option with a text argument to add a description to the diff report and the subject field of
emails. This can be useful to distinguish different commands.
```bash
dwatch --write-default-config
```
to create a default configuration file at `~/.dwatchrc`. Open the file with a text editor and configure a sender
`from_address` and receiver `to_address` in the `[mail]` section:
```text
[mail]
backend = sendmail
server = mail.example.com
login_user = jane.doe
login_password = xxx
encryption = starttls
from_address = dwatch-report@example.com
to_addresses = admin@example.com
```
Change `sendmail` to `smtplib` to use an arbitrary email provider and set the server address, the login credentials and
the encryption (`none`, `starttls` or `ssl`). If `none` is chosen, no login credentials are sent for security reasons.
This can only be used for very simple mail server setups.
## Configuration
These options can be configured in the file `~/.dwatchrc`:
- `[general]` section:
- `verbosity`: The logging level of the application. Can be one of `quiet`, `error`, `warn`, `verbose` or `debug`.
- `[mail]` section:
- `backend`: `sendmail` to use the local `sendmail` command or `smtplib` to connect to an arbitrary email server with
the smtp protocol.
- `server`: The mail server to use. This field is ignored if the `sendmail` backend is chosen.
- `login_user`: The login name for the mail server. This field is ignored if the `sendmail` backend is chosen.
- `login_password`: The login password for the mail server. This field is ignored if the `sendmail` backend is chosen.
- `encryption`: The encryption to use to connect to the mail server, can be `none` (not recommended!), `starttls` or
`ssl`. This field is ignored if the `sendmail` backend is chosen. If `none` is chosen, no login credentials are sent
for security reasons.
- `from_address`: The from address in the email envelope. Many providers do not support to change the from address and
overwrite this with your actual mail address.
- `to_address`: The recipient address.
- `[watch]` section:
- `interval`: The time interval in seconds between runs of the given command.
- `run_once`: If set to `True`, the command will only be run once the program exits. This is intended to be used with
cron jobs.
- `shell`: Run the given command in a subshell. This is useful to allow shell patterns in a command like pipes (for
example `command | grep pattern`).
## Command line options
```text
usage: dwatch [-h] [-d DESCRIPTION] [-i INTERVAL] [-o | -O] [-s | -S]
[--stdout] [-V] [-w] [-q | --error | --warn | -v | --debug]
[command]
dwatch is a tool for watching command output for changes and notifiying the
user. Default values for command line options are taken from the config file
at "~/.dwatchrc"
positional arguments:
command the command to watch
options:
-h, --help show this help message and exit
-d DESCRIPTION, --description DESCRIPTION
add a description which is added to the diff output
and used in the e-mail subject
-i INTERVAL, --interval INTERVAL
set the interval for the watched command (default:
"60.0")
-o, --run-once run the given command once and exit (default: "False")
-O, --no-run-once don't run the given command once and exit (default:
"True")
-s, --shell run the given command in a shell subprocess (default:
"False")
-S, --no-shell don't run the given command in a shell subprocess
(default: "True")
--stdout print the diff on stdout, do not send a mail
-V, --version print the version number and exit
-w, --write-default-config
create a configuration file with default values
(config filepath: "~/.dwatchrc")
-q, --quiet be quiet (default: "False")
--error print error messages (default: "False")
--warn print warning and error messages (default: "False")
-v, --verbose be verbose (default: "True")
--debug print debug messages (default: "False")
```
Raw data
{
"_id": null,
"home_page": "https://github.com/IngoMeyer441/dwatch",
"name": "dwatch",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.6",
"maintainer_email": "",
"keywords": "administration,monitoring",
"author": "Ingo Meyer",
"author_email": "i.meyer@fz-juelich.de",
"download_url": "https://files.pythonhosted.org/packages/a0/98/78c09b986706004a302621426c4c3f0fc9adb86bf2b75e46c0eb81be1ebc/dwatch-0.2.0.tar.gz",
"platform": null,
"description": "# dwatch\n\n## Overview\n\n\n\ndwatch (*diff watch*) is a tool to monitor the output of a given command and notify the user on changes by sending an\nemail with a diff view.\n\n## Installation\n\ndwatch is available on PyPI and can be installed with `pip`:\n\n```bash\npython3 -m pip install dwatch\n```\n\nAt least Python 3.6 is required.\n\nIf you run an Arch-based system, you can also install `dwatch` from the\n[AUR](https://aur.archlinux.org/packages/dwatch/):\n\n```bash\nyay -S dwatch\n```\n\nYou can also download self-contained executables (no Python installation required) for Linux x64 and macOS x64 from the\n[releases page](https://github.com/IngoMeyer441/dwatch/releases).\n\n## Usage\n\nBy default, dwatch runs a commmand passed on the command line every 60 seconds and notifies the user on any changes. You\ncan run a first test with:\n\n```bash\ndwatch -i 2 --stdout \"date\"\n```\n\nThis runs the `date` command every 2 seconds and prints the output differences to stdout.\n\nPass the `--run-once` option to run one check, print a diff if necessary and exit. The diff is created against the\noutput from the previous run (command outputs are stored in the file `~/.dwatch_command_output.json`). This is\nespecially useful in cron jobs.\n\nWithout `--stdout` the diff output is sent as an HTML email. By default, dwatch uses the `sendmail` tool for this, which\nis available if a local email server like Postfix or Exim is installed or if a simple mail forwarder like\n[ssmtp](https://packages.debian.org/stable/ssmtp) is present. As an alternative, dwatch supports direct communication\nwith a mail server with Python's builtin [smtplib](https://docs.python.org/3/library/smtplib.html). This can be used if\nno email server is installed locally. In either case, run\n\nUse the `--description` option with a text argument to add a description to the diff report and the subject field of\nemails. This can be useful to distinguish different commands.\n\n```bash\ndwatch --write-default-config\n```\n\nto create a default configuration file at `~/.dwatchrc`. Open the file with a text editor and configure a sender\n`from_address` and receiver `to_address` in the `[mail]` section:\n\n```text\n[mail]\nbackend = sendmail\nserver = mail.example.com\nlogin_user = jane.doe\nlogin_password = xxx\nencryption = starttls\nfrom_address = dwatch-report@example.com\nto_addresses = admin@example.com\n```\n\nChange `sendmail` to `smtplib` to use an arbitrary email provider and set the server address, the login credentials and\nthe encryption (`none`, `starttls` or `ssl`). If `none` is chosen, no login credentials are sent for security reasons.\nThis can only be used for very simple mail server setups.\n\n## Configuration\n\nThese options can be configured in the file `~/.dwatchrc`:\n\n- `[general]` section:\n\n - `verbosity`: The logging level of the application. Can be one of `quiet`, `error`, `warn`, `verbose` or `debug`.\n\n- `[mail]` section:\n\n - `backend`: `sendmail` to use the local `sendmail` command or `smtplib` to connect to an arbitrary email server with\n the smtp protocol.\n - `server`: The mail server to use. This field is ignored if the `sendmail` backend is chosen.\n - `login_user`: The login name for the mail server. This field is ignored if the `sendmail` backend is chosen.\n - `login_password`: The login password for the mail server. This field is ignored if the `sendmail` backend is chosen.\n - `encryption`: The encryption to use to connect to the mail server, can be `none` (not recommended!), `starttls` or\n `ssl`. This field is ignored if the `sendmail` backend is chosen. If `none` is chosen, no login credentials are sent\n for security reasons.\n - `from_address`: The from address in the email envelope. Many providers do not support to change the from address and\n overwrite this with your actual mail address.\n - `to_address`: The recipient address.\n\n- `[watch]` section:\n\n - `interval`: The time interval in seconds between runs of the given command.\n - `run_once`: If set to `True`, the command will only be run once the program exits. This is intended to be used with\n cron jobs.\n - `shell`: Run the given command in a subshell. This is useful to allow shell patterns in a command like pipes (for\n example `command | grep pattern`).\n\n## Command line options\n\n```text\nusage: dwatch [-h] [-d DESCRIPTION] [-i INTERVAL] [-o | -O] [-s | -S]\n [--stdout] [-V] [-w] [-q | --error | --warn | -v | --debug]\n [command]\n\ndwatch is a tool for watching command output for changes and notifiying the\nuser. Default values for command line options are taken from the config file\nat \"~/.dwatchrc\"\n\npositional arguments:\n command the command to watch\n\noptions:\n -h, --help show this help message and exit\n -d DESCRIPTION, --description DESCRIPTION\n add a description which is added to the diff output\n and used in the e-mail subject\n -i INTERVAL, --interval INTERVAL\n set the interval for the watched command (default:\n \"60.0\")\n -o, --run-once run the given command once and exit (default: \"False\")\n -O, --no-run-once don't run the given command once and exit (default:\n \"True\")\n -s, --shell run the given command in a shell subprocess (default:\n \"False\")\n -S, --no-shell don't run the given command in a shell subprocess\n (default: \"True\")\n --stdout print the diff on stdout, do not send a mail\n -V, --version print the version number and exit\n -w, --write-default-config\n create a configuration file with default values\n (config filepath: \"~/.dwatchrc\")\n -q, --quiet be quiet (default: \"False\")\n --error print error messages (default: \"False\")\n --warn print warning and error messages (default: \"False\")\n -v, --verbose be verbose (default: \"True\")\n --debug print debug messages (default: \"False\")\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to watch command output for differences and send notifications.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/IngoMeyer441/dwatch"
},
"split_keywords": [
"administration",
"monitoring"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "34b21626db3a0e707255df39b379caab4ed353c95228c7fd2274627bcf90558a",
"md5": "18ede4fb4a968f9dd01a6b336a13ccca",
"sha256": "6dc8d2f39c643e13ea17b7db8eaf38087f2099984753ee0f8fc73ae0b2aa683e"
},
"downloads": -1,
"filename": "dwatch-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18ede4fb4a968f9dd01a6b336a13ccca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.6",
"size": 13651,
"upload_time": "2023-06-12T11:05:23",
"upload_time_iso_8601": "2023-06-12T11:05:23.310530Z",
"url": "https://files.pythonhosted.org/packages/34/b2/1626db3a0e707255df39b379caab4ed353c95228c7fd2274627bcf90558a/dwatch-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a09878c09b986706004a302621426c4c3f0fc9adb86bf2b75e46c0eb81be1ebc",
"md5": "f6f943858c0072877493b9689a9d7f55",
"sha256": "58fd293dbd648b7babb252ee29443b4dccf2705d5e6701b8217d2a7f382ba724"
},
"downloads": -1,
"filename": "dwatch-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f6f943858c0072877493b9689a9d7f55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.6",
"size": 14349,
"upload_time": "2023-06-12T11:05:25",
"upload_time_iso_8601": "2023-06-12T11:05:25.123579Z",
"url": "https://files.pythonhosted.org/packages/a0/98/78c09b986706004a302621426c4c3f0fc9adb86bf2b75e46c0eb81be1ebc/dwatch-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-12 11:05:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IngoMeyer441",
"github_project": "dwatch",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dwatch"
}
JSON
