Configuration

Introduction to the configuration

LibreMesh has a configuration system based on the following principles:

Be simple to configure and understand what configurations are in use in each node
Based on the idea of shared configurations at Community level with possible customizations per Node
Maintainable over time, by firmware updates, adding new nodes in the community, etc.
To be able to make complex configurations.

The configuration system is fundamental to understand the internal functioning of LibreMesh,
however it is not necessary to understand it before starting a LibreMesh network!

Geek free configuration using the FirstBootWizard

If your community wants to deploy a free geek network it is advisable to do so using the lime-app
using the FirstBootWizard. This application simplifies the initial configuration of the nodes and
allows new nodes to join an existing network, all through a user-friendly interface
which does not require prior knowledge of networks.

To use the FirstBootWizard simply follow the steps on the screen when
enter http://thisnode.info

FirstBootWizard splash

However, if your community is a geek community, then you may not want to use the FirstBootWizard.

Once the network is started using the FBW, the participants can perform some
configuration changes through the lime-app.
As needs arise in the community that are not currently met by the
lime-app network participants will be able to learn how to make these changes through ssh
or other tools and following the documentation below.

Configuration for network administrators

LibreMesh uses UCI as its configuration, so does OpenWrt.
UCI is a database that is easily modified both from the command line and by editing the configuration files directly.
All UCI configuration files are located in the /etc/config/ directory.
The LibreMesh configuration files that can be edited for are: /etc/config/lime-node and /etc/config/lime-community
All other configuration files should not be modified.

Configuration levels Community and Node

To help the community maintain its configs, the configuration of the network nodes
is structured hierarchically on 3 levels:

Node, /etc/config/lime-node file
Community, /etc/config/lime-community file
Default, /etc/config/lime-defaults file

Where the configuration made at the Node level takes priority over the Community and the latter has
priority over the Default.
This way, when most of the nodes share a certain characteristic, it is convenient
be configured at the community level and only modified at the Node level in the nodes where that configuration differs.
The Default level contains all configuration values at their default value.

Example

Let’s suppose that we want to set the maximum wireless distance from the 2.4GHz nodes in the community
in 300 meters but in two of the nodes A and B configure it in 1000m. We could do it in the following way:

In the lime-community of all the nodes we would have

config lime 'wifi'
	# other options
	option distance_2ghz '300'

And in the lime-node files of nodes A and B:

config lime 'wifi'
	option distance_2ghz '1000'

Operation

When running the lime-config command the first thing that happens is that the Node levels are processed, Community and Default and the /etc/config/lime-autogen file is generated.
This file is the one that contains the configuration that is really going to be used by libremesh to configure the system.

The resulting configuration files are then written for each package based on /etc/config/lime-autogen.
For the settings to be applied, it is recommended to run reboot after lime-config. While there are faster ways of applying the modifications in certain cases, running reboot is the only way to ensure that all changes were applied.

List of sections and options

The configuration is divided into three main sections: system, network and wifi.

For detailed and updated information on all options see the updated reference
in /docs/lime-example.

System options

The following options in the system section are the most relevant:

config lime system
	option hostname 'LiMe-%M4%M5%M6'
	option domain 'thisnode.info'

We suggest you change the domain thisnode.info to a new subdomain of your community site, for example option domain 'mesh.altermundi.net'. This domain ('mesh.altermundi.net') should be a domain that does not already exist outside the network (i.e. it is a bad idea to use 'altermundi.net'). All clients that get an IP address by DHCP and all network nodes will be assigned a fully qualified domain (e.g. 'lime-ddeeff.mesh.altermundi.net')

General network configurations

Of all the network options, the following are the most relevant

config lime network
	option primary_interface 'eth0'
	option main_ipv4_address '10.%N1.0.0/16'
	option main_ipv6_address '2a00:1508:0a%N1:%N200::/64'
	list protocols ieee80211s
	list protocols lan
	list protocols anygw
	list protocols batadv:%N1

IPv4 configuration: main_ipv4_address

There are four possibilities:
. set a static IP and subnet, e.g. '192.0.2.1/16'
. parameterize with %Mn and %Nn, and configure the subnet, for example '192.%N1.%M5.%M6/16'.
. configure a network address (not a specific IP) to obtain an auto-complete IP
within the network from the bits of the MAC. This also works with masks other than
/24 or /16 as in '192.0.128.0/17'.
. set two different parameters, the first for the subnet and the second for the IP setting,
for example '192.0.128.0/16/17', resulting in a /16 subnet with broadcast domain (192.0.0.0/16) but with the IP of the node
calculated in a /17 range (from 192.0.128.0 to 192.0.255.254).

IPv6 configuration: main_ipv6_address

The configuration is similar to the max_ipv4_address. If autocompletion is used as a maximum, it completes
the last 24 bits, so in this case it is not useful to use a range greater than /104.

List of protocols

List of protocols configured by LibreMesh. Some of these require the installation of your related package lime-proto….
Note that because of the way the list (ICU lists) work, configuring some protocols causes the list to be rewritten
The complete set of protocols that is in the values for Default.
Don’t worry if there are more protocols defined than you really need: only the protocols corresponding to
installed packages will be used. So for example if the package lime-proto-olsr is not installed then by more
that the protocol olsr is listed, it will not be used.

General WiFi settings

Of all the network options, the following are the most relevant

config lime wifi
	option channel_2ghz '11'
	list channel_5ghz '48'
	list channel_5ghz '157'
	option distance_2ghz '100'
	option distance_5ghz '1000'
	list modes 'ap'
	list modes 'apname'
	list modes 'ieee80211s'
	option ap_ssid 'LibreMesh.org'
	option apname_ssid 'LibreMesh.org/%H'
	option country 'ES'

Country setting: country code

The default country code is not specified (so the default is usually US),
but we strongly recommend that you set it up. If the network is in Spain then the configuration is
option country 'ES', which also allows the use of channel 13 (permitted in Spain) which is otherwise restricted.

distance

The distance parameter indicates the maximum distance the other nodes or clients can be.
A very large value decreases the performance but a lower value than necessary results in a
connection with a very very bad performance (you often see duplicate packets (DUPs) when pinging).

wifi options

Any options in the form <mode>_<option> are copied directly to /etc/config/wireless (without the <mode>_ prefix).

wifi Access point password

To secure the AP and APname interfaces with WPA2-PSK, add the key 'MySecurePassword' and
encryption 'psk2' options. For an example see in /docs/lime-example.

Specific interface configurations

Changing the above options allows us to have a configuration of the whole system.

In cases where different network interfaces must have different configurations, see /docs/lime-example.

Parameterisable options

Some options are parameterizable using a set of special characters that will be
replaced by node-specific information.

MAC bytes %Mn refers to the n byte of the MAC address of the main interface.
For example from the MAC CA:FF:EE:BA:BB:EE %M1 will be replaced by CA (the first byte of the MAC)
and %M4 by BA (the fourth byte of the MAC).
Network Identifier %Nn refers to the n byte of the cloud identifier which is a hash that is calculated
from the SSID of the AP (taken from the content of option ap_ssid …).
Hostname %H refers to the hostname of the node.

Setting up things not foreseen in LibreMesh

If you want to make a configuration for which LibreMesh does not have an option then
it is necessary to use generic configs and _lime-assets.

generic_uci_config

Other files can be configured in /etc/config/ from the lime configuration files using
generic configurations.

Example to configure the location of /etc/config/libremap from /etc/config/lime-community:

config generic_uci_config libremap
    list uci_set "libremap.settings=libremap"
    list uci_set "libremap.settings.community=our.libre.org"
    list uci_set "libremap.settings.community_lat=-200.123"
    list uci_set "libremap.settings.community_lon=500.9"

lime-assets

The lime-assets are files that allow you to make special configurations. These files
are divided into two groups, those of the node and those of the community. The idea is that the assets of the community
are shared by all the nodes and allow configurations that are necessary in all the nodes.
On the other hand, the files (assets) of the node are designed to make specific configurations in the node.

copy_asset

If a file is required to be present on the file system you can use the copy_asset directive.
copy_asset copies a file from the assets directory to a path defined by the dst option.

For example to configure the collectd program for your community you can create a collectd.conf file.
in /etc/lime-assets/community/collectd.conf and use it by defining the following settings in the file
lime-community in the following way:

config copy_asset collectd
   option asset 'community/collectd.conf'
   option dst '/etc/collectd.conf'

run_asset

To configure LibreMesh to run a script you should use the run_asset option.
Use this configuration method as a last resort if the other methods are not sufficient.

Run_asset` runs a script from the assets directory. The execution can be in the first boot
(that is, when it starts after a firmware upgrade) using ATFIRSTBOOT or in every
once you reconfigure LibreMesh (when you run lime-config) using ATCONFIG.

For example to run the script myscript.sh saved in /etc/lime-assets/community/myscript.sh
on the first boot:

config run_asset a_test_script
    option asset 'community/myscript.sh'
    option when 'ATFIRSTBOOT'

This configuration method replaces the functionality of the uci-defaults scripts.