proxmox-mirrors/mirror_frr
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_frr synced 2026-01-06 01:29:31 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: document defaults mechanism

Browse Source 
Signed-off-by: David Lamparter <equinox@diac24.net>
This commit is contained in:
David Lamparter 2018-10-29 20:26:53 +01:00 committed by David Lamparter
parent 684959068c
commit a048cda55f
1 changed files with 134 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
doc/user/basic.rst
View File

@ -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