Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision

Target

Select target project
  • firmware/gluon
  • 0x4A6F/gluon
  • patrick/gluon
3 results
Select Git revision
Show changes
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 674 additions and 357 deletions
docs/features/autoupdater.rst
View file @ a6566bab
......@@ -7,8 +7,11 @@ Building Images
---------------
By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
during development), but it can be enabled by setting the variable GLUON_BRANCH when building
to override the default branch set in the site configuration.
during development), but it can be enabled by setting the variable ``GLUON_AUTOUPDATER_ENABLED`` to ``1`` when building.
It is also possible to override the default branch during build using the variable ``GLUON_AUTOUPDATER_BRANCH``.
If a default branch is set neither in *site.conf* nor via ``GLUON_AUTOUPDATER_BRANCH``, the default branch is
implementation-defined. Currently, the branch with the first name in alphabetical order is chosen.
A manifest file for the updater can be generated with `make manifest`. A signing script (using
``ecdsautils``) can be found in the `contrib` directory. When creating the manifest, the
......@@ -27,20 +30,42 @@ in ``site.mk``, care must be taken to pass the same ``GLUON_RELEASE`` to ``make
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:
.. code-block:: sh
BRANCH=stable
DATE=2020-10-07 00:00:00+02:00
PRIORITY=7
- ``BRANCH`` is the autoupdater branch name that needs to match the nodes configuration.
- ``DATE`` specifies when the time period for the update begins. Nodes will do their regular update during a random minute
between 4:00 and 4:59 am. Nodes might not always have a reliable NTP synchronization, which is why a fallback mechanism
exists, that checks for an update, and will execute if ``DATE`` is at least 24h in the past.
- ``PRIORITY`` can be configured as ``GLUON_PRIORITY`` when generating the manifest or in ``site.mk``, and defines
the number of days over which the update should be stretched out after ``DATE``. Nodes will calculate a probability
based on the time left to determine when to update.
Automated nightly builds
------------------------
A fully automated nightly build could use the following commands:
::
.. code-block:: sh
git pull
(git -C site pull)
# git -C site pull
make update
make clean GLUON_TARGET=ar71xx-generic
make clean GLUON_TARGET=ath79-generic
NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ar71xx-generic GLUON_BRANCH=experimental GLUON_RELEASE=$GLUON_RELEASE
make manifest GLUON_BRANCH=experimental GLUON_RELEASE=$GLUON_RELEASE
make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ath79-generic GLUON_RELEASE=$GLUON_RELEASE \
GLUON_AUTOUPDATER_BRANCH=experimental GLUON_AUTOUPDATER_ENABLED=1
make manifest GLUON_RELEASE=$GLUON_RELEASE GLUON_AUTOUPDATER_BRANCH=experimental
contrib/sign.sh $SECRETKEY output/images/sysupgrade/experimental.manifest
rm -rf /where/to/put/this/experimental
......@@ -74,16 +99,16 @@ These commands can be used on a node:
::
# Update with some probability
autoupdater
# Update with some probability
autoupdater
::
# Force update check, even when the updater is disabled
autoupdater -f
# Force update check, even when the updater is disabled
autoupdater -f
::
# If fallback is true the updater will perform an update only if the timespan
# PRIORITY days (as defined in the manifest) and another 24h have passed
autoupdater --fallback
# If fallback is true the updater will perform an update only if the timespan
# PRIORITY days (as defined in the manifest) and another 24h have passed
autoupdater --fallback
docs/features/configmode.png 0 → 100644
View file @ a6566bab
docs/features/configmode.png

112 KiB

docs/features/configmode.rst
View file @ a6566bab
......@@ -18,6 +18,9 @@ Config Mode by pressing and holding the RESET/WPS/DECT button for about three
seconds. The device should reboot (all LEDs will turn off briefly) and
Config Mode will be available.
If you have access to the console of the node, there is the
``gluon-enter-setup-mode`` command, which reboots a node into Config Mode.
Port Configuration
------------------
......@@ -35,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/dns-cache.rst 0 → 100644
View file @ a6566bab
.. _dns-caching:
DNS caching
===========
User experience may be greatly improved when dns is accelerated. Also, it
seems like a good idea to keep the number of packages being exchanged
between node and gateway as small as possible. In order to do this, a
DNS cache may be used on a node. The dnsmasq instance listening on port
53 on the node will be reconfigured to answer requests, use a list of
upstream servers and a specific cache size if the options listed below are
added to site.conf. Upstream servers are the DNS servers which are normally
used by the nodes to resolve hostnames (e.g. gateways/supernodes).
There are the following settings:
servers
cacheentries
To use the node's DNS server, both options should be set. The node will cache at
most 'cacheentries' many DNS records in RAM. The 'servers' list will be used to
resolve the received DNS queries if the request cannot be answered from
cache. Gateways should announce the "next node" address via DHCP and RDNSS (if
any). Note that not setting 'servers' here will lead to DNS not working: Once
the gateways all announce the "next node" address for DNS, there is no way for
nodes to automatically determine DNS servers. They have to be baked into the
firmware.
If these settings do not exist, the cache is not initialized and RAM usage will
not increase.
When next_node.name is set, an A record and an AAAA record for the
next-node IP address are placed in the dnsmasq configuration. This means that
the content of next_node.name may be resolved even without upstream connectivity.
It is suggested to use the same name as the DNS server provides:
e.g. nextnode.location.community.example.org (This way the name also works if a
client uses static DNS Servers). Hint: If next_node.name does not contain a dot
some browsers would open the searchpage instead.
::
dns = {
cacheentries = 5000,
servers = { '2001:4860:4860::8888', '2001:4860:4860::8844' },
},
next_node = {
name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
ip6 = '2001:db8:8::1',
ip4 = '198.51.100.1',
}
Each cache entry will occupy about 90 bytes of RAM.
docs/features/dns-forwarder.rst deleted 100644 → 0
View file @ bf8c3bab
DNS forwarder
=============
A Gluon node can be configured to act as a DNS forwarder. Requests for the
next-node hostname(s) can be answered locally, without querying the upstream
resolver.
**Note:** While this reduces answer time and allows to use the next-node
hostname without upstream connectivity, this feature should not be used for
next-node hostnames that are FQDN when the zone uses DNSSEC.
One or more upstream resolvers can be configured in the *dns.servers* setting.
When *next_node.name* is set, A and/or AAAA records for the next-node IP
addresses are placed in the dnsmasq configuration.
::
dns = {
servers = { '2001:db8::1', },
},
next_node = {
name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
ip6 = '2001:db8:8::1',
ip4 = '198.51.100.1',
}
docs/features/monitoring.rst
View file @ a6566bab
......@@ -47,7 +47,7 @@ installed. Please note that at least one alfred daemon is required to run as
.. _alfred-json: https://github.com/ffnord/alfred-json
The following datatypes are used:
The following data types are used:
* `nodeinfo`: 158
* `statistics`: 159
......@@ -135,5 +135,5 @@ Adding a data provider
----------------------
To add a provider, you need to install a shared object into ``/lib/gluon/respondd``.
For more information, refer to the `respondd README <https://github.com/freifunk-gluon/packages/blob/master/net/respondd/README.md>`_
For more information, refer to the `respondd README <https://github.com/freifunk-gluon/packages/blob/main/net/respondd/README.md>`_
and have a look the existing providers.
docs/features/multidomain.rst
View file @ a6566bab
......@@ -21,18 +21,18 @@ Overview
Multidomain support allows to build a single firmware with multiple,
switchable domain configurations. The nomenclature is as follows:
- ``site``: an aggregate over multiple domains
- ``domain``: mesh network with connectivity parameters that prevent
accidental bridging with other domains
- ``domain code``: unique domain identifier
- ``domain name``: pretty name for a domain code
- ``site``: an aggregate over multiple domains
- ``domain``: mesh network with connectivity parameters that prevent
accidental bridging with other domains
- ``domain code``: unique domain identifier
- ``domain name``: pretty name for a domain code
By default Gluon builds firmware with a single domain embedded into
``site.conf``. To use multiple domains, enable it in ``site.mk``:
::
GLUON_MULTIDOMAIN=1
GLUON_MULTIDOMAIN=1
In the site repository, create the ``domains/`` directory, which will
hold your domain configurations. Each domain configuration file is named
......@@ -41,26 +41,26 @@ supported.
::
site/
|-- site.conf
|-- site.mk
|-- i18n/
|-- domains/
|-- alpha_centauri.conf
|-- beta_centauri.conf
|-- gamma_centauri.conf
site/
|-- site.conf
|-- site.mk
|-- i18n/
|-- domains/
|-- alpha_centauri.conf
|-- beta_centauri.conf
|-- gamma_centauri.conf
The domain configuration ``alpha_centauri.conf`` could look like this.
::
{
domain_names = {
alpha_centauri = 'Alpha Centauri'
},
{
domain_names = {
alpha_centauri = 'Alpha Centauri'
},
-- more domain specific config follows below
}
-- more domain specific config follows below
}
In this example “Alpha Centauri” is the user-visible ``domain_name`` for the
domain_code ``alpha_centauri``. Also note that the domain code
......@@ -88,18 +88,25 @@ domain of a router, if and only if one of the above conditions matches.
Switching the domain
--------------------
**via commandline**:
Via commandline
^^^^^^^^^^^^^^^
::
uci set gluon.core.domain="newdomaincode"
gluon-reconfigure
reboot
gluon-switch-domain 'newdomaincode'
**via config mode:**
When the node is not in config mode, ``gluon-switch-domain`` will automatically
reboot the node by default. This can be suppressed by passing ``--no-reboot``::
To allow switching the domain via config mode, ``config-mode-domain-select``
has to be added to GLUON_FEATURES in the site.mk.
gluon-switch-domain --no-reboot 'newdomaincode'
Switching the domain without reboot is currently **experimental**.
Via config mode
^^^^^^^^^^^^^^^
To allow switching the domain via config mode, add ``config-mode-domain-select``
to the enabled features in the image-customization.lua file.
|image0|
......@@ -116,115 +123,112 @@ site or domain context.
site.conf only variables
^^^^^^^^^^^^^^^^^^^^^^^^
- Used in as initial default values, when the firmware was just flashed
and/or the config mode is skipped, so they do not make sense in a
domain specific way:
- authorized_keys
- default_domain
- poe_passthrough
- mesh_on_wan
- mesh_on_lan
- single_as_lan
- setup_mode.skip
- autoupdater.branch
- mesh_vpn.enabled
- mesh_vpn.pubkey_privacy
- mesh_vpn.bandwidth_limit
- mesh_vpn.bandwidth_limit.enabled
- mesh_vpn.bandwidth_limit.ingress
- mesh_vpn.bandwidth_limit.egress
- Variables that influence the appearance of the config mode,
domain-independent because they are relevant before a domain was selected.
- config_mode.geo_location.show_altitude
- config_mode.hostname.optional
- config_mode.remote_login
- config_mode.remote_login.show_password_form
- config_mode.remote_login.min_password_length
- hostname_prefix
- mesh_vpn.fastd.configurable
- roles.default
- roles.list
- Specific to a firmware build itself:
- site_code
- site_name
- autoupdater.branches.*.name
- autoupdater.branches.*.good_signatures
- autoupdater.branches.*.pubkeys
- We simply do not see any reason, why these variables could be helpful
in a domain specific way:
- mesh_vpn.fastd.syslog_level
- timezone
- regdom
- Used in as initial default values, when the firmware was just flashed
and/or the config mode is skipped, so they do not make sense in a
domain specific way:
- authorized_keys
- default_domain
- poe_passthrough
- interfaces.*.default_roles
- setup_mode.skip
- autoupdater.branch
- mesh_vpn.enabled
- mesh_vpn.pubkey_privacy
- mesh_vpn.bandwidth_limit
- mesh_vpn.bandwidth_limit.enabled
- mesh_vpn.bandwidth_limit.ingress
- mesh_vpn.bandwidth_limit.egress
- Variables that influence the appearance of the config mode,
domain-independent because they are relevant before a domain was selected.
- config_mode.geo_location.show_altitude
- config_mode.hostname.optional
- config_mode.remote_login
- config_mode.remote_login.show_password_form
- config_mode.remote_login.min_password_length
- hostname_prefix
- mesh_vpn.fastd.configurable
- roles.default
- roles.list
- Specific to a firmware build itself:
- site_code
- site_name
- autoupdater.branches.*.name
- autoupdater.branches.*.good_signatures
- autoupdater.branches.*.pubkeys
- We simply do not see any reason, why these variables could be helpful
in a domain specific way:
- mesh_vpn.fastd.syslog_level
- timezone
- regdom
domain.conf only variables
^^^^^^^^^^^^^^^^^^^^^^^^^^
- Obviously:
- Obviously:
- domain_names
- domain_names
- a table of domain codes to domain names
``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
- a table of domain codes to domain names
``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
- hide_domain
- hide_domain
- prevents a domain name(s) from appearing in config mode, either
boolean or array of domain codes
- prevents a domain name(s) from appearing in config mode, either
boolean or array of domain codes
- ``true``, ``false``
- ``{ 'foo', 'bar' }``
- ``true``, ``false``
- ``{ 'foo', 'bar' }``
- Because each domain is considered as an own layer 2 network, these
values should be different in each domain:
- Because each domain is considered a separate layer 2 network, these
values should be different in each domain:
- next_node.ip4
- next_node.ip6
- next_node.name
- prefix6
- prefix4
- extra_prefixes6
- next_node.ip4
- next_node.ip6
- next_node.name
- prefix6
- prefix4
- extra_prefixes6
- To prevent accidental bridging of different domains, all meshing
technologies should be separated:
- To prevent accidental bridging of different domains, all meshing
technologies should be separated:
- domain_seed (wired mesh)
- domain_seed (wired mesh)
- must be a random value used to derive the vxlan id for wired meshing
- must be a random value used to derive the vxlan id for wired meshing
- wifi*.mesh.id
- mesh_vpn.fastd.groups.*.peers.remotes
- mesh_vpn.fastd.groups.*.peers.key
- mesh_vpn.tunneldigger.brokers
- wifi*.mesh.id
- mesh_vpn.fastd.groups.*.peers.remotes
- mesh_vpn.fastd.groups.*.peers.key
- Clients consider WiFi networks sharing the same ESSID as if they were
the same L2 network and try to reconfirm and reuse previous
addressing. If multiple neighbouring domains shared the same ESSID,
the roaming experience of clients would degrade.
- Clients consider WiFi networks sharing the same ESSID as if they were
the same L2 network and try to reconfirm and reuse previous
addressing. If multiple neighbouring domains shared the same ESSID,
the roaming experience of clients would degrade.
- wifi*.ap.ssid
- wifi*.ap.ssid
- Some values should be only set in legacy domains and not in new domains.
- Some values should be only set in legacy domains and not in new domains.
- mesh.vxlan
- mesh.vxlan
- By default, this value is `true`. It should be only set to `false`
for one legacy domain, since vxlan prevents accidental wired
merges of domains. For old domains this value is still available
to keep compatibility between all nodes in one domain.
- By default, this value is `true`. It should be only set to `false`
for one legacy domain, since vxlan prevents accidental wired
merges of domains. For old domains this value is still available
to keep compatibility between all nodes in one domain.
- next_node.mac
- next_node.mac
- For new domains, the default value should be used, since there is
no need for a special mac (or domain specific mac). For old domains
this value is still available to keep compatibility between all
nodes in one domain.
- For new domains, the default value should be used, since there is
no need for a special mac (or domain specific mac). For old domains
this value is still available to keep compatibility between all
nodes in one domain.
Example config
--------------
......
docs/features/private-wlan.rst
View file @ a6566bab
Private WLAN
============
It is possible to set up a private WLAN that bridges the WAN port and is separated from the mesh network.
Please note that you should not enable ``mesh_on_wan`` simultaneously.
It is possible to set up a private WLAN that bridges the uplink port and is separated from the mesh network.
Please note that you should not enable Wired Mesh on the uplink port at the same time.
The private WLAN is encrypted using WPA2 by default. On devices with enough flash and a supported radio,
WPA3 or WPA2/WPA3 mixed-mode can be used instead of WPA2. For this to work, the ``wireless-encryption-wpa3``
feature has to be added to ``GLUON_FEATURES``.
feature has to be enabled as a feature.
It is recommended to enable IEEE 802.11w management frame protection for WPA2/WPA3 networks, however this
can lead to connectivity problems for older clients. In this case, management frame protection can be
......
docs/features/status-page.png 0 → 100644
View file @ a6566bab
docs/features/status-page.png

150 KiB

docs/features/status-page.rst 0 → 100644
View file @ a6566bab
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 → 100644
View file @ a6566bab
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/vpn.rst
View file @ a6566bab
Mesh-VPN
.. _mesh-vpn:
Mesh VPN
========
Gluon integrates several OSI-Layer 2 tunneling protocols to
enable interconnects between local meshes and provide
internetwork access. Available protocols currently are:
Gluon integrates several layer 2 tunneling protocols to
allow connections between local meshes through the internet.
Protocols overview
^^^^^^^^^^^^^^^^^^
For a comprehensive comparison and evaluation of the supported and formerly supported VPN methods that best suit your needs, refer to the following table (Be sure to scroll to the right):
+---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
| Gluon VPN method | IPv4 | IPv6 | Authentication | Encryption | Kernelspace forwarding | MTU overhead | Multithreading | Single interface for all |
| | | | | (no→faster,insecure [1]_) | (yes→faster) | (bytes @v4) [7]_ | | peers |
+=======================================+======+==========+================+============================+========================+==================+================+==========================+
| fastd, encrypted | yes | yes | optional [2]_ | yes | no | low (98) | no | optional |
+---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
| fastd, null | yes | yes | optional [2]_, | no | no | low (98) | no | optional |
| | | | partial [3]_ | | | | | |
+---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
| fastd, ``null@l2tp``, with offloading | yes | yes | optional [2]_, | no | yes | low (82) | | optional |
| | | | partial [3]_ | | | | | |
+---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
| fastd, ``null@l2tp``, no offloading | yes | yes | optional [2]_, | no | no | low (82) | no | optional |
| | | | partial [3]_ | | | | | |
+---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
| Tunneldigger (L2TP - deprecated) [6]_ | yes | no [4]_ | no | no | yes | low (82) | | no |
+---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
| WireGuard + VXLAN | yes | yes | yes | yes | yes | high (162) | yes [5]_ | yes |
+---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
.. [1] No encryption allows internet providers to read and alter mesh traffic.
.. [2] The Gateway can ignore authentication for the initial connection request, via ``"on verify 'true'"``. However, a node→gateway handshake authentication with valid fastd keys in the site.conf is still required.
.. [3] Initial connection request can be authenticated, however, payload data is not authenticated afterward.
.. [4] https://github.com/wlanslovenija/tunneldigger/issues/75
.. [5] https://www.wireguard.com/performance/
.. [6] https://github.com/ffac/community-packages/tree/master/ff-mesh-vpn-tunneldigger
.. [7] :ref:`mtu`
Additional, notable compatibility features
""""""""""""""""""""""""""""""""""""""""""
* fastd: multiple encrypted and unencrypted methods can be handled by one daemon
* fastd: a ``null@l2tp`` peer with offloading is fully compatible with a peer with ``null@l2tp`` without offloading
* fastd+WireGuard: a single secret can be used for both fastd and WireGuard via :ref:`gluon-mesh-vpn-key-translate <gluon-mesh-vpn-key-translate>`, so no need for a node owner switching to (or from) Wireguard from (or to) fastd to submit a new key
Core Protocol handlers
^^^^^^^^^^^^^^^^^^^^^^
- fastd
- L2TPv3 (via tunneldigger)
There are currently two supported protocol handlers which
can be selected as a feature:
fastd is a lightweight userspace tunneling daemon, that
mesh-vpn-fastd
""""""""""""""
fastd is a lightweight userspace tunneling daemon that
implements cipher suites that are specifically designed
to work well on embedded devices. It offers encryption
and authentication. Its primary drawback are the necessary
context-switches when forwarding packets.
and authentication.
The primary drawback of fastd's encrypted connection modes
is the necessary context switches when forwarding packets.
A kernel-supported L2TPv3 offloading option is available to
work around the context-switching bottleneck, but it comes
at the cost of losing the ability to protect tunnel connections
against eavesdropping or manipulation.
mesh-vpn-wireguard
""""""""""""""""""
L2TPv3 is an in-kernel tunneling protocol that performs well,
but offers no security properties by itself.
The brokering of the tunnel happens through tunneldigger,
its primary drawback being the lack of IPv6 support.
WireGuard is an encrypted in-kernel tunneling protocol that
provides encrypted transmission and at the same time offers
high throughput.
fastd
-----
^^^^^
Configurable Cipher
^^^^^^^^^^^^^^^^^^^
.. _VPN fastd methods:
Methods
"""""""
From the site configuration fastd can be allowed to offer
toggleable encryption in the config mode with the intent to
increase throughput, although in practice the gain is minimal.
fastd offers various different connection "methods" with different
security properties that can be configured in the site configuration.
**Site configuration:**
The following methods are currently recommended:
1) Add the feature ``web-mesh-vpn-fastd`` in ``site.mk``
2) Set ``mesh_vpn.fastd.configurable = true`` in ``site.conf``
3) Optionally add ``null`` to the ``mesh_vpn.fastd.methods`` table if you want "Performance mode" as default (not recommended)
- ``salsa2012+umac``: Encrypted + authenticated
- ``null+salsa2012+umac``: Unencrypted, authenticated
- ``null@l2tp``: Unencrypted, unauthenticated
**Gateway configuration:**
Multiple methods can be listed in ``site.conf``. The first listed method
supported by both the node and its peer will be used.
1) Prepend the ``null`` cipher in fastd's method list
The use of the ``null@l2tp`` method with offloading enabled can provide a
considerable performance gain, especially on weaker embedded hardware.
For L2TP offloading, the ``mesh-vpn-fastd-l2tp`` feature needs to be enabled in
``site.mk``.
**Config Mode:**
The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport.
.. _vpn-gateway-configuration:
.. image:: fastd_mode.gif
Gateway / Supernode Configuration
"""""""""""""""""""""""""""""""""
When only using the ``null`` or ``null@l2tp`` methods without offloading,
simply add these methods to the front of the method list. ``null@l2tp``
should always appear before ``null`` in the configuration when both are enabled.
fastd v22 or newer is needed for the ``null@l2tp`` method.
It is often not necessary to enable L2TP offloading on supernodes for
performance reasons. Nodes using offloading can communicate with supernodes that
don't use offloading as long as both use the ``null@l2tp`` method.
.. _vpn-gateway-configuration-offloading:
Offloading on Gateways / Supernodes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Unix socket:**
To confirm whether the correct cipher is being used, fastds unix
socket can be interrogated, after installing for example `socat`.
To enable L2TP offloading on the supernodes, it is recommended to study the
fastd documentation section pertaining to the `offload configuration option
<https://fastd.readthedocs.io/en/stable/manual/config.html#option-offload>`_.
::
However, the important changes to the fastd config on your Supernode are:
- | Set ``mode multitap;``
| Every peer gets their own interface.
- | Replace ``interface "foo":`` with ``interface "peer-%k";``
| ``%k`` is substituted for a portion of the peers public key.
- | Set ``offload l2tp yes;``
| This tells fastd to use the l2tp kernel module.
- | Set ``persist interface no;``
| This tells fastd to only keep interfaces around while the connection is active.
Note that in ``multitap`` mode, which is required when using L2TP offloading,
fastd will create one interface per peer on the supernode's. This allows
offloading the L2TP forwarding into the kernel space. But this also means added
complexity with regards to handling those interfaces.
There are two main options on how you can handle this:
- create ``on up`` and ``on down`` hooks
- to handle interface setup and destruction
- preferably using the async keyword, so hooks are not blocking fastd
- use a daemon like systemd-networkd
Examples for both options can be found in the
`Wiki <https://github.com/freifunk-gluon/gluon/wiki/fastd-l2tp-offloading-on-supernodes>`_.
Configurable Method
"""""""""""""""""""
From the site configuration, fastd can be allowed to offer
toggleable encryption in the config mode with the intent to
increase throughput.
There is also an older unprotected method ``null``. Use of the newer
``null@l2tp`` method is generally recommended over ``null``, as the
performance gains provided by the latter (compared to the encrypted
and authenticated methods) are very small.
Site configuration
~~~~~~~~~~~~~~~~~~
1)
Add the feature ``web-mesh-vpn-fastd`` in ``site.mk``
2)
Set ``mesh_vpn.fastd.configurable = true`` in ``site.conf``
3)
Optionally, add ``null@l2tp`` to the ``mesh_vpn.fastd.methods`` table if you want
"Performance mode" as default (not recommended)
Config Mode
~~~~~~~~~~~
The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport.
.. image:: fastd_mode.gif
opkg update
opkg install socat
socat - UNIX-CONNECT:/var/run/fastd.mesh_vpn.socket
To confirm whether the correct cipher is being used, the log output
of fastd can be checked using ``logread``.
WireGuard
^^^^^^^^^
In order to support WireGuard in Gluon, a few technologies are glued together.
**VXLAN:** As Gluon typically relies on batman-adv, the Mesh VPN has to provide
OSI Layer 2 transport. But WireGuard is an OSI Layer 3 tunneling protocol, so
additional technology is necessary here. For this, we use VXLAN. In short, VXLAN
is a well-known technology to encapsulate ethernet packages into IP packages.
You can think of it as kind of similar to VLAN, but on a different layer. Here,
we use VXLAN to transport batman-adv traffic over WireGuard.
**wgpeerselector**: To connect all gluon nodes to each other, it is common to
create a topology where each gluon node is connected to one of the available
gateways via Mesh VPN respectively. To achieve this, the gluon node should be
able to select a random gateway to connect to. But such "random selection of a
peer" is not implemented in WireGuard by default. WireGuard only knows static
peers. Therefore the *wgpeerselector* has been developed. It randomly selects a
gateway, tries to establish a connection, and if it fails, tries to connect
to the next gateway. This approach has several advantages, such as load
balancing VPN connection attempts and avoiding problems with offline gateways.
More information about the wgpeerselector and its algorithm can be found
`here <https://github.com/freifunk-gluon/packages/blob/main/net/wgpeerselector/README.md>`__.
On the gluon node both VXLAN and the wgpeerselector are well integrated and no
explicit configuration of those tools is necessary, once the general WireGuard
support has been configured.
Attention must by paid to time synchronization. As WireGuard
performs checks on timestamps in order to avoid replay attacks, time must
be synchronized before the Mesh VPN connection is established. This means that
the NTP servers specified in your site.conf must be publicly available (and not
only through the mesh). Be aware that if you fail this, you may not directly see
negative effects. Only when a previously connected node reboots the effect
comes into play, as the gateway still knows about the old timestamp of the gluon
node.
.. _gluon-mesh-vpn-key-translate:
gluon-mesh-vpn-key-translate
""""""""""""""""""""""""""""
Many communities already possess a collection of active fastd-keys when they
plan migrating their community to WireGuard.
These public keys known on the server-side can be derived into their WireGuard
equivalent using `gluon-mesh-vpn-key-translate <https://github.com/AiyionPrime/gluon-mesh-vpn-key-translate>`__.
The routers do the necessary reencoding of the private key seamlessly
when updating firmware from fastd to the WireGuard variant.
Gateway / Supernode Configuration
"""""""""""""""""""""""""""""""""
On the gateway side, a software called *wireguard-vxlan-glue* is necessary. It
is a small daemon that dynamically adds and removes forwarding rules for VXLAN
interfaces, so traffic is sent correctly into the WireGuard interface. Thereby
the forwarding rules are only installed if a client is connected, so
unnecessary traffic in the kernel is avoided. The source can be found
`here <https://github.com/freifunkh/wireguard-vxlan-glue/>`__.
docs/features/wired-mesh.rst
View file @ a6566bab
......@@ -50,38 +50,84 @@ Configuration
Both Mesh-on-WAN and Mesh-on-LAN can be configured on the "Network" page
of the *Advanced settings* (if the package ``gluon-web-network`` is installed).
It is also possible to enable Mesh-on-WAN and Mesh-on-LAN by default by
adding ``mesh_on_wan = true`` and ``mesh_on_lan = true`` to ``site.conf``.
It is also possible to enable Mesh-on-WAN and Mesh-on-LAN by default by adding
the ``mesh`` role to the ``interfaces.*.default_roles`` options in your
:ref:`site.conf<user-site-interfaces>`.
.. _wired-mesh-commandline:
Commandline
===========
Starting with release 2022.1, the wired network configuration is rebuilt from ``/etc/config/gluon``
upon each ``gluon-reconfigure``.
Therefore the network configuration is overwritten at least with every firmware upgrade.
Every interface has a list of roles assigned to it which can be ``client``, ``mesh`` or ``uplink``.
When the client role is assigned to an interface in combination with other roles
(like 'client', 'mesh' in the Mesh-on-LAN example below), the other roles take
precedence, enabling mesh but not client in the previous example.
The setup/config-mode interface is every interface with the role ``client`` which makes removing
it from interfaces not only unnecessary, but generally unrecommended.
In order to make persistent changes to the router's configuration it's necessary to:
* change the sections in ``/etc/config/gluon`` e.g. using uci (see examples below)
* call ``gluon-reconfigure`` to re-generate ``/etc/config/network``
* apply the networking changes, either through executing ``service network restart`` or by performing a ``reboot``
Enable Mesh-on-WAN::
uci set network.mesh_wan.disabled=0
uci commit network
uci add_list gluon.iface_wan.role='mesh'
uci commit gluon
Disable Mesh-on-WAN::
uci set network.mesh_wan.disabled=1
uci commit network
uci del_list gluon.iface_wan.role='mesh'
uci commit gluon
Enable Mesh-on-LAN::
uci set network.mesh_lan.disabled=0
for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
uci del_list network.client.ifname=$ifname
done
uci commit network
uci add_list gluon.iface_lan.role='mesh'
uci commit gluon
Disable Mesh-on-LAN::
uci set network.mesh_lan.disabled=1
for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
uci add_list network.client.ifname=$ifname
done
uci commit network
uci del_list gluon.iface_lan.role='mesh'
uci commit gluon
For devices with a single interface, instead of `iface_lan` and `iface_wan` configuration is
done with `iface_single`.
Enable Mesh-on-Single::
uci add_list gluon.iface_single.role='mesh'
uci commit gluon
Disable Mesh-on-Single::
uci del_list gluon.iface_single.role='mesh'
uci commit gluon
Furthermore it is possible to make use of 802.1Q VLAN.
The following statements would create a VLAN with id 8 on ``eth0`` and join the mesh network with it::
uci set gluon.iface_lan_vlan8=interface
uci set gluon.iface_lan_vlan8.name='eth0.8'
uci add_list gluon.iface_lan_vlan8.role='mesh'
uci commit gluon
Other VLAN-interfaces could be configured on the same parent interface in order to have
all three roles available on ``eth0`` without having them interfere with each other.
This feature comes in especially handy for the persistent configuration of virtual machines
as offloader for bigger installations.
A ``reboot`` is not sufficient to apply an altered configuration; calling ``gluon-reconfigure`` before is
mandatory in order for changes to take effect.
Please note that this configuration has changed in Gluon 2016.1. Using
the old commands on 2016.1 and later will break the corresponding options
Please note that this configuration has changed in Gluon 2022.1. Using
the old commands on 2022.1 and later will break the corresponding options
in the *Advanced settings*.
docs/features/wlan-configuration.rst
View file @ a6566bab
......@@ -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
-----------------
......@@ -16,10 +23,10 @@ by the user). This means that it is not possible to enable or disable an existin
configurations during upgrades.
During upgrades the wifi channel of the 2.4GHz and 5GHz radio will be restored to the channel
configured in the site.conf. If you need to preserve a user defined wifi channel during upgrades
you can configure this via the uci section ``gluon-core.wireless``::
configured in the site.conf. The channel width will be reset to Gluon's default. If you need to preserve
these settings during upgrades you can configure this via the uci section ``gluon-core.wireless``::
uci set gluon-core.@wireless[0].preserve_channels='1'
uci set gluon.wireless.preserve_channels='1'
When channels should be preserved, toggling the outdoor mode will have no effect on the channel settings.
Therefore, the Outdoor mode settings won't be displayed in config mode.
......
docs/index.rst
View file @ a6566bab
......@@ -6,133 +6,92 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
.. toctree::
:caption: User Documentation
:maxdepth: 2
:caption: User Documentation
:maxdepth: 2
user/getting_started
user/site
user/supported_devices
user/x86
user/faq
user/getting_started
user/site
user/supported_devices
user/x86
user/faq
user/mtu
.. toctree::
:caption: Features
:maxdepth: 2
features/configmode
features/autoupdater
features/wlan-configuration
features/private-wlan
features/wired-mesh
features/dns-forwarder
features/monitoring
features/multidomain
features/authorized-keys
features/roles
features/vpn
:caption: Features
:maxdepth: 2
features/configmode
features/autoupdater
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
:maxdepth: 2
dev/basics
dev/hardware
dev/packages
dev/upgrade
dev/wan
dev/mac_addresses
dev/site_library
dev/build
dev/debugging
:caption: Developer Documentation
:maxdepth: 2
dev/basics
dev/hardware
dev/packages
dev/upgrade
dev/uplink
dev/mac_addresses
dev/site_library
dev/build
dev/debugging
.. toctree::
:caption: gluon-web Reference
:maxdepth: 1
:caption: gluon-web Reference
:maxdepth: 1
dev/web/controller
dev/web/model
dev/web/view
dev/web/i18n
dev/web/config-mode
dev/web/controller
dev/web/model
dev/web/view
dev/web/i18n
dev/web/config-mode
.. toctree::
:caption: Packages
:maxdepth: 1
package/gluon-client-bridge
package/gluon-config-mode-domain-select
package/gluon-ebtables-filter-multicast
package/gluon-ebtables-filter-ra-dhcp
package/gluon-ebtables-limit-arp
package/gluon-ebtables-source-filter
package/gluon-hoodselector
package/gluon-logging
package/gluon-mesh-batman-adv
package/gluon-mesh-wireless-sae
package/gluon-radv-filterd
package/gluon-scheduled-domain-switch
package/gluon-web-admin
package/gluon-web-logging
:caption: Packages
:maxdepth: 1
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
package/gluon-ebtables-source-filter
package/gluon-hoodselector
package/gluon-logging
package/gluon-mesh-batman-adv
package/gluon-mesh-wireless-sae
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::
:caption: Releases
:maxdepth: 1
releases/v2020.2
releases/v2020.1.3
releases/v2020.1.2
releases/v2020.1.1
releases/v2020.1
releases/v2019.1.2
releases/v2019.1.1
releases/v2019.1
releases/v2018.2.4
releases/v2018.2.3
releases/v2018.2.2
releases/v2018.2.1
releases/v2018.2
releases/v2018.1.4
releases/v2018.1.3
releases/v2018.1.2
releases/v2018.1.1
releases/v2018.1
releases/v2017.1.8
releases/v2017.1.7
releases/v2017.1.6
releases/v2017.1.5
releases/v2017.1.4
releases/v2017.1.3
releases/v2017.1.2
releases/v2017.1.1
releases/v2017.1
releases/v2016.2.7
releases/v2016.2.6
releases/v2016.2.5
releases/v2016.2.4
releases/v2016.2.3
releases/v2016.2.2
releases/v2016.2.1
releases/v2016.2
releases/v2016.1.6
releases/v2016.1.5
releases/v2016.1.4
releases/v2016.1.3
releases/v2016.1.2
releases/v2016.1.1
releases/v2016.1
releases/v2015.1.2
releases/v2015.1.1
releases/v2015.1
releases/v2014.4
releases/v2014.3.1
releases/v2014.3
:caption: Releases
:maxdepth: 1
releases/index
License
-------
See LICENCE_
.. _LICENCE: https://github.com/freifunk-gluon/gluon/blob/master/LICENSE
.. _LICENCE: https://github.com/freifunk-gluon/gluon/blob/main/LICENSE
Indices and tables
==================
......
docs/multidomain-site-example/domains/alpha_centauri.conf
View file @ a6566bab
......@@ -22,9 +22,9 @@
},
wifi24 = {
channel = 1,
ap = {
ssid = "alpha-centauri.example.org",
channel = 1,
},
mesh = {
id = 'ueH3uXjdp', -- usually you don't want users to connect to this mesh-SSID, so use a cryptic id that no one will accidentally mistake for the client WiFi
......@@ -32,9 +32,9 @@
},
wifi5 = {
channel = 44,
ap = {
ssid = "alpha-centauri.example.org",
channel = 44,
},
mesh = {
id = 'ueH3uXjdp',
......
docs/multidomain-site-example/image-customization.lua 0 → 100644
View file @ a6566bab
features {
'autoupdater',
'ebtables-filter-multicast',
'ebtables-filter-ra-dhcp',
'ebtables-limit-arp',
'mesh-batman-adv-15',
'mesh-vpn-fastd',
'respondd',
'status-page',
'web-advanced',
'web-wizard',
}
packages {
'iwinfo',
}
if not device_class('tiny') then
features {'wireless-encryption-wpa3'}
end
docs/multidomain-site-example/site.conf
View file @ a6566bab
......@@ -20,10 +20,10 @@
},
mesh_vpn = {
mtu = 1312,
fastd = {
methods = {'salsa2012+umac'},
mtu = 1312,
},
bandwidth_limit = {
......@@ -39,7 +39,15 @@
branches = {
stable = {
name = 'stable',
mirrors = {'http://update.example.org/stable/sysupgrade'},
mirrors = {
'http://1.updates.example.org/stable/sysupgrade',
-- Requires the tls feature in image-customization.lua
-- 'https://2.updates.example.org/stable/sysupgrade',
-- Uses http or https depending on the tls feature in image-customization.lua
'//3.updates.example.org/stable/sysupgrade',
},
good_signatures = 2,
pubkeys = {
'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
......
docs/multidomain-site-example/site.mk
View file @ a6566bab
This diff is collapsed.
docs/package/gluon-config-mode-geo-location-osm.png 0 → 100644
View file @ a6566bab
docs/package/gluon-config-mode-geo-location-osm.png

345 KiB

Impressum - Datenschutz