summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDavid Lamparter <equinox@opensourcerouting.org>2018-10-29 20:26:53 +0100
committerDavid Lamparter <equinox@diac24.net>2019-12-06 15:13:32 +0100
commita048cda55ff5e44e596710d10ef5b7d51fcca899 (patch)
treed975c6e877551d4d137a345f2731788dc77e2596 /doc
parentbuild: apply DFLT_NAME/profiles in init script (diff)
downloadfrr-a048cda55ff5e44e596710d10ef5b7d51fcca899.tar.xz
frr-a048cda55ff5e44e596710d10ef5b7d51fcca899.zip
doc: document defaults mechanism
Signed-off-by: David Lamparter <equinox@diac24.net>
Diffstat (limited to 'doc')
-rw-r--r--doc/user/basic.rst134
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