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

Target

Select target project
  • ffbs/ffbs-gluon
  • parabol1337/ffbs-gluon
  • darkbit/ffbs-gluon
3 results
Show changes
Hide whitespace changes
Inline Side-by-side
Showing
with 763 additions and 402 deletions
docs/features/multidomain.rst
View file @ b9a90f4f
......@@ -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,117 +123,113 @@ 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*.ibss.ssid
- wifi*.ibss.bssid
- 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
- mesh_vpn.tunneldigger.brokers
- 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 @ b9a90f4f
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 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
made optional or completely disabled in the advanced settings tab.
The private WLAN can be enabled through the config mode if the package ``gluon-web-private-wifi`` is installed.
You may also enable a private WLAN using the command line::
......
docs/features/roles.rst
View file @ b9a90f4f
......@@ -2,8 +2,8 @@ Roles
=====
It is possible to define a set of roles you want to distinguish at backend side. One node can own one
role which it will announce via alfred inside the mesh. This will make it easier to differentiate
nodes when parsing alfred data. E.g to count only **normal** nodes and not the gateways
role which it will announce via respondd/announced inside the mesh. This will make it easier to differentiate
nodes when parsing respondd data. E.g to count only **normal** nodes and not the gateways
or servers (nodemap). A lot of things are possible.
For this the section ``roles`` in ``site.conf`` is needed::
......@@ -28,7 +28,7 @@ If you want node owners to change the defined roles via config-mode you can add
The role is saved in ``gluon-node-info.system.role``. To change the role using command line do::
uci set gluon-node-info.system.role="$ROLE"
uci set gluon-node-info.@system[0].role="$ROLE"
uci commit
Please replace ``$ROLE`` by the role you want the node to own.
docs/features/vpn.rst
View file @ b9a90f4f
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.
- fastd
- L2TPv3 (via tunneldigger)
Protocol handlers
^^^^^^^^^^^^^^^^^
fastd is a lightweight userspace tunneling daemon, that
There are currently three protocol handlers which can be selected
as a feature:
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.
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.
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-tunneldigger
"""""""""""""""""""""
Tunneldigger always uses L2TPv3, generally achieving the same
performance as fastd with the ``null@l2tp`` method, but offering
no security.
Tunneldigger's primary drawback is the lack of IPv6 support.
It also provides less configurability than fastd.
mesh-vpn-wireguard
""""""""""""""""""
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
**Unix socket:**
To confirm whether the correct cipher is being used, fastds unix
socket can be interrogated, after installing for example `socat`.
- | 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/master/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 @ b9a90f4f
......@@ -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 @ b9a90f4f
......@@ -2,10 +2,9 @@ WLAN configuration
==================
Gluon allows to configure 2.4GHz and 5GHz radios independently. The configuration
may include any or all of the three networks "client" (AP mode), "mesh" (802.11s
mode) and "ibss" (adhoc mode), which can be used simultaneously (using "mesh" and
"ibss" at same time should be avoided though as weaker hardware usually can't handle the additional
load). See :doc:`../user/site` for details on the configuration.
may include one or both of the two networks "client" (AP mode) and "mesh" (802.11s
mode), which can be used simultaneously. See :doc:`../user/site` for details on the
configuration.
Upgrade behaviour
-----------------
......@@ -16,19 +15,12 @@ on upgrades the existing setting is always retained (as this setting may have be
by the user). This means that it is not possible to enable or disable an existing network
configurations during upgrades.
For the "mesh" and "ibss" networks, the default setting only has an effect if none
of the two has existed before. If a new configuration has been added for "mesh" or "ibss",
while the other of the two has already existed before, the enabled/disabled state of the
existing configuration will also be set for the new configuration.
This allows upgrades to change from IBSS to 11s and vice-versa while retaining the
"wireless meshing is enabled/disabled" property configured by the user regardless
of the used mode.
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.
Keep in mind that nodes running wifi interfaces on custom channels can't mesh with default nodes anymore!
docs/index.rst
View file @ b9a90f4f
......@@ -6,114 +6,80 @@ 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/dns-cache
features/monitoring
features/multidomain
features/authorized-keys
features/roles
features/vpn
.. toctree::
:caption: Developer Documentation
:maxdepth: 2
dev/basics
dev/hardware
dev/packages
dev/upgrade
dev/wan
dev/mac_addresses
dev/site_library
: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-mesh-batman-adv
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-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
.. toctree::
:caption: Releases
:maxdepth: 1
releases/v2019.1
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
-------
......
docs/multidomain-site-example/domains/alpha_centauri.conf
View file @ b9a90f4f
......@@ -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 @ b9a90f4f
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 @ b9a90f4f
......@@ -20,10 +20,10 @@
},
mesh_vpn = {
mtu = 1312,
fastd = {
methods = {'salsa2012+umac'},
mtu = 1312,
},
bandwidth_limit = {
......
docs/multidomain-site-example/site.mk
View file @ b9a90f4f
## gluon site.mk makefile example
## GLUON_FEATURES
# Specify Gluon features/packages to enable;
# Gluon will automatically enable a set of packages
# depending on the combination of features listed
GLUON_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
## GLUON_MULTIDOMAIN
# Build gluon with multidomain support.
GLUON_MULTIDOMAIN=1
## GLUON_SITE_PACKAGES
# Specify additional Gluon/LEDE packages to include here;
# A minus sign may be prepended to remove a packages from the
# selection that would be enabled by default or due to the
# chosen feature flags
GLUON_SITE_PACKAGES := haveged iwinfo
## DEFAULT_GLUON_RELEASE
# version string to use for images
# gluon relies on
......@@ -58,6 +32,3 @@ GLUON_REGION ?= eu
# Languages to include
GLUON_LANGS ?= en de
# Do not build images for deprecated devices
GLUON_DEPRECATED ?= 0
docs/package/gluon-ebtables-limit-arp.rst
View file @ b9a90f4f
gluon-ebtables-limit-arp
========================
The *gluon-ebtables-limit-arp* package adds filters to limit the
amount of ARP requests client devices are allowed to send into the
mesh.
The *gluon-ebtables-limit-arp* package adds filters to limit the
amount of ARP requests client devices are allowed to send into the
mesh.
The limits per client device, identified by its MAC address, are
6 packets per minute and 1 per second per node in total.
6 packets per minute and 1 per second per node in total.
A burst of up to 50 ARP requests is allowed until the rate-limiting
takes effect (see ``--limit-burst`` in ``ebtables(8)``).
Furthermore, ARP requests for a target IP already present in the
batman-adv DAT cache are excluded from rate-limiting, in regard
batman-adv DAT cache are excluded from rate-limiting, in regard
to both counting and filtering, as batman-adv will be able
to respond locally without a burden for the mesh. Therefore, this
limiter should not affect popular target IP addresses, like those
......@@ -21,9 +21,10 @@ However it mitigates the impact on the mesh when a larger range of
its IPv4 subnet is being scanned, which would otherwise result in
a significant amount of ARP chatter, even for unused IP addresses.
This package is selected by default if the installed routing
package is gluon-mesh-batman-adv-14 or gluon-mesh-batman-adv-15.
This package is installed by default if the selected routing
feature is *mesh-batman-adv-15*.
It can be unselected via::
GLUON_SITE_PACKAGES := \
-gluon-ebtables-limit-arp
packages {
'-gluon-ebtables-limit-arp',
}
docs/package/gluon-hoodselector.rst
View file @ b9a90f4f
......@@ -36,7 +36,7 @@ example of a regional domain:
Behaviour
------------------
The following is an abstract state diagramm which gives an overview
The following is an abstract state diagram which gives an overview
of the process:
.. image:: ./gluon-hoodselector.svg
......@@ -61,12 +61,12 @@ It provides a fallback to the default domain.
Domain shapes
-------------
There are two types of domains: the unique dehault one without a defined shape
There are two types of domains: the unique default one without a defined shape
and others which contain shapes.
* **default domain**
The default domain doesn’t hold any shapes and represents the inverted area of
The default domain doesn't hold any shapes and represents the inverted area of
all other shapes held by other domains with geo coordinates. It will only be
entered if a node could not be matched to a geo domain. A suggested approach is
to define the "old" network as default domain and gradually migrate nodes from
......
docs/package/gluon-logging.rst 0 → 100644
View file @ b9a90f4f
gluon-logging
=============
The *gluon-logging* package allows to configure a remote syslog server that
will receive the systems log output that is also visible when calling ``logread``
from a terminal.
It supports both IPv4 and IPv6 endpoints over UDP and TCP.
Note: The syslog mechanism is incapable of providing a complete log as network
access is required to send out log messages and ``logd`` does not buffer and resend
older log messages even though they might be available in ``logread``.
This package conflicts with ``gluon-web-logging`` as it will overwrite the
user-given syslog server on every upgrade.
site.conf
---------
syslog.ip : required
- Destination address of the remote syslog server
syslog.port : optional
- Destination port of the remote syslog server
- Defaults to 514
syslog.proto : optional
- Protocol to transport syslog frames in, can be either ``tcp`` or ``udp``
- Defaults to UDP
Example::
syslog = {
ip = "2001:db8::1",
port = 514,
proto = "udp",
},
docs/package/gluon-mesh-batman-adv.rst
View file @ b9a90f4f
......@@ -2,7 +2,7 @@ gluon-mesh-batman-adv
=====================
.. image:: gluon-mesh-batman-adv-logo.svg
:width: 300 px
:width: 300 px
B.A.T.M.A.N. Advanced (often referenced as batman-adv) is an implementation of
the B.A.T.M.A.N. routing protocol in form of a linux kernel module operating on layer 2.
......@@ -20,49 +20,11 @@ B.A.T.M.A.N. Advanced project homepage:
* https://www.open-mesh.org/projects/batman-adv/wiki/Wiki
Flavours
--------
Gluon currently supports two main build flavours of batman-adv:
gluon-mesh-batman-adv-15
^^^^^^^^^^^^^^^^^^^^^^^^
This is the recommended batman-adv flavour to use.
It follows recent, upstream batman-adv releases and is flexible to new feature additions.
gluon-mesh-batman-adv-14 (`batman-adv-legacy`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
`gluon-mesh-batman-adv-14`, also known as `batman-adv-legacy` or batman-adv v2013.4
is the last batman-adv release with the batman-adv compatibility version 14, which
was released in October 2013.
With batman-adv v2014.0.0 a compat breakage became necessary for the introduction
of new features. However, one of these features was the addition of TVLV support
(type-version-length-value fields) which from then on allowed adding features
without breaking packet format compatibility. This made it possible to stay with
compatibility version 15 so far.
For new installations `gluon-mesh-batman-adv-14` is **not recommended**. It misses
a lot of bugfixes and is currently only available for existing communities
until they have migrated. This package will soon be deprecated and removed.
Also see:
* https://www.open-mesh.org/projects/batman-adv/wiki/Compatversion
* https://www.open-mesh.org/news/56
* https://github.com/freifunk-gluon/batman-adv-legacy/
B.A.T.M.A.N. Routing Algorithms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For the `gluon-mesh-batman-adv-15` package two routing algorithms are selectable
via :ref:`site.conf mesh section <user-site-mesh>`: BATMAN_IV and BATMAN_V.
For the `gluon-mesh-batman-adv-14` package, BATMAN_IV_LEGACY needs to be selected.
Two routing algorithms are selectable via
:ref:`site.conf mesh section <user-site-mesh>`: BATMAN_IV and BATMAN_V.
BATMAN_IV - stable
""""""""""""""""""
......@@ -85,21 +47,21 @@ Multicast Architecture
----------------------
.. image:: gluon-mesh-batman-adv-multicast.svg
:width: 300 px
:width: 300 px
While generally broadcast capability is a nice feature of a layer 2
mesh protocol, it quickly reaches its limit.
For meshes with about **50 nodes / 100 clients, or more** it is therefore highly
recommended to add the :doc:`gluon-ebtables-filter-multicast`
package. Also, with gluon-mesh-batman-adv-15 or gluon-mesh-batman-adv-14
installed :doc:`gluon-ebtables-limit-arp` is selected by default.
package. Also, with the *mesh-batman-adv-15* feature,
:doc:`gluon-ebtables-limit-arp` is selected by default.
Furthermore, by default IGMP and MLD messages are filtered. See
:ref:`site.conf mesh section <user-site-mesh>` and
:ref:`igmp-mld-domain-segmentation` for details.
To achieve some level of scalabilty for multicast, multicast group
To achieve some level of scalability for multicast, multicast group
awareness is implemented and utilized in the following ways:
Node-Local Multicast Handling
......
docs/package/gluon-mesh-wireless-sae.rst 0 → 100644
View file @ b9a90f4f
gluon-mesh-wireless-sae
=======================
This package adds support for SAE on 802.11s mesh connections.
Enabling this package will require all 802.11s mesh connections
to be encrypted using the SAE key agreement scheme. The security
of SAE relies upon the authentication through a shared secret.
In the context of public mesh networks a shared secret is an
obvious oxymoron. Still, this functionality may provide an improvement
over unencrypted mesh connections in that it protects against a
passive attacker who did not observe the key agreement. In addition
Management Frame Protection (802.11w) gets automatically enabled on
wireless mesh interfaces to prevent protocol-level deauthentication attacks.
If `wifi.mesh.sae` is enabled, a shared secret will automatically be
derived from the `prefix6` variable. This is as secure as it gets
for a public mesh network.
For *private* mesh networks `wifi.mesh.sae_passphrase` should be
set to your shared secret.
site.conf
---------
These settings apply to all 802.11s mesh interfaces on all radios.
wifi.mesh.sae \: optional
- ``true`` enables SAE on 802.11s mesh connections
- ``false`` disables SAE on 802.11s mesh connections
- defaults to ``false``
wifi.mesh.sae_passphrase \: optional
- sets a shared secret used to authenticate any two mesh nodes,
crucial for private mesh networks
- should not be set, if the shared secret is shared with untrusted
third parties, like in a publish mesh network
- defaults to an autogenerated value derived from ``prefix6``
Example::
wifi = {
mesh = {
sae = true,
-- sae_passphrase = "<shared secret>",
},
},
docs/package/gluon-radv-filterd.rst
View file @ b9a90f4f
......@@ -13,29 +13,32 @@ Selected router
The router selection mechanism is independent from the batman-adv gateway mode.
In contrast, the device originating the router advertisement could be any router
or client connected to the mesh, as radv-filterd captures all router
advertisements originating from it. All nodes announcing router advertisement
advertisements originating from it. All nodes announcing router advertisement
**with** a default lifetime greater than 0 are being considered as candidates.
In case a router is not a batman-adv originator itself, its TQ is defined by
the originator it is connected to. This lookup uses the batman-adv global
translation table.
Initially the router is the selected by choosing the candidate with the
strongest TQ. When another candidate can provide a better TQ metric it is not
picked up as the selected router until it will outperform the currently
selected router by X metric units. The hysteresis threshold is configurable
and prevents excessive flapping of the gateway.
Initially the router is selected by choosing the candidate with the strongest
TQ. When another candidate can provide a better TQ metric, that outperforms the
currently selected router by X metric units, it will be picked as the new
selected router. The hysteresis threshold is configurable and prevents excessive
flapping of the gateway.
"Local" routers
---------------
Local routers
-------------
Local routers (i.e. local internet gateways connected to some nodes) that are
connected to the client interface via cable or WLAN instead of via the mesh
(technically: appearing in the transtable_local) are taken into account with a
fake TQ of 512, so that they are always preferred.
The package has functionality to select "local" routers, i.e. those connected
via cable or WLAN instead of via the mesh (technically: appearing in the
``transtable_local``), a fake TQ of 512 so that they are always preferred.
However, if used together with the :doc:`gluon-ebtables-filter-ra-dhcp`
package, these router advertisements are filtered anyway and reach neither the
node nor any other client. You currently have to disable the package or insert
custom ebtables rules in order to use local routers.
Be aware of problems if you plan to use local routers together with the
:doc:`gluon-ebtables-filter-ra-dhcp` package. These router advertisements are
filtered anyway and reach neither the node nor any other client. Therefore the
use of local routers is not possible as long as the package
``gluon-radv-filterd`` is used.
respondd module
---------------
......
docs/package/gluon-scheduled-domain-switch.rst
View file @ b9a90f4f
......@@ -3,7 +3,7 @@ gluon-scheduled-domain-switch
This package allows to switch a routers domain at a given point
in time. This is needed for switching between incompatible transport
protocols (e.g. 802.11s and IBSS or VXLAN).
protocols (e.g. wired meshing with and without VXLAN).
Nodes will switch when the defined *switch-time* has passed. In case the node was
powered off while this was supposed to happen, it might not be able to acquire the
......@@ -15,15 +15,15 @@ site.conf
All those settings have to be defined exclusively in the domain, not the site.
domain_switch : optional (needed for domains to switch)
target_domain :
- target domain to switch to
switch_after_offline_mins :
- amount of time without reachable gateway to switch unconditionally
switch_time :
- UNIX epoch after which domain will be switched
connection_check_targets :
- array of IPv6 addresses which are probed to determine if the node is
connected to the mesh
target_domain :
- target domain to switch to
switch_after_offline_mins :
- amount of time without reachable gateway to switch unconditionally
switch_time :
- UNIX epoch after which domain will be switched
connection_check_targets :
- array of IPv6 addresses which are probed to determine if the node is
connected to the mesh
Example::
......
docs/package/gluon-web-admin.rst
View file @ b9a90f4f
......@@ -13,7 +13,7 @@ config_mode.remote_login.show_password_form \: optional
- ``true`` the password section in config mode is shown
- ``false`` the password section in config mode is hidden
- defaults to ``false``
config_mode.remote_login.min_password_length \: optional
- sets the minimum allowed password length. Set this to ``1`` to disable the
length check.
......
docs/releases/index.rst 0 → 100644
View file @ b9a90f4f
Release Notes
=============
.. toctree::
:caption: Gluon 2023.2
:maxdepth: 2
v2023.2.4
v2023.2.3
v2023.2.2
v2023.2.1
v2023.2
.. toctree::
:caption: Gluon 2023.1
:maxdepth: 2
v2023.1.1
v2023.1
.. toctree::
:caption: Gluon 2022.1
:maxdepth: 2
v2022.1.4
v2022.1.3
v2022.1.2
v2022.1.1
v2022.1
.. toctree::
:caption: Gluon 2021.1
:maxdepth: 2
v2021.1.2
v2021.1.1
v2021.1
.. toctree::
:caption: Gluon 2020.2
:maxdepth: 2
v2020.2.3
v2020.2.2
v2020.2.1
v2020.2
.. toctree::
:caption: Gluon 2020.1
:maxdepth: 2
v2020.1.4
v2020.1.3
v2020.1.2
v2020.1.1
v2020.1
.. toctree::
:caption: Gluon 2019.1
:maxdepth: 2
v2019.1.3
v2019.1.2
v2019.1.1
v2019.1
.. toctree::
:caption: Gluon 2018.2
:maxdepth: 2
v2018.2.4
v2018.2.3
v2018.2.2
v2018.2.1
v2018.2
.. toctree::
:caption: Gluon 2018.1
:maxdepth: 2
v2018.1.4
v2018.1.3
v2018.1.2
v2018.1.1
v2018.1
.. toctree::
:caption: Gluon 2017.1
:maxdepth: 2
v2017.1.8
v2017.1.7
v2017.1.6
v2017.1.5
v2017.1.4
v2017.1.3
v2017.1.2
v2017.1.1
v2017.1
.. toctree::
:caption: Gluon 2016.2
:maxdepth: 2
v2016.2.7
v2016.2.6
v2016.2.5
v2016.2.4
v2016.2.3
v2016.2.2
v2016.2.1
v2016.2
.. toctree::
:caption: Gluon 2016.1
:maxdepth: 2
v2016.1.6
v2016.1.5
v2016.1.4
v2016.1.3
v2016.1.2
v2016.1.1
v2016.1
.. toctree::
:caption: Gluon 2015.1
:maxdepth: 2
v2015.1.2
v2015.1.1
v2015.1
.. toctree::
:caption: Gluon 2014.4
:maxdepth: 2
v2014.4
.. toctree::
:caption: Gluon 2014.3
:maxdepth: 2
v2014.3.1
v2014.3