[docs] Restructured Documentation

Restructured the documentation in a way that allows it to
be included in the Unified Documentation of OpenWISP.

For more information see openwisp/openwisp-docs#107.

---------

Co-authored-by: Federico Capoano <[email protected]>

.github/workflows/ci.yml

@@ -60,7 +60,7 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
-      - name: Cache OpenWRT dependencies
+      - name: Cache OpenWrt dependencies
         id: cache
         uses: actions/cache@v2
         env:

docs/developer/installation.rst

@@ -0,0 +1,100 @@
+Developer Documentation
+=======================
+
+.. include:: ../partials/developer-docs.rst
+
+.. contents:: **Table of Contents**:
+    :depth: 2
+    :local:
+
+.. _compiling_openwisp_config:
+
+Compiling openwisp-config
+-------------------------
+
+The following procedure illustrates how to compile *openwisp-config* and
+its dependencies:
+
+.. code-block:: shell
+
+    git clone https://github.com/openwrt/openwrt.git openwrt
+    cd openwrt
+    git checkout <openwrt-branch>
+
+    # configure feeds
+    echo "src-git openwisp https://github.com/openwisp/openwisp-config.git" > feeds.conf
+    cat feeds.conf.default >> feeds.conf
+    ./scripts/feeds update -a
+    ./scripts/feeds install -a
+    # any arch/target is fine because the package is architecture indipendent
+    arch="ar71xx"
+    echo "CONFIG_TARGET_$arch=y" > .config;
+    echo "CONFIG_PACKAGE_openwisp-config=y" >> .config
+    make defconfig
+    make tools/install
+    make toolchain/install
+    make package/openwisp-config/compile
+
+Alternatively, you can configure your build interactively with ``make
+menuconfig``, in this case you will need to select *openwisp-config* by
+going to ``Administration > openwisp``:
+
+.. code-block:: shell
+
+    git clone https://github.com/openwrt/openwrt.git openwrt
+    cd openwrt
+    git checkout <openwrt-branch>
+
+    # configure feeds
+    echo "src-git openwisp https://github.com/openwisp/openwisp-config.git" > feeds.conf
+    cat feeds.conf.default >> feeds.conf
+    ./scripts/feeds update -a
+    ./scripts/feeds install -a
+    make menuconfig
+    # go to Administration > openwisp and select the variant you need interactively
+    make -j1 V=s
+
+Quality Assurance Checks
+------------------------
+
+We use `LuaFormatter <https://luarocks.org/modules/tammela/luaformatter>`_
+and `shfmt <https://github.com/mvdan/sh#shfmt>`_ to format lua files and
+shell scripts respectively.
+
+First of all, you will need install the lua packages mentioned above, then
+you can format all files with:
+
+.. code-block::
+
+    ./qa-format
+
+To run quality assurance checks you can use the ``run-qa-checks`` script:
+
+.. code-block::
+
+    # install openwisp-utils QA tools first
+    pip install openwisp-utils[qa]
+
+    # run QA checks before committing code
+    ./run-qa-checks
+
+Run tests
+---------
+
+To run the unit tests, you must install the required dependencies first;
+to do this, you can take a look at the `install-dev.sh
+<https://github.com/openwisp/openwisp-config/blob/master/install-dev.sh>`_
+script.
+
+You can run all the unit tests by launching the dedicated script:
+
+.. code-block:: shell
+
+    ./runtests
+
+Alternatively, you can run specifc tests, eg:
+
+.. code-block:: shell
+
+    cd openwisp-config/tests/
+    lua test_utils.lua -v

docs/index.rst

@@ -0,0 +1,50 @@
+OpenWISP Config Agent
+=====================
+
+.. seealso::
+
+    **Source code**: `github.com/openwisp/openwisp-config
+    <https://github.com/openwisp/openwisp-config>`_.
+
+OpenWISP Config is an `OpenWrt <https://openwrt.org/>`_ configuration
+agent that automates network management tasks. It interfaces with the
+OpenWISP Controller to streamline configuration deployment.
+
+For a comprehensive overview of features, please refer to the
+:doc:`user/intro` page.
+
+The following diagram illustrates the role of the OpenWrt Config Agent in
+the OpenWISP architecture.
+
+.. figure:: images/architecture-v2-openwrt-config-agent.png
+    :target: ../_images/architecture-v2-openwrt-config-agent.png
+    :align: center
+    :alt: OpenWISP Architecture: OpenWISP Config Agent for OpenWrt
+
+    **OpenWISP Architecture: highlighted OpenWISP Config Agent for
+    OpenWrt**
+
+.. important::
+
+    For an enhanced viewing experience, open the image above in a new
+    browser tab.
+
+    Refer to :doc:`/general/architecture` for more information.
+
+.. toctree::
+    :caption: OpenWrt Config Agent Usage Docs
+    :maxdepth: 1
+
+    ./user/intro.rst
+    ./user/quickstart.rst
+    ./user/settings.rst
+    ./user/automatic-registration.rst
+    ./user/hotplug-events.rst
+    ./user/compiling.rst
+    ./user/debugging.rst
+
+.. toctree::
+    :caption: OpenWrt Config Agent Developer Docs
+    :maxdepth: 2
+
+    developer/installation.rst

docs/partials/developer-docs.rst

@@ -0,0 +1,12 @@
+.. note::
+
+    This documentation page is aimed at developers who want to customize,
+    change or extend the code of OpenWISP Config in order to modify its
+    behavior (eg: for personal or commercial purposes or to fix a bug,
+    implement a new feature or contribute to the project in general).
+
+    If you aren't a developer and you are looking for information on how
+    to use OpenWISP, please refer to:
+
+    - :doc:`General OpenWISP Quickstart </user/quickstart>`
+    - :doc:`OpenWISP Config User Docs </openwrt-config-agent/index>`

docs/user/automatic-registration.rst

@@ -0,0 +1,42 @@
+Automatic registration
+======================
+
+When the agent starts, if both ``uuid`` and ``key`` are not defined, it
+will consider the router to be unregistered and it will attempt to perform
+an automatic registration.
+
+The automatic registration is performed only if ``shared_secret`` is
+correctly set.
+
+The device will choose as name one of its mac addresses, unless its
+hostname is not ``OpenWrt``, in the latter case it will simply register
+itself with the current hostname.
+
+When the registration is completed, the agent will automatically set
+``uuid`` and ``key`` in ``/etc/config/openwisp``.
+
+To enable this feature by default on your firmware images, follow the
+procedure described in :doc:`compiling`.
+
+.. _config_consistent_key_generation:
+
+Consistent Key Generation
+-------------------------
+
+When using `Automatic registration`_, this feature allows devices to keep
+the same configuration even if reset or reflashed.
+
+The ``key`` is generated consistently with an operation like
+``md5sum(mac_address + shared_secret)``; this allows the controller
+application to recognize that an existing device is registering itself
+again.
+
+The ``mac_interface`` configuration key specifies which interface is used
+to calculate the mac address, this setting defaults to ``eth0``. If no
+``eth0`` interface exists, the first non-loopback, non-bridge and non-tap
+interface is used. You won't need to change this setting often, but if you
+do, ensure you choose a physical interface which has constant mac address.
+
+The "Consistent key generation" feature is enabled by default, but must be
+:ref:`enabled also in the controller application
+<openwisp_controller_consistent_registration>` in order to work.

docs/user/compiling.rst

@@ -0,0 +1,61 @@
+Compiling a Custom OpenWrt Image
+================================
+
+If you are managing many devices and customizing your ``openwisp-config``
+configuration by hand on each new device, you should switch to using a
+custom OpenWrt firmware image that includes ``openwisp-config`` and its
+precompiled configuration file, this strategy has a few important
+benefits:
+
+- you can save yourself the effort of installing and configuring
+  ``openwisp-config`` on each device
+- you can enable :doc:`automatic-registration` by setting
+  ``shared_secret``, hence saving extra time and effort to register each
+  device on the controller app
+- if you happen to reset the firmware to initial settings, these
+  precompiled settings will be restored as well
+
+The following procedure illustrates how to compile a custom `OpenWrt
+<https://openwrt.org/>`_ image with a precompiled minimal
+``/etc/config/openwisp`` configuration file:
+
+.. code-block:: shell
+
+    git clone https://github.com/openwrt/openwrt.git openwrt
+    cd openwrt
+    git checkout <openwrt-branch>
+
+    # include precompiled file
+    mkdir -p files/etc/config
+    cat <<EOF > files/etc/config/openwisp
+    config controller 'http'
+        # change the values of the following 2 options
+        option url 'https://demo.openwisp.io'
+        option shared_secret 'nzXTd7qpXKPNdrWZDsYoMxbGpOrEVjeD'
+    EOF
+
+    # configure feeds
+    echo "src-git openwisp https://github.com/openwisp/openwisp-config.git" > feeds.conf
+    cat feeds.conf.default >> feeds.conf
+    ./scripts/feeds update -a
+    ./scripts/feeds install -a
+    # replace with your desired arch target
+    arch="ar71xx"
+    echo "CONFIG_TARGET_$arch=y" > .config
+    echo "CONFIG_PACKAGE_openwisp-config=y" >> .config
+    make defconfig
+    # compile with verbose output
+    make -j1 V=s
+
+Automate Compilation for Different Organizations
+------------------------------------------------
+
+If you are working with OpenWISP, there are chances you may be compiling
+several images for different organizations (clients or non-profit
+communities) and use cases (full featured, mesh, 4G, etc).
+
+Doing this by hand without tracking your changes can lead you into a very
+disorganized and messy situation.
+
+To alleviate this pain you can use `ansible-openwisp2-imagegenerator
+<https://github.com/openwisp/ansible-openwisp2-imagegenerator>`_.

docs/user/debugging.rst

@@ -0,0 +1,33 @@
+Debugging
+=========
+
+Debugging *openwisp-config* can be easily done by using the ``logread``
+command:
+
+.. code-block:: shell
+
+    logread
+
+Use grep to filter out any other log message:
+
+.. code-block:: shell
+
+    logread | grep openwisp
+
+If you are in doubt openwisp-config is running at all, you can check with:
+
+.. code-block:: shell
+
+    ps | grep openwisp
+
+You should see something like:
+
+.. code-block:: text
+
+    3800 root      1200 S    {openwisp-config} /bin/sh /usr/sbin/openwisp-config --url https://demo.openwisp.io --verify-ssl 1 --consistent-key 1 ...
+
+You can inspect the version of openwisp-config currently installed with:
+
+.. code-block:: shell
+
+    openwisp-config --version

docs/user/hotplug-events.rst

@@ -0,0 +1,39 @@
+Hotplug Events
+==============
+
+The agent sends the following `Hotplug events
+<https://openwrt.org/docs/guide-user/base-system/hotplug>`_:
+
+- After the registration is successfully completed: ``post-registration``
+- After the registration failed: ``registration-failed``
+- When the agent first starts after the bootup of the device: ``bootup``
+- After any subsequent restart: ``restart``
+- After the configuration has been successfully applied:
+  ``config-applied``
+- After the previous configuration has been restored: ``config-restored``
+- Before services are reloaded: ``pre-reload``
+- After services have been reloaded: ``post-reload``
+- After the agent has finished its check cycle, before going to sleep:
+  ``end-of-cycle``
+
+If a hotplug event is sent by *openwisp-config* then all scripts existing
+in ``/etc/hotplug.d/openwisp/`` will be executed. In scripts the type of
+event is visible in the variable ``$ACTION``. For example, a script to log
+the hotplug events, ``/etc/hotplug.d/openwisp/01_log_events``, could look
+like this:
+
+.. code-block:: shell
+
+    #!/bin/sh
+
+    logger "openwisp-config sent a hotplug event. Action: $ACTION"
+
+It will create log entries like this:
+
+.. code-block:: text
+
+    Wed Jun 22 06:15:17 2022 user.notice root: openwisp-config sent a hotplug event. Action: registration-failed
+
+For more information on using these events refer to the `Hotplug Events
+OpenWrt Documentation
+<https://openwrt.org/docs/guide-user/base-system/hotplug>`_.

docs/user/intro.rst

@@ -0,0 +1,14 @@
+OpenWISP Config: Features
+=========================
+
+OpenWISP Config agent provides the following features:
+
+- Fetches the latest configuration from the OpenWISP Controller, ensuring
+  devices stay up-to-date.
+- :ref:`Combines centrally managed settings with local configurations
+  <config_merge_configuration>`, preserving local overrides.
+- Performs :ref:`rollback of previous configuration
+  <config_configuration_test>` when the new configuration fails to apply.
+- Simplifies onboarding by :doc:`automatically registering devices
+  <automatic-registration>` with the controller using a shared secret.
+- Supports :doc:`OpenWrt hotplug events <hotplug-events>`.