Merge pull request #4765 from opensourcerouting/defaults-v2

lib/*: new config defaults system, v2

1 files changed, 134 insertions, 0 deletions

diff --git a/doc/user/basic.rst b/doc/user/basic.rst
index f946c37a7..edcfce45a 100644
--- a/doc/user/basic.rst
+++ b/doc/user/basic.rst
@@ -286,6 +286,9 @@ Below is a sample configuration file for the zebra daemon.
    !
    ! Zebra configuration file
    !
+   frr version 6.0
+   frr defaults traditional
+   !
    hostname Router
    password zebra
    enable password zebra
@@ -307,6 +310,137 @@ If a comment character is not the first character of the word, it's a normal
 character. So in the above example ``!`` will not be regarded as a comment and
 the password is set to ``zebra!password``.
 
+
+Configuration versioning, profiles and upgrade behavior
+-------------------------------------------------------
+
+All |PACKAGE_NAME| daemons share a mechanism to specify a configuration profile
+and version for loading and saving configuration.  Specific configuration
+settings take different default values depending on the selected profile and
+version.
+
+While the profile can be selected by user configuration and will remain over
+upgrades, |PACKAGE_NAME| will always write configurations using its current
+version.  This means that, after upgrading, a ``write file`` may write out a
+slightly different configuration than what was read in.
+
+Since the previous configuration is loaded with its version's defaults, but
+the new configuration is written with the new defaults, any default that
+changed between versions will result in an appropriate configuration entry
+being written out.  **FRRouting configuration is sticky, staying consistent
+over upgrades.**  Changed defaults will only affect new configuration.
+
+Note that the loaded version persists into interactive configuration
+sessions.  Commands executed in an interactive configuration session are
+no different from configuration loaded at startup.  This means that when,
+say, you configure a new BGP peer, the defaults used for configuration
+are the ones selected by the last ``frr version`` command.
+
+.. warning::
+
+   Saving the configuration does not bump the daemons forward to use the new
+   version for their defaults, but restarting them will, since they will then
+   apply the new ``frr version`` command that was written out.  Manually
+   execute the ``frr version`` command in ``show running-config`` to avoid
+   this intermediate state.
+
+This is visible in ``show running-config``:
+
+.. code-block:: frr
+
+   Current configuration:
+   !
+   ! loaded from 6.0
+   frr version 6.1-dev
+   frr defaults traditional
+   !
+
+If you save and then restart with this configuration, the old defaults will
+no longer apply.  Similarly, you could execute ``frr version 6.1-dev``, causing
+the new defaults to apply and the ``loaded from 6.0`` comment to disappear.
+
+
+Profiles
+^^^^^^^^
+
+|PACKAGE_NAME| provides configuration profiles to adapt its default settings
+to various usage scenarios.  Currently, the following profiles are
+implemented:
+
+* ``traditional`` - reflects defaults adhering mostly to IETF standards or
+  common practices in wide-area internet routing.
+* ``datacenter`` - reflects a single administrative domain with intradomain
+  links using aggressive timers.
+
+Your distribution/installation may pre-set a profile through the ``-F`` command
+line option on all daemons.  All daemons must be configured for the same
+profile.  The value specified on the command line is only a pre-set and any
+``frr defaults`` statement in the configuration will take precedence.
+
+.. note::
+
+   The profile must be the same across all daemons.  Mismatches may result
+   in undefined behavior.
+
+You can freely switch between profiles without causing any interruption or
+configuration changes.  All settings remain at their previous values, and
+``show running-configuration`` output will have new output listing the previous
+default values as explicit configuration.  New configuration, e.g. adding a
+BGP peer, will use the new defaults.  To apply the new defaults for existing
+configuration, the previously-invisible old defaults that are now shown must
+be removed from the configuration.
+
+
+Upgrade practices for interactive configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you configure |PACKAGE_NAME| interactively and use the configuration
+writing functionality to make changes persistent, the following
+recommendations apply in regards to upgrades:
+
+1. Skipping major versions should generally work but is still inadvisable.
+   To avoid unneeded issue, upgrade one major version at a time and write
+   out the configuration after each update.
+
+2. After installing a new |PACKAGE_NAME| version, check the configuration
+   for differences against your old configuration.  If any defaults changed
+   that affect your setup, lines may appear or disappear.  If a new line
+   appears, it was previously the default (or not supported) and is now
+   neccessary to retain previous behavior.  If a line disappears, it
+   previously wasn't the default, but now is, so it is no longer necessary.
+
+3. Check the log files for deprecation warnings by using ``grep -i deprecat``.
+
+4. After completing each upgrade, save the configuration and either restart
+   |PACKAGE_NAME| or execute ``frr version <CURRENT>`` to ensure defaults of
+   the new version are fully applied.
+
+
+Upgrade practices for autogenerated configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When using |PACKAGE_NAME| with generated configurations (e.g. Ansible,
+Puppet, etc.), upgrade considerations differ somewhat:
+
+1. Always write out a ``frr version`` statement in the configurations you
+   generate.  This ensures that defaults are applied consistently.
+
+2. Try to not run more distinct versions of |PACKAGE_NAME| than necessary.
+   Each version may need to be checked individually.  If running a mix of
+   older and newer installations, use the oldest version for the
+   ``frr version`` statement.
+
+3. When rolling out upgrades, generate a configuration as usual with the old
+   version identifier and load it.  Check for any differences or deprecation
+   warnings.  If there are differences in the configuration, propagate these
+   back to the configuration generator to minimize relying on actual default
+   values.
+
+4. After the last installation of an old version is removed, change the
+   configuration generation to a newer ``frr version`` as appropriate.  Perform
+   the same checks as when rolling out upgrades.
+
+
 .. _terminal-mode-commands:
 
 Terminal Mode Commands