Monitoring ========== .. image:: https://github.com/openwisp/openwisp-monitoring/raw/docs/docs/monitoring-demo.gif :target: https://github.com/openwisp/openwisp-monitoring/tree/docs/docs/monitoring-demo.gif :alt: Feature Highlights `OpenWISP Monitoring `_ has been introduced in OpenWISP 22.05 and focuses on allowing users to know the status of their devices at any given time. .. contents:: **Table of Contents**: :backlinks: none :depth: 3 Deploy instructions ------------------- The monitoring module is enabled by default in the `OpenWISP 22.05 ansible role `_. It's also available in `docker-openwisp `_ although its usage is not recommended for production usage yet, unless the reader is willing to invest effort in adapting the docker images and configurations to overcome any roadblocks encountered. Quickstart Guide ---------------- This guide assumes you have the `OpenWISP Monitoring `_ module enabled in your OpenWISP server application and you have already followed the steps to :doc:`install openwisp-config on your OpenWRT devices <./configure-device>`. Install monitoring packages on the device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `Install the openwrt-openwisp-monitoring packages `_ on your device. These packages collect and send the monitoring data from the device to OpenWISP Monitoring and are required to collect `metrics `_ like interface traffic, WiFi clients, CPU load, memory usage, etc. .. _openwisp_reach_devices: Make sure OpenWISP can reach your devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to perform `active checks `_ and other actions like `triggering the push of configuration changes `_, `executing shell commands `_ or `performing firmware upgrades `_, **the OpenWISP server needs to be able to reach the network devices**. There are mainly two deployment scenarios for OpenWISP: 1. the OpenWISP server is deployed on the public internet and the devices are geographically distributed across different locations: **in this case a management tunnel is needed** 2. the OpenWISP server is deployed on a computer/server which is located in the same Layer 2 network (that is, in the same LAN) where the devices are located. **in this case a management tunnel is NOT needed** 1. Public internet deployment ############################# This is the most common scenario: - the OpenWISP server is deployed to the public internet, hence the server has a public IPv4 (and IPv6) address and usually a valid SSL certificate provided by Mozilla Letsencrypt or another SSL provider - the network devices are geographically distributed across different locations (different cities, different regions, different countries) In this scenario, the OpenWISP application will not be able to reach the devices **unless a management tunnel** is used, for that reason having a management VPN like OpenVPN, Wireguard, ZeroTier or any other tunneling solution is paramount, not only to allow OpenWISP to work properly, but also to be able to perform debugging and troubleshooting when needed. In this scenario, the following requirements are needed: - a VPN server must be installed in a way that the OpenWISP server can reach the VPN peers, for more information on how to do this via OpenWISP please refer to the following sections: - `OpenVPN tunnel automation `_ - `Wireguard tunnel automation `_ If you prefer to use other tunneling solutions (L2TP, Softether, etc.) and know how to configure those solutions on your own, that's totally fine as well. If the OpenWISP server is connected to a network infrastructure which allows it to reach the devices via pre-existing tunneling or Intranet solutions (eg: MPLS, SD-WAN), then setting up a VPN server is not needed, as long as there's a dedicated interface on OpenWrt which gets an IP address assigned to it and which is reachable from the OpenWISP server. - The devices must be configured to join the management tunnel automatically, either via a pre-existing configuration in the firmware or via an `OpenWISP Template `_. - The `openwisp-config `_ agent on the devices must be configured to specify the ``management_interface`` option, the agent will communicate the IP of the management interface to the OpenWISP Server and OpenWISP will use the management IP for reaching the device. For example, if the *management interface* is named ``tun0``, the openwisp-config configuration should look like the following example: .. code-block:: text # In /etc/config/openwisp on the device config controller 'http' # ... other configuration directives ... option management_interface 'tun0' 2. LAN deployment ################# When the OpenWISP server and the network devices are deployed in the same L2 network (eg: an office LAN) and the OpenWISP server is reachable on the LAN address, OpenWISP can then use the **Last IP** field of the devices to reach them. In this scenario it's necessary to set the `"OPENWISP_MONITORING_MANAGEMENT_IP_ONLY" `_ setting to ``False``. Find out more about OpenWISP Monitoring --------------------------------------- For more information about the features offered by OpenWISP Monitoring and the related OpenWrt packages we refer to the following sections of their respective READMEs. OpenWISP Monitoring Python/Django module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - `List of the available features `_ - `Passive vs Active Metric Collection `_ - `Device Health Status `_ - `Default Metrics `_ - `Available Checks `_ - `Rest API `_ - `Django Settings `_ OpenWISP Monitoring OpenWrt packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - `Configuration options `_ - `Collecting vs Sending `_ - `Compiling openwisp-monitoring `_ - `Debugging `_