doc: update config file doc for integrated requirement

Signed-off-by: Christian Hopps <[email protected]>
FRRouting · Jan 12, 2024 · a268390 · a268390
1 parent d2c275a
commit a268390
Show file tree

Hide file tree

Showing 20 changed files with 88 additions and 102 deletions.
diff --git a/doc/user/babeld.rst b/doc/user/babeld.rst
@@ -26,8 +26,7 @@ The *zebra* daemon must be running before *babeld* is
 invoked. Also, if *zebra* is restarted then *babeld*
 must be too.
 
-Configuration of *babeld* is done in its configuration file
-:file:`babeld.conf`.
+.. include:: config-include.rst
 
 .. _babel-configuration:
 

diff --git a/doc/user/basic.rst b/doc/user/basic.rst
@@ -11,45 +11,22 @@ The following sections discuss commands common to all the routing daemons.
 Config Commands
 ===============
 
-
-
-
-
-In a config file, you can write the debugging options, a vty's password,
+In the config file, you can write the debugging options, a vty's password,
 routing daemon configurations, a log file name, and so forth. This information
 forms the initial command set for a routing beast as it is starting.
 
-Config files are generally found in |INSTALL_PREFIX_ETC|.
-
-Config Methods
---------------
-
-There are two ways of configuring FRR.
-
-Traditionally each of the daemons had its own config file. The daemon name plus
-``.conf`` was the default config file name. For example, zebra's default config
-file was :file:`zebra.conf`. This method is deprecated.
-
-Because of the amount of config files this creates, and the tendency of one
-daemon to rely on others for certain functionality, most deployments now use
-"integrated" configuration. In this setup all configuration goes into a single
-file, typically :file:`/etc/frr/frr.conf`. When starting up FRR using an init
-script or systemd, ``vtysh`` is invoked to read the config file and send the
-appropriate portions to only the daemons interested in them. Running
-configuration updates are persisted back to this single file using ``vtysh``.
-This is the recommended method. To use this method, add the following line to
-:file:`/etc/frr/vtysh.conf`:
-
-.. code-block:: frr
-
-   service integrated-vtysh-config
+.. _config-file:
 
-If you installed from source or used a package, this is probably already
-present.
+Integrated Config File
+----------------------
 
-If desired, you can specify a config file using the :option:`-f` or
-:option:`--config_file` options when starting a daemon.
+FRR uses a single configuration file located in |INSTALL_PREFIX_ETC|/frr.conf.
+When FRR is started using an init script or ``systemd``, ``vtysh`` is invoked to
+read the config file and send the appropriate portions to only the daemons
+interested in them. Running configuration updates are persisted back to this
+single file using ``vtysh`` as well.
 
+.. include:: prior-config-files.rst
 
 .. _basic-config-commands:
 

diff --git a/doc/user/bfd.rst b/doc/user/bfd.rst
@@ -27,6 +27,8 @@ This document will focus on the later implementation: *bfdd*.
 Starting BFD
 ============
 
+.. include:: config-include.rst
+
 *bfdd* default configuration file is :file:`bfdd.conf`. *bfdd* searches
 the current directory first then |INSTALL_PREFIX_ETC|/bfdd.conf. All of
 *bfdd*'s command must be configured in :file:`bfdd.conf`.

diff --git a/doc/user/bgp.rst b/doc/user/bgp.rst
@@ -14,10 +14,7 @@ interdomain routing protocol. BGP-4 is described in :rfc:`1771` and updated by
 Starting BGP
 ============
 
-The default configuration file of *bgpd* is :file:`bgpd.conf`. *bgpd* searches
-the current directory first, followed by |INSTALL_PREFIX_ETC|/bgpd.conf. All of
-*bgpd*'s commands must be configured in :file:`bgpd.conf` when the integrated
-config is not being used.
+.. include:: config-include.rst
 
 *bgpd* specific invocation options are described below. Common options may also
 be specified (:ref:`common-invocation-options`).

diff --git a/doc/user/config-include.rst b/doc/user/config-include.rst
@@ -0,0 +1,12 @@
+..
+.. January 12 2024, Christian Hopps <[email protected]>
+..
+.. Copyright (c) 2024, LabN Consulting, L.L.C.
+..
+..
+
+Configuration for the daemon should be saved in the FRR integrated configuration
+file located in |INSTALL_PREFIX_ETC|/frr.conf, see :ref:`config-file` for more
+information on system configuration.
+
+.. include:: prior-config-files.rst
diff --git a/doc/user/eigrpd.rst b/doc/user/eigrpd.rst
@@ -24,21 +24,17 @@ known topology.
 Starting and Stopping eigrpd
 ============================
 
-The default configuration file name of *eigrpd*'s is :file:`eigrpd.conf`. When
-invocation *eigrpd* searches directory |INSTALL_PREFIX_ETC|. If
-:file:`eigrpd.conf` is not there next search current directory. If an
-integrated config is specified configuration is written into :file:`frr.conf`.
+.. include:: config-include.rst
 
-The EIGRP protocol requires interface information maintained by *zebra* daemon.
-So running *zebra* is mandatory to run *eigrpd*. Thus minimum sequence for
-running EIGRP is:
+If starting daemons by hand then please note, the EIGRP protocol requires
+interface information maintained by *zebra* daemon. So running *zebra* is
+mandatory to run *eigrpd*. Thus minimum sequence for running EIGRP is:
 
 ::
 
   # zebra -d
   # eigrpd -d
 
-
 Please note that *zebra* must be invoked before *eigrpd*.
 
 To stop *eigrpd*, please use::

diff --git a/doc/user/isisd.rst b/doc/user/isisd.rst
@@ -22,8 +22,7 @@ interface information from *zebra* in order to function. Therefore *zebra* must
 be running before invoking *isisd*. Also, if *zebra* is restarted then *isisd*
 must be too.
 
-Like other daemons, *isisd* configuration is done in :abbr:`ISIS` specific
-configuration file :file:`isisd.conf`.
+.. include:: config-include.rst
 
 .. _isis-router:
 

diff --git a/doc/user/ldpd.rst b/doc/user/ldpd.rst
@@ -32,9 +32,7 @@ options (:ref:`common-invocation-options`).
 
 The *zebra* daemon must be running before *ldpd* is invoked.
 
-Configuration of *ldpd* is done in its configuration file
-:file:`ldpd.conf`.
-
+.. include:: config-include.rst
 
 .. _understanding-ldp:
 

diff --git a/doc/user/ospf6d.rst b/doc/user/ospf6d.rst
@@ -9,8 +9,13 @@ described in :rfc:`2740`.
 
 .. _ospf6-router:
 
-OSPF6 router
-============
+Configuring OSPF6
+*****************
+
+.. include:: config-include.rst
+
+Configuration Commands
+======================
 
 .. clicmd:: router ospf6 [vrf NAME]
 

diff --git a/doc/user/ospfd.rst b/doc/user/ospfd.rst
@@ -32,8 +32,7 @@ Configuring OSPF
 Therefore *zebra* must be running before invoking *ospfd*. Also, if *zebra* is
 restarted then *ospfd* must be too.
 
-Like other daemons, *ospfd* configuration is done in :abbr:`OSPF` specific
-configuration file :file:`ospfd.conf` when the integrated config is not used.
+.. include:: config-include.rst
 
 .. _ospf-multi-instance:
 

diff --git a/doc/user/pbr.rst b/doc/user/pbr.rst
@@ -15,11 +15,7 @@ the default Linux kernel dataplane provider.
 Starting PBR
 ============
 
-Default configuration file for *pbrd* is :file:`pbrd.conf`.  The typical
-location of :file:`pbrd.conf` is |INSTALL_PREFIX_ETC|/pbrd.conf.
-
-If FRR is using integrated config, then :file:`pbrd.conf` need not be
-present and the :file:`frr.conf` is read instead.
+.. include:: config-include.rst
 
 .. program:: pbrd
 

diff --git a/doc/user/pim.rst b/doc/user/pim.rst
@@ -23,12 +23,11 @@ network for optimizing forwarding of overlay BUM traffic.
 Starting and Stopping pimd
 ==========================
 
-The default configuration file name of *pimd*'s is :file:`pimd.conf`. When
-invoked *pimd* searches directory |INSTALL_PREFIX_ETC|. If
-:file:`pimd.conf` is not there then next search current directory.
+.. include:: config-include.rst
 
-*pimd* requires zebra for proper operation. Additionally *pimd* depends on
-routing properly setup and working in the network that it is working on.
+If starting daemons by hand then please note, *pimd* requires zebra for proper
+operation. Additionally *pimd* depends on routing properly setup and working in
+the network that it is working on.
 
 ::
 

diff --git a/doc/user/pimv6.rst b/doc/user/pimv6.rst
@@ -15,12 +15,11 @@ do S,G mrouting.
 Starting and Stopping pim6d
 ===========================
 
-The default configuration file name of *pim6d*'s is :file:`pim6d.conf`. When
-invoked *pim6d* searches directory |INSTALL_PREFIX_ETC|. If
-:file:`pim6d.conf` is not there then next search current directory.
+.. include:: config-include.rst
 
-*pim6d* requires zebra for proper operation. Additionally *pim6d* depends on
-routing properly setup and working in the network that it is working on.
+If starting daemons by hand then please note, *pim6d* requires zebra for proper
+operation. Additionally *pim6d* depends on routing properly setup and working in
+the network that it is working on.
 
 ::
 

diff --git a/doc/user/prior-config-files.rst b/doc/user/prior-config-files.rst
@@ -0,0 +1,22 @@
+..
+.. January 12 2024, Christian Hopps <[email protected]>
+..
+.. Copyright (c) 2024, LabN Consulting, L.L.C.
+..
+..
+
+Prior versions of FRR supported reading and writing per-daemon config files;
+however, with the introduction of the centralized management daemon ``mgmtd``
+this could no longer be supported.
+
+In order to allow for an orderly transition from per-daemon config files to the
+integrated config file, FRR daemons will continue to try and **read** their
+specific per-daemon configuration file as before. Additionally the config can
+still be loaded directly using the ``-f`` or ``--config-file`` CLI options;
+however, these files will **not** be updated when the configuration is written
+(e.g., with the ``write mem`` command).
+
+.. warning:: Per-daemon files will **no longer** be updated when the user issues
+             a ``write memory`` command. Therefore these per-daemon config files
+             should only be used as a mechanism for transitioning to the
+             integrated config, and then removed.
diff --git a/doc/user/ripd.rst b/doc/user/ripd.rst
@@ -21,15 +21,15 @@ version 1 as described in RFC1058.
 Starting and Stopping ripd
 ==========================
 
-The default configuration file name of *ripd*'s is :file:`ripd.conf`. When
-invocation *ripd* searches directory |INSTALL_PREFIX_ETC|. If :file:`ripd.conf`
-is not there next search current directory.
+.. include:: config-include.rst
 
 RIP uses UDP port 520 to send and receive RIP packets. So the user must have
 the capability to bind the port, generally this means that the user must have
-superuser privileges. RIP protocol requires interface information maintained by
-*zebra* daemon. So running *zebra* is mandatory to run *ripd*. Thus minimum
-sequence for running RIP is like below:
+superuser privileges.
+
+If starting daemons by hand then please note, RIP protocol requires interface
+information maintained by *zebra* daemon. So running *zebra* is mandatory to run
+*ripd*. Thus minimum sequence for running RIP is like below:
 
 ::
 

diff --git a/doc/user/ripngd.rst b/doc/user/ripngd.rst
@@ -12,6 +12,8 @@ reincarnation of the RIP protocol.
 Invoking ripngd
 ===============
 
+.. include:: config-include.rst
+
 There are no `ripngd` specific invocation options. Common options can be
 specified (:ref:`common-invocation-options`).
 

diff --git a/doc/user/sharp.rst b/doc/user/sharp.rst
@@ -13,11 +13,7 @@ labs.
 Starting SHARP
 ==============
 
-Default configuration file for *sharpd* is :file:`sharpd.conf`.  The typical
-location of :file:`sharpd.conf` is |INSTALL_PREFIX_ETC|/sharpd.conf.
-
-If the user is using integrated config, then :file:`sharpd.conf` need not be
-present and the :file:`frr.conf` is read instead.
+.. include:: config-include.rst
 
 .. program:: sharpd
 

diff --git a/doc/user/static.rst b/doc/user/static.rst
@@ -12,21 +12,13 @@ of static routes.
 Starting STATIC
 ===============
 
-Default configuration file for *staticd* is :file:`staticd.conf`.  The typical
-location of :file:`staticd.conf` is |INSTALL_PREFIX_ETC|/staticd.conf.
-
-If the user is using integrated config, then :file:`staticd.conf` need not be
-present and the :file:`frr.conf` is read instead.
-
-If the user has not fully upgraded to using the staticd.conf and still has
-a non-integrated config with zebra.conf holding the static routes, *staticd*
-will read in the :file:`zebrad.conf` as a backup.
-
 .. program:: staticd
 
 :abbr:`STATIC` supports all the common FRR daemon start options which are
 documented elsewhere.
 
+.. include:: config-include.rst
+
 .. _static-route-commands:
 
 Static Route Commands

diff --git a/doc/user/vrrp.rst b/doc/user/vrrp.rst
@@ -24,11 +24,7 @@ protocol.
 Starting VRRP
 =============
 
-The configuration file for *vrrpd* is :file:`vrrpd.conf`. The typical location
-of :file:`vrrpd.conf` is |INSTALL_PREFIX_ETC|/vrrpd.conf.
-
-If using integrated config, then :file:`vrrpd.conf` need not be present and
-:file:`frr.conf` is read instead.
+.. include:: config-include.rst
 
 .. program:: vrrpd
 

diff --git a/doc/user/vtysh.rst b/doc/user/vtysh.rst
@@ -131,14 +131,14 @@ could be made SGID (set group ID) to the |INSTALL_VTY_GROUP| group.
   at all.
 
 
-.. _integrated-configuration-mode:
+.. _integrated-configuration-file:
 
-Integrated configuration mode
+Integrated configuration file
 =============================
 
-Integrated configuration mode uses a single configuration file,
-:file:`frr.conf`, for all daemons. This replaces the individual files like
-:file:`zebra.conf` or :file:`bgpd.conf`.
+FRR uses a single configuration file, :file:`frr.conf`, for all daemons. This
+replaces the individual files like :file:`zebra.conf` or :file:`bgpd.conf` used
+in previous versions of the software.
 
 :file:`frr.conf` is located in |INSTALL_PREFIX_ETC|. All daemons check for the
 existence of this file at startup, and if it exists will not load their