From 7a5c6246dfcf5e0814af9210df872c7295ffebcf Mon Sep 17 00:00:00 2001 From: David Bauer Date: Mon, 27 Nov 2023 05:59:59 +0100 Subject: [PATCH] docs: update to use new site-selection framework --- docs/dev/packages.rst | 3 +- docs/features/multidomain.rst | 2 +- docs/features/private-wlan.rst | 2 +- docs/features/vpn.rst | 2 +- docs/user/site.rst | 99 ++++++++++++++++++++-------------- 5 files changed, 64 insertions(+), 44 deletions(-) diff --git a/docs/dev/packages.rst b/docs/dev/packages.rst index 5bd1f0e3300..83371d88ba6 100644 --- a/docs/dev/packages.rst +++ b/docs/dev/packages.rst @@ -154,7 +154,8 @@ Feature flags Feature flags provide a convenient way to define package selections without making it necessary to list each package explicitly. The list of features to -enable for a Gluon build is set by the *GLUON_FEATURES* variable in *site.mk*. +enable for a Gluon build is determined by the selection of features using +the feature and package customization framework. The main feature flag definition file is ``package/features``, but each package feed can provide additional definitions in a file called ``features`` at the root diff --git a/docs/features/multidomain.rst b/docs/features/multidomain.rst index 43f343bbb60..a345bcd3e7d 100644 --- a/docs/features/multidomain.rst +++ b/docs/features/multidomain.rst @@ -106,7 +106,7 @@ Via config mode ^^^^^^^^^^^^^^^ To allow switching the domain via config mode, add ``config-mode-domain-select`` -to GLUON_FEATURES in site.mk. +to your list of enabled features. |image0| diff --git a/docs/features/private-wlan.rst b/docs/features/private-wlan.rst index 41664b73b07..338206e9d69 100644 --- a/docs/features/private-wlan.rst +++ b/docs/features/private-wlan.rst @@ -6,7 +6,7 @@ Please note that you should not enable Wired Mesh on the uplink port at the same 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. 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 diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst index 7a5ba774876..391de9bda99 100644 --- a/docs/features/vpn.rst +++ b/docs/features/vpn.rst @@ -8,7 +8,7 @@ Protocol handlers ^^^^^^^^^^^^^^^^^ There are currently three protocol handlers which can be selected -via ``GLUON_FEATURES`` in ``site.mk``: +as features in a site ``package``: mesh-vpn-fastd """""""""""""" diff --git a/docs/user/site.rst b/docs/user/site.rst index f21778ee7c1..f989bc352ec 100644 --- a/docs/user/site.rst +++ b/docs/user/site.rst @@ -134,8 +134,8 @@ wifi24 \: optional For an OWE secured network, the ``owe_ssid`` string has to be set. It sets the SSID for the opportunistically encrypted wireless network, to which compatible clients can connect to. - For OWE to work, the ``wireless-encryption-wpa3`` has to be enabled (usually by - adding it to ``GLUON_FEATURES_standard``) in your ``site.mk``. + For OWE to work, the ``wireless-encryption-wpa3`` feature has to be enabled + in your package-selection. To utilize the OWE transition mode, ``owe_transition_mode`` has to be set to true. When ``owe_transition_mode`` is enabled, the OWE secured SSID will be hidden. Compatible devices will automatically connect to the OWE secured SSID when selecting @@ -611,33 +611,6 @@ GLUON_DEPRECATED and ``upgrade`` for existing configurations (where upgrades for existing deployments of low-flash devices are required). Defaults to ``0``. -GLUON_FEATURES - Defines a list of features to include. Depending on the device, the feature list - defined from this value is combined with the feature list for either the standard - or the tiny device-class. The resulting feature list is used to generate the default - package set. - -GLUON_FEATURES_standard - Defines a list of additional features to include or exclude for devices of - the standard device-class. - -GLUON_FEATURES_tiny - Defines a list of additional features to include or exclude for devices of - the tiny device-class. - -GLUON_SITE_PACKAGES - Defines a list of packages which should be installed in addition to the - default package set. It is also possible to remove packages from the - default set by prepending a minus sign to the package name. - -GLUON_SITE_PACKAGES_standard - Defines a list of additional packages to include or exclude for devices of - the standard device-class. - -GLUON_SITE_PACKAGES_tiny - Defines a list of additional packages to include or exclude for devices of - the tiny device-class. - GLUON_RELEASE The current release version Gluon should use. @@ -655,6 +628,56 @@ GLUON_LANGS .. _user-site-feature-flags: +Feature customization +^^^^^^^^^^^^^^^^^^^^^ + +For inclusion of additional features and packages, Gluon provides a flexible +framework for determining, which features and packages a specific device image +ships with. + +Features and package inclusions are defined within the *packages* file in the +site root. Multiple selectors and criteria are available for controlling +per-device package and feature inclusion. + +A selector always includes a selection-set. A selection-set is a Lua table +consisting of one or more selectors. + +An example can be found in the example site. + +The following selectors are available. + +Feature(feature-name) + Include a gluon-specific feature in the image. + +Package(package-name) + Include a package in the image. This selector should only + be used with non-gluon packages, be it from OpenWrt upstream + or custom package feeds. + +The following criteria are available. + +default(selection-set) + The default criteria includes packages without any further criteria. + It is functionally equivalent to the *when* selector with an always-true + condition. + +when(condition, selection-set) + This criteria includes a selection-set if the condition evaluates to true. + +The following conditions are available. + +device(device-name) + Match a specific device name. The name is identical with the OpenWrt target name. + +target(target, subtarget) + Match a specific target and optionally a subtarget. If subtarget is omitted, + all subtargets belonging to the target are matched. + +device_class + Match a specific device-class. Currently supported values are *standard* and *tiny*. + +Conditions can be combined using Lua operators like *and* or *or*. + Feature flags ^^^^^^^^^^^^^ @@ -674,8 +697,8 @@ leading to entangled package names like *gluon-mesh-vpn-fastd-respondd* or *gluon-status-page-mesh-batman-adv-i18n-de*. For this reason, we have introduced *feature flags*, which can be specified -in the *GLUON_FEATURES* variable. These flags allow to specify a set of features -on a higher level than individual package names. +in the *packages* file of a site repository. These flags allow to specify a +set of features on a higher level than individual package names. Most Gluon packages can simply be specified as feature flags by removing the ``gluon-`` prefix: The feature flag corresponding to the package *gluon-mesh-batman-adv-15* is @@ -697,7 +720,7 @@ flags using a flexible ruleset defined in the Gluon repo or site package feeds. To some extent, it will even allow us to further modularize existing Gluon packages, without necessitating changes to existing site configurations. -It is still possible to override such automatic rules using *GLUON_SITE_PACKAGES* +It is still possible to override such automatic rules by using a *package* selector (e.g., ``-gluon-status-page-mesh-batman-adv`` to remove the automatically added package *gluon-status-page-mesh-batman-adv*). @@ -707,18 +730,14 @@ package: * web-wizard Includes the *gluon-config-mode-...* base packages (hostname, geolocation and contact info), - as well as the *gluon-config-mode-autoupdater* (when *autoupdater* is in *GLUON_FEATURES*), - and *gluon-config-mode-mesh-vpn* (when *mesh-vpn-fastd* or *mesh-vpn-tunneldigger* are in - *GLUON_FEATURES*) + as well as the *gluon-config-mode-autoupdater* (when *autoupdater* is an enabled feature), + and *gluon-config-mode-mesh-vpn* (when *mesh-vpn-fastd* or *mesh-vpn-tunneldigger* are + enabled features) * web-advanced Includes the *gluon-web-...* base packages (admin, network, WiFi config), - as well as the *gluon-web-autoupdater* (when *autoupdater* is in *GLUON_FEATURES*) - -We recommend to use *GLUON_SITE_PACKAGES* for non-Gluon OpenWrt packages only and -completely rely on *GLUON_FEATURES* for Gluon packages, as it is shown in the -example *site.mk*. + as well as the *gluon-web-autoupdater* (when *autoupdater* is an enabled feature) .. _site-config-mode-texts: