Merge pull request #15150 from LabNConsulting/chopps/config-file-integrated

doc: update config file doc for integrated requirement

20 files changed, 89 insertions, 102 deletions

diff --git a/doc/user/babeld.rst b/doc/user/babeld.rst
index bda0045a60..b7b7c1fcb4 100644
--- 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
index 24978b2f79..4fd4f5f7c4 100644
--- 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
index 6c57822510..6915885f45 100644
--- 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
index 050141203b..11bd676740 100644
--- 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
new file mode 100644
index 0000000000..3a341513b4
--- /dev/null
+++ b/doc/user/config-include.rst
@@ -0,0 +1,12 @@
+..
+.. January 12 2024, Christian Hopps <chopps@labn.net>
+..
+.. 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
index fa157c4659..58a2957ad0 100644
--- 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
index 63c921330b..d37dfa64c6 100644
--- 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
index 682443a456..cbed734e42 100644
--- 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
index 12b368d431..ad5861051d 100644
--- 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
index 2f88f24599..3bc4487f64 100644
--- 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
index 7a4effd3fc..6ea153cc35 100644
--- 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
index d70c3c0e64..80a6a2787c 100644
--- 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
index 856939038f..d550c8e89c 100644
--- 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
new file mode 100644
index 0000000000..a01b688859
--- /dev/null
+++ b/doc/user/prior-config-files.rst
@@ -0,0 +1,23 @@
+..
+.. January 12 2024, Christian Hopps <chopps@labn.net>
+..
+.. 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
index f9c7724302..ea13dc92df 100644
--- 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
index 1e78294f32..f898bed57a 100644
--- 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
index 3e73a599ed..355b6b4d59 100644
--- 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
index d405276573..922c71a073 100644
--- 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
index ef3aebeafa..d99fc23ef5 100644
--- 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
index adbdf3451a..9722231d33 100644
--- 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