doc: Add documentation for PBRD

Signed-off-by: Donald Sharp <sharpd@cumulusnetworks.com>

doc/Makefile.am

@@ -26,6 +26,10 @@ man_MANS += $(MANPAGE_BUILDDIR)/pimd.8
 man_MANS += $(MANPAGE_BUILDDIR)/mtracebis.8
 endif
 
+if PBRD
+man_MANS += $(MANPAGE_BUILDDIR)/pbrd.8
+endif
+
 if BGPD
 man_MANS += $(MANPAGE_BUILDDIR)/bgpd.8
 endif
@@ -140,6 +144,7 @@ EXTRA_DIST = frr-sphinx.mk \
 	manpages/ospfd.rst \
 	manpages/pimd.rst \
 	manpages/ripd.rst \
+	manpages/pbrd.rst \
 	manpages/ripngd.rst \
 	manpages/vtysh.rst \
 	manpages/watchfrr.rst \
@@ -202,6 +207,7 @@ EXTRA_DIST = frr-sphinx.mk \
 	user/overview.rst \
 	user/pim.rst \
 	user/ripd.rst \
+	user/pbr.rst \
 	user/ripngd.rst \
 	user/routemap.rst \
 	user/routeserver.rst \

doc/manpages/common-options.rst

@@ -122,6 +122,7 @@ These following options control the daemon's VTY (interactive command line) inte
       pimd            2611
       ldpd            2612
       eigrpd          2613
+      pbrd            2615
 
    Port 2607 is used for ospfd's Opaque LSA API, while port 2600 is used for the (insecure) TCP-ZEBRA interface.
 

doc/manpages/conf.py

@@ -318,6 +318,7 @@ man_pages = [
     ('ldpd', 'ldpd', fwfrr.format("an LDP "), [], 8),
     ('nhrpd', 'nhrpd', fwfrr.format("a Next Hop Routing Protocol "), [], 8),
     ('pimd', 'pimd', fwfrr.format("a PIM "), [], 8),
+    ('pbrd', 'pbrd', fwfrr.format("a PBR "), [], 8),
     ('mtracebis', 'mtracebis', "a multicast trace client", [], 8),
     ('ripd', 'ripd', fwfrr.format("a RIP "), [], 8),
     ('ripngd', 'ripngd', fwfrr.format("a RIPNG "), [], 8),

doc/manpages/defines.rst

@@ -1,3 +1,3 @@
 .. |synopsis-options| replace:: [-d|-t|-dt] [-C] [-f config-file] [-i pid-file] [-z zclient-path] [-u user] [-g group] [-A vty-addr] [-P vty-port] [-M module[:options]] [-N pathspace] [--vty_socket vty-path] [--moduledir module-path]
 .. |synopsis-options-hv| replace:: [-h] [-v]
-.. |seealso-programs| replace:: zebra(8), vtysh(1), ripd(8), ripngd(8), ospfd(8), ospf6d(8), bgpd(8), isisd(8), babeld(8), nhrpd(8), pimd(8), ldpd(8), eigrpd(8), mtracebis(8)
+.. |seealso-programs| replace:: zebra(8), vtysh(1), ripd(8), ripngd(8), ospfd(8), ospf6d(8), bgpd(8), isisd(8), babeld(8), nhrpd(8), pimd(8), pbrd(8), ldpd(8), eigrpd(8), mtracebis(8)

doc/manpages/index.rst

@@ -18,6 +18,7 @@ Welcome to FRR's documentation!
    ospfclient
    ospfd
    pimd
+   pbrd
    mtracebis
    ripd
    ripngd

doc/manpages/pbrd.rst

@@ -0,0 +1,39 @@
+****
+PBRD
+****
+
+.. include:: defines.rst
+.. |DAEMON| replace:: pbrd
+
+SYNOPSIS
+========
+|DAEMON| |synopsis-options-hv|
+
+|DAEMON| |synopsis-options|
+
+DESCRIPTION
+===========
+|DAEMON| is a routing component that works with the FRRouting engine.
+
+OPTIONS
+=======
+OPTIONS available for the |DAEMON| command:
+
+.. include:: common-options.rst
+
+FILES
+=====
+
+|INSTALL_PREFIX_SBIN|/|DAEMON|
+   The default location of the |DAEMON| binary.
+
+|INSTALL_PREFIX_ETC|/|DAEMON|.conf
+   The default location of the |DAEMON| config file.
+
+$(PWD)/|DAEMON|.log
+   If the |DAEMON| process is configured to output logs to a file, then you
+   will find this file in the directory where you started |DAEMON|.
+
+.. include:: epilogue.rst
+
+

doc/user/index.rst

@@ -22,6 +22,7 @@ Welcome to FRR's documentation!
    ospfd
    ospf6d
    pim
+   pbr
    ripd
    ripngd
    vnc

doc/user/pbr.rst

@@ -0,0 +1,130 @@
+.. _pbr:
+
+***
+PBR
+***
+
+:abbr:`PBR` is Policy Based Routing.  This implementation supports a very
+simple interface to allow admins to influence routing on their router.  At
+this time you can only match on destination and source prefixes for
+an incoming interface.  At this point in time, this implementation will
+only work on Linux.
+
+.. _starting-pbr:
+
+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 the user is using integrated config, then :file:`pbrd.conf` need
+not be present and the :file:`frr.conf` is read instead.
+
+.. program:: pbrd
+
+:abbr:`PBR` supports all the common FRR daemon start options which are
+documented elsewhere.
+
+.. _nexthop-groups:
+
+NEXTHOP GROUPS
+==============
+
+Nexthop groups are a way to encapsulate ECMP information together.  It's a
+listing of ECMP nexthops used to forward packets for when a pbr-map is
+matched.
+
+.. index:: nexthop-group
+.. clicmd:: nexthop-group NAME
+
+    Create a nexthop-group with an associated NAME.  This will put
+    you into a sub-mode where you can specify individual nexthops.
+    To exit this mode type exit or end as per normal conventions
+    for leaving a sub-mode.
+
+.. clicmd:: nexthop [A.B.C.D|X:X::X:XX] [interface] [nexthop-vrf NAME]
+
+    Create a v4 or v6 nexthop.  All normal rules for creating nexthops
+    that you are used to are allowed here.  The syntax was intentionally
+    kept the same as creating nexthops as you would for static routes.
+	   
+.. _pbr-maps:
+
+PBR MAPS
+========
+
+PBR MAPS are a way to group policies that we would like to apply
+to individual interfaces.  These policies when applied are matched
+against incoming packets.  If matched the nexthop-group or nexthop
+is used to forward the packets to the end destination
+
+.. index:: pbr-map
+.. clicmd:: pbr-map NAME seq (1-1000)
+
+    Create a pbr-map with NAME and sequence number specified.  This
+    command puts you into a new submode for pbr-map specification.
+    To exit this mode type exit or end as per normal conventions
+    for leaving a sub-mode.
+
+.. index:: match
+.. clicmd:: match src-ip <PREFIX>
+
+    When a incoming packet matches the source prefix specified, take the packet
+    and forward according to the nexthops specified.  This command
+    accepts both v4 and v6 prefixes.  This command is used in
+    conjunction of the 'match dst-ip <PREFIX>' command for matching.
+
+.. clicmd:: match dst-ip <PREFIX>
+
+    When a incoming packet matches the destination prefix specified, take
+    the packet and forward according to the nexthops specified.  This
+    command accepts both v4 and v6 prefixes.  This command is used in
+    conjuction of the 'match src-ip <PREFIX>' command for matching.
+
+.. clicmd:: set nexthop-group NAME
+
+    Use the nexthop-group NAME as the place to forward packets when
+    the match commands have matched a packet.
+
+.. clicmd:: set nexthop [A.B.C.D|X:X::X:XX] [interface] [nexthop-vrf NAME]
+
+    Use this individual nexthop as the place to forward packets when
+    the match commands have matched a packet.
+
+.. _pbr-policy:
+
+PBR POLICY
+==========
+
+After you have specified a PBR MAP, in order for it to be turned on,
+you must apply the PBR MAP to an interface.  This policy application
+to an interface causes the policy to be installed into the kernel.
+
+..index:: pbr-policy
+.. clicmd:: pbr-policy NAME
+
+    This command is available under interface sub-mode.  This turns
+    on the PBR MAP NAME and allows it to work properly.
+
+.. _pbr-details:
+
+PBR DETAILS
+===========
+
+Under the covers a PBR MAP is translated into two separate constructs
+in the linux kernel.
+
+..index:: Rules
+
+    The PBR MAP specified creates a `ip rule ...` that is inserted into
+    the linux kernel that points to a table to use for forwarding once
+    the rule matches.
+    
+..index:: Tables
+
+    The creation of a nexthop or nexthop-group is translated to a default
+    route in a table with the nexthops specified as the nexthops for the
+    default route.
+
+