Add documentation (#19)

* Update docs for initial version

* Update docs with new files

* Update most documentation sections. Add info to readme.

* Add new docs.

* Finalize the docs for release

* Fix issue with the plugins not being able to run as passive checks

* Update version for release

* Update with how to build the docs

* Fix typo

Author: jomann09

.gitignore

@@ -1,6 +1,7 @@
 ./config.yml
 build/bin/*
 build/rcagent.spec
+site
 rcagent.pem
 rcagent.key
 rcagent.exe

CHANGELOG.md

@@ -1,3 +1,7 @@
+06/25/2023 - 1.0.4
+==================
+- Fixed passive check plugins endpoint not able to run due to invalid check error
+
 05/01/2023 - 1.0.3
 ==================
 - Added cpuPercent and memPercent to processes output (#14)

README.md

@@ -1,14 +1,17 @@
 [![Go Test/Build](https://github.com/rechecked/rcagent/actions/workflows/go.yml/badge.svg)](https://github.com/rechecked/rcagent/actions/workflows/go.yml)
+[![GitHub release](https://img.shields.io/github/release/rechecked/rcagent?include_prereleases=&sort=semver&color=blue)](https://github.com/rechecked/rcagent/releases/)
+[![License](https://img.shields.io/badge/License-GPLv3-blue)](https://github.com/rechecked/rcagent/blob/main/LICENSE)
+[![rcagent - Documentation](https://img.shields.io/badge/rcagent-Documentation-informational)](https://docs.rechecked.io/rcagent)
 
 ReChecked Agent (rcagent) is light-weight, cross-platform, API-based agent that is compatible with Nagios (using NRDP and check_rcagent) check-based monitoring systems.
 
 ### For Binary Installs
 
 We currently build for: Windows, macOS (12+), CentOS Stream/RHEL (8+), Debian (10+), Ubuntu (18+ LTS)
 
-We recommend [using the repo install](https://repo.rechecked.io/) for CentOS/RHEL, Debian, and Ubuntu.
+Follow the [installation guide in the rcagent documentation](https://docs.rechecked.io/rcagent/getting-started/installation/).
 
-Download from [GitHub releases](https://github.com/rechecked/rcagent/releases) or [download from rechecked.io](https://rechecked.io/download)
+Download from [GitHub releases](https://github.com/rechecked/rcagent/releases).
 
 ### For Source Install
 
@@ -32,11 +35,22 @@ If you'd like to run the source version as a service, you can install the servic
 
 ### Using rcagent
 
-You can read how to [get started](https://rechecked.io/quick-start-guide/) and you can install the config wizard or plugin below.
+Read more about how to use rcagent in the [documentation](https://docs.rechecked.io/rcagent/).
 
-- **Nagios XI** - Download and install the latest [ReChecked Nagios XI Config Wizard](https://rechecked.io/download) in the XI GUI.
-- **Nagios Core** - Download the [check_rcagent.py](https://rechecked.io/download) file, place it in `/usr/local/nagios/libexec`.
+- **Nagios XI** - Download and install the latest [ReChecked Nagios XI Config Wizard](https://github.com/rechecked/rcagent-nagiosxi/releases/latest/download/rcagent.zip) in the XI GUI.
+- **Nagios Core** - Download the [check_rcagent.py](https://github.com/rechecked/rcagent-plugins/releases/latest/download/check_rcagent.py) file, place it in `/usr/local/nagios/libexec`.
 
 ### Config Options
 
-For a full list of config options in config.yml, check the [config options page](https://rechecked.io/config-options/).
+For a full list of config options in `config.yml`, check the [config options documentation](https://docs.rechecked.io/config/options/).
+
+### Building Documentation
+
+If you'd like the build your own set of docs (you'll need to host them in order for them to work properly) you can run the following:
+
+Install mkdocs-material and run the mkdocs build:
+
+```
+pip install mkdocs-material
+mkdocs build
+```

VERSION

@@ -1 +1 @@
-1.0.3
+1.0.4

build/package/config.yml

@@ -72,3 +72,5 @@ pluginTypes:
 #    options:
 #      warning: 10
 #      critical: 20
+
+

docs/assets/favicon.ico

@@ -0,0 +1,104 @@
+# Active Checks
+
+Active checks are checks where the request for data is sent from `check_rcagent.py` to the agent's Status API. The returned output, exit code, and perfdata is already in the Nagios plugins return format and the `check_rcagent.py` plugin just outputs what is returned, it does not do any data or check processing on the plugin side.
+
+In general, active checks are configured on the monitoring system (Nagios Core) and each active check is ran as a full command with returned exit code, output, and perfdata, which is what the monitoring system uses to determine if things are OK or not.
+
+## Downloading `check_rcagent.py`
+
+If you don't have the plugin already, you can [download the latest version](https://github.com/rechecked/rcagent-plugins/releases/latest/download/check_rcagent.py).
+
+There is a [GitHub rcagent-plugins repo](https://github.com/rechecked/rcagent-plugins) specifically for the plugins, so if you have any problems with the plugin, feel free to mention them in the issues.
+
+## Installing `check_rcagent.py`
+
+If you are using Nagios Core, you will need to copy the plugin into the plugins directory. Normally the directory is `/usr/local/nagios/libexec` but may be different on your specific system if you've customized the paths or installed via a repo.
+
+## Using `check_rcagent.py`
+
+Endpoints (such as CPU, Memory, Services, etc) are reached using `-e <endpoint>` while plugins are ran using `-p <plugin>`.
+
+A typical call with the plugin will look similar to this:
+
+```
+./check_rcagent.py -H <host> -t <token> -e <endpoint> -w <warning> -c <critical>
+```
+
+Another useful feature is using `-q` to pass query arguments. This is necessary for things like services or processes when you need to send a name or value. You can add multiple `-q` values on the command line, like so:
+
+```
+./check_rcagent.py -H <host> -t <token> -e <endpoint> -q "name=test" -q "name2=test2"
+```
+
+!!! note
+
+	There are more options than what we show here! You can use the `--help` option to see all available options.
+
+### Endpoint Examples
+
+The endpoint checks are available by default on any rcagent and does not require special setup, unlike plugins which have to be added after installation.
+
+Here are a few examples of endpoint checks. If you want to see more endpoints you can use, check the Status API Reference section.
+
+#### Disk Check
+
+An example of a basic [disk](../../status-api/disk) check using the path value of `/` (root) and showing the return output. Note that the return output also includes any perfdata for the check. Some checks may not have perfdata associated with them.
+
+Command:
+
+```
+./check_rcagent.py -H <host> -t <token> -e disk -q path=/
+```
+
+Output:
+
+```
+OK: Disk usage of / is 34.91% (12.23/35.04 GiB Total) | 'percent'=34.91% 'used'=12.23GiB 'free'=22.81GiB 'total'=35.04GiB
+```
+
+#### Service Check
+
+When running against the [services](../../status-api/services) endpoint, you need to pass an `against` and `expected` parameter. The `against` parameter is the name of the service you want to run the check against. If the service status matches the `expected` value, it will be OK, otherwise it is CRITICAL.
+
+```
+./check_rcagent.py -H <host> -t <token> -e services -q "against=rcagent" -q "expected=running"
+```
+
+Output:
+
+```
+OK: rcagent is [running] (expected value is [running])
+```
+
+#### Memory Check
+
+Most checks that return a number run with a `-w` (warning) and `-c` (critical) value. Memory checks are example of this. You can also adjust the units returned by sending in `-u`.
+
+```
+./check_rcagent.py -H <host> -t <token> -e memory/virtual -w 20 -c 60 -u GB
+
+```
+
+Output:
+
+```
+WARNING - Memory usage is 24.11% (16.49/68.38 GB Total) | 'percent'=24.11%;20;60 'available'=51.89GB;20;60 'used'=16.49GB;20;60 'free'=51.89GB;20;60 'total'=68.38GB;20;60
+```
+
+### Plugins Example
+
+Plugins are added to the plugins directory. You specify the plugin you want to run using the `-p` flag rather than the `-e` endpoint flag.
+
+When running a plugin use `--arg=""` for proper parsing rather than `-a` if you are using `-`/`--` in your arugment. An example of this is:
+
+```
+./check_rcagent.py -H <host> -t <token> -p check_test.sh --arg="--warning 10" --arg="-c 20"
+```
+
+Output:
+
+```
+--warning 10 -c 20
+```
+
+The above `check_test.sh` plugin just echos out whatever is passed to the plugin. So in the output we see the two arguments that we passed to the plugin.

docs/assets/rechecked-white.png

@@ -0,0 +1,88 @@
+# Passive Checks
+
+Passive checks are a type of check that run on the agent side and the results are sent to the monitotring system. In our case, we normally send passive checks to Nagios via NRDP. You can use NRDP with both Nagios Core and Nagios XI which includes it pre-configured by default.
+
+## Why Use Passive Checks?
+
+One of the biggest reasons for using passive checks is that it will offload some of the resource requirements from the monitoring system. Active checks are ran through a subprocess by Nagios Core and will use various amounts of system resources depending on the kind of check.
+
+Passive checks are more like a distributed system; running specific checks for the Nagios Core instance and returning just the output, result code, and perfdata back to Nagios Core. The resources required to read that data is much less than used to do the checks themselves.
+
+!!! note
+
+	There is one difference with passive checks compared to active checks that you should remember. You will need to set up [freshness checks](https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/4/en/freshness.html) for passive checks to ensure that if you are no longer recieving a check from rcagent, you know there is a problem you need to deal with!
+
+## Setup NRDP Sender(s)
+
+You can configure one or more [`senders`](../../config/options/#senders) to send passive checks. Currently the only available sender is for NRDP which comes installed by default on Nagios XI but can easily be added to Nagios Core if you follow the [NRDP readme on GitHub](https://github.com/NagiosEnterprises/nrdp).
+
+If you have multiple senders, all checks performed will be sent to all the senders you have added.
+
+Example sender config:
+
+```
+senders:
+  - name: NRDP Server 1
+    url: http://192.168.0.100/nrdp/
+    token: sometoken
+    type: nrdp
+```
+
+## Adding Passive Checks
+
+It is possible to add as many passive checks as you want to your system. One of the nice things about passive checks is that you can run plugins and offload some of the work from your main monitoring system.
+
+Each check can be set with a pecific `interval` time, which is per check. There are also other [`checks` config options available](../../config/checks).
+
+### Example Host Check
+
+The variable `$HOST` will be replaced with the hostname of the rcagent system
+
+```
+checks:
+  - hostname: $HOST
+    interval: 5m
+    endpoint: system/version
+    options:
+      warning: 10
+      critical: 20
+```
+
+### Example Service Checks
+
+Example of service checks, including running a plugin as a passive service check:
+
+```
+checks:
+  - hostname: $HOST
+    servicename: Custom Plugin
+    interval: 5m
+    endpoint: plugins
+    options:
+      plugin: check_test.ps1
+      args:
+        - -m "hello and test!"
+        - --dir /test/dir
+  - hostname: $HOST
+    servicename: CPU Usage
+    interval: 30s
+    endpoint: cpu/percent
+    options:
+      warning: 10
+      critical: 20
+  - hostname: $HOST
+    servicename: Memory Usage
+    interval: 5m
+    endpoint: memory/virtual
+    options:
+      warning: 80
+      critical: 90
+  - hostname: $HOST
+    servicename: Disk Usage - C:
+    interval: 1h
+    endpoint: disk
+    options:
+      path: C:
+      warning: 70
+      critical: 90
+```

docs/checks/active-checks.md

@@ -0,0 +1,54 @@
+# Checks
+
+Checks are passive checks configured to run at certain intervals while rcagent is running. These checks are sent to some other location (like NRDP) using [senders](../options#senders).
+
+In the YAML file, `checks` is a list of checks to run. You can have as many passive check configurations as you want.
+
+## Special Values
+
+### `$HOST`
+
+This value is populated with the hostname of the system the rcagent is running on.
+
+## Config Options
+
+Options with a * next to them are **required**.
+
+### `hostname` *
+
+The hostname associated with the passive check.
+
+### `servicename`
+
+The service name (or service description, if a service check) associated with the passive check.
+
+### `interval` *
+
+The interval in which to run the check. It can be in format: `Xs` (seconds), `Xm` (minutes), `Xh` (hours) where `X` is a number.
+
+### `endpoint ` *
+
+The endpoint to use for the check, just like an active check. Example is `memory/virtual` or `services`.
+
+### `options`
+
+You can pass all the normal URL-style parameters in the options, such as warning/critical value and more. See the example in the [`config.yml`](../options) file for formatting.
+
+## Example Check Config
+
+```
+checks:
+  - hostname: $HOST
+    interval: 5m
+    endpoint: system/version
+    options:
+      warning: 10
+      critical: 20
+  - hostname: $HOST
+    servicename: CPU Usage
+    interval: 30s
+    endpoint: cpu/percent
+    options:
+      warning: 10
+      critical: 20
+```

docs/checks/passive-checks.md

@@ -0,0 +1,32 @@
+# Manager
+
+If you are using ReChecked Manager, you will use this section to tell the agent how to connect to the manager along with some options that tell it how to interact and behave with the manager.
+
+Configuration for this section should be under the top level `manager` section.
+
+## Config Options
+
+Options with a * next to them are **required**.
+
+### `url`
+
+Optional URL value to the manager.
+
+**Default:** `https://manage.rechecked.io`
+
+### `apikey` *
+
+The API key for the organization that the agent should be connected to in the manager.
+
+### `ignoreCert`
+
+By default the certificate for the manager is verified. If you'd like to ignore it for some reason, set this value to `true`.
+
+**Default:** `false`
+
+## Example Manager Config
+
+```
+manager:
+	apikey: 5E51781D7FFF4E0AA757132B017AAC80
+```