From 68f20c80f58497d0e7d249526028a87cb335b1e8 Mon Sep 17 00:00:00 2001 From: James Seward Date: Wed, 3 Mar 2021 19:09:12 +0000 Subject: [PATCH] WIP new docs --- .gitignore | 1 + docs/Makefile | 20 ++ docs/command-line.rst | 0 docs/conf.py | 68 ++++++ docs/configuration.rst | 223 +++++++++++++++++++ docs/index.rst | 129 +++++++++++ docs/installation.rst | 78 +++++++ docs/make.bat | 35 +++ docs/monitors.rst | 477 +++++++++++++++++++++++++++++++++++++++++ docs/requirements.txt | 2 + setup.cfg | 2 +- 11 files changed, 1034 insertions(+), 1 deletion(-) create mode 100644 docs/Makefile create mode 100644 docs/command-line.rst create mode 100644 docs/conf.py create mode 100644 docs/configuration.rst create mode 100644 docs/index.rst create mode 100644 docs/installation.rst create mode 100644 docs/make.bat create mode 100644 docs/monitors.rst create mode 100644 docs/requirements.txt diff --git a/.gitignore b/.gitignore index 62ca49ad..14525379 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,4 @@ simplemonitor.code-workspace client.log master.log coverage.xml +_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/command-line.rst b/docs/command-line.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..f95c4ef2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,68 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) +import sphinx_rtd_theme # noqa: F401 +from sphinx.application import Sphinx +from sphinx.util.docfields import Field + +# -- Project information ----------------------------------------------------- + +project = "SimpleMonitor" +copyright = "2021, James Seward" +author = "James Seward" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ["sphinx_rtd_theme"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + + +# Borrowed from mypy's conf.py +def setup(app: Sphinx) -> None: + app.add_object_type( + "confval", + "confval", + objname="configuration value", + indextemplate="pair: %s; configuration value", + doc_field_types=[ + Field("type", label="Type", has_arg=False, names=("type",)), + Field("default", label="Default", has_arg=False, names=("default",)), + Field("required", label="Required", has_arg=True, names=("required",)), + ], + ) diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 00000000..b89be1e9 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,223 @@ +Configuration +============= + +The main configuration lives in :file:`monitor.ini`. By default, SimpleMonitor will +look for it in the working directory when launched. To specify a different +file, use the ``-f`` option. + +The format is fairly standard "INI"; section names are lowercase in ``[square +brackets]``, and values inside the sections are defined as ``key=value``. You +can use blank lines to space things out, and comments start with ``#``. + +Section names and option values, but not option names, support environment +variable injection. To include the value of an environment variable, use +``%env:VARIABLE%``, which will inject the value of ``$VARAIBLE`` from the +environment. You can use this to share a common configuration file across +multiple hosts, for example. + +This main configuration file contains the global settings for SimpleMonitor, +plus the logging and alerting configuration. A separate file, by default +:file:`monitors.ini`, contains the monitor configuration. You can specify a +different monitors configuration file using a directive in the main +configuration. + +.. warning:: I know the configuration file names are dumb, sorry. + +.. _config-bytes: + +Configuration value types +------------------------- + +Values which take **bool** accept ``1``, ``yes``, and ``true`` as truthy, and +everything else as falsey. + +Values which take **bytes** accept suffixes of ``K``, ``M``, or ``G`` for +kibibytes, mibibytes or gibibytes, otherwise are just a number of bytes. + +``monitor.ini`` +--------------- + +This file must contain a ``[monitor]`` section, which must contain at least the ``interval`` setting. + +``[monitor]`` section +^^^^^^^^^^^^^^^^^^^^^ + +.. confval:: interval + + :type: integer + :required: true + + defines how many seconds to wait between running all the monitors. Note that + the time taken to run the monitors is not subtracted from the interval, so + the next iteration will run at interval + time_to_run_monitors seconds. + +.. confval:: monitors + + :type: string + :required: false + :default: ``monitors.ini`` + + the filename to load the monitors themselves from. Relative to the cwd, not + the path of this configuration file. + +.. confval:: pidfile + + :type: string + :required: false + :default: none + + the path to write a pidfile to. + +.. confval:: remote + + :type: bool + :required: false + :default: false + + enables the listener for receiving data from remote instances. Can be + overridden to disabled with ``-N`` command line option. + +.. confval:: remote_port + + :type: integer + :required: if ``remote`` is enabled + + the TCP port to listen on for remote data + +.. confval:: key + + :type: string + :required: if ``remote`` is enabled + + shared secret for validating data from remote instances. + +.. confval:: bind_host + + :type: string + :required: false + :default: ``0.0.0.0`` (all interfaces) + + the local IP address to listen on, if ``remote`` is enabled. + +.. confval:: hup_file + + :type: string + :required: false + :default: none + + a file to watch the modification time on. If the modification time increases, SimpleMonitor reloads its configuration. + + .. tip:: SimpleMonitor will reload if it receives SIGHUP; this option is useful for platforms which don't have that. + +.. confval:: bind_host + + :type: string + :required: false + :default: all interfaces + + the local address to bind to for remote data + +``[reporting]`` section +^^^^^^^^^^^^^^^^^^^^^^^ + +.. confval:: loggers + + :type: comma-separated list of string + :required: false + :default: none + + the names of the loggers you want to use. Each one must be a ``[section]`` in this configuration file. + + See Loggers for the common options and list of Alerters with their configurations. + +.. confval:: alerters + + :type: comma-separated list of string + :required: false + :default: none + + the names of the alerters you want to use. Each one must be a ``[section]`` in this configuration file. + + See Alerters for the common options and list of Alerters with their configurations. + +``monitors.ini`` +---------------- + +This file only contains monitors. Each monitor is a ``[section]`` in the file, +with the section name giving the monitor its name. The name ``defaults`` is +reserved, and can be used to specify default values for options. Each monitor's +individual configuration overrides the defaults. + +See Monitors for the common options and list of Monitors with their configurations. + +Example configuration +--------------------- + +This is an example pair of configuration files to show what goes where. For more examples, see :ref:`Config examples`. + +:file:`monitor.ini`: + +.. code-block:: ini + + [monitor] + interval=60 + + [reporting] + loggers=logfile + alerters=email,sms + + # write a log file with the state of each monitor, each time + [logfile] + type=logfile + filename=monitor.log + + # email me when monitors fail or succeed + [email] + type=email + host=mailserver.example.com + from=monitor@example.com + to=admin@example.com + + # send me an SMS after a monitor has failed 10 times in a row + [sms] + type=bulksms + username=some-username + password=some-password + target=+447777123456 + limit=10 + +:file:`monitors.ini`: + +.. code-block:: ini + + # check the webserver pings + [www-ping] + type=ping + host=www.example.com + + # check the webserver answers https; don't bother checking if it's not pinging + [www-http] + type=http + url=https://www.example.com + depend=www-ping + + # check the root partition has at least 1GB of free space + [root-diskspace] + type=diskspace + partition=/ + limit=1G + + +Reloading +--------- + +You can send SimpleMonitor a SIGHUP to make it reload its configuration. On +platforms which don't have that (e.g. Windows), you can specify a file to +watch. If the modification time of the file changes, SimpleMonitor will reload +its configration. + +Reloading will pick up a change to ``interval`` but no other configuration in +the ``[monitor]`` section. Monitors, Alerters and Loggers are reloaded. You can +add and remove them, and change their configurations, but not change their +types. (To change a type, first remove it from the configuration and reload, +then add it back in.) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..9692324c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,129 @@ +.. SimpleMonitor documentation master file, created by + sphinx-quickstart on Sun Jan 31 19:23:11 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to SimpleMonitor +======================== + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Getting started + + installation + configuration + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Configuration Reference + + monitors + alerters + loggers + configuration-examples + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Extending + + creating-monitors + creating-alerters + creating-loggers + + +SimpleMonitor is a Python script which monitors hosts and network +connectivity. It is designed to be quick and easy to set up and lacks complex +features that can make things like Nagios, OpenNMS and Zenoss overkill for a +small business or home network. Remote monitor instances can send their +results back to a central location. + +SimpleMonitor supports Python 3.6.2 and higher on Windows, Linux and FreeBSD. + +Features +======== + +Things SimpleMonitor can monitor +-------------------------------- + +For the complete list, see :ref:`Monitors`. + +* Host ping +* Host open ports (TCP) +* HTTP (is a URL fetchable without error? Does the page content it match a regular expression?) +* DNS record return value +* Services: Windows, Linux, FreeBSD services are supported +* Disk space +* File existence, age and time +* FreeBSD portaudit (and pkg audit) for security notifications +* Load average +* Process existence +* Exim queue size monitoring +* APC UPS monitoring (requires apcupsd to be installed and configured) +* Running an arbitrary command and checking the output +* Compound monitors to combine any other types + +Adding your own Monitor type is straightforward with a bit of Python knowledge. + +Logging and Alerting +-------------------- + +To SimpleMonitor, a Logger is something which reports the status of every +monitor, each time it's checked. An Alerter sends a message about a monitor +changing state. + +Some of the options include (for the complete list, see :ref:`Loggers` and :ref:`Alerters`): + +* Writing the state of each monitor at each iteration to a SQLite database +* Sending an email alert when a monitor fails, and when it recovers, directly over SMTP or via Amazon SES +* Writing a log file of all successes and failures, or just failures +* Sending a message via BulkSMS, Amazon Simple Notification Service (SNS), Telegram, Slack, MQTT (with HomeBridge support) and more +* Writing an HTML status page +* Writing an entry to the syslog (non-Windows only) +* Executing arbitary commands on monitor failure and recovery + +Other features +-------------- + +* Simple configuration file format: it’s a standard INI file for the overall configuration and another for the monitor definitions +* Remote monitors: An instance running on a remote machine can send its results back to a central instance for central logging and alerting +* Dependencies: Monitors can be declared as depending on the success of others. If a monitor fails, its dependencies will be skipped until it succeeds +* Tolerance: Monitors checking things the other side of unreliable links or which have many transient failures can be configured to require their test to fail a number of times in a row before they report a problem +* Escalation of alerts: Alerters can be configured to require a monitor to fail a number of times in a row (after its tolerance limit) before they fire, so alerts can be sent to additional addresses or people +* Urgency: Monitors can be defined as non-urgent so that urgent alerting methods (like SMS) are not wasted on them +* Per-host monitors: Define a monitor which should only run on a particular host and all other hosts will ignore it – so you can share one configuration file between all your hosts +* Groups: Configure some Alerters to only react to some monitors +* Monitor gaps: By default every monitor polls every interval (e.g. 60 seconds). Monitors can be given a gap between polls so that they only poll once a day (for example) +* Alert periods: Alerters can be configured to only alert during certain times and/or on certain days +* Alert catchup: ...and also to alert you to a monitor which failed when they were unable to tell you. (For example, I don’t want to be woken up overnight by an SMS, but if something’s still broken I’d like an SMS at 7am as I’m getting up.) + +Contributing +============ + +* Clone the GitHub repo +* ``poetry install`` + +You can use ``pre-commit`` to ensure your code is up to my exacting standards ;) + +You can run tests with ``make unit-test``. See the Makefile for other useful targets. + +Licence +======= + +SimpleMonitor is released under the BSD Licence. + +Contact +======= + +* Open an issue or start a discussion on `GitHub `_ +* Twitter: `@jamesoff `_ +* Email: james at jamesoff dot net + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..b71d4145 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,78 @@ +Installation +============ + +SimpleMonitor is available via `PyPi `_:: + + pip install simplemonitor + +.. tip:: You may want to install it in a virtualenv, or you can use pipx which + automatically manages virtualenvs for command-line tools. + +TODO: install ring etc? + +Create the configuration files: ``monitor.ini`` and ``monitors.ini``. See +Configuration. + +.. warning:: I know the configuration file names are dumb, sorry. + +Running +------- + +Just run:: + + simplemonitor + +SimpleMonitor does not fork. For best results, run it with a service +management tool such as daemontools, supervisor, or systemd. You can find +some sample configurations for this purpose `on GitHub +`_. + +SimpleMonitor will look for its configuration files in the current working +directory. You can specify a different configuration file using ``-f``. + +You can verify the configuration files syntax with ``-t``. + +By default, SimpleMonitor's output is limited to errors and other issues, and +it emits a ``.`` character every two loops. Use ``-H`` to disable the latter, +and ``-v``, ``-d`` and ``-q`` (or ``-l``) to control the former. + +If you are using something like systemd or multilog which add their own +timestamps to the start of the line, you may want ``--no-timestamps`` to +avoid having unnecessary timestamps added. + +Command Line Options Reference +------------------------------ + +**General options** + + -h, --help show help message and exit + --version show version number and exit + +**Execution options** + + -p PIDFILE, --pidfile PIDFILE + Write PID into this file + -N, --no-network Disable network listening socket (if enabled in config) + -f CONFIG, --config CONFIG + configuration file (this is the main config; you also need monitors.ini (default filename) + -j THREADS, --threads THREADS + number of threads to run for checking monitors (default is number of CPUs detected) + +**Output options** + -v, --verbose Alias for ``--log-level=info`` + -q, --quiet Alias for ``--log-level=critical`` + -d, --debug Alias for ``--log-level=debug`` + -H, --no-heartbeat Omit printing the '.' character when running checks + -l LOGLEVEL, --log-level LOGLEVEL + Log level: critical, error, warn, info, debug + -C, --no-colour, --no-color + Do not colourise log output + --no-timestamps Do not prefix log output with timestamps + +**Testing options** + -t, --test Test config and exit + -1, --one-shot Run the monitors once only, without alerting. Require monitors without "fail" in the name to succeed. Exit zero + or non-zero accordingly. + --loops LOOPS Number of iterations to run before exiting + --dump-known-resources + Print out loaded Monitor, Alerter and Logger types diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..2119f510 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/monitors.rst b/docs/monitors.rst new file mode 100644 index 00000000..3c2c317a --- /dev/null +++ b/docs/monitors.rst @@ -0,0 +1,477 @@ +Monitor Configuration +===================== + +Monitors are defined in (by default) :file:`monitors.ini`. The monitor is named +by its ``[section]`` heading. If you create a ``[defaults]`` section, the +values are used as defaults for all the other monitors. Each monitor's +configuration will override the values from the default. + +.. contents:: + +Common options +-------------- + +These options are common to all monitor types. + +.. confval:: type + + :type: string + :required: true + + the type of the monitor; one of those in the list below. + +.. confval:: runon + + :type: string + :required: false + :default: none + + a hostname on which the monitor should run. If not set, always runs. You + can use this to share one config file among many hosts. (The value which is + compared to is that returned by Python's :code:`socket.gethostname()`.) + +.. confval:: depend + + :type: comma-separated list of string + :required: false + :default: none + + the monitors on which this one depends. This monitor will run after those, unless one of them fails or is skipped, in which case this one will also skip. A skip does not trigger an alerter. + +.. confval:: tolerance + + :type: integer + :required: false + :default: 1 + + the number of times a monitor can fail before it enters the failed state. Handy for things which intermittently fail, such as unreliable links. See also the :ref:`limit-option` on Alerters. + +.. confval:: urgent + + :type: boolean + :required: false + :default: true + + if this monitor is "urgent" or not. Non-urgent monitors do not trigger urgent alerters (e.g. BulkSMS) + +.. confval:: gap + + :type: integer + :required: false + :default: 0 + + the number of seconds this monitor should allow to pass before polling. Use it to make a monitor poll only once an hour (``3600``), for example. Setting this value lower than the ``interval`` will have no effect, and the monitor will run every loop like normal. + + .. hint:: Monitors which are in the failed state will poll every loop, regardless of this setting, in order to detect recovery as quickly as possible + +.. confval:: remote_alert + + :type: boolean + :required: false + :default: false + + set to true to have this monitor's alerting handled by a remote instance instead of the local one. If you're using the remote feature, this is a good candidate to put in the ``[defaults]``. + +.. confval:: recover_command + + :type: string + :required: false + :default: none + + a command to execute once when this monitor enters the failed state. For example, it could attempt to restart a service. + +.. confval:: recovered_command + + :type: string + :required: false + :default: none + + a command to execute once when this monitor returns to the OK state. For example, it could restart a service which was affected by the failure of what this monitor checks. + +.. confval:: notify + + :type: boolean + :required: false + :default: true + + if this monitor should alert at all. + +.. confval:: group + + :type: string + :required: false + :default: ``default`` + + the group the monitor belongs to. Alerters and Loggers will only fire for monitors which appear in their groups. + +.. confval:: failure_doc + + :type: string + :required: false + :default: none + + information to include in alerts on failure (e.g. a URL to a runbook) + + +Monitors +-------- + +.. note:: The ``type`` of the monitor is the first word in its heading. + +apcupsd - APC UPS status +^^^^^^^^^^^^^^^^^^^^^^^^ + +Uses an existing and configured ``apcupsd`` installation to check the UPS status. Any status other than ``ONLINE`` is a failure. + +.. confval:: path + + :type: string + :required: false + :default: none + + the path to the :file:`apcaccess` binary. On Windows, defaults to :file:`C:\\apcupsd\\bin`. On other platforms, looks in ``$PATH``. + +arlo_camera - Arlo camera battery level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Checks Arlo camera battery level is high enough. + +.. confval:: username + + :type: string + :required: true + + Arlo username + +.. confval:: password + + :type: string + :required: true + + Arlo password + +.. confval:: device_name + + :type: string + :required: true + + the device to check (e.g. ``Front Camera``) + +.. confval:: base_station_id + + :type: integer + :required: false + :default: ``0`` + + the number of your base station. Only required if you have more than one. It's an array index, but figuring out which is which is an exercise left to the reader. + +command - run an external command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Run a command, and optionally verify its output. If the command exits non-zero, this monitor fails. + +.. confval:: command + + :type: string + :required: true + + the command to run. + +.. confval:: result_regexp + + :type: string (regular expression) + :required: false + :default: none + + if supplied, the output of the command must match else the monitor fails. + +.. confval:: result_max + + :type: integer + :required: false + + if supplied, the output of the command is evaluated as an integer and if greater than this, the monitor fails. If the output cannot be converted to an integer, the monitor fails. + +compound - combine monitors +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Combine (logical-and) multiple monitors. By default, if any monitor in the list is OK, this monitor is OK. If they all fail, this monitor fails. To change this limit use the ``min_fail`` setting. + +.. warning:: Do not specify the other monitors in this monitor's ``depends`` setting. The dependency handling for compound monitors is a special case and done for you. + +.. confval:: monitors + + :type: comma-separated list of string + :required: true + + the monitors to combine + +.. confval:: min_fail + + :type: integer + :required: false + :default: the number of monitors in the list + + the number of monitors from the list which should be failed for this monitor to fail. The default is that all the monitors must fail. + +diskspace - free disk space +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Checks the free space on the given partition/drive. + +.. confval:: partition + + :type: string + :required: true + + the partition/drive to check. On Windows, give the drive letter (e.g. :file:`C:`). Otherwise, give the mountpoint (e.g. :file:`/usr`). + +.. confval:: limit + + :type: :ref:`bytes` + :required: true + + the minimum allowed amount of free space. + +dns - resolve record +^^^^^^^^^^^^^^^^^^^^ + +Attempts to resolve the DNS record, and optionally checks the result. Requires ``dig`` to be installed and on the PATH. + +.. confval:: record + + :type: string + :required: true + + the DNS name to resolve + +.. confval:: record_type + + :type: string + :required: false + :default: ``A`` + + the type of record to request + +.. confval:: desired_val + + :type: string + :required: false + + if not given, this monitor simply checks the record resolves. + + Give the special value ``NXDOMAIN`` to check the record **does not** resolve. + + If you need to check a multivalue response (e.g. MX records), format them like this (note the leading spaces on the continuation lines): + + .. code-block:: ini + + desired_val=10 a.mx.domain.com + 20 b.mx.domain.com + 30 c.mx.domain.com + +.. confval:: server + + :type: string + :required: false + + the server to send the request to. If not given, uses the system default. + +fail - alawys fails +^^^^^^^^^^^^^^^^^^^ + +This monitor fails 5 times in a row, then succeeds once. Use for testing. See the :ref:`pass - always succeds` monitor for the inverse. + +filestat - file size and age +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Examines a file's size and age. If neither of the age/size values are given, simply checks the file exists. + +.. confval:: filename + + :type: string + :required: true + + the path of the file to monitor. + +.. confval:: maxage + + :type: integer + :required: false + + the maximum allowed age of the file in seconds. If not given, not checked. + +.. confval:: minsize + + :type: :ref:`bytes` + :required: false + + the minimum allowed size of the file in bytes. If not given, not checked. + +hass_sensor - Home Automation Sensors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This monitor checks for the existence of a home automation sensor. + +.. confval:: url + + :type: string + :required: true + + API URL for the monitor + +.. confval:: sensor + + :type: string + :required: true + + the name of the sensor + +.. confval:: token + + :type: string + :required: true + + API token for the sensor + +host - ping a host +^^^^^^^^^^^^^^^^^^ + +Check a host is pingable. + +.. tip:: This monitor relies on executing the ``ping`` command provided by your OS. It has known issues on non-English locales on Windows. You should use the :ref:`ping` monitor instead. The only reason to use this one is that it does not require SimpleMonitor to run as root. + +.. confval:: host + + :type: string + :required: true + + the hostname/IP to ping + +.. confval:: ping_regexp + + :type: regexp + :required: false + :default: automatic + + the regexp which matches a successful ping. You may need to set this to use this monitor in a non-English locale. + +.. confval:: time_regexp + + :type: regexp + :required: false + :default: automatic + + the regexp which matches the ping time in the output. Must set a match group named ``ms``. You may need to set this as above. + +http - fetch and verify a URL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Attempts to fetch a URL and makes sure the HTTP return code is (by default) 200/OK. Can also match the content of the page to a regular expression. + +.. confval:: url + + :type: string + :required: true + + the URL to open + +.. confval:: regexp + + :type: regexp + :required: false + :default: none + + the regexp to look for in the body of the response + +.. confval:: allowed_codes + + :type: comma-separated list of integer + :required: false + :default: `200` + + a list of acceptable HTTP status codes + +.. confval:: verify_hostname + + :type: boolean + :required: false + :default: true + + set to false to disable SSL hostname verification (e.g. with self-signed certificates) + +.. confval:: timeout + + :type: integer + :required: false + :default: ``5`` + + the timeout in seconds for the HTTP request to complete + +.. confval:: headers + + :type: JSON map as string + :required: false + :default: ``{}`` + + JSON map of HTTP header names and values to add to the request + +loadavg - load average +^^^^^^^^^^^^^^^^^^^^^^ + +Check the load average on the host. + +.. confval:: which + + :type: integer + :required: false + :default: ``1`` + + the load average to monitor. ``0`` = 1min, ``1`` = 5min, ``2`` = 15min + +.. confval:: max + + :type: float + :required: false + :default: ``1.00`` + + the maximum acceptable load average + +memory - free memory percent +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Check free memory percentage. + +.. confval:: percent_free + + :type: int + :required: true + + the minimum percent of available (as per psutils’ definition) memory + +null - always passes +^^^^^^^^^^^^^^^^^^^^ + +Monitor which always passes. Use for testing. + +This monitor has no additional parameters. + +ping - ping a host +^^^^^^^^^^^^^^^^^^ + +Pings a host to make sure it’s up. Uses a Python ping module instead of calling out to an external app, but needs to be run as root. + +.. confval:: host + + :type: string + :required: true + + the hostname or IP to ping + +.. confval:: timeout + + :type: int + :required: false + :default: ``5`` + + the timeout for the ping in seconds diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..b49c9962 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx==3.4.2 +sphinx_rtd_theme==0.5.1 diff --git a/setup.cfg b/setup.cfg index d00172d1..67afed15 100644 --- a/setup.cfg +++ b/setup.cfg @@ -11,7 +11,7 @@ per-file-ignores = simplemonitor/__init__.py:F401 [isort] -known_third_party = arrow,freezegun,requests,setuptools,win32event,win32service,win32serviceutil +known_third_party = arrow,freezegun,requests,setuptools,sphinx,sphinx_rtd_theme,win32event,win32service,win32serviceutil known_first_party = Alerters,Loggers,Monitors,envconfig,util,simplemonitor line_length=88 multi_line_output=3