Merge pull request #7462 from qlyoung/fix-misc-doc-issues

Fix misc doc issues

doc/user/basic.rst

@@ -25,10 +25,35 @@ forms the initial command set for a routing beast as it is starting.
 
 Config files are generally found in |INSTALL_PREFIX_ETC|.
 
-Each of the daemons has its own config file. The daemon name plus ``.conf`` is
-the default config file name. For example, zebra's default config file name is
-:file:`zebra.conf`. You can specify a config file using the :option:`-f` or
-:option:`--config_file` options when starting the daemon.
+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
+
+If you installed from source or used a package, this is probably already
+present.
+
+If desired, you can specify a config file using the :option:`-f` or
+:option:`--config_file` options when starting a daemon.
+
 
 .. _basic-config-commands:
 

doc/user/installation.rst

@@ -31,8 +31,11 @@ From Source
 
 Building FRR from source is the best way to ensure you have the latest features
 and bug fixes. Details for each supported platform, including dependency
-package listings, permissions, and other gotchas, are in the developer's
-documentation. This section provides a brief overview on the process.
+package listings, permissions, and other gotchas, are in the `developer's
+documentation
+<http://docs.frrouting.org/projects/dev-guide/en/latest/building.html>`_. This
+section provides a brief overview on the process.
+
 
 Getting the Source
 ^^^^^^^^^^^^^^^^^^

doc/user/vrrp.rst

@@ -507,3 +507,55 @@ VRRP is automatically activated. Global defaults, if set, are applied.
 
 You can then edit this configuration with **vtysh** as needed, and commit it by
 writing to the configuration file.
+
+
+Troubleshooting
+---------------
+
+My virtual routers are not seeing each others' advertisements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Check:
+- Is your kernel at least 5.1?
+- Did you set the macvlan devices to ``bridge`` mode?
+- If using IPv4 virtual addresses, does the parent of the macvlan devices have
+  an IPv4 address?
+- If using IPv6 virtual addresses, is ``addrgenmode`` correctly set to
+  ``random`` and not the default ``eui64``?
+- Is a firewall (``iptables``) or policy (``ip rule``) dropping multicast
+  traffic?
+- Do you have unusual ``sysctls`` enabled that could affect the operation of
+  multicast traffic?
+- Are you running in ESXi? See below.
+
+
+My master router is not forwarding traffic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There's several possible causes here. If you're sure your configuration is
+otherwise correct, the following sysctl likely needs to be turned on:
+
+.. code-block:: console
+
+   sysctl -w net.ipv4.conf.eth0.ignore_routes_with_linkdown=1
+
+Without this setting, it's possible to create topologies in which virtual
+routers holding mastership status will not forward traffic.
+
+Issue reference: https://github.com/FRRouting/frr/issues/7391
+
+
+My router is running in ESXi and VRRP isn't working
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, ESXi traffic security settings don't allow traffic to egress a VNIC
+that does not have the MAC address assigned to the VNIC. This breaks VRRP,
+since virtual MACs are the basis of the protocol.
+
+On ESXi before 6.7, you need to enable Promiscuous Mode in the ESXi settings.
+This is a significant security issue in some deployments so make sure you
+understand what you're doing. On 6.7 and later, you can use the MAC Learning
+feature instead, explained `here
+<https://www.virtuallyghetto.com/2018/04/native-mac-learning-in-vsphere-6-7-removes-the-need-for-promiscuous-mode-for-nested-esxi.html>`_.
+
+Issue reference: https://github.com/FRRouting/frr/issues/5386