Settings

Configuration Options

UCI configuration options must go in /etc/config/openwisp.

  • url: URL of controller, e.g.: https://demo.openwisp.io

  • interval: time in seconds between checks for changes to the configuration, defaults to 120

  • management_interval: time in seconds between the management ip discovery attempts, defaults to $interval/12

  • registration_interval: time in seconds between the registration attempts, defaults to $interval/4

  • verify_ssl: whether SSL verification must be performed or not, defaults to 1

  • shared_secret: shared secret, needed for Automatic registration

  • consistent_key: whether Consistent Key Generation is enabled or not, defaults to 1

  • merge_config: whether Merge Configuration is enabled or not, defaults to 1

  • tags: template tags to use during registration, multiple tags separated by space can be used, for more information see Template Tags

  • test_config: whether a new configuration must be tested before being considered applied, defaults to 1

  • test_retries: maximum number of retries when doing the default configuration test, defaults to 3

  • test_script: custom test script, read more about this feature in Configuration Test

  • uuid: unique identifier of the router configuration in the controller application

  • key: key required to download the configuration

  • hardware_id_script: custom script to read out a hardware id (e.g. a serial number), read more about this feature in Hardware ID

  • hardware_id_key: whether to use the hardware id for key generation or not, defaults to 1

  • bootup_delay: maximum value in seconds of a random delay after boot, defaults to 10, see Boot Up Delay

  • unmanaged: list of config sections which won't be overwritten, see Unmanaged Configurations

  • capath: value passed to curl --capath argument, by default is empty; see also curl capath argument

  • cacert: value passed to curl --cacert argument, by default is empty; see also curl cacert argument

  • connect_timeout: value passed to curl --connect-timeout argument, defaults to 15; see curl connect-timeout argument

  • max_time: value passed to curl --max-time argument, defaults to 30; see curl max-time argument

  • mac_interface: the interface from which the MAC address is taken when performing automatic registration, defaults to eth0

  • management_interface: management interface name (both openwrt UCI names and linux interface names are supported), it's used to collect the management interface ip address and send this information to the OpenWISP server, for more information please read how to make sure OpenWISP can reach your devices

  • default_hostname: if your firmware has a custom default hostname, you can use this configuration option so the agent can recognize it during registration and replicate the standard behavior (new device will be named after its mac address, to avoid having many new devices with the same name), the possible options are to either set this to the value of the default hostname used by your firmware, or set it to * to always force to register new devices using their mac address as their name (this last option is useful if you have a firmware which can work on different hardware models and each model has a different default hostname)

  • pre_reload_hook: path to custom executable script, see pre-reload-hook

  • post_reload_hook: path to custom executable script, see post-reload-hook

  • post_reload_delay: delay in seconds to wait before the post-reload-hook and any configuration test, defaults to 5

  • post_registration_hook: path to custom executable script, see post-registration-hook

  • respawn_threshold: time in seconds used as procd respawn threshold, defaults to 3600

  • respawn_timeout: time in seconds used as procd respawn timeout, defaults to 5

  • respawn_retry: number of procd respawn retries (use 0 for infinity), defaults to 5

  • checksum_max_retries: maximum number of retries for checksum requests which fail with 404, defaults to 5, after these failures the agent will assume the device has been deleted from OpenWISP Controller and will exit; please keep in mind that due to respawn_retry, procd will try to respawn the agent after it exits, so the total number of attempts which will be tried has to be calculated as: checksum_max_retries * respawn_retry

  • checksum_retry_delay: time in seconds between retries, defaults to 6

Merge Configuration

By default the remote configuration is merged with the local one. This has several advantages:

  • less boilerplate configuration stored in the remote controller

  • local users can change local configurations without fear of losing their changes

It is possible to turn this feature off by setting merge_config to 0 in /etc/config/openwisp.

Details about the merging behavior:

  • if a configuration option or list is present both in the remote configuration and in the local configuration, the remote configurations will overwrite the local ones

  • configuration options that are present in the local configuration but are not present in the remote configuration will be retained

  • configuration files that were present in the local configuration and are replaced by the remote configuration are backed up and eventually restored if the modifications are removed from the controller

Configuration Test

When a new configuration is downloaded, the agent will first backup the current running configuration, then it will try to apply the new one and perform a basic test, which consists in trying to contact the controller again;

If the test succeeds, the configuration is considered applied and the backup is deleted.

If the test fails, the backup is restored and the agent will log the failure via syslog (see Debugging for more information on auditing logs).

Disable Testing

To disable this feature, set the test_config option to 0, then reload/restart openwisp-config.

Define Custom Tests

If the default test does not satisfy your needs, you can define your own tests in an executable script and indicate the path to this script in the test_script config option.

If the exit code of the executable script is higher than 0 the test will be considered failed.

Hardware ID

It is possible to use a unique hardware id for device identification, for example a serial number.

If hardware_id_script contains the path to an executable script, it will be used to read out the hardware id from the device. The hardware id will then be sent to the controller when the device is registered.

If the above configuration option is set then the hardware id will also be used for generating the device key, instead of the mac address. If you use a hardware id script but prefer to use the mac address for key generation then set hardware_id_key to 0.

See also the related hardware ID settings in OpenWISP Controller.

Boot Up Delay

The option bootup_delay is used to delay the initialization of the agent for a random amount of seconds after the device boots.

The value specified in this option represents the maximum value of the range of possible random values, the minimum value being 0.

The default value of this option is 10, meaning that the initialization of the agent will be delayed for a random number of seconds, this random number being comprised between 0 and 10.

This feature is used to spread the load on the OpenWISP server when a large amount of devices boot at the same time after a blackout.

Large OpenWISP installations may want to increase this value.

Hooks

Warning

Hooks are deprecated in favor of Hotplug events.

Below are described the available hooks in openwisp-config.

pre-reload-hook

Defaults to /etc/openwisp/pre-reload-hook; the hook is not called if the path does not point to an executable script file.

This hook is called each time openwisp-config applies a configuration, but before services are reloaded, more precisely in these situations:

  • after a new remote configuration is downloaded and applied

  • after a configuration test failed (see Configuration Test) and a previous backup is restored

You can use this hook to perform custom actions before services are reloaded, e.g.: to perform auto-configuration with LibreMesh.

Example configuration:

config controller 'http'
        ...
        option pre_reload_hook '/usr/sbin/my-pre-reload-hook'
        ...

Complete example:

# set hook in configuration
uci set openwisp.http.pre_reload_hook='/usr/sbin/my-pre-reload-hook'
uci commit openwisp
# create hook script
cat <<EOF > /usr/sbin/my-pre-reload-hook
#!/bin/sh
# put your custom operations here
EOF
# make script executable
chmod +x /usr/sbin/my-pre-reload-hook
# reload openwisp-config by using procd's convenient utility
reload_config

post-reload-hook

Defaults to /etc/openwisp/post-reload-hook; the hook is not called if the path does not point to an executable script file.

Same as pre_reload_hook but with the difference that this hook is called after the configuration services have been reloaded.

post-registration-hook

Defaults to /etc/openwisp/post-registration-hook;

Path to an executable script that will be called after the registration is completed.

Unmanaged Configurations

In some cases it could be necessary to ensure that some configuration sections won't be overwritten by the controller.

These settings are called "unmanaged", in the sense that they are not managed remotely. In the default configuration of openwisp-config there are no unmanaged settings.

Example unmanaged settings:

config controller 'http'
        ...
        list unmanaged 'system.@led'
        list unmanaged 'network.loopback'
        list unmanaged 'network.@switch'
        list unmanaged 'network.@switch_vlan'
        ...

Note the lines with the @ sign; this syntax means any UCI section of the specified type will be unmanaged.

In the previous example, the loopback interface, all led settings, all switch and switch_vlan directives will never be overwritten by the remote configuration and will only be editable via SSH or via the web interface.