Merge pull request #3188 from maurerle/improve_docs

[docs] update package, features and config mode docs

docs/dev/web/config-mode.rst

@@ -11,18 +11,28 @@ gluon-config-mode-core
 gluon-config-mode-hostname
     Provides a hostname field.
 
-gluon-config-mode-autoupdater
+:doc:`gluon-config-mode-autoupdater <../../features/autoupdater>`
     Informs whether the autoupdater is enabled.
 
-gluon-config-mode-mesh-vpn
-    Allows toggling of mesh-vpn-fastd and setting a bandwidth limit.
+:doc:`gluon-config-mode-mesh-vpn <../../features/vpn>`
+    Allows toggling of installed mesh-vpn technology and setting a bandwidth limit.
 
 gluon-config-mode-geo-location
     Enables the user to set the geographical location of the node.
 
+:doc:`../../package/gluon-config-mode-geo-location-osm`
+    Lets the user click on a map to select the geographical location through a OSM map
+
 gluon-config-mode-contact-info
     Adds a field where the user can provide contact information.
 
+:doc:`../../package/gluon-web-cellular`
+    Adds advanced options to enter WWAN config.
+
+:doc:`../../package/gluon-web-network`
+    Adds option to configure used role on interfaces
+
+Most of the configuration options are described in :ref:`user-site-config_mode`
 
 Writing Config Mode modules
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/features/autoupdater.rst

@@ -31,7 +31,7 @@ as otherwise the generated manifest will be incomplete.
 
 
 Manifest format
-------------------------
+---------------
 
 The manifest starts with a short header, followed by the list of firmwares and signatures.
 The header contains the following information:

docs/features/configmode.rst

@@ -38,3 +38,17 @@ Accessing Config Mode
 Config Mode can be accessed at http://192.168.1.1. The node will offer DHCP
 to clients. Should this fail, you may assign an IP from 192.168.1.0/24 to
 your computer manually.
+
+.. image:: configmode.png
+
+Advanced Config Options
+-----------------------
+
+Depending on the installed packages, the advanced config mode allows to configure packages further.
+
+* :doc:`gluon-web-wifi-config enable <wlan-configuration>` radios used for wifi and mesh as well as outdoor mode
+* :doc:`../package/gluon-web-network` allows to configure the used roles (uplink, mesh, client) on each interface
+* :doc:`../package/gluon-web-admin` allows to enter SSH keys or set a password in the `Remote access` section
+* :doc:`../package/gluon-web-cellular` allows to configure SIM card / WWAN settings on supported cellular devices
+
+The advanced config does also allow to upload a sysupgrade file to update the firmware to a different version.

docs/features/status-page.rst

@@ -0,0 +1,30 @@
+Status-Page
+===========
+
+When the feature ``gluon-status-page`` is enabled, Gluon nodes run a HTTP server with status information on all IP addresses of ``br-client``.
+This makes it possible to check information of the node in realtime.
+
+If the mesh protocol ``gluon-mesh-batman-adv`` is installed too, the package ``gluon-status-page-mesh-batman-adv`` is added too according to the :ref:`user-site-feature-flags`
+
+.. _status-page-example-picture:
+
+Example Picture
+---------------
+
+The left side of the status page contains Overview information.
+In the middle, current monitoring information abut the system, number of clients, radios, amount of traffic and connected mesh-vpn if any are shown.
+The right side of the Status-Page contains information about Neighbours to this node through :doc:`wired-mesh` as well as wireless mesh.
+
+.. image:: status-page.png
+
+Mesh Graphs
+-----------
+
+When wireless mesh is enabled, the mesh interfaces show realtime Graphs about the received signal strength (RSSI) in dBm.
+
+Neighbours
+----------
+
+The list of neighbours at first shows the mac-address of the neighbour it sees.
+The status-page sends a second request to ``http://[ipv6]/cgi-bin/dyn/neighbours-nodeinfo?mesh-vpn`` which triggers the lookup of neighbour information on the node itself.
+Through this, the actual nodenames of the neighbours are shown on the status-page as can be seen in the :ref:`status-page-example-picture`.

docs/features/tls.rst

@@ -0,0 +1,10 @@
+TLS support
+===========
+
+The generic TLS implementation which is currently used by OpenWRT can be installed or added as dependency through the package ``gluon-tls``.
+This removes the need for community packages to depend on a specific TLS implementation (like mbedtls, OpenSSL or WolfSSL).
+
+This package is an alias for the current TLS implementation used.
+To allow for easy usage of communicating through HTTPS from the node, typical Certificate Authorities (CAs) are included through the package ``ca-bundle`` .
+
+* Starting with OpenWRT 23.05, mbedtls is the default TLS layer - this is reflected in Gluon :ref:`v2023.2 <releases-v2023.2-minor-changes>`. HTTPS is used by default to communicate with OpenWRT opkg servers.

docs/features/wlan-configuration.rst

@@ -6,6 +6,13 @@ may include one or both of the two networks "client" (AP mode) and "mesh" (802.1
 mode), which can be used simultaneously. See :doc:`../user/site` for details on the
 configuration.
 
+Outdoor mode
+------------
+
+Configuring the node for outdoor use tunes the 5 GHz radio to a frequency and transmission power that conforms with the local regulatory requirements. 
+It also enables dynamic frequency selection (DFS; radar detection).
+At the same time, mesh functionality is disabled as it requires neighbouring nodes to stay on the same channel permanently.
+
 Upgrade behaviour
 -----------------
 

docs/index.rst

@@ -25,12 +25,14 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
   features/wlan-configuration
   features/private-wlan
   features/wired-mesh
+  features/tls
   features/dns-cache
   features/monitoring
   features/multidomain
   features/authorized-keys
   features/roles
   features/vpn
+  features/status-page
 
 .. toctree::
   :caption: Developer Documentation
@@ -62,6 +64,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
 
   package/gluon-client-bridge
   package/gluon-config-mode-domain-select
+  package/gluon-config-mode-geo-location-osm
   package/gluon-ebtables-filter-multicast
   package/gluon-ebtables-filter-ra-dhcp
   package/gluon-ebtables-limit-arp
@@ -73,6 +76,8 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
   package/gluon-radv-filterd
   package/gluon-scheduled-domain-switch
   package/gluon-web-admin
+  package/gluon-web-cellular
+  package/gluon-web-network
   package/gluon-web-logging
 
 .. toctree::

docs/package/gluon-config-mode-geo-location-osm.rst

@@ -0,0 +1,11 @@
+.. _package-gluon-config-mode-geo-location-osm:
+
+gluon-config-mode-geo-location-osm
+==================================
+
+When package *gluon-config-mode-geo-location-osm* is enabled, the configuration wizard will
+try to load an OSM-based map to allow the user to specify the node location.
+Loading the map requires a working internet connection, for example via WLAN
+(while connected to the Gluon node via Ethernet).
+
+.. image:: gluon-config-mode-geo-location-osm.png

docs/package/gluon-web-cellular.rst

@@ -0,0 +1,14 @@
+.. _package-gluon-web-cellular:
+
+gluon-web-cellular
+==================
+
+This package allows to configure WWAN for capable cellular devices.
+
+This works by creating an abstraction layer into Gluon which takes common options (SIM PIN / APN) and translates it to modem-specific settings based on the specific device using. 
+Doing so limits the use-case onto specific models (no LTE sticks possible) but provides a common interface.
+
+The WWAN is assigned the WAN firewall zone and wired WAN can still be used, however without prioritization.
+The traffic path is not configured to prefer one uplink source or the other.
+
+.. image:: gluon-web-cellular.png

docs/package/gluon-web-network.rst

@@ -0,0 +1,19 @@
+gluon-web-network
+=================
+
+The package *gluon-web-network* is part of :ref:`Feature Flag <user-site-feature-flags>` web-advanced.
+It allows to configure the network interfaces roles of the gluon node in config mode through checkboxes.
+
+It is a user-friendly way to configure what otherwise would need the :ref:`wired-mesh-commandline`.
+
+.. image:: gluon-web-network.png
+
+configuration options
+---------------------
+
+The following roles can be assigned to the interfaces:
+* `Uplink` - interface is used for WAN connection, which is used for the VPN if `mesh-vpn` checkbox is enabled in basic config mode
+* `Mesh` - interface is used for :doc:`../features/wired-mesh`. Using this on the WAN interface is also known as "Mesh-on-WAN"
+* `Client` - interface is used as client network - connected devices to this interface should get a working internet configuration through DHCP
+
+The roles `Uplink`/`Mesh` and `Client` are mutually exclusive.

docs/releases/v2023.2.rst

@@ -288,6 +288,7 @@ Major changes
 This release is based on the newest OpenWrt 23.05 release branch.
 It ships with Linux kernel 5.15.y, wireless-backports 6.1.24 and batman-adv 2023.1.
 
+.. _releases-v2023.2-minor-changes:
 
 Minor changes
 -------------

docs/user/x86.rst

@@ -9,9 +9,9 @@ Targets
 
 The following targets for x86 images exist:
 
-`x86-generic`
-    Generic x86 support with many different ethernet drivers; should run on
-    most x86 systems.
+`x86-64`
+    Generic x86 64-bit support with many different ethernet drivers; should run on
+    most x86 systems with 64-bit support.
 
     There are three images:
 
@@ -20,10 +20,15 @@ The following targets for x86 images exist:
     * `vmware` (VMDK image)
 
     These images differ in the image file format, the content is the same. Therefore
-    a single `x86-generic` sysupgrade image is provided, only.
+    a single `x86-64` sysupgrade image is provided, only.
+
+`x86-generic`
+    32-bit version of `x86-64` for hardware not supporting 64-bit images.
+    Also comes with `virtualbox` and `vmware` factory installs.
 
 `x86-geode`
     x86 image for Geode CPUs.
 
-`x86-64`
-    64bit version of `x86-generic`.
+`x86-legacy`
+    x86 image for very old PC hardware like i586.
+