From 8f5372c656ee68dd4c0a9918abd090e559968ecb Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Mon, 8 Aug 2022 13:08:23 +0200 Subject: [PATCH] [docs] Improved README --- README.rst | 126 +++++++++++++++++++++++++++++------------------------ 1 file changed, 69 insertions(+), 57 deletions(-) diff --git a/README.rst b/README.rst index f0d994a80..12d9a26b9 100644 --- a/README.rst +++ b/README.rst @@ -858,7 +858,7 @@ Iperf .. figure:: https://github.com/openwisp/openwisp-monitoring/raw/docs/docs/1.1/datagram-loss.png :align: center -**Note:** Iperf charts uses ``connect_points=True`` in +**Note:** Iperf charts uses ``connect_points=True`` in `default chart configuration <#openwisp_monitoring_charts>`_ that joins it's individual chart data points. Dashboard Monitoring Charts @@ -1010,54 +1010,58 @@ if there's anything that is not working as intended. Iperf ~~~~~ -This check provides network performance measurements such as maximum achievable bandwidth, -jitter, datagram loss etc of the device using `iperf3 utility `_. +This check provides network performance measurements such as maximum achievable bandwidth, +jitter, datagram loss etc of the device using `iperf3 utility `_. This check is **disabled by default**. You can enable auto creation of this check by setting the `OPENWISP_MONITORING_AUTO_IPERF <#OPENWISP_MONITORING_AUTO_IPERF>`_ to ``True``. It also supports tuning of various parameters. -You can also change the parameters used for iperf checks (e.g. timing, port, username, -password, rsa_publc_key etc) using the `OPENWISP_MONITORING_IPERF_CHECK_CONFIG +You can also change the parameters used for iperf checks (e.g. timing, port, username, +password, rsa_publc_key etc) using the `OPENWISP_MONITORING_IPERF_CHECK_CONFIG <#OPENWISP_MONITORING_IPERF_CHECK_CONFIG>`_ setting. -Usage Instructions ------------------- - -How to configure iperf check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Iperf Check Usage Instructions +------------------------------ -1. Register your device to OpenWISP -################################### +1. Make sure iperf is installed on the device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Register your device to OpenWISP and make sure `iperf3 openwrt package -`_ is installed on the device if not run : +Register your device to OpenWISP and make sure the `iperf3 openwrt package +`_ is installed on the device, +eg: .. code-block:: shell - opkg install iperf3 + opkg install iperf3 # if using without authentication + opkg install iperf3-ssl # if using with authentication (read below for more info) -2. Enable secure SSH access from OpenWISP to your devices -######################################################### +2. Ensure SSH access from OpenWISP is enabled on your devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Follow the steps in `"How to configure push updates" section of the openwisp-controller documentation -`_ to allow SSH access to you device from OpenWISP. +Follow the steps in `"How to configure push updates" section of the +OpenWISP documentation +`_ +to allow SSH access to you device from OpenWISP. -**Note:** Make sure device connection is enabled & working with right update strategy i.e. ``OpenWRT SSH``. +**Note:** Make sure device connection is enabled +& working with right update strategy i.e. ``OpenWRT SSH``. .. image:: https://github.com/openwisp/openwisp-monitoring/raw/docs/docs/1.1/enable-openwrt-ssh.png :alt: Enable ssh access from openwisp to device :align: center - -3. Configure Iperf settings -########################### -Configure iperf servers in `openwisp settings -`_ , -The host can be specified by hostname, IPv4 literal, or IPv6 literal. +3. Set up and configure Iperf server settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After having deployed your Iperf servers, you need to +configure the iperf settings on the django side of OpenWISP, +see the `test project settings for reference +`_. -For example. +The host can be specified by hostname, IPv4 literal, or IPv6 literal. +Example: .. code-block:: python @@ -1075,8 +1079,7 @@ For example. } } -Add celery beat configuration for iperf check in `openwisp settings -`_ +The celery-beat configuration for the iperf check needs to be added too: .. code-block:: python @@ -1087,7 +1090,6 @@ Add celery beat configuration for iperf check in `openwisp settings CELERY_TIMEZONE = TIME_ZONE CELERY_BEAT_SCHEDULE = { # Other celery beat configurations - # Celery beat configuration for iperf check 'run_iperf_checks': { 'task': 'openwisp_monitoring.check.tasks.run_checks', @@ -1100,30 +1102,34 @@ Add celery beat configuration for iperf check in `openwisp settings } } -**Note:** We recommended to configure this check for night or -during non peak traffic times to not interfere with standard traffic. +Once the changes are saved, you will need to restart all the processes. + +**Note:** We recommended to configure this check to run in non peak +traffic times to not interfere with standard traffic. 4. Run the check -################ +~~~~~~~~~~~~~~~~ + +This should happen automatically if you have celery-beat correctly +configured and running in the background. +For testing purposes, you can run this check manually using the +`run_checks <#run_checks>`_ command. -This should happen automatically if you have celery running in the background. For testing, you can -run this check manually using the `run_checks <#run_checks>`_ command. After that, you should see the -iperf network measurements charts. +After that, you should see the iperf network measurements charts. .. image:: https://github.com/openwisp/openwisp-monitoring/raw/docs/docs/1.1/iperf-charts.png :alt: Iperf network measurement charts - Iperf authentication ~~~~~~~~~~~~~~~~~~~~ -By default iperf check runs without any kind of **authentication**, -in this section we will explain how to configure **RSA authentication** -between the **client** and the **server** to restrict connections +By default iperf check runs without any kind of **authentication**, +in this section we will explain how to configure **RSA authentication** +between the **client** and the **server** to restrict connections to authenticated clients. -At Iperf server -############### +Server side +########### 1. Generate RSA keypair ^^^^^^^^^^^^^^^^^^^^^^^ @@ -1134,11 +1140,13 @@ At Iperf server openssl rsa -in private.pem -outform PEM -pubout -out public_key.pem openssl rsa -in private.pem -out private_key.pem -outform PEM -After running the commands mentioned above, the public key will be stored in -``public_key.pem`` which will be used in **rsa_public_key** parameter -in `OPENWISP_MONITORING_IPERF_CHECK_CONFIG <#OPENWISP_MONITORING_IPERF_CHECK_CONFIG>`_ -and the private key will be contained in the file ``private_key.pem`` -which will be used with **--rsa-private-key-path** command option at iperf server. +After running the commands mentioned above, the public key will be stored in +``public_key.pem`` which will be used in **rsa_public_key** parameter +in `OPENWISP_MONITORING_IPERF_CHECK_CONFIG +<#OPENWISP_MONITORING_IPERF_CHECK_CONFIG>`_ +and the private key will be contained in the file ``private_key.pem`` +which will be used with **--rsa-private-key-path** command option when +starting the iperf server. 2. Create user credentials ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1164,14 +1172,17 @@ Add the above hash with username in ``credentials.csv`` iperf3 -s --rsa-private-key-path ./private_key.pem --authorized-users-path ./credentials.csv -At client (openwrt device) -########################## +Client side (OpenWrt device) +############################ 1. Install iperf3-ssl ^^^^^^^^^^^^^^^^^^^^^ -Install `iperf3-ssl openwrt package `_ instead of normal -`iperf3 openwrt package `_ which comes without any authentication. +Install the `iperf3-ssl openwrt package +`_ +instead of the normal +`iperf3 openwrt package `_ +because the latter comes without support for authentication. You may also check your installed **iperf3 openwrt package** features: @@ -1180,15 +1191,16 @@ You may also check your installed **iperf3 openwrt package** features: root@vm-openwrt:~ iperf3 -v iperf 3.7 (cJSON 1.5.2) Linux vm-openwrt 4.14.171 #0 SMP Thu Feb 27 21:05:12 2020 x86_64 - Optional features available: CPU affinity setting, IPv6 flow label, TCP congestion algorithm setting, + Optional features available: CPU affinity setting, IPv6 flow label, TCP congestion algorithm setting, sendfile / zerocopy, socket pacing, authentication # contains 'authentication' 2. Configure iperf check auth parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Now, add the following iperf authentication parameters -to `OPENWISP_MONITORING_IPERF_CHECK_CONFIG <#OPENWISP_MONITORING_IPERF_CHECK_CONFIG>`_ -in `openwisp settings `_ +Now, add the following iperf authentication parameters +to `OPENWISP_MONITORING_IPERF_CHECK_CONFIG +<#OPENWISP_MONITORING_IPERF_CHECK_CONFIG>`_ +in the settings: .. code-block:: python @@ -1350,8 +1362,8 @@ For example, if you want to change only the **port number** of | **default**: | ``True`` | +--------------+-------------------------------+ -This setting allows you to set whether -`iperf check RSA public key <#configure-iperf-check-for-authentication>`_ +This setting allows you to set whether +`iperf check RSA public key <#configure-iperf-check-for-authentication>`_ will be deleted after successful completion of the check or not. ``OPENWISP_MONITORING_AUTO_CHARTS``