user: add 'Linux sysctl settings and kernel modules' installation considerations

Signed-off-by: Lou Berger <lberger@labn.net>

diff --git a/doc/user/installation.rst b/doc/user/installation.rst
index 8501054fdb655657fe2392a0c393005944b657ee..020e8b264a188e579a8ab588777ebb140ff3a830 100644 (file)
--- a/doc/user/installation.rst
+++ b/doc/user/installation.rst
@@ -287,6 +287,92 @@ or upper.
   utility.  It contains *ifconfig*, *route*, *netstat*, and other tools.
   `net-tools` may be found at http://www.tazenda.demon.co.uk/phil/net-tools/.
 
+
+Linux sysctl settings and kernel modules
+````````````````````````````````````````
+
+There are several kernel parameters that impact overall operation of FRR when
+using Linux as a router. Generally these parameters should be set in a
+sysctl related configuration file, e.g., :file:`/etc/sysctl.conf` on
+Ubuntu based systems and a new file
+:file:`/etc/sysctl.d/90-routing-sysctl.conf` on Centos based systems.
+Additional kernel modules are also needed to support MPLS forwarding.
+
+:makevar:`IPv4 and IPv6 forwarding`
+   The following are set to enable IP forwarding in the kernel:
+
+   .. code-block:: shell
+
+      net.ipv4.conf.all.forwarding=1
+      net.ipv6.conf.all.forwarding=1
+
+:makevar:`MPLS forwarding`
+   Basic MPLS kernel support was introduced 4.1, additional capability
+   was introduced in 4.3 and 4.5. For some general information on Linux
+   MPLS support see
+   https://www.netdevconf.org/1.1/proceedings/slides/prabhu-mpls-tutorial.pdf.
+   The following modules should be loaded to support MPLS forwarding,
+   and are generally added to a configuration file such as
+   :file:`/etc/modules-load.d/modules.conf`:
+
+   .. code-block:: shell
+
+      # Load MPLS Kernel Modules
+      mpls_router
+      mpls_iptunnel
+
+   The following is an example to enable MPLS forwarding in the kernel:
+
+   .. code-block:: shell
+
+      # Enable MPLS Label processing on all interfaces
+      net.mpls.conf.eth0.input=1
+      net.mpls.conf.eth1.input=1
+      net.mpls.conf.eth2.input=1
+      net.mpls.platform_labels=100000
+
+   Make sure to add a line equal to :file:`net.mpls.conf.<if>.input` for
+   each interface *'<if>'* used with MPLS and to set labels to an
+   appropriate value.
+
+:makevar:`VRF forwarding`
+   General information on Linux VRF support can be found in
+   https://www.kernel.org/doc/Documentation/networking/vrf.txt. Kernel
+   support for VRFs was introduced in 4.3 and improved upon through
+   4.13, which is the version most used in FRR testing (as of June
+   2018).  Additional background on using Linux VRFs and kernel specific
+   features can be found in
+   http://schd.ws/hosted_files/ossna2017/fe/vrf-tutorial-oss.pdf.
+
+   The following impacts how BGP TCP sockets are managed across VRFs:
+
+   .. code-block:: shell
+
+      net.ipv4.tcp_l3mdev_accept=0
+
+   With this setting a BGP TCP socket is opened per VRF.  This setting
+   ensures that other TCP services, such as SSH, provided for non-VRF
+   purposes are blocked from VRF associated Linux interfaces.
+
+   .. code-block:: shell
+
+      net.ipv4.tcp_l3mdev_accept=1
+
+   With this setting a single BGP TCP socket is shared across the
+   system.  This setting exposes any TCP service running on the system,
+   e.g., SSH, to all VRFs.  Generally this setting is not used in
+   environments where VRFs are used to support multiple administrative
+   groups.
+
+   **Important note** as of June 2018, Kernel versions 4.14-4.18 have a
+   known bug where VRF-specific TCP sockets are not properly handled. When
+   running these kernel versions, if unable to establish any VRF BGP
+   adjacencies, either downgrade to 4.13 or set
+   'net.ipv4.tcp_l3mdev_accept=1'. The fix for this issue is planned to be
+   included in future kernel versions so upgrading your kernel may also
+   address this issue.
+
+
 .. _build-the-software:
 
 Build the Software