From: Donald Sharp Date: Wed, 20 Jun 2018 13:14:48 +0000 (-0400) Subject: doc: Add some documentation for staticd X-Git-Tag: frr-6.1-dev~86^2~7 X-Git-Url: https://git.puffer.fish/?a=commitdiff_plain;h=614aa5c166aa05f5840d447e7d7d424d89afa91c;p=matthieu%2Ffrr.git doc: Add some documentation for staticd Remove the ip route specific sections from zebra documenation and create a specific one for the new staticd. Signed-off-by: Donald Sharp --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 19aab63ea3..da8ac3d050 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -86,6 +86,10 @@ if SHARPD man_MANS += $(MANPAGE_BUILDDIR)/sharpd.8 endif +if STATICD +man_MANS += $(MANPAGE_BUILDDIR)/staticd.8 +endif + # Automake is particular about manpages. It is aware of them and has some # special facilities for handling them, but it assumes that manpages are always # given in groff source and so these facilities are limited to simply @@ -151,6 +155,7 @@ EXTRA_DIST = frr-sphinx.mk \ manpages/pbrd.rst \ manpages/ripngd.rst \ manpages/sharpd.rst \ + manpages/staticd.rst \ manpages/vtysh.rst \ manpages/watchfrr.rst \ manpages/zebra.rst \ @@ -224,6 +229,7 @@ EXTRA_DIST = frr-sphinx.mk \ user/sharp.rst \ user/snmp.rst \ user/snmptrap.rst \ + user/static.rst \ user/Useful_Sysctl_Settings.md \ user/vnc.rst \ user/vtysh.rst \ diff --git a/doc/manpages/common-options.rst b/doc/manpages/common-options.rst index e9241b7438..1b2eb18dea 100644 --- a/doc/manpages/common-options.rst +++ b/doc/manpages/common-options.rst @@ -123,6 +123,7 @@ These following options control the daemon's VTY (interactive command line) inte ldpd 2612 eigrpd 2613 pbrd 2615 + staticd 2616 Port 2607 is used for ospfd's Opaque LSA API, while port 2600 is used for the (insecure) TCP-ZEBRA interface. diff --git a/doc/manpages/conf.py b/doc/manpages/conf.py index 2b0f7e3893..4d5797f613 100644 --- a/doc/manpages/conf.py +++ b/doc/manpages/conf.py @@ -324,6 +324,7 @@ man_pages = [ ('pimd', 'pimd', fwfrr.format("a PIM "), [], 8), ('pbrd', 'pbrd', fwfrr.format("a PBR "), [], 8), ('sharpd', 'sharpd', fwfrr.format("a SHARP "), [], 8), + ('staticd', 'staticd', fwfrr.format("a static route manager "), [], 8), ('mtracebis', 'mtracebis', "a multicast trace client", [], 8), ('ripd', 'ripd', fwfrr.format("a RIP "), [], 8), ('ripngd', 'ripngd', fwfrr.format("a RIPNG "), [], 8), diff --git a/doc/manpages/defines.rst b/doc/manpages/defines.rst index 21c3790afa..e1f7ec4ce8 100644 --- a/doc/manpages/defines.rst +++ b/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), pbrd(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), staticd(8), mtracebis(8) diff --git a/doc/manpages/index.rst b/doc/manpages/index.rst index 6d3f3aae55..e95dd26e84 100644 --- a/doc/manpages/index.rst +++ b/doc/manpages/index.rst @@ -20,6 +20,7 @@ ripd ripngd sharpd + staticd watchfrr zebra vtysh diff --git a/doc/manpages/staticd.rst b/doc/manpages/staticd.rst new file mode 100644 index 0000000000..ccbcf32e36 --- /dev/null +++ b/doc/manpages/staticd.rst @@ -0,0 +1,38 @@ +******* +STATICD +******* + +.. include:: defines.rst +.. |DAEMON| replace:: staticd + +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 + + diff --git a/doc/user/index.rst b/doc/user/index.rst index 746cc1c32d..14688e05d8 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -52,6 +52,7 @@ Protocols ripd ripngd sharp + static vnc ######## diff --git a/doc/user/setup.rst b/doc/user/setup.rst index 1bbbe36931..e9fd44a347 100644 --- a/doc/user/setup.rst +++ b/doc/user/setup.rst @@ -29,6 +29,7 @@ systemd. The file initially looks like this: eigrpd=no babeld=no sharpd=no + staticd=no pbrd=no To enable a particular daemon, simply change the corresponding 'no' to 'yes'. @@ -63,6 +64,7 @@ This file has several parts. Here is an example: eigrpd_options=" --daemon -A 127.0.0.1" babeld_options=" --daemon -A 127.0.0.1" sharpd_options=" --daemon -A 127.0.0.1" + staticd_options=" --daemon -A 127.0.0.1" pbrd_options=" --daemon -A 127.0.0.1" # The list of daemons to watch is automatically generated by the init script. diff --git a/doc/user/static.rst b/doc/user/static.rst new file mode 100644 index 0000000000..6755c809eb --- /dev/null +++ b/doc/user/static.rst @@ -0,0 +1,130 @@ +.. _static: + +****** +STATIC +****** + +:abbr:`STATIC` is a daemon that handles the installation and deletion +of static routes. + +.. _starting-static: + +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. + +.. _static-route-commands: + +Static Route Commands +===================== + +Static routing is a very fundamental feature of routing technology. It defines +a static prefix and gateway. + +.. index:: ip route NETWORK GATEWAY table TABLENO nexthop-vrf VRFNAME DISTANCE vrf VRFNAME +.. clicmd:: ip route NETWORK GATEWAY table TABLENO nexthop-vrf VRFNAME DISTANCE vrf VRFNAME + +.. index:: ipv6 route NETWORK from SRCPREFIX GATEWAY table TABLENO nexthop-vrf VRFNAME DISTANCE vrf VRFNAME +.. clicmd:: ipv6 route NETWORK from SRCPREFIX GATEWAY table TABLENO nexthop-vrf VRFNAME DISTANCE vrf VRFNAME + + NETWORK is destination prefix with a valid v4 or v6 network based upon + initial form of the command. GATEWAY is gateway for the prefix it currently + must match the v4 or v6 route type specified at the start of the command. + GATEWAY can also be treated as an interface name. If the interface name + is ``null0`` then zebra installs a blackhole route. TABLENO + is an optional parameter for namespaces that allows you to create the + route in a specified table associated with the vrf namespace. table will + be rejected if you are not using namespace based vrfs. ``nexthop-vrf`` + allows you to create a leaked route with a nexthop in the specified VRFNAME + vrf VRFNAME allows you to create the route in a specified vrf. + ``nexthop-vrf`` cannot be currently used with namespace based vrfs + currently as well. + The v6 variant allows the installation of a static source-specific route + with the SRCPREFIX sub command. These routes are currently supported + on Linux operating systems only, and perform AND matching on packet's + destination and source addresses in the kernel's forwarding path. Note + that destination longest-prefix match is "more important" than source + LPM, e.g. ``2001:db8:1::/64 from 2001:db8::/48`` will win over + ``2001:db8::/48 from 2001:db8:1::/64`` if both match. + +.. _multiple-route-command: + +Multiple nexthop static route +============================= + +To create multiple nexthops to the same NETWORK, just reenter the same +network statement with different nexthop information. + +.. code-block:: frr + + ip route 10.0.0.1/32 10.0.0.2 + ip route 10.0.0.1/32 10.0.0.3 + ip route 10.0.0.1/32 eth0 + + +If there is no route to 10.0.0.2 and 10.0.0.3, and interface eth0 +is reachable, then the last route is installed into the kernel. + +If zebra has been compiled with multipath support, and both 10.0.0.2 and +10.0.0.3 are reachable, zebra will install a multipath route via both +nexthops, if the platform supports this. + +:: + + router> show ip route + S> 10.0.0.1/32 [1/0] via 10.0.0.2 inactive + via 10.0.0.3 inactive + * is directly connected, eth0 + + +.. code-block:: frr + + ip route 10.0.0.0/8 10.0.0.2 + ip route 10.0.0.0/8 10.0.0.3 + ip route 10.0.0.0/8 null0 255 + + +This will install a multihop route via the specified next-hops if they are +reachable, as well as a high-distance blackhole route, which can be useful to +prevent traffic destined for a prefix to match less-specific routes (e.g. +default) should the specified gateways not be reachable. E.g.: + +:: + + router> show ip route 10.0.0.0/8 + Routing entry for 10.0.0.0/8 + Known via "static", distance 1, metric 0 + 10.0.0.2 inactive + 10.0.0.3 inactive + + Routing entry for 10.0.0.0/8 + Known via "static", distance 255, metric 0 + directly connected, Null0 + +Also, if the user wants to configure a static route for a specific VRF, then +a specific VRF configuration mode is available. After entering into that mode +with :clicmd:`vrf VRF` the user can enter the same route command as before, +but this time, the route command will apply to the VRF. + +.. code-block:: frr + + # case with VRF + configure terminal + vrf r1-cust1 + ip route 10.0.0.0/24 10.0.0.2 + exit-vrf + diff --git a/doc/user/zebra.rst b/doc/user/zebra.rst index a9431b16e3..af8e4b8d47 100644 --- a/doc/user/zebra.rst +++ b/doc/user/zebra.rst @@ -269,125 +269,6 @@ Link Parameters Commands for InterASv2 link in OSPF (RFC5392). Note that this option is not yet supported for ISIS (RFC5316). -.. _static-route-commands: - -Static Route Commands -===================== - -Static routing is a very fundamental feature of routing technology. It defines -static prefix and gateway. - -.. index:: ip route NETWORK GATEWAY -.. clicmd:: ip route NETWORK GATEWAY - - NETWORK is destination prefix with format of A.B.C.D/M. GATEWAY is gateway - for the prefix. When GATEWAY is A.B.C.D format. It is taken as a IPv4 - address gateway. Otherwise it is treated as an interface name. If the - interface name is ``null0`` then zebra installs a blackhole route. - - Some example configuration: - - .. code-block:: frr - - ip route 10.0.0.0/8 10.0.0.2 - ip route 10.0.0.0/8 ppp0 - ip route 10.0.0.0/8 null0 - - First example defines 10.0.0.0/8 static route with gateway 10.0.0.2. Second - one defines the same prefix but with gateway to interface ppp0. The third - install a blackhole route. - -.. index:: ip route NETWORK NETMASK GATEWAY -.. clicmd:: ip route NETWORK NETMASK GATEWAY - - This is alternate version of above command. When NETWORK is A.B.C.D format, - user must define NETMASK value with A.B.C.D format. GATEWAY is same option - as above command. - - .. code-block:: frr - - ip route 10.0.0.0 255.255.255.0 10.0.0.2 - ip route 10.0.0.0 255.255.255.0 ppp0 - ip route 10.0.0.0 255.255.255.0 null0 - - - These statements are equivalent to those in the previous example. - -.. index:: ip route NETWORK GATEWAY DISTANCE -.. clicmd:: ip route NETWORK GATEWAY DISTANCE - - Installs the route with the specified distance. - -Multiple nexthop static route: - -.. code-block:: frr - - ip route 10.0.0.1/32 10.0.0.2 - ip route 10.0.0.1/32 10.0.0.3 - ip route 10.0.0.1/32 eth0 - - -If there is no route to 10.0.0.2 and 10.0.0.3, and interface eth0 -is reachable, then the last route is installed into the kernel. - -If zebra has been compiled with multipath support, and both 10.0.0.2 and -10.0.0.3 are reachable, zebra will install a multipath route via both -nexthops, if the platform supports this. - -:: - - zebra> show ip route - S> 10.0.0.1/32 [1/0] via 10.0.0.2 inactive - via 10.0.0.3 inactive - * is directly connected, eth0 - - -.. code-block:: frr - - ip route 10.0.0.0/8 10.0.0.2 - ip route 10.0.0.0/8 10.0.0.3 - ip route 10.0.0.0/8 null0 255 - - -This will install a multihop route via the specified next-hops if they are -reachable, as well as a high-metric blackhole route, which can be useful to -prevent traffic destined for a prefix to match less-specific routes (e.g. -default) should the specified gateways not be reachable. E.g.: - -:: - - zebra> show ip route 10.0.0.0/8 - Routing entry for 10.0.0.0/8 - Known via "static", distance 1, metric 0 - 10.0.0.2 inactive - 10.0.0.3 inactive - - Routing entry for 10.0.0.0/8 - Known via "static", distance 255, metric 0 - directly connected, Null0 - - -.. index:: ipv6 route NETWORK GATEWAY -.. clicmd:: ipv6 route NETWORK GATEWAY - -.. index:: ipv6 route NETWORK GATEWAY DISTANCE -.. clicmd:: ipv6 route NETWORK GATEWAY DISTANCE - - These behave similarly to their ipv4 counterparts. - -.. index:: ipv6 route NETWORK from SRCPREFIX GATEWAY -.. clicmd:: ipv6 route NETWORK from SRCPREFIX GATEWAY - -.. index:: ipv6 route NETWORK from SRCPREFIX GATEWAY DISTANCE -.. clicmd:: ipv6 route NETWORK from SRCPREFIX GATEWAY DISTANCE - - Install a static source-specific route. These routes are currently supported - on Linux operating systems only, and perform AND matching on packet's - destination and source addresses in the kernel's forwarding path. Note that - destination longest-prefix match is "more important" than source LPM, e.g. - ``2001:db8:1::/64 from 2001:db8::/48`` will win over - ``2001:db8::/48 from 2001:db8:1::/64`` if both match. - .. index:: table TABLENO .. clicmd:: table TABLENO @@ -415,31 +296,9 @@ for each VRF. This conceptual view introduces the *Default VRF* case. If the user does not configure any specific VRF, then by default, FRR uses the *Default VRF*. -In the context of *Zebra*, this is done automatically when configuring a static -route with, for example, :clicmd:`ip route NETWORK GATEWAY`: - -.. code-block:: frr - - # case without VRF - configure terminal - ip route 10.0.0.0 255.255.255.0 10.0.0.2 - exit - Configuring VRF networking contexts can be done in various ways on FRR. The VRF interfaces can be configured by entering in interface configuration mode -:clicmd:`interface IFNAME vrf VRF`. Also, if the user wants to configure a -static route for a specific VRF, then a specific VRF configuration mode is -available. After entering into that mode with :clicmd:`vrf VRF` the user can -enter the same route command as before, but this time, the route command will -apply to the VRF. - -.. code-block:: frr - - # case with VRF - configure terminal - vrf r1-cust1 - ip route 10.0.0.0 255.255.255.0 10.0.0.2 - exit-vrf +:clicmd:`interface IFNAME vrf VRF`. A VRF backend mode is chosen when running *Zebra*. @@ -479,25 +338,6 @@ commands in relationship to VRF. Here is an extract of some of those commands: decide to provision this command in configuration file to provide more clarity about the intended configuration. -.. index:: ip route NETWORK NETMASK GATEWAY NEXTHOPVRF -.. clicmd:: ip route NETWORK NETMASK GATEWAY NEXTHOPVRF - - This command is based on VRF configuration mode or in configuration mode. If - on configuration mode, this applies to default VRF. Otherwise, this command - applies to the VRF of the vrf configuration mode. This command is used to - configure a vrf route leak across 2 VRFs. This command is only available - when *Zebra* is launched without :option:`-n` option. - -.. index:: ip route NETWORK NETMASK GATEWAY table TABLENO -.. clicmd:: ip route NETWORK NETMASK GATEWAY table TABLENO - - This command is based on configuration mode. There, for default VRF, this - command is available for all modes. The ``TABLENO`` configured is one of the - tables from Default *Linux network namespace*. This command is also available - on vrf configuration mode, provided that *Zebra* is run with :option:`-n` - option. In that case, this command configures a network route in the given - ``TABLENO`` of the *Linux network namespace* of the relevant VRF. - .. index:: show ip route vrf VRF .. clicmd:: show ip route vrf VRF @@ -515,14 +355,6 @@ commands in relationship to VRF. Here is an extract of some of those commands: will dump the routing table ``TABLENO`` of the *Linux network namespace* ``VRF``. -The usual static route commands are also available in the VRF context. When -entered within the VRF context the static routes are created in the VRF. - -.. code-block:: frr - - ip route 10.0.0.0 255.255.255.0 10.0.0.2 vrf r1-cust1 table 43 - show ip table vrf r1-cust1 table 43 - .. _zebra-mpls: