Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] update package, features and config mode docs #3188

Merged
merged 11 commits into from
Aug 7, 2024
16 changes: 13 additions & 3 deletions docs/dev/web/config-mode.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
2 changes: 1 addition & 1 deletion docs/features/autoupdater.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Binary file added docs/features/configmode.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 14 additions & 0 deletions docs/features/configmode.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Binary file added docs/features/status-page.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 30 additions & 0 deletions docs/features/status-page.rst
Original file line number Diff line number Diff line change
@@ -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`.
10 changes: 10 additions & 0 deletions docs/features/tls.rst
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions docs/features/wlan-configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
-----------------

Expand Down
5 changes: 5 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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::
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
11 changes: 11 additions & 0 deletions docs/package/gluon-config-mode-geo-location-osm.rst
Original file line number Diff line number Diff line change
@@ -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
Binary file added docs/package/gluon-web-cellular.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 14 additions & 0 deletions docs/package/gluon-web-cellular.rst
Original file line number Diff line number Diff line change
@@ -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
Binary file added docs/package/gluon-web-network.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
19 changes: 19 additions & 0 deletions docs/package/gluon-web-network.rst
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions docs/releases/v2023.2.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------
Expand Down
17 changes: 11 additions & 6 deletions docs/user/x86.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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.