From 2941f492027799e2dc9ce7fd4e540e177d36b8e7 Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Fri, 4 Mar 2016 19:53:37 +0100 Subject: [PATCH] Added "Unmanaged Configurations" instructions to README #16 Removed deprecated "Default Configuration"; closes #16 --- README.rst | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/README.rst b/README.rst index dae4360..8e30d45 100644 --- a/README.rst +++ b/README.rst @@ -58,7 +58,7 @@ UCI configuration options must go in ``/etc/config/openwisp``. - ``uuid``: unique identifier of the router configuration in the controller application - ``key``: key required to download the configuration - ``shared_secret``: shared secret, needed for `Automatic registration`_ -- ``merge_default``: list of default configuration files that must be kept, see `Default Configuration`_ +- ``unmanaged``: list of config sections which won't be overwritten, see `Unmanaged Configurations`_ - ``test_config``: whether a new configuration must be tested before being considered applied, defaults to ``1`` - ``test_script``: custom test script, read more about this feature in `Configuration test`_ @@ -101,39 +101,41 @@ If the default test does not satisfy your needs, you can define your own tests i If the exit code of the executable script is higher than ``0`` the test will be considered failed. -Default Configuration ---------------------- +Unmanaged Configurations +------------------------ -In some cases it is necessary to ensure that some configuration files won't be +In some cases it is necessary to ensure that some configuration sections won't be overwritten by the controller. -These configuration files will be backed up the first time the agent will be able -to contact the controller (which means it will have a basic working configuration.) and -from then on they will be merged in after the configuration is downloaded and applied. - -This also allows you to avoid to define a lot of boilerplate configuration in the controller, -think about LED settings, switch directives, NTP configuration and so on. +This brings two main advantages: -When *openwisp-config* is installed the following packages are listed in ``merge_default``: +- it frees you from defining a lot of boilerplate configuration in the controller, + think about LED settings, switch directives, NTP configuration and so on +- it allows you to define settings that can be managed manually via luci/SSH when needed, + think about a user wanting to change its LAN ip settings from dhcp to a precise static address -* ``system`` -* ``network`` - -Eg:: +These are the default unmanaged settings:: config controller 'http' ... - list merge_default 'system' - list merge_default 'network' + list unmanaged 'system.ntp' + list unmanaged 'system.@led' + list unmanaged 'network.loopback' + list unmanaged 'network.globals' + list unmanaged 'network.lan' + list unmanaged 'network.wan' + list unmanaged 'network.@switch' + list unmanaged 'network.@switch_vlan' ... -The ``system`` config file is treated in a special way: ``hostname`` and ``timezone`` are -removed because they are always automatically generated by the controller. +Note the lines with the `@` sign; that syntax means that any UCI section of that type will be unmanaged. + +All the other lines refer to precise named UCI settings, eg: ``network.lan`` refers to the LAN interface. -Disable default configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Disable Unmanaged Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To disable this feature, just remove all the ``merge_default`` options. +To disable unmanaged configurations simply remove all the ``unmanaged`` options. Compiling openwisp-config -------------------------