802.11s - The Mesh11sd Project

Mesh11sd is a dynamic parameter configuration daemon for 802.11s mesh networks.
It was originally designed to leverage 802.11s mesh networking at Captive Portal venues but is in fact a general purpose dynamic configuration daemon for 802.11s mesh network parameters using standard UCI configuration options.

This is the open source version and it enables easy and automated mesh network operation with multiple mesh nodes.
It does not require a Captive Portal to be running.

For rapid deployment of an 802.11s mesh network, see:

802.11s Rapid Deployment

For some background information on 802.11s mesh networking, see:

802.11s Wireless Mesh Networking

A mesh network is a multi point to multi point layer 2 mac-routing backhaul used to interconnect mesh peers. Mesh peers are generally non-user devices, such as routers, access points, CPEs etc..

A normal user device, such as a phone, tablet, laptop etc., cannot connect to a mesh network. Instead, connection is achieved via a mesh gateway, a special type of mesh peer.

If you are looking for a solution to enable your user devices to seamlessly roam from one access point to another in your home, you need 802.11r (roaming), not 802.11s.

It is unfortunate that some manufacturers have used the word “Mesh” for marketing purposes to describe their non-standard, closed source, proprietary “roaming” functionality and this causes great confusion to many people when they enter the world of international standards and open source firmware for their network infrastructure.

1. The accepted standard for mesh networks is ieee802.11s.
2. The accepted standard for fast roaming of user devices is ieee802.11r.

These are two completely unrelated standards.

For an installation guide, see https://github.com/openNDS/mesh11sd/tree/master#3-manual-or-auto-configuration

WARNING - It is not recommended to upgrade to v4.0.0 or or higher, from a lower version as the configuration is very different.
If upgrading, remove the old version, delete the /etc/config/mesh11sd file and then remove all mesh configuration from /etc/config/wireless before installing the new version.

From version 4.0.0 onwards, the default mode after install is for manual configuration.

If you have not done any manual mesh configuration, mesh11sd will do nothing and wait in the background for you to do so.

Switching on Auto Configuration is a simple task and is recommended if you are starting from a basic OpenWrt reflash.
ie you have not done any configuration after flashing the image.

WARNING: If you have done ANY mesh configuration manually, you might cause a soft-brick condition.
Pre-configuring before enabling auto_config is for advanced users only. Make sure you know what you are doing!

If the mesh network interface is defined in the wireless configuration file, mesh11sd will attempt to use it, but be warned, this may have very unpredictable results and is not normally recommended.

To quickly enable auto config mode, execute the following commands:

  service mesh11sd stop
  uci set mesh11sd.setup.auto_config='1'
  uci commit mesh11sd
  service mesh11sd start

By default in auto_config mode, Mesh11sd checks the wireless configuration for mesh options in addition to checking for a mesh capable version of the wpad package.
If a suitable version of wpad is installed (eg wpad-mesh-mbedtls), mesh11sd adds options to the wireless configuration to bring up 802.11s mesh interfaces, if they are not already present.

Note: Mesh11sd uses the uci utility to manage dynamic configuration changes, both autoconfig and run time.

The autoconfiguration is done on every startup and is not a one off process.
In normal operation, config changes are not written to the config files in /etc/config but are kept in volatile storage by way of the uci utility.

Directly editing a config file might possibly break something, all changes should be done with the uci utility.

From version 3.1.0 onwards, non-mesh peer links are supported.
Bridge loops are blocked and mesh links are given higher priority in the spanning tree.
This is intended only to be used to connect remote segments of the backhaul that are out of useable radio range.
Note:
The kmod-nft-bridge package must be installed for support of non-mesh backhaul segments

Mesh11sd allows all mesh parameters that are supported by the wireless driver to be set in either the wireless or the mesh11sd uci config file.
Settings take effect immediately without having to restart the wireless network and the default settings give rapid and reliable layer 2 mesh convergence.

The settings in the uci wireless config are acted upon at boot time or when the wireless network is restarted and are implemented before the mesh interface has reached an active state.
In general, mesh configuration parameters can only be set after the mesh interface becomes active. Without mesh11sd, many mesh parameters cannot be set in the uci wireless config file as the mesh interface must be up before the parameters can be set.
Some of those that are supported, would fail to be implemented when the network is (re)started resulting in errors or dropped nodes.

Parameters should be set in the mesh11sd config and these settings will override any mesh parameter settings in the wireless config.

Depending on the wireless drivers/hardware, mesh parameters set in the wireless config may not only fail on startup, but may also generate errors and in the worst case may cause the wireless driver to crash.

For this reason it is recommended that all mesh parameter options are removed from the wireless config and placed instead into the mesh11sd config.

All initial configuration of the mesh interface must be done manually.
The Default mesh11sd configuration file will be effectively empty with all options commented out:

config mesh11sd 'setup'
	###########################################################################################
	# debuglevel (optional)
	# Sets the debuglevel
	# Default: 1 (Notification)
	# Options are 0, silent, 1 notification, 2 info and 3 debug
	#
	#option debuglevel '2'

	###########################################################################################
	# enabled (optional)
	# Enables or disables the mesh11sd daemon
	# Default: 1 (enabled)
	#
	# Set to 0 to disable
	#
	#option enabled '1'

	###########################################################################################
	# checkinterval (optional)
	# Sets the dynamic configuration checkinterval in seconds
	# Default: 10 (seconds)
	#
	#option checkinterval '15'

	###########################################################################################
	# portal_detect (optional)
	# Ignored if auto_config is disabled.
	#
	# Default 1
	#
	# Possible values:
	#  0  - Force Portal mode regardless of an upstream connection.
	#  1  - Detect if the meshnode is a portal, meaning it has an upstream wan link.
	# 	If the upstream link is active, the router hosting the meshnode will serve ipv4 dhcp into the mesh network.
	# 	If the upstream link is not connected, dhcp will be disabled and the meshnode will function as a layer 2 bridge on the mesh network.
	#  2  - Force peer mode, ignoring any upstream wan connection.
	#  3  - Force CPE mode (Customer Premises Equipment)
	#  	This is a peer mode but treats the mesh backhaul as an upstream wan connection.
	#  	A nat routed lan is created with its own ipv4 subnet.
	#
	# Has no effect if auto_config is disabled.
	#
	#option portal_detect '0'

	###########################################################################################
	# portal_channel (optional) Applies to 2.4 GHz band only
	#
	# If portal_detect is disabled (0), portal_channel can be set to:
	# 1. auto - a channel is auto selected
	# 2. default - the channel defined in /etc/config/wireless is used
	# 3. A valid 2.4 GHz channel (1 to 13, depending on the country setting)
	#
	# Default: default
	#
	# All mesh peer and mesh gate nodes will autonomously track the mesh portal channel
	# regardless of the configured auto_mesh_band
	# 
	#option portal_channel 'auto'
	# or
	#option portal_channel '4'

	###########################################################################################
	# channel_tracking_checkinterval (optional)
	# The minimum interval in seconds after which channel tracking begins on peer nodes
	# Values less than checkinterval are ignored
	#
	# Default: 30 seconds
	#
	# Example:
	#option channel_tracking_checkinterval '60'

	###########################################################################################
	# portal_detect_threshold (optional)
	#
	# This is the portal detect watchdog.
	#
	# The number of checkintervals before the portal detect watchdog begins actions to (re)establish a reconnection to a portal.
	#
	# Default 0 (watchdog does nothing)
	# Ignored if auto_config is disabled.
	#
	# Each time the peer node fails to detect the portal, a counter is incremented.
	# If the threshold is reached, the node will take various actions in an attempt to find the portal.
	# If the portal is still not detected, the watchdog will reboot the peer node.
	#
	# Example - Set threshold to 10 chekintervals:
	#option portal_detect_threshold '10'

	###########################################################################################
	# mesh_path_cost (optional)
	# sets the STP cost of the mesh network
	# Default: 10
	# Can be set to any value from 0 to 65534
	# Setting to 0 disables STP
	#
	# Example:
	#option mesh_path_cost '100'

	###########################################################################################
	# interface_timeout (optional)
	# Sets the interface timeout interval in seconds
	# Default: 10 (seconds)
	#
	#option interface_timeout '10'

	###########################################################################################
	# auto_config (optional)
	# Enables autonomous dynamic mesh configuration.
	# Auto configure mesh interfaces in the wireless configuration.
	# Default 0 (disabled). Set to 1 to enable.
	#
	#option auto_config '1'
	#
	# The following options are recommended when auto_config is set to 0 (disabled)
	# (When auto_config is enabled, these options are dynamically set if and when required)
	#
	# A Portal Node: having an ip routed connectivity to an upstream feed [eg an Internet feed]
	#	option mesh_fwding '1'
	#
	#	option mesh_connected_to_as '1' [if link is up]
	# or
	#	option mesh_connected_to_as '0' [if link is down]
	#
	#	option mesh_hwmp_rootmode '4'
	#
	#	option mesh_connected_to_gate '1' [if it also supports an AP]
	# or
	#	option mesh_connected_to_gate '0' [if it does not support an AP]
	#
	#	option mesh_gate_announcements '1'  [if it also supports an AP]
	# or
	#	option mesh_gate_announcements '0'  [if it does not support an AP]
	#
	# A Gateway Node: offering both backhaul and downstream infrastructure connectivity
	#	option mesh_fwding '1'
	#	option mesh_connected_to_as '0'
	#	option mesh_hwmp_rootmode '2'
	#	option mesh_connected_to_gate '1'
	#	option mesh_gate_announcements '1'
	#
	# A Gateway Leech Node: a Gateway that doesn't contribute to the mesh backhaul, it just leeches off of it
	#	option mesh_fwding '0'
	#	option mesh_connected_to_as '0'
	#	option mesh_hwmp_rootmode '0'
	#	option mesh_connected_to_gate '1'
	#	option mesh_gate_announcements '0'
	#
	# A Peer Node: connected to mesh backhaul but no downstream infrastructure
	#	option mesh_fwding '1'
	#	option mesh_connected_to_as '0'
	#	option mesh_hwmp_rootmode '2'
	#	option mesh_connected_to_gate '0'
	#	option mesh_gate_announcements '0'

	###########################################################################################
	# auto_mesh_id (optional)
	# Configure the mesh_id of the wireless interface(s) when auto_config is enabled
	# Default --__
	#
	# This string will be hashed to produce a secure mesh id
	# If set, it must also be set to the same value on every mesh node
	#
	#option auto_mesh_id 'MyMeshID'

	###########################################################################################
	# auto_mesh_band (optional)
	# Configure the band to use for the mesh network
	# Valid values: 2g, 2g40, 5g, 6g, 60g
	# Default 2g40
	#
	# If set, it must also be set to the same value on every mesh node
	#
	# All mesh peer and mesh gate nodes will autonomously track the mesh portal channel
	# regardless of the configured auto_mesh_band
	#
	#option auto_mesh_band '5g'

	###########################################################################################
	# auto_mesh_key (optional)
	# Defaults to a sha256 key to be automatically used on all members of this mesh when auto_config is enabled
	# Generates a secure sha256 key from the value set in this option.
	#
	# If set, it must also be set to the same value on every mesh node
	#
	#option auto_mesh_key 'MySecretKey'

	###########################################################################################
	# auto_mesh_network (optional)
	# Set the network the mesh interface will bind to (eg lan, guestlan etc) when auto_config is enabled.
	# Network wan is not accepted
	# Default lan
	#
	#option auto_mesh_network 'guest'

	###########################################################################################
	# mesh_basename (optional)
	# The first 4 characters after non alphanumerics are removed are used as the mesh_basename
	# The mesh_basename is used to construct a unique mesh interface name of the form m-xxxx-n
	# Default: 11s
	# Results in ifname=m-11s-0 for the first mesh interface
	# Example: link
	# Results in ifname=m-link-0
	#
	#option mesh_basename 'link'

	###########################################################################################
	# mesh_gate_encryption (optional)
	# Determines whether this node's gate will be a encrypted
	#
	# Default: 0 (disabled)
	# Set to 0 (none/owe-transition), 1 (sae, aka wpa3), 2 (sae-mixed, aka wpa2/wpa3), 3 (psk2, aka wpa2)
	# or 4 (Opportunistic Wireless Encryption - owe)
	#
	# Example - enable psk2 encryption
	#option mesh_gate_encryption '3'

	###########################################################################################
	# mesh_gate_key (optional)
	# Determines the encryption key for this node's gate.
	#
	# Default: not set (encryption disabled)
	# Set to a secret string value to use for encrypting the node's gate
	# Ignored if mesh_gate_encryption is set to 0 or 4
	#
	# Example - set a key string
	#option mesh_gate_key 'mysecretencryptionkey'

	###########################################################################################
	# mesh_gate_enable (optional)
	# Determines whether this node will be a gate
	#
	# Default: 1 (enabled)
	# Set to 0 to disable (turns off the node's gate interface ie its access point and SSID)
	#
	#option mesh_gate_enable '0'

	###########################################################################################
	# mesh_leechmode_enable (optional)
	# Determines whether this node will be a gate only leech node
	# A gate only leech node acts as an access point with a mesh backhaul connection, but does not contribute to the mesh
	#
	# This is useful when a node is well within the coverage of 2 or more peer nodes,
	# as otherwise it could create unstable multi hop paths within the backhaul.
	#
	# Default: 0 (disabled)
	# Set to 1 to enable (turns off the node's mesh forwarding and HWMP mac-routing)
	#
	# Example - enable leach mode
	#option mesh_leechmode_enable '1'

	###########################################################################################
	# txpower (optional)
	# Set the mesh radio transmit power in dBm.

	# Default - use driver default or value set in wireless config
	# Values outside the limits defined by the regulatory domain will be ignored
	#
	# Example - Set tx power to 15 dBm:
	#option txpower '15'

	###########################################################################################
	# ssid_suffix_enable (optional)
	# Add a 4 digit suffix to the ssid
	# The 4 digits are the last 4 digits of the mac address of the mesh interface
	# Default 1 (enabled)
	#
	#option ssid_suffix_enable '0'

	###########################################################################################
	# watchdog_nonvolatile_log (optional - FOR DEBUGGING PURPOSES ONLY)
	#
	# This enables logging of the portal detect watchdog actions in non-volatile storage.
	# The log file /mesh11sd_log/mesh11sd.log is created
	#
	# ##########WARNING##########
	# THIS OPTION IS FOR PORTAL DETECT WATCHDOG DEBUGGING PURPOSES ONLY
	# IF LEFT ENABLED FOR A LENGTH OF TIME IT MAY CAUSE NONE REPAIRABLE FLASH MEMORY WEAR AND USE UP FREE STORAGE SPACE
	# DISABLE IMMEDIATELY AFTER DEBUGGING OPERATIONS ARE COMPLETE
	# ##########WARNING##########

	###########################################################################################
	# mesh_path_stabilisation (optional)
	#
	# This enables mesh path stabilisation, preventing multi hop path changes due to multipath signal strength jitter
	#
	# Default: 1 (enabled)
	#
	# To disable, set to zero:
	#option mesh_path_stabilisation '0'

config mesh11sd 'mesh_params'
	# A minimum set of parameters is automatically set for initial startup and do not have to be configured here
	#
	# Any mesh parameter supported by the wireless driver can be specified here
	# and will be dynamically set and continuously checked every "checkinterval"
	# 
	# Examples:
	#option mesh_rssi_threshold '-70'
	#option mesh_max_peer_links '20'

	#
	# The command: "mesh11sd status" gives a full list of supported parameters.

For auto configuration, the setup option auto_config must be set to 1:

service mesh11sd stop
uci set mesh11sd.setup.auto_config='1'
uci commit mesh11sd
service mesh11sd start

No initial configuration is required.

A full list of setup options can be seen here: https://github.com/openNDS/mesh11sd/tree/master#6-setup-options

For a publicly accessible mesh network it is recommended that auto_mesh_id and auto_mesh_key are set to your own custom values, making sure all nodes have the same configured values.
Mesh11sd will generate hashed values for both auto_mesh_id and auto_mesh_key.

Example:

service mesh11sd stop
uci set mesh11sd.setup.auto_mesh_id='secret_meshid'
uci set mesh11sd.setup.auto_mesh_key='secret_encryption_hash_seed'
uci commit mesh11sd
service mesh11sd start

Set the debuglevel to 2

service mesh11sd stop
uci set mesh11sd.setup.debuglevel='2'
uci commit mesh11sd
service mesh11sd start

The operating channel can be set for the entire mesh network, by setting option portal_channel on the portal node (the node with the upstream wan connection ie Internet feed).

Set the mesh channel to channel 5

service mesh11sd stop
uci set mesh11sd.setup.portal_channel='5'
uci commit mesh11sd
service mesh11sd start

The portal node will change to the new channel as mesh11sd starts. The channel change will rapidly propagate out into the mesh, node by node.
Note: This setting is ignored if the meshnode is not in portal mode.

A full list of mesh parameter options can be seen here: https://github.com/openNDS/mesh11sd/tree/master#7-mesh-parameter-options

Basic mesh parameters are automatically set and do not need to be set in the default config file.
These basic parameters ensure the mesh interface will be able to either seed a new mesh or join an existing one of the same mesh id.
A list of parameters and their current values can also be viewed at any time by running the command:

mesh11sd status

Example: Set mesh_max_peer_links to 25

uci set mesh11sd.mesh_params.mesh_max_peer_links='25'

The mesh_max_peer_links will be set immediately to this new value and will remain set until changed again or a reboot occurs.

Mesh11sd is an OpenWrt service daemon and runs continuously in the background. It does however also have a CLI interface.

A full description of the command line interface can be seen here:

https://github.com/openNDS/mesh11sd/tree/master#8-command-line-interface

Create an issue on the Github repository at:
https://github.com/openNDS/mesh11sd/issues