diff --git a/README.md b/README.md index c7ad57d..71688e7 100644 --- a/README.md +++ b/README.md @@ -2,29 +2,36 @@ Cross platform command line application to run health checks against sensor stations registered on [openSenseMap.org](https://opensensemap.org). -This tool quickly runs various health checks on selected senseBoxes, -and can send out notifications via various protocols. -Specifically email is implemented, but other transports can be added easily. +This tool lets you automatically check if senseBoxes are still runnning correctly, +and when that's not the case, notifies you. +Currently, email notifications are implemented, but other transports can be added easily. +Implemented health checks are [described below](#possible-values-for-defaulthealthchecksevents), and new ones can be added just as easily (given some knowledge of programming). -The tool can also operate in watch mode, checking boxes at regular intervals. +The tool has multiple modes of operation: -Check the manual in the [doc/](doc/osem_notify.md) directory for a description of features. +- `osem_notify check boxes`: run one-off checks on boxes +- `osem_notify watch boxes`: check boxes continuously + +Run `osem_notify help` or check the manual in the [docs/](docs/osem_notify.md) directory for more details. ## get it -Download a build from the [releases page](releases/). -You can immediately call the application by running `./osem_notify` in a terminal in your downloads directory. +Download a build from the [releases page](https://github.com/noerw/osem_notify/releases/). +You can run the application by running `./osem_notify*` in a terminal in your downloads directory. -On unix platforms you may add it to your path for convenience, so it is always callable via `osem_notify`: +On unix platforms you may need to make it executable, and can add it to your `$PATH` for convenience, so it is always callable via `osem_notify`: ```sh -sudo mv osem_notify /usr/bin/osem_notify +chmod +x osem_notify* +sudo mv osem_notify* /usr/bin/osem_notify ``` ## configure it -Configuration is required to set up notification transports, and can set the default healthchecks. +The tool works out of the box for basic functionality, but must be configured to set up notifications. + Configuration can be done via a YAML file located at `~/.osem_notify.yml` or through environment variables. Example configuration: ```yaml +# override default health checks: defaultHealthchecks: notifications: transport: email @@ -49,14 +56,14 @@ email: from: hildegunst@example.com ``` -### possible values for `notifications`: +### possible values for `defaultHealthchecks.notifications`: `transport` | `options` ------------|------------ `email` | `recipients`: list of email addresses Want more? [add it](#contribute)! -### possible values for `events[]`: +### possible values for `defaultHealthchecks.events[]`: `type` | description ---------------------|------------ @@ -71,8 +78,9 @@ Want more? [add it](#contribute)! ### configuration via environment variables Instead of a YAML file, you may configure the tool through environment variables. Keys are the same as in the YAML, but: -- prefixed with `osem_notify_` +- prefixed with `OSEM_NOTIFY_` - path separator is not `.`, but `_` +- all upper case Example: `OSEM_NOTIFY_EMAIL_PASS=supersecret osem_notify check boxes` @@ -92,7 +100,7 @@ Contributions are welcome! Check out the following locations for plugging in new functionality: - new notification transports: [core/notifiers.go](core/notifiers.go) -- new health checks: [core/Box.go](core/Box.go) +- new health checks: [core/healthcheck*.go](core/healtchecks.go) - new commands: [cmd/](cmd/) Before committing and submitting a pull request, please run `go fmt ./ cmd/ core/`. diff --git a/doc/osem_notify.md b/docs/osem_notify.md similarity index 60% rename from doc/osem_notify.md rename to docs/osem_notify.md index cd95100..3746504 100644 --- a/doc/osem_notify.md +++ b/docs/osem_notify.md @@ -13,17 +13,22 @@ osem_notify [flags] ### Options ``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") -c, --config string path to config file (default $HOME/.osem_notify.yml) -d, --debug enable verbose logging -h, --help help for osem_notify -l, --logformat string log format, can be plain or json (default "plain") -n, --notify if set, will send out notifications. - Otherwise results are printed to stdout only + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + ``` ### SEE ALSO * [osem_notify check](osem_notify_check.md) - One-off check for events on boxes +* [osem_notify debug](osem_notify_debug.md) - Run some debugging checks on osem_notify itself +* [osem_notify version](osem_notify_version.md) - Get build and version information * [osem_notify watch](osem_notify_watch.md) - Watch boxes for events at an interval -###### Auto generated by spf13/cobra on 24-Jun-2018 +###### Auto generated by spf13/cobra on 26-Jun-2018 diff --git a/doc/osem_notify_check.md b/docs/osem_notify_check.md similarity index 70% rename from doc/osem_notify_check.md rename to docs/osem_notify_check.md index 5494cdf..769d703 100644 --- a/doc/osem_notify_check.md +++ b/docs/osem_notify_check.md @@ -15,11 +15,14 @@ One-off check for events on boxes ### Options inherited from parent commands ``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") -c, --config string path to config file (default $HOME/.osem_notify.yml) -d, --debug enable verbose logging -l, --logformat string log format, can be plain or json (default "plain") -n, --notify if set, will send out notifications. - Otherwise results are printed to stdout only + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + ``` ### SEE ALSO @@ -27,4 +30,4 @@ One-off check for events on boxes * [osem_notify](osem_notify.md) - Root command displaying help * [osem_notify check boxes](osem_notify_check_boxes.md) - one-off check on one or more box IDs -###### Auto generated by spf13/cobra on 24-Jun-2018 +###### Auto generated by spf13/cobra on 26-Jun-2018 diff --git a/doc/osem_notify_check_boxes.md b/docs/osem_notify_check_boxes.md similarity index 70% rename from doc/osem_notify_check_boxes.md rename to docs/osem_notify_check_boxes.md index 2182c33..d00608f 100644 --- a/doc/osem_notify_check_boxes.md +++ b/docs/osem_notify_check_boxes.md @@ -19,15 +19,18 @@ osem_notify check boxes [...] [flags] ### Options inherited from parent commands ``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") -c, --config string path to config file (default $HOME/.osem_notify.yml) -d, --debug enable verbose logging -l, --logformat string log format, can be plain or json (default "plain") -n, --notify if set, will send out notifications. - Otherwise results are printed to stdout only + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + ``` ### SEE ALSO * [osem_notify check](osem_notify_check.md) - One-off check for events on boxes -###### Auto generated by spf13/cobra on 24-Jun-2018 +###### Auto generated by spf13/cobra on 26-Jun-2018 diff --git a/docs/osem_notify_debug.md b/docs/osem_notify_debug.md new file mode 100644 index 0000000..c63a2a8 --- /dev/null +++ b/docs/osem_notify_debug.md @@ -0,0 +1,37 @@ +## osem_notify debug + +Run some debugging checks on osem_notify itself + +### Synopsis + +osem_notify debug tests the functionality of the given feature + +``` +osem_notify debug [flags] +``` + +### Options + +``` + -h, --help help for debug +``` + +### Options inherited from parent commands + +``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + +``` + +### SEE ALSO + +* [osem_notify](osem_notify.md) - Root command displaying help +* [osem_notify debug notifications](osem_notify_debug_notifications.md) - Verify that notifications are working + +###### Auto generated by spf13/cobra on 26-Jun-2018 diff --git a/docs/osem_notify_debug_notifications.md b/docs/osem_notify_debug_notifications.md new file mode 100644 index 0000000..14b5188 --- /dev/null +++ b/docs/osem_notify_debug_notifications.md @@ -0,0 +1,36 @@ +## osem_notify debug notifications + +Verify that notifications are working + +### Synopsis + +osem_notify debug tests the functionality of the given feature + +``` +osem_notify debug notifications [flags] +``` + +### Options + +``` + -h, --help help for notifications +``` + +### Options inherited from parent commands + +``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + +``` + +### SEE ALSO + +* [osem_notify debug](osem_notify_debug.md) - Run some debugging checks on osem_notify itself + +###### Auto generated by spf13/cobra on 26-Jun-2018 diff --git a/docs/osem_notify_version.md b/docs/osem_notify_version.md new file mode 100644 index 0000000..c5d6baf --- /dev/null +++ b/docs/osem_notify_version.md @@ -0,0 +1,36 @@ +## osem_notify version + +Get build and version information + +### Synopsis + +osem_notify version returns its build and version information + +``` +osem_notify version [flags] +``` + +### Options + +``` + -h, --help help for version +``` + +### Options inherited from parent commands + +``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + +``` + +### SEE ALSO + +* [osem_notify](osem_notify.md) - Root command displaying help + +###### Auto generated by spf13/cobra on 26-Jun-2018 diff --git a/doc/osem_notify_watch.md b/docs/osem_notify_watch.md similarity index 72% rename from doc/osem_notify_watch.md rename to docs/osem_notify_watch.md index 3c22345..63e5187 100644 --- a/doc/osem_notify_watch.md +++ b/docs/osem_notify_watch.md @@ -16,11 +16,14 @@ Watch boxes for events at an interval ### Options inherited from parent commands ``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") -c, --config string path to config file (default $HOME/.osem_notify.yml) -d, --debug enable verbose logging -l, --logformat string log format, can be plain or json (default "plain") -n, --notify if set, will send out notifications. - Otherwise results are printed to stdout only + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + ``` ### SEE ALSO @@ -28,4 +31,4 @@ Watch boxes for events at an interval * [osem_notify](osem_notify.md) - Root command displaying help * [osem_notify watch boxes](osem_notify_watch_boxes.md) - watch a list of box IDs for events -###### Auto generated by spf13/cobra on 24-Jun-2018 +###### Auto generated by spf13/cobra on 26-Jun-2018 diff --git a/doc/osem_notify_watch_boxes.md b/docs/osem_notify_watch_boxes.md similarity index 72% rename from doc/osem_notify_watch_boxes.md rename to docs/osem_notify_watch_boxes.md index 222cdb9..160904d 100644 --- a/doc/osem_notify_watch_boxes.md +++ b/docs/osem_notify_watch_boxes.md @@ -19,16 +19,19 @@ osem_notify watch boxes [...] [flags] ### Options inherited from parent commands ``` + -a, --api string openSenseMap API to query against (default "https://api.opensensemap.org") -c, --config string path to config file (default $HOME/.osem_notify.yml) -d, --debug enable verbose logging -i, --interval int interval to run checks in minutes (default 15) -l, --logformat string log format, can be plain or json (default "plain") -n, --notify if set, will send out notifications. - Otherwise results are printed to stdout only + Otherwise results are printed to stdout only. + You might want to run 'osem_notify debug notifications' first to verify everything works. + ``` ### SEE ALSO * [osem_notify watch](osem_notify_watch.md) - Watch boxes for events at an interval -###### Auto generated by spf13/cobra on 24-Jun-2018 +###### Auto generated by spf13/cobra on 26-Jun-2018