From: Quentin Young Date: Fri, 15 Dec 2017 18:16:24 +0000 (-0500) Subject: doc: start translating user manual to rst X-Git-Tag: frr-5.0-dev~165^2~91 X-Git-Url: https://git.puffer.fish/?a=commitdiff_plain;h=42fc5d26696cfa646edd21883d32a520816f5cc3;p=mirror%2Ffrr.git doc: start translating user manual to rst Automatically translated all Texinfo files to RST using a script found on the GCC mailing list[0]. Some formatting manually corrected. Also created index.rst for building as well as boilerplate Sphinx conf.py and Makefile. [0] https://gcc.gnu.org/ml/gcc-patches/2015-11/msg01095.html Signed-off-by: Quentin Young --- diff --git a/doc/appendix.texi b/doc/appendix.texi deleted file mode 100644 index 2e1c9deb1b..0000000000 --- a/doc/appendix.texi +++ /dev/null @@ -1,257 +0,0 @@ -@node Packet Binary Dump Format -@appendix Packet Binary Dump Format - - FRR can dump routing protocol packet into file with a binary format -(@pxref{Dump BGP packets and table}). - - It seems to be better that we share the MRT's header format for -backward compatibility with MRT's dump logs. We should also define the -binary format excluding the header, because we must support both IP -v4 and v6 addresses as socket addresses and / or routing entries. - - In the last meeting, we discussed to have a version field in the -header. But Masaki told us that we can define new `type' value rather -than having a `version' field, and it seems to be better because we -don't need to change header format. - - Here is the common header format. This is same as that of MRT. - -@example -@group -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Time | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Type | Subtype | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Length | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - - If `type' is PROTOCOL_BGP4MP_ET, the common header format will -contain an additional microsecond field (RFC6396 2011). - -@example -@group -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Time | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Type | Subtype | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Length | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Microsecond | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - - If `type' is PROTOCOL_BGP4MP, `subtype' is BGP4MP_STATE_CHANGE, and -Address Family == IP (version 4) - -@example -@group - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source AS number | Destination AS number | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Interface Index | Address Family | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Old State | New State | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - -Where State is the value defined in RFC1771. - -If `type' is PROTOCOL_BGP4MP, `subtype' is BGP4MP_STATE_CHANGE, -and Address Family == IP version 6 - -@example -@group - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source AS number | Destination AS number | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Interface Index | Address Family | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Old State | New State | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - -If `type' is PROTOCOL_BGP4MP, `subtype' is BGP4MP_MESSAGE, -and Address Family == IP (version 4) - -@example -@group - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source AS number | Destination AS number | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Interface Index | Address Family | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| BGP Message Packet | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - -Where BGP Message Packet is the whole contents of the -BGP4 message including header portion. - -If `type' is PROTOCOL_BGP4MP, `subtype' is BGP4MP_MESSAGE, -and Address Family == IP version 6 - -@example -@group - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source AS number | Destination AS number | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Interface Index | Address Family | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Source IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Destination IP address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| BGP Message Packet | -| | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - -If `type' is PROTOCOL_BGP4MP, `subtype' is BGP4MP_ENTRY, -and Address Family == IP (version 4) - -@example -@group - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| View # | Status | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Time Last Change | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Address Family | SAFI | Next-Hop-Len | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Next Hop Address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Prefix Length | Address Prefix [variable] | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Attribute Length | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| BGP Attribute [variable length] | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - -If `type' is PROTOCOL_BGP4MP, `subtype' is BGP4MP_ENTRY, -and Address Family == IP version 6 - -@example -@group - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| View # | Status | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Time Last Change | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Address Family | SAFI | Next-Hop-Len | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Next Hop Address | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Next Hop Address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Next Hop Address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Next Hop Address (Cont'd) | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Prefix Length | Address Prefix [variable] | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Address Prefix (cont'd) [variable] | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Attribute Length | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| BGP Attribute [variable length] | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - - BGP4 Attribute must not contain MP_UNREACH_NLRI. - If BGP Attribute has MP_REACH_NLRI field, it must has - zero length NLRI, e.g., MP_REACH_NLRI has only Address - Family, SAFI and next-hop values. - -If `type' is PROTOCOL_BGP4MP and `subtype' is BGP4MP_SNAPSHOT, - -@example -@group - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| View # | File Name [variable] | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -@end group -@end example - - The file specified in "File Name" contains all routing entries, - which are in the format of ``subtype == BGP4MP_ENTRY''. - -@example -@group -Constants: - /* type value */ - #define MSG_PROTOCOL_BGP4MP 16 - #define MSG_PROTOCOL_BGP4MP_ET 17 - /* subtype value */ - #define BGP4MP_STATE_CHANGE 0 - #define BGP4MP_MESSAGE 1 - #define BGP4MP_ENTRY 2 - #define BGP4MP_SNAPSHOT 3 -@end group -@end example diff --git a/doc/babeld.texi b/doc/babeld.texi deleted file mode 100644 index 341f692869..0000000000 --- a/doc/babeld.texi +++ /dev/null @@ -1,212 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the FRR Manual. -@c @value{COPYRIGHT_STR} -@c See file frr.texi for copying conditions. -@node Babel -@chapter Babel - -Babel is an interior gateway protocol that is suitable both for wired -networks and for wireless mesh networks. Babel has been described as -``RIP on speed'' --- it is based on the same principles as RIP, but -includes a number of refinements that make it react much faster to -topology changes without ever counting to infinity, and allow it to -perform reliable link quality estimation on wireless links. Babel is -a double-stack routing protocol, meaning that a single Babel instance -is able to perform routing for both IPv4 and IPv6. - -FRR implements Babel as described in RFC6126. - -@menu -* Configuring babeld:: -* Babel configuration:: -* Babel redistribution:: -* Show Babel information:: -* Babel debugging commands:: -@end menu - -@node Configuring babeld, Babel configuration, Babel, Babel -@section Configuring babeld - -The @command{babeld} daemon can be invoked with any of the common -options (@pxref{Common Invocation Options}). - -The @command{zebra} daemon must be running before @command{babeld} is -invoked. Also, if @command{zebra} is restarted then @command{babeld} -must be too. - -Configuration of @command{babeld} is done in its configuration file -@file{babeld.conf}. - -@node Babel configuration, Babel redistribution, Configuring babeld, Babel -@section Babel configuration - -@deffn Command {router babel} {} -@deffnx Command {no router babel} {} -Enable or disable Babel routing. -@end deffn - -@deffn Command {babel resend-delay <20-655340>} {} -Specifies the time after which important messages are resent when -avoiding a black-hole. The default is 2000@dmn{ms}. -@end deffn - -@deffn Command {babel diversity} {} -@deffnx Command {no babel diversity} {} -Enable or disable routing using radio frequency diversity. This is -highly recommended in networks with many wireless nodes. - -If you enable this, you will probably want to set @code{babel -diversity-factor} and @code{babel channel} below. -@end deffn - -@deffn Command {babel diversity-factor <1-256>} {} -Sets the multiplicative factor used for diversity routing, in units of -1/256; lower values cause diversity to play a more important role in -route selection. The default it 256, which means that diversity plays -no role in route selection; you will probably want to set that to 128 -or less on nodes with multiple independent radios. -@end deffn - -@deffn {Babel Command} {network @var{ifname}} {} -@deffnx {Babel Command} {no network @var{ifname}} {} -Enable or disable Babel on the given interface. -@end deffn - -@deffn {Interface Command} {babel wired} {} -@deffnx {Interface Command} {babel wireless} {} -Specifies whether this interface is wireless, which disables a number -of optimisations that are only correct on wired interfaces. -Specifying @code{wireless} (the default) is always correct, but may -cause slower convergence and extra routing traffic. -@end deffn - -@deffn {Interface Command} {babel split-horizon} -@deffnx {Interface Command} {no babel split-horizon} -Specifies whether to perform split-horizon on the interface. -Specifying @code{no babel split-horizon} is always correct, while -@code{babel split-horizon} is an optimisation that should only be used -on symmetric and transitive (wired) networks. The default is -@code{babel split-horizon} on wired interfaces, and @code{no babel -split-horizon} on wireless interfaces. This flag is reset when the -wired/wireless status of an interface is changed. -@end deffn - -@deffn {Interface Command} {babel hello-interval <20-655340>} -Specifies the time in milliseconds between two scheduled hellos. On -wired links, Babel notices a link failure within two hello intervals; -on wireless links, the link quality value is reestimated at every -hello interval. The default is 4000@dmn{ms}. -@end deffn - -@deffn {Interface Command} {babel update-interval <20-655340>} -Specifies the time in milliseconds between two scheduled updates. -Since Babel makes extensive use of triggered updates, this can be set -to fairly high values on links with little packet loss. The default -is 20000@dmn{ms}. -@end deffn - -@deffn {Interface Command} {babel channel <1-254>} -@deffnx {Interface Command} {babel channel interfering} -@deffnx {Interface Command} {babel channel noninterfering} -Set the channel number that diversity routing uses for this interface -(see @code{babel diversity} above). Noninterfering interfaces are -assumed to only interfere with themselves, interfering interfaces are -assumed to interfere with all other channels except noninterfering -channels, and interfaces with a channel number interfere with -interfering interfaces and interfaces with the same channel number. -The default is @samp{babel channel interfering} for wireless -interfaces, and @samp{babel channel noninterfering} for wired -interfaces. This is reset when the wired/wireless status of an -interface is changed. -@end deffn - -@deffn {Interface Command} {babel rxcost <1-65534>} -Specifies the base receive cost for this interface. For wireless -interfaces, it specifies the multiplier used for computing the ETX -reception cost (default 256); for wired interfaces, it specifies the -cost that will be advertised to neighbours. This value is reset when -the wired/wireless attribute of the interface is changed. - -Do not use this command unless you know what you are doing; in most -networks, acting directly on the cost using route maps is a better -technique. -@end deffn - -@deffn {Interface Command} {babel rtt-decay <1-256>} -This specifies the decay factor for the exponential moving average of -RTT samples, in units of 1/256. Higher values discard old samples -faster. The default is 42. -@end deffn - -@deffn {Interface Command} {babel rtt-min <1-65535>} -This specifies the minimum RTT, in milliseconds, starting from which we -increase the cost to a neighbour. The additional cost is linear in (rtt -- rtt-min ). The default is 10@dmn{ms}. -@end deffn - -@deffn {Interface Command} {babel rtt-max <1-65535>} -This specifies the maximum RTT, in milliseconds, above which we don't -increase the cost to a neighbour. The default is 120@dmn{ms}. -@end deffn - -@deffn {Interface Command} {babel max-rtt-penalty <0-65535>} -This specifies the maximum cost added to a neighbour because of RTT, -i.e. when the RTT is higher or equal than rtt-max. The default is 0, -which effectively disables the use of a RTT-based cost. -@end deffn - -@deffn {Interface Command} {babel enable-timestamps} -@deffnx {Interface Command} {no babel enable-timestamps} -Enable or disable sending timestamps with each Hello and IHU message in -order to compute RTT values. The default is @code{no babel -enable-timestamps}. -@end deffn - -@deffn {Babel Command} {babel resend-delay <20-655340>} -Specifies the time in milliseconds after which an ``important'' -request or update will be resent. The default is 2000@dmn{ms}. You -probably don't want to tweak this value. -@end deffn - -@deffn {Babel Command} {babel smoothing-half-life <0-65534>} -Specifies the time constant, in seconds, of the smoothing algorithm -used for implementing hysteresis. Larger values reduce route -oscillation at the cost of very slightly increasing convergence time. -The value 0 disables hysteresis, and is suitable for wired networks. -The default is 4@dmn{s}. -@end deffn - -@node Babel redistribution, Show Babel information, Babel configuration, Babel -@section Babel redistribution - -@deffn {Babel command} {redistribute @var{} @var{kind}} -@deffnx {Babel command} {no redistribute @var{} @var{kind}} -Specify which kind of routes should be redistributed into Babel. -@end deffn - -@node Show Babel information, Babel debugging commands, Babel redistribution, Babel -@section Show Babel information - -@deffn {Command} {show babel route} {} -@deffnx {Command} {show babel route A.B.C.D} -@deffnx {Command} {show babel route X:X::X:X} -@deffnx {Command} {show babel route A.B.C.D/M} -@deffnx {Command} {show babel route X:X::X:X/M} -@deffnx {Command} {show babel interface} {} -@deffnx {Command} {show babel interface @var{ifname}} {} -@deffnx {Command} {show babel neighbor} {} -@deffnx {Command} {show babel parameters} {} -These commands dump various parts of @command{babeld}'s internal state. -@end deffn - -@node Babel debugging commands, , Show Babel information, Babel -@section Babel debugging commands - -@deffn {Babel Command} {debug babel @var{kind}} {} -@deffnx {Babel Command} {no debug babel @var{kind}} {} -Enable or disable debugging messages of a given kind. @var{kind} can -be one of @samp{common}, @samp{kernel}, @samp{filter}, @samp{timeout}, -@samp{interface}, @samp{route} or @samp{all}. Note that if you have -compiled with the NO_DEBUG flag, then these commands aren't available. -@end deffn - diff --git a/doc/basic.texi b/doc/basic.texi deleted file mode 100644 index 6e43210bb8..0000000000 --- a/doc/basic.texi +++ /dev/null @@ -1,642 +0,0 @@ -@node Basic commands -@chapter Basic commands - -There are five routing daemons in use, and there is one manager daemon. -These daemons may be located on separate machines from the manager -daemon. Each of these daemons will listen on a particular port for -incoming VTY connections. The routing daemons are: - -@itemize @bullet -@item @command{ripd}, @command{ripngd}, @command{ospfd}, @command{ospf6d}, @command{bgpd} -@item @command{zebra} -@end itemize - -The following sections discuss commands common to all the routing -daemons. - -@menu -* Config Commands:: Commands used in config files -* Terminal Mode Commands:: Common commands used in a VTY -* Common Invocation Options:: Starting the daemons -* Loadable Module Support:: Using extension modules -* Virtual Terminal Interfaces:: Interacting with the daemons -@end menu - - - -@node Config Commands -@section Config Commands - -@cindex Configuration files for running the software -@c A -not configuration files for installing the software -@cindex Files for running configurations -@cindex Modifying the herd's behavior -@cindex Getting the herd running - - -@menu -* Basic Config Commands:: Some of the generic config commands -* Sample Config File:: An example config file -@end menu - - -In a 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: - -@itemize @w{} -@item @file{@value{INSTALL_PREFIX_ETC}/*.conf} -@end itemize - -Each of the daemons has its own -config file. For example, zebra's default config file name is: - -@itemize @w{} -@item @file{@value{INSTALL_PREFIX_ETC}/zebra.conf} -@end itemize - -The daemon name plus @file{.conf} is the default config file name. You -can specify a config file using the @kbd{-f} or @kbd{--config-file} -options when starting the daemon. - - - -@node Basic Config Commands -@subsection Basic Config Commands - -@deffn Command {hostname @var{hostname}} {} -Set hostname of the router. -@end deffn - -@deffn Command {password @var{password}} {} -Set password for vty interface. If there is no password, a vty won't -accept connections. -@end deffn - -@deffn Command {enable password @var{password}} {} -Set enable password. -@end deffn - -@deffn Command {log trap @var{level}} {} -@deffnx Command {no log trap} {} -These commands are deprecated and are present only for historical compatibility. -The log trap command sets the current logging level for all enabled -logging destinations, and it sets the default for all future logging commands -that do not specify a level. The normal default -logging level is debugging. The @code{no} form of the command resets -the default level for future logging commands to debugging, but it does -not change the logging level of existing logging destinations. -@end deffn - - -@deffn Command {log stdout} {} -@deffnx Command {log stdout @var{level}} {} -@deffnx Command {no log stdout} {} -Enable logging output to stdout. -If the optional second argument specifying the -logging level is not present, the default logging level (typically debugging, -but can be changed using the deprecated @code{log trap} command) will be used. -The @code{no} form of the command disables logging to stdout. -The @code{level} argument must have one of these values: -emergencies, alerts, critical, errors, warnings, notifications, informational, or debugging. Note that the existing code logs its most important messages -with severity @code{errors}. -@end deffn - -@deffn Command {log file @var{filename}} {} -@deffnx Command {log file @var{filename} @var{level}} {} -@deffnx Command {no log file} {} -If you want to log into a file, please specify @code{filename} as -in this example: -@example -log file /var/log/frr/bgpd.log informational -@end example -If the optional second argument specifying the -logging level is not present, the default logging level (typically debugging, -but can be changed using the deprecated @code{log trap} command) will be used. -The @code{no} form of the command disables logging to a file. - -Note: if you do not configure any file logging, and a daemon crashes due -to a signal or an assertion failure, it will attempt to save the crash -information in a file named /var/tmp/frr..crashlog. -For security reasons, this will not happen if the file exists already, so -it is important to delete the file after reporting the crash information. -@end deffn - -@deffn Command {log syslog} {} -@deffnx Command {log syslog @var{level}} {} -@deffnx Command {no log syslog} {} -Enable logging output to syslog. -If the optional second argument specifying the -logging level is not present, the default logging level (typically debugging, -but can be changed using the deprecated @code{log trap} command) will be used. -The @code{no} form of the command disables logging to syslog. -@end deffn - -@deffn Command {log monitor} {} -@deffnx Command {log monitor @var{level}} {} -@deffnx Command {no log monitor} {} -Enable logging output to vty terminals that have enabled logging -using the @code{terminal monitor} command. -By default, monitor logging is enabled at the debugging level, but this -command (or the deprecated @code{log trap} command) can be used to change -the monitor logging level. -If the optional second argument specifying the -logging level is not present, the default logging level (typically debugging, -but can be changed using the deprecated @code{log trap} command) will be used. -The @code{no} form of the command disables logging to terminal monitors. -@end deffn - -@deffn Command {log facility @var{facility}} {} -@deffnx Command {no log facility} {} -This command changes the facility used in syslog messages. The default -facility is @code{daemon}. The @code{no} form of the command resets -the facility to the default @code{daemon} facility. -@end deffn - -@deffn Command {log record-priority} {} -@deffnx Command {no log record-priority} {} -To include the severity in all messages logged to a file, to stdout, or to -a terminal monitor (i.e. anything except syslog), -use the @code{log record-priority} global configuration command. -To disable this option, use the @code{no} form of the command. By default, -the severity level is not included in logged messages. Note: some -versions of syslogd (including Solaris) can be configured to include -the facility and level in the messages emitted. -@end deffn - -@deffn Command {log timestamp precision @var{<0-6>}} {} -@deffnx Command {no log timestamp precision} {} -This command sets the precision of log message timestamps to the -given number of digits after the decimal point. Currently, -the value must be in the range 0 to 6 (i.e. the maximum precision -is microseconds). -To restore the default behavior (1-second accuracy), use the -@code{no} form of the command, or set the precision explicitly to 0. - -@example -@group -log timestamp precision 3 -@end group -@end example - -In this example, the precision is set to provide timestamps with -millisecond accuracy. -@end deffn - -@deffn Command {log commands} {} -This command enables the logging of all commands typed by a user to -all enabled log destinations. The note that logging includes full -command lines, including passwords. Once set, command logging can only -be turned off by restarting the daemon. -@end deffn - -@deffn Command {service password-encryption} {} -Encrypt password. -@end deffn - -@deffn Command {service advanced-vty} {} -Enable advanced mode VTY. -@end deffn - -@deffn Command {service terminal-length @var{<0-512>}} {} -Set system wide line configuration. This configuration command applies -to all VTY interfaces. -@end deffn - -@deffn Command {line vty} {} -Enter vty configuration mode. -@end deffn - -@deffn Command {banner motd default} {} -Set default motd string. -@end deffn - -@deffn Command {no banner motd} {} -No motd banner string will be printed. -@end deffn - -@deffn {Line Command} {exec-timeout @var{minute}} {} -@deffnx {Line Command} {exec-timeout @var{minute} @var{second}} {} -Set VTY connection timeout value. When only one argument is specified -it is used for timeout value in minutes. Optional second argument is -used for timeout value in seconds. Default timeout value is 10 minutes. -When timeout value is zero, it means no timeout. -@end deffn - -@deffn {Line Command} {no exec-timeout} {} -Do not perform timeout at all. This command is as same as -@command{exec-timeout 0 0}. -@end deffn - -@deffn {Line Command} {access-class @var{access-list}} {} -Restrict vty connections with an access list. -@end deffn - -@node Sample Config File -@subsection Sample Config File - - -Below is a sample configuration file for the zebra daemon. - -@example -@group -! -! Zebra configuration file -! -hostname Router -password zebra -enable password zebra -! -log stdout -! -! -@end group -@end example - -'!' and '#' are comment characters. If the first character of the word -is one of the comment characters then from the rest of the line forward -will be ignored as a comment. - -@example -password zebra!password -@end example - -If a comment character is not the first character of the word, it's a -normal character. So in the above example '!' will not be regarded as a -comment and the password is set to 'zebra!password'. - - - -@node Terminal Mode Commands -@section Terminal Mode Commands - -@deffn Command {write terminal} {} -Displays the current configuration to the vty interface. -@end deffn - -@deffn Command {write file} {} -Write current configuration to configuration file. -@end deffn - -@deffn Command {configure terminal} {} -Change to configuration mode. This command is the first step to -configuration. -@end deffn - -@deffn Command {terminal length @var{<0-512>}} {} -Set terminal display length to @var{<0-512>}. If length is 0, no -display control is performed. -@end deffn - -@deffn Command {who} {} -Show a list of currently connected vty sessions. -@end deffn - -@deffn Command {list} {} -List all available commands. -@end deffn - -@deffn Command {show version} {} -Show the current version of @value{PACKAGE_NAME} and its build host information. -@end deffn - -@deffn Command {show logging} {} -Shows the current configuration of the logging system. This includes -the status of all logging destinations. -@end deffn - -@deffn Command {logmsg @var{level} @var{message}} {} -Send a message to all logging destinations that are enabled for messages -of the given severity. -@end deffn - - - - -@node Common Invocation Options -@section Common Invocation Options -@c COMMON_OPTIONS -@c OPTIONS section of the man page - -These options apply to all @value{PACKAGE_NAME} daemons. - -@table @samp - -@item -d -@itemx --daemon -Runs in daemon mode. - -@item -f @var{file} -@itemx --config_file=@var{file} -Set configuration file name. - -@item -h -@itemx --help -Display this help and exit. - -@item -i @var{file} -@itemx --pid_file=@var{file} - -Upon startup the process identifier of the daemon is written to a file, -typically in @file{/var/run}. This file can be used by the init system -to implement commands such as @command{@dots{}/init.d/zebra status}, -@command{@dots{}/init.d/zebra restart} or @command{@dots{}/init.d/zebra -stop}. - -The file name is an run-time option rather than a configure-time option -so that multiple routing daemons can be run simultaneously. This is -useful when using @value{PACKAGE_NAME} to implement a routing looking glass. One -machine can be used to collect differing routing views from differing -points in the network. - -@item -A @var{address} -@itemx --vty_addr=@var{address} -Set the VTY local address to bind to. If set, the VTY socket will only -be bound to this address. - -@item -P @var{port} -@itemx --vty_port=@var{port} -Set the VTY TCP port number. If set to 0 then the TCP VTY sockets will not -be opened. - -@item -u @var{user} -@itemx --vty_addr=@var{user} -Set the user and group to run as. - -@item -v -@itemx --version -Print program version. - -@end table - - -@node Loadable Module Support -@section Loadable Module Support - -FRR supports loading extension modules at startup. Loading, reloading or -unloading modules at runtime is not supported (yet). To load a module, use -the following command line option at daemon startup: - -@table @samp -@item -M @var{module:options} -@itemx --module @var{module:options} - -Load the specified module, optionally passing options to it. If the module -name contains a slash (/), it is assumed to be a full pathname to a file to -be loaded. If it does not contain a slash, the -@code{@value{INSTALL_PREFIX_MODULES}} directory is searched for a module of -the given name; first with the daemon name prepended (e.g. @code{zebra_mod} -for @code{mod}), then without the daemon name prepended. - -This option is available on all daemons, though some daemons may not have -any modules available to be loaded. -@end table - - -@subsection The SNMP Module - -If SNMP is enabled during compile-time and installed as part of the package, -the @code{snmp} module can be loaded for the @command{zebra}, -@command{bgpd}, @command{ospfd}, @command{ospf6d} and @command{ripd} daemons. - -The module ignores any options passed to it. Refer to @ref{SNMP Support} -for information on its usage. - - -@subsection The FPM Module - -If FPM is enabled during compile-time and installed as part of the package, -the @code{fpm} module can be loaded for the @command{zebra} daemon. This -provides the Forwarding Plane Manager ("FPM") API. - -The module expects its argument to be either @code{netlink} or -@code{protobuf}, specifying the encapsulation to use. @code{netlink} is the -default, and @code{protobuf} may not be available if the module was built -without protobuf support. Refer to @ref{zebra FIB push interface} for more -information. - - -@node Virtual Terminal Interfaces -@section Virtual Terminal Interfaces - -VTY -- Virtual Terminal [aka TeletYpe] Interface is a command line -interface (CLI) for user interaction with the routing daemon. - -@menu -* VTY Overview:: Basics about VTYs -* VTY Modes:: View, Enable, and Other VTY modes -* VTY CLI Commands:: Commands for movement, edition, and management -@end menu - - - -@node VTY Overview -@subsection VTY Overview - - -VTY stands for Virtual TeletYpe interface. It means you can connect to -the daemon via the telnet protocol. - -To enable a VTY interface, you have to setup a VTY password. If there -is no VTY password, one cannot connect to the VTY interface at all. - -@example -@group -% telnet localhost 2601 -Trying 127.0.0.1... -Connected to localhost. -Escape character is '^]'. - -Hello, this is @value{PACKAGE_NAME} (version @value{PACKAGE_VERSION}) -@value{COPYRIGHT_STR} - -User Access Verification - -Password: XXXXX -Router> ? - enable Turn on privileged commands - exit Exit current mode and down to previous mode - help Description of the interactive help system - list Print command list - show Show running system information - who Display who is on a vty -Router> enable -Password: XXXXX -Router# configure terminal -Router(config)# interface eth0 -Router(config-if)# ip address 10.0.0.1/8 -Router(config-if)# ^Z -Router# -@end group -@end example - -'?' is very useful for looking up commands. - -@node VTY Modes -@subsection VTY Modes - -There are three basic VTY modes: - -@menu -* VTY View Mode:: Mode for read-only interaction -* VTY Enable Mode:: Mode for read-write interaction -* VTY Other Modes:: Special modes (tftp, etc) -@end menu - -There are commands that may be restricted to specific VTY modes. - -@node VTY View Mode -@subsubsection VTY View Mode -@c to be written (gpoul) - - -This mode is for read-only access to the CLI. One may exit the mode by -leaving the system, or by entering @code{enable} mode. - -@node VTY Enable Mode -@subsubsection VTY Enable Mode - -@c to be written (gpoul) -This mode is for read-write access to the CLI. One may exit the mode by -leaving the system, or by escaping to view mode. - -@node VTY Other Modes -@subsubsection VTY Other Modes - - -@c to be written (gpoul) -This page is for describing other modes. - -@node VTY CLI Commands -@subsection VTY CLI Commands - -Commands that you may use at the command-line are described in the following -three subsubsections. - -@menu -* CLI Movement Commands:: Commands for moving the cursor about -* CLI Editing Commands:: Commands for changing text -* CLI Advanced Commands:: Other commands, session management and so on -@end menu - -@node CLI Movement Commands -@subsubsection CLI Movement Commands - -These commands are used for moving the CLI cursor. The @key{C} character -means press the Control Key. - -@table @kbd - -@item C-f -@itemx @key{RIGHT} -@kindex C-f -@kindex @key{RIGHT} -Move forward one character. - -@item C-b -@itemx @key{LEFT} -@kindex C-b -@kindex @key{LEFT} -Move backward one character. - -@item M-f -@kindex M-f -Move forward one word. - -@item M-b -@kindex M-b -Move backward one word. - -@item C-a -@kindex C-a -Move to the beginning of the line. - -@item C-e -@kindex C-e -Move to the end of the line. - -@end table - -@node CLI Editing Commands -@subsubsection CLI Editing Commands - -These commands are used for editing text on a line. The @key{C} -character means press the Control Key. - -@table @kbd - -@item C-h -@itemx @key{DEL} -@kindex C-h -@kindex @key{DEL} -Delete the character before point. - -@item C-d -@kindex C-d -Delete the character after point. - -@item M-d -@kindex M-d -Forward kill word. - -@item C-w -@kindex C-w -Backward kill word. - -@item C-k -@kindex C-k -Kill to the end of the line. - -@item C-u -@kindex C-u -Kill line from the beginning, erasing input. - -@item C-t -@kindex C-t -Transpose character. - -@end table - -@node CLI Advanced Commands -@subsubsection CLI Advanced Commands - -There are several additional CLI commands for command line completions, -insta-help, and VTY session management. - -@table @kbd - -@item C-c -@kindex C-c -Interrupt current input and moves to the next line. - -@item C-z -@kindex C-z -End current configuration session and move to top node. - - -@item C-n -@itemx @key{DOWN} -@kindex C-n -@kindex @key{DOWN} -Move down to next line in the history buffer. - -@item C-p -@itemx @key{UP} -@kindex C-p -@kindex @key{UP} -Move up to previous line in the history buffer. - -@item TAB -@kindex @key{TAB} -Use command line completion by typing @key{TAB}. - -@item ? -@kindex @key{?} -You can use command line help by typing @code{help} at the beginning of -the line. Typing @kbd{?} at any point in the line will show possible -completions. - -@end table diff --git a/doc/bgpd.texi b/doc/bgpd.texi deleted file mode 100644 index d62c3a7516..0000000000 --- a/doc/bgpd.texi +++ /dev/null @@ -1,2149 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the Frr Manual. -@c @value{COPYRIGHT_STR} -@c Portions: -@c Copyright @copyright{} 2015 Hewlett Packard Enterprise Development LP -@c See file frr.texi for copying conditions. -@node BGP -@chapter BGP - -@acronym{BGP} stands for a Border Gateway Protocol. The lastest BGP version -is 4. It is referred as BGP-4. BGP-4 is one of the Exterior Gateway -Protocols and de-fact standard of Inter Domain routing protocol. -BGP-4 is described in @cite{RFC1771, A Border Gateway Protocol -4 (BGP-4)}. - -Many extensions have been added to @cite{RFC1771}. @cite{RFC2858, -Multiprotocol Extensions for BGP-4} provides multiprotocol support to -BGP-4. - -@menu -* Starting BGP:: -* BGP router:: -* BGP MED:: -* BGP network:: -* BGP Peer:: -* BGP Peer Group:: -* BGP Address Family:: -* Autonomous System:: -* BGP Communities Attribute:: -* BGP Extended Communities Attribute:: -* BGP Large Communities Attribute:: -* Displaying BGP information:: -* Capability Negotiation:: -* Route Reflector:: -* Route Server:: -* BGP Regular Expressions:: -* How to set up a 6-Bone connection:: -* Dump BGP packets and table:: -* BGP Configuration Examples:: -* Prefix Origin Validation Using RPKI:: -@end menu - -@node Starting BGP -@section Starting BGP - -Default configuration file of @command{bgpd} is @file{bgpd.conf}. -@command{bgpd} searches the current directory first then -@value{INSTALL_PREFIX_ETC}/bgpd.conf. All of bgpd's command must be -configured in @file{bgpd.conf}. - -@command{bgpd} specific invocation options are described below. Common -options may also be specified (@pxref{Common Invocation Options}). - -@table @samp -@item -p @var{PORT} -@itemx --bgp_port=@var{PORT} -Set the bgp protocol's port number. - -@item -r -@itemx --retain -When program terminates, retain BGP routes added by zebra. - -@item -l -@itemx --listenon -Specify a specific IP address for bgpd to listen on, rather than its -default of INADDR_ANY / IN6ADDR_ANY. This can be useful to constrain bgpd -to an internal address, or to run multiple bgpd processes on one host. - -@end table - -@node BGP router -@section BGP router - - First of all you must configure BGP router with @command{router bgp} -command. To configure BGP router, you need AS number. AS number is an -identification of autonomous system. BGP protocol uses the AS number -for detecting whether the BGP connection is internal one or external one. - -@deffn Command {router bgp @var{asn}} {} -Enable a BGP protocol process with the specified @var{asn}. After -this statement you can input any @code{BGP Commands}. You can not -create different BGP process under different @var{asn} without -specifying @code{multiple-instance} (@pxref{Multiple instance}). -@end deffn - -@deffn Command {no router bgp @var{asn}} {} -Destroy a BGP protocol process with the specified @var{asn}. -@end deffn - -@deffn {BGP} {bgp router-id @var{A.B.C.D}} {} -This command specifies the router-ID. If @command{bgpd} connects to @command{zebra} it gets -interface and address information. In that case default router ID value -is selected as the largest IP Address of the interfaces. When -@code{router zebra} is not enabled @command{bgpd} can't get interface information -so @code{router-id} is set to 0.0.0.0. So please set router-id by hand. -@end deffn - -@menu -* BGP distance:: -* BGP decision process:: -* BGP route flap dampening:: -@end menu - -@node BGP distance -@subsection BGP distance - -@deffn {BGP} {distance bgp <1-255> <1-255> <1-255>} {} -This command change distance value of BGP. Each argument is distance -value for external routes, internal routes and local routes. -@end deffn - -@deffn {BGP} {distance <1-255> @var{A.B.C.D/M}} {} -@deffnx {BGP} {distance <1-255> @var{A.B.C.D/M} @var{word}} {} -This command set distance value to -@end deffn - -@node BGP decision process -@subsection BGP decision process - -The decision process Frr BGP uses to select routes is as follows: - -@table @asis -@item 1. Weight check -prefer higher local weight routes to lower routes. - -@item 2. Local preference check -prefer higher local preference routes to lower. - -@item 3. Local route check -Prefer local routes (statics, aggregates, redistributed) to received routes. - -@item 4. AS path length check -Prefer shortest hop-count AS_PATHs. - -@item 5. Origin check -Prefer the lowest origin type route. That is, prefer IGP origin routes to -EGP, to Incomplete routes. - -@item 6. MED check -Where routes with a MED were received from the same AS, -prefer the route with the lowest MED. @xref{BGP MED}. - -@item 7. External check -Prefer the route received from an external, eBGP peer -over routes received from other types of peers. - -@item 8. IGP cost check -Prefer the route with the lower IGP cost. - -@item 9. Multi-path check -If multi-pathing is enabled, then check whether -the routes not yet distinguished in preference may be considered equal. If -@ref{bgp bestpath as-path multipath-relax} is set, all such routes are -considered equal, otherwise routes received via iBGP with identical AS_PATHs -or routes received from eBGP neighbours in the same AS are considered equal. - -@item 10 Already-selected external check - -Where both routes were received from eBGP peers, then prefer the route which -is already selected. Note that this check is not applied if @ref{bgp -bestpath compare-routerid} is configured. This check can prevent some cases -of oscillation. - -@item 11. Router-ID check -Prefer the route with the lowest @w{router-ID}. If the -route has an @w{ORIGINATOR_ID} attribute, through iBGP reflection, then that -router ID is used, otherwise the @w{router-ID} of the peer the route was -received from is used. - -@item 12. Cluster-List length check -The route with the shortest cluster-list -length is used. The cluster-list reflects the iBGP reflection path the -route has taken. - -@item 13. Peer address -Prefer the route received from the peer with the higher -transport layer address, as a last-resort tie-breaker. - -@end table - -@deffn {BGP} {bgp bestpath as-path confed} {} -This command specifies that the length of confederation path sets and -sequences should should be taken into account during the BGP best path -decision process. -@end deffn - -@deffn {BGP} {bgp bestpath as-path multipath-relax} {} -@anchor{bgp bestpath as-path multipath-relax} -This command specifies that BGP decision process should consider paths -of equal AS_PATH length candidates for multipath computation. Without -the knob, the entire AS_PATH must match for multipath computation. -@end deffn - -@deffn {BGP} {bgp bestpath compare-routerid} {} -@anchor{bgp bestpath compare-routerid} - -Ensure that when comparing routes where both are equal on most metrics, -including local-pref, AS_PATH length, IGP cost, MED, that the tie is broken -based on router-ID. - -If this option is enabled, then the already-selected check, where -already selected eBGP routes are preferred, is skipped. - -If a route has an @w{ORIGINATOR_ID} attribute because it has been reflected, -that @w{ORIGINATOR_ID} will be used. Otherwise, the router-ID of the peer the -route was received from will be used. - -The advantage of this is that the route-selection (at this point) will be -more deterministic. The disadvantage is that a few or even one lowest-ID -router may attract all trafic to otherwise-equal paths because of this -check. It may increase the possibility of MED or IGP oscillation, unless -other measures were taken to avoid these. The exact behaviour will be -sensitive to the iBGP and reflection topology. - -@end deffn - - -@node BGP route flap dampening -@subsection BGP route flap dampening - -@deffn {BGP} {bgp dampening @var{<1-45>} @var{<1-20000>} @var{<1-20000>} @var{<1-255>}} {} -This command enables BGP route-flap dampening and specifies dampening parameters. - -@table @asis -@item @asis{half-life} -Half-life time for the penalty -@item @asis{reuse-threshold} -Value to start reusing a route -@item @asis{suppress-threshold} -Value to start suppressing a route -@item @asis{max-suppress} -Maximum duration to suppress a stable route -@end table - -The route-flap damping algorithm is compatible with @cite{RFC2439}. The use of this command -is not recommended nowadays, see @uref{http://www.ripe.net/ripe/docs/ripe-378,,RIPE-378}. -@end deffn - -@node BGP MED -@section BGP MED - -The BGP MED (Multi_Exit_Discriminator) attribute has properties which can -cause subtle convergence problems in BGP. These properties and problems -have proven to be hard to understand, at least historically, and may still -not be widely understood. The following attempts to collect together and -present what is known about MED, to help operators and Frr users in -designing and configuring their networks. - -The BGP @acronym{MED, Multi_Exit_Discriminator} attribute is intended to -allow one AS to indicate its preferences for its ingress points to another -AS. The MED attribute will not be propagated on to another AS by the -receiving AS - it is `non-transitive' in the BGP sense. - -E.g., if AS X and AS Y have 2 different BGP peering points, then AS X -might set a MED of 100 on routes advertised at one and a MED of 200 at the -other. When AS Y selects between otherwise equal routes to or via -AS X, AS Y should prefer to take the path via the lower MED peering of 100 with -AS X. Setting the MED allows an AS to influence the routing taken to it -within another, neighbouring AS. - -In this use of MED it is not really meaningful to compare the MED value on -routes where the next AS on the paths differs. E.g., if AS Y also had a -route for some destination via AS Z in addition to the routes from AS X, and -AS Z had also set a MED, it wouldn't make sense for AS Y to compare AS Z's -MED values to those of AS X. The MED values have been set by different -administrators, with different frames of reference. - -The default behaviour of BGP therefore is to not compare MED values across -routes received from different neighbouring ASes. In Frr this is done by -comparing the neighbouring, left-most AS in the received AS_PATHs of the -routes and only comparing MED if those are the same. - -@c TeXInfo uses the old, non-UTF-8 capable, pdftex, and so -@c doesn't render TeX the unicode precedes character correctly in PDF, etc. -@c Using a TeX code on the other hand doesn't work for non-TeX outputs -@c (plaintext, e.g.). So, use an output-conditional macro. - -@iftex -@macro mprec{} -@math{\\prec} -@end macro -@end iftex - -@ifnottex -@macro mprec{} -@math{≺} -@end macro -@end ifnottex - -Unfortunately, this behaviour of MED, of sometimes being compared across -routes and sometimes not, depending on the properties of those other routes, -means MED can cause the order of preference over all the routes to be -undefined. That is, given routes A, B, and C, if A is preferred to B, and B -is preferred to C, then a well-defined order should mean the preference is -transitive (in the sense of orders @footnote{For some set of objects to have -an order, there @emph{must} be some binary ordering relation that is defined -for @emph{every} combination of those objects, and that relation @emph{must} -be transitive. I.e.@:, if the relation operator is @mprec{}, and if -a @mprec{} b and b @mprec{} c then that relation must carry over -and it @emph{must} be that a @mprec{} c for the objects to have an -order. The ordering relation may allow for equality, i.e. -a @mprec{} b and b @mprec{} a may both be true amd imply that -a and b are equal in the order and not distinguished by it, in -which case the set has a partial order. Otherwise, if there is an order, -all the objects have a distinct place in the order and the set has a total -order.}) and that A would be preferred to C. - -However, when MED is involved this need not be the case. With MED it is -possible that C is actually preferred over A. So A is preferred to B, B is -preferred to C, but C is preferred to A. This can be true even where BGP -defines a deterministic ``most preferred'' route out of the full set of -A,B,C. With MED, for any given set of routes there may be a -deterministically preferred route, but there need not be any way to arrange -them into any order of preference. With unmodified MED, the order of -preference of routes literally becomes undefined. - -That MED can induce non-transitive preferences over routes can cause issues. -Firstly, it may be perceived to cause routing table churn locally at -speakers; secondly, and more seriously, it may cause routing instability in -iBGP topologies, where sets of speakers continually oscillate between -different paths. - -The first issue arises from how speakers often implement routing decisions. -Though BGP defines a selection process that will deterministically select -the same route as best at any given speaker, even with MED, that process -requires evaluating all routes together. For performance and ease of -implementation reasons, many implementations evaluate route preferences in a -pair-wise fashion instead. Given there is no well-defined order when MED is -involved, the best route that will be chosen becomes subject to -implementation details, such as the order the routes are stored in. That -may be (locally) non-deterministic, e.g.@: it may be the order the routes -were received in. - -This indeterminism may be considered undesirable, though it need not cause -problems. It may mean additional routing churn is perceived, as sometimes -more updates may be produced than at other times in reaction to some event . - -This first issue can be fixed with a more deterministic route selection that -ensures routes are ordered by the neighbouring AS during selection. -@xref{bgp deterministic-med}. This may reduce the number of updates as -routes are received, and may in some cases reduce routing churn. Though, it -could equally deterministically produce the largest possible set of updates -in response to the most common sequence of received updates. - -A deterministic order of evaluation tends to imply an additional overhead of -sorting over any set of n routes to a destination. The implementation of -deterministic MED in Frr scales significantly worse than most sorting -algorithms at present, with the number of paths to a given destination. -That number is often low enough to not cause any issues, but where there are -many paths, the deterministic comparison may quickly become increasingly -expensive in terms of CPU. - -Deterministic local evaluation can @emph{not} fix the second, more major, -issue of MED however. Which is that the non-transitive preference of routes -MED can cause may lead to routing instability or oscillation across multiple -speakers in iBGP topologies. This can occur with full-mesh iBGP, but is -particularly problematic in non-full-mesh iBGP topologies that further -reduce the routing information known to each speaker. This has primarily -been documented with iBGP route-reflection topologies. However, any -route-hiding technologies potentially could also exacerbate oscillation with -MED. - -This second issue occurs where speakers each have only a subset of routes, -and there are cycles in the preferences between different combinations of -routes - as the undefined order of preference of MED allows - and the routes -are distributed in a way that causes the BGP speakers to 'chase' those -cycles. This can occur even if all speakers use a deterministic order of -evaluation in route selection. - -E.g., speaker 4 in AS A might receive a route from speaker 2 in AS X, and -from speaker 3 in AS Y; while speaker 5 in AS A might receive that route -from speaker 1 in AS Y. AS Y might set a MED of 200 at speaker 1, and 100 -at speaker 3. I.e, using ASN:ID:MED to label the speakers: - -@example - - /---------------\ - X:2------|--A:4-------A:5--|-Y:1:200 - Y:3:100--|-/ | - \---------------/ - -@end example - -Assuming all other metrics are equal (AS_PATH, ORIGIN, 0 IGP costs), then -based on the RFC4271 decision process speaker 4 will choose X:2 over -Y:3:100, based on the lower ID of 2. Speaker 4 advertises X:2 to speaker 5. -Speaker 5 will continue to prefer Y:1:200 based on the ID, and advertise -this to speaker 4. Speaker 4 will now have the full set of routes, and the -Y:1:200 it receives from 5 will beat X:2, but when speaker 4 compares -Y:1:200 to Y:3:100 the MED check now becomes active as the ASes match, and -now Y:3:100 is preferred. Speaker 4 therefore now advertises Y:3:100 to 5, -which will also agrees that Y:3:100 is preferred to Y:1:200, and so -withdraws the latter route from 4. Speaker 4 now has only X:2 and Y:3:100, -and X:2 beats Y:3:100, and so speaker 4 implicitly updates its route to -speaker 5 to X:2. Speaker 5 sees that Y:1:200 beats X:2 based on the ID, -and advertises Y:1:200 to speaker 4, and the cycle continues. - -The root cause is the lack of a clear order of preference caused by how MED -sometimes is and sometimes is not compared, leading to this cycle in the -preferences between the routes: - -@example - - /---> X:2 ---beats---> Y:3:100 --\ - | | - | | - \---beats--- Y:1:200 <---beats---/ - -@end example - -This particular type of oscillation in full-mesh iBGP topologies can be -avoided by speakers preferring already selected, external routes rather than -choosing to update to new a route based on a post-MED metric (e.g. -router-ID), at the cost of a non-deterministic selection process. Frr -implements this, as do many other implementations, so long as it is not -overridden by setting @ref{bgp bestpath compare-routerid}, and see also -@ref{BGP decision process}, . - -However, more complex and insidious cycles of oscillation are possible with -iBGP route-reflection, which are not so easily avoided. These have been -documented in various places. See, e.g., @cite{McPherson, D. and Gill, V. -and Walton, D., "Border Gateway Protocol (BGP) Persistent Route Oscillation -Condition", IETF RFC3345}, and @cite{Flavel, A. and M. Roughan, "Stable -and flexible iBGP", ACM SIGCOMM 2009}, and @cite{Griffin, T. and G. Wilfong, -"On the correctness of IBGP configuration", ACM SIGCOMM 2002} for concrete -examples and further references. - -There is as of this writing @emph{no} known way to use MED for its original -purpose; @emph{and} reduce routing information in iBGP topologies; -@emph{and} be sure to avoid the instability problems of MED due the -non-transitive routing preferences it can induce; in general on arbitrary -networks. - -There may be iBGP topology specific ways to reduce the instability risks, -even while using MED, e.g.@: by constraining the reflection topology and by -tuning IGP costs between route-reflector clusters, see RFC3345 for details. -In the near future, the Add-Path extension to BGP may also solve MED -oscillation while still allowing MED to be used as intended, by distributing -"best-paths per neighbour AS". This would be at the cost of distributing at -least as many routes to all speakers as a full-mesh iBGP would, if not more, -while also imposing similar CPU overheads as the "Deterministic MED" feature -at each Add-Path reflector. - -More generally, the instability problems that MED can introduce on more -complex, non-full-mesh, iBGP topologies may be avoided either by: - -@itemize - -@item -Setting @ref{bgp always-compare-med}, however this allows MED to be compared -across values set by different neighbour ASes, which may not produce -coherent desirable results, of itself. - -@item -Effectively ignoring MED by setting MED to the same value (e.g.@: 0) using -@ref{routemap set metric} on all received routes, in combination with -setting @ref{bgp always-compare-med} on all speakers. This is the simplest -and most performant way to avoid MED oscillation issues, where an AS is happy -not to allow neighbours to inject this problematic metric. - -@end itemize - -As MED is evaluated after the AS_PATH length check, another possible use for -MED is for intra-AS steering of routes with equal AS_PATH length, as an -extension of the last case above. As MED is evaluated before IGP metric, -this can allow cold-potato routing to be implemented to send traffic to -preferred hand-offs with neighbours, rather than the closest hand-off -according to the IGP metric. - -Note that even if action is taken to address the MED non-transitivity -issues, other oscillations may still be possible. E.g., on IGP cost if -iBGP and IGP topologies are at cross-purposes with each other - see the -Flavel and Roughan paper above for an example. Hence the guideline that the -iBGP topology should follow the IGP topology. - -@deffn {BGP} {bgp deterministic-med} {} -@anchor{bgp deterministic-med} - -Carry out route-selection in way that produces deterministic answers -locally, even in the face of MED and the lack of a well-defined order of -preference it can induce on routes. Without this option the preferred route -with MED may be determined largely by the order that routes were received -in. - -Setting this option will have a performance cost that may be noticeable when -there are many routes for each destination. Currently in Frr it is -implemented in a way that scales poorly as the number of routes per -destination increases. - -The default is that this option is not set. -@end deffn - -Note that there are other sources of indeterminism in the route selection -process, specifically, the preference for older and already selected routes -from eBGP peers, @xref{BGP decision process}. - -@deffn {BGP} {bgp always-compare-med} {} -@anchor{bgp always-compare-med} - -Always compare the MED on routes, even when they were received from -different neighbouring ASes. Setting this option makes the order of -preference of routes more defined, and should eliminate MED induced -oscillations. - -If using this option, it may also be desirable to use @ref{routemap set -metric} to set MED to 0 on routes received from external neighbours. - -This option can be used, together with @ref{routemap set metric} to use MED -as an intra-AS metric to steer equal-length AS_PATH routes to, e.g., desired -exit points. -@end deffn - - - -@node BGP network -@section BGP network - -@menu -* BGP route:: -* Route Aggregation:: -* Redistribute to BGP:: -@end menu - -@node BGP route -@subsection BGP route - -@deffn {BGP} {network @var{A.B.C.D/M}} {} -This command adds the announcement network. -@example -@group -router bgp 1 - address-family ipv4 unicast - network 10.0.0.0/8 - exit-address-family -@end group -@end example -This configuration example says that network 10.0.0.0/8 will be -announced to all neighbors. Some vendors' routers don't advertise -routes if they aren't present in their IGP routing tables; @code{bgpd} -doesn't care about IGP routes when announcing its routes. -@end deffn - -@deffn {BGP} {no network @var{A.B.C.D/M}} {} -@end deffn - -@node Route Aggregation -@subsection Route Aggregation - -@deffn {BGP} {aggregate-address @var{A.B.C.D/M}} {} -This command specifies an aggregate address. -@end deffn - -@deffn {BGP} {aggregate-address @var{A.B.C.D/M} as-set} {} -This command specifies an aggregate address. Resulting routes include -AS set. -@end deffn - -@deffn {BGP} {aggregate-address @var{A.B.C.D/M} summary-only} {} -This command specifies an aggregate address. Aggreated routes will -not be announce. -@end deffn - -@deffn {BGP} {no aggregate-address @var{A.B.C.D/M}} {} -@end deffn - -@node Redistribute to BGP -@subsection Redistribute to BGP - -@deffn {BGP} {redistribute kernel} {} -Redistribute kernel route to BGP process. -@end deffn - -@deffn {BGP} {redistribute static} {} -Redistribute static route to BGP process. -@end deffn - -@deffn {BGP} {redistribute connected} {} -Redistribute connected route to BGP process. -@end deffn - -@deffn {BGP} {redistribute rip} {} -Redistribute RIP route to BGP process. -@end deffn - -@deffn {BGP} {redistribute ospf} {} -Redistribute OSPF route to BGP process. -@end deffn - -@deffn {BGP} {redistribute vpn} {} -Redistribute VNC routes to BGP process. -@end deffn - -@deffn {BGP} {update-delay @var{max-delay}} {} -@deffnx {BGP} {update-delay @var{max-delay} @var{establish-wait}} {} -This feature is used to enable read-only mode on BGP process restart or when -BGP process is cleared using 'clear ip bgp *'. When applicable, read-only mode -would begin as soon as the first peer reaches Established status and a timer -for max-delay seconds is started. - -During this mode BGP doesn't run any best-path or generate any updates to its -peers. This mode continues until: -1. All the configured peers, except the shutdown peers, have sent explicit EOR -(End-Of-RIB) or an implicit-EOR. The first keep-alive after BGP has reached -Established is considered an implicit-EOR. - If the establish-wait optional value is given, then BGP will wait for - peers to reach established from the begining of the update-delay till the - establish-wait period is over, i.e. the minimum set of established peers for - which EOR is expected would be peers established during the establish-wait - window, not necessarily all the configured neighbors. -2. max-delay period is over. -On hitting any of the above two conditions, BGP resumes the decision process -and generates updates to its peers. - -Default max-delay is 0, i.e. the feature is off by default. -@end deffn - -@deffn {BGP} {table-map @var{route-map-name}} {} -This feature is used to apply a route-map on route updates from BGP to Zebra. -All the applicable match operations are allowed, such as match on prefix, -next-hop, communities, etc. Set operations for this attach-point are limited -to metric and next-hop only. Any operation of this feature does not affect -BGPs internal RIB. - -Supported for ipv4 and ipv6 address families. It works on multi-paths as well, -however, metric setting is based on the best-path only. -@end deffn - -@node BGP Peer -@section BGP Peer - -@menu -* Defining Peer:: -* BGP Peer commands:: -* Peer filtering:: -@end menu - -@node Defining Peer -@subsection Defining Peer - -@deffn {BGP} {neighbor @var{peer} remote-as @var{asn}} {} -Creates a new neighbor whose remote-as is @var{asn}. @var{peer} -can be an IPv4 address or an IPv6 address. -@example -@group -router bgp 1 - neighbor 10.0.0.1 remote-as 2 -@end group -@end example -In this case my router, in AS-1, is trying to peer with AS-2 at -10.0.0.1. - -This command must be the first command used when configuring a neighbor. -If the remote-as is not specified, @command{bgpd} will complain like this: -@example -can't find neighbor 10.0.0.1 -@end example -@end deffn - -@node BGP Peer commands -@subsection BGP Peer commands - -In a @code{router bgp} clause there are neighbor specific configurations -required. - -@deffn {BGP} {neighbor @var{peer} shutdown} {} -@deffnx {BGP} {no neighbor @var{peer} shutdown} {} -Shutdown the peer. We can delete the neighbor's configuration by -@code{no neighbor @var{peer} remote-as @var{as-number}} but all -configuration of the neighbor will be deleted. When you want to -preserve the configuration, but want to drop the BGP peer, use this -syntax. -@end deffn - -@deffn {BGP} {neighbor @var{peer} ebgp-multihop} {} -@deffnx {BGP} {no neighbor @var{peer} ebgp-multihop} {} -@end deffn - -@deffn {BGP} {neighbor @var{peer} description ...} {} -@deffnx {BGP} {no neighbor @var{peer} description ...} {} -Set description of the peer. -@end deffn - -@deffn {BGP} {neighbor @var{peer} version @var{version}} {} -Set up the neighbor's BGP version. @var{version} can be @var{4}, -@var{4+} or @var{4-}. BGP version @var{4} is the default value used for -BGP peering. BGP version @var{4+} means that the neighbor supports -Multiprotocol Extensions for BGP-4. BGP version @var{4-} is similar but -the neighbor speaks the old Internet-Draft revision 00's Multiprotocol -Extensions for BGP-4. Some routing software is still using this -version. -@end deffn - -@deffn {BGP} {neighbor @var{peer} interface @var{ifname}} {} -@deffnx {BGP} {no neighbor @var{peer} interface @var{ifname}} {} -When you connect to a BGP peer over an IPv6 link-local address, you -have to specify the @var{ifname} of the interface used for the -connection. To specify IPv4 session addresses, see the -@code{neighbor @var{peer} update-source} command below. - -This command is deprecated and may be removed in a future release. Its -use should be avoided. -@end deffn - -@deffn {BGP} {neighbor @var{peer} next-hop-self [all]} {} -@deffnx {BGP} {no neighbor @var{peer} next-hop-self [all]} {} -This command specifies an announced route's nexthop as being equivalent -to the address of the bgp router if it is learned via eBGP. -If the optional keyword @code{all} is specified the modifiation is done -also for routes learned via iBGP. -@end deffn - -@deffn {BGP} {neighbor @var{peer} update-source @var{}} {} -@deffnx {BGP} {no neighbor @var{peer} update-source} {} -Specify the IPv4 source address to use for the @acronym{BGP} session to this -neighbour, may be specified as either an IPv4 address directly or -as an interface name (in which case the @command{zebra} daemon MUST be running -in order for @command{bgpd} to be able to retrieve interface state). -@example -@group -router bgp 64555 - neighbor foo update-source 192.168.0.1 - neighbor bar update-source lo0 -@end group -@end example -@end deffn - -@deffn {BGP} {neighbor @var{peer} default-originate} {} -@deffnx {BGP} {no neighbor @var{peer} default-originate} {} -@command{bgpd}'s default is to not announce the default route (0.0.0.0/0) even it -is in routing table. When you want to announce default routes to the -peer, use this command. -@end deffn - -@deffn {BGP} {neighbor @var{peer} port @var{port}} {} -@deffnx {BGP} {neighbor @var{peer} port @var{port}} {} -@end deffn - -@deffn {BGP} {neighbor @var{peer} send-community} {} -@deffnx {BGP} {neighbor @var{peer} send-community} {} -@end deffn - -@deffn {BGP} {neighbor @var{peer} weight @var{weight}} {} -@deffnx {BGP} {no neighbor @var{peer} weight @var{weight}} {} -This command specifies a default @var{weight} value for the neighbor's -routes. -@end deffn - -@deffn {BGP} {neighbor @var{peer} maximum-prefix @var{number}} {} -@deffnx {BGP} {no neighbor @var{peer} maximum-prefix @var{number}} {} -@end deffn - -@deffn {BGP} {neighbor @var{peer} local-as @var{as-number}} {} -@deffnx {BGP} {neighbor @var{peer} local-as @var{as-number} no-prepend} {} -@deffnx {BGP} {neighbor @var{peer} local-as @var{as-number} no-prepend replace-as} {} -@deffnx {BGP} {no neighbor @var{peer} local-as} {} -Specify an alternate AS for this BGP process when interacting with the -specified peer. With no modifiers, the specified local-as is prepended to -the received AS_PATH when receiving routing updates from the peer, and -prepended to the outgoing AS_PATH (after the process local AS) when -transmitting local routes to the peer. - -If the no-prepend attribute is specified, then the supplied local-as is not -prepended to the received AS_PATH. - -If the replace-as attribute is specified, then only the supplied local-as is -prepended to the AS_PATH when transmitting local-route updates to this peer. - -Note that replace-as can only be specified if no-prepend is. - -This command is only allowed for eBGP peers. -@end deffn - -@deffn {BGP} {neighbor @var{peer} ttl-security hops @var{number}} {} -@deffnx {BGP} {no neighbor @var{peer} ttl-security hops @var{number}} {} -This command enforces Generalized TTL Security Mechanism (GTSM), as -specified in RFC 5082. With this command, only neighbors that are the -specified number of hops away will be allowed to become neighbors. This -command is mututally exclusive with @command{ebgp-multihop}. -@end deffn - -@node Peer filtering -@subsection Peer filtering - -@deffn {BGP} {neighbor @var{peer} distribute-list @var{name} [in|out]} {} -This command specifies a distribute-list for the peer. @var{direct} is -@samp{in} or @samp{out}. -@end deffn - -@deffn {BGP command} {neighbor @var{peer} prefix-list @var{name} [in|out]} {} -@end deffn - -@deffn {BGP command} {neighbor @var{peer} filter-list @var{name} [in|out]} {} -@end deffn - -@deffn {BGP} {neighbor @var{peer} route-map @var{name} [in|out]} {} -Apply a route-map on the neighbor. @var{direct} must be @code{in} or -@code{out}. -@end deffn - -@deffn {BGP} {bgp route-reflector allow-outbound-policy} {} -By default, attribute modification via route-map policy out is not reflected -on reflected routes. This option allows the modifications to be reflected as -well. Once enabled, it affects all reflected routes. -@end deffn - -@c ----------------------------------------------------------------------- -@node BGP Peer Group -@section BGP Peer Group - -@deffn {BGP} {neighbor @var{word} peer-group} {} -This command defines a new peer group. -@end deffn - -@deffn {BGP} {neighbor @var{peer} peer-group @var{word}} {} -This command bind specific peer to peer group @var{word}. -@end deffn - -@node BGP Address Family -@section BGP Address Family - -Multiprotocol BGP enables BGP to carry routing information for multiple -Network Layer protocols. BGP supports multiple Address Family -Identifier (AFI), namely IPv4 and IPv6. Support is also provided for -multiple sets of per-AFI information via Subsequent Address Family -Identifiers (SAFI). In addition to unicast information, VPN information -@cite{RFC4364} and @cite{RFC4659}, and Encapsulation information -@cite{RFC5512} is supported. - -@deffn {Command} {show ip bgp vpnv4 all} {} -@deffnx {Command} {show ipv6 bgp vpn all} {} -Print active IPV4 or IPV6 routes advertised via the VPN SAFI. -@end deffn - -@deffn {Command} {show ip bgp encap all} {} -@deffnx {Command} {show ipv6 bgp encap all} {} -Print active IPV4 or IPV6 routes advertised via the Encapsulation SAFI. -@end deffn - -@deffn {Command} {show bgp ipv4 encap summary} {} -@deffnx {Command} {show bgp ipv4 vpn summary} {} -@deffnx {Command} {show bgp ipv6 encap summary} {} -@deffnx {Command} {show bgp ipv6 vpn summary} {} -Print a summary of neighbor connections for the specified AFI/SAFI combination. -@end deffn - -@c ----------------------------------------------------------------------- -@node Autonomous System -@section Autonomous System - -The @acronym{AS,Autonomous System} number is one of the essential -element of BGP. BGP is a distance vector routing protocol, and the -AS-Path framework provides distance vector metric and loop detection to -BGP. @cite{RFC1930, Guidelines for creation, selection, and -registration of an Autonomous System (AS)} provides some background on -the concepts of an AS. - -The AS number is a two octet value, ranging in value from 1 to 65535. -The AS numbers 64512 through 65535 are defined as private AS numbers. -Private AS numbers must not to be advertised in the global Internet. - -@menu -* Display BGP Routes by AS Path:: -* AS Path Access List:: -* Using AS Path in Route Map:: -* Private AS Numbers:: -@end menu - -@node Display BGP Routes by AS Path -@subsection Display BGP Routes by AS Path - -To show BGP routes which has specific AS path information @code{show -ip bgp} command can be used. - -@deffn Command {show bgp @{ipv4|ipv6@} regexp @var{line}} {} -This commands displays BGP routes that matches a regular -expression @var{line} (@pxref{BGP Regular Expressions}). -@end deffn - -@node AS Path Access List -@subsection AS Path Access List - -AS path access list is user defined AS path. - -@deffn {Command} {ip as-path access-list @var{word} @{permit|deny@} @var{line}} {} -This command defines a new AS path access list. -@end deffn - -@deffn {Command} {no ip as-path access-list @var{word}} {} -@deffnx {Command} {no ip as-path access-list @var{word} @{permit|deny@} @var{line}} {} -@end deffn - -@node Using AS Path in Route Map -@subsection Using AS Path in Route Map - -@deffn {Route Map} {match as-path @var{word}} {} -@end deffn - -@deffn {Route Map} {set as-path prepend @var{as-path}} {} -Prepend the given string of AS numbers to the AS_PATH. -@end deffn - -@deffn {Route Map} {set as-path prepend last-as @var{num}} {} -Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. -@end deffn - -@node Private AS Numbers -@subsection Private AS Numbers - -@c ----------------------------------------------------------------------- -@node BGP Communities Attribute -@section BGP Communities Attribute - -BGP communities attribute is widely used for implementing policy -routing. Network operators can manipulate BGP communities attribute -based on their network policy. BGP communities attribute is defined -in @cite{RFC1997, BGP Communities Attribute} and -@cite{RFC1998, An Application of the BGP Community Attribute -in Multi-home Routing}. It is an optional transitive attribute, -therefore local policy can travel through different autonomous system. - -Communities attribute is a set of communities values. Each -communities value is 4 octet long. The following format is used to -define communities value. - -@table @code -@item AS:VAL -This format represents 4 octet communities value. @code{AS} is high -order 2 octet in digit format. @code{VAL} is low order 2 octet in -digit format. This format is useful to define AS oriented policy -value. For example, @code{7675:80} can be used when AS 7675 wants to -pass local policy value 80 to neighboring peer. -@item internet -@code{internet} represents well-known communities value 0. -@item no-export -@code{no-export} represents well-known communities value @code{NO_EXPORT}@* -@r{(0xFFFFFF01)}. All routes carry this value must not be advertised -to outside a BGP confederation boundary. If neighboring BGP peer is -part of BGP confederation, the peer is considered as inside a BGP -confederation boundary, so the route will be announced to the peer. -@item no-advertise -@code{no-advertise} represents well-known communities value -@code{NO_ADVERTISE}@*@r{(0xFFFFFF02)}. All routes carry this value -must not be advertise to other BGP peers. -@item local-AS -@code{local-AS} represents well-known communities value -@code{NO_EXPORT_SUBCONFED} @r{(0xFFFFFF03)}. All routes carry this -value must not be advertised to external BGP peers. Even if the -neighboring router is part of confederation, it is considered as -external BGP peer, so the route will not be announced to the peer. -@end table - - When BGP communities attribute is received, duplicated communities -value in the communities attribute is ignored and each communities -values are sorted in numerical order. - -@menu -* BGP Community Lists:: -* Numbered BGP Community Lists:: -* BGP Community in Route Map:: -* Display BGP Routes by Community:: -* Using BGP Communities Attribute:: -@end menu - -@node BGP Community Lists -@subsection BGP Community Lists - - BGP community list is a user defined BGP communites attribute list. -BGP community list can be used for matching or manipulating BGP -communities attribute in updates. - -There are two types of community list. One is standard community -list and another is expanded community list. Standard community list -defines communities attribute. Expanded community list defines -communities attribute string with regular expression. Standard -community list is compiled into binary format when user define it. -Standard community list will be directly compared to BGP communities -attribute in BGP updates. Therefore the comparison is faster than -expanded community list. - -@deffn Command {ip community-list standard @var{name} @{permit|deny@} @var{community}} {} -This command defines a new standard community list. @var{community} -is communities value. The @var{community} is compiled into community -structure. We can define multiple community list under same name. In -that case match will happen user defined order. Once the -community list matches to communities attribute in BGP updates it -return permit or deny by the community list definition. When there is -no matched entry, deny will be returned. When @var{community} is -empty it matches to any routes. -@end deffn - -@deffn Command {ip community-list expanded @var{name} @{permit|deny@} @var{line}} {} -This command defines a new expanded community list. @var{line} is a -string expression of communities attribute. @var{line} can be a -regular expression (@pxref{BGP Regular Expressions}) to match -the communities attribute in BGP updates. -@end deffn - -@deffn Command {no ip community-list @var{name}} {} -@deffnx Command {no ip community-list standard @var{name}} {} -@deffnx Command {no ip community-list expanded @var{name}} {} -These commands delete community lists specified by @var{name}. All of -community lists shares a single name space. So community lists can be -removed simpley specifying community lists name. -@end deffn - -@deffn {Command} {show ip community-list} {} -@deffnx {Command} {show ip community-list @var{name}} {} -This command displays current community list information. When -@var{name} is specified the specified community list's information is -shown. - -@example -# show ip community-list -Named Community standard list CLIST - permit 7675:80 7675:100 no-export - deny internet -Named Community expanded list EXPAND - permit : - -# show ip community-list CLIST -Named Community standard list CLIST - permit 7675:80 7675:100 no-export - deny internet -@end example -@end deffn - -@node Numbered BGP Community Lists -@subsection Numbered BGP Community Lists - -When number is used for BGP community list name, the number has -special meanings. Community list number in the range from 1 and 99 is -standard community list. Community list number in the range from 100 -to 199 is expanded community list. These community lists are called -as numbered community lists. On the other hand normal community lists -is called as named community lists. - -@deffn Command {ip community-list <1-99> @{permit|deny@} @var{community}} {} -This command defines a new community list. <1-99> is standard -community list number. Community list name within this range defines -standard community list. When @var{community} is empty it matches to -any routes. -@end deffn - -@deffn Command {ip community-list <100-199> @{permit|deny@} @var{community}} {} -This command defines a new community list. <100-199> is expanded -community list number. Community list name within this range defines -expanded community list. -@end deffn - -@deffn Command {ip community-list @var{name} @{permit|deny@} @var{community}} {} -When community list type is not specifed, the community list type is -automatically detected. If @var{community} can be compiled into -communities attribute, the community list is defined as a standard -community list. Otherwise it is defined as an expanded community -list. This feature is left for backward compability. Use of this -feature is not recommended. -@end deffn - -@node BGP Community in Route Map -@subsection BGP Community in Route Map - -In Route Map (@pxref{Route Map}), we can match or set BGP -communities attribute. Using this feature network operator can -implement their network policy based on BGP communities attribute. - -Following commands can be used in Route Map. - -@deffn {Route Map} {match community @var{word}} {} -@deffnx {Route Map} {match community @var{word} exact-match} {} -This command perform match to BGP updates using community list -@var{word}. When the one of BGP communities value match to the one of -communities value in community list, it is match. When -@code{exact-match} keyword is spcified, match happen only when BGP -updates have completely same communities value specified in the -community list. -@end deffn - -@deffn {Route Map} {set community none} {} -@deffnx {Route Map} {set community @var{community}} {} -@deffnx {Route Map} {set community @var{community} additive} {} -This command manipulate communities value in BGP updates. When -@code{none} is specified as communities value, it removes entire -communities attribute from BGP updates. When @var{community} is not -@code{none}, specified communities value is set to BGP updates. If -BGP updates already has BGP communities value, the existing BGP -communities value is replaced with specified @var{community} value. -When @code{additive} keyword is specified, @var{community} is appended -to the existing communities value. -@end deffn - -@deffn {Route Map} {set comm-list @var{word} delete} {} -This command remove communities value from BGP communities attribute. -The @var{word} is community list name. When BGP route's communities -value matches to the community list @var{word}, the communities value -is removed. When all of communities value is removed eventually, the -BGP update's communities attribute is completely removed. -@end deffn - -@node Display BGP Routes by Community -@subsection Display BGP Routes by Community - -To show BGP routes which has specific BGP communities attribute, -@code{show bgp @{ipv4|ipv6@}} command can be used. The -@var{community} and @var{community-list} subcommand can be used. - -@deffn Command {show bgp @{ipv4|ipv6@} community} {} -@deffnx Command {show bgp @{ipv4|ipv6@} community @var{community}} {} -@deffnx Command {show bgp @{ipv4|ipv6@} community @var{community} exact-match} {} -@code{show bgp @{ipv4|ipv6@} community} displays BGP routes which has communities -attribute. Where the address family can be IPv4 or IPv6 among others. When -@var{community} is specified, BGP routes that matches @var{community} value is -displayed. For this command, @code{internet} keyword can't be used for -@var{community} value. When @code{exact-match} is specified, it display only -routes that have an exact match. -@end deffn - -@deffn Command {show bgp @{ipv4|ipv6@} community-list @var{word}} {} -@deffnx Command {show bgp @{ipv4|ipv6@} community-list @var{word} exact-match} {} -This commands display BGP routes for the address family specified that matches -community list @var{word}. When @code{exact-match} is specified, display only -routes that have an exact match. -@end deffn - -@node Using BGP Communities Attribute -@subsection Using BGP Communities Attribute - -Following configuration is the most typical usage of BGP communities -attribute. AS 7675 provides upstream Internet connection to AS 100. -When following configuration exists in AS 7675, AS 100 networks -operator can set local preference in AS 7675 network by setting BGP -communities attribute to the updates. - -@example -router bgp 7675 - neighbor 192.168.0.1 remote-as 100 - address-family ipv4 unicast - neighbor 192.168.0.1 route-map RMAP in - exit-address-family -! -ip community-list 70 permit 7675:70 -ip community-list 70 deny -ip community-list 80 permit 7675:80 -ip community-list 80 deny -ip community-list 90 permit 7675:90 -ip community-list 90 deny -! -route-map RMAP permit 10 - match community 70 - set local-preference 70 -! -route-map RMAP permit 20 - match community 80 - set local-preference 80 -! -route-map RMAP permit 30 - match community 90 - set local-preference 90 -@end example - -Following configuration announce 10.0.0.0/8 from AS 100 to AS 7675. -The route has communities value 7675:80 so when above configuration -exists in AS 7675, announced route's local preference will be set to -value 80. - -@example -router bgp 100 - network 10.0.0.0/8 - neighbor 192.168.0.2 remote-as 7675 - address-family ipv4 unicast - neighbor 192.168.0.2 route-map RMAP out - exit-address-family -! -ip prefix-list PLIST permit 10.0.0.0/8 -! -route-map RMAP permit 10 - match ip address prefix-list PLIST - set community 7675:80 -@end example - -Following configuration is an example of BGP route filtering using -communities attribute. This configuration only permit BGP routes -which has BGP communities value 0:80 or 0:90. Network operator can -put special internal communities value at BGP border router, then -limit the BGP routes announcement into the internal network. - -@example -router bgp 7675 - neighbor 192.168.0.1 remote-as 100 - address-family ipv4 unicast - neighbor 192.168.0.1 route-map RMAP in - exit-address-family -! -ip community-list 1 permit 0:80 0:90 -! -route-map RMAP permit in - match community 1 -@end example - -Following exmaple filter BGP routes which has communities value 1:1. -When there is no match community-list returns deny. To avoid -filtering all of routes, we need to define permit any at last. - -@example -router bgp 7675 - neighbor 192.168.0.1 remote-as 100 - address-family ipv4 unicast - neighbor 192.168.0.1 route-map RMAP in - exit-address-family -! -ip community-list standard FILTER deny 1:1 -ip community-list standard FILTER permit -! -route-map RMAP permit 10 - match community FILTER -@end example - -Communities value keyword @code{internet} has special meanings in -standard community lists. In below example @code{internet} act as -match any. It matches all of BGP routes even if the route does not -have communities attribute at all. So community list @code{INTERNET} -is same as above example's @code{FILTER}. - -@example -ip community-list standard INTERNET deny 1:1 -ip community-list standard INTERNET permit internet -@end example - -Following configuration is an example of communities value deletion. -With this configuration communities value 100:1 and 100:2 is removed -from BGP updates. For communities value deletion, only @code{permit} -community-list is used. @code{deny} community-list is ignored. - -@example -router bgp 7675 - neighbor 192.168.0.1 remote-as 100 - address-family ipv4 unicast - neighbor 192.168.0.1 route-map RMAP in - exit-address-family -! -ip community-list standard DEL permit 100:1 100:2 -! -route-map RMAP permit 10 - set comm-list DEL delete -@end example - -@c ----------------------------------------------------------------------- -@node BGP Extended Communities Attribute -@section BGP Extended Communities Attribute - -BGP extended communities attribute is introduced with MPLS VPN/BGP -technology. MPLS VPN/BGP expands capability of network infrastructure -to provide VPN functionality. At the same time it requires a new -framework for policy routing. With BGP Extended Communities Attribute -we can use Route Target or Site of Origin for implementing network -policy for MPLS VPN/BGP. - -BGP Extended Communities Attribute is similar to BGP Communities -Attribute. It is an optional transitive attribute. BGP Extended -Communities Attribute can carry multiple Extended Community value. -Each Extended Community value is eight octet length. - -BGP Extended Communities Attribute provides an extended range -compared with BGP Communities Attribute. Adding to that there is a -type field in each value to provides community space structure. - -There are two format to define Extended Community value. One is AS -based format the other is IP address based format. - -@table @code -@item AS:VAL -This is a format to define AS based Extended Community value. -@code{AS} part is 2 octets Global Administrator subfield in Extended -Community value. @code{VAL} part is 4 octets Local Administrator -subfield. @code{7675:100} represents AS 7675 policy value 100. -@item IP-Address:VAL -This is a format to define IP address based Extended Community value. -@code{IP-Address} part is 4 octets Global Administrator subfield. -@code{VAL} part is 2 octets Local Administrator subfield. -@code{10.0.0.1:100} represents -@end table - -@menu -* BGP Extended Community Lists:: -* BGP Extended Communities in Route Map:: -@end menu - -@node BGP Extended Community Lists -@subsection BGP Extended Community Lists - -Expanded Community Lists is a user defined BGP Expanded Community -Lists. - -@deffn Command {ip extcommunity-list standard @var{name} @{permit|deny@} @var{extcommunity}} {} -This command defines a new standard extcommunity-list. -@var{extcommunity} is extended communities value. The -@var{extcommunity} is compiled into extended community structure. We -can define multiple extcommunity-list under same name. In that case -match will happen user defined order. Once the extcommunity-list -matches to extended communities attribute in BGP updates it return -permit or deny based upon the extcommunity-list definition. When -there is no matched entry, deny will be returned. When -@var{extcommunity} is empty it matches to any routes. -@end deffn - -@deffn Command {ip extcommunity-list expanded @var{name} @{permit|deny@} @var{line}} {} -This command defines a new expanded extcommunity-list. @var{line} is -a string expression of extended communities attribute. @var{line} can -be a regular expression (@pxref{BGP Regular Expressions}) to match an -extended communities attribute in BGP updates. -@end deffn - -@deffn Command {no ip extcommunity-list @var{name}} {} -@deffnx Command {no ip extcommunity-list standard @var{name}} {} -@deffnx Command {no ip extcommunity-list expanded @var{name}} {} -These commands delete extended community lists specified by -@var{name}. All of extended community lists shares a single name -space. So extended community lists can be removed simpley specifying -the name. -@end deffn - -@deffn {Command} {show ip extcommunity-list} {} -@deffnx {Command} {show ip extcommunity-list @var{name}} {} -This command displays current extcommunity-list information. When -@var{name} is specified the community list's information is shown. - -@example -# show ip extcommunity-list -@end example -@end deffn - -@node BGP Extended Communities in Route Map -@subsection BGP Extended Communities in Route Map - -@deffn {Route Map} {match extcommunity @var{word}} {} -@end deffn - -@deffn {Route Map} {set extcommunity rt @var{extcommunity}} {} -This command set Route Target value. -@end deffn - -@deffn {Route Map} {set extcommunity soo @var{extcommunity}} {} -This command set Site of Origin value. -@end deffn - -@c ----------------------------------------------------------------------- -@node BGP Large Communities Attribute -@section BGP Large Communities Attribute - -The BGP Large Communities attribute was introduced in Feb 2017 with -@cite{RFC8092, BGP Large Communities Attribute}. - -The BGP Large Communities Attribute is similar to the BGP Communities -Attribute except that it has 3 components instead of two and each of -which are 4 octets in length. Large Communities bring additional -functionality and convenience over traditional communities, specifically -the fact that the @code{GLOBAL} part below is now 4 octets wide allowing -AS4 operators seamless use. - -@table @code -@item GLOBAL:LOCAL1:LOCAL2 -This is the format to define Large Community values. Referencing -@cite{RFC8195, Use of BGP Large Communities} the values are commonly -referred to as follows. -The @code{GLOBAL} part is a 4 octet Global Administrator field, common -use of this field is the operators AS number. -The @code{LOCAL1} part is a 4 octet Local Data Part 1 subfield referred -to as a function. -The @code{LOCAL2} part is a 4 octet Local Data Part 2 field and referred -to as the parameter subfield. @code{65551:1:10} represents AS 65551 -function 1 and parameter 10. -The referenced RFC above gives some guidelines on recommended usage. -@end table - -@menu -* BGP Large Community Lists:: -* BGP Large Communities in Route Map:: -@end menu - -@node BGP Large Community Lists -@subsection BGP Large Community Lists - -Two types of large community lists are supported, namely @code{standard} and -@code{expanded}. - -@deffn Command {ip large-community-list standard @var{name} @{permit|deny@} @var{large-community}} {} -This command defines a new standard large-community-list. -@var{large-community} is the Large Community value. We -can add multiple large communities under same name. In that case -the match will happen in the user defined order. Once the large-community-list -matches the Large Communities attribute in BGP updates it will return -permit or deny based upon the large-community-list definition. When -there is no matched entry, a deny will be returned. When @var{large-community} -is empty it matches any routes. -@end deffn - -@deffn Command {ip large-community-list expanded @var{name} @{permit|deny@} @var{line}} {} -This command defines a new expanded large-community-list. Where @var{line} is -a string matching expression, it will be compared to the entire Large Communities -attribute as a string, with each large-community in order from lowest to highest. -@var{line} can also be a regular expression which matches this Large -Community attribute. -@end deffn - -@deffn Command {no ip large-community-list @var{name}} {} -@deffnx Command {no ip large-community-list standard @var{name}} {} -@deffnx Command {no ip large-community-list expanded @var{name}} {} -These commands delete Large Community lists specified by -@var{name}. All Large Community lists share a single namespace. -This means Large Community lists can be removed by simply specifying the name. -@end deffn - -@deffn {Command} {show ip large-community-list} {} -@deffnx {Command} {show ip large-community-list @var{name}} {} -This command display current large-community-list information. When -@var{name} is specified the community list information is shown. -@end deffn - -@deffn {Command} {show ip bgp large-community-info} {} -This command displays the current large communities in use. -@end deffn - -@node BGP Large Communities in Route Map -@subsection BGP Large Communities in Route Map - -@deffn {Route Map} {match large-community @var{line}} {} -Where @var{line} can be a simple string to match, or a regular expression. -It is very important to note that this match occurs on the entire -large-community string as a whole, where each large-community is ordered -from lowest to highest. -@end deffn - -@deffn {Route Map} {set large-community @var{large-community}} {} -@deffnx {Route Map} {set large-community @var{large-community} @var{large-community}} {} -@deffnx {Route Map} {set large-community @var{large-community} additive} {} -These commands are used for setting large-community values. The first -command will overwrite any large-communities currently present. -The second specifies two large-communities, which overwrites the current -large-community list. The third will add a large-community value without -overwriting other values. Multiple large-community values can be specified. -@end deffn - -@c ----------------------------------------------------------------------- - -@node Displaying BGP information -@section Displaying BGP information - -@menu -* Showing BGP information:: -* Other BGP commands:: -@end menu - -@node Showing BGP information -@subsection Showing BGP information - -@deffn {Command} {show ip bgp} {} -@deffnx {Command} {show ip bgp @var{A.B.C.D}} {} -@deffnx {Command} {show ip bgp @var{X:X::X:X}} {} -This command displays BGP routes. When no route is specified it -display all of IPv4 BGP routes. -@end deffn - -@example -BGP table version is 0, local router ID is 10.1.1.1 -Status codes: s suppressed, d damped, h history, * valid, > best, i - internal -Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path -*> 1.1.1.1/32 0.0.0.0 0 32768 i - -Total number of prefixes 1 -@end example - -@deffn {Command} {show ip bgp regexp @var{line}} {} -This command displays BGP routes using AS path regular expression -(@pxref{BGP Regular Expressions}). -@end deffn - -@deffn Command {show ip bgp community @var{community}} {} -@deffnx Command {show ip bgp community @var{community} exact-match} {} -This command displays BGP routes using @var{community} (@pxref{Display -BGP Routes by Community}). -@end deffn - -@deffn Command {show ip bgp community-list @var{word}} {} -@deffnx Command {show ip bgp community-list @var{word} exact-match} {} -This command displays BGP routes using community list (@pxref{Display -BGP Routes by Community}). -@end deffn - -@deffn {Command} {show bgp @{ipv4|ipv6@} summary} {} -Show a bgp peer summary for the specified address family. -@end deffn - -@deffn {Command} {show bgp @{ipv4|ipv6@} neighbor [@var{peer}]} {} -This command shows information on a specific BGP @var{peer}. -@end deffn - -@deffn {Command} {show bgp @{ipv4|ipv6@} dampening dampened-paths} {} -Display paths suppressed due to dampening. -@end deffn - -@deffn {Command} {show bgp @{ipv4|ipv6@} dampening flap-statistics} {} -Display flap statistics of routes. -@end deffn - -@node Other BGP commands -@subsection Other BGP commands - -@deffn {Command} {clear bgp @{ipv4|ipv6@} *} {} -Clear all address family peers. -@end deffn - -@deffn {Command} {clear bgp @{ipv4|ipv6@} @var{peer}} {} -Clear peers which have addresses of X.X.X.X -@end deffn - -@deffn {Command} {clear bgp @{ipv4|ipv6@} @var{peer} soft in} {} -Clear peer using soft reconfiguration. -@end deffn - -@deffn {Command} {show debug} {} -@end deffn - -@deffn {Command} {debug event} {} -@end deffn - -@deffn {Command} {debug update} {} -@end deffn - -@deffn {Command} {debug keepalive} {} -@end deffn - -@deffn {Command} {no debug event} {} -@end deffn - -@deffn {Command} {no debug update} {} -@end deffn - -@deffn {Command} {no debug keepalive} {} -@end deffn - -@node Capability Negotiation -@section Capability Negotiation - -When adding IPv6 routing information exchange feature to BGP. There -were some proposals. @acronym{IETF,Internet Engineering Task Force} -@acronym{IDR, Inter Domain Routing} @acronym{WG, Working group} adopted -a proposal called Multiprotocol Extension for BGP. The specification -is described in @cite{RFC2283}. The protocol does not define new protocols. -It defines new attributes to existing BGP. When it is used exchanging -IPv6 routing information it is called BGP-4+. When it is used for -exchanging multicast routing information it is called MBGP. - -@command{bgpd} supports Multiprotocol Extension for BGP. So if remote -peer supports the protocol, @command{bgpd} can exchange IPv6 and/or -multicast routing information. - -Traditional BGP did not have the feature to detect remote peer's -capabilities, e.g. whether it can handle prefix types other than IPv4 -unicast routes. This was a big problem using Multiprotocol Extension -for BGP to operational network. @cite{RFC2842, Capabilities -Advertisement with BGP-4} adopted a feature called Capability -Negotiation. @command{bgpd} use this Capability Negotiation to detect -the remote peer's capabilities. If the peer is only configured as IPv4 -unicast neighbor, @command{bgpd} does not send these Capability -Negotiation packets (at least not unless other optional BGP features -require capability negotation). - -By default, Frr will bring up peering with minimal common capability -for the both sides. For example, local router has unicast and -multicast capabilitie and remote router has unicast capability. In -this case, the local router will establish the connection with unicast -only capability. When there are no common capabilities, Frr sends -Unsupported Capability error and then resets the connection. - -If you want to completely match capabilities with remote peer. Please -use @command{strict-capability-match} command. - -@deffn {BGP} {neighbor @var{peer} strict-capability-match} {} -@deffnx {BGP} {no neighbor @var{peer} strict-capability-match} {} -Strictly compares remote capabilities and local capabilities. If capabilities -are different, send Unsupported Capability error then reset connection. -@end deffn - -You may want to disable sending Capability Negotiation OPEN message -optional parameter to the peer when remote peer does not implement -Capability Negotiation. Please use @command{dont-capability-negotiate} -command to disable the feature. - -@deffn {BGP} {neighbor @var{peer} dont-capability-negotiate} {} -@deffnx {BGP} {no neighbor @var{peer} dont-capability-negotiate} {} -Suppress sending Capability Negotiation as OPEN message optional -parameter to the peer. This command only affects the peer is configured -other than IPv4 unicast configuration. -@end deffn - -When remote peer does not have capability negotiation feature, remote -peer will not send any capabilities at all. In that case, bgp -configures the peer with configured capabilities. - -You may prefer locally configured capabilities more than the negotiated -capabilities even though remote peer sends capabilities. If the peer -is configured by @command{override-capability}, @command{bgpd} ignores -received capabilities then override negotiated capabilities with -configured values. - -@deffn {BGP} {neighbor @var{peer} override-capability} {} -@deffnx {BGP} {no neighbor @var{peer} override-capability} {} -Override the result of Capability Negotiation with local configuration. -Ignore remote peer's capability value. -@end deffn - -@node Route Reflector -@section Route Reflector - -@deffn {BGP} {bgp cluster-id @var{a.b.c.d}} {} -@end deffn - -@deffn {BGP} {neighbor @var{peer} route-reflector-client} {} -@deffnx {BGP} {no neighbor @var{peer} route-reflector-client} {} -@end deffn - -@node Route Server -@section Route Server - -At an Internet Exchange point, many ISPs are connected to each other by -external BGP peering. Normally these external BGP connection are done by -@samp{full mesh} method. As with internal BGP full mesh formation, -this method has a scaling problem. - -This scaling problem is well known. Route Server is a method to resolve -the problem. Each ISP's BGP router only peers to Route Server. Route -Server serves as BGP information exchange to other BGP routers. By -applying this method, numbers of BGP connections is reduced from -O(n*(n-1)/2) to O(n). - -Unlike normal BGP router, Route Server must have several routing tables -for managing different routing policies for each BGP speaker. We call the -routing tables as different @code{view}s. @command{bgpd} can work as -normal BGP router or Route Server or both at the same time. - -@menu -* Multiple instance:: -* BGP instance and view:: -* Routing policy:: -* Viewing the view:: -@end menu - -@node Multiple instance -@subsection Multiple instance - -To enable multiple view function of @code{bgpd}, you must turn on -multiple instance feature beforehand. - -@deffn {Command} {bgp multiple-instance} {} -Enable BGP multiple instance feature. After this feature is enabled, -you can make multiple BGP instances or multiple BGP views. -@end deffn - -@deffn {Command} {no bgp multiple-instance} {} -Disable BGP multiple instance feature. You can not disable this feature -when BGP multiple instances or views exist. -@end deffn - -When you want to make configuration more Cisco like one, - -@deffn {Command} {bgp config-type cisco} {} -Cisco compatible BGP configuration output. -@end deffn - -When bgp config-type cisco is specified, - -``no synchronization'' is displayed. -``no auto-summary'' is displayed. - -``network'' and ``aggregate-address'' argument is displayed as -``A.B.C.D M.M.M.M'' - -Frr: network 10.0.0.0/8 -Cisco: network 10.0.0.0 - -Frr: aggregate-address 192.168.0.0/24 -Cisco: aggregate-address 192.168.0.0 255.255.255.0 - -Community attribute handling is also different. If there is no -configuration is specified community attribute and extended community -attribute are sent to neighbor. When user manually disable the -feature community attribute is not sent to the neighbor. In case of -@command{bgp config-type cisco} is specified, community attribute is not -sent to the neighbor by default. To send community attribute user has -to specify @command{neighbor A.B.C.D send-community} command. - -@example -! -router bgp 1 - neighbor 10.0.0.1 remote-as 1 - address-family ipv4 unicast - no neighbor 10.0.0.1 send-community - exit-address-family -! -router bgp 1 - neighbor 10.0.0.1 remote-as 1 - address-family ipv4 unicast - neighbor 10.0.0.1 send-community - exit-address-family -! -@end example - -@deffn {Command} {bgp config-type zebra} {} -Frr style BGP configuration. This is default. -@end deffn - -@node BGP instance and view -@subsection BGP instance and view - -BGP instance is a normal BGP process. The result of route selection -goes to the kernel routing table. You can setup different AS at the -same time when BGP multiple instance feature is enabled. - -@deffn {Command} {router bgp @var{as-number}} {} -Make a new BGP instance. You can use arbitrary word for the @var{name}. -@end deffn - -@example -@group -bgp multiple-instance -! -router bgp 1 - neighbor 10.0.0.1 remote-as 2 - neighbor 10.0.0.2 remote-as 3 -! -router bgp 2 - neighbor 10.0.0.3 remote-as 4 - neighbor 10.0.0.4 remote-as 5 -@end group -@end example - -BGP view is almost same as normal BGP process. The result of -route selection does not go to the kernel routing table. BGP view is -only for exchanging BGP routing information. - -@deffn {Command} {router bgp @var{as-number} view @var{name}} {} -Make a new BGP view. You can use arbitrary word for the @var{name}. This -view's route selection result does not go to the kernel routing table. -@end deffn - -With this command, you can setup Route Server like below. - -@example -@group -bgp multiple-instance -! -router bgp 1 view 1 - neighbor 10.0.0.1 remote-as 2 - neighbor 10.0.0.2 remote-as 3 -! -router bgp 2 view 2 - neighbor 10.0.0.3 remote-as 4 - neighbor 10.0.0.4 remote-as 5 -@end group -@end example - -@node Routing policy -@subsection Routing policy - -You can set different routing policy for a peer. For example, you can -set different filter for a peer. - -@example -@group -bgp multiple-instance -! -router bgp 1 view 1 - neighbor 10.0.0.1 remote-as 2 - address-family ipv4 unicast - neighbor 10.0.0.1 distribute-list 1 in - exit-address-family -! -router bgp 1 view 2 - neighbor 10.0.0.1 remote-as 2 - address-family ipv4 unicast - neighbor 10.0.0.1 distribute-list 2 in - exit-address-family -@end group -@end example - -This means BGP update from a peer 10.0.0.1 goes to both BGP view 1 and view -2. When the update is inserted into view 1, distribute-list 1 is -applied. On the other hand, when the update is inserted into view 2, -distribute-list 2 is applied. - -@node Viewing the view -@subsection Viewing the view - -To display routing table of BGP view, you must specify view name. - -@deffn {Command} {show ip bgp view @var{name}} {} -Display routing table of BGP view @var{name}. -@end deffn - -@node BGP Regular Expressions -@section BGP Regular Expressions - -BGP regular expressions are based on @code{POSIX 1003.2} regular -expressions. The following description is just a quick subset of the -@code{POSIX} regular expressions. Adding to that, the special character -'_' is added. - -@table @code -@item . -Matches any single character. -@item * -Matches 0 or more occurrences of pattern. -@item + -Matches 1 or more occurrences of pattern. -@item ? -Match 0 or 1 occurrences of pattern. -@item ^ -Matches the beginning of the line. -@item $ -Matches the end of the line. -@item _ -Character @code{_} has special meanings in BGP regular expressions. -It matches to space and comma , and AS set delimiter @{ and @} and AS -confederation delimiter @code{(} and @code{)}. And it also matches to -the beginning of the line and the end of the line. So @code{_} can be -used for AS value boundaries match. This character technically evaluates -to @code{(^|[,@{@}() ]|$)}. -@end table - -@node How to set up a 6-Bone connection -@section How to set up a 6-Bone connection - - -@example -@group -zebra configuration -=================== -! -! Actually there is no need to configure zebra -! - -bgpd configuration -================== -! -! This means that routes go through zebra and into the kernel. -! -router zebra -! -! MP-BGP configuration -! -router bgp 7675 - bgp router-id 10.0.0.1 - neighbor 3ffe:1cfa:0:2:2a0:c9ff:fe9e:f56 remote-as @var{as-number} -! - address-family ipv6 - network 3ffe:506::/32 - neighbor 3ffe:1cfa:0:2:2a0:c9ff:fe9e:f56 activate - neighbor 3ffe:1cfa:0:2:2a0:c9ff:fe9e:f56 route-map set-nexthop out - neighbor 3ffe:1cfa:0:2:2c0:4fff:fe68:a231 remote-as @var{as-number} - neighbor 3ffe:1cfa:0:2:2c0:4fff:fe68:a231 route-map set-nexthop out - exit-address-family -! -ipv6 access-list all permit any -! -! Set output nexthop address. -! -route-map set-nexthop permit 10 - match ipv6 address all - set ipv6 nexthop global 3ffe:1cfa:0:2:2c0:4fff:fe68:a225 - set ipv6 nexthop local fe80::2c0:4fff:fe68:a225 -! -! logfile FILENAME is obsolete. Please use log file FILENAME - -log file bgpd.log -! -@end group -@end example - -@node Dump BGP packets and table -@section Dump BGP packets and table - -@deffn Command {dump bgp all @var{path} [@var{interval}]} {} -@deffnx Command {dump bgp all-et @var{path} [@var{interval}]} {} -@deffnx Command {no dump bgp all [@var{path}] [@var{interval}]} {} -Dump all BGP packet and events to @var{path} file. -If @var{interval} is set, a new file will be created for echo @var{interval} of seconds. -The path @var{path} can be set with date and time formatting (strftime). -The type ‘all-et’ enables support for Extended Timestamp Header (@pxref{Packet Binary Dump Format}). -(@pxref{Packet Binary Dump Format}) -@end deffn - -@deffn Command {dump bgp updates @var{path} [@var{interval}]} {} -@deffnx Command {dump bgp updates-et @var{path} [@var{interval}]} {} -@deffnx Command {no dump bgp updates [@var{path}] [@var{interval}]} {} -Dump only BGP updates messages to @var{path} file. -If @var{interval} is set, a new file will be created for echo @var{interval} of seconds. -The path @var{path} can be set with date and time formatting (strftime). -The type ‘updates-et’ enables support for Extended Timestamp Header (@pxref{Packet Binary Dump Format}). -@end deffn - -@deffn Command {dump bgp routes-mrt @var{path}} {} -@deffnx Command {dump bgp routes-mrt @var{path} @var{interval}} {} -@deffnx Command {no dump bgp route-mrt [@var{path}] [@var{interval}]} {} -Dump whole BGP routing table to @var{path}. This is heavy process. -The path @var{path} can be set with date and time formatting (strftime). -If @var{interval} is set, a new file will be created for echo @var{interval} of seconds. -@end deffn - -Note: the interval variable can also be set using hours and minutes: 04h20m00. - - -@node BGP Configuration Examples -@section BGP Configuration Examples - -Example of a session to an upstream, advertising only one prefix to it. - -@example -router bgp 64512 - bgp router-id 10.236.87.1 - neighbor upstream peer-group - neighbor upstream remote-as 64515 - neighbor upstream capability dynamic - neighbor 10.1.1.1 peer-group upstream - neighbor 10.1.1.1 description ACME ISP - - address-family ipv4 unicast - network 10.236.87.0/24 - neighbor upstream prefix-list pl-allowed-adv out - exit-address-family -! -ip prefix-list pl-allowed-adv seq 5 permit 82.195.133.0/25 -ip prefix-list pl-allowed-adv seq 10 deny any - -@end example - -A more complex example. With upstream, peer and customer sessions. -Advertising global prefixes and NO_EXPORT prefixes and providing -actions for customer routes based on community values. Extensive use of -route-maps and the 'call' feature to support selective advertising of -prefixes. This example is intended as guidance only, it has NOT been -tested and almost certainly containts silly mistakes, if not serious -flaws. - -@example -router bgp 64512 - bgp router-id 10.236.87.1 - neighbor upstream capability dynamic - neighbor cust capability dynamic - neighbor peer capability dynamic - neighbor 10.1.1.1 remote-as 64515 - neighbor 10.1.1.1 peer-group upstream - neighbor 10.2.1.1 remote-as 64516 - neighbor 10.2.1.1 peer-group upstream - neighbor 10.3.1.1 remote-as 64517 - neighbor 10.3.1.1 peer-group cust-default - neighbor 10.3.1.1 description customer1 - neighbor 10.4.1.1 remote-as 64518 - neighbor 10.4.1.1 peer-group cust - neighbor 10.4.1.1 description customer2 - neighbor 10.5.1.1 remote-as 64519 - neighbor 10.5.1.1 peer-group peer - neighbor 10.5.1.1 description peer AS 1 - neighbor 10.6.1.1 remote-as 64520 - neighbor 10.6.1.1 peer-group peer - neighbor 10.6.1.1 description peer AS 2 - - address-family ipv4 unicast - network 10.123.456.0/24 - network 10.123.456.128/25 route-map rm-no-export - neighbor upstream route-map rm-upstream-out out - neighbor cust route-map rm-cust-in in - neighbor cust route-map rm-cust-out out - neighbor cust send-community both - neighbor peer route-map rm-peer-in in - neighbor peer route-map rm-peer-out out - neighbor peer send-community both - neighbor 10.3.1.1 prefix-list pl-cust1-network in - neighbor 10.4.1.1 prefix-list pl-cust2-network in - neighbor 10.5.1.1 prefix-list pl-peer1-network in - neighbor 10.6.1.1 prefix-list pl-peer2-network in - exit-address-family -! -ip prefix-list pl-default permit 0.0.0.0/0 -! -ip prefix-list pl-upstream-peers permit 10.1.1.1/32 -ip prefix-list pl-upstream-peers permit 10.2.1.1/32 -! -ip prefix-list pl-cust1-network permit 10.3.1.0/24 -ip prefix-list pl-cust1-network permit 10.3.2.0/24 -! -ip prefix-list pl-cust2-network permit 10.4.1.0/24 -! -ip prefix-list pl-peer1-network permit 10.5.1.0/24 -ip prefix-list pl-peer1-network permit 10.5.2.0/24 -ip prefix-list pl-peer1-network permit 192.168.0.0/24 -! -ip prefix-list pl-peer2-network permit 10.6.1.0/24 -ip prefix-list pl-peer2-network permit 10.6.2.0/24 -ip prefix-list pl-peer2-network permit 192.168.1.0/24 -ip prefix-list pl-peer2-network permit 192.168.2.0/24 -ip prefix-list pl-peer2-network permit 172.16.1/24 -! -ip as-path access-list asp-own-as permit ^$ -ip as-path access-list asp-own-as permit _64512_ -! -! ################################################################# -! Match communities we provide actions for, on routes receives from -! customers. Communities values of :X, with X, have actions: -! -! 100 - blackhole the prefix -! 200 - set no_export -! 300 - advertise only to other customers -! 400 - advertise only to upstreams -! 500 - set no_export when advertising to upstreams -! 2X00 - set local_preference to X00 -! -! blackhole the prefix of the route -ip community-list standard cm-blackhole permit 64512:100 -! -! set no-export community before advertising -ip community-list standard cm-set-no-export permit 64512:200 -! -! advertise only to other customers -ip community-list standard cm-cust-only permit 64512:300 -! -! advertise only to upstreams -ip community-list standard cm-upstream-only permit 64512:400 -! -! advertise to upstreams with no-export -ip community-list standard cm-upstream-noexport permit 64512:500 -! -! set local-pref to least significant 3 digits of the community -ip community-list standard cm-prefmod-100 permit 64512:2100 -ip community-list standard cm-prefmod-200 permit 64512:2200 -ip community-list standard cm-prefmod-300 permit 64512:2300 -ip community-list standard cm-prefmod-400 permit 64512:2400 -ip community-list expanded cme-prefmod-range permit 64512:2... -! -! Informational communities -! -! 3000 - learned from upstream -! 3100 - learned from customer -! 3200 - learned from peer -! -ip community-list standard cm-learnt-upstream permit 64512:3000 -ip community-list standard cm-learnt-cust permit 64512:3100 -ip community-list standard cm-learnt-peer permit 64512:3200 -! -! ################################################################### -! Utility route-maps -! -! These utility route-maps generally should not used to permit/deny -! routes, i.e. they do not have meaning as filters, and hence probably -! should be used with 'on-match next'. These all finish with an empty -! permit entry so as not interfere with processing in the caller. -! -route-map rm-no-export permit 10 - set community additive no-export -route-map rm-no-export permit 20 -! -route-map rm-blackhole permit 10 - description blackhole, up-pref and ensure it cant escape this AS - set ip next-hop 127.0.0.1 - set local-preference 10 - set community additive no-export -route-map rm-blackhole permit 20 -! -! Set local-pref as requested -route-map rm-prefmod permit 10 - match community cm-prefmod-100 - set local-preference 100 -route-map rm-prefmod permit 20 - match community cm-prefmod-200 - set local-preference 200 -route-map rm-prefmod permit 30 - match community cm-prefmod-300 - set local-preference 300 -route-map rm-prefmod permit 40 - match community cm-prefmod-400 - set local-preference 400 -route-map rm-prefmod permit 50 -! -! Community actions to take on receipt of route. -route-map rm-community-in permit 10 - description check for blackholing, no point continuing if it matches. - match community cm-blackhole - call rm-blackhole -route-map rm-community-in permit 20 - match community cm-set-no-export - call rm-no-export - on-match next -route-map rm-community-in permit 30 - match community cme-prefmod-range - call rm-prefmod -route-map rm-community-in permit 40 -! -! ##################################################################### -! Community actions to take when advertising a route. -! These are filtering route-maps, -! -! Deny customer routes to upstream with cust-only set. -route-map rm-community-filt-to-upstream deny 10 - match community cm-learnt-cust - match community cm-cust-only -route-map rm-community-filt-to-upstream permit 20 -! -! Deny customer routes to other customers with upstream-only set. -route-map rm-community-filt-to-cust deny 10 - match community cm-learnt-cust - match community cm-upstream-only -route-map rm-community-filt-to-cust permit 20 -! -! ################################################################### -! The top-level route-maps applied to sessions. Further entries could -! be added obviously.. -! -! Customers -route-map rm-cust-in permit 10 - call rm-community-in - on-match next -route-map rm-cust-in permit 20 - set community additive 64512:3100 -route-map rm-cust-in permit 30 -! -route-map rm-cust-out permit 10 - call rm-community-filt-to-cust - on-match next -route-map rm-cust-out permit 20 -! -! Upstream transit ASes -route-map rm-upstream-out permit 10 - description filter customer prefixes which are marked cust-only - call rm-community-filt-to-upstream - on-match next -route-map rm-upstream-out permit 20 - description only customer routes are provided to upstreams/peers - match community cm-learnt-cust -! -! Peer ASes -! outbound policy is same as for upstream -route-map rm-peer-out permit 10 - call rm-upstream-out -! -route-map rm-peer-in permit 10 - set community additive 64512:3200 -@end example - -@include rpki.texi diff --git a/doc/defines.texi.in b/doc/defines.texi.in deleted file mode 100644 index b2af89e40a..0000000000 --- a/doc/defines.texi.in +++ /dev/null @@ -1,21 +0,0 @@ -@c -*- texinfo -*- -@c @configure_input@ - -@c Set variables -@set PACKAGE_NAME @PACKAGE_NAME@ -@set PACKAGE_TARNAME @PACKAGE_TARNAME@ -@set PACKAGE_STRING @PACKAGE_STRING@ -@set PACKAGE_URL @PACKAGE_URL@ -@set PACKAGE_VERSION @PACKAGE_VERSION@ -@set AUTHORS Kunihiro Ishiguro, et al. -@set COPYRIGHT_YEAR 1999-2005 -@set COPYRIGHT_STR Copyright @copyright{} @value{COPYRIGHT_YEAR} @value{AUTHORS} - -@c These may vary with installation environment. -@set INSTALL_PREFIX_ETC @CFG_SYSCONF@ -@set INSTALL_PREFIX_SBIN @CFG_SBIN@ -@set INSTALL_PREFIX_STATE @CFG_STATE@ -@set INSTALL_PREFIX_MODULES @CFG_MODULE@ -@set INSTALL_USER @enable_user@ -@set INSTALL_GROUP @enable_group@ -@set INSTALL_VTY_GROUP @enable_vty_group@ diff --git a/doc/eigrpd.texi b/doc/eigrpd.texi deleted file mode 100644 index a3a82bbefb..0000000000 --- a/doc/eigrpd.texi +++ /dev/null @@ -1,216 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the Frr Manual. -@c @value{COPYRIGHT_STR} -@c See file frr.texi for copying conditions. -@node EIGRP -@chapter EIGRP - -EIGRP -- Routing Information Protocol is widely deployed interior gateway -routing protocol. EIGRP was developed in the 1990's. EIGRP is a -@dfn{distance-vector} protocol and is based on the @dfn{dual} algorithms. -As a distance-vector protocol, the EIGRP router send updates to its -neighbors as networks change, thus allowing the convergence to a -known topology. - -@command{eigrpd} supports EIGRP as described in RFC7868 - -@menu -* Starting and Stopping eigrpd:: -* EIGRP Configuration:: -* How to Announce EIGRP routes:: -* Show EIGRP Information:: -* EIGRP Debug Commands:: -@end menu - -@node Starting and Stopping eigrpd -@section Starting and Stopping eigrpd - -The default configuration file name of @command{eigrpd}'s is -@file{eigrpd.conf}. When invocation @command{eigrpd} searches directory -@value{INSTALL_PREFIX_ETC}. If @file{eigrpd.conf} is not there next -search current directory. If an integrated config is specified -configuration is written into frr.conf - -The EIGRP protocol requires interface information -maintained by @command{zebra} daemon. So running @command{zebra} -is mandatory to run @command{eigrpd}. Thus minimum sequence for running -EIGRP is like below: - -@example -@group -# zebra -d -# eigrpd -d -@end group -@end example - -Please note that @command{zebra} must be invoked before @command{eigrpd}. - -To stop @command{eigrpd}. Please use @command{kill `cat -/var/run/eigrpd.pid`}. Certain signals have special meanings to @command{eigrpd}. - -@table @samp -@item SIGHUP -@item SIGUSR1 -Rotate @command{eigrpd} Rotate the logfile. -@item SIGINT -@itemx SIGTERM -@command{eigrpd} sweeps all installed EIGRP routes then terminates properly. -@end table - -@command{eigrpd} invocation options. Common options that can be specified -(@pxref{Common Invocation Options}). - -@table @samp -@item -r -@itemx --retain -When the program terminates, retain routes added by @command{eigrpd}. -@end table - -@node EIGRP Configuration -@section EIGRP Configuration - -@deffn Command {router eigrp (1-65535)} {} -The @code{router eigrp} command is necessary to enable EIGRP. To disable -EIGRP, use the @code{no router eigrp (1-65535)} command. EIGRP must be enabled before carrying out any of the EIGRP commands. -@end deffn - -@deffn Command {no router eigrp (1-65535)} {} -Disable EIGRP. -@end deffn - -@deffn {EIGRP Command} {network @var{network}} {} -@deffnx {EIGRP Command} {no network @var{network}} {} -Set the EIGRP enable interface by @var{network}. The interfaces which -have addresses matching with @var{network} are enabled. - -This group of commands either enables or disables EIGRP interfaces between -certain numbers of a specified network address. For example, if the -network for 10.0.0.0/24 is EIGRP enabled, this would result in all the -addresses from 10.0.0.0 to 10.0.0.255 being enabled for EIGRP. The @code{no -network} command will disable EIGRP for the specified network. -@end deffn - -Below is very simple EIGRP configuration. Interface @code{eth0} and -interface which address match to @code{10.0.0.0/8} are EIGRP enabled. - -@example -@group -! -router eigrp 1 - network 10.0.0.0/8 -! -@end group -@end example - -Passive interface - -@deffn {EIGRP command} {passive-interface (@var{IFNAME}|default)} {} -@deffnx {EIGRP command} {no passive-interface @var{IFNAME}} {} -This command sets the specified interface to passive mode. On passive mode -interface, all receiving packets are ignored and eigrpd does -not send either multicast or unicast EIGRP packets except to EIGRP neighbors -specified with @code{neighbor} command. The interface may be specified -as @var{default} to make eigrpd default to passive on all interfaces. - -The default is to be passive on all interfaces. -@end deffn - -@node How to Announce EIGRP route -@section How to Announce EIGRP route - -@deffn {EIGRP command} {redistribute kernel} {} -@deffnx {EIGRP command} {redistribute kernel metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} -@deffnx {EIGRP command} {no redistribute kernel} {} -@code{redistribute kernel} redistributes routing information from -kernel route entries into the EIGRP tables. @code{no redistribute kernel} -disables the routes. -@end deffn - -@deffn {EIGRP command} {redistribute static} {} -@deffnx {EIGRP command} {redistribute static metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} -@deffnx {EIGRP command} {no redistribute static} {} -@code{redistribute static} redistributes routing information from -static route entries into the EIGRP tables. @code{no redistribute static} -disables the routes. -@end deffn - -@deffn {EIGRP command} {redistribute connected} {} -@deffnx {EIGRP command} {redistribute connected metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} -@deffnx {EIGRP command} {no redistribute connected} {} -Redistribute connected routes into the EIGRP tables. @code{no -redistribute connected} disables the connected routes in the EIGRP tables. -This command redistribute connected of the interface which EIGRP disabled. -The connected route on EIGRP enabled interface is announced by default. -@end deffn - -@deffn {EIGRP command} {redistribute ospf} {} -@deffnx {EIGRP command} {redistribute ospf metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} -@deffnx {EIGRP command} {no redistribute ospf} {} -@code{redistribute ospf} redistributes routing information from -ospf route entries into the EIGRP tables. @code{no redistribute ospf} -disables the routes. -@end deffn - -@deffn {EIGRP command} {redistribute bgp} {} -@deffnx {EIGRP command} {redistribute bgp metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} -@deffnx {EIGRP command} {no redistribute bgp} {} -@code{redistribute bgp} redistributes routing information from -bgp route entries into the EIGRP tables. @code{no redistribute bgp} -disables the routes. -@end deffn - -@node Show EIGRP Information -@section Show EIGRP Information - -To display EIGRP routes. - -@deffn Command {show ip eigrp topology} {} -Show EIGRP routes. -@end deffn - -The command displays all EIGRP routes. - -@c Exmaple here. - -@deffn Command {show ip eigrp topology} {} -The command displays current EIGRP status -@end deffn - -@example -@group -eigrpd> @b{show ip eigrp topology} -# show ip eigrp topo - -EIGRP Topology Table for AS(4)/ID(0.0.0.0) - -Codes: P - Passive, A - Active, U - Update, Q - Query, R - Reply - r - reply Status, s - sia Status - -P 10.0.2.0/24, 1 successors, FD is 256256, serno: 0 - via Connected, enp0s3 -@end group -@end example - -@node EIGRP Debug Commands -@section EIGRP Debug Commands - -Debug for EIGRP protocol. - -@deffn Command {debug eigrp packets} {} -Debug eigrp packets -@end deffn - -@code{debug eigrp} will show EIGRP packets that are sent and recevied. - -@deffn Command {debug eigrp transmit} {} -Debug eigrp transmit events -@end deffn - -@code{debug eigrp transmit} will display detailed information about the EIGRP transmit events. - -@deffn Command {show debugging eigrp} {} -Display @command{eigrpd}'s debugging option. -@end deffn - -@code{show debugging eigrp} will show all information currently set for eigrpd -debug. diff --git a/doc/filter.texi b/doc/filter.texi deleted file mode 100644 index a494043659..0000000000 --- a/doc/filter.texi +++ /dev/null @@ -1,182 +0,0 @@ -@node Filtering -@comment node-name, next, previous, up -@chapter Filtering - -Frr provides many very flexible filtering features. Filtering is used -for both input and output of the routing information. Once filtering is -defined, it can be applied in any direction. - -@menu -* IP Access List:: -* IP Prefix List:: -@end menu - -@node IP Access List -@comment node-name, next, previous, up -@section IP Access List - -@deffn {Command} {access-list @var{name} permit @var{ipv4-network}} {} -@deffnx {Command} {access-list @var{name} deny @var{ipv4-network}} {} -@end deffn - -Basic filtering is done by @code{access-list} as shown in the -following example. - -@example -access-list filter deny 10.0.0.0/9 -access-list filter permit 10.0.0.0/8 -@end example - -@node IP Prefix List -@comment node-name, next, previous, up -@section IP Prefix List - -@command{ip prefix-list} provides the most powerful prefix based -filtering mechanism. In addition to @command{access-list} functionality, -@command{ip prefix-list} has prefix length range specification and -sequential number specification. You can add or delete prefix based -filters to arbitrary points of prefix-list using sequential number specification. - -If no ip prefix-list is specified, it acts as permit. If @command{ip prefix-list} -is defined, and no match is found, default deny is applied. - -@c @deffn {Command} {ip prefix-list @var{name} [seq @var{number}] permit|deny [le @var{prefixlen}] [ge @var{prefixlen}]} {} -@deffn {Command} {ip prefix-list @var{name} (permit|deny) @var{prefix} [le @var{len}] [ge @var{len}]} {} -@deffnx {Command} {ip prefix-list @var{name} seq @var{number} (permit|deny) @var{prefix} [le @var{len}] [ge @var{len}]} {} - -You can create @command{ip prefix-list} using above commands. - -@table @asis - -@item @asis{seq} -seq @var{number} can be set either automatically or manually. In the -case that sequential numbers are set manually, the user may pick any -number less than 4294967295. In the case that sequential number are set -automatically, the sequential number will increase by a unit of five (5) -per list. If a list with no specified sequential number is created -after a list with a specified sequential number, the list will -automatically pick the next multiple of five (5) as the list number. -For example, if a list with number 2 already exists and a new list with -no specified number is created, the next list will be numbered 5. If -lists 2 and 7 already exist and a new list with no specified number is -created, the new list will be numbered 10. - -@item @asis{le} -@command{le} command specifies prefix length. The prefix list will be -applied if the prefix length is less than or equal to the le prefix length. - -@item @asis{ge} -@command{ge} command specifies prefix length. The prefix list will be -applied if the prefix length is greater than or equal to the ge prefix length. - -@end table - -@end deffn - -Less than or equal to prefix numbers and greater than or equal to -prefix numbers can be used together. The order of the le and ge -commands does not matter. - -If a prefix list with a different sequential number but with the exact -same rules as a previous list is created, an error will result. -However, in the case that the sequential number and the rules are -exactly similar, no error will result. - -If a list with the same sequential number as a previous list is created, -the new list will overwrite the old list. - -Matching of IP Prefix is performed from the smaller sequential number to the -larger. The matching will stop once any rule has been applied. - -In the case of no le or ge command, the prefix length must match exactly the -length specified in the prefix list. - -@deffn {Command} {no ip prefix-list @var{name}} {} -@end deffn - -@menu -* ip prefix-list description:: -* ip prefix-list sequential number control:: -* Showing ip prefix-list:: -* Clear counter of ip prefix-list:: -@end menu - -@node ip prefix-list description -@subsection ip prefix-list description - -@deffn {Command} {ip prefix-list @var{name} description @var{desc}} {} -Descriptions may be added to prefix lists. This command adds a -description to the prefix list. -@end deffn - -@deffn {Command} {no ip prefix-list @var{name} description [@var{desc}]} {} -Deletes the description from a prefix list. It is possible to use the -command without the full description. -@end deffn - -@node ip prefix-list sequential number control -@subsection ip prefix-list sequential number control - -@deffn {Command} {ip prefix-list sequence-number} {} -With this command, the IP prefix list sequential number is displayed. -This is the default behavior. -@end deffn - -@deffn {Command} {no ip prefix-list sequence-number} {} -With this command, the IP prefix list sequential number is not -displayed. -@end deffn - -@node Showing ip prefix-list -@subsection Showing ip prefix-list - -@deffn {Command} {show ip prefix-list} {} -Display all IP prefix lists. -@end deffn - -@deffn {Command} {show ip prefix-list @var{name}} {} -Show IP prefix list can be used with a prefix list name. -@end deffn - -@deffn {Command} {show ip prefix-list @var{name} seq @var{num}} {} -Show IP prefix list can be used with a prefix list name and sequential -number. -@end deffn - -@deffn {Command} {show ip prefix-list @var{name} @var{a.b.c.d/m}} {} -If the command longer is used, all prefix lists with prefix lengths equal to -or longer than the specified length will be displayed. -If the command first match is used, the first prefix length match will be -displayed. -@end deffn - -@deffn {Command} {show ip prefix-list @var{name} @var{a.b.c.d/m} longer} {} -@end deffn - -@deffn {Command} {show ip prefix-list @var{name} @var{a.b.c.d/m} first-match} {} -@end deffn - -@deffn {Command} {show ip prefix-list summary} {} -@end deffn -@deffn {Command} {show ip prefix-list summary @var{name}} {} -@end deffn - -@deffn {Command} {show ip prefix-list detail} {} -@end deffn -@deffn {Command} {show ip prefix-list detail @var{name}} {} -@end deffn - -@node Clear counter of ip prefix-list -@subsection Clear counter of ip prefix-list - -@deffn {Command} {clear ip prefix-list} {} -Clears the counters of all IP prefix lists. Clear IP Prefix List can be -used with a specified name and prefix. -@end deffn - -@deffn {Command} {clear ip prefix-list @var{name}} {} -@end deffn - -@deffn {Command} {clear ip prefix-list @var{name} @var{a.b.c.d/m}} {} -@end deffn - diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/install.texi b/doc/install.texi deleted file mode 100644 index 19d9614420..0000000000 --- a/doc/install.texi +++ /dev/null @@ -1,287 +0,0 @@ -@node Installation -@chapter Installation - -@cindex How to install Frr -@cindex Installation -@cindex Installing Frr -@cindex Building the system -@cindex Making Frr - -There are three steps for installing the software: configuration, -compilation, and installation. - -@menu -* Configure the Software:: -* Build the Software:: -* Install the Software:: -@end menu - -The easiest way to get Frr running is to issue the following -commands: - -@example -% configure -% make -% make install -@end example - -@node Configure the Software -@section Configure the Software - -@menu -* The Configure script and its options:: -* Least-Privilege support:: -* Linux notes:: -@end menu - -@node The Configure script and its options -@subsection The Configure script and its options - -@cindex Configuration options -@cindex Options for configuring -@cindex Build options -@cindex Distribution configuration -@cindex Options to @code{./configure} - -Frr has an excellent configure script which automatically detects most -host configurations. There are several additional configure options to -customize the build to include or exclude specific features and dependencies. - -@table @option -@item --disable-zebra -Do not build zebra daemon. -@item --disable-ripd -Do not build ripd. -@item --disable-ripngd -Do not build ripngd. -@item --disable-ospfd -Do not build ospfd. -@item --disable-ospf6d -Do not build ospf6d. -@item --disable-bgpd -Do not build bgpd. -@item --disable-bgp-announce -Make @command{bgpd} which does not make bgp announcements at all. This -feature is good for using @command{bgpd} as a BGP announcement listener. -@item --enable-datacenter -Enable system defaults to work as if in a Data Center. See defaults.h -for what is changed by this configure option. -@item --enable-snmp -Enable SNMP support. By default, SNMP support is disabled. -@item --disable-ospfapi -Disable support for OSPF-API, an API to interface directly with ospfd. -OSPF-API is enabled if --enable-opaque-lsa is set. -@item --disable-ospfclient -Disable building of the example OSPF-API client. -@item --disable-ospf-ri -Disable support for OSPF Router Information (RFC4970 & RFC5088) this -requires support for Opaque LSAs and Traffic Engineering. -@item --disable-isisd -Do not build isisd. -@item --enable-isis-topology -Enable IS-IS topology generator. -@item --enable-isis-te -Enable Traffic Engineering Extension for ISIS (RFC5305) -@item --enable-multipath=@var{ARG} -Enable support for Equal Cost Multipath. @var{ARG} is the maximum number -of ECMP paths to allow, set to 0 to allow unlimited number of paths. -@item --disable-rtadv -Disable support IPV6 router advertisement in zebra. -@item --enable-gcc-rdynamic -Pass the @command{-rdynamic} option to the linker driver. This is in most -cases neccessary for getting usable backtraces. This option defaults to on -if the compiler is detected as gcc, but giving an explicit enable/disable is -suggested. -@item --disable-backtrace -Controls backtrace support for the crash handlers. This is autodetected by -default. Using the switch will enforce the requested behaviour, failing with -an error if support is requested but not available. On BSD systems, this -needs libexecinfo, while on glibc support for this is part of libc itself. -@item --enable-dev-build -Turn on some options for compiling FRR within a development environment in -mind. Specifically turn on -g3 -O0 for compiling options and add inclusion -of grammar sandbox. -@item --enable-fuzzing -Turn on some compile options to allow you to run fuzzing tools -against the system. This tools is intended as a developer -only tool and should not be used for normal operations -@end table - -You may specify any combination of the above options to the configure -script. By default, the executables are placed in @file{/usr/local/sbin} -and the configuration files in @file{/usr/local/etc}. The @file{/usr/local/} -installation prefix and other directories may be changed using the following -options to the configuration script. - -@table @option -@item --prefix=@var{prefix} -Install architecture-independent files in @var{prefix} [/usr/local]. -@item --sysconfdir=@var{dir} -Look for configuration files in @var{dir} [@var{prefix}/etc]. Note -that sample configuration files will be installed here. -@item --localstatedir=@var{dir} -Configure zebra to use @var{dir} for local state files, such -as pid files and unix sockets. -@end table - -@example -% ./configure --disable-snmp -@end example - -This command will configure zebra and the routing daemons. - -@node Least-Privilege support -@subsection Least-Privilege support - -@cindex Frr Least-Privileges -@cindex Frr Privileges - -Additionally, you may configure zebra to drop its elevated privileges -shortly after startup and switch to another user. The configure script will -automatically try to configure this support. There are three configure -options to control the behaviour of Frr daemons. - -@table @option -@item --enable-user=@var{user} -Switch to user @var{ARG} shortly after startup, and run as user @var{ARG} -in normal operation. -@item --enable-group=@var{group} -Switch real and effective group to @var{group} shortly after -startup. -@item --enable-vty-group=@var{group} -Create Unix Vty sockets (for use with vtysh) with group owndership set to -@var{group}. This allows one to create a seperate group which is -restricted to accessing only the Vty sockets, hence allowing one to -delegate this group to individual users, or to run vtysh setgid to -this group. -@end table - -The default user and group which will be configured is 'frr' if no user -or group is specified. Note that this user or group requires write access to -the local state directory (see --localstatedir) and requires at least read -access, and write access if you wish to allow daemons to write out their -configuration, to the configuration directory (see --sysconfdir). - -On systems which have the 'libcap' capabilities manipulation library -(currently only linux), the frr system will retain only minimal -capabilities required, further it will only raise these capabilities for -brief periods. On systems without libcap, frr will run as the user -specified and only raise its uid back to uid 0 for brief periods. - -@node Linux notes -@subsection Linux Notes - -@cindex Configuring Frr -@cindex Building on Linux boxes -@cindex Linux configurations - -There are several options available only to @sc{gnu}/Linux systems: -@footnote{@sc{gnu}/Linux has very flexible kernel configuration features}. If -you use @sc{gnu}/Linux, make sure that the current kernel configuration is -what you want. Frr will run with any kernel configuration but some -recommendations do exist. - -@table @var - -@item CONFIG_NETLINK -Kernel/User netlink socket. This is a brand new feature which enables an -advanced interface between the Linux kernel and zebra (@pxref{Kernel Interface}). - -@item CONFIG_RTNETLINK -Routing messages. -This makes it possible to receive netlink routing messages. If you -specify this option, @command{zebra} can detect routing information -updates directly from the kernel (@pxref{Kernel Interface}). - -@item CONFIG_IP_MULTICAST -IP: multicasting. -This option should be specified when you use @command{ripd} (@pxref{RIP}) or -@command{ospfd} (@pxref{OSPFv2}) because these protocols use multicast. - -@end table - -IPv6 support has been added in @sc{gnu}/Linux kernel version 2.2. If you -try to use the Frr IPv6 feature on a @sc{gnu}/Linux kernel, please -make sure the following libraries have been installed. Please note that -these libraries will not be needed when you uses @sc{gnu} C library 2.1 -or upper. - -@table @code - -@item inet6-apps -The @code{inet6-apps} package includes basic IPv6 related libraries such -as @code{inet_ntop} and @code{inet_pton}. Some basic IPv6 programs such -as @command{ping}, @command{ftp}, and @command{inetd} are also -included. The @code{inet-apps} can be found at -@uref{ftp://ftp.inner.net/pub/ipv6/}. - -@item net-tools -The @code{net-tools} package provides an IPv6 enabled interface and -routing utility. It contains @command{ifconfig}, @command{route}, -@command{netstat}, and other tools. @code{net-tools} may be found at -@uref{http://www.tazenda.demon.co.uk/phil/net-tools/}. - -@end table -@c A - end of footnote - -@node Build the Software -@section Build the Software - -After configuring the software, you will need to compile it for your -system. Simply issue the command @command{make} in the root of the source -directory and the software will be compiled. Cliff Note versions of -different compilation examples can be found in the doc/Building_FRR_on_XXX.md -files. If you have *any* problems at this stage, be certain to send a -bug report @xref{Bug Reports}. - -@example -% ./bootstrap.sh -% ./configure -% make -@end example -@c A - End of node, Building the Software - - -@node Install the Software -@comment node-name, next, previous, up -@section Install the Software - -Installing the software to your system consists of copying the compiled -programs and supporting files to a standard location. After the -installation process has completed, these files have been copied -from your work directory to @file{/usr/local/bin}, and @file{/usr/local/etc}. - -To install the Frr suite, issue the following command at your shell -prompt: @command{make install}. - -@example -% -% make install -% -@end example - -Frr daemons have their own terminal interface or VTY. After -installation, you have to setup each beast's port number to connect to -them. Please add the following entries to @file{/etc/services}. - -@example -zebrasrv 2600/tcp # zebra service -zebra 2601/tcp # zebra vty -ripd 2602/tcp # RIPd vty -ripngd 2603/tcp # RIPngd vty -ospfd 2604/tcp # OSPFd vty -bgpd 2605/tcp # BGPd vty -ospf6d 2606/tcp # OSPF6d vty -ospfapi 2607/tcp # ospfapi -isisd 2608/tcp # ISISd vty -nhrpd 2610/tcp # nhrpd vty -pimd 2611/tcp # PIMd vty -@end example - -If you use a FreeBSD newer than 2.2.8, the above entries are already -added to @file{/etc/services} so there is no need to add it. If you -specify a port number when starting the daemon, these entries may not be -needed. - -You may need to make changes to the config files in -@file{@value{INSTALL_PREFIX_ETC}/*.conf}. @xref{Config Commands}. diff --git a/doc/ipv6.texi b/doc/ipv6.texi deleted file mode 100644 index 859f6a960e..0000000000 --- a/doc/ipv6.texi +++ /dev/null @@ -1,186 +0,0 @@ -@node IPv6 Support -@chapter IPv6 Support - -Frr fully supports IPv6 routing. As described so far, Frr supports -RIPng, OSPFv3, and BGP-4+. You can give IPv6 addresses to an interface -and configure static IPv6 routing information. Frr IPv6 also provides -automatic address configuration via a feature called @code{address -auto configuration}. To do it, the router must send router advertisement -messages to the all nodes that exist on the network. - -Previous versions of Frr could be built without IPv6 support. This is -no longer possible. - -@menu -* Router Advertisement:: -@end menu - -@node Router Advertisement -@section Router Advertisement - -@deffn {Interface Command} {no ipv6 nd suppress-ra} {} -Send router advertisment messages. -@end deffn - -@deffn {Interface Command} {ipv6 nd suppress-ra} {} -Don't send router advertisment messages. -@end deffn - -@deffn {Interface Command} {ipv6 nd prefix @var{ipv6prefix} [@var{valid-lifetime}] [@var{preferred-lifetime}] [off-link] [no-autoconfig] [router-address]} {} -Configuring the IPv6 prefix to include in router advertisements. Several prefix -specific optional parameters and flags may follow: -@itemize @bullet -@item -@var{valid-lifetime} - the length of time in seconds during what the prefix is -valid for the purpose of on-link determination. Value @var{infinite} represents -infinity (i.e. a value of all one bits (@code{0xffffffff})). - -Range: @code{<0-4294967295>} Default: @code{2592000} - -@item -@var{preferred-lifetime} - the length of time in seconds during what addresses -generated from the prefix remain preferred. Value @var{infinite} represents -infinity. - -Range: @code{<0-4294967295>} Default: @code{604800} - -@item -@var{off-link} - indicates that advertisement makes no statement about on-link or -off-link properties of the prefix. - -Default: not set, i.e. this prefix can be used for on-link determination. - -@item -@var{no-autoconfig} - indicates to hosts on the local link that the specified prefix -cannot be used for IPv6 autoconfiguration. - -Default: not set, i.e. prefix can be used for autoconfiguration. - -@item -@var{router-address} - indicates to hosts on the local link that the specified -prefix -contains a complete IP address by setting R flag. - -Default: not set, i.e. hosts do not assume a complete IP address is placed. -@end itemize -@end deffn - -@deffn {Interface Command} {ipv6 nd ra-interval <1-1800>} {} -@deffnx {Interface Command} {no ipv6 nd ra-interval [<1-1800>]} {} -The maximum time allowed between sending unsolicited multicast router -advertisements from the interface, in seconds. - -Default: @code{600} -@end deffn - -@deffn {Interface Command} {ipv6 nd ra-interval msec <70-1800000>} {} -@deffnx {Interface Command} {no ipv6 nd ra-interval [msec <70-1800000>]} {} -The maximum time allowed between sending unsolicited multicast router -advertisements from the interface, in milliseconds. - -Default: @code{600000} -@end deffn - -@deffn {Interface Command} {ipv6 nd ra-lifetime <0-9000>} {} -@deffnx {Interface Command} {no ipv6 nd ra-lifetime [<0-9000>]} {} -The value to be placed in the Router Lifetime field of router advertisements -sent from the interface, in seconds. Indicates the usefulness of the router -as a default router on this interface. Setting the value to zero indicates -that the router should not be considered a default router on this interface. -Must be either zero or between value specified with @var{ipv6 nd ra-interval} -(or default) and 9000 seconds. - -Default: @code{1800} -@end deffn - -@deffn {Interface Command} {ipv6 nd reachable-time <1-3600000>} {} -@deffnx {Interface Command} {no ipv6 nd reachable-time [<1-3600000>]} {} -The value to be placed in the Reachable Time field in the Router Advertisement -messages sent by the router, in milliseconds. The configured time enables the -router to detect unavailable neighbors. The value zero means unspecified (by -this router). - -Default: @code{0} -@end deffn - -@deffn {Interface Command} {ipv6 nd managed-config-flag} {} -@deffnx {Interface Command} {no ipv6 nd managed-config-flag} {} -Set/unset flag in IPv6 router advertisements which indicates to hosts that they -should use managed (stateful) protocol for addresses autoconfiguration in -addition to any addresses autoconfigured using stateless address -autoconfiguration. - -Default: not set -@end deffn - -@deffn {Interface Command} {ipv6 nd other-config-flag} {} -@deffnx {Interface Command} {no ipv6 nd other-config-flag} {} -Set/unset flag in IPv6 router advertisements which indicates to hosts that -they should use administered (stateful) protocol to obtain autoconfiguration -information other than addresses. - -Default: not set -@end deffn - -@deffn {Interface Command} {ipv6 nd home-agent-config-flag} {} -@deffnx {Interface Command} {no ipv6 nd home-agent-config-flag} {} -Set/unset flag in IPv6 router advertisements which indicates to hosts that -the router acts as a Home Agent and includes a Home Agent Option. - -Default: not set -@end deffn - -@deffn {Interface Command} {ipv6 nd home-agent-preference <0-65535>} {} -@deffnx {Interface Command} {no ipv6 nd home-agent-preference [<0-65535>]} {} -The value to be placed in Home Agent Option, when Home Agent config flag is set, -which indicates to hosts Home Agent preference. The default value of 0 stands -for the lowest preference possible. - -Default: 0 -@end deffn - -@deffn {Interface Command} {ipv6 nd home-agent-lifetime <0-65520>} {} -@deffnx {Interface Command} {no ipv6 nd home-agent-lifetime [<0-65520>]} {} -The value to be placed in Home Agent Option, when Home Agent config flag is set, -which indicates to hosts Home Agent Lifetime. The default value of 0 means to -place the current Router Lifetime value. - -Default: 0 -@end deffn - -@deffn {Interface Command} {ipv6 nd adv-interval-option} {} -@deffnx {Interface Command} {no ipv6 nd adv-interval-option} {} -Include an Advertisement Interval option which indicates to hosts the maximum time, -in milliseconds, between successive unsolicited Router Advertisements. - -Default: not set -@end deffn - -@deffn {Interface Command} {ipv6 nd router-preference (high|medium|low)} {} -@deffnx {Interface Command} {no ipv6 nd router-preference [(high|medium|low)]} {} -Set default router preference in IPv6 router advertisements per RFC4191. - -Default: medium -@end deffn - -@deffn {Interface Command} {ipv6 nd mtu <1-65535>} {} -@deffnx {Interface Command} {no ipv6 nd mtu [<1-65535>]} {} -Include an MTU (type 5) option in each RA packet to assist the attached hosts -in proper interface configuration. The announced value is not verified to be -consistent with router interface MTU. - -Default: don't advertise any MTU option -@end deffn - -@example -@group -interface eth0 - no ipv6 nd suppress-ra - ipv6 nd prefix 2001:0DB8:5009::/64 -@end group -@end example - -For more information see @cite{RFC2462 (IPv6 Stateless Address Autoconfiguration)} -, @cite{RFC4861 (Neighbor Discovery for IP Version 6 (IPv6))} -, @cite{RFC6275 (Mobility Support in IPv6)} -and @cite{RFC4191 (Default Router Preferences and More-Specific Routes)}. diff --git a/doc/isisd.texi b/doc/isisd.texi deleted file mode 100644 index bbc2896755..0000000000 --- a/doc/isisd.texi +++ /dev/null @@ -1,432 +0,0 @@ -@cindex ISIS -@node ISIS -@chapter ISIS - -@acronym{ISIS,Intermediate System to Intermediate System} is a routing protocol -which is described in @cite{ISO10589, RFC1195, RFC5308}. ISIS is an -@acronym{IGP,Interior Gateway Protocol}. Compared with @acronym{RIP}, -@acronym{ISIS} can provide scalable network support and faster -convergence times like @acronym{OSPF}. ISIS is widely used in large networks such as -@acronym{ISP,Internet Service Provider} and carrier backbone networks. - -@menu -* Configuring isisd:: -* ISIS router:: -* ISIS Timer:: -* ISIS region:: -* ISIS interface:: -* Showing ISIS information:: -* ISIS Traffic Engineering:: -* Debugging ISIS:: -* ISIS Configuration Examples:: -@end menu - -@node Configuring isisd -@section Configuring isisd - -There are no @command{isisd} specific options. Common options can be -specified (@pxref{Common Invocation Options}) to @command{isisd}. -@command{isisd} needs to acquire interface information from -@command{zebra} in order to function. Therefore @command{zebra} must be -running before invoking @command{isisd}. Also, if @command{zebra} is -restarted then @command{isisd} must be too. - -Like other daemons, @command{isisd} configuration is done in @acronym{ISIS} -specific configuration file @file{isisd.conf}. - -@node ISIS router -@section ISIS router - -To start ISIS process you have to specify the ISIS router. As of this -writing, @command{isisd} does not support multiple ISIS processes. - -@deffn Command {router isis WORD} {} -@deffnx Command {no router isis WORD} {} -@anchor{router isis WORD}Enable or disable the ISIS process by specifying the ISIS domain with 'WORD'. -@command{isisd} does not yet support multiple ISIS processes but you must specify -the name of ISIS process. The ISIS process name 'WORD' is then used for interface -(see command @ref{ip router isis WORD}). -@end deffn - -@deffn {ISIS Command} {net XX.XXXX. ... .XXX.XX} {} -@deffnx {ISIS Command} {no net XX.XXXX. ... .XXX.XX} {} -Set/Unset network entity title (NET) provided in ISO format. -@end deffn - -@deffn {ISIS Command} {hostname dynamic} {} -@deffnx {ISIS Command} {no hostname dynamic} {} -Enable support for dynamic hostname. -@end deffn - -@deffn {ISIS Command} {area-password [clear | md5] } {} -@deffnx {ISIS Command} {domain-password [clear | md5] } {} -@deffnx {ISIS Command} {no area-password} {} -@deffnx {ISIS Command} {no domain-password} {} -Configure the authentication password for an area, respectively a domain, -as clear text or md5 one. -@end deffn - -@deffn {ISIS Command} {log-adjacency-changes} {} -@deffnx {ISIS Command} {no log-adjacency-changes} {} -Log changes in adjacency state. -@end deffn - -@deffn {ISIS Command} {metric-style [narrow | transition | wide]} {} -@deffnx {ISIS Command} {no metric-style} {} -@anchor{metric-style}Set old-style (ISO 10589) or new-style packet formats: - - narrow Use old style of TLVs with narrow metric - - transition Send and accept both styles of TLVs during transition - - wide Use new style of TLVs to carry wider metric -@end deffn - -@deffn {ISIS Command} {set-overload-bit} {} -@deffnx {ISIS Command} {no set-overload-bit} {} -Set overload bit to avoid any transit traffic. -@end deffn - -@node ISIS Timer -@section ISIS Timer - -@deffn {ISIS Command} {lsp-gen-interval <1-120>} {} -@deffnx {ISIS Command} {lsp-gen-interval [level-1 | level-2] <1-120>} {} -@deffnx {ISIS Command} {no lsp-gen-interval} {} -@deffnx {ISIS Command} {no lsp-gen-interval [level-1 | level-2]} {} -Set minimum interval in seconds between regenerating same LSP, -globally, for an area (level-1) or a domain (level-2). -@end deffn - -@deffn {ISIS Command} {lsp-refresh-interval <1-65235>} {} -@deffnx {ISIS Command} {lsp-refresh-interval [level-1 | level-2] <1-65235>} {} -@deffnx {ISIS Command} {no lsp-refresh-interval} {} -@deffnx {ISIS Command} {no lsp-refresh-interval [level-1 | level-2]} {} -Set LSP refresh interval in seconds, globally, for an area (level-1) or a domain (level-2). -@end deffn - -@deffn {ISIS Command} {lsp-refresh-interval <1-65235>} {} -@deffnx {ISIS Command} {lsp-refresh-interval [level-1 | level-2] <1-65235>} {} -@deffnx {ISIS Command} {no lsp-refresh-interval} {} -@deffnx {ISIS Command} {no lsp-refresh-interval [level-1 | level-2]} {} -Set LSP refresh interval in seconds, globally, for an area (level-1) or a domain (level-2). -@end deffn - -@deffn {ISIS Command} {max-lsp-lifetime <360-65535>} {} -@deffnx {ISIS Command} {max-lsp-lifetime [level-1 | level-2] <360-65535>} {} -@deffnx {ISIS Command} {no max-lsp-lifetime} {} -@deffnx {ISIS Command} {no max-lsp-lifetime [level-1 | level-2]} {} -Set LSP maximum LSP lifetime in seconds, globally, for an area (level-1) or a domain (level-2). -@end deffn - -@deffn {ISIS Command} {spf-interval <1-120>} {} -@deffnx {ISIS Command} {spf-interval [level-1 | level-2] <1-120>} {} -@deffnx {ISIS Command} {no spf-interval} {} -@deffnx {ISIS Command} {no spf-interval [level-1 | level-2]} {} -Set minimum interval between consecutive SPF calculations in seconds. -@end deffn - -@node ISIS region -@section ISIS region - -@deffn {ISIS Command} {is-type [level-1 | level-1-2 | level-2-only]} {} -@deffnx {ISIS Command} {no is-type} {} -Define the ISIS router behavior: - - level-1 Act as a station router only - - level-1-2 Act as both a station router and an area router - - level-2-only Act as an area router only -@end deffn - -@node ISIS interface -@section ISIS interface - -@deffn {Interface Command} {ip router isis WORD} {} -@deffnx {Interface Command} {no ip router isis WORD} {} -@anchor{ip router isis WORD}Activate ISIS adjacency on this interface. Note that the name -of ISIS instance must be the same as the one used to configure the ISIS process -(see command @ref{router isis WORD}). -@end deffn - -@deffn {Interface Command} {isis circuit-type [level-1 | level-1-2 | level-2]} {} -@deffnx {Interface Command} {no isis circuit-type} {} -Configure circuit type for interface: - - level-1 Level-1 only adjacencies are formed - - level-1-2 Level-1-2 adjacencies are formed - - level-2-only Level-2 only adjacencies are formed -@end deffn - -@deffn {Interface Command} {isis csnp-interval <1-600>} {} -@deffnx {Interface Command} {isis csnp-interval <1-600> [level-1 | level-2]} {} -@deffnx {Interface Command} {no isis csnp-interval} {} -@deffnx {Interface Command} {no isis csnp-interval [level-1 | level-2]} {} -Set CSNP interval in seconds globally, for an area (level-1) or a domain (level-2). -@end deffn - -@deffn {Interface Command} {isis hello padding} {} -Add padding to IS-IS hello packets. -@end deffn - -@deffn {Interface Command} {isis hello-interval <1-600>} {} -@deffnx {Interface Command} {isis hello-interval <1-600> [level-1 | level-2]} {} -@deffnx {Interface Command} {no isis hello-interval} {} -@deffnx {Interface Command} {no isis hello-interval [level-1 | level-2]} {} -Set Hello interval in seconds globally, for an area (level-1) or a domain (level-2). -@end deffn - -@deffn {Interface Command} {isis hello-multiplier <2-100>} {} -@deffnx {Interface Command} {isis hello-multiplier <2-100> [level-1 | level-2]} {} -@deffnx {Interface Command} {no isis hello-multiplier} {} -@deffnx {Interface Command} {no isis hello-multiplier [level-1 | level-2]} {} -Set multiplier for Hello holding time globally, for an area (level-1) or a domain (level-2). -@end deffn - -@deffn {Interface Command} {isis metric [<0-255> | <0-16777215>]} {} -@deffnx {Interface Command} {isis metric [<0-255> | <0-16777215>] [level-1 | level-2]} {} -@deffnx {Interface Command} {no isis metric} {} -@deffnx {Interface Command} {no isis metric [level-1 | level-2]} {} -Set default metric value globally, for an area (level-1) or a domain (level-2). -Max value depend if metric support narrow or wide value (see command @ref{metric-style}). -@end deffn - -@deffn {Interface Command} {isis network point-to-point} {} -@deffnx {Interface Command} {no isis network point-to-point} {} -Set network type to 'Point-to-Point' (broadcast by default). -@end deffn - -@deffn {Interface Command} {isis passive} {} -@deffnx {Interface Command} {no isis passive} {} -Configure the passive mode for this interface. -@end deffn - -@deffn {Interface Command} {isis password [clear | md5] } {} -@deffnx {Interface Command} {no isis password} {} -Configure the authentication password (clear or encoded text) for the interface. -@end deffn - -@deffn {Interface Command} {isis priority <0-127>} {} -@deffnx {Interface Command} {isis priority <0-127> [level-1 | level-2]} {} -@deffnx {Interface Command} {no isis priority} {} -@deffnx {Interface Command} {no isis priority [level-1 | level-2]} {} -Set priority for Designated Router election, globally, for the area (level-1) -or the domain (level-2). -@end deffn - -@deffn {Interface Command} {isis psnp-interval <1-120>} {} -@deffnx {Interface Command} {isis psnp-interval <1-120> [level-1 | level-2]} {} -@deffnx {Interface Command} {no isis psnp-interval} {} -@deffnx {Interface Command} {no isis psnp-interval [level-1 | level-2]} {} -Set PSNP interval in seconds globally, for an area (level-1) or a domain (level-2). -@end deffn - -@node Showing ISIS information -@section Showing ISIS information - -@deffn {Command} {show isis summary} {} -Show summary information about ISIS. -@end deffn - -@deffn {Command} {show isis hostname} {} -Show information about ISIS node. -@end deffn - -@deffn {Command} {show isis interface} {} -@deffnx {Command} {show isis interface detail} {} -@deffnx {Command} {show isis interface } {} -Show state and configuration of ISIS specified interface, or all -interfaces if no interface is given with or without details. -@end deffn - -@deffn {Command} {show isis neighbor} {} -@deffnx {Command} {show isis neighbor } {} -@deffnx {Command} {show isis neighbor detail} {} -Show state and information of ISIS specified neighbor, or all -neighbors if no system id is given with or without details. -@end deffn - -@deffn {Command} {show isis database} {} -@deffnx {Command} {show isis database [detail]} {} -@deffnx {Command} {show isis database [detail]} {} -@deffnx {Command} {show isis database detail } {} -Show the ISIS database globally, for a specific LSP id without or with details. -@end deffn - -@deffn {Command} {show isis topology} {} -@deffnx {Command} {show isis topology [level-1|level-2]} {} -Show topology IS-IS paths to Intermediate Systems, globally, -in area (level-1) or domain (level-2). -@end deffn - -@deffn {Command} {show ip route isis} {} -Show the ISIS routing table, as determined by the most recent SPF calculation. -@end deffn - -@node ISIS Traffic Engineering -@section Traffic Engineering - -@deffn {ISIS Command} {mpls-te on} {} -@deffnx {ISIS Command} {no mpls-te} {} -Enable Traffic Engineering LSP flooding. -@end deffn - -@deffn {ISIS Command} {mpls-te router-address } {} -@deffnx {ISIS Command} {no mpls-te router-address} {} -Configure stable IP address for MPLS-TE. -@end deffn - -@deffn {Command} {show isis mpls-te interface} {} -@deffnx {Command} {show isis mpls-te interface @var{interface}} {} -Show MPLS Traffic Engineering parameters for all or specified interface. -@end deffn - -@deffn {Command} {show isis mpls-te router} {} -Show Traffic Engineering router parameters. -@end deffn - -@node Debugging ISIS -@section Debugging ISIS - -@deffn {Command} {debug isis adj-packets} {} -@deffnx {Command} {no debug isis adj-packets} {} -IS-IS Adjacency related packets. -@end deffn - -@deffn {Command} {debug isis checksum-errors} {} -@deffnx {Command} {no debug isis checksum-errors} {} -IS-IS LSP checksum errors. -@end deffn - -@deffn {Command} {debug isis events} {} -@deffnx {Command} {no debug isis events} {} -IS-IS Events. -@end deffn - -@deffn {Command} {debug isis local-updates} {} -@deffnx {Command} {no debug isis local-updates} {} -IS-IS local update packets. -@end deffn - -@deffn {Command} {debug isis packet-dump} {} -@deffnx {Command} {no debug isis packet-dump} {} -IS-IS packet dump. -@end deffn - -@deffn {Command} {debug isis protocol-errors} {} -@deffnx {Command} {no debug isis protocol-errors} {} -IS-IS LSP protocol errors. -@end deffn - -@deffn {Command} {debug isis route-events} {} -@deffnx {Command} {no debug isis route-events} {} -IS-IS Route related events. -@end deffn - -@deffn {Command} {debug isis snp-packets} {} -@deffnx {Command} {no debug isis snp-packets} {} -IS-IS CSNP/PSNP packets. -@end deffn - -@deffn {Command} {debug isis spf-events} {} -@deffnx {Command} {debug isis spf-statistics} {} -@deffnx {Command} {debug isis spf-triggers} {} -@deffnx {Command} {no debug isis spf-events} {} -@deffnx {Command} {no debug isis spf-statistics} {} -@deffnx {Command} {no debug isis spf-triggers} {} -IS-IS Shortest Path First Events, Timing and Statistic Data -and triggering events. -@end deffn - -@deffn {Command} {debug isis update-packets} {} -@deffnx {Command} {no debug isis update-packets} {} -Update related packets. -@end deffn - -@deffn {Command} {show debugging isis} {} -Print which ISIS debug level is activate. -@end deffn - -@node ISIS Configuration Examples -@section ISIS Configuration Examples -A simple example, with MD5 authentication enabled: - -@example -@group -! -interface eth0 - ip router isis FOO - isis network point-to-point - isis circuit-type level-2-only -! -router isis FOO -net 47.0023.0000.0000.0000.0000.0000.0000.1900.0004.00 - metric-style wide - is-type level-2-only -@end group -@end example - - -A Traffic Engineering configuration, with Inter-ASv2 support. - - - First, the 'zebra.conf' part: - -@example -@group -hostname HOSTNAME -password PASSWORD -log file /var/log/zebra.log -! -interface eth0 - ip address 10.2.2.2/24 - mpls-te on - mpls-te link metric 10 - mpls-te link max-bw 1.25e+06 - mpls-te link max-rsv-bw 1.25e+06 - mpls-te link unrsv-bw 0 1.25e+06 - mpls-te link unrsv-bw 1 1.25e+06 - mpls-te link unrsv-bw 2 1.25e+06 - mpls-te link unrsv-bw 3 1.25e+06 - mpls-te link unrsv-bw 4 1.25e+06 - mpls-te link unrsv-bw 5 1.25e+06 - mpls-te link unrsv-bw 6 1.25e+06 - mpls-te link unrsv-bw 7 1.25e+06 - mpls-te link rsc-clsclr 0xab -! -interface eth1 - ip address 10.1.1.1/24 - mpls-te on - mpls-te link metric 10 - mpls-te link max-bw 1.25e+06 - mpls-te link max-rsv-bw 1.25e+06 - mpls-te link unrsv-bw 0 1.25e+06 - mpls-te link unrsv-bw 1 1.25e+06 - mpls-te link unrsv-bw 2 1.25e+06 - mpls-te link unrsv-bw 3 1.25e+06 - mpls-te link unrsv-bw 4 1.25e+06 - mpls-te link unrsv-bw 5 1.25e+06 - mpls-te link unrsv-bw 6 1.25e+06 - mpls-te link unrsv-bw 7 1.25e+06 - mpls-te link rsc-clsclr 0xab - mpls-te neighbor 10.1.1.2 as 65000 -@end group -@end example - - - Then the 'isisd.conf' itself: - -@example -@group -hostname HOSTNAME -password PASSWORD -log file /var/log/isisd.log -! -! -interface eth0 - ip router isis FOO -! -interface eth1 - ip router isis FOO -! -! -router isis FOO - isis net 47.0023.0000.0000.0000.0000.0000.0000.1900.0004.00 - mpls-te on - mpls-te router-address 10.1.1.1 -! -line vty -@end group -@end example diff --git a/doc/kernel.texi b/doc/kernel.texi deleted file mode 100644 index e58ade5a85..0000000000 --- a/doc/kernel.texi +++ /dev/null @@ -1,47 +0,0 @@ -@node Kernel Interface -@chapter Kernel Interface - -There are several different methods for reading kernel routing table -information, updating kernel routing tables, and for looking up -interfaces. - -@table @samp - -@item ioctl -The @samp{ioctl} method is a very traditional way for reading or writing -kernel information. @samp{ioctl} can be used for looking up interfaces -and for modifying interface addresses, flags, mtu settings and other -types of information. Also, @samp{ioctl} can insert and delete kernel -routing table entries. It will soon be available on almost any platform -which zebra supports, but it is a little bit ugly thus far, so if a -better method is supported by the kernel, zebra will use that. - -@item sysctl -@samp{sysctl} can lookup kernel information using MIB (Management -Information Base) syntax. Normally, it only provides a way of getting -information from the kernel. So one would usually want to change kernel -information using another method such as @samp{ioctl}. - -@item proc filesystem -@samp{proc filesystem} provides an easy way of getting kernel -information. - -@item routing socket - -@item netlink -On recent Linux kernels (2.0.x and 2.2.x), there is a kernel/user -communication support called @code{netlink}. It makes asynchronous -communication between kernel and Frr possible, similar to a routing -socket on BSD systems. - -Before you use this feature, be sure to select (in kernel configuration) -the kernel/netlink support option 'Kernel/User network link driver' and -'Routing messages'. - -Today, the /dev/route special device file is obsolete. Netlink -communication is done by reading/writing over netlink socket. - -After the kernel configuration, please reconfigure and rebuild Frr. -You can use netlink as a dynamic routing update channel between Frr -and the kernel. -@end table diff --git a/doc/main.texi b/doc/main.texi deleted file mode 100644 index 9e2ca5e506..0000000000 --- a/doc/main.texi +++ /dev/null @@ -1,525 +0,0 @@ -@node Zebra -@chapter Zebra - -@c SYNOPSIS -@command{zebra} is an IP routing manager. It provides kernel routing -table updates, interface lookups, and redistribution of routes between -different routing protocols. - -@menu -* Invoking zebra:: Running the program -* Interface Commands:: Commands for zebra interfaces -* Static Route Commands:: Commands for adding static routes -* Multicast RIB Commands:: Commands for controlling MRIB behavior -* zebra Route Filtering:: Commands for zebra route filtering -* zebra FIB push interface:: Interface to optional FPM component -* zebra Terminal Mode Commands:: Commands for zebra's VTY -@end menu - - -@node Invoking zebra -@section Invoking zebra - -Besides the common invocation options (@pxref{Common Invocation Options}), the -@command{zebra} specific invocation options are listed below. - -@table @samp -@item -b -@itemx --batch -Runs in batch mode. @command{zebra} parses configuration file and terminates -immediately. - -@item -k -@itemx --keep_kernel -When zebra starts up, don't delete old self inserted routes. - -@item -r -@itemx --retain -When program terminates, retain routes added by zebra. - -@end table - -@node Interface Commands -@section Interface Commands - -@menu -* Standard Commands:: -* Link Parameters Commands:: -@end menu - -@node Standard Commands -@subsection Standard Commands - -@deffn Command {interface @var{ifname}} {} -@end deffn - -@deffn {Interface Command} {shutdown} {} -@deffnx {Interface Command} {no shutdown} {} -Up or down the current interface. -@end deffn - -@deffn {Interface Command} {ip address @var{address/prefix}} {} -@deffnx {Interface Command} {ipv6 address @var{address/prefix}} {} -@deffnx {Interface Command} {no ip address @var{address/prefix}} {} -@deffnx {Interface Command} {no ipv6 address @var{address/prefix}} {} -Set the IPv4 or IPv6 address/prefix for the interface. -@end deffn - -@deffn {Interface Command} {ip address @var{local-addr} peer @var{peer-addr/prefix}} {} -@deffnx {Interface Command} {no ip address @var{local-addr} peer @var{peer-addr/prefix}} {} -Configure an IPv4 Pointopoint address on the interface. -(The concept of PtP addressing does not exist for IPv6.) - -@var{local-addr} has no subnet mask since the local side in PtP -addressing is always a single (/32) address. @var{peer-addr/prefix} -can be an arbitrary subnet behind the other end of the link (or even on the -link in Point-to-Multipoint setups), though generally /32s are used. -@end deffn - -@deffn {Interface Command} {ip address @var{address/prefix} secondary} {} -@deffnx {Interface Command} {no ip address @var{address/prefix} secondary} {} -Set the secondary flag for this address. This causes ospfd to not treat the -address as a distinct subnet. -@end deffn - -@deffn {Interface Command} {description @var{description} ...} {} -Set description for the interface. -@end deffn - -@deffn {Interface Command} {multicast} {} -@deffnx {Interface Command} {no multicast} {} -Enable or disables multicast flag for the interface. -@end deffn - -@deffn {Interface Command} {bandwidth <1-10000000>} {} -@deffnx {Interface Command} {no bandwidth <1-10000000>} {} -Set bandwidth value of the interface in kilobits/sec. This is for -calculating OSPF cost. This command does not affect the actual device -configuration. -@end deffn - -@deffn {Interface Command} {link-detect} {} -@deffnx {Interface Command} {no link-detect} {} -Enable/disable link-detect on platforms which support this. Currently -only Linux and Solaris, and only where network interface drivers support reporting -link-state via the IFF_RUNNING flag. -@end deffn - -@node Link Parameters Commands -@subsection Link Parameters Commands - -@deffn {Interface Command} {link-params} {} -@deffnx {Interface Command} {no link-param} {} -Enter into the link parameters sub node. At least 'enable' must be set to activate the link parameters, -and consequently Traffic Engineering on this interface. MPLS-TE must be enable at the OSPF (@ref{OSPF Traffic Engineering}) -or ISIS (@ref{ISIS Traffic Engineering}) router level in complement to this. -Disable link parameters for this interface. -@end deffn - -Under link parameter statement, the following commands set the different TE values: - -@deffn link-params {enable} -Enable link parameters for this interface. -@end deffn - -@deffn link-params {metric <0-4294967295>} {} -@deffnx link-params {max-bw @var{bandwidth}} {} -@deffnx link-params {max-rsv-bw @var{bandwidth}} {} -@deffnx link-params {unrsv-bw <0-7> @var{bandwidth}} {} -@deffnx link-params {admin-grp @var{bandwidth}} {} -These commands specifies the Traffic Engineering parameters of the interface in conformity to RFC3630 (OSPF) -or RFC5305 (ISIS). -There are respectively the TE Metric (different from the OSPF or ISIS metric), Maximum Bandwidth (interface speed -by default), Maximum Reservable Bandwidth, Unreserved Bandwidth for each 0-7 priority and Admin Group (ISIS) or -Resource Class/Color (OSPF). - -Note that @var{bandwidth} are specified in IEEE floating point format and express in Bytes/second. -@end deffn - -@deffn link-param {delay <0-16777215> [min <0-16777215> | max <0-16777215>]} {} -@deffnx link-param {delay-variation <0-16777215>} {} -@deffnx link-param {packet-loss @var{percentage}} {} -@deffnx link-param {res-bw @var{bandwidth}} {} -@deffnx link-param {ava-bw @var{bandwidth}} {} -@deffnx link-param {use-bw @var{bandwidth}} {} -These command specifies additionnal Traffic Engineering parameters of the interface in conformity to -draft-ietf-ospf-te-metrics-extension-05.txt and draft-ietf-isis-te-metrics-extension-03.txt. There are -respectively the delay, jitter, loss, available bandwidth, reservable bandwidth and utilized bandwidth. - -Note that @var{bandwidth} are specified in IEEE floating point format and express in Bytes/second. -Delays and delay variation are express in micro-second (µs). Loss is specified in @var{percentage} ranging -from 0 to 50.331642% by step of 0.000003. -@end deffn - -@deffn link-param {neighbor as <0-65535>} {} -@deffnx link-param {no neighbor} {} -Specifies the remote ASBR IP address and Autonomous System (AS) number for InterASv2 link in OSPF (RFC5392). -Note that this option is not yet supported for ISIS (RFC5316). -@end deffn - - -@node Static Route Commands -@section Static Route Commands - -Static routing is a very fundamental feature of routing technology. It -defines static prefix and gateway. - -@deffn Command {ip route @var{network} @var{gateway}} {} -@var{network} is destination prefix with format of A.B.C.D/M. -@var{gateway} is gateway for the prefix. When @var{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 @var{null0} then -zebra installs a blackhole route. - -@example -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 -@end example - -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. -@end deffn - -@deffn Command {ip route @var{network} @var{netmask} @var{gateway}} {} -This is alternate version of above command. When @var{network} is -A.B.C.D format, user must define @var{netmask} value with A.B.C.D -format. @var{gateway} is same option as above command - -@example -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 -@end example - -These statements are equivalent to those in the previous example. -@end deffn - -@deffn Command {ip route @var{network} @var{gateway} @var{distance}} {} -Installs the route with the specified distance. -@end deffn - -Multiple nexthop static route - -@example -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 -@end example - -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. - -@example -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 -@end example - -@example -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 -@end example - -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 (eg -default) should the specified gateways not be reachable. Eg: - -@example -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 -@end example - -@deffn Command {ipv6 route @var{network} @var{gateway}} {} -@deffnx Command {ipv6 route @var{network} @var{gateway} @var{distance}} {} -These behave similarly to their ipv4 counterparts. -@end deffn - -@deffn Command {ipv6 route @var{network} from @var{srcprefix} @var{gateway}} {} -@deffnx Command {ipv6 route @var{network} from @var{srcprefix} @var{gateway} @var{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. -@command{"2001:db8:1::/64 from 2001:db8::/48"} will win over -@command{"2001:db8::/48 from 2001:db8:1::/64"} if both match. -@end deffn - - -@deffn Command {table @var{tableno}} {} -Select the primary kernel routing table to be used. This only works -for kernels supporting multiple routing tables (like GNU/Linux 2.2.x -and later). After setting @var{tableno} with this command, -static routes defined after this are added to the specified table. -@end deffn - -@node Multicast RIB Commands -@section Multicast RIB Commands - -The Multicast RIB provides a separate table of unicast destinations which -is used for Multicast Reverse Path Forwarding decisions. It is used with -a multicast source's IP address, hence contains not multicast group -addresses but unicast addresses. - -This table is fully separate from the default unicast table. However, -RPF lookup can include the unicast table. - -WARNING: RPF lookup results are non-responsive in this version of Frr, -i.e. multicast routing does not actively react to changes in underlying -unicast topology! - -@deffn Command {ip multicast rpf-lookup-mode @var{mode}} {} -@deffnx Command {no ip multicast rpf-lookup-mode [@var{mode}]} {} - -@var{mode} sets the method used to perform RPF lookups. Supported modes: - -@table @samp -@item urib-only -Performs the lookup on the Unicast RIB. The Multicast RIB is never used. -@item mrib-only -Performs the lookup on the Multicast RIB. The Unicast RIB is never used. -@item mrib-then-urib -Tries to perform the lookup on the Multicast RIB. If any route is found, -that route is used. Otherwise, the Unicast RIB is tried. -@item lower-distance -Performs a lookup on the Multicast RIB and Unicast RIB each. The result -with the lower administrative distance is used; if they're equal, the -Multicast RIB takes precedence. -@item longer-prefix -Performs a lookup on the Multicast RIB and Unicast RIB each. The result -with the longer prefix length is used; if they're equal, the -Multicast RIB takes precedence. -@end table - -The @code{mrib-then-urib} setting is the default behavior if nothing is -configured. If this is the desired behavior, it should be explicitly -configured to make the configuration immune against possible changes in -what the default behavior is. - -WARNING: Unreachable routes do not receive special treatment and do not -cause fallback to a second lookup. -@end deffn - -@deffn Command {show ip rpf @var{addr}} {} - -Performs a Multicast RPF lookup, as configured with -@command{ip multicast rpf-lookup-mode @var{mode}}. @var{addr} specifies -the multicast source address to look up. - -@example -> show ip rpf 192.0.2.1 -Routing entry for 192.0.2.0/24 using Unicast RIB - Known via "kernel", distance 0, metric 0, best - * 198.51.100.1, via eth0 -@end example - -Indicates that a multicast source lookup for 192.0.2.1 would use an -Unicast RIB entry for 192.0.2.0/24 with a gateway of 198.51.100.1. -@end deffn - -@deffn Command {show ip rpf} {} - -Prints the entire Multicast RIB. Note that this is independent of the -configured RPF lookup mode, the Multicast RIB may be printed yet not -used at all. -@end deffn - -@deffn Command {ip mroute @var{prefix} @var{nexthop} [@var{distance}]} {} -@deffnx Command {no ip mroute @var{prefix} @var{nexthop} [@var{distance}]} {} - -Adds a static route entry to the Multicast RIB. This performs exactly as -the @command{ip route} command, except that it inserts the route in the -Multicast RIB instead of the Unicast RIB. -@end deffn - - -@node zebra Route Filtering -@section zebra Route Filtering -Zebra supports @command{prefix-list} and @command{route-map} to match -routes received from other frr components. The -@command{permit}/@command{deny} facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -@deffn Command {ip protocol @var{protocol} route-map @var{routemap}} {} -Apply a route-map filter to routes for the specified protocol. @var{protocol} -can be @b{any} or one of -@b{system}, -@b{kernel}, -@b{connected}, -@b{static}, -@b{rip}, -@b{ripng}, -@b{ospf}, -@b{ospf6}, -@b{isis}, -@b{bgp}, -@b{hsls}. -@end deffn - -@deffn {Route Map} {set src @var{address}} -Within a route-map, set the preferred source address for matching routes -when installing in the kernel. -@end deffn - -@example -The following creates a prefix-list that matches all addresses, a route-map -that sets the preferred source address, and applies the route-map to all -@command{rip} routes. - -@group -ip prefix-list ANY permit 0.0.0.0/0 le 32 -route-map RM1 permit 10 - match ip address prefix-list ANY - set src 10.0.0.1 - -ip protocol rip route-map RM1 -@end group -@end example - -@node zebra FIB push interface -@section zebra FIB push interface - -Zebra supports a 'FIB push' interface that allows an external -component to learn the forwarding information computed by the Frr -routing suite. This is a loadable module that needs to be enabled -at startup as described in @ref{Loadable Module Support}. - -In Frr, the Routing Information Base (RIB) resides inside -zebra. Routing protocols communicate their best routes to zebra, and -zebra computes the best route across protocols for each prefix. This -latter information makes up the Forwarding Information Base -(FIB). Zebra feeds the FIB to the kernel, which allows the IP stack in -the kernel to forward packets according to the routes computed by -Frr. The kernel FIB is updated in an OS-specific way. For example, -the @code{netlink} interface is used on Linux, and route sockets are -used on FreeBSD. - -The FIB push interface aims to provide a cross-platform mechanism to -support scenarios where the router has a forwarding path that is -distinct from the kernel, commonly a hardware-based fast path. In -these cases, the FIB needs to be maintained reliably in the fast path -as well. We refer to the component that programs the forwarding plane -(directly or indirectly) as the Forwarding Plane Manager or FPM. - -The FIB push interface comprises of a TCP connection between zebra and -the FPM. The connection is initiated by zebra -- that is, the FPM acts -as the TCP server. - -The relevant zebra code kicks in when zebra is configured with the -@code{--enable-fpm} flag. Zebra periodically attempts to connect to -the well-known FPM port. Once the connection is up, zebra starts -sending messages containing routes over the socket to the FPM. Zebra -sends a complete copy of the forwarding table to the FPM, including -routes that it may have picked up from the kernel. The existing -interaction of zebra with the kernel remains unchanged -- that is, the -kernel continues to receive FIB updates as before. - -The encapsulation header for the messages exchanged with the FPM is -defined by the file @file{fpm/fpm.h} in the frr tree. The routes -themselves are encoded in netlink or protobuf format, with netlink -being the default. - -Protobuf is one of a number of new serialization formats wherein the -message schema is expressed in a purpose-built language. Code for -encoding/decoding to/from the wire format is generated from the -schema. Protobuf messages can be extended easily while maintaining -backward-compatibility with older code. Protobuf has the following -advantages over netlink: - -@itemize -@item -Code for serialization/deserialization is generated -automatically. This reduces the likelihood of bugs, allows third-party -programs to be integrated quickly, and makes it easy to add fields. -@item -The message format is not tied to an OS (Linux), and can be evolved -independently. -@end itemize - -As mentioned before, zebra encodes routes sent to the FPM in netlink -format by default. The format can be controlled via the FPM module's -load-time option to zebra, which currently takes the values @code{netlink} -and @code{protobuf}. - -The zebra FPM interface uses replace semantics. That is, if a 'route -add' message for a prefix is followed by another 'route add' message, -the information in the second message is complete by itself, and -replaces the information sent in the first message. - -If the connection to the FPM goes down for some reason, zebra sends -the FPM a complete copy of the forwarding table(s) when it reconnects. - -@node zebra Terminal Mode Commands -@section zebra Terminal Mode Commands - -@deffn Command {show ip route} {} -Display current routes which zebra holds in its database. - -@example -@group -Router# show ip route -Codes: K - kernel route, C - connected, S - static, R - RIP, - B - BGP * - FIB route. - -K* 0.0.0.0/0 203.181.89.241 -S 0.0.0.0/0 203.181.89.1 -C* 127.0.0.0/8 lo -C* 203.181.89.240/28 eth0 -@end group -@end example -@end deffn - -@deffn Command {show ipv6 route} {} -@end deffn - -@deffn Command {show interface} {} -@end deffn - -@deffn Command {show ip prefix-list [@var{name}]} {} -@end deffn - -@deffn Command {show route-map [@var{name}]} {} -@end deffn - -@deffn Command {show ip protocol} {} -@end deffn - -@deffn Command {show ipforward} {} -Display whether the host's IP forwarding function is enabled or not. -Almost any UNIX kernel can be configured with IP forwarding disabled. -If so, the box can't work as a router. -@end deffn - -@deffn Command {show ipv6forward} {} -Display whether the host's IP v6 forwarding is enabled or not. -@end deffn - -@deffn Command {show zebra} {} -Display various statistics related to the installation and deletion -of routes, neighbor updates, and LSP's into the kernel. -@end deffn - -@deffn Command {show zebra fpm stats} {} -Display statistics related to the zebra code that interacts with the -optional Forwarding Plane Manager (FPM) component. -@end deffn - -@deffn Command {clear zebra fpm stats} {} -Reset statistics related to the zebra code that interacts with the -optional Forwarding Plane Manager (FPM) component. -@end deffn diff --git a/doc/nhrpd.texi b/doc/nhrpd.texi deleted file mode 100644 index 069b46495c..0000000000 --- a/doc/nhrpd.texi +++ /dev/null @@ -1,145 +0,0 @@ -@cindex NHRP -@node NHRP -@chapter NHRP - -@command{nhrpd} is a daemon to support Next Hop Routing Protocol (NHRP). -NHRP is described in RFC2332. - -NHRP is used to improve the efficiency of routing computer network -traffic over Non-Broadcast, Multiple Access (NBMA) Networks. NHRP provides -an ARP-like solution that allows a system to dynamically learn the NBMA -address of the other systems that are part of that network, allowing -these systems to directly communicate without requiring traffic to use -an intermediate hop. - -Cisco Dynamic Multipoint VPN (DMVPN) is based on NHRP, and -@value{PACKAGE_NAME} nhrpd implements this scenario. - -@menu -* Routing Design:: -* Configuring NHRP:: -* Hub Functionality:: -* Integration with IKE:: -* NHRP Events:: -* Configuration Example:: -@end menu - -@node Routing Design -@section Routing Design - -nhrpd never handles routing of prefixes itself. You need to run some -real routing protocol (e.g. BGP) to advertise routes over the tunnels. -What nhrpd does it establishes 'shortcut routes' that optimizes the -routing protocol to avoid going through extra nodes in NBMA GRE mesh. - -nhrpd does route NHRP domain addresses individually using per-host prefixes. -This is similar to Cisco FlexVPN; but in contrast to opennhrp which uses -a generic subnet route. - -To create NBMA GRE tunnel you might use the following (linux terminal -commands): -@example -@group - ip tunnel add gre1 mode gre key 42 ttl 64 - ip addr add 10.255.255.2/32 dev gre1 - ip link set gre1 up -@end group -@end example - -Note that the IP-address is assigned as host prefix to gre1. nhrpd will -automatically create additional host routes pointing to gre1 when -a connection with these hosts is established. - -The gre1 subnet prefix should be announced by routing protocol from the -hub nodes (e.g. BGP 'network' announce). This allows the routing protocol -to decide which is the closest hub and determine the relay hub on prefix -basis when direct tunnel is not established. - -nhrpd will redistribute directly connected neighbors to zebra. Within -hub nodes, these routes should be internally redistributed using some -routing protocol (e.g. iBGP) to allow hubs to be able to relay all traffic. - -This can be achieved in hubs with the following bgp configuration (network -command defines the GRE subnet): -@example -@group -router bgp 65555 - address-family ipv4 unicast - network 172.16.0.0/16 - redistribute nhrp - exit-address-family -@end group -@end example - - -@node Configuring NHRP -@section Configuring NHRP - -FIXME - -@node Hub Functionality -@section Hub Functionality - -In addition to routing nhrp redistributed host prefixes, the hub nodes -are also responsible to send NHRP Traffic Indication messages that -trigger creation of the shortcut tunnels. - -nhrpd sends Traffic Indication messages based on network traffic captured -using NFLOG. Typically you want to send Traffic Indications for network -traffic that is routed from gre1 back to gre1 in rate limited manner. -This can be achieved with the following iptables rule. - -@example -@group -iptables -A FORWARD -i gre1 -o gre1 \ - -m hashlimit --hashlimit-upto 4/minute --hashlimit-burst 1 \ - --hashlimit-mode srcip,dstip --hashlimit-srcmask 24 --hashlimit-dstmask 24 \ - --hashlimit-name loglimit-0 -j NFLOG --nflog-group 1 --nflog-range 128 -@end group -@end example - -You can fine tune the src/dstmask according to the prefix lengths you -announce internal, add additional IP range matches, or rate limitation -if needed. However, the above should be good in most cases. - -This kernel NFLOG target's nflog-group is configured in global nhrp config -with: -@example -@group -nhrp nflog-group 1 -@end group -@end example - -To start sending these traffic notices out from hubs, use the nhrp -per-interface directive: -@example -@group -interface gre1 - ip nhrp redirect -@end group -@end example - -@node Integration with IKE -@section Integration with IKE - -nhrpd needs tight integration with IKE daemon for various reasons. -Currently only strongSwan is supported as IKE daemon. - -nhrpd connects to strongSwan using VICI protocol based on UNIX socket -(hardcoded now as /var/run/charon.vici). - -strongSwan currently needs few patches applied. Please check out the -@uref{http://git.alpinelinux.org/cgit/user/tteras/strongswan/log/?h=tteras-release,release} -and -@uref{http://git.alpinelinux.org/cgit/user/tteras/strongswan/log/?h=tteras,working tree} -git repositories for the patches. - -@node NHRP Events -@section NHRP Events - -FIXME - -@node Configuration Example -@section Configuration Example - -FIXME diff --git a/doc/ospf6d.texi b/doc/ospf6d.texi deleted file mode 100644 index 3ea71fbd20..0000000000 --- a/doc/ospf6d.texi +++ /dev/null @@ -1,172 +0,0 @@ -@node OSPFv3 -@chapter OSPFv3 - -@command{ospf6d} is a daemon support OSPF version 3 for IPv6 network. -OSPF for IPv6 is described in RFC2740. - -@menu -* OSPF6 router:: -* OSPF6 area:: -* OSPF6 interface:: -* Redistribute routes to OSPF6:: -* Showing OSPF6 information:: -* OSPF6 Configuration Examples:: -@end menu - -@node OSPF6 router -@section OSPF6 router - -@deffn {Command} {router ospf6} {} -@end deffn - -@deffn {OSPF6 Command} {router-id @var{a.b.c.d}} {} -Set router's Router-ID. -@end deffn - -@deffn {OSPF6 Command} {interface @var{ifname} area @var{area}} {} -Bind interface to specified area, and start sending OSPF packets. @var{area} can -be specified as 0. -@end deffn - -@deffn {OSPF6 Command} {timers throttle spf @var{delay} @var{initial-holdtime} @var{max-holdtime}} {} -@deffnx {OSPF6 Command} {no timers throttle spf} {} -This command sets the initial @var{delay}, the @var{initial-holdtime} -and the @var{maximum-holdtime} between when SPF is calculated and the -event which triggered the calculation. The times are specified in -milliseconds and must be in the range of 0 to 600000 milliseconds. - -The @var{delay} specifies the minimum amount of time to delay SPF -calculation (hence it affects how long SPF calculation is delayed after -an event which occurs outside of the holdtime of any previous SPF -calculation, and also serves as a minimum holdtime). - -Consecutive SPF calculations will always be seperated by at least -'hold-time' milliseconds. The hold-time is adaptive and initially is -set to the @var{initial-holdtime} configured with the above command. -Events which occur within the holdtime of the previous SPF calculation -will cause the holdtime to be increased by @var{initial-holdtime}, bounded -by the @var{maximum-holdtime} configured with this command. If the adaptive -hold-time elapses without any SPF-triggering event occuring then -the current holdtime is reset to the @var{initial-holdtime}. - -@example -@group -router ospf6 - timers throttle spf 200 400 10000 -@end group -@end example - -In this example, the @var{delay} is set to 200ms, the @var{initial -holdtime} is set to 400ms and the @var{maximum holdtime} to 10s. Hence -there will always be at least 200ms between an event which requires SPF -calculation and the actual SPF calculation. Further consecutive SPF -calculations will always be seperated by between 400ms to 10s, the -hold-time increasing by 400ms each time an SPF-triggering event occurs -within the hold-time of the previous SPF calculation. - -@end deffn - -@deffn {OSPF6 Command} {auto-cost reference-bandwidth @var{cost}} {} -@deffnx {OSPF6 Command} {no auto-cost reference-bandwidth} {} -This sets the reference bandwidth for cost calculations, where this -bandwidth is considered equivalent to an OSPF cost of 1, specified in -Mbits/s. The default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s -or higher will have a cost of 1. Cost of lower bandwidth links will be -scaled with reference to this cost). - -This configuration setting MUST be consistent across all routers -within the OSPF domain. -@end deffn - -@node OSPF6 area -@section OSPF6 area - -Area support for OSPFv3 is not yet implemented. - -@node OSPF6 interface -@section OSPF6 interface - -@deffn {Interface Command} {ipv6 ospf6 cost COST} {} -Sets interface's output cost. Default value depends on the interface -bandwidth and on the auto-cost reference bandwidth. -@end deffn - -@deffn {Interface Command} {ipv6 ospf6 hello-interval HELLOINTERVAL} {} -Sets interface's Hello Interval. Default 40 -@end deffn - -@deffn {Interface Command} {ipv6 ospf6 dead-interval DEADINTERVAL} {} -Sets interface's Router Dead Interval. Default value is 40. -@end deffn - -@deffn {Interface Command} {ipv6 ospf6 retransmit-interval RETRANSMITINTERVAL} {} -Sets interface's Rxmt Interval. Default value is 5. -@end deffn - -@deffn {Interface Command} {ipv6 ospf6 priority PRIORITY} {} -Sets interface's Router Priority. Default value is 1. -@end deffn - -@deffn {Interface Command} {ipv6 ospf6 transmit-delay TRANSMITDELAY} {} -Sets interface's Inf-Trans-Delay. Default value is 1. -@end deffn - -@deffn {Interface Command} {ipv6 ospf6 network (broadcast|point-to-point)} {} -Set explicitly network type for specifed interface. -@end deffn - -@node Redistribute routes to OSPF6 -@section Redistribute routes to OSPF6 - -@deffn {OSPF6 Command} {redistribute static} {} -@deffnx {OSPF6 Command} {redistribute connected} {} -@deffnx {OSPF6 Command} {redistribute ripng} {} -@end deffn - -@node Showing OSPF6 information -@section Showing OSPF6 information - -@deffn {Command} {show ipv6 ospf6 [INSTANCE_ID]} {} -INSTANCE_ID is an optional OSPF instance ID. To see router ID and OSPF -instance ID, simply type "show ipv6 ospf6 ". -@end deffn - -@deffn {Command} {show ipv6 ospf6 database} {} -This command shows LSA database summary. You can specify the type of LSA. -@end deffn - -@deffn {Command} {show ipv6 ospf6 interface} {} -To see OSPF interface configuration like costs. -@end deffn - -@deffn {Command} {show ipv6 ospf6 neighbor} {} -Shows state and chosen (Backup) DR of neighbor. -@end deffn - -@deffn {Command} {show ipv6 ospf6 request-list A.B.C.D} {} -Shows requestlist of neighbor. -@end deffn - -@deffn {Command} {show ipv6 route ospf6} {} -This command shows internal routing table. -@end deffn - -@deffn {Command} {show ipv6 ospf6 zebra} {} -Shows state about what is being redistributed between zebra and OSPF6 -@end deffn - -@node OSPF6 Configuration Examples -@section OSPF6 Configuration Examples - -Example of ospf6d configured on one interface and area: - -@example -interface eth0 - ipv6 ospf6 instance-id 0 -! -router ospf6 - router-id 212.17.55.53 - area 0.0.0.0 range 2001:770:105:2::/64 - interface eth0 area 0.0.0.0 -! -@end example diff --git a/doc/ospf_fundamentals.texi b/doc/ospf_fundamentals.texi deleted file mode 100644 index 82218e6015..0000000000 --- a/doc/ospf_fundamentals.texi +++ /dev/null @@ -1,582 +0,0 @@ -@c Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. -@cindex OSPF Fundamentals -@node OSPF Fundamentals -@section OSPF Fundamentals - -@cindex Link-state routing protocol -@cindex Distance-vector routing protocol -@acronym{OSPF} is, mostly, a link-state routing protocol. In contrast -to @dfn{distance-vector} protocols, such as @acronym{RIP} or -@acronym{BGP}, where routers describe available @dfn{paths} (i.e@. routes) -to each other, in @dfn{link-state} protocols routers instead -describe the state of their links to their immediate neighbouring -routers. - -@cindex Link State Announcement -@cindex Link State Advertisement -@cindex LSA flooding -@cindex Link State DataBase -Each router describes their link-state information in a message known -as an @acronym{LSA,Link State Advertisement}, which is then propogated -through to all other routers in a link-state routing domain, by a -process called @dfn{flooding}. Each router thus builds up an -@acronym{LSDB,Link State Database} of all the link-state messages. From -this collection of LSAs in the LSDB, each router can then calculate the -shortest path to any other router, based on some common metric, by -using an algorithm such as @url{http://www.cs.utexas.edu/users/EWD/, -Edgser Dijkstra}'s @acronym{SPF,Shortest Path First}. - -@cindex Link-state routing protocol advantages -By describing connectivity of a network in this way, in terms of -routers and links rather than in terms of the paths through a network, -a link-state protocol can use less bandwidth and converge more quickly -than other protocols. A link-state protocol need distribute only one -link-state message throughout the link-state domain when a link on any -single given router changes state, in order for all routers to -reconverge on the best paths through the network. In contrast, distance -vector protocols can require a progression of different path update -messages from a series of different routers in order to converge. - -@cindex Link-state routing protocol disadvantages -The disadvantage to a link-state protocol is that the process of -computing the best paths can be relatively intensive when compared to -distance-vector protocols, in which near to no computation need be done -other than (potentially) select between multiple routes. This overhead -is mostly negligible for modern embedded CPUs, even for networks with -thousands of nodes. The primary scaling overhead lies more in coping -with the ever greater frequency of LSA updates as the size of a -link-state area increases, in managing the @acronym{LSDB} and required -flooding. - -This section aims to give a distilled, but accurate, description of the -more important workings of @acronym{OSPF}@ which an administrator may need -to know to be able best configure and trouble-shoot @acronym{OSPF}@. - -@subsection OSPF Mechanisms - -@acronym{OSPF} defines a range of mechanisms, concerned with detecting, -describing and propogating state through a network. These mechanisms -will nearly all be covered in greater detail further on. They may be -broadly classed as: - -@table @dfn -@cindex OSPF Hello Protocol overview -@item The Hello Protocol - -@cindex OSPF Hello Protocol -The OSPF Hello protocol allows OSPF to quickly detect changes in -two-way reachability between routers on a link. OSPF can additionally -avail of other sources of reachability information, such as link-state -information provided by hardware, or through dedicated reachability -protocols such as @acronym{BFD,Bi-directional Forwarding Detection}. - -OSPF also uses the Hello protocol to propagate certain state between -routers sharing a link, for example: - -@itemize @bullet -@item Hello protocol configured state, such as the dead-interval. -@item Router priority, for DR/BDR election. -@item DR/BDR election results. -@item Any optional capabilities supported by each router. -@end itemize - -The Hello protocol is comparatively trivial and will not be explored in -greater detail than here. - -@cindex OSPF LSA overview -@item LSAs - -At the heart of @acronym{OSPF} are @acronym{LSA,Link State -Advertisement} messages. Despite the name, some @acronym{LSA}s do not, -strictly speaking, describe link-state information. Common -@acronym{LSA}s describe information such as: - -@itemize @bullet -@item -Routers, in terms of their links. -@item -Networks, in terms of attached routers. -@item -Routes, external to a link-state domain: - -@itemize @bullet -@item External Routes - -Routes entirely external to @acronym{OSPF}@. Routers originating such -routes are known as @acronym{ASBR,Autonomous-System Border Router} -routers. - -@item Summary Routes - -Routes which summarise routing information relating to OSPF areas -external to the OSPF link-state area at hand, originated by -@acronym{ABR,Area Boundary Router} routers. -@end itemize -@end itemize - -@item LSA Flooding -OSPF defines several related mechanisms, used to manage synchronisation of -@acronym{LSDB}s between neighbours as neighbours form adjacencies and -the propogation, or @dfn{flooding} of new or updated @acronym{LSA}s. - -@xref{OSPF Flooding}. - -@cindex OSPF Areas overview -@item Areas -OSPF provides for the protocol to be broken up into multiple smaller -and independent link-state areas. Each area must be connected to a -common backbone area by an @acronym{ABR,Area Boundary Router}. These -@acronym{ABR} routers are responsible for summarising the link-state -routing information of an area into @dfn{Summary LSAs}, possibly in a -condensed (i.e. aggregated) form, and then originating these summaries -into all other areas the @acronym{ABR} is connected to. - -Note that only summaries and external routes are passed between areas. -As these describe @emph{paths}, rather than any router link-states, -routing between areas hence is by @dfn{distance-vector}, @strong{not} -link-state. - -@xref{OSPF Areas}. -@end table - -@subsection OSPF LSAs - -@acronym{LSA}s are the core object in OSPF@. Everything else in OSPF -revolves around detecting what to describe in LSAs, when to update -them, how to flood them throughout a network and how to calculate -routes from them. - -There are a variety of different @acronym{LSA}s, for purposes such -as describing actual link-state information, describing paths (i.e. -routes), describing bandwidth usage of links for -@acronym{TE,Traffic Engineering} purposes, and even arbitrary data -by way of @emph{Opaque} @acronym{LSA}s. - -@subsubsection LSA Header -All LSAs share a common header with the following information: - -@itemize @bullet -@item Type - -Different types of @acronym{LSA}s describe different things in -@acronym{OSPF}@. Types include: - -@itemize @bullet -@item Router LSA -@item Network LSA -@item Network Summary LSA -@item Router Summary LSA -@item AS-External LSA -@end itemize - -The specifics of the different types of LSA are examined below. - -@item Advertising Router - -The Router ID of the router originating the LSA, see @ref{ospf router-id}. - -@item LSA ID - -The ID of the LSA, which is typically derived in some way from the -information the LSA describes, e.g. a Router LSA uses the Router ID as -the LSA ID, a Network LSA will have the IP address of the @acronym{DR} -as its LSA ID@. - -The combination of the Type, ID and Advertising Router ID must uniquely -identify the @acronym{LSA}@. There can however be multiple instances of -an LSA with the same Type, LSA ID and Advertising Router ID, see -@ref{OSPF LSA sequence number,,LSA Sequence Number}. - -@item Age - -A number to allow stale @acronym{LSA}s to, eventually, be purged by routers -from their @acronym{LSDB}s. - -The value nominally is one of seconds. An age of 3600, i.e. 1 hour, is -called the @dfn{MaxAge}. MaxAge LSAs are ignored in routing -calculations. LSAs must be periodically refreshed by their Advertising -Router before reaching MaxAge if they are to remain valid. - -Routers may deliberately flood LSAs with the age artificially set to -3600 to indicate an LSA is no longer valid. This is called -@dfn{flushing} of an LSA@. - -It is not abnormal to see stale LSAs in the LSDB, this can occur where -a router has shutdown without flushing its LSA(s), e.g. where it has -become disconnected from the network. Such LSAs do little harm. - -@anchor{OSPF LSA sequence number} -@item Sequence Number - -A number used to distinguish newer instances of an LSA from older instances. -@end itemize - -@subsubsection Link-State LSAs -Of all the various kinds of @acronym{LSA}s, just two types comprise the -actual link-state part of @acronym{OSPF}, Router @acronym{LSA}s and -Network @acronym{LSA}s. These LSA types are absolutely core to the -protocol. - -Instances of these LSAs are specific to the link-state area in which -they are originated. Routes calculated from these two LSA types are -called @dfn{intra-area routes}. - -@itemize @bullet -@item Router LSA - -Each OSPF Router must originate a router @acronym{LSA} to describe -itself. In it, the router lists each of its @acronym{OSPF} enabled -interfaces, for the given link-state area, in terms of: - -@itemize @bullet -@item Cost - -The output cost of that interface, scaled inversely to some commonly known -reference value, @xref{OSPF auto-cost reference-bandwidth,,auto-cost -reference-bandwidth}. - -@item Link Type -@itemize @bullet -@item Transit Network - -A link to a multi-access network, on which the router has at least one -Full adjacency with another router. - -@item @acronym{PtP,Point-to-Point} - -A link to a single remote router, with a Full adjacency. No -@acronym{DR, Designated Router} is elected on such links; no network -LSA is originated for such a link. - -@item Stub - -A link with no adjacent neighbours, or a host route. -@end itemize - -@item Link ID and Data - -These values depend on the Link Type: - -@multitable @columnfractions .18 .32 .32 -@headitem Link Type @tab Link ID @tab Link Data - -@item Transit -@tab Link IP address of the @acronym{DR} -@tab Interface IP address - -@item Point-to-Point -@tab Router ID of the remote router -@tab Local interface IP address, -or the @acronym{ifindex,MIB-II interface index} -for unnumbered links - -@item Stub -@tab IP address -@tab Subnet Mask - -@end multitable -@end itemize - -Links on a router may be listed multiple times in the Router LSA, e.g. -a @acronym{PtP} interface on which OSPF is enabled must @emph{always} -be described by a Stub link in the Router @acronym{LSA}, in addition to -being listed as PtP link in the Router @acronym{LSA} if the adjacency -with the remote router is Full. - -Stub links may also be used as a way to describe links on which OSPF is -@emph{not} spoken, known as @dfn{passive interfaces}, see @ref{OSPF -passive-interface,,passive-interface}. - -@item Network LSA - -On multi-access links (e.g. ethernets, certain kinds of ATM and X@.25 -configurations), routers elect a @acronym{DR}@. The @acronym{DR} is -responsible for originating a Network @acronym{LSA}, which helps reduce -the information needed to describe multi-access networks with multiple -routers attached. The @acronym{DR} also acts as a hub for the flooding of -@acronym{LSA}s on that link, thus reducing flooding overheads. - -The contents of the Network LSA describes the: - -@itemize @bullet -@item Subnet Mask - -As the @acronym{LSA} ID of a Network LSA must be the IP address of the -@acronym{DR}, the Subnet Mask together with the @acronym{LSA} ID gives -you the network address. - -@item Attached Routers - -Each router fully-adjacent with the @acronym{DR} is listed in the LSA, -by their Router-ID. This allows the corresponding Router @acronym{LSA}s to be -easily retrieved from the @acronym{LSDB}@. -@end itemize -@end itemize - -Summary of Link State LSAs: - -@multitable @columnfractions .18 .32 .40 -@headitem LSA Type @tab LSA ID Describes @tab LSA Data Describes - -@item Router LSA -@tab The Router ID -@tab The @acronym{OSPF} enabled links of the router, within - a specific link-state area. - -@item Network LSA -@tab The IP address of the @acronym{DR} for the network -@tab The Subnet Mask of the network, and the Router IDs of all routers - on the network. -@end multitable - -With an LSDB composed of just these two types of @acronym{LSA}, it is -possible to construct a directed graph of the connectivity between all -routers and networks in a given OSPF link-state area. So, not -surprisingly, when OSPF routers build updated routing tables, the first -stage of @acronym{SPF} calculation concerns itself only with these two -LSA types. - -@subsubsection Link-State LSA Examples - -The example below (@pxref{OSPF Link-State LSA Example}) shows two -@acronym{LSA}s, both originated by the same router (Router ID -192.168.0.49) and with the same @acronym{LSA} ID (192.168.0.49), but of -different LSA types. - -The first LSA being the router LSA describing 192.168.0.49's links: 2 links -to multi-access networks with fully-adjacent neighbours (i.e. Transit -links) and 1 being a Stub link (no adjacent neighbours). - -The second LSA being a Network LSA, for which 192.168.0.49 is the -@acronym{DR}, listing the Router IDs of 4 routers on that network which -are fully adjacent with 192.168.0.49. - -@anchor{OSPF Link-State LSA Example} -@example -# show ip ospf database router 192.168.0.49 - - OSPF Router with ID (192.168.0.53) - - - Router Link States (Area 0.0.0.0) - - LS age: 38 - Options: 0x2 : *|-|-|-|-|-|E|* - LS Flags: 0x6 - Flags: 0x2 : ASBR - LS Type: router-LSA - Link State ID: 192.168.0.49 - Advertising Router: 192.168.0.49 - LS Seq Number: 80000f90 - Checksum: 0x518b - Length: 60 - Number of Links: 3 - - Link connected to: a Transit Network - (Link ID) Designated Router address: 192.168.1.3 - (Link Data) Router Interface address: 192.168.1.3 - Number of TOS metrics: 0 - TOS 0 Metric: 10 - - Link connected to: a Transit Network - (Link ID) Designated Router address: 192.168.0.49 - (Link Data) Router Interface address: 192.168.0.49 - Number of TOS metrics: 0 - TOS 0 Metric: 10 - - Link connected to: Stub Network - (Link ID) Net: 192.168.3.190 - (Link Data) Network Mask: 255.255.255.255 - Number of TOS metrics: 0 - TOS 0 Metric: 39063 -# show ip ospf database network 192.168.0.49 - - OSPF Router with ID (192.168.0.53) - - - Net Link States (Area 0.0.0.0) - - LS age: 285 - Options: 0x2 : *|-|-|-|-|-|E|* - LS Flags: 0x6 - LS Type: network-LSA - Link State ID: 192.168.0.49 (address of Designated Router) - Advertising Router: 192.168.0.49 - LS Seq Number: 80000074 - Checksum: 0x0103 - Length: 40 - Network Mask: /29 - Attached Router: 192.168.0.49 - Attached Router: 192.168.0.52 - Attached Router: 192.168.0.53 - Attached Router: 192.168.0.54 -@end example - -Note that from one LSA, you can find the other. E.g. Given the -Network-LSA you have a list of Router IDs on that network, from which -you can then look up, in the local @acronym{LSDB}, the matching Router -LSA@. From that Router-LSA you may (potentially) find links to other -Transit networks and Routers IDs which can be used to lookup the -corresponding Router or Network LSA@. And in that fashion, one can find -all the Routers and Networks reachable from that starting @acronym{LSA}@. - -Given the Router LSA instead, you have the IP address of the -@acronym{DR} of any attached transit links. Network LSAs will have that IP -as their LSA ID, so you can then look up that Network LSA and from that -find all the attached routers on that link, leading potentially to more -links and Network and Router LSAs, etc. etc. - -From just the above two @acronym{LSA}s, one can already see the -following partial topology: -@example -@group - - - --------------------- Network: ...... - | Designated Router IP: 192.168.1.3 - | - IP: 192.168.1.3 - (transit link) - (cost: 10) - Router ID: 192.168.0.49(stub)---------- IP: 192.168.3.190/32 - (cost: 10) (cost: 39063) - (transit link) - IP: 192.168.0.49 - | - | ------------------------------- Network: 192.168.0.48/29 - | | | Designated Router IP: 192.168.0.49 - | | | - | | Router ID: 192.168.0.54 - | | - | Router ID: 192.168.0.53 - | -Router ID: 192.168.0.52 -@end group -@end example - -Note the Router IDs, though they look like IP addresses and often are -IP addresses, are not strictly speaking IP addresses, nor need they be -reachable addresses (though, OSPF will calculate routes to Router IDs). - -@subsubsection External LSAs - -External, or "Type 5", @acronym{LSA}s describe routing information which is -entirely external to @acronym{OSPF}, and is "injected" into -@acronym{OSPF}@. Such routing information may have come from another -routing protocol, such as RIP or BGP, they may represent static routes -or they may represent a default route. - -An @acronym{OSPF} router which originates External @acronym{LSA}s is known as an -@acronym{ASBR,AS Boundary Router}. Unlike the link-state @acronym{LSA}s, and -most other @acronym{LSA}s, which are flooded only within the area in -which they originate, External @acronym{LSA}s are flooded through-out -the @acronym{OSPF} network to all areas capable of carrying External -@acronym{LSA}s (@pxref{OSPF Areas}). - -Routes internal to OSPF (intra-area or inter-area) are always preferred -over external routes. - -The External @acronym{LSA} describes the following: - -@itemize @bullet -@item IP Network number - -The IP Network number of the route is described by the @acronym{LSA} ID -field. - -@item IP Network Mask - -The body of the External LSA describes the IP Network Mask of the -route. This, together with the @acronym{LSA} ID, describes the prefix -of the IP route concerned. - -@item Metric - -The cost of the External Route. This cost may be an OSPF cost (also -known as a "Type 1" metric), i.e. equivalent to the normal OSPF costs, -or an externally derived cost ("Type 2" metric) which is not comparable -to OSPF costs and always considered larger than any OSPF cost. Where -there are both Type 1 and 2 External routes for a route, the Type 1 is -always preferred. - -@item Forwarding Address - -The address of the router to forward packets to for the route. This may -be, and usually is, left as 0 to specify that the ASBR originating the -External @acronym{LSA} should be used. There must be an internal OSPF -route to the forwarding address, for the forwarding address to be -useable. - -@item Tag - -An arbitrary 4-bytes of data, not interpreted by OSPF, which may -carry whatever information about the route which OSPF speakers desire. -@end itemize - -@subsubsection AS External LSA Example - -To illustrate, below is an example of an External @acronym{LSA} in the -@acronym{LSDB} of an OSPF router. It describes a route to the IP prefix -of 192.168.165.0/24, originated by the ASBR with Router-ID -192.168.0.49. The metric of 20 is external to OSPF. The forwarding -address is 0, so the route should forward to the originating ASBR if -selected. - -@example -@group -# show ip ospf database external 192.168.165.0 - LS age: 995 - Options: 0x2 : *|-|-|-|-|-|E|* - LS Flags: 0x9 - LS Type: AS-external-LSA - Link State ID: 192.168.165.0 (External Network Number) - Advertising Router: 192.168.0.49 - LS Seq Number: 800001d8 - Checksum: 0xea27 - Length: 36 - Network Mask: /24 - Metric Type: 2 (Larger than any link state path) - TOS: 0 - Metric: 20 - Forward Address: 0.0.0.0 - External Route Tag: 0 -@end group -@end example - -We can add this to our partial topology from above, which now looks -like: -@example -@group - --------------------- Network: ...... - | Designated Router IP: 192.168.1.3 - | - IP: 192.168.1.3 /---- External route: 192.168.165.0/24 - (transit link) / Cost: 20 (External metric) - (cost: 10) / - Router ID: 192.168.0.49(stub)---------- IP: 192.168.3.190/32 - (cost: 10) (cost: 39063) - (transit link) - IP: 192.168.0.49 - | - | ------------------------------- Network: 192.168.0.48/29 - | | | Designated Router IP: 192.168.0.49 - | | | - | | Router ID: 192.168.0.54 - | | - | Router ID: 192.168.0.53 - | -Router ID: 192.168.0.52 -@end group -@end example - -@subsubsection Summary LSAs - -Summary LSAs are created by @acronym{ABR}s to summarise the destinations available within one area to other areas. These LSAs may describe IP networks, potentially in aggregated form, or @acronym{ASBR} routers. - -@anchor{OSPF Flooding} -@subsection OSPF Flooding - -@anchor{OSPF Areas} -@subsection OSPF Areas diff --git a/doc/ospfd.texi b/doc/ospfd.texi deleted file mode 100644 index cc33211510..0000000000 --- a/doc/ospfd.texi +++ /dev/null @@ -1,929 +0,0 @@ - -@cindex OSPFv2 -@node OSPFv2 -@chapter OSPFv2 - -@acronym{OSPF,Open Shortest Path First} version 2 is a routing protocol -which is described in @cite{RFC2328, OSPF Version 2}. OSPF is an -@acronym{IGP,Interior Gateway Protocol}. Compared with @acronym{RIP}, -@acronym{OSPF} can provide scalable network support and faster -convergence times. OSPF is widely used in large networks such as -@acronym{ISP,Internet Service Provider} backbone and enterprise -networks. - -@menu -* OSPF Fundamentals:: -* Configuring ospfd:: -* OSPF router:: -* OSPF area:: -* OSPF interface:: -* Redistribute routes to OSPF:: -* Showing OSPF information:: -* Opaque LSA:: -* OSPF Traffic Engineering:: -* Router Information:: -* Debugging OSPF:: -* OSPF Configuration Examples:: -@end menu - -@include ospf_fundamentals.texi - -@node Configuring ospfd -@section Configuring ospfd - -There are no @command{ospfd} specific options. Common options can be -specified (@pxref{Common Invocation Options}) to @command{ospfd}. -@command{ospfd} needs to acquire interface information from -@command{zebra} in order to function. Therefore @command{zebra} must be -running before invoking @command{ospfd}. Also, if @command{zebra} is -restarted then @command{ospfd} must be too. - -Like other daemons, @command{ospfd} configuration is done in @acronym{OSPF} -specific configuration file @file{ospfd.conf}. - -@node OSPF router -@section OSPF router - -To start OSPF process you have to specify the OSPF router. As of this -writing, @command{ospfd} does not support multiple OSPF processes. - -@deffn Command {router ospf} {} -@deffnx Command {no router ospf} {} -Enable or disable the OSPF process. @command{ospfd} does not yet -support multiple OSPF processes. So you can not specify an OSPF process -number. -@end deffn - -@deffn {OSPF Command} {ospf router-id @var{a.b.c.d}} {} -@deffnx {OSPF Command} {no ospf router-id} {} -@anchor{ospf router-id}This sets the router-ID of the OSPF process. The -router-ID may be an IP address of the router, but need not be - it can -be any arbitrary 32bit number. However it MUST be unique within the -entire OSPF domain to the OSPF speaker - bad things will happen if -multiple OSPF speakers are configured with the same router-ID! If one -is not specified then @command{ospfd} will obtain a router-ID -automatically from @command{zebra}. -@end deffn - -@deffn {OSPF Command} {ospf abr-type @var{type}} {} -@deffnx {OSPF Command} {no ospf abr-type @var{type}} {} -@var{type} can be cisco|ibm|shortcut|standard. The "Cisco" and "IBM" types -are equivalent. - -The OSPF standard for ABR behaviour does not allow an ABR to consider -routes through non-backbone areas when its links to the backbone are -down, even when there are other ABRs in attached non-backbone areas -which still can reach the backbone - this restriction exists primarily -to ensure routing-loops are avoided. - -With the "Cisco" or "IBM" ABR type, the default in this release of -Frr, this restriction is lifted, allowing an ABR to consider -summaries learnt from other ABRs through non-backbone areas, and hence -route via non-backbone areas as a last resort when, and only when, -backbone links are down. - -Note that areas with fully-adjacent virtual-links are considered to be -"transit capable" and can always be used to route backbone traffic, and -hence are unaffected by this setting (@pxref{OSPF virtual-link}). - -More information regarding the behaviour controlled by this command can -be found in @cite{RFC 3509, Alternative Implementations of OSPF Area -Border Routers}, and @cite{draft-ietf-ospf-shortcut-abr-02.txt}. - -Quote: "Though the definition of the @acronym{ABR,Area Border Router} -in the OSPF specification does not require a router with multiple -attached areas to have a backbone connection, it is actually -necessary to provide successful routing to the inter-area and -external destinations. If this requirement is not met, all traffic -destined for the areas not connected to such an ABR or out of the -OSPF domain, is dropped. This document describes alternative ABR -behaviors implemented in Cisco and IBM routers." -@end deffn - -@deffn {OSPF Command} {ospf rfc1583compatibility} {} -@deffnx {OSPF Command} {no ospf rfc1583compatibility} {} -@cite{RFC2328}, the sucessor to @cite{RFC1583}, suggests according -to section G.2 (changes) in section 16.4 a change to the path -preference algorithm that prevents possible routing loops that were -possible in the old version of OSPFv2. More specifically it demands -that inter-area paths and intra-area backbone path are now of equal preference -but still both preferred to external paths. - -This command should NOT be set normally. -@end deffn - -@deffn {OSPF Command} {log-adjacency-changes [detail]} {} -@deffnx {OSPF Command} {no log-adjacency-changes [detail]} {} -Configures ospfd to log changes in adjacency. With the optional -detail argument, all changes in adjacency status are shown. Without detail, -only changes to full or regressions are shown. -@end deffn - -@deffn {OSPF Command} {passive-interface @var{interface}} {} -@deffnx {OSPF Command} {no passive-interface @var{interface}} {} -@anchor{OSPF passive-interface} Do not speak OSPF interface on the -given interface, but do advertise the interface as a stub link in the -router-@acronym{LSA,Link State Advertisement} for this router. This -allows one to advertise addresses on such connected interfaces without -having to originate AS-External/Type-5 LSAs (which have global flooding -scope) - as would occur if connected addresses were redistributed into -OSPF (@pxref{Redistribute routes to OSPF})@. This is the only way to -advertise non-OSPF links into stub areas. -@end deffn - -@deffn {OSPF Command} {timers throttle spf @var{delay} @var{initial-holdtime} @var{max-holdtime}} {} -@deffnx {OSPF Command} {no timers throttle spf} {} -This command sets the initial @var{delay}, the @var{initial-holdtime} -and the @var{maximum-holdtime} between when SPF is calculated and the -event which triggered the calculation. The times are specified in -milliseconds and must be in the range of 0 to 600000 milliseconds. - -The @var{delay} specifies the minimum amount of time to delay SPF -calculation (hence it affects how long SPF calculation is delayed after -an event which occurs outside of the holdtime of any previous SPF -calculation, and also serves as a minimum holdtime). - -Consecutive SPF calculations will always be seperated by at least -'hold-time' milliseconds. The hold-time is adaptive and initially is -set to the @var{initial-holdtime} configured with the above command. -Events which occur within the holdtime of the previous SPF calculation -will cause the holdtime to be increased by @var{initial-holdtime}, bounded -by the @var{maximum-holdtime} configured with this command. If the adaptive -hold-time elapses without any SPF-triggering event occuring then -the current holdtime is reset to the @var{initial-holdtime}. The current -holdtime can be viewed with @ref{show ip ospf}, where it is expressed as -a multiplier of the @var{initial-holdtime}. - -@example -@group -router ospf - timers throttle spf 200 400 10000 -@end group -@end example - -In this example, the @var{delay} is set to 200ms, the @var{initial -holdtime} is set to 400ms and the @var{maximum holdtime} to 10s. Hence -there will always be at least 200ms between an event which requires SPF -calculation and the actual SPF calculation. Further consecutive SPF -calculations will always be seperated by between 400ms to 10s, the -hold-time increasing by 400ms each time an SPF-triggering event occurs -within the hold-time of the previous SPF calculation. - -This command supercedes the @command{timers spf} command in previous Frr -releases. -@end deffn - -@deffn {OSPF Command} {max-metric router-lsa [on-startup|on-shutdown] <5-86400>} {} -@deffnx {OSPF Command} {max-metric router-lsa administrative} {} -@deffnx {OSPF Command} {no max-metric router-lsa [on-startup|on-shutdown|administrative]} {} -This enables @cite{RFC3137, OSPF Stub Router Advertisement} support, -where the OSPF process describes its transit links in its router-LSA as -having infinite distance so that other routers will avoid calculating -transit paths through the router while still being able to reach -networks through the router. - -This support may be enabled administratively (and indefinitely) or -conditionally. Conditional enabling of max-metric router-lsas can be -for a period of seconds after startup and/or for a period of seconds -prior to shutdown. - -Enabling this for a period after startup allows OSPF to converge fully -first without affecting any existing routes used by other routers, -while still allowing any connected stub links and/or redistributed -routes to be reachable. Enabling this for a period of time in advance -of shutdown allows the router to gracefully excuse itself from the OSPF -domain. - -Enabling this feature administratively allows for administrative -intervention for whatever reason, for an indefinite period of time. -Note that if the configuration is written to file, this administrative -form of the stub-router command will also be written to file. If -@command{ospfd} is restarted later, the command will then take effect -until manually deconfigured. - -Configured state of this feature as well as current status, such as the -number of second remaining till on-startup or on-shutdown ends, can be -viewed with the @ref{show ip ospf} command. -@end deffn - -@deffn {OSPF Command} {auto-cost reference-bandwidth <1-4294967>} {} -@deffnx {OSPF Command} {no auto-cost reference-bandwidth} {} -@anchor{OSPF auto-cost reference-bandwidth}This sets the reference -bandwidth for cost calculations, where this bandwidth is considered -equivalent to an OSPF cost of 1, specified in Mbits/s. The default is -100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will have a -cost of 1. Cost of lower bandwidth links will be scaled with reference -to this cost). - -This configuration setting MUST be consistent across all routers within the -OSPF domain. -@end deffn - -@deffn {OSPF Command} {network @var{a.b.c.d/m} area @var{a.b.c.d}} {} -@deffnx {OSPF Command} {network @var{a.b.c.d/m} area @var{<0-4294967295>}} {} -@deffnx {OSPF Command} {no network @var{a.b.c.d/m} area @var{a.b.c.d}} {} -@deffnx {OSPF Command} {no network @var{a.b.c.d/m} area @var{<0-4294967295>}} {} -@anchor{OSPF network command} -This command specifies the OSPF enabled interface(s). If the interface has -an address from range 192.168.1.0/24 then the command below enables ospf -on this interface so router can provide network information to the other -ospf routers via this interface. - -@example -@group -router ospf - network 192.168.1.0/24 area 0.0.0.0 -@end group -@end example - -Prefix length in interface must be equal or bigger (ie. smaller network) than -prefix length in network statement. For example statement above doesn't enable -ospf on interface with address 192.168.1.1/23, but it does on interface with -address 192.168.1.129/25. - -Note that the behavior when there is a peer address -defined on an interface changed after release 0.99.7. -Currently, if a peer prefix has been configured, -then we test whether the prefix in the network command contains -the destination prefix. Otherwise, we test whether the network command prefix -contains the local address prefix of the interface. - -In some cases it may be more convenient to enable OSPF on a per -interface/subnet basis (@pxref{OSPF ip ospf area command}). - -@end deffn - -@node OSPF area -@section OSPF area - -@deffn {OSPF Command} {area @var{a.b.c.d} range @var{a.b.c.d/m}} {} -@deffnx {OSPF Command} {area <0-4294967295> range @var{a.b.c.d/m}} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} range @var{a.b.c.d/m}} {} -@deffnx {OSPF Command} {no area <0-4294967295> range @var{a.b.c.d/m}} {} -Summarize intra area paths from specified area into one Type-3 summary-LSA -announced to other areas. This command can be used only in ABR and ONLY -router-LSAs (Type-1) and network-LSAs (Type-2) (ie. LSAs with scope area) can -be summarized. Type-5 AS-external-LSAs can't be summarized - their scope is AS. -Summarizing Type-7 AS-external-LSAs isn't supported yet by Frr. - -@example -@group -router ospf - network 192.168.1.0/24 area 0.0.0.0 - network 10.0.0.0/8 area 0.0.0.10 - area 0.0.0.10 range 10.0.0.0/8 -@end group -@end example - -With configuration above one Type-3 Summary-LSA with routing info 10.0.0.0/8 is -announced into backbone area if area 0.0.0.10 contains at least one intra-area -network (ie. described with router or network LSA) from this range. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} range IPV4_PREFIX not-advertise} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} range IPV4_PREFIX not-advertise} {} -Instead of summarizing intra area paths filter them - ie. intra area paths from this -range are not advertised into other areas. -This command makes sense in ABR only. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} range IPV4_PREFIX substitute IPV4_PREFIX} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} range IPV4_PREFIX substitute IPV4_PREFIX} {} -Substitute summarized prefix with another prefix. - -@example -@group -router ospf - network 192.168.1.0/24 area 0.0.0.0 - network 10.0.0.0/8 area 0.0.0.10 - area 0.0.0.10 range 10.0.0.0/8 substitute 11.0.0.0/8 -@end group -@end example - -One Type-3 summary-LSA with routing info 11.0.0.0/8 is announced into backbone area if -area 0.0.0.10 contains at least one intra-area network (ie. described with router-LSA or -network-LSA) from range 10.0.0.0/8. -This command makes sense in ABR only. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} virtual-link @var{a.b.c.d}} {} -@deffnx {OSPF Command} {area <0-4294967295> virtual-link @var{a.b.c.d}} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} virtual-link @var{a.b.c.d}} {} -@deffnx {OSPF Command} {no area <0-4294967295> virtual-link @var{a.b.c.d}} {} -@anchor{OSPF virtual-link} -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} shortcut} {} -@deffnx {OSPF Command} {area <0-4294967295> shortcut} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} shortcut} {} -@deffnx {OSPF Command} {no area <0-4294967295> shortcut} {} -Configure the area as Shortcut capable. See @cite{RFC3509}. This requires -that the 'abr-type' be set to 'shortcut'. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} stub} {} -@deffnx {OSPF Command} {area <0-4294967295> stub} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} stub} {} -@deffnx {OSPF Command} {no area <0-4294967295> stub} {} -Configure the area to be a stub area. That is, an area where no router -originates routes external to OSPF and hence an area where all external -routes are via the ABR(s). Hence, ABRs for such an area do not need -to pass AS-External LSAs (type-5s) or ASBR-Summary LSAs (type-4) into the -area. They need only pass Network-Summary (type-3) LSAs into such an area, -along with a default-route summary. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} stub no-summary} {} -@deffnx {OSPF Command} {area <0-4294967295> stub no-summary} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} stub no-summary} {} -@deffnx {OSPF Command} {no area <0-4294967295> stub no-summary} {} -Prevents an @command{ospfd} ABR from injecting inter-area -summaries into the specified stub area. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} default-cost <0-16777215>} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} default-cost <0-16777215>} {} -Set the cost of default-summary LSAs announced to stubby areas. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} export-list NAME} {} -@deffnx {OSPF Command} {area <0-4294967295> export-list NAME} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} export-list NAME} {} -@deffnx {OSPF Command} {no area <0-4294967295> export-list NAME} {} -Filter Type-3 summary-LSAs announced to other areas originated from intra- -area paths from specified area. - -@example -@group -router ospf - network 192.168.1.0/24 area 0.0.0.0 - network 10.0.0.0/8 area 0.0.0.10 - area 0.0.0.10 export-list foo -! -access-list foo permit 10.10.0.0/16 -access-list foo deny any -@end group -@end example - -With example above any intra-area paths from area 0.0.0.10 and from range -10.10.0.0/16 (for example 10.10.1.0/24 and 10.10.2.128/30) are announced into -other areas as Type-3 summary-LSA's, but any others (for example 10.11.0.0/16 -or 10.128.30.16/30) aren't. - -This command is only relevant if the router is an ABR for the specified -area. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} import-list NAME} {} -@deffnx {OSPF Command} {area <0-4294967295> import-list NAME} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} import-list NAME} {} -@deffnx {OSPF Command} {no area <0-4294967295> import-list NAME} {} -Same as export-list, but it applies to paths announced into specified area as -Type-3 summary-LSAs. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} filter-list prefix NAME in} {} -@deffnx {OSPF Command} {area @var{a.b.c.d} filter-list prefix NAME out} {} -@deffnx {OSPF Command} {area <0-4294967295> filter-list prefix NAME in} {} -@deffnx {OSPF Command} {area <0-4294967295> filter-list prefix NAME out} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} filter-list prefix NAME in} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} filter-list prefix NAME out} {} -@deffnx {OSPF Command} {no area <0-4294967295> filter-list prefix NAME in} {} -@deffnx {OSPF Command} {no area <0-4294967295> filter-list prefix NAME out} {} -Filtering Type-3 summary-LSAs to/from area using prefix lists. This command -makes sense in ABR only. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} authentication} {} -@deffnx {OSPF Command} {area <0-4294967295> authentication} {} -@deffnx {OSPF Command} {no area @var{a.b.c.d} authentication} {} -@deffnx {OSPF Command} {no area <0-4294967295> authentication} {} -Specify that simple password authentication should be used for the given -area. -@end deffn - -@deffn {OSPF Command} {area @var{a.b.c.d} authentication message-digest} {} -@deffnx {OSPF Command} {area <0-4294967295> authentication message-digest} {} - -@anchor{area authentication message-digest}Specify that OSPF packets -must be authenticated with MD5 HMACs within the given area. Keying -material must also be configured on a per-interface basis (@pxref{ip -ospf message-digest-key}). - -MD5 authentication may also be configured on a per-interface basis -(@pxref{ip ospf authentication message-digest}). Such per-interface -settings will override any per-area authentication setting. -@end deffn - -@node OSPF interface -@section OSPF interface - -@deffn {Interface Command} {ip ospf area @var{AREA} [@var{ADDR}]} {} -@deffnx {Interface Command} {no ip ospf area [@var{ADDR}]} {} -@anchor{OSPF ip ospf area command} - -Enable OSPF on the interface, optionally restricted to just the IP address -given by @var{ADDR}, putting it in the @var{AREA} area. Per interface area -settings take precedence to network commands (@pxref{OSPF network command}). - -If you have a lot of interfaces, and/or a lot of subnets, then enabling OSPF -via this command may result in a slight performance improvement. - -@end deffn - -@deffn {Interface Command} {ip ospf authentication-key @var{AUTH_KEY}} {} -@deffnx {Interface Command} {no ip ospf authentication-key} {} -Set OSPF authentication key to a simple password. After setting @var{AUTH_KEY}, -all OSPF packets are authenticated. @var{AUTH_KEY} has length up to 8 chars. - -Simple text password authentication is insecure and deprecated in favour of -MD5 HMAC authentication (@pxref{ip ospf authentication message-digest}). -@end deffn - -@deffn {Interface Command} {ip ospf authentication message-digest} {} -@anchor{ip ospf authentication message-digest}Specify that MD5 HMAC -authentication must be used on this interface. MD5 keying material must -also be configured (@pxref{ip ospf message-digest-key}). Overrides any -authentication enabled on a per-area basis (@pxref{area -authentication message-digest}). - -Note that OSPF MD5 authentication requires that time never go backwards -(correct time is NOT important, only that it never goes backwards), even -across resets, if ospfd is to be able to promptly reestabish adjacencies -with its neighbours after restarts/reboots. The host should have system -time be set at boot from an external or non-volatile source (eg battery backed clock, NTP, -etc.) or else the system clock should be periodically saved to non-volative -storage and restored at boot if MD5 authentication is to be expected to work -reliably. -@end deffn - -@deffn {Interface Command} {ip ospf message-digest-key KEYID md5 KEY} {} -@deffnx {Interface Command} {no ip ospf message-digest-key} {} -@anchor{ip ospf message-digest-key}Set OSPF authentication key to a -cryptographic password. The cryptographic algorithm is MD5. - -KEYID identifies secret key used to create the message digest. This ID -is part of the protocol and must be consistent across routers on a -link. - -KEY is the actual message digest key, of up to 16 chars (larger strings -will be truncated), and is associated with the given KEYID. -@end deffn - -@deffn {Interface Command} {ip ospf cost <1-65535>} {} -@deffnx {Interface Command} {no ip ospf cost} {} -Set link cost for the specified interface. The cost value is set to router-LSA's -metric field and used for SPF calculation. -@end deffn - -@deffn {Interface Command} {ip ospf dead-interval <1-65535>} {} -@deffnx {Interface Command} {ip ospf dead-interval minimal hello-multiplier <2-20>} {} -@deffnx {Interface Command} {no ip ospf dead-interval} {} -@anchor{ip ospf dead-interval minimal} Set number of seconds for -RouterDeadInterval timer value used for Wait Timer and Inactivity -Timer. This value must be the same for all routers attached to a -common network. The default value is 40 seconds. - -If 'minimal' is specified instead, then the dead-interval is set to 1 -second and one must specify a hello-multiplier. The hello-multiplier -specifies how many Hellos to send per second, from 2 (every 500ms) to -20 (every 50ms). Thus one can have 1s convergence time for OSPF. If this form -is specified, then the hello-interval advertised in Hello packets is set to -0 and the hello-interval on received Hello packets is not checked, thus -the hello-multiplier need NOT be the same across multiple routers on a common -link. -@end deffn - -@deffn {Interface Command} {ip ospf hello-interval <1-65535>} {} -@deffnx {Interface Command} {no ip ospf hello-interval} {} -Set number of seconds for HelloInterval timer value. Setting this value, -Hello packet will be sent every timer value seconds on the specified interface. -This value must be the same for all routers attached to a common network. -The default value is 10 seconds. - -This command has no effect if @ref{ip ospf dead-interval minimal} is also -specified for the interface. -@end deffn - -@deffn {Interface Command} {ip ospf network (broadcast|non-broadcast|point-to-multipoint|point-to-point)} {} -@deffnx {Interface Command} {no ip ospf network} {} -Set explicitly network type for specifed interface. -@end deffn - -@deffn {Interface Command} {ip ospf priority <0-255>} {} -@deffnx {Interface Command} {no ip ospf priority} {} -Set RouterPriority integer value. The router with the highest priority -will be more eligible to become Designated Router. Setting the value -to 0, makes the router ineligible to become Designated Router. The -default value is 1. -@end deffn - -@deffn {Interface Command} {ip ospf retransmit-interval <1-65535>} {} -@deffnx {Interface Command} {no ip ospf retransmit interval} {} -Set number of seconds for RxmtInterval timer value. This value is used -when retransmitting Database Description and Link State Request packets. -The default value is 5 seconds. -@end deffn - -@deffn {Interface Command} {ip ospf transmit-delay} {} -@deffnx {Interface Command} {no ip ospf transmit-delay} {} -Set number of seconds for InfTransDelay value. LSAs' age should be -incremented by this value when transmitting. -The default value is 1 seconds. -@end deffn - -@deffn {Interface Command} {ip ospf area (A.B.C.D|<0-4294967295>)} {} -@deffnx {Interface Command} {no ip ospf area} {} -Enable ospf on an interface and set associated area. -@end deffn - -@node Redistribute routes to OSPF -@section Redistribute routes to OSPF - -@deffn {OSPF Command} {redistribute (kernel|connected|static|rip|bgp)} {} -@deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) @var{route-map}} {} -@deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2)} {} -@deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) route-map @var{word}} {} -@deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric <0-16777214>} {} -@deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric <0-16777214> route-map @var{word}} {} -@deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214>} {} -@deffnx {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214> route-map @var{word}} {} -@deffnx {OSPF Command} {no redistribute (kernel|connected|static|rip|bgp)} {} -@anchor{OSPF redistribute}Redistribute routes of the specified protocol -or kind into OSPF, with the metric type and metric set if specified, -filtering the routes using the given route-map if specified. -Redistributed routes may also be filtered with distribute-lists, see -@ref{ospf distribute-list}. - -Redistributed routes are distributed as into OSPF as Type-5 External -LSAs into links to areas that accept external routes, Type-7 External LSAs -for NSSA areas and are not redistributed at all into Stub areas, where -external routes are not permitted. - -Note that for connected routes, one may instead use -@dfn{passive-interface}, see @ref{OSPF passive-interface}. -@end deffn - -@deffn {OSPF Command} {default-information originate} {} -@deffnx {OSPF Command} {default-information originate metric <0-16777214>} {} -@deffnx {OSPF Command} {default-information originate metric <0-16777214> metric-type (1|2)} {} -@deffnx {OSPF Command} {default-information originate metric <0-16777214> metric-type (1|2) route-map @var{word}} {} -@deffnx {OSPF Command} {default-information originate always} {} -@deffnx {OSPF Command} {default-information originate always metric <0-16777214>} {} -@deffnx {OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2)} {} -@deffnx {OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2) route-map @var{word}} {} -@deffnx {OSPF Command} {no default-information originate} {} -Originate an AS-External (type-5) LSA describing a default route into -all external-routing capable areas, of the specified metric and metric -type. If the 'always' keyword is given then the default is always -advertised, even when there is no default present in the routing table. -@end deffn - -@deffn {OSPF Command} {distribute-list NAME out (kernel|connected|static|rip|ospf} {} -@deffnx {OSPF Command} {no distribute-list NAME out (kernel|connected|static|rip|ospf} {} -@anchor{ospf distribute-list}Apply the access-list filter, NAME, to -redistributed routes of the given type before allowing the routes to -redistributed into OSPF (@pxref{OSPF redistribute}). -@end deffn - -@deffn {OSPF Command} {default-metric <0-16777214>} {} -@deffnx {OSPF Command} {no default-metric} {} -@end deffn - -@deffn {OSPF Command} {distance <1-255>} {} -@deffnx {OSPF Command} {no distance <1-255>} {} -@end deffn - -@deffn {OSPF Command} {distance ospf (intra-area|inter-area|external) <1-255>} {} -@deffnx {OSPF Command} {no distance ospf} {} -@end deffn - -@deffn {Command} {router zebra} {} -@deffnx {Command} {no router zebra} {} -@end deffn - -@node Showing OSPF information -@section Showing OSPF information - -@deffn {Command} {show ip ospf} {} -@anchor{show ip ospf}Show information on a variety of general OSPF and -area state and configuration information. -@end deffn - -@deffn {Command} {show ip ospf interface [INTERFACE]} {} -Show state and configuration of OSPF the specified interface, or all -interfaces if no interface is given. -@end deffn - -@deffn {Command} {show ip ospf neighbor} {} -@deffnx {Command} {show ip ospf neighbor INTERFACE} {} -@deffnx {Command} {show ip ospf neighbor detail} {} -@deffnx {Command} {show ip ospf neighbor INTERFACE detail} {} -@end deffn - -@deffn {Command} {show ip ospf database} {} -@end deffn - -@deffn {Command} {show ip ospf database (asbr-summary|external|network|router|summary)} {} -@deffnx {Command} {show ip ospf database (asbr-summary|external|network|router|summary) @var{link-state-id}} {} -@deffnx {Command} {show ip ospf database (asbr-summary|external|network|router|summary) @var{link-state-id} adv-router @var{adv-router}} {} -@deffnx {Command} {show ip ospf database (asbr-summary|external|network|router|summary) adv-router @var{adv-router}} {} -@deffnx {Command} {show ip ospf database (asbr-summary|external|network|router|summary) @var{link-state-id} self-originate} {} -@deffnx {Command} {show ip ospf database (asbr-summary|external|network|router|summary) self-originate} {} -@end deffn - -@deffn {Command} {show ip ospf database max-age} {} -@end deffn - -@deffn {Command} {show ip ospf database self-originate} {} -@end deffn - -@deffn {Command} {show ip ospf route} {} -Show the OSPF routing table, as determined by the most recent SPF calculation. -@end deffn - -@node Opaque LSA -@section Opaque LSA - -@deffn {OSPF Command} {ospf opaque-lsa} {} -@deffnx {OSPF Command} {capability opaque} {} -@deffnx {OSPF Command} {no ospf opaque-lsa} {} -@deffnx {OSPF Command} {no capability opaque} {} -@command{ospfd} support Opaque LSA (RFC2370) as fondment for MPLS Traffic Engineering LSA. Prior to used MPLS TE, opaque-lsa must be enable in the configuration file. Alternate command could be "mpls-te on" (@ref{OSPF Traffic Engineering}). -@end deffn - -@deffn {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external)} {} -@deffnx {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) @var{link-state-id}} {} -@deffnx {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) @var{link-state-id} adv-router @var{adv-router}} {} -@deffnx {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) adv-router @var{adv-router}} {} -@deffnx {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) @var{link-state-id} self-originate} {} -@deffnx {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) self-originate} {} -Show Opaque LSA from the database. -@end deffn - -@node OSPF Traffic Engineering -@section Traffic Engineering - -@deffn {OSPF Command} {mpls-te on} {} -@deffnx {OSPF Command} {no mpls-te} {} -Enable Traffic Engineering LSA flooding. -@end deffn - -@deffn {OSPF Command} {mpls-te router-address } {} -@deffnx {OSPF Command} {no mpls-te} {} -Configure stable IP address for MPLS-TE. This IP address is then advertise in Opaque LSA Type-10 TLV=1 (TE) -option 1 (Router-Address). -@end deffn - -@deffn {OSPF Command} {mpls-te inter-as area |as} {} -@deffnx {OSPF Command} {no mpls-te inter-as} {} -Enable RFC5392 suuport - Inter-AS TE v2 - to flood Traffic Engineering parameters of Inter-AS link. -2 modes are supported: AREA and AS; LSA are flood in AREA with Opaque Type-10, -respectively in AS with Opaque Type-11. In all case, Opaque-LSA TLV=6. -@end deffn - -@deffn {Command} {show ip ospf mpls-te interface} {} -@deffnx {Command} {show ip ospf mpls-te interface @var{interface}} {} -Show MPLS Traffic Engineering parameters for all or specified interface. -@end deffn - -@deffn {Command} {show ip ospf mpls-te router} {} -Show Traffic Engineering router parameters. -@end deffn - -@node Router Information -@section Router Information - -@deffn {OSPF Command} {router-info [as | area ]} {} -@deffnx {OSPF Command} {no router-info} {} -Enable Router Information (RFC4970) LSA advertisement with AS scope (default) or Area scope flooding -when area is specified. -@end deffn - -@deffn {OSPF Command} {pce address } {} -@deffnx {OSPF Command} {no pce address} {} -@deffnx {OSPF Command} {pce domain as <0-65535>} {} -@deffnx {OSPF Command} {no pce domain as <0-65535>} {} -@deffnx {OSPF Command} {pce neighbor as <0-65535>} {} -@deffnx {OSPF Command} {no pce neighbor as <0-65535>} {} -@deffnx {OSPF Command} {pce flag BITPATTERN} {} -@deffnx {OSPF Command} {no pce flag} {} -@deffnx {OSPF Command} {pce scope BITPATTERN} {} -@deffnx {OSPF Command} {no pce scope} {} -The commands are conform to RFC 5088 and allow OSPF router announce Path Compuatation Elemenent (PCE) capabilities -through the Router Information (RI) LSA. Router Information must be enable prior to this. The command set/unset -respectively the PCE IP adress, Autonomous System (AS) numbers of controlled domains, neighbor ASs, flag and scope. -For flag and scope, please refer to RFC5088 for the BITPATTERN recognition. Multiple 'pce neighbor' command could -be specified in order to specify all PCE neighbours. -@end deffn - -@deffn {Command} {show ip ospf router-info} {} -Show Router Capabilities flag. -@end deffn -@deffn {Command} {show ip ospf router-info pce} {} -Show Router Capabilities PCE parameters. -@end deffn - -@node Debugging OSPF -@section Debugging OSPF - -@deffn {Command} {debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all) (send|recv) [detail]} {} -@deffnx {Command} {no debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all) (send|recv) [detail]} {} -Dump Packet for debugging -@end deffn - -@deffn {Command} {debug ospf ism} {} -@deffnx {Command} {debug ospf ism (status|events|timers)} {} -@deffnx {Command} {no debug ospf ism} {} -@deffnx {Command} {no debug ospf ism (status|events|timers)} {} -Show debug information of Interface State Machine -@end deffn - -@deffn {Command} {debug ospf nsm} {} -@deffnx {Command} {debug ospf nsm (status|events|timers)} {} -@deffnx {Command} {no debug ospf nsm} {} -@deffnx {Command} {no debug ospf nsm (status|events|timers)} {} -Show debug information of Network State Machine -@end deffn - -@deffn {Command} {debug ospf event} {} -@deffnx {Command} {no debug ospf event} {} -Show debug information of OSPF event -@end deffn - -@deffn {Command} {debug ospf nssa} {} -@deffnx {Command} {no debug ospf nssa} {} -Show debug information about Not So Stub Area -@end deffn - -@deffn {Command} {debug ospf lsa} {} -@deffnx {Command} {debug ospf lsa (generate|flooding|refresh)} {} -@deffnx {Command} {no debug ospf lsa} {} -@deffnx {Command} {no debug ospf lsa (generate|flooding|refresh)} {} -Show debug detail of Link State messages -@end deffn - -@deffn {Command} {debug ospf te} {} -@deffnx {Command} {no debug ospf te} {} -Show debug information about Traffic Engineering LSA -@end deffn - -@deffn {Command} {debug ospf zebra} {} -@deffnx {Command} {debug ospf zebra (interface|redistribute)} {} -@deffnx {Command} {no debug ospf zebra} {} -@deffnx {Command} {no debug ospf zebra (interface|redistribute)} {} -Show debug information of ZEBRA API -@end deffn - -@deffn {Command} {show debugging ospf} {} -@end deffn - -@node OSPF Configuration Examples -@section OSPF Configuration Examples -A simple example, with MD5 authentication enabled: - -@example -@group -! -interface bge0 - ip ospf authentication message-digest - ip ospf message-digest-key 1 md5 ABCDEFGHIJK -! -router ospf - network 192.168.0.0/16 area 0.0.0.1 - area 0.0.0.1 authentication message-digest -@end group -@end example - -An @acronym{ABR} router, with MD5 authentication and performing summarisation -of networks between the areas: - -@example -@group -! -password ABCDEF -log file /var/log/frr/ospfd.log -service advanced-vty -! -interface eth0 - ip ospf authentication message-digest - ip ospf message-digest-key 1 md5 ABCDEFGHIJK -! -interface ppp0 -! -interface br0 - ip ospf authentication message-digest - ip ospf message-digest-key 2 md5 XYZ12345 -! -router ospf - ospf router-id 192.168.0.1 - redistribute connected - passive interface ppp0 - network 192.168.0.0/24 area 0.0.0.0 - network 10.0.0.0/16 area 0.0.0.0 - network 192.168.1.0/24 area 0.0.0.1 - area 0.0.0.0 authentication message-digest - area 0.0.0.0 range 10.0.0.0/16 - area 0.0.0.0 range 192.168.0.0/24 - area 0.0.0.1 authentication message-digest - area 0.0.0.1 range 10.2.0.0/16 -! -@end group -@end example - -A Traffic Engineering configuration, with Inter-ASv2 support. - - - First, the 'zebra.conf' part: - -@example -@group -hostname HOSTNAME -password PASSWORD -log file /var/log/zebra.log -! -interface eth0 - ip address 198.168.1.1/24 - mpls-te on - mpls-te link metric 10 - mpls-te link max-bw 1.25e+06 - mpls-te link max-rsv-bw 1.25e+06 - mpls-te link unrsv-bw 0 1.25e+06 - mpls-te link unrsv-bw 1 1.25e+06 - mpls-te link unrsv-bw 2 1.25e+06 - mpls-te link unrsv-bw 3 1.25e+06 - mpls-te link unrsv-bw 4 1.25e+06 - mpls-te link unrsv-bw 5 1.25e+06 - mpls-te link unrsv-bw 6 1.25e+06 - mpls-te link unrsv-bw 7 1.25e+06 - mpls-te link rsc-clsclr 0xab -! -interface eth1 - ip address 192.168.2.1/24 - mpls-te on - mpls-te link metric 10 - mpls-te link max-bw 1.25e+06 - mpls-te link max-rsv-bw 1.25e+06 - mpls-te link unrsv-bw 0 1.25e+06 - mpls-te link unrsv-bw 1 1.25e+06 - mpls-te link unrsv-bw 2 1.25e+06 - mpls-te link unrsv-bw 3 1.25e+06 - mpls-te link unrsv-bw 4 1.25e+06 - mpls-te link unrsv-bw 5 1.25e+06 - mpls-te link unrsv-bw 6 1.25e+06 - mpls-te link unrsv-bw 7 1.25e+06 - mpls-te link rsc-clsclr 0xab - mpls-te neighbor 192.168.2.2 as 65000 -@end group -@end example - - - Then the 'ospfd.conf' itself: - -@example -@group -hostname HOSTNAME -password PASSWORD -log file /var/log/ospfd.log -! -! -interface eth0 - ip ospf hello-interval 60 - ip ospf dead-interval 240 -! -interface eth1 - ip ospf hello-interval 60 - ip ospf dead-interval 240 -! -! -router ospf - ospf router-id 192.168.1.1 - network 192.168.0.0/16 area 1 - ospf opaque-lsa - mpls-te - mpls-te router-address 192.168.1.1 - mpls-te inter-as area 1 -! -line vty -@end group -@end example - -A router information example with PCE advsertisement: - -@example -@group -! -router ospf - ospf router-id 192.168.1.1 - network 192.168.0.0/16 area 1 - capability opaque - mpls-te - mpls-te router-address 192.168.1.1 - router-info area 0.0.0.1 - pce address 192.168.1.1 - pce flag 0x80 - pce domain as 65400 - pce neighbor as 65500 - pce neighbor as 65200 - pce scope 0x80 -! -@end group -@end example diff --git a/doc/overview.texi b/doc/overview.texi deleted file mode 100644 index c988e219b7..0000000000 --- a/doc/overview.texi +++ /dev/null @@ -1,337 +0,0 @@ -@node Overview -@chapter Overview -@cindex Overview - - @uref{@value{PACKAGE_URL},,Frr} is a routing software package that -provides TCP/IP based routing services with routing protocols support such -as RIPv1, RIPv2, RIPng, OSPFv2, OSPFv3, IS-IS, BGP-4, and BGP-4+ (@pxref{Supported -RFCs}). Frr also supports special BGP Route Reflector and Route Server -behavior. In addition to traditional IPv4 routing protocols, Frr also -supports IPv6 routing protocols. With SNMP daemon which supports SMUX and AgentX -protocol, Frr provides routing protocol MIBs (@pxref{SNMP Support}). - - Frr uses an advanced software architecture to provide you with a high -quality, multi server routing engine. Frr has an interactive user -interface for each routing protocol and supports common client commands. -Due to this design, you can add new protocol daemons to Frr easily. You -can use Frr library as your program's client user interface. - - Frr is distributed under the @sc{gnu} General Public License. - -@menu -* About Frr:: Basic information about Frr -* System Architecture:: The Frr system architecture -* Supported Platforms:: Supported platforms and future plans -* Supported RFCs:: Supported RFCs -* How to get Frr:: -* Mailing List:: Mailing list information -* Bug Reports:: Mail address for bug data -@end menu - -@node About Frr -@comment node-name, next, previous, up -@section About Frr -@cindex About Frr - - Today, TCP/IP networks are covering all of the world. The Internet has -been deployed in many countries, companies, and to the home. When you -connect to the Internet your packet will pass many routers which have TCP/IP -routing functionality. - - A system with Frr installed acts as a dedicated router. With Frr, -your machine exchanges routing information with other routers using routing -protocols. Frr uses this information to update the kernel routing table -so that the right data goes to the right place. You can dynamically change -the configuration and you may view routing table information from the Frr -terminal interface. - - Adding to routing protocol support, Frr can setup interface's flags, -interface's address, static routes and so on. If you have a small network, -or a stub network, or xDSL connection, configuring the Frr routing -software is very easy. The only thing you have to do is to set up the -interfaces and put a few commands about static routes and/or default routes. -If the network is rather large, or if the network structure changes -frequently, you will want to take advantage of Frr's dynamic routing -protocol support for protocols such as RIP, OSPF, IS-IS or BGP. - - Traditionally, UNIX based router configuration is done by -@command{ifconfig} and @command{route} commands. Status of routing -table is displayed by @command{netstat} utility. Almost of these commands -work only if the user has root privileges. Frr has a different system -administration method. There are two user modes in Frr. One is normal -mode, the other is enable mode. Normal mode user can only view system -status, enable mode user can change system configuration. This UNIX account -independent feature will be great help to the router administrator. - - Currently, Frr supports common unicast routing protocols, that is BGP, -OSPF, RIP and IS-IS. Upcoming for MPLS support, an implementation of LDP is -currently being prepared for merging. Implementations of BFD and PIM-SSM -(IPv4) also exist, but are not actively being worked on. - - The ultimate goal of the Frr project is making a productive, quality, free -TCP/IP routing software package. - -@node System Architecture -@comment node-name, next, previous, up -@section System Architecture -@cindex System architecture -@cindex Software architecture -@cindex Software internals - - Traditional routing software is made as a one process program which -provides all of the routing protocol functionalities. Frr takes a -different approach. It is made from a collection of several daemons that -work together to build the routing table. There may be several -protocol-specific routing daemons and zebra the kernel routing manager. - - The @command{ripd} daemon handles the RIP protocol, while -@command{ospfd} is a daemon which supports OSPF version 2. -@command{bgpd} supports the BGP-4 protocol. For changing the kernel -routing table and for redistribution of routes between different routing -protocols, there is a kernel routing table manager @command{zebra} daemon. -It is easy to add a new routing protocol daemons to the entire routing -system without affecting any other software. You need to run only the -protocol daemon associated with routing protocols in use. Thus, user may -run a specific daemon and send routing reports to a central routing console. - - There is no need for these daemons to be running on the same machine. You -can even run several same protocol daemons on the same machine. This -architecture creates new possibilities for the routing system. - -@example -@group -+----+ +----+ +-----+ +-----+ -|bgpd| |ripd| |ospfd| |zebra| -+----+ +----+ +-----+ +-----+ - | -+---------------------------|--+ -| v | -| UNIX Kernel routing table | -| | -+------------------------------+ - - Frr System Architecture -@end group -@end example - -Multi-process architecture brings extensibility, modularity and -maintainability. At the same time it also brings many configuration files -and terminal interfaces. Each daemon has it's own configuration file and -terminal interface. When you configure a static route, it must be done in -@command{zebra} configuration file. When you configure BGP network it must -be done in @command{bgpd} configuration file. This can be a very annoying -thing. To resolve the problem, Frr provides integrated user interface -shell called @command{vtysh}. @command{vtysh} connects to each daemon with -UNIX domain socket and then works as a proxy for user input. - -Frr was planned to use multi-threaded mechanism when it runs with a -kernel that supports multi-threads. But at the moment, the thread library -which comes with @sc{gnu}/Linux or FreeBSD has some problems with running -reliable services such as routing software, so we don't use threads at all. -Instead we use the @command{select(2)} system call for multiplexing the -events. - -@node Supported Platforms -@comment node-name, next, previous, up -@section Supported Platforms - -@cindex Supported platforms -@cindex Frr on other systems -@cindex Compatibility with other systems -@cindex Operating systems that support Frr - -Currently Frr supports @sc{gnu}/Linux and BSD. Porting Frr -to other platforms is not too difficult as platform dependent code should -most be limited to the @command{zebra} daemon. Protocol daemons are mostly -platform independent. Please let us know when you find out Frr runs on a -platform which is not listed below. - -The list of officially supported platforms are listed below. Note that -Frr may run correctly on other platforms, and may run with partial -functionality on further platforms. - -@sp 1 -@itemize @bullet -@item -@sc{gnu}/Linux -@item -FreeBSD -@item -NetBSD -@item -OpenBSD -@end itemize - -Versions of these platforms that are older than around 2 years from the point -of their original release (in case of @sc{gnu}/Linux, this is since the kernel's -release on kernel.org) may need some work. Similarly, the following platforms -may work with some effort: - -@sp 1 -@itemize @bullet -@item -Solaris -@item -Mac OSX -@end itemize - -Also note that, in particular regarding proprietary platforms, compiler -and C library choice will affect Frr. Only recent versions of the -following C compilers are well-tested: - -@sp 1 -@itemize @bullet -@item -@sc{gnu}'s GCC -@item -LLVM's clang -@item -Intel's ICC -@end itemize - -@node Supported RFCs -@comment node-name, next, previous, up -@section Supported RFCs - - Below is the list of currently supported RFC's. - -@table @asis -@item @asis{RFC1058} -@cite{Routing Information Protocol. C.L. Hedrick. Jun-01-1988.} - -@item @asis{RF2082} -@cite{RIP-2 MD5 Authentication. F. Baker, R. Atkinson. January 1997.} - -@item @asis{RFC2453} -@cite{RIP Version 2. G. Malkin. November 1998.} - -@item @asis{RFC2080} -@cite{RIPng for IPv6. G. Malkin, R. Minnear. January 1997.} - -@item @asis{RFC2328} -@cite{OSPF Version 2. J. Moy. April 1998.} - -@item @asis{RFC2370} -@cite{The OSPF Opaque LSA Option R. Coltun. July 1998.} - -@item @asis{RFC3101} -@cite{The OSPF Not-So-Stubby Area (NSSA) Option P. Murphy. January 2003.} - -@item @asis{RFC2740} -@cite{OSPF for IPv6. R. Coltun, D. Ferguson, J. Moy. December 1999.} - -@item @asis{RFC1771} -@cite{A Border Gateway Protocol 4 (BGP-4). Y. Rekhter & T. Li. March 1995.} - -@item @asis{RFC1965} -@cite{Autonomous System Confederations for BGP. P. Traina. June 1996.} - -@item @asis{RFC1997} -@cite{BGP Communities Attribute. R. Chandra, P. Traina & T. Li. August 1996.} - -@item @asis{RFC2545} -@cite{Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing. P. Marques, F. Dupont. March 1999.} - -@item @asis{RFC2796} -@cite{BGP Route Reflection An alternative to full mesh IBGP. T. Bates & R. Chandrasekeran. June 1996.} - -@item @asis{RFC2858} -@cite{Multiprotocol Extensions for BGP-4. T. Bates, Y. Rekhter, R. Chandra, D. Katz. June 2000.} - -@item @asis{RFC2842} -@cite{Capabilities Advertisement with BGP-4. R. Chandra, J. Scudder. May 2000.} - -@item @asis{RFC3137} -@cite{OSPF Stub Router Advertisement, A. Retana, L. Nguyen, R. White, A. Zinin, D. McPherson. June 2001} -@end table - - When SNMP support is enabled, below RFC is also supported. - -@table @asis - -@item @asis{RFC1227} -@cite{SNMP MUX protocol and MIB. M.T. Rose. May-01-1991.} - -@item @asis{RFC1657} -@cite{Definitions of Managed Objects for the Fourth Version of the -Border Gateway Protocol (BGP-4) using SMIv2. S. Willis, J. Burruss, -J. Chu, Editor. July 1994.} - -@item @asis{RFC1724} -@cite{RIP Version 2 MIB Extension. G. Malkin & F. Baker. November 1994.} - -@item @asis{RFC1850} -@cite{OSPF Version 2 Management Information Base. F. Baker, R. Coltun. -November 1995.} - -@item @asis{RFC2741} -@cite{Agent Extensibility (AgentX) Protocol. M. Daniele, B. Wijnen. January 2000.} - -@end table - -@node How to get Frr -@comment node-name, next, previous, up -@section How to get Frr - -The official Frr web-site is located at: - -@uref{@value{PACKAGE_URL}} - -and contains further information, as well as links to additional -resources. - -@uref{@value{PACKAGE_URL},Frr} is a fork of Quagga, whose -web-site is located at: - -@uref{http://www.quagga.net/}. - -@node Mailing List -@comment node-name, next, previous, up -@section Mailing List -@cindex How to get in touch with Frr -@cindex Mailing Frr -@cindex Contact information -@cindex Mailing lists - -There is a mailing list for discussions about Frr. If you have any -comments or suggestions to Frr, please subscribe to: - -@uref{https://lists.frrouting.org/listinfo/frog}. - -The @uref{@value{PACKAGE_URL},,Frr} site has further information on -the available mailing lists, see: - - @uref{https://lists.frrouting.org/} - -@node Bug Reports -@section Bug Reports - -@cindex Bug Reports -@cindex Bug hunting -@cindex Found a bug? -@cindex Reporting bugs -@cindex Reporting software errors -@cindex Errors in the software - -If you think you have found a bug, please send a bug report to: - -@uref{http://github.com/frrouting/frr/issues} - -When you send a bug report, please be careful about the points below. - -@itemize @bullet -@item -Please note what kind of OS you are using. If you use the IPv6 stack -please note that as well. -@item -Please show us the results of @code{netstat -rn} and @code{ifconfig -a}. -Information from zebra's VTY command @code{show ip route} will also be -helpful. -@item -Please send your configuration file with the report. If you specify -arguments to the configure script please note that too. -@end itemize - - Bug reports are very important for us to improve the quality of Frr. -Frr is still in the development stage, but please don't hesitate to -send a bug report to @uref{http://github.com/frrouting/frr/issues}. diff --git a/doc/protocol.texi b/doc/protocol.texi deleted file mode 100644 index 7e8a96dc5d..0000000000 --- a/doc/protocol.texi +++ /dev/null @@ -1,115 +0,0 @@ -@node Zebra Protocol -@appendix Zebra Protocol -@appendixsection Overview of the Zebra Protocol - -Zebra Protocol is used by protocol daemons to communicate with the -zebra daemon. - -Each protocol daemon may request and send information to and from the -zebra daemon such as interface states, routing state, -nexthop-validation, and so on. Protocol daemons may also install routes -with zebra. The zebra daemon manages which route is installed into the -forwarding table with the kernel. - -Zebra Protocol is a streaming protocol, with a common header. Two -versions of the header are in use. Version 0 is implicitely versioned. -Version 1 has an explicit version field. Version 0 can be distinguished -from all other versions by examining the 3rd byte of the header, which -contains a marker value for all versions bar version 0. The marker byte -corresponds to the command field in version 0, and the marker value is -a reserved command in version 0. - -We do not anticipate there will be further versions of the header for -the foreseeable future, as the command field in version 1 is wide -enough to allow for future extensions to done compatibly through -seperate commands. - -Version 0 is used by all versions of GNU Zebra as of this writing, and -versions of Quagga up to and including Quagga 0.98. Version 2 was created -for 0.99.21 of Quagga. Version 3 designates VRF compatibility and was -released in 1.0. Version 4 will be used as of Frr 2.0 to indicate that -we are a different Routing Suite now and to hopefully prevent accidental -Quagga <-> FRR issues. - -@appendixsection Zebra Protocol Definition -@appendixsubsec Zebra Protocol Header (version 0) -@example -@group -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-------------------------------+---------------+ -| Length (2) | Command (1) | -+-------------------------------+---------------+ -@end group -@end example - -@appendixsubsec Zebra Protocol Common Header (version 1) -@example -@group -0 1 2 3 -0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+-------------------------------+---------------+-------------+ -| Length (2) | Marker (1) | Version (1) | -+-------------------------------+---------------+-------------+ -| Command (2) | -+-------------------------------+ -@end group -@end example - -@appendixsubsec Zebra Protocol Header Field Definitions -@table @samp -@item Length -Total packet length including this header. The minimum length is 3 -bytes for version 0 messages and 6 bytes for version 1 messages. - -@item Marker -Static marker with a value of 255 always. This is to allow version 0 -Zserv headers (which do not include version explicitely) to be -distinguished from versioned headers. Not present in version 0 -messages. - -@item Version -Version number of the Zserv message. Clients should not continue -processing messages past the version field for versions they do not -recognise. Not present in version 0 messages. - -@item Command -The Zebra Protocol command. -@end table - -@appendixsubsec Zebra Protocol Commands -@multitable {ZEBRA_REDISTRIBUTE_DEFAULT_DELETE_WHATEVER} {99999} -@headitem Command @tab Value -@item ZEBRA_INTERFACE_ADD -@tab 1 -@item ZEBRA_INTERFACE_DELETE -@tab 2 -@item ZEBRA_INTERFACE_ADDRESS_ADD -@tab 3 -@item ZEBRA_INTERFACE_ADDRESS_DELETE -@tab 4 -@item ZEBRA_INTERFACE_UP -@tab 5 -@item ZEBRA_INTERFACE_DOWN -@tab 6 -@item ZEBRA_IPV4_ROUTE_ADD -@tab 7 -@item ZEBRA_IPV4_ROUTE_DELETE -@tab 8 -@item ZEBRA_IPV6_ROUTE_ADD -@tab 9 -@item ZEBRA_IPV6_ROUTE_DELETE -@tab 10 -@item ZEBRA_REDISTRIBUTE_ADD -@tab 11 -@item ZEBRA_REDISTRIBUTE_DELETE -@tab 12 -@item ZEBRA_REDISTRIBUTE_DEFAULT_ADD -@tab 13 -@item ZEBRA_REDISTRIBUTE_DEFAULT_DELETE -@tab 14 -@item ZEBRA_IPV4_NEXTHOP_LOOKUP -@tab 15 -@item ZEBRA_IPV6_NEXTHOP_LOOKUP -@tab 16 -@end multitable diff --git a/doc/ripd.texi b/doc/ripd.texi deleted file mode 100644 index da0f596afd..0000000000 --- a/doc/ripd.texi +++ /dev/null @@ -1,623 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the Frr Manual. -@c @value{COPYRIGHT_STR} -@c See file frr.texi for copying conditions. -@node RIP -@chapter RIP - -RIP -- Routing Information Protocol is widely deployed interior gateway -protocol. RIP was developed in the 1970s at Xerox Labs as part of the -XNS routing protocol. RIP is a @dfn{distance-vector} protocol and is -based on the @dfn{Bellman-Ford} algorithms. As a distance-vector -protocol, RIP router send updates to its neighbors periodically, thus -allowing the convergence to a known topology. In each update, the -distance to any given network will be broadcasted to its neighboring -router. - -@command{ripd} supports RIP version 2 as described in RFC2453 and RIP -version 1 as described in RFC1058. - -@menu -* Starting and Stopping ripd:: -* RIP Configuration:: -* RIP Version Control:: -* How to Announce RIP route:: -* Filtering RIP Routes:: -* RIP Metric Manipulation:: -* RIP distance:: -* RIP route-map:: -* RIP Authentication:: -* RIP Timers:: -* Show RIP Information:: -* RIP Debug Commands:: -@end menu - -@node Starting and Stopping ripd -@section Starting and Stopping ripd - -The default configuration file name of @command{ripd}'s is -@file{ripd.conf}. When invocation @command{ripd} searches directory -@value{INSTALL_PREFIX_ETC}. If @file{ripd.conf} is not there next -search current directory. - -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 @command{zebra} daemon. So running @command{zebra} -is mandatory to run @command{ripd}. Thus minimum sequence for running -RIP is like below: - -@example -@group -# zebra -d -# ripd -d -@end group -@end example - -Please note that @command{zebra} must be invoked before @command{ripd}. - -To stop @command{ripd}. Please use @command{kill `cat -/var/run/ripd.pid`}. Certain signals have special meaningss to @command{ripd}. - -@table @samp -@item SIGHUP -Reload configuration file @file{ripd.conf}. All configurations are -reseted. All routes learned so far are cleared and removed from routing -table. -@item SIGUSR1 -Rotate @command{ripd} logfile. -@item SIGINT -@itemx SIGTERM -@command{ripd} sweeps all installed RIP routes then terminates properly. -@end table - -@command{ripd} invocation options. Common options that can be specified -(@pxref{Common Invocation Options}). - -@table @samp -@item -r -@itemx --retain -When the program terminates, retain routes added by @command{ripd}. -@end table - -@menu -* RIP netmask:: -@end menu - -@node RIP netmask -@subsection RIP netmask - -The netmask features of @command{ripd} support both version 1 and version 2 of -RIP. Version 1 of RIP originally contained no netmask information. In -RIP version 1, network classes were originally used to determine the -size of the netmask. Class A networks use 8 bits of mask, Class B -networks use 16 bits of masks, while Class C networks use 24 bits of -mask. Today, the most widely used method of a network mask is assigned -to the packet on the basis of the interface that received the packet. -Version 2 of RIP supports a variable length subnet mask (VLSM). By -extending the subnet mask, the mask can be divided and reused. Each -subnet can be used for different purposes such as large to middle size -LANs and WAN links. Frr @command{ripd} does not support the non-sequential -netmasks that are included in RIP Version 2. - -In a case of similar information with the same prefix and metric, the -old information will be suppressed. Ripd does not currently support -equal cost multipath routing. - - -@node RIP Configuration -@section RIP Configuration - -@deffn Command {router rip} {} -The @code{router rip} command is necessary to enable RIP. To disable -RIP, use the @code{no router rip} command. RIP must be enabled before -carrying out any of the RIP commands. -@end deffn - -@deffn Command {no router rip} {} -Disable RIP. -@end deffn - -@deffn {RIP Command} {network @var{network}} {} -@deffnx {RIP Command} {no network @var{network}} {} -Set the RIP enable interface by @var{network}. The interfaces which -have addresses matching with @var{network} are enabled. - -This group of commands either enables or disables RIP interfaces between -certain numbers of a specified network address. For example, if the -network for 10.0.0.0/24 is RIP enabled, this would result in all the -addresses from 10.0.0.0 to 10.0.0.255 being enabled for RIP. The @code{no -network} command will disable RIP for the specified network. -@end deffn - -@deffn {RIP Command} {network @var{ifname}} {} -@deffnx {RIP Command} {no network @var{ifname}} {} -Set a RIP enabled interface by @var{ifname}. Both the sending and -receiving of RIP packets will be enabled on the port specified in the -@code{network ifname} command. The @code{no network ifname} command will disable -RIP on the specified interface. -@end deffn - -@deffn {RIP Command} {neighbor @var{a.b.c.d}} {} -@deffnx {RIP Command} {no neighbor @var{a.b.c.d}} {} -Specify RIP neighbor. When a neighbor doesn't understand multicast, -this command is used to specify neighbors. In some cases, not all -routers will be able to understand multicasting, where packets are sent -to a network or a group of addresses. In a situation where a neighbor -cannot process multicast packets, it is necessary to establish a direct -link between routers. The neighbor command allows the network -administrator to specify a router as a RIP neighbor. The @code{no -neighbor a.b.c.d} command will disable the RIP neighbor. -@end deffn - -Below is very simple RIP configuration. Interface @code{eth0} and -interface which address match to @code{10.0.0.0/8} are RIP enabled. - -@example -@group -! -router rip - network 10.0.0.0/8 - network eth0 -! -@end group -@end example - -Passive interface - -@deffn {RIP command} {passive-interface (@var{IFNAME}|default)} {} -@deffnx {RIP command} {no passive-interface @var{IFNAME}} {} -This command sets the specified interface to passive mode. On passive mode -interface, all receiving packets are processed as normal and ripd does -not send either multicast or unicast RIP packets except to RIP neighbors -specified with @code{neighbor} command. The interface may be specified -as @var{default} to make ripd default to passive on all interfaces. - -The default is to be passive on all interfaces. -@end deffn - -RIP split-horizon - -@deffn {Interface command} {ip split-horizon} {} -@deffnx {Interface command} {no ip split-horizon} {} -Control split-horizon on the interface. Default is @code{ip -split-horizon}. If you don't perform split-horizon on the interface, -please specify @code{no ip split-horizon}. -@end deffn - -@node RIP Version Control -@section RIP Version Control - -RIP can be configured to send either Version 1 or Version 2 packets. -The default is to send RIPv2 while accepting both RIPv1 and RIPv2 (and -replying with packets of the appropriate version for REQUESTS / -triggered updates). The version to receive and send can be specified -globally, and further overriden on a per-interface basis if needs be -for send and receive seperately (see below). - -It is important to note that RIPv1 can not be authenticated. Further, -if RIPv1 is enabled then RIP will reply to REQUEST packets, sending the -state of its RIP routing table to any remote routers that ask on -demand. For a more detailed discussion on the security implications of -RIPv1 see @ref{RIP Authentication}. - -@deffn {RIP Command} {version @var{version}} {} -Set RIP version to accept for reads and send. @var{version} -can be either `1'' or `2''. - -Disabling RIPv1 by specifying version 2 is STRONGLY encouraged, -@xref{RIP Authentication}. This may become the default in a future -release. - -Default: Send Version 2, and accept either version. -@end deffn - -@deffn {RIP Command} {no version} {} -Reset the global version setting back to the default. -@end deffn - -@deffn {Interface command} {ip rip send version @var{version}} {} -@var{version} can be `1', `2' or `1 2'. - -This interface command overrides the global rip version setting, and -selects which version of RIP to send packets with, for this interface -specifically. Choice of RIP Version 1, RIP Version 2, or both versions. -In the latter case, where `1 2' is specified, packets will be both -broadcast and multicast. - -Default: Send packets according to the global version (version 2) -@end deffn - -@deffn {Interface command} {ip rip receive version @var{version}} {} -@var{version} can be `1', `2' or `1 2'. - -This interface command overrides the global rip version setting, and -selects which versions of RIP packets will be accepted on this -interface. Choice of RIP Version 1, RIP Version 2, or both. - -Default: Accept packets according to the global setting (both 1 and 2). -@end deffn - -@node How to Announce RIP route -@section How to Announce RIP route - -@deffn {RIP command} {redistribute kernel} {} -@deffnx {RIP command} {redistribute kernel metric <0-16>} {} -@deffnx {RIP command} {redistribute kernel route-map @var{route-map}} {} -@deffnx {RIP command} {no redistribute kernel} {} -@code{redistribute kernel} redistributes routing information from -kernel route entries into the RIP tables. @code{no redistribute kernel} -disables the routes. -@end deffn - -@deffn {RIP command} {redistribute static} {} -@deffnx {RIP command} {redistribute static metric <0-16>} {} -@deffnx {RIP command} {redistribute static route-map @var{route-map}} {} -@deffnx {RIP command} {no redistribute static} {} -@code{redistribute static} redistributes routing information from -static route entries into the RIP tables. @code{no redistribute static} -disables the routes. -@end deffn - -@deffn {RIP command} {redistribute connected} {} -@deffnx {RIP command} {redistribute connected metric <0-16>} {} -@deffnx {RIP command} {redistribute connected route-map @var{route-map}} {} -@deffnx {RIP command} {no redistribute connected} {} -Redistribute connected routes into the RIP tables. @code{no -redistribute connected} disables the connected routes in the RIP tables. -This command redistribute connected of the interface which RIP disabled. -The connected route on RIP enabled interface is announced by default. -@end deffn - -@deffn {RIP command} {redistribute ospf} {} -@deffnx {RIP command} {redistribute ospf metric <0-16>} {} -@deffnx {RIP command} {redistribute ospf route-map @var{route-map}} {} -@deffnx {RIP command} {no redistribute ospf} {} -@code{redistribute ospf} redistributes routing information from -ospf route entries into the RIP tables. @code{no redistribute ospf} -disables the routes. -@end deffn - -@deffn {RIP command} {redistribute bgp} {} -@deffnx {RIP command} {redistribute bgp metric <0-16>} {} -@deffnx {RIP command} {redistribute bgp route-map @var{route-map}} {} -@deffnx {RIP command} {no redistribute bgp} {} -@code{redistribute bgp} redistributes routing information from -bgp route entries into the RIP tables. @code{no redistribute bgp} -disables the routes. -@end deffn - -If you want to specify RIP only static routes: - -@deffn {RIP command} {default-information originate} {} -@end deffn - -@deffn {RIP command} {route @var{a.b.c.d/m}} {} -@deffnx {RIP command} {no route @var{a.b.c.d/m}} {} -This command is specific to Frr. The @code{route} command makes a static -route only inside RIP. This command should be used only by advanced -users who are particularly knowledgeable about the RIP protocol. In -most cases, we recommend creating a static route in Frr and -redistributing it in RIP using @code{redistribute static}. -@end deffn - -@node Filtering RIP Routes -@section Filtering RIP Routes - -RIP routes can be filtered by a distribute-list. - -@deffn Command {distribute-list @var{access_list} @var{direct} @var{ifname}} {} -You can apply access lists to the interface with a @code{distribute-list} -command. @var{access_list} is the access list name. @var{direct} is -@samp{in} or @samp{out}. If @var{direct} is @samp{in} the access list -is applied to input packets. - -The @code{distribute-list} command can be used to filter the RIP path. -@code{distribute-list} can apply access-lists to a chosen interface. -First, one should specify the access-list. Next, the name of the -access-list is used in the distribute-list command. For example, in the -following configuration @samp{eth0} will permit only the paths that -match the route 10.0.0.0/8 - -@example -@group -! -router rip - distribute-list private in eth0 -! -access-list private permit 10 10.0.0.0/8 -access-list private deny any -! -@end group -@end example -@end deffn - -@code{distribute-list} can be applied to both incoming and outgoing data. - -@deffn Command {distribute-list prefix @var{prefix_list} (in|out) @var{ifname}} {} -You can apply prefix lists to the interface with a -@code{distribute-list} command. @var{prefix_list} is the prefix list -name. Next is the direction of @samp{in} or @samp{out}. If -@var{direct} is @samp{in} the access list is applied to input packets. -@end deffn - -@node RIP Metric Manipulation -@section RIP Metric Manipulation - -RIP metric is a value for distance for the network. Usually -@command{ripd} increment the metric when the network information is -received. Redistributed routes' metric is set to 1. - -@deffn {RIP command} {default-metric <1-16>} {} -@deffnx {RIP command} {no default-metric <1-16>} {} -This command modifies the default metric value for redistributed routes. The -default value is 1. This command does not affect connected route -even if it is redistributed by @command{redistribute connected}. To modify -connected route's metric value, please use @command{redistribute -connected metric} or @command{route-map}. @command{offset-list} also -affects connected routes. -@end deffn - -@deffn {RIP command} {offset-list @var{access-list} (in|out)} {} -@deffnx {RIP command} {offset-list @var{access-list} (in|out) @var{ifname}} {} -@end deffn - -@node RIP distance -@section RIP distance - -Distance value is used in zebra daemon. Default RIP distance is 120. - -@deffn {RIP command} {distance <1-255>} {} -@deffnx {RIP command} {no distance <1-255>} {} -Set default RIP distance to specified value. -@end deffn - -@deffn {RIP command} {distance <1-255> @var{A.B.C.D/M}} {} -@deffnx {RIP command} {no distance <1-255> @var{A.B.C.D/M}} {} -Set default RIP distance to specified value when the route's source IP -address matches the specified prefix. -@end deffn - -@deffn {RIP command} {distance <1-255> @var{A.B.C.D/M} @var{access-list}} {} -@deffnx {RIP command} {no distance <1-255> @var{A.B.C.D/M} @var{access-list}} {} -Set default RIP distance to specified value when the route's source IP -address matches the specified prefix and the specified access-list. -@end deffn - -@node RIP route-map -@section RIP route-map - -Usage of @command{ripd}'s route-map support. - -Optional argument route-map MAP_NAME can be added to each @code{redistribute} -statement. - -@example -redistribute static [route-map MAP_NAME] -redistribute connected [route-map MAP_NAME] -..... -@end example - -Cisco applies route-map _before_ routes will exported to rip route table. -In current Frr's test implementation, @command{ripd} applies route-map -after routes are listed in the route table and before routes will be -announced to an interface (something like output filter). I think it is not -so clear, but it is draft and it may be changed at future. - -Route-map statement (@pxref{Route Map}) is needed to use route-map -functionality. - -@deffn {Route Map} {match interface @var{word}} {} -This command match to incoming interface. Notation of this match is -different from Cisco. Cisco uses a list of interfaces - NAME1 NAME2 -... NAMEN. Ripd allows only one name (maybe will change in the -future). Next - Cisco means interface which includes next-hop of -routes (it is somewhat similar to "ip next-hop" statement). Ripd -means interface where this route will be sent. This difference is -because "next-hop" of same routes which sends to different interfaces -must be different. Maybe it'd be better to made new matches - say -"match interface-out NAME" or something like that. -@end deffn - -@deffn {Route Map} {match ip address @var{word}} {} -@deffnx {Route Map} {match ip address prefix-list @var{word}} {} -Match if route destination is permitted by access-list. -@end deffn - -@deffn {Route Map} {match ip next-hop @var{word}} {} -@deffnx {Route Map} {match ip next-hop prefix-list @var{word}} {} -Match if route next-hop (meaning next-hop listed in the rip route-table -as displayed by "show ip rip") is permitted by access-list. -@end deffn - -@deffn {Route Map} {match metric <0-4294967295>} {} -This command match to the metric value of RIP updates. For other -protocol compatibility metric range is shown as <0-4294967295>. But -for RIP protocol only the value range <0-16> make sense. -@end deffn - -@deffn {Route Map} {set ip next-hop A.B.C.D} {} -This command set next hop value in RIPv2 protocol. This command does -not affect RIPv1 because there is no next hop field in the packet. -@end deffn - -@deffn {Route Map} {set metric <0-4294967295>} {} -Set a metric for matched route when sending announcement. The metric -value range is very large for compatibility with other protocols. For -RIP, valid metric values are from 1 to 16. -@end deffn - -@node RIP Authentication -@section RIP Authentication - -RIPv2 allows packets to be authenticated via either an insecure plain -text password, included with the packet, or via a more secure MD5 based -@acronym{HMAC, keyed-Hashing for Message AuthentiCation}, -RIPv1 can not be authenticated at all, thus when authentication is -configured @code{ripd} will discard routing updates received via RIPv1 -packets. - -However, unless RIPv1 reception is disabled entirely, -@xref{RIP Version Control}, RIPv1 REQUEST packets which are received, -which query the router for routing information, will still be honoured -by @code{ripd}, and @code{ripd} WILL reply to such packets. This allows -@code{ripd} to honour such REQUESTs (which sometimes is used by old -equipment and very simple devices to bootstrap their default route), -while still providing security for route updates which are received. - -In short: Enabling authentication prevents routes being updated by -unauthenticated remote routers, but still can allow routes (I.e. the -entire RIP routing table) to be queried remotely, potentially by anyone -on the internet, via RIPv1. - -To prevent such unauthenticated querying of routes disable RIPv1, -@xref{RIP Version Control}. - -@deffn {Interface command} {ip rip authentication mode md5} {} -@deffnx {Interface command} {no ip rip authentication mode md5} {} -Set the interface with RIPv2 MD5 authentication. -@end deffn - -@deffn {Interface command} {ip rip authentication mode text} {} -@deffnx {Interface command} {no ip rip authentication mode text} {} -Set the interface with RIPv2 simple password authentication. -@end deffn - -@deffn {Interface command} {ip rip authentication string @var{string}} {} -@deffnx {Interface command} {no ip rip authentication string @var{string}} {} -RIP version 2 has simple text authentication. This command sets -authentication string. The string must be shorter than 16 characters. -@end deffn - -@deffn {Interface command} {ip rip authentication key-chain @var{key-chain}} {} -@deffnx {Interface command} {no ip rip authentication key-chain @var{key-chain}} {} -Specifiy Keyed MD5 chain. -@end deffn - -@example -! -key chain test - key 1 - key-string test -! -interface eth1 - ip rip authentication mode md5 - ip rip authentication key-chain test -! -@end example - -@node RIP Timers -@section RIP Timers - -@deffn {RIP command} {timers basic @var{update} @var{timeout} @var{garbage}} {} - -RIP protocol has several timers. User can configure those timers' values -by @code{timers basic} command. - -The default settings for the timers are as follows: - -@itemize @bullet -@item -The update timer is 30 seconds. Every update timer seconds, the RIP -process is awakened to send an unsolicited Response message containing -the complete routing table to all neighboring RIP routers. - -@item -The timeout timer is 180 seconds. Upon expiration of the timeout, the -route is no longer valid; however, it is retained in the routing table -for a short time so that neighbors can be notified that the route has -been dropped. - -@item -The garbage collect timer is 120 seconds. Upon expiration of the -garbage-collection timer, the route is finally removed from the routing -table. - -@end itemize - -The @code{timers basic} command allows the the default values of the timers -listed above to be changed. -@end deffn - -@deffn {RIP command} {no timers basic} {} -The @code{no timers basic} command will reset the timers to the default -settings listed above. -@end deffn - -@node Show RIP Information -@section Show RIP Information - -To display RIP routes. - -@deffn Command {show ip rip} {} -Show RIP routes. -@end deffn - -The command displays all RIP routes. For routes that are received -through RIP, this command will display the time the packet was sent and -the tag information. This command will also display this information -for routes redistributed into RIP. - -@c Exmaple here. - -@deffn Command {show ip rip status} {} -The command displays current RIP status. It includes RIP timer, -filtering, version, RIP enabled interface and RIP peer inforation. -@end deffn - -@example -@group -ripd> @b{show ip rip status} -Routing Protocol is "rip" - Sending updates every 30 seconds with +/-50%, next due in 35 seconds - Timeout after 180 seconds, garbage collect after 120 seconds - Outgoing update filter list for all interface is not set - Incoming update filter list for all interface is not set - Default redistribution metric is 1 - Redistributing: kernel connected - Default version control: send version 2, receive version 2 - Interface Send Recv - Routing for Networks: - eth0 - eth1 - 1.1.1.1 - 203.181.89.241 - Routing Information Sources: - Gateway BadPackets BadRoutes Distance Last Update -@end group -@end example - -@node RIP Debug Commands -@section RIP Debug Commands - -Debug for RIP protocol. - -@deffn Command {debug rip events} {} -Debug rip events. -@end deffn - -@code{debug rip} will show RIP events. Sending and receiving -packets, timers, and changes in interfaces are events shown with @command{ripd}. - -@deffn Command {debug rip packet} {} -Debug rip packet. -@end deffn - -@code{debug rip packet} will display detailed information about the RIP -packets. The origin and port number of the packet as well as a packet -dump is shown. - -@deffn Command {debug rip zebra} {} -Debug rip between zebra communication. -@end deffn - -This command will show the communication between @command{ripd} and -@command{zebra}. The main information will include addition and deletion of -paths to the kernel and the sending and receiving of interface information. - -@deffn Command {show debugging rip} {} -Display @command{ripd}'s debugging option. -@end deffn - -@code{show debugging rip} will show all information currently set for ripd -debug. diff --git a/doc/ripngd.texi b/doc/ripngd.texi deleted file mode 100644 index 1adda69433..0000000000 --- a/doc/ripngd.texi +++ /dev/null @@ -1,84 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the Frr Manual. -@c @value{COPYRIGHT_STR} -@c See file frr.texi for copying conditions. -@node RIPng -@chapter RIPng - -@command{ripngd} supports the RIPng protocol as described in RFC2080. It's an -IPv6 reincarnation of the RIP protocol. - -@menu -* Invoking ripngd:: -* ripngd Configuration:: -* ripngd Terminal Mode Commands:: -* ripngd Filtering Commands:: -@end menu - -@node Invoking ripngd -@section Invoking ripngd - -There are no @code{ripngd} specific invocation options. Common options -can be specified (@pxref{Common Invocation Options}). - -@node ripngd Configuration -@section ripngd Configuration - -Currently ripngd supports the following commands: - -@deffn Command {router ripng} {} -Enable RIPng. -@end deffn - -@deffn {RIPng Command} {flush_timer @var{time}} {} -Set flush timer. -@end deffn - -@deffn {RIPng Command} {network @var{network}} {} -Set RIPng enabled interface by @var{network} -@end deffn - -@deffn {RIPng Command} {network @var{ifname}} {} -Set RIPng enabled interface by @var{ifname} -@end deffn - -@deffn {RIPng Command} {route @var{network}} {} -Set RIPng static routing announcement of @var{network}. -@end deffn - -@deffn Command {router zebra} {} -This command is the default and does not appear in the configuration. -With this statement, RIPng routes go to the @command{zebra} daemon. -@end deffn - -@node ripngd Terminal Mode Commands -@section ripngd Terminal Mode Commands - -@deffn Command {show ip ripng} {} -@end deffn - -@deffn Command {show debugging ripng} {} -@end deffn - -@deffn Command {debug ripng events} {} -@end deffn - -@deffn Command {debug ripng packet} {} -@end deffn - -@deffn Command {debug ripng zebra} {} -@end deffn - -@node ripngd Filtering Commands -@section ripngd Filtering Commands - -@deffn Command {distribute-list @var{access_list} (in|out) @var{ifname}} {} -You can apply an access-list to the interface using the -@code{distribute-list} command. @var{access_list} is an access-list -name. @var{direct} is @samp{in} or @samp{out}. If @var{direct} is -@samp{in}, the access-list is applied only to incoming packets. - -@example -distribute-list local-only out sit1 -@end example -@end deffn diff --git a/doc/routemap.texi b/doc/routemap.texi deleted file mode 100644 index b72f539c46..0000000000 --- a/doc/routemap.texi +++ /dev/null @@ -1,272 +0,0 @@ -@node Route Map -@chapter Route Map - -Route maps provide a means to both filter and/or apply actions to -route, hence allowing policy to be applied to routes. - -@menu -* Route Map Command:: -* Route Map Match Command:: -* Route Map Set Command:: -* Route Map Call Command:: -* Route Map Exit Action Command:: -* Route Map Examples:: -@end menu - -Route-maps are an ordered list of route-map entries. Each entry may -specify up to four distincts sets of clauses: - -@table @samp -@item Matching Policy - -This specifies the policy implied if the @samp{Matching Conditions} are -met or not met, and which actions of the route-map are to be taken, if -any. The two possibilities are: - -@itemize @minus -@item -@samp{permit}: If the entry matches, then carry out the @samp{Set -Actions}. Then finish processing the route-map, permitting the route, -unless an @samp{Exit Action} indicates otherwise. - -@item -@samp{deny}: If the entry matches, then finish processing the route-map and -deny the route (return @samp{deny}). -@end itemize - -The @samp{Matching Policy} is specified as part of the command which -defines the ordered entry in the route-map. See below. - -@item Matching Conditions - -A route-map entry may, optionally, specify one or more conditions which -must be matched if the entry is to be considered further, as governed -by the Match Policy. If a route-map entry does not explicitely specify -any matching conditions, then it always matches. - -@item Set Actions - -A route-map entry may, optionally, specify one or more @samp{Set -Actions} to set or modify attributes of the route. - -@item Call Action - -Call to another route-map, after any @samp{Set Actions} have been -carried out. If the route-map called returns @samp{deny} then -processing of the route-map finishes and the route is denied, -regardless of the @samp{Matching Policy} or the @samp{Exit Policy}. If -the called route-map returns @samp{permit}, then @samp{Matching Policy} -and @samp{Exit Policy} govern further behaviour, as normal. - -@item Exit Policy - -An entry may, optionally, specify an alternative @samp{Exit Policy} to -take if the entry matched, rather than the normal policy of exiting the -route-map and permitting the route. The two possibilities are: - -@itemize @minus -@item -@samp{next}: Continue on with processing of the route-map entries. - -@item -@samp{goto N}: Jump ahead to the first route-map entry whose order in -the route-map is >= N. Jumping to a previous entry is not permitted. -@end itemize -@end table - -The default action of a route-map, if no entries match, is to deny. -I.e. a route-map essentially has as its last entry an empty @samp{deny} -entry, which matches all routes. To change this behaviour, one must -specify an empty @samp{permit} entry as the last entry in the route-map. - -To summarise the above: - -@multitable {permit} {action} {No Match} -@headitem @tab Match @tab No Match -@item @emph{Permit} @tab action @tab cont -@item @emph{Deny} @tab deny @tab cont -@end multitable - -@table @samp - -@item action -@itemize @minus -@item -Apply @emph{set} statements - -@item -If @emph{call} is present, call given route-map. If that returns a @samp{deny}, finish -processing and return @samp{deny}. - -@item -If @samp{Exit Policy} is @emph{next}, goto next route-map entry - -@item -If @samp{Exit Policy} is @emph{goto}, goto first entry whose order in the list -is >= the given order. - -@item -Finish processing the route-map and permit the route. -@end itemize - -@item deny -@itemize @minus -@item -The route is denied by the route-map (return @samp{deny}). -@end itemize - -@item cont -@itemize @minus -@item -goto next route-map entry -@end itemize -@end table - -@node Route Map Command -@section Route Map Command - -@deffn {Command} {route-map @var{route-map-name} (permit|deny) @var{order}} {} - -Configure the @var{order}'th entry in @var{route-map-name} with -@samp{Match Policy} of either @emph{permit} or @emph{deny}. - -@end deffn - -@node Route Map Match Command -@section Route Map Match Command - -@deffn {Route-map Command} {match ip address @var{access_list}} {} -Matches the specified @var{access_list} -@end deffn - -@deffn {Route-map Command} {match ip address @var{prefix-list}} {} -Matches the specified @var{prefix-list} -@end deffn - -@deffn {Route-map Command} {match ip address prefix-len @var{0-32}} {} -Matches the specified @var{prefix-len}. This is a Zebra specific command. -@end deffn - -@deffn {Route-map Command} {match ipv6 address @var{access_list}} {} -Matches the specified @var{access_list} -@end deffn - -@deffn {Route-map Command} {match ipv6 address @var{prefix-list}} {} -Matches the specified @var{prefix-list} -@end deffn - -@deffn {Route-map Command} {match ipv6 address prefix-len @var{0-128}} {} -Matches the specified @var{prefix-len}. This is a Zebra specific command. -@end deffn - -@deffn {Route-map Command} {match ip next-hop @var{ipv4_addr}} {} -Matches the specified @var{ipv4_addr}. -@end deffn - -@deffn {Route-map Command} {match aspath @var{as_path}} {} -Matches the specified @var{as_path}. -@end deffn - -@deffn {Route-map Command} {match metric @var{metric}} {} -Matches the specified @var{metric}. -@end deffn - -@deffn {Route-map Command} {match local-preference @var{metric}} {} -Matches the specified @var{local-preference}. -@end deffn - -@deffn {Route-map Command} {match community @var{community_list}} {} -Matches the specified @var{community_list} -@end deffn - -@deffn {Route-map Command} {match peer @var{ipv4_addr}} {} -This is a BGP specific match command. Matches the peer ip address -if the neighbor was specified in this manner. -@end deffn - -@deffn {Route-map Command} {match peer @var{ipv6_addr}} {} -This is a BGP specific match command. Matches the peer ipv6 -address if the neighbor was specified in this manner. -@end deffn - -@deffn {Route-map Command} {match peer @var{interface_name}} {} -This is a BGP specific match command. Matches the peer -interface name specified if the neighbor was specified -in this manner. -@end deffn - -@node Route Map Set Command -@section Route Map Set Command - -@deffn {Route-map Command} {set ip next-hop @var{ipv4_address}} {} -Set the BGP nexthop address. -@end deffn - -@deffn {Route-map Command} {set local-preference @var{local_pref}} {} -Set the BGP local preference to @var{local_pref}. -@end deffn - -@deffn {Route-map Command} {set weight @var{weight}} {} -Set the route's weight. -@end deffn - -@deffn {Route-map Command} {set metric @var{metric}} {} -@anchor{routemap set metric} -Set the BGP attribute MED. -@end deffn - -@deffn {Route-map Command} {set as-path prepend @var{as_path}} {} -Set the BGP AS path to prepend. -@end deffn - -@deffn {Route-map Command} {set community @var{community}} {} -Set the BGP community attribute. -@end deffn - -@deffn {Route-map Command} {set ipv6 next-hop global @var{ipv6_address}} {} -Set the BGP-4+ global IPv6 nexthop address. -@end deffn - -@deffn {Route-map Command} {set ipv6 next-hop local @var{ipv6_address}} {} -Set the BGP-4+ link local IPv6 nexthop address. -@end deffn - -@node Route Map Call Command -@section Route Map Call Command - -@deffn {Route-map Command} {call @var{name}} {} -Call route-map @var{name}. If it returns deny, deny the route and -finish processing the route-map. -@end deffn - -@node Route Map Exit Action Command -@section Route Map Exit Action Command - -@deffn {Route-map Command} {on-match next} {} -@deffnx {Route-map Command} {continue} {} -Proceed on to the next entry in the route-map. -@end deffn - -@deffn {Route-map Command} {on-match goto @var{N}} {} -@deffnx {Route-map Command} {continue @var{N}} {} -Proceed processing the route-map at the first entry whose order is >= N -@end deffn - -@node Route Map Examples -@section Route Map Examples - -A simple example of a route-map: - -@example -@group -route-map test permit 10 - match ip address 10 - set local-preference 200 -@end group -@end example - -This means that if a route matches ip access-list number 10 it's -local-preference value is set to 200. - -See @ref{BGP Configuration Examples} for examples of more sophisticated -useage of route-maps, including of the @samp{call} action. diff --git a/doc/routeserver.texi b/doc/routeserver.texi deleted file mode 100644 index b25800107d..0000000000 --- a/doc/routeserver.texi +++ /dev/null @@ -1,561 +0,0 @@ -@c -*-texinfo-*- -@c @value{COPYRIGHT_STR} -@c See file frr.texi for copying conditions. -@c -@c This file is a modified version of Jose Luis Rubio's TeX sources -@c of his RS-Manual document - -@node Configuring Frr as a Route Server -@chapter Configuring Frr as a Route Server - -The purpose of a Route Server is to centralize the peerings between BGP -speakers. For example if we have an exchange point scenario with four BGP -speakers, each of which maintaining a BGP peering with the other three -(@pxref{fig:full-mesh}), we can convert it into a centralized scenario where -each of the four establishes a single BGP peering against the Route Server -(@pxref{fig:route-server}). - -We will first describe briefly the Route Server model implemented by Frr. -We will explain the commands that have been added for configuring that -model. And finally we will show a full example of Frr configured as Route -Server. - -@menu -* Description of the Route Server model:: -* Commands for configuring a Route Server:: -* Example of Route Server Configuration:: -@end menu - -@node Description of the Route Server model -@section Description of the Route Server model - -First we are going to describe the normal processing that BGP announcements -suffer inside a standard BGP speaker, as shown in @ref{fig:normal-processing}, -it consists of three steps: - -@itemize @bullet -@item -When an announcement is received from some peer, the `In' filters -configured for that peer are applied to the announcement. These filters can -reject the announcement, accept it unmodified, or accept it with some of its -attributes modified. - -@item -The announcements that pass the `In' filters go into the -Best Path Selection process, where they are compared to other -announcements referred to the same destination that have been -received from different peers (in case such other -announcements exist). For each different destination, the announcement -which is selected as the best is inserted into the BGP speaker's Loc-RIB. - -@item -The routes which are inserted in the Loc-RIB are -considered for announcement to all the peers (except the one -from which the route came). This is done by passing the routes -in the Loc-RIB through the `Out' filters corresponding to each -peer. These filters can reject the route, -accept it unmodified, or accept it with some of its attributes -modified. Those routes which are accepted by the `Out' filters -of a peer are announced to that peer. -@end itemize - -@float Figure,fig:normal-processing -@image{fig-normal-processing,400pt,,Normal announcement processing} -@caption{Announcement processing inside a ``normal'' BGP speaker} -@end float - -@float Figure,fig:full-mesh -@image{fig_topologies_full,120pt,,Full Mesh BGP Topology} -@caption{Full Mesh} -@end float - -@float Figure,fig:route-server -@image{fig_topologies_rs,120pt,,Route Server BGP Topology} -@caption{Route Server and clients} -@end float - -Of course we want that the routing tables obtained in each of the routers -are the same when using the route server than when not. But as a consequence -of having a single BGP peering (against the route server), the BGP speakers -can no longer distinguish from/to which peer each announce comes/goes. -@anchor{filter-delegation}This means that the routers connected to the route -server are not able to apply by themselves the same input/output filters -as in the full mesh scenario, so they have to delegate those functions to -the route server. - -Even more, the ``best path'' selection must be also performed inside -the route server on behalf of its clients. The reason is that if, after -applying the filters of the announcer and the (potential) receiver, the -route server decides to send to some client two or more different -announcements referred to the same destination, the client will only -retain the last one, considering it as an implicit withdrawal of the -previous announcements for the same destination. This is the expected -behavior of a BGP speaker as defined in @cite{RFC1771}, and even though -there are some proposals of mechanisms that permit multiple paths for -the same destination to be sent through a single BGP peering, none are -currently supported by most existing BGP implementations. - -As a consequence a route server must maintain additional information and -perform additional tasks for a RS-client that those necessary for common BGP -peerings. Essentially a route server must: - -@anchor{Route Server tasks} -@itemize @bullet -@item -Maintain a separated Routing Information Base (Loc-RIB) -for each peer configured as RS-client, containing the routes -selected as a result of the ``Best Path Selection'' process -that is performed on behalf of that RS-client. - -@item -Whenever it receives an announcement from a RS-client, -it must consider it for the Loc-RIBs of the other RS-clients. - -@anchor{Route-server path filter process} -@itemize @bullet -@item -This means that for each of them the route server must pass the -announcement through the appropriate `Out' filter of the -announcer. - -@item -Then through the appropriate `In' filter of -the potential receiver. - -@item -Only if the announcement is accepted by both filters it will be passed -to the ``Best Path Selection'' process. - -@item -Finally, it might go into the Loc-RIB of the receiver. -@end itemize -@end itemize - -When we talk about the ``appropriate'' filter, both the announcer and the -receiver of the route must be taken into account. Suppose that the route -server receives an announcement from client A, and the route server is -considering it for the Loc-RIB of client B. The filters that should be -applied are the same that would be used in the full mesh scenario, i.e., -first the `Out' filter of router A for announcements going to router B, and -then the `In' filter of router B for announcements coming from router A. - -We call ``Export Policy'' of a RS-client to the set of `Out' filters that -the client would use if there was no route server. The same applies for the -``Import Policy'' of a RS-client and the set of `In' filters of the client -if there was no route server. - -It is also common to demand from a route server that it does not -modify some BGP attributes (next-hop, as-path and MED) that are usually -modified by standard BGP speakers before announcing a route. - -The announcement processing model implemented by Frr is shown in -@ref{fig:rs-processing}. The figure shows a mixture of RS-clients (B, C and D) -with normal BGP peers (A). There are some details that worth additional -comments: - -@itemize @bullet -@item -Announcements coming from a normal BGP peer are also -considered for the Loc-RIBs of all the RS-clients. But -logically they do not pass through any export policy. - -@item -Those peers that are configured as RS-clients do not -receive any announce from the `Main' Loc-RIB. - -@item -Apart from import and export policies, -`In' and `Out' filters can also be set for RS-clients. `In' -filters might be useful when the route server has also normal -BGP peers. On the other hand, `Out' filters for RS-clients are -probably unnecessary, but we decided not to remove them as -they do not hurt anybody (they can always be left empty). -@end itemize - -@float Figure,fig:rs-processing -@image{fig-rs-processing,450pt,,Route Server Processing Model} -@caption{Announcement processing model implemented by the Route Server} -@end float - -@node Commands for configuring a Route Server -@section Commands for configuring a Route Server - -Now we will describe the commands that have been added to frr -in order to support the route server features. - -@deffn {Route-Server} {neighbor @var{peer-group} route-server-client} {} -@deffnx {Route-Server} {neighbor @var{A.B.C.D} route-server-client} {} -@deffnx {Route-Server} {neighbor @var{X:X::X:X} route-server-client} {} -This command configures the peer given by @var{peer}, @var{A.B.C.D} or -@var{X:X::X:X} as an RS-client. - -Actually this command is not new, it already existed in standard Frr. It -enables the transparent mode for the specified peer. This means that some -BGP attributes (as-path, next-hop and MED) of the routes announced to that -peer are not modified. - -With the route server patch, this command, apart from setting the -transparent mode, creates a new Loc-RIB dedicated to the specified peer -(those named `Loc-RIB for X' in @ref{fig:rs-processing}.). Starting from -that moment, every announcement received by the route server will be also -considered for the new Loc-RIB. -@end deffn - -@deffn {Route-Server} {neigbor @{A.B.C.D|X.X::X.X|peer-group@} route-map WORD @{import|export@}} {} -This set of commands can be used to specify the route-map that -represents the Import or Export policy of a peer which is -configured as a RS-client (with the previous command). -@end deffn - -@deffn {Route-Server} {match peer @{A.B.C.D|X:X::X:X@}} {} -This is a new @emph{match} statement for use in route-maps, enabling them to -describe import/export policies. As we said before, an import/export policy -represents a set of input/output filters of the RS-client. This statement -makes possible that a single route-map represents the full set of filters -that a BGP speaker would use for its different peers in a non-RS scenario. - -The @emph{match peer} statement has different semantics whether it is used -inside an import or an export route-map. In the first case the statement -matches if the address of the peer who sends the announce is the same that -the address specified by @{A.B.C.D|X:X::X:X@}. For export route-maps it -matches when @{A.B.C.D|X:X::X:X@} is the address of the RS-Client into whose -Loc-RIB the announce is going to be inserted (how the same export policy is -applied before different Loc-RIBs is shown in @ref{fig:rs-processing}.). -@end deffn - -@deffn {Route-map Command} {call @var{WORD}} {} -This command (also used inside a route-map) jumps into a different -route-map, whose name is specified by @var{WORD}. When the called -route-map finishes, depending on its result the original route-map -continues or not. Apart from being useful for making import/export -route-maps easier to write, this command can also be used inside -any normal (in or out) route-map. -@end deffn - -@node Example of Route Server Configuration -@section Example of Route Server Configuration - -Finally we are going to show how to configure a Frr daemon to act as a -Route Server. For this purpose we are going to present a scenario without -route server, and then we will show how to use the configurations of the BGP -routers to generate the configuration of the route server. - -All the configuration files shown in this section have been taken -from scenarios which were tested using the VNUML tool -@uref{http://www.dit.upm.es/vnuml,VNUML}. - -@menu -* Configuration of the BGP routers without Route Server:: -* Configuration of the BGP routers with Route Server:: -* Configuration of the Route Server itself:: -* Further considerations about Import and Export route-maps:: -@end menu - -@node Configuration of the BGP routers without Route Server -@subsection Configuration of the BGP routers without Route Server - -We will suppose that our initial scenario is an exchange point with three -BGP capable routers, named RA, RB and RC. Each of the BGP speakers generates -some routes (with the @var{network} command), and establishes BGP peerings -against the other two routers. These peerings have In and Out route-maps -configured, named like ``PEER-X-IN'' or ``PEER-X-OUT''. For example the -configuration file for router RA could be the following: - -@exampleindent 0 -@example -#Configuration for router 'RA' -! -hostname RA -password **** -! -router bgp 65001 - no bgp default ipv4-unicast - neighbor 2001:0DB8::B remote-as 65002 - neighbor 2001:0DB8::C remote-as 65003 -! - address-family ipv6 - network 2001:0DB8:AAAA:1::/64 - network 2001:0DB8:AAAA:2::/64 - network 2001:0DB8:0000:1::/64 - network 2001:0DB8:0000:2::/64 - - neighbor 2001:0DB8::B activate - neighbor 2001:0DB8::B soft-reconfiguration inbound - neighbor 2001:0DB8::B route-map PEER-B-IN in - neighbor 2001:0DB8::B route-map PEER-B-OUT out - - neighbor 2001:0DB8::C activate - neighbor 2001:0DB8::C soft-reconfiguration inbound - neighbor 2001:0DB8::C route-map PEER-C-IN in - neighbor 2001:0DB8::C route-map PEER-C-OUT out - exit-address-family -! -ipv6 prefix-list COMMON-PREFIXES seq 5 permit 2001:0DB8:0000::/48 ge 64 le 64 -ipv6 prefix-list COMMON-PREFIXES seq 10 deny any -! -ipv6 prefix-list PEER-A-PREFIXES seq 5 permit 2001:0DB8:AAAA::/48 ge 64 le 64 -ipv6 prefix-list PEER-A-PREFIXES seq 10 deny any -! -ipv6 prefix-list PEER-B-PREFIXES seq 5 permit 2001:0DB8:BBBB::/48 ge 64 le 64 -ipv6 prefix-list PEER-B-PREFIXES seq 10 deny any -! -ipv6 prefix-list PEER-C-PREFIXES seq 5 permit 2001:0DB8:CCCC::/48 ge 64 le 64 -ipv6 prefix-list PEER-C-PREFIXES seq 10 deny any -! -route-map PEER-B-IN permit 10 - match ipv6 address prefix-list COMMON-PREFIXES - set metric 100 -route-map PEER-B-IN permit 20 - match ipv6 address prefix-list PEER-B-PREFIXES - set community 65001:11111 -! -route-map PEER-C-IN permit 10 - match ipv6 address prefix-list COMMON-PREFIXES - set metric 200 -route-map PEER-C-IN permit 20 - match ipv6 address prefix-list PEER-C-PREFIXES - set community 65001:22222 -! -route-map PEER-B-OUT permit 10 - match ipv6 address prefix-list PEER-A-PREFIXES -! -route-map PEER-C-OUT permit 10 - match ipv6 address prefix-list PEER-A-PREFIXES -! -line vty -! -@end example - -@node Configuration of the BGP routers with Route Server -@subsection Configuration of the BGP routers with Route Server - -To convert the initial scenario into one with route server, first we must -modify the configuration of routers RA, RB and RC. Now they must not peer -between them, but only with the route server. For example, RA's -configuration would turn into: - -@example -# Configuration for router 'RA' -! -hostname RA -password **** -! -router bgp 65001 - no bgp default ipv4-unicast - neighbor 2001:0DB8::FFFF remote-as 65000 -! - address-family ipv6 - network 2001:0DB8:AAAA:1::/64 - network 2001:0DB8:AAAA:2::/64 - network 2001:0DB8:0000:1::/64 - network 2001:0DB8:0000:2::/64 - - neighbor 2001:0DB8::FFFF activate - neighbor 2001:0DB8::FFFF soft-reconfiguration inbound - exit-address-family -! -line vty -! -@end example - -Which is logically much simpler than its initial configuration, as it now -maintains only one BGP peering and all the filters (route-maps) have -disappeared. - -@node Configuration of the Route Server itself -@subsection Configuration of the Route Server itself - -As we said when we described the functions of a route server -(@pxref{Description of the Route Server model}), it is in charge of all the -route filtering. To achieve that, the In and Out filters from the RA, RB and -RC configurations must be converted into Import and Export policies in the -route server. - -This is a fragment of the route server configuration (we only show -the policies for client RA): - -@example -# Configuration for Route Server ('RS') -! -hostname RS -password ix -! -bgp multiple-instance -! -router bgp 65000 view RS - no bgp default ipv4-unicast - neighbor 2001:0DB8::A remote-as 65001 - neighbor 2001:0DB8::B remote-as 65002 - neighbor 2001:0DB8::C remote-as 65003 -! - address-family ipv6 - neighbor 2001:0DB8::A activate - neighbor 2001:0DB8::A route-server-client - neighbor 2001:0DB8::A route-map RSCLIENT-A-IMPORT import - neighbor 2001:0DB8::A route-map RSCLIENT-A-EXPORT export - neighbor 2001:0DB8::A soft-reconfiguration inbound - - neighbor 2001:0DB8::B activate - neighbor 2001:0DB8::B route-server-client - neighbor 2001:0DB8::B route-map RSCLIENT-B-IMPORT import - neighbor 2001:0DB8::B route-map RSCLIENT-B-EXPORT export - neighbor 2001:0DB8::B soft-reconfiguration inbound - - neighbor 2001:0DB8::C activate - neighbor 2001:0DB8::C route-server-client - neighbor 2001:0DB8::C route-map RSCLIENT-C-IMPORT import - neighbor 2001:0DB8::C route-map RSCLIENT-C-EXPORT export - neighbor 2001:0DB8::C soft-reconfiguration inbound - exit-address-family -! -ipv6 prefix-list COMMON-PREFIXES seq 5 permit 2001:0DB8:0000::/48 ge 64 le 64 -ipv6 prefix-list COMMON-PREFIXES seq 10 deny any -! -ipv6 prefix-list PEER-A-PREFIXES seq 5 permit 2001:0DB8:AAAA::/48 ge 64 le 64 -ipv6 prefix-list PEER-A-PREFIXES seq 10 deny any -! -ipv6 prefix-list PEER-B-PREFIXES seq 5 permit 2001:0DB8:BBBB::/48 ge 64 le 64 -ipv6 prefix-list PEER-B-PREFIXES seq 10 deny any -! -ipv6 prefix-list PEER-C-PREFIXES seq 5 permit 2001:0DB8:CCCC::/48 ge 64 le 64 -ipv6 prefix-list PEER-C-PREFIXES seq 10 deny any -! -route-map RSCLIENT-A-IMPORT permit 10 - match peer 2001:0DB8::B - call A-IMPORT-FROM-B -route-map RSCLIENT-A-IMPORT permit 20 - match peer 2001:0DB8::C - call A-IMPORT-FROM-C -! -route-map A-IMPORT-FROM-B permit 10 - match ipv6 address prefix-list COMMON-PREFIXES - set metric 100 -route-map A-IMPORT-FROM-B permit 20 - match ipv6 address prefix-list PEER-B-PREFIXES - set community 65001:11111 -! -route-map A-IMPORT-FROM-C permit 10 - match ipv6 address prefix-list COMMON-PREFIXES - set metric 200 -route-map A-IMPORT-FROM-C permit 20 - match ipv6 address prefix-list PEER-C-PREFIXES - set community 65001:22222 -! -route-map RSCLIENT-A-EXPORT permit 10 - match peer 2001:0DB8::B - match ipv6 address prefix-list PEER-A-PREFIXES -route-map RSCLIENT-A-EXPORT permit 20 - match peer 2001:0DB8::C - match ipv6 address prefix-list PEER-A-PREFIXES -! -... -... -... -@end example - -If you compare the initial configuration of RA with the route server -configuration above, you can see how easy it is to generate the Import and -Export policies for RA from the In and Out route-maps of RA's original -configuration. - -When there was no route server, RA maintained two peerings, one with RB and -another with RC. Each of this peerings had an In route-map configured. To -build the Import route-map for client RA in the route server, simply add -route-map entries following this scheme: - -@example -route-map permit 10 - match peer - call -route-map permit 20 - match peer - call -@end example - -This is exactly the process that has been followed to generate the route-map -RSCLIENT-A-IMPORT. The route-maps that are called inside it (A-IMPORT-FROM-B -and A-IMPORT-FROM-C) are exactly the same than the In route-maps from the -original configuration of RA (PEER-B-IN and PEER-C-IN), only the name is -different. - -The same could have been done to create the Export policy for RA (route-map -RSCLIENT-A-EXPORT), but in this case the original Out route-maps where so -simple that we decided not to use the @var{call WORD} commands, and we -integrated all in a single route-map (RSCLIENT-A-EXPORT). - -The Import and Export policies for RB and RC are not shown, but -the process would be identical. - -@node Further considerations about Import and Export route-maps -@subsection Further considerations about Import and Export route-maps - -The current version of the route server patch only allows to specify a -route-map for import and export policies, while in a standard BGP speaker -apart from route-maps there are other tools for performing input and output -filtering (access-lists, community-lists, ...). But this does not represent -any limitation, as all kinds of filters can be included in import/export -route-maps. For example suppose that in the non-route-server scenario peer -RA had the following filters configured for input from peer B: - -@example - neighbor 2001:0DB8::B prefix-list LIST-1 in - neighbor 2001:0DB8::B filter-list LIST-2 in - neighbor 2001:0DB8::B route-map PEER-B-IN in - ... - ... -route-map PEER-B-IN permit 10 - match ipv6 address prefix-list COMMON-PREFIXES - set local-preference 100 -route-map PEER-B-IN permit 20 - match ipv6 address prefix-list PEER-B-PREFIXES - set community 65001:11111 -@end example - -It is posible to write a single route-map which is equivalent to -the three filters (the community-list, the prefix-list and the -route-map). That route-map can then be used inside the Import -policy in the route server. Lets see how to do it: - -@example - neighbor 2001:0DB8::A route-map RSCLIENT-A-IMPORT import - ... -! -... -route-map RSCLIENT-A-IMPORT permit 10 - match peer 2001:0DB8::B - call A-IMPORT-FROM-B -... -... -! -route-map A-IMPORT-FROM-B permit 1 - match ipv6 address prefix-list LIST-1 - match as-path LIST-2 - on-match goto 10 -route-map A-IMPORT-FROM-B deny 2 -route-map A-IMPORT-FROM-B permit 10 - match ipv6 address prefix-list COMMON-PREFIXES - set local-preference 100 -route-map A-IMPORT-FROM-B permit 20 - match ipv6 address prefix-list PEER-B-PREFIXES - set community 65001:11111 -! -... -... -@end example - -The route-map A-IMPORT-FROM-B is equivalent to the three filters -(LIST-1, LIST-2 and PEER-B-IN). The first entry of route-map -A-IMPORT-FROM-B (sequence number 1) matches if and only if both -the prefix-list LIST-1 and the filter-list LIST-2 match. If that -happens, due to the ``on-match goto 10'' statement the next -route-map entry to be processed will be number 10, and as of that -point route-map A-IMPORT-FROM-B is identical to PEER-B-IN. If -the first entry does not match, `on-match goto 10'' will be -ignored and the next processed entry will be number 2, which will -deny the route. - -Thus, the result is the same that with the three original filters, -i.e., if either LIST-1 or LIST-2 rejects the route, it does not -reach the route-map PEER-B-IN. In case both LIST-1 and LIST-2 -accept the route, it passes to PEER-B-IN, which can reject, accept -or modify the route. diff --git a/doc/rpki.texi b/doc/rpki.texi deleted file mode 100644 index c1c8a8aa54..0000000000 --- a/doc/rpki.texi +++ /dev/null @@ -1,256 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the FRR Manual. -@c @value{COPYRIGHT_STR} -@c See file frr.texi for copying conditions. -@node Prefix Origin Validation Using RPKI -@section Prefix Origin Validation Using RPKI - -Prefix Origin Validation allows BGP routers to verify if the origin AS of -an IP prefix is legitimate to announce this IP prefix. The required -attestation objects are stored in the Resource Public Key Infrastructure -(@acronym{RPKI}). However, RPKI-enabled routers do not store cryptographic -data itself but only validation information. The validation of the -cryptographic data (so called Route Origin Authorization, or short -@acronym{ROA}, objects) will be performed by trusted cache servers. The -RPKI/RTR protocol defines a standard mechanism to maintain the exchange of -the prefix/origin AS mapping between the cache server and routers. -In combination with a BGP Prefix Origin Validation scheme a router is able -to verify received BGP updates without suffering from cryptographic -complexity. - - -The RPKI/RTR protocol is defined in @cite{RFC6810, The Resource Public Key -Infrastructure (RPKI) to Router Protocol}, and the validation scheme in -@cite{RFC6811, BGP Prefix Origin Validation}. The current version of Prefix -Origin Validation in FRR implements both RFCs. - -For a more detailed but still easy-to-read background, we suggest the -following two articles: -@enumerate -@item @cite{Geoff Huston, Randy Bush: Securing BGP, In: The Internet -Protocol Journal, Volume 14, No. 2, 2011.} -@uref{http://www.cisco.com/web/about/ac123/ac147/archived_issues/ipj_14-2/142_bgp.html} - -@item @cite{Geoff Huston: Resource Certification, In: The Internet Protocol -Journal, Volume 12, No.1, 2009.} -@uref{http://www.cisco.com/web/about/ac123/ac147/archived_issues/ipj_12-1/121_resource.html} -@end enumerate - -@menu -* Features of the Current Implementation:: -* Enabling RPKI:: -* Configuring RPKI/RTR Cache Servers:: -* Validating BGP Updates:: -* Debugging:: -* Displaying RPKI:: -* RPKI Configuration Example:: -@end menu - -@node Features of the Current Implementation -@subsection Features of the Current Implementation - -In a nutshell, the current implementation provides the following features -@itemize @bullet -@item The BGP router can connect to one or more RPKI cache servers to -receive validated prefix to origin AS mappings. -Advanced failover can be implemented by server sockets with different -preference values. - -@item If no connection to an RPKI cache server can be established after a -pre-defined timeout, the router will process routes without prefix origin -validation. It still will try to establish a connection to an RPKI cache -server in the background. - -@item By default, enabling RPKI does not change best path selection. In -particular, invalid prefixes will still be considered during best path -selection. However, the router can be configured to ignore all invalid -prefixes. - -@item Route maps can be configured to match a specific RPKI validation -state. This allows the creation of local policies, which handle BGP routes -based on the outcome of the Prefix Origin Validation. - -@c @item When the router receives updated validation information from the RPKI -@c cache server, all routes in the local routing table will be re-evaluated. - -@end itemize - - -@node Enabling RPKI -@subsection Enabling RPKI -@deffn {Command} {rpki} {} -This command enables the RPKI configuration mode. Most commands that start -with @command{rpki} can only be used in this mode. - -When it is used in a telnet session, leaving of this mode cause rpki to be initialized. - -Executing this command alone does not activate prefix -validation. You need to configure at least one reachable cache server. See section -@ref{Configuring RPKI/RTR Cache Servers} for configuring a cache server. -@end deffn - -@node Configuring RPKI/RTR Cache Servers -@subsection Configuring RPKI/RTR Cache Servers - -The following commands are independent of a specific cache server. - -@deffn {RPKI Command} {rpki polling_period <1-3600>} {} -@deffnx {RPKI Command} {no rpki polling_period} {} -Set the number of seconds the router waits until the router asks the cache again -for updated data. - -The default value is 300 seconds. -@end deffn - -@deffn {RPKI Command} {rpki timeout <1-4,294,967,296>} {} -@deffnx {RPKI Command} {no rpki timeout} {} -Set the number of seconds the router waits for the cache reply. If the -cache server is not replying within this time period, the router deletes -all received prefix records from the prefix table. - -The default value is 600 seconds. -@end deffn - -@deffn {RPKI Command} {rpki initial-synchronisation-timeout <1-4,294,967,296>} {} -@deffnx {RPKI Command} {no rpki initial-synchronisation-timeout} {} -Set the number of seconds until the first synchronization with the cache -server needs to be completed. If the timeout expires, BGP routing is -started without RPKI. The router will try to establish the cache server -connection in the background. - -The default value is 30 seconds. -@end deffn - -@noindent The following commands configure one or multiple cache servers. - -@deffn {RPKI Socket Command} {rpki cache (@var{A.B.C.D}|@var{WORD}) @var{PORT} [@var{SSH_USERNAME}] [@var{SSH_PRIVKEY_PATH}] [@var{SSH_PUBKEY_PATH}] [@var{KNOWN_HOSTS_PATH}] @var{PREFERENCE}} {} -@deffnx {RPKI Socket Command} {no rpki cache (@var{A.B.C.D}|@var{WORD}) [@var{PORT}] @var{PREFERENCE}} {} -Add a cache server to the socket. By default, the connection between -router and cache server is based on plain TCP. Protecting the connection -between router and cache server by SSH is optional. -Deleting a socket removes the associated cache server and -terminates the existing connection. -@end deffn - -@table @code -@item @var{A.B.C.D}|@var{WORD} -Address of the cache server. - -@item @var{PORT} -Port number to connect to the cache server - -@item @var{SSH_USERNAME} -SSH username to establish an SSH connection to the cache server. - -@item @var{SSH_PRIVKEY_PATH} -Local path that includes the private key file of the router. - -@item @var{SSH_PUBKEY_PATH} -Local path that includes the public key file of the router. - -@item @var{KNOWN_HOSTS_PATH} -Local path that includes the known hosts file. The default value depends on the -configuration of the operating system environment, usually -@file{~/.ssh/known_hosts}. - -@end table - -@node Validating BGP Updates -@subsection Validating BGP Updates - -@deffn {Route Map Command} {match rpki @{notfound|invalid|valid@}} {} -@deffnx {Route Map Command} {no match rpki @{notfound|invalid|valid@}} {} -Create a clause for a route map to match prefixes with the specified RPKI state. - -@strong{Note} that the matching of invalid prefixes requires that invalid -prefixes are considered for best path selection, i.e., @command{bgp -bestpath prefix-validate disallow-invalid} is not enabled. - -In the following example, the router prefers valid routes over invalid -prefixes because invalid routes have a lower local preference. -@example - ! Allow for invalid routes in route selection process - route bgp 60001 - ! - ! Set local preference of invalid prefixes to 10 - route-map rpki permit 10 - match rpki invalid - set local-preference 10 - ! - ! Set local preference of valid prefixes to 500 - route-map rpki permit 500 - match rpki valid - set local-preference 500 -@end example - -@end deffn - -@node Debugging -@subsection Debugging - -@deffn {Command} {debug rpki} {} -@deffnx {Command} {no debug rpki} {} -Enable or disable debugging output for RPKI. -@end deffn - - -@node Displaying RPKI -@subsection Displaying RPKI - -@deffn {Command} {show rpki prefix-table} {} -Display all validated prefix to origin AS mappings/records which have been -received from the cache servers and stored in the router. Based on this data, -the router validates BGP Updates. -@end deffn - -@deffn {Command} {show rpki cache-connection} {} -Display all configured cache servers, whether active or not. -@end deffn - -@node RPKI Configuration Example -@subsection RPKI Configuration Example - - -@example -hostname bgpd1 -password zebra -! log stdout -debug bgp updates -debug bgp keepalives -debug rpki -! -rpki - rpki polling_period 1000 - rpki timeout 10 - ! SSH Example: - rpki cache example.com 22 rtr-ssh ./ssh_key/id_rsa ./ssh_key/id_rsa.pub preference 1 - ! TCP Example: - rpki cache rpki-validator.realmv6.org 8282 preference 2 - exit -! -router bgp 60001 - bgp router-id 141.22.28.223 - network 192.168.0.0/16 - neighbor 123.123.123.0 remote-as 60002 - neighbor 123.123.123.0 route-map rpki in -! - address-family ipv6 - neighbor 123.123.123.0 activate - neighbor 123.123.123.0 route-map rpki in - exit-address-family -! -route-map rpki permit 10 - match rpki invalid - set local-preference 10 -! -route-map rpki permit 20 - match rpki notfound - set local-preference 20 -! -route-map rpki permit 30 - match rpki valid - set local-preference 30 -! -route-map rpki permit 40 -! -@end example diff --git a/doc/snmp.texi b/doc/snmp.texi deleted file mode 100644 index d9656941d0..0000000000 --- a/doc/snmp.texi +++ /dev/null @@ -1,189 +0,0 @@ -@node SNMP Support -@chapter SNMP Support - -@acronym{SNMP,Simple Network Managing Protocol} is a widely implemented -feature for collecting network information from router and/or host. -Frr itself does not support SNMP agent (server daemon) functionality -but is able to connect to a SNMP agent using the SMUX protocol -(@cite{RFC1227}) or the AgentX protocol (@cite{RFC2741}) and make the -routing protocol MIBs available through it. - -Note that SNMP Support needs to be enabled at compile-time and loaded as -module on daemon startup. Refer to @ref{Loadable Module Support} on -the latter. - -@menu -* Getting and installing an SNMP agent:: -* AgentX configuration:: -* SMUX configuration:: -* MIB and command reference:: -* Handling SNMP Traps:: -@end menu - -@node Getting and installing an SNMP agent -@section Getting and installing an SNMP agent - -There are several SNMP agent which support SMUX or AgentX. We recommend to use the latest -version of @code{net-snmp} which was formerly known as @code{ucd-snmp}. -It is free and open software and available at @uref{http://www.net-snmp.org/} -and as binary package for most Linux distributions. -@code{net-snmp} has to be compiled with @code{--with-mib-modules=agentx} to -be able to accept connections from Frr using AgentX protocol or with -@code{--with-mib-modules=smux} to use SMUX protocol. - -Nowadays, SMUX is a legacy protocol. The AgentX protocol should be -preferred for any new deployment. Both protocols have the same coverage. - -@node AgentX configuration -@section AgentX configuration - -To enable AgentX protocol support, Frr must have been build with the -@code{--enable-snmp} or @code{--enable-snmp=agentx} option. Both the -master SNMP agent (snmpd) and each of the Frr daemons must be -configured. In @code{/etc/snmp/snmpd.conf}, @code{master agentx} -directive should be added. In each of the Frr daemons, @code{agentx} -command will enable AgentX support. - -@example -/etc/snmp/snmpd.conf: - # - # example access restrictions setup - # - com2sec readonly default public - group MyROGroup v1 readonly - view all included .1 80 - access MyROGroup "" any noauth exact all none none - # - # enable master agent for AgentX subagents - # - master agentx - -/etc/frr/ospfd.conf: - ! ... the rest of ospfd.conf has been omitted for clarity ... - ! - agentx - ! -@end example - -Upon successful connection, you should get something like this in the -log of each Frr daemons: - -@example -2012/05/25 11:39:08 ZEBRA: snmp[info]: NET-SNMP version 5.4.3 AgentX subagent connected -@end example - -Then, you can use the following command to check everything works as expected: - -@example -# snmpwalk -c public -v1 localhost .1.3.6.1.2.1.14.1.1 -OSPF-MIB::ospfRouterId.0 = IpAddress: 192.168.42.109 -[...] -@end example - -The AgentX protocol can be transported over a Unix socket or using TCP -or UDP. It usually defaults to a Unix socket and depends on how NetSNMP -was built. If need to configure Frr to use another transport, you can -configure it through @code{/etc/snmp/frr.conf}: - -@example -/etc/snmp/frr.conf: - [snmpd] - # Use a remote master agent - agentXSocket tcp:192.168.15.12:705 -@end example - -@node SMUX configuration -@section SMUX configuration - -To enable SMUX protocol support, Frr must have been build with the -@code{--enable-snmp=smux} option. - -A separate connection has then to be established between the -SNMP agent (snmpd) and each of the Frr daemons. This connections -each use different OID numbers and passwords. Be aware that this OID -number is not the one that is used in queries by clients, it is solely -used for the intercommunication of the daemons. - -In the following example the ospfd daemon will be connected to the -snmpd daemon using the password "frr_ospfd". For testing it is -recommending to take exactly the below snmpd.conf as wrong access -restrictions can be hard to debug. - -@example -/etc/snmp/snmpd.conf: - # - # example access restrictions setup - # - com2sec readonly default public - group MyROGroup v1 readonly - view all included .1 80 - access MyROGroup "" any noauth exact all none none - # - # the following line is relevant for Frr - # - smuxpeer .1.3.6.1.4.1.3317.1.2.5 frr_ospfd - -/etc/frr/ospf: - ! ... the rest of ospfd.conf has been omitted for clarity ... - ! - smux peer .1.3.6.1.4.1.3317.1.2.5 frr_ospfd - ! -@end example - -After restarting snmpd and frr, a successful connection can be verified in -the syslog and by querying the SNMP daemon: - -@example -snmpd[12300]: [smux_accept] accepted fd 12 from 127.0.0.1:36255 -snmpd[12300]: accepted smux peer: \ - oid GNOME-PRODUCT-ZEBRA-MIB::ospfd, frr-0.96.5 - -# snmpwalk -c public -v1 localhost .1.3.6.1.2.1.14.1.1 -OSPF-MIB::ospfRouterId.0 = IpAddress: 192.168.42.109 -@end example - -Be warned that the current version (5.1.1) of the Net-SNMP daemon writes a line -for every SNMP connect to the syslog which can lead to enormous log file sizes. -If that is a problem you should consider to patch snmpd and comment out the -troublesome @code{snmp_log()} line in the function -@code{netsnmp_agent_check_packet()} in @code{agent/snmp_agent.c}. - -@node MIB and command reference -@section MIB and command reference - -The following OID numbers are used for the interprocess communication of snmpd and -the Frr daemons with SMUX only. -@example - (OIDs below .iso.org.dod.internet.private.enterprises) -zebra .1.3.6.1.4.1.3317.1.2.1 .gnome.gnomeProducts.zebra.zserv -bgpd .1.3.6.1.4.1.3317.1.2.2 .gnome.gnomeProducts.zebra.bgpd -ripd .1.3.6.1.4.1.3317.1.2.3 .gnome.gnomeProducts.zebra.ripd -ospfd .1.3.6.1.4.1.3317.1.2.5 .gnome.gnomeProducts.zebra.ospfd -ospf6d .1.3.6.1.4.1.3317.1.2.6 .gnome.gnomeProducts.zebra.ospf6d -@end example - -Sadly, SNMP has not been implemented in all daemons yet. The following -OID numbers are used for querying the SNMP daemon by a client: -@example -zebra .1.3.6.1.2.1.4.24 .iso.org.dot.internet.mgmt.mib-2.ip.ipForward -ospfd .1.3.6.1.2.1.14 .iso.org.dot.internet.mgmt.mib-2.ospf -bgpd .1.3.6.1.2.1.15 .iso.org.dot.internet.mgmt.mib-2.bgp -ripd .1.3.6.1.2.1.23 .iso.org.dot.internet.mgmt.mib-2.rip2 -ospf6d .1.3.6.1.3.102 .iso.org.dod.internet.experimental.ospfv3 -@end example - -The following syntax is understood by the Frr daemons for configuring SNMP using SMUX: -@deffn {Command} {smux peer @var{oid}} {} -@deffnx {Command} {no smux peer @var{oid}} {} -@end deffn - -@deffn {Command} {smux peer @var{oid} @var{password}} {} -@deffnx {Command} {no smux peer @var{oid} @var{password}} {} -@end deffn - -Here is the syntax for using AgentX: -@deffn {Command} {agentx} {} -@deffnx {Command} {no agentx} {} -@end deffn - -@include snmptrap.texi diff --git a/doc/snmptrap.texi b/doc/snmptrap.texi deleted file mode 100644 index 0dd3a703af..0000000000 --- a/doc/snmptrap.texi +++ /dev/null @@ -1,205 +0,0 @@ -@c Documentation on configuring Frr and snmpd for SNMP traps -@c contributed by Jeroen Simonetti, jsimonetti@denit.net - -@node Handling SNMP Traps -@section Handling SNMP Traps - -To handle snmp traps make sure your snmp setup of frr works -correctly as described in the frr documentation in @xref{SNMP Support}. - -The BGP4 mib will send traps on peer up/down events. These should be -visible in your snmp logs with a message similar to: - -@samp{snmpd[13733]: Got trap from peer on fd 14} - -To react on these traps they should be handled by a trapsink. Configure -your trapsink by adding the following lines to @file{/etc/snmpd/snmpd.conf}: - -@example - # send traps to the snmptrapd on localhost - trapsink localhost -@end example - -This will send all traps to an snmptrapd running on localhost. You can -of course also use a dedicated management station to catch traps. -Configure the snmptrapd daemon by adding the following line to -@file{/etc/snmpd/snmptrapd.conf}: - -@c Documentation contributed by Jeroen Simonetti, jsimonetti@denit.net - -@example - traphandle .1.3.6.1.4.1.3317.1.2.2 /etc/snmp/snmptrap_handle.sh -@end example - -This will use the bash script @file{/etc/snmp/snmptrap_handle.sh} to handle -the BGP4 traps. To add traps for other protocol daemons, lookup their -appropriate OID from their mib. (For additional information about which -traps are supported by your mib, lookup the mib on -@uref{http://www.oidview.com/mibs/detail.html}). - -Make sure snmptrapd is started. - -The snmptrap_handle.sh script I personally use for handling BGP4 traps -is below. You can of course do all sorts of things when handling traps, -like sound a siren, have your display flash, etc., be creative ;). - -@verbatim - #!/bin/bash - - # routers name - ROUTER=`hostname -s` - - #email address use to sent out notification - EMAILADDR="john@doe.com" - #email address used (allongside above) where warnings should be sent - EMAILADDR_WARN="sms-john@doe.com" - - # type of notification - TYPE="Notice" - - # local snmp community for getting AS belonging to peer - COMMUNITY="" - - # if a peer address is in $WARN_PEERS a warning should be sent - WARN_PEERS="192.0.2.1" - - - # get stdin - INPUT=`cat -` - - # get some vars from stdin - uptime=`echo $INPUT | cut -d' ' -f5` - peer=`echo $INPUT | cut -d' ' -f8 | sed -e 's/SNMPv2-SMI::mib-2.15.3.1.14.//g'` - peerstate=`echo $INPUT | cut -d' ' -f13` - errorcode=`echo $INPUT | cut -d' ' -f9 | sed -e 's/\"//g'` - suberrorcode=`echo $INPUT | cut -d' ' -f10 | sed -e 's/\"//g'` - remoteas=`snmpget -v2c -c $COMMUNITY localhost SNMPv2-SMI::mib-2.15.3.1.9.$peer | cut -d' ' -f4` - - WHOISINFO=`whois -h whois.ripe.net " -r AS$remoteas" | egrep '(as-name|descr)'` - asname=`echo "$WHOISINFO" | grep "^as-name:" | sed -e 's/^as-name://g' -e 's/ //g' -e 's/^ //g' | uniq` - asdescr=`echo "$WHOISINFO" | grep "^descr:" | sed -e 's/^descr://g' -e 's/ //g' -e 's/^ //g' | uniq` - - # if peer address is in $WARN_PEER, the email should also - # be sent to $EMAILADDR_WARN - for ip in $WARN_PEERS; do - if [ "x$ip" == "x$peer" ]; then - EMAILADDR="$EMAILADDR,$EMAILADDR_WARN" - TYPE="WARNING" - break - fi - done - - - # convert peer state - case "$peerstate" in - 1) peerstate="Idle" ;; - 2) peerstate="Connect" ;; - 3) peerstate="Active" ;; - 4) peerstate="Opensent" ;; - 5) peerstate="Openconfirm" ;; - 6) peerstate="Established" ;; - *) peerstate="Unknown" ;; - esac - - # get textual messages for errors - case "$errorcode" in - 00) - error="No error" - suberror="" - ;; - 01) - error="Message Header Error" - case "$suberrorcode" in - 01) suberror="Connection Not Synchronized" ;; - 02) suberror="Bad Message Length" ;; - 03) suberror="Bad Message Type" ;; - *) suberror="Unknown" ;; - esac - ;; - 02) - error="OPEN Message Error" - case "$suberrorcode" in - 01) suberror="Unsupported Version Number" ;; - 02) suberror="Bad Peer AS" ;; - 03) suberror="Bad BGP Identifier" ;; - 04) suberror="Unsupported Optional Parameter" ;; - 05) suberror="Authentication Failure" ;; - 06) suberror="Unacceptable Hold Time" ;; - *) suberror="Unknown" ;; - esac - ;; - 03) - error="UPDATE Message Error" - case "$suberrorcode" in - 01) suberror="Malformed Attribute List" ;; - 02) suberror="Unrecognized Well-known Attribute" ;; - 03) suberror="Missing Well-known Attribute" ;; - 04) suberror="Attribute Flags Error" ;; - 05) suberror="Attribute Length Error" ;; - 06) suberror="Invalid ORIGIN Attribute" ;; - 07) suberror="AS Routing Loop" ;; - 08) suberror="Invalid NEXT_HOP Attribute" ;; - 09) suberror="Optional Attribute Error" ;; - 10) suberror="Invalid Network Field" ;; - 11) suberror="Malformed AS_PATH" ;; - *) suberror="Unknown" ;; - esac - ;; - 04) - error="Hold Timer Expired" - suberror="" - ;; - 05) - error="Finite State Machine Error" - suberror="" - ;; - 06) - error="Cease" - case "$suberrorcode" in - 01) suberror="Maximum Number of Prefixes Reached" ;; - 02) suberror="Administratively Shutdown" ;; - 03) suberror="Peer Unconfigured" ;; - 04) suberror="Administratively Reset" ;; - 05) suberror="Connection Rejected" ;; - 06) suberror="Other Configuration Change" ;; - 07) suberror="Connection collision resolution" ;; - 08) suberror="Out of Resource" ;; - 09) suberror="MAX" ;; - *) suberror="Unknown" ;; - esac - ;; - *) - error="Unknown" - suberror="" - ;; - esac - - # create textual message from errorcodes - if [ "x$suberror" == "x" ]; then - NOTIFY="$errorcode ($error)" - else - NOTIFY="$errorcode/$suberrorcode ($error/$suberror)" - fi - - - # form a decent subject - SUBJECT="$TYPE: $ROUTER [bgp] $peer is $peerstate: $NOTIFY" - # create the email body - MAIL=`cat << EOF - BGP notification on router $ROUTER. - - Peer: $peer - AS: $remoteas - New state: $peerstate - Notification: $NOTIFY - - Info: - $asname - $asdescr - - Snmpd uptime: $uptime - EOF` - - # mail the notification - echo "$MAIL" | mail -s "$SUBJECT" $EMAILADDR -@end verbatim diff --git a/doc/user/.gitignore b/doc/user/.gitignore new file mode 100644 index 0000000000..0505537159 --- /dev/null +++ b/doc/user/.gitignore @@ -0,0 +1,3 @@ +/_templates +/_build +!/Makefile diff --git a/doc/user/Makefile b/doc/user/Makefile new file mode 100644 index 0000000000..056b78e68e --- /dev/null +++ b/doc/user/Makefile @@ -0,0 +1,216 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FRR.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FRR.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/FRR" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FRR" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/user/appendix.rst b/doc/user/appendix.rst new file mode 100644 index 0000000000..334d162c91 --- /dev/null +++ b/doc/user/appendix.rst @@ -0,0 +1,223 @@ +Packet Binary Dump Format +========================= + +Packet Binary Dump Format +------------------------- + +FRR can dump routing protocol packet into file with a binary format +(@pxref{Dump BGP packets and table}). + +It seems to be better that we share the MRT's header format for +backward compatibility with MRT's dump logs. We should also define the +binary format excluding the header, because we must support both IP +v4 and v6 addresses as socket addresses and / or routing entries. + +In the last meeting, we discussed to have a version field in the +header. But Masaki told us that we can define new 'type' value rather +than having a 'version' field, and it seems to be better because we +don't need to change header format. + +Here is the common header format. This is same as that of MRT.:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Time | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Type | Subtype | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +If 'type' is PROTOCOL_BGP4MP_ET, the common header format will +contain an additional microsecond field (RFC6396 2011).:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Time | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Type | Subtype | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Microsecond | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +If 'type' is PROTOCOL_BGP4MP, 'subtype' is BGP4MP_STATE_CHANGE, and +Address Family == IP (version 4):: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source AS number | Destination AS number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Interface Index | Address Family | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Old State | New State | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +Where State is the value defined in RFC1771. + +If 'type' is PROTOCOL_BGP4MP, 'subtype' is BGP4MP_STATE_CHANGE, +and Address Family == IP version 6:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source AS number | Destination AS number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Interface Index | Address Family | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Old State | New State | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +If 'type' is PROTOCOL_BGP4MP, 'subtype' is BGP4MP_MESSAGE, +and Address Family == IP (version 4):: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source AS number | Destination AS number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Interface Index | Address Family | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | BGP Message Packet | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +Where BGP Message Packet is the whole contents of the +BGP4 message including header portion. + +If 'type' is PROTOCOL_BGP4MP, 'subtype' is BGP4MP_MESSAGE, +and Address Family == IP version 6:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source AS number | Destination AS number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Interface Index | Address Family | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Source IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Destination IP address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | BGP Message Packet | + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +If 'type' is PROTOCOL_BGP4MP, 'subtype' is BGP4MP_ENTRY, +and Address Family == IP (version 4):: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | View # | Status | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Time Last Change | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Address Family | SAFI | Next-Hop-Len | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Next Hop Address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Prefix Length | Address Prefix [variable] | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Attribute Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | BGP Attribute [variable length] | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +If 'type' is PROTOCOL_BGP4MP, 'subtype' is BGP4MP_ENTRY, +and Address Family == IP version 6:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | View # | Status | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Time Last Change | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Address Family | SAFI | Next-Hop-Len | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Next Hop Address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Next Hop Address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Next Hop Address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Next Hop Address (Cont'd) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Prefix Length | Address Prefix [variable] | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Address Prefix (cont'd) [variable] | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Attribute Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | BGP Attribute [variable length] | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +BGP4 Attribute must not contain MP_UNREACH_NLRI. If BGP Attribute has +MP_REACH_NLRI field, it must has zero length NLRI, e.g., MP_REACH_NLRI has only +Address Family, SAFI and next-hop values. + +If 'type' is PROTOCOL_BGP4MP and 'subtype' is BGP4MP_SNAPSHOT:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | View # | File Name [variable] | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +The file specified in "File Name" contains all routing entries, +which are in the format of ``subtype == BGP4MP_ENTRY``. + +@example +@group +Constants::: + + /* type value */ + #define MSG_PROTOCOL_BGP4MP 16 + #define MSG_PROTOCOL_BGP4MP_ET 17 + /* subtype value */ + #define BGP4MP_STATE_CHANGE 0 + #define BGP4MP_MESSAGE 1 + #define BGP4MP_ENTRY 2 + #define BGP4MP_SNAPSHOT 3 diff --git a/doc/user/babeld.rst b/doc/user/babeld.rst new file mode 100644 index 0000000000..926b453e53 --- /dev/null +++ b/doc/user/babeld.rst @@ -0,0 +1,265 @@ +.. _Babel: + +***** +Babel +***** + +Babel is an interior gateway protocol that is suitable both for wired +networks and for wireless mesh networks. Babel has been described as +'RIP on speed' --- it is based on the same principles as RIP, but +includes a number of refinements that make it react much faster to +topology changes without ever counting to infinity, and allow it to +perform reliable link quality estimation on wireless links. Babel is +a double-stack routing protocol, meaning that a single Babel instance +is able to perform routing for both IPv4 and IPv6. + +FRR implements Babel as described in RFC6126. + +.. _Configuring_babeld: + +Configuring babeld +================== + +The *babeld* daemon can be invoked with any of the common +options (:ref:`Common_Invocation_Options`). + +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`. + +.. _Babel_configuration: + +Babel configuration +=================== + +.. index:: Command {router babel} {} + +Command {router babel} {} +.. index:: Command {no router babel} {} + +Command {no router babel} {} + Enable or disable Babel routing. + +.. index:: Command {babel resend-delay <20-655340>} {} + +Command {babel resend-delay <20-655340>} {} + Specifies the time after which important messages are resent when + avoiding a black-hole. The default is 2000@dmn{ms}. + +.. index:: Command {babel diversity} {} + +Command {babel diversity} {} +.. index:: Command {no babel diversity} {} + +Command {no babel diversity} {} + Enable or disable routing using radio frequency diversity. This is + highly recommended in networks with many wireless nodes. + + If you enable this, you will probably want to set `babel diversity-factor` and `babel channel` below. + +.. index:: Command {babel diversity-factor <1-256>} {} + +Command {babel diversity-factor <1-256>} {} + Sets the multiplicative factor used for diversity routing, in units of + 1/256; lower values cause diversity to play a more important role in + route selection. The default it 256, which means that diversity plays + no role in route selection; you will probably want to set that to 128 + or less on nodes with multiple independent radios. + +.. index:: {Babel Command} {network `ifname`} {} + +{Babel Command} {network `ifname`} {} +.. index:: {Babel Command} {no network `ifname`} {} + +{Babel Command} {no network `ifname`} {} + Enable or disable Babel on the given interface. + +.. index:: {Interface Command} {babel wired} {} + +{Interface Command} {babel wired} {} +.. index:: {Interface Command} {babel wireless} {} + +{Interface Command} {babel wireless} {} + Specifies whether this interface is wireless, which disables a number + of optimisations that are only correct on wired interfaces. + Specifying `wireless` (the default) is always correct, but may + cause slower convergence and extra routing traffic. + +.. index:: {Interface Command} {babel split-horizon} + +{Interface Command} {babel split-horizon} +.. index:: {Interface Command} {no babel split-horizon} + +{Interface Command} {no babel split-horizon} + Specifies whether to perform split-horizon on the interface. + Specifying `no babel split-horizon` is always correct, while + `babel split-horizon` is an optimisation that should only be used + on symmetric and transitive (wired) networks. The default is + `babel split-horizon` on wired interfaces, and `no babel split-horizon` on wireless interfaces. This flag is reset when the + wired/wireless status of an interface is changed. + +.. index:: {Interface Command} {babel hello-interval <20-655340>} + +{Interface Command} {babel hello-interval <20-655340>} + Specifies the time in milliseconds between two scheduled hellos. On + wired links, Babel notices a link failure within two hello intervals; + on wireless links, the link quality value is reestimated at every + hello interval. The default is 4000@dmn{ms}. + +.. index:: {Interface Command} {babel update-interval <20-655340>} + +{Interface Command} {babel update-interval <20-655340>} + Specifies the time in milliseconds between two scheduled updates. + Since Babel makes extensive use of triggered updates, this can be set + to fairly high values on links with little packet loss. The default + is 20000@dmn{ms}. + +.. index:: {Interface Command} {babel channel <1-254>} + +{Interface Command} {babel channel <1-254>} +.. index:: {Interface Command} {babel channel interfering} + +{Interface Command} {babel channel interfering} +.. index:: {Interface Command} {babel channel noninterfering} + +{Interface Command} {babel channel noninterfering} + Set the channel number that diversity routing uses for this interface + (see `babel diversity` above). Noninterfering interfaces are + assumed to only interfere with themselves, interfering interfaces are + assumed to interfere with all other channels except noninterfering + channels, and interfaces with a channel number interfere with + interfering interfaces and interfaces with the same channel number. + The default is @samp{babel channel interfering} for wireless + interfaces, and @samp{babel channel noninterfering} for wired + interfaces. This is reset when the wired/wireless status of an + interface is changed. + +.. index:: {Interface Command} {babel rxcost <1-65534>} + +{Interface Command} {babel rxcost <1-65534>} + Specifies the base receive cost for this interface. For wireless + interfaces, it specifies the multiplier used for computing the ETX + reception cost (default 256); for wired interfaces, it specifies the + cost that will be advertised to neighbours. This value is reset when + the wired/wireless attribute of the interface is changed. + + Do not use this command unless you know what you are doing; in most + networks, acting directly on the cost using route maps is a better + technique. + +.. index:: {Interface Command} {babel rtt-decay <1-256>} + +{Interface Command} {babel rtt-decay <1-256>} + This specifies the decay factor for the exponential moving average of + RTT samples, in units of 1/256. Higher values discard old samples + faster. The default is 42. + +.. index:: {Interface Command} {babel rtt-min <1-65535>} + +{Interface Command} {babel rtt-min <1-65535>} + This specifies the minimum RTT, in milliseconds, starting from which we + increase the cost to a neighbour. The additional cost is linear in (rtt + - rtt-min ). The default is 10@dmn{ms}. + +.. index:: {Interface Command} {babel rtt-max <1-65535>} + +{Interface Command} {babel rtt-max <1-65535>} + This specifies the maximum RTT, in milliseconds, above which we don't + increase the cost to a neighbour. The default is 120@dmn{ms}. + +.. index:: {Interface Command} {babel max-rtt-penalty <0-65535>} + +{Interface Command} {babel max-rtt-penalty <0-65535>} + This specifies the maximum cost added to a neighbour because of RTT, + i.e. when the RTT is higher or equal than rtt-max. The default is 0, + which effectively disables the use of a RTT-based cost. + +.. index:: {Interface Command} {babel enable-timestamps} + +{Interface Command} {babel enable-timestamps} +.. index:: {Interface Command} {no babel enable-timestamps} + +{Interface Command} {no babel enable-timestamps} + Enable or disable sending timestamps with each Hello and IHU message in + order to compute RTT values. The default is `no babel enable-timestamps`. + +.. index:: {Babel Command} {babel resend-delay <20-655340>} + +{Babel Command} {babel resend-delay <20-655340>} + Specifies the time in milliseconds after which an 'important' + request or update will be resent. The default is 2000@dmn{ms}. You + probably don't want to tweak this value. + +.. index:: {Babel Command} {babel smoothing-half-life <0-65534>} + +{Babel Command} {babel smoothing-half-life <0-65534>} + Specifies the time constant, in seconds, of the smoothing algorithm + used for implementing hysteresis. Larger values reduce route + oscillation at the cost of very slightly increasing convergence time. + The value 0 disables hysteresis, and is suitable for wired networks. + The default is 4@dmn{s}. + +.. _Babel_redistribution: + +Babel redistribution +==================== + +.. index:: {Babel command} {redistribute `` `kind`} + +{Babel command} {redistribute `` `kind`} +.. index:: {Babel command} {no redistribute `` `kind`} + +{Babel command} {no redistribute `` `kind`} + Specify which kind of routes should be redistributed into Babel. + +.. _Show_Babel_information: + +Show Babel information +====================== + +.. index:: {Command} {show babel route} {} + +{Command} {show babel route} {} +.. index:: {Command} {show babel route A.B.C.D} + +{Command} {show babel route A.B.C.D} +.. index:: {Command} {show babel route X:X::X:X} + +{Command} {show babel route X:X::X:X} +.. index:: {Command} {show babel route A.B.C.D/M} + +{Command} {show babel route A.B.C.D/M} +.. index:: {Command} {show babel route X:X::X:X/M} + +{Command} {show babel route X:X::X:X/M} +.. index:: {Command} {show babel interface} {} + +{Command} {show babel interface} {} +.. index:: {Command} {show babel interface `ifname`} {} + +{Command} {show babel interface `ifname`} {} +.. index:: {Command} {show babel neighbor} {} + +{Command} {show babel neighbor} {} +.. index:: {Command} {show babel parameters} {} + +{Command} {show babel parameters} {} + These commands dump various parts of *babeld*'s internal state. + +Babel debugging commands +======================== + +.. index:: {Babel Command} {debug babel `kind`} {} + +{Babel Command} {debug babel `kind`} {} +.. index:: {Babel Command} {no debug babel `kind`} {} + +{Babel Command} {no debug babel `kind`} {} + Enable or disable debugging messages of a given kind. `kind` can + be one of @samp{common}, @samp{kernel}, @samp{filter}, @samp{timeout}, + @samp{interface}, @samp{route} or @samp{all}. Note that if you have + compiled with the NO_DEBUG flag, then these commands aren't available. + diff --git a/doc/user/basic.rst b/doc/user/basic.rst new file mode 100644 index 0000000000..505de59547 --- /dev/null +++ b/doc/user/basic.rst @@ -0,0 +1,706 @@ +.. _Basic_commands: + +************** +Basic commands +************** + +There are five routing daemons in use, and there is one manager daemon. +These daemons may be located on separate machines from the manager +daemon. Each of these daemons will listen on a particular port for +incoming VTY connections. The routing daemons are: + +* *ripd*, *ripngd*, *ospfd*, *ospf6d*, *bgpd* +* *zebra* + +The following sections discuss commands common to all the routing +daemons. + +.. _Config_Commands: + +Config Commands +=============== + +.. index:: Configuration files for running the software + +.. index:: Files for running configurations + +.. index:: Modifying the herd's behavior + +.. index:: Getting the herd running + +In a 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: + +* :file:`@value{INSTALL_PREFIX_ETC}`/\*.conf + +Each of the daemons has its own +config file. For example, zebra's default config file name is: + +* :file:`@value{INSTALL_PREFIX_ETC`/zebra.conf} + +The daemon name plus :file:`.conf` is the default config file name. You +can specify a config file using the @kbd{-f} or @kbd{--config-file} +options when starting the daemon. + +.. _Basic_Config_Commands: + +Basic Config Commands +--------------------- + +.. index:: Command {hostname `hostname`} {} + +Command {hostname `hostname`} {} + Set hostname of the router. + +.. index:: Command {password `password`} {} + +Command {password `password`} {} + Set password for vty interface. If there is no password, a vty won't + accept connections. + +.. index:: Command {enable password `password`} {} + +Command {enable password `password`} {} + Set enable password. + +.. index:: Command {log trap `level`} {} + +Command {log trap `level`} {} +.. index:: Command {no log trap} {} + +Command {no log trap} {} + These commands are deprecated and are present only for historical compatibility. + The log trap command sets the current logging level for all enabled + logging destinations, and it sets the default for all future logging commands + that do not specify a level. The normal default + logging level is debugging. The `no` form of the command resets + the default level for future logging commands to debugging, but it does + not change the logging level of existing logging destinations. + +.. index:: Command {log stdout} {} + +Command {log stdout} {} +.. index:: Command {log stdout `level`} {} + +Command {log stdout `level`} {} +.. index:: Command {no log stdout} {} + +Command {no log stdout} {} + Enable logging output to stdout. + If the optional second argument specifying the + logging level is not present, the default logging level (typically debugging, + but can be changed using the deprecated `log trap` command) will be used. + The `no` form of the command disables logging to stdout. + The `level` argument must have one of these values: + emergencies, alerts, critical, errors, warnings, notifications, informational, or debugging. Note that the existing code logs its most important messages + with severity `errors`. + +.. index:: Command {log file `filename`} {} + +Command {log file `filename`} {} +.. index:: Command {log file `filename` `level`} {} + +Command {log file `filename` `level`} {} +.. index:: Command {no log file} {} + +Command {no log file} {} + If you want to log into a file, please specify `filename` as + in this example:: + + log file /var/log/frr/bgpd.log informational + + If the optional second argument specifying the + logging level is not present, the default logging level (typically debugging, + but can be changed using the deprecated `log trap` command) will be used. + The `no` form of the command disables logging to a file. + + Note: if you do not configure any file logging, and a daemon crashes due + to a signal or an assertion failure, it will attempt to save the crash + information in a file named /var/tmp/frr..crashlog. + For security reasons, this will not happen if the file exists already, so + it is important to delete the file after reporting the crash information. + +.. index:: Command {log syslog} {} + +Command {log syslog} {} +.. index:: Command {log syslog `level`} {} + +Command {log syslog `level`} {} +.. index:: Command {no log syslog} {} + +Command {no log syslog} {} + Enable logging output to syslog. + If the optional second argument specifying the + logging level is not present, the default logging level (typically debugging, + but can be changed using the deprecated `log trap` command) will be used. + The `no` form of the command disables logging to syslog. + +.. index:: Command {log monitor} {} + +Command {log monitor} {} +.. index:: Command {log monitor `level`} {} + +Command {log monitor `level`} {} +.. index:: Command {no log monitor} {} + +Command {no log monitor} {} + Enable logging output to vty terminals that have enabled logging + using the `terminal monitor` command. + By default, monitor logging is enabled at the debugging level, but this + command (or the deprecated `log trap` command) can be used to change + the monitor logging level. + If the optional second argument specifying the + logging level is not present, the default logging level (typically debugging, + but can be changed using the deprecated `log trap` command) will be used. + The `no` form of the command disables logging to terminal monitors. + +.. index:: Command {log facility `facility`} {} + +Command {log facility `facility`} {} +.. index:: Command {no log facility} {} + +Command {no log facility} {} + This command changes the facility used in syslog messages. The default + facility is `daemon`. The `no` form of the command resets + the facility to the default `daemon` facility. + +.. index:: Command {log record-priority} {} + +Command {log record-priority} {} +.. index:: Command {no log record-priority} {} + +Command {no log record-priority} {} + To include the severity in all messages logged to a file, to stdout, or to + a terminal monitor (i.e. anything except syslog), + use the `log record-priority` global configuration command. + To disable this option, use the `no` form of the command. By default, + the severity level is not included in logged messages. Note: some + versions of syslogd (including Solaris) can be configured to include + the facility and level in the messages emitted. + +.. index:: Command {log timestamp precision `<0-6>`} {} + +Command {log timestamp precision `<0-6>`} {} +.. index:: Command {no log timestamp precision} {} + +Command {no log timestamp precision} {} + This command sets the precision of log message timestamps to the + given number of digits after the decimal point. Currently, + the value must be in the range 0 to 6 (i.e. the maximum precision + is microseconds). + To restore the default behavior (1-second accuracy), use the + `no` form of the command, or set the precision explicitly to 0. + +:: + + @group + log timestamp precision 3 + @end group + + + In this example, the precision is set to provide timestamps with + millisecond accuracy. + +.. index:: Command {log commands} {} + +Command {log commands} {} + This command enables the logging of all commands typed by a user to + all enabled log destinations. The note that logging includes full + command lines, including passwords. Once set, command logging can only + be turned off by restarting the daemon. + +.. index:: Command {service password-encryption} {} + +Command {service password-encryption} {} + Encrypt password. + +.. index:: Command {service advanced-vty} {} + +Command {service advanced-vty} {} + Enable advanced mode VTY. + +.. index:: Command {service terminal-length `<0-512>`} {} + +Command {service terminal-length `<0-512>`} {} + Set system wide line configuration. This configuration command applies + to all VTY interfaces. + +.. index:: Command {line vty} {} + +Command {line vty} {} + Enter vty configuration mode. + +.. index:: Command {banner motd default} {} + +Command {banner motd default} {} + Set default motd string. + +.. index:: Command {no banner motd} {} + +Command {no banner motd} {} + No motd banner string will be printed. + +.. index:: {Line Command} {exec-timeout `minute`} {} + +{Line Command} {exec-timeout `minute`} {} +.. index:: {Line Command} {exec-timeout `minute` `second`} {} + +{Line Command} {exec-timeout `minute` `second`} {} + Set VTY connection timeout value. When only one argument is specified + it is used for timeout value in minutes. Optional second argument is + used for timeout value in seconds. Default timeout value is 10 minutes. + When timeout value is zero, it means no timeout. + +.. index:: {Line Command} {no exec-timeout} {} + +{Line Command} {no exec-timeout} {} + Do not perform timeout at all. This command is as same as + *exec-timeout 0 0*. + +.. index:: {Line Command} {access-class `access-list`} {} + +{Line Command} {access-class `access-list`} {} + Restrict vty connections with an access list. + +.. _Sample_Config_File: + +Sample Config File +------------------ + +Below is a sample configuration file for the zebra daemon. + +:: + + @group + ! + ! Zebra configuration file + ! + hostname Router + password zebra + enable password zebra + ! + log stdout + ! + ! + @end group + + +'!' and '#' are comment characters. If the first character of the word +is one of the comment characters then from the rest of the line forward +will be ignored as a comment. + +:: + + password zebra!password + + +If a comment character is not the first character of the word, it's a +normal character. So in the above example '!' will not be regarded as a +comment and the password is set to 'zebra!password'. + +.. _Terminal_Mode_Commands: + +Terminal Mode Commands +====================== + +.. index:: Command {write terminal} {} + +Command {write terminal} {} + Displays the current configuration to the vty interface. + +.. index:: Command {write file} {} + +Command {write file} {} + Write current configuration to configuration file. + +.. index:: Command {configure terminal} {} + +Command {configure terminal} {} + Change to configuration mode. This command is the first step to + configuration. + +.. index:: Command {terminal length `<0-512>`} {} + +Command {terminal length `<0-512>`} {} + Set terminal display length to `<0-512>`. If length is 0, no + display control is performed. + +.. index:: Command {who} {} + +Command {who} {} + Show a list of currently connected vty sessions. + +.. index:: Command {list} {} + +Command {list} {} + List all available commands. + +.. index:: Command {show version} {} + +Command {show version} {} + Show the current version of @value{PACKAGE_NAME} and its build host information. + +.. index:: Command {show logging} {} + +Command {show logging} {} + Shows the current configuration of the logging system. This includes + the status of all logging destinations. + +.. index:: Command {logmsg `level` `message`} {} + +Command {logmsg `level` `message`} {} + Send a message to all logging destinations that are enabled for messages + of the given severity. + +.. _Common_Invocation_Options: + +Common Invocation Options +========================= + +These options apply to all @value{PACKAGE_NAME} daemons. + + + +*-d* + +*--daemon* + Runs in daemon mode. + + +*-f `file`* + +*--config_file=`file`* + Set configuration file name. + + +*-h* + +*--help* + Display this help and exit. + + +*-i `file`* + +*--pid_file=`file`* + Upon startup the process identifier of the daemon is written to a file, + typically in :file:`/var/run`. This file can be used by the init system + to implement commands such as *.../init.d/zebra status*, + *.../init.d/zebra restart* or @command{.../init.d/zebra + stop}. + + The file name is an run-time option rather than a configure-time option + so that multiple routing daemons can be run simultaneously. This is + useful when using @value{PACKAGE_NAME} to implement a routing looking glass. One + machine can be used to collect differing routing views from differing + points in the network. + + +*-A `address`* + +*--vty_addr=`address`* + Set the VTY local address to bind to. If set, the VTY socket will only + be bound to this address. + + +*-P `port`* + +*--vty_port=`port`* + Set the VTY TCP port number. If set to 0 then the TCP VTY sockets will not + be opened. + + +*-u `user`* + +*--vty_addr=`user`* + Set the user and group to run as. + + +*-v* + +*--version* + Print program version. + + +.. _Loadable_Module_Support: + +Loadable Module Support +======================= + +FRR supports loading extension modules at startup. Loading, reloading or +unloading modules at runtime is not supported (yet). To load a module, use +the following command line option at daemon startup: + + + +*-M `module:options`* + +*--module `module:options`* + Load the specified module, optionally passing options to it. If the module + name contains a slash (/), it is assumed to be a full pathname to a file to + be loaded. If it does not contain a slash, the + `@value{INSTALL_PREFIX_MODULES`} directory is searched for a module of + the given name; first with the daemon name prepended (e.g. `zebra_mod` + for `mod`), then without the daemon name prepended. + + This option is available on all daemons, though some daemons may not have + any modules available to be loaded. + +The SNMP Module +--------------- + +If SNMP is enabled during compile-time and installed as part of the package, +the `snmp` module can be loaded for the *zebra*, +*bgpd*, *ospfd*, *ospf6d* and *ripd* daemons. + +The module ignores any options passed to it. Refer to :ref:`SNMP_Support` +for information on its usage. + +The FPM Module +-------------- + +If FPM is enabled during compile-time and installed as part of the package, +the `fpm` module can be loaded for the *zebra* daemon. This +provides the Forwarding Plane Manager ("FPM") API. + +The module expects its argument to be either `netlink` or +`protobuf`, specifying the encapsulation to use. `netlink` is the +default, and `protobuf` may not be available if the module was built +without protobuf support. Refer to :ref:`zebra_FIB_push_interface` for more +information. + +.. _Virtual_Terminal_Interfaces: + +Virtual Terminal Interfaces +=========================== + +VTY -- Virtual Terminal [aka TeletYpe] Interface is a command line +interface (CLI) for user interaction with the routing daemon. + +.. _VTY_Overview: + +VTY Overview +------------ + +VTY stands for Virtual TeletYpe interface. It means you can connect to +the daemon via the telnet protocol. + +To enable a VTY interface, you have to setup a VTY password. If there +is no VTY password, one cannot connect to the VTY interface at all. + +:: + + @group + % telnet localhost 2601 + Trying 127.0.0.1... + Connected to localhost. + Escape character is '^]'. + + Hello, this is @value{PACKAGE_NAME} (version @value{PACKAGE_VERSION}) + @value{COPYRIGHT_STR} + + User Access Verification + + Password: XXXXX + Router> ? + enable Turn on privileged commands + exit Exit current mode and down to previous mode + help Description of the interactive help system + list Print command list + show Show running system information + who Display who is on a vty + Router> enable + Password: XXXXX + Router# configure terminal + Router(config)# interface eth0 + Router(config-if)# ip address 10.0.0.1/8 + Router(config-if)# ^Z + Router# + @end group + + +'?' is very useful for looking up commands. + +.. _VTY_Modes: + +VTY Modes +--------- + +There are three basic VTY modes: + +There are commands that may be restricted to specific VTY modes. + +.. _VTY_View_Mode: + +VTY View Mode +^^^^^^^^^^^^^ + +This mode is for read-only access to the CLI. One may exit the mode by +leaving the system, or by entering `enable` mode. + +.. _VTY_Enable_Mode: + +VTY Enable Mode +^^^^^^^^^^^^^^^ + +This mode is for read-write access to the CLI. One may exit the mode by +leaving the system, or by escaping to view mode. + +.. _VTY_Other_Modes: + +VTY Other Modes +^^^^^^^^^^^^^^^ + +This page is for describing other modes. + +.. _VTY_CLI_Commands: + +VTY CLI Commands +---------------- + +Commands that you may use at the command-line are described in the following +three subsubsections. + +.. _CLI_Movement_Commands: + +CLI Movement Commands +^^^^^^^^^^^^^^^^^^^^^ + +These commands are used for moving the CLI cursor. The :kbd:`C` character +means press the Control Key. + + + +*C-f* + +*:kbd:`RIGHT`* + @kindex C-f + @kindex :kbd:`RIGHT` + Move forward one character. + + +*C-b* + +*:kbd:`LEFT`* + @kindex C-b + @kindex :kbd:`LEFT` + Move backward one character. + + +*M-f* + @kindex M-f + Move forward one word. + + +*M-b* + @kindex M-b + Move backward one word. + + +*C-a* + @kindex C-a + Move to the beginning of the line. + + +*C-e* + @kindex C-e + Move to the end of the line. + + +.. _CLI_Editing_Commands: + +CLI Editing Commands +^^^^^^^^^^^^^^^^^^^^ + +These commands are used for editing text on a line. The :kbd:`C` +character means press the Control Key. + + + +*C-h* + +*:kbd:`DEL`* + @kindex C-h + @kindex :kbd:`DEL` + Delete the character before point. + + +*C-d* + @kindex C-d + Delete the character after point. + + +*M-d* + @kindex M-d + Forward kill word. + + +*C-w* + @kindex C-w + Backward kill word. + + +*C-k* + @kindex C-k + Kill to the end of the line. + + +*C-u* + @kindex C-u + Kill line from the beginning, erasing input. + + +*C-t* + @kindex C-t + Transpose character. + + +CLI Advanced Commands +^^^^^^^^^^^^^^^^^^^^^ + +There are several additional CLI commands for command line completions, +insta-help, and VTY session management. + + + +*C-c* + @kindex C-c + Interrupt current input and moves to the next line. + + +*C-z* + @kindex C-z + End current configuration session and move to top node. + + +*C-n* + +*:kbd:`DOWN`* + @kindex C-n + @kindex :kbd:`DOWN` + Move down to next line in the history buffer. + + +*C-p* + +*:kbd:`UP`* + @kindex C-p + @kindex :kbd:`UP` + Move up to previous line in the history buffer. + + +*TAB* + @kindex :kbd:`TAB` + Use command line completion by typing :kbd:`TAB`. + + +*?* + @kindex :kbd:`?` + You can use command line help by typing `help` at the beginning of + the line. Typing @kbd{?} at any point in the line will show possible + completions. + + diff --git a/doc/user/bgp.rst b/doc/user/bgp.rst new file mode 100644 index 0000000000..81c55805be --- /dev/null +++ b/doc/user/bgp.rst @@ -0,0 +1,2392 @@ +.. _BGP: + +*** +BGP +*** + +@acronym{BGP} stands for a Border Gateway Protocol. The lastest BGP version +is 4. It is referred as BGP-4. BGP-4 is one of the Exterior Gateway +Protocols and de-fact standard of Inter Domain routing protocol. +BGP-4 is described in @cite{RFC1771, A Border Gateway Protocol +4 (BGP-4)}. + +Many extensions have been added to @cite{RFC1771}. @cite{RFC2858, +Multiprotocol Extensions for BGP-4} provides multiprotocol support to +BGP-4. + +.. _Starting_BGP: + +Starting BGP +============ + +Default configuration file of *bgpd* is :file:`bgpd.conf`. +*bgpd* searches the current directory first then +@value{INSTALL_PREFIX_ETC}/bgpd.conf. All of bgpd's command must be +configured in :file:`bgpd.conf`. + +*bgpd* specific invocation options are described below. Common +options may also be specified (:ref:`Common_Invocation_Options`). + + + +*-p `PORT`* + +*--bgp_port=`PORT`* + Set the bgp protocol's port number. + + +*-r* + +*--retain* + When program terminates, retain BGP routes added by zebra. + + +*-l* + +*--listenon* + Specify a specific IP address for bgpd to listen on, rather than its + default of INADDR_ANY / IN6ADDR_ANY. This can be useful to constrain bgpd + to an internal address, or to run multiple bgpd processes on one host. + + +.. _BGP_router: + +BGP router +========== + +First of all you must configure BGP router with *router bgp* +command. To configure BGP router, you need AS number. AS number is an +identification of autonomous system. BGP protocol uses the AS number +for detecting whether the BGP connection is internal one or external one. + +.. index:: Command {router bgp `asn`} {} + +Command {router bgp `asn`} {} + Enable a BGP protocol process with the specified `asn`. After + this statement you can input any `BGP Commands`. You can not + create different BGP process under different `asn` without + specifying `multiple-instance` (:ref:`Multiple_instance`). + +.. index:: Command {no router bgp `asn`} {} + +Command {no router bgp `asn`} {} + Destroy a BGP protocol process with the specified `asn`. + +.. index:: {BGP} {bgp router-id `A.B.C.D`} {} + +{BGP} {bgp router-id `A.B.C.D`} {} + This command specifies the router-ID. If *bgpd* connects to *zebra* it gets + interface and address information. In that case default router ID value + is selected as the largest IP Address of the interfaces. When + `router zebra` is not enabled *bgpd* can't get interface information + so `router-id` is set to 0.0.0.0. So please set router-id by hand. + +.. _BGP_distance: + +BGP distance +------------ + +.. index:: {BGP} {distance bgp <1-255> <1-255> <1-255>} {} + +{BGP} {distance bgp <1-255> <1-255> <1-255>} {} + This command change distance value of BGP. Each argument is distance + value for external routes, internal routes and local routes. + +.. index:: {BGP} {distance <1-255> `A.B.C.D/M`} {} + +{BGP} {distance <1-255> `A.B.C.D/M`} {} +.. index:: {BGP} {distance <1-255> `A.B.C.D/M` `word`} {} + +{BGP} {distance <1-255> `A.B.C.D/M` `word`} {} + This command set distance value to + +.. _BGP_decision_process: + +BGP decision process +-------------------- + +The decision process Frr BGP uses to select routes is as follows: + + + +*1. Weight check* + prefer higher local weight routes to lower routes. + + +*2. Local preference check* + prefer higher local preference routes to lower. + + +*3. Local route check* + Prefer local routes (statics, aggregates, redistributed) to received routes. + + +*4. AS path length check* + Prefer shortest hop-count AS_PATHs. + + +*5. Origin check* + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + + +*6. MED check* + Where routes with a MED were received from the same AS, + prefer the route with the lowest MED. :ref:`BGP_MED`. + + +*7. External check* + Prefer the route received from an external, eBGP peer + over routes received from other types of peers. + + +*8. IGP cost check* + Prefer the route with the lower IGP cost. + + +*9. Multi-path check* + If multi-pathing is enabled, then check whether + the routes not yet distinguished in preference may be considered equal. If + :ref:`bgp_bestpath_as-path_multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + + +*10 Already-selected external check* + Where both routes were received from eBGP peers, then prefer the route which + is already selected. Note that this check is not applied if :ref:`bgp_bestpath_compare-routerid` is configured. This check can prevent some cases + of oscillation. + + +*11. Router-ID check* + Prefer the route with the lowest @w{router-ID}. If the + route has an @w{ORIGINATOR_ID} attribute, through iBGP reflection, then that + router ID is used, otherwise the @w{router-ID} of the peer the route was + received from is used. + + +*12. Cluster-List length check* + The route with the shortest cluster-list + length is used. The cluster-list reflects the iBGP reflection path the + route has taken. + + +*13. Peer address* + Prefer the route received from the peer with the higher + transport layer address, as a last-resort tie-breaker. + + +.. index:: {BGP} {bgp bestpath as-path confed} {} + +{BGP} {bgp bestpath as-path confed} {} + This command specifies that the length of confederation path sets and + sequences should should be taken into account during the BGP best path + decision process. + +.. index:: {BGP} {bgp bestpath as-path multipath-relax} {} + +{BGP} {bgp bestpath as-path multipath-relax} {} + .. _bgp_bestpath_as-path_multipath-relax: + + This command specifies that BGP decision process should consider paths + of equal AS_PATH length candidates for multipath computation. Without + the knob, the entire AS_PATH must match for multipath computation. + +.. index:: {BGP} {bgp bestpath compare-routerid} {} + +{BGP} {bgp bestpath compare-routerid} {} + .. _bgp_bestpath_compare-routerid: + + Ensure that when comparing routes where both are equal on most metrics, + including local-pref, AS_PATH length, IGP cost, MED, that the tie is broken + based on router-ID. + + If this option is enabled, then the already-selected check, where + already selected eBGP routes are preferred, is skipped. + + If a route has an @w{ORIGINATOR_ID} attribute because it has been reflected, + that @w{ORIGINATOR_ID} will be used. Otherwise, the router-ID of the peer the + route was received from will be used. + + The advantage of this is that the route-selection (at this point) will be + more deterministic. The disadvantage is that a few or even one lowest-ID + router may attract all trafic to otherwise-equal paths because of this + check. It may increase the possibility of MED or IGP oscillation, unless + other measures were taken to avoid these. The exact behaviour will be + sensitive to the iBGP and reflection topology. + + +.. _BGP_route_flap_dampening: + +BGP route flap dampening +------------------------ + +.. index:: {BGP} {bgp dampening `<1-45>` `<1-20000>` `<1-20000>` `<1-255>`} {} + +{BGP} {bgp dampening `<1-45>` `<1-20000>` `<1-20000>` `<1-255>`} {} + This command enables BGP route-flap dampening and specifies dampening parameters. + + + +*@asis{half-life}* + Half-life time for the penalty + +*@asis{reuse-threshold}* + Value to start reusing a route + +*@asis{suppress-threshold}* + Value to start suppressing a route + +*@asis{max-suppress}* + Maximum duration to suppress a stable route + + The route-flap damping algorithm is compatible with @cite{RFC2439}. The use of this command + is not recommended nowadays, see `http://www.ripe.net/ripe/docs/ripe-378,,RIPE-378 `_. + +.. _BGP_MED: + +BGP MED +======= + +The BGP MED (Multi_Exit_Discriminator) attribute has properties which can +cause subtle convergence problems in BGP. These properties and problems +have proven to be hard to understand, at least historically, and may still +not be widely understood. The following attempts to collect together and +present what is known about MED, to help operators and Frr users in +designing and configuring their networks. + +The BGP @acronym{MED, Multi_Exit_Discriminator} attribute is intended to +allow one AS to indicate its preferences for its ingress points to another +AS. The MED attribute will not be propagated on to another AS by the +receiving AS - it is 'non-transitive' in the BGP sense. + +E.g., if AS X and AS Y have 2 different BGP peering points, then AS X +might set a MED of 100 on routes advertised at one and a MED of 200 at the +other. When AS Y selects between otherwise equal routes to or via +AS X, AS Y should prefer to take the path via the lower MED peering of 100 with +AS X. Setting the MED allows an AS to influence the routing taken to it +within another, neighbouring AS. + +In this use of MED it is not really meaningful to compare the MED value on +routes where the next AS on the paths differs. E.g., if AS Y also had a +route for some destination via AS Z in addition to the routes from AS X, and +AS Z had also set a MED, it wouldn't make sense for AS Y to compare AS Z's +MED values to those of AS X. The MED values have been set by different +administrators, with different frames of reference. + +The default behaviour of BGP therefore is to not compare MED values across +routes received from different neighbouring ASes. In Frr this is done by +comparing the neighbouring, left-most AS in the received AS_PATHs of the +routes and only comparing MED if those are the same. + +@ifnottex +@macro mprec{} +@math{<} +@end macro +@end ifnottex + +Unfortunately, this behaviour of MED, of sometimes being compared across +routes and sometimes not, depending on the properties of those other routes, +means MED can cause the order of preference over all the routes to be +undefined. That is, given routes A, B, and C, if A is preferred to B, and B +is preferred to C, then a well-defined order should mean the preference is +transitive (in the sense of orders @footnote{For some set of objects to have +an order, there *must* be some binary ordering relation that is defined +for *every* combination of those objects, and that relation *must* +be transitive. I.e.@:, if the relation operator is @mprec{}, and if +a @mprec{} b and b @mprec{} c then that relation must carry over +and it *must* be that a @mprec{} c for the objects to have an +order. The ordering relation may allow for equality, i.e. +a @mprec{} b and b @mprec{} a may both be true amd imply that +a and b are equal in the order and not distinguished by it, in +which case the set has a partial order. Otherwise, if there is an order, +all the objects have a distinct place in the order and the set has a total +order.}) and that A would be preferred to C. + +However, when MED is involved this need not be the case. With MED it is +possible that C is actually preferred over A. So A is preferred to B, B is +preferred to C, but C is preferred to A. This can be true even where BGP +defines a deterministic 'most preferred' route out of the full set of +A,B,C. With MED, for any given set of routes there may be a +deterministically preferred route, but there need not be any way to arrange +them into any order of preference. With unmodified MED, the order of +preference of routes literally becomes undefined. + +That MED can induce non-transitive preferences over routes can cause issues. +Firstly, it may be perceived to cause routing table churn locally at +speakers; secondly, and more seriously, it may cause routing instability in +iBGP topologies, where sets of speakers continually oscillate between +different paths. + +The first issue arises from how speakers often implement routing decisions. +Though BGP defines a selection process that will deterministically select +the same route as best at any given speaker, even with MED, that process +requires evaluating all routes together. For performance and ease of +implementation reasons, many implementations evaluate route preferences in a +pair-wise fashion instead. Given there is no well-defined order when MED is +involved, the best route that will be chosen becomes subject to +implementation details, such as the order the routes are stored in. That +may be (locally) non-deterministic, e.g.@: it may be the order the routes +were received in. + +This indeterminism may be considered undesirable, though it need not cause +problems. It may mean additional routing churn is perceived, as sometimes +more updates may be produced than at other times in reaction to some event . + +This first issue can be fixed with a more deterministic route selection that +ensures routes are ordered by the neighbouring AS during selection. +:ref:`bgp_deterministic-med`. This may reduce the number of updates as +routes are received, and may in some cases reduce routing churn. Though, it +could equally deterministically produce the largest possible set of updates +in response to the most common sequence of received updates. + +A deterministic order of evaluation tends to imply an additional overhead of +sorting over any set of n routes to a destination. The implementation of +deterministic MED in Frr scales significantly worse than most sorting +algorithms at present, with the number of paths to a given destination. +That number is often low enough to not cause any issues, but where there are +many paths, the deterministic comparison may quickly become increasingly +expensive in terms of CPU. + +Deterministic local evaluation can *not* fix the second, more major, +issue of MED however. Which is that the non-transitive preference of routes +MED can cause may lead to routing instability or oscillation across multiple +speakers in iBGP topologies. This can occur with full-mesh iBGP, but is +particularly problematic in non-full-mesh iBGP topologies that further +reduce the routing information known to each speaker. This has primarily +been documented with iBGP route-reflection topologies. However, any +route-hiding technologies potentially could also exacerbate oscillation with +MED. + +This second issue occurs where speakers each have only a subset of routes, +and there are cycles in the preferences between different combinations of +routes - as the undefined order of preference of MED allows - and the routes +are distributed in a way that causes the BGP speakers to 'chase' those +cycles. This can occur even if all speakers use a deterministic order of +evaluation in route selection. + +E.g., speaker 4 in AS A might receive a route from speaker 2 in AS X, and +from speaker 3 in AS Y; while speaker 5 in AS A might receive that route +from speaker 1 in AS Y. AS Y might set a MED of 200 at speaker 1, and 100 +at speaker 3. I.e, using ASN:ID:MED to label the speakers: + +:: + + /---------------\\ + X:2------|--A:4-------A:5--|-Y:1:200 + Y:3:100--|-/ | + \\---------------/ + + + +Assuming all other metrics are equal (AS_PATH, ORIGIN, 0 IGP costs), then +based on the RFC4271 decision process speaker 4 will choose X:2 over +Y:3:100, based on the lower ID of 2. Speaker 4 advertises X:2 to speaker 5. +Speaker 5 will continue to prefer Y:1:200 based on the ID, and advertise +this to speaker 4. Speaker 4 will now have the full set of routes, and the +Y:1:200 it receives from 5 will beat X:2, but when speaker 4 compares +Y:1:200 to Y:3:100 the MED check now becomes active as the ASes match, and +now Y:3:100 is preferred. Speaker 4 therefore now advertises Y:3:100 to 5, +which will also agrees that Y:3:100 is preferred to Y:1:200, and so +withdraws the latter route from 4. Speaker 4 now has only X:2 and Y:3:100, +and X:2 beats Y:3:100, and so speaker 4 implicitly updates its route to +speaker 5 to X:2. Speaker 5 sees that Y:1:200 beats X:2 based on the ID, +and advertises Y:1:200 to speaker 4, and the cycle continues. + +The root cause is the lack of a clear order of preference caused by how MED +sometimes is and sometimes is not compared, leading to this cycle in the +preferences between the routes: + +:: + + /---> X:2 ---beats---> Y:3:100 --\\ + | | + | | + \\---beats--- Y:1:200 <---beats---/ + + + +This particular type of oscillation in full-mesh iBGP topologies can be +avoided by speakers preferring already selected, external routes rather than +choosing to update to new a route based on a post-MED metric (e.g. +router-ID), at the cost of a non-deterministic selection process. Frr +implements this, as do many other implementations, so long as it is not +overridden by setting :ref:`bgp_bestpath_compare-routerid`, and see also +:ref:`BGP_decision_process`, . + +However, more complex and insidious cycles of oscillation are possible with +iBGP route-reflection, which are not so easily avoided. These have been +documented in various places. See, e.g., @cite{McPherson, D. and Gill, V. +and Walton, D., "Border Gateway Protocol (BGP) Persistent Route Oscillation +Condition", IETF RFC3345}, and @cite{Flavel, A. and M. Roughan, "Stable +and flexible iBGP", ACM SIGCOMM 2009}, and @cite{Griffin, T. and G. Wilfong, +"On the correctness of IBGP configuration", ACM SIGCOMM 2002} for concrete +examples and further references. + +There is as of this writing *no* known way to use MED for its original +purpose; *and* reduce routing information in iBGP topologies; +*and* be sure to avoid the instability problems of MED due the +non-transitive routing preferences it can induce; in general on arbitrary +networks. + +There may be iBGP topology specific ways to reduce the instability risks, +even while using MED, e.g.@: by constraining the reflection topology and by +tuning IGP costs between route-reflector clusters, see RFC3345 for details. +In the near future, the Add-Path extension to BGP may also solve MED +oscillation while still allowing MED to be used as intended, by distributing +"best-paths per neighbour AS". This would be at the cost of distributing at +least as many routes to all speakers as a full-mesh iBGP would, if not more, +while also imposing similar CPU overheads as the "Deterministic MED" feature +at each Add-Path reflector. + +More generally, the instability problems that MED can introduce on more +complex, non-full-mesh, iBGP topologies may be avoided either by: + + +* + Setting :ref:`bgp_always-compare-med`, however this allows MED to be compared + across values set by different neighbour ASes, which may not produce + coherent desirable results, of itself. + +* + Effectively ignoring MED by setting MED to the same value (e.g.@: 0) using + :ref:`routemap_set_metric` on all received routes, in combination with + setting :ref:`bgp_always-compare-med` on all speakers. This is the simplest + and most performant way to avoid MED oscillation issues, where an AS is happy + not to allow neighbours to inject this problematic metric. + + +As MED is evaluated after the AS_PATH length check, another possible use for +MED is for intra-AS steering of routes with equal AS_PATH length, as an +extension of the last case above. As MED is evaluated before IGP metric, +this can allow cold-potato routing to be implemented to send traffic to +preferred hand-offs with neighbours, rather than the closest hand-off +according to the IGP metric. + +Note that even if action is taken to address the MED non-transitivity +issues, other oscillations may still be possible. E.g., on IGP cost if +iBGP and IGP topologies are at cross-purposes with each other - see the +Flavel and Roughan paper above for an example. Hence the guideline that the +iBGP topology should follow the IGP topology. + +.. index:: {BGP} {bgp deterministic-med} {} + +{BGP} {bgp deterministic-med} {} + .. _bgp_deterministic-med: + + Carry out route-selection in way that produces deterministic answers + locally, even in the face of MED and the lack of a well-defined order of + preference it can induce on routes. Without this option the preferred route + with MED may be determined largely by the order that routes were received + in. + + Setting this option will have a performance cost that may be noticeable when + there are many routes for each destination. Currently in Frr it is + implemented in a way that scales poorly as the number of routes per + destination increases. + + The default is that this option is not set. + +Note that there are other sources of indeterminism in the route selection +process, specifically, the preference for older and already selected routes +from eBGP peers, :ref:`BGP_decision_process`. + +.. index:: {BGP} {bgp always-compare-med} {} + +{BGP} {bgp always-compare-med} {} + .. _bgp_always-compare-med: + + Always compare the MED on routes, even when they were received from + different neighbouring ASes. Setting this option makes the order of + preference of routes more defined, and should eliminate MED induced + oscillations. + + If using this option, it may also be desirable to use :ref:`routemap_set_metric` to set MED to 0 on routes received from external neighbours. + + This option can be used, together with :ref:`routemap_set_metric` to use MED + as an intra-AS metric to steer equal-length AS_PATH routes to, e.g., desired + exit points. + +.. _BGP_network: + +BGP network +=========== + + +.. _BGP_route: + +BGP route +--------- + +.. index:: {BGP} {network `A.B.C.D/M`} {} + +{BGP} {network `A.B.C.D/M`} {} + This command adds the announcement network.:: + + @group + router bgp 1 + address-family ipv4 unicast + network 10.0.0.0/8 + exit-address-family + @end group + + This configuration example says that network 10.0.0.0/8 will be + announced to all neighbors. Some vendors' routers don't advertise + routes if they aren't present in their IGP routing tables; `bgpd` + doesn't care about IGP routes when announcing its routes. + +.. index:: {BGP} {no network `A.B.C.D/M`} {} + +{BGP} {no network `A.B.C.D/M`} {} + +.. _Route_Aggregation: + +Route Aggregation +----------------- + +.. index:: {BGP} {aggregate-address `A.B.C.D/M`} {} + +{BGP} {aggregate-address `A.B.C.D/M`} {} + This command specifies an aggregate address. + +.. index:: {BGP} {aggregate-address `A.B.C.D/M` as-set} {} + +{BGP} {aggregate-address `A.B.C.D/M` as-set} {} + This command specifies an aggregate address. Resulting routes include + AS set. + +.. index:: {BGP} {aggregate-address `A.B.C.D/M` summary-only} {} + +{BGP} {aggregate-address `A.B.C.D/M` summary-only} {} + This command specifies an aggregate address. Aggreated routes will + not be announce. + +.. index:: {BGP} {no aggregate-address `A.B.C.D/M`} {} + +{BGP} {no aggregate-address `A.B.C.D/M`} {} + +.. _Redistribute_to_BGP: + +Redistribute to BGP +------------------- + +.. index:: {BGP} {redistribute kernel} {} + +{BGP} {redistribute kernel} {} + Redistribute kernel route to BGP process. + +.. index:: {BGP} {redistribute static} {} + +{BGP} {redistribute static} {} + Redistribute static route to BGP process. + +.. index:: {BGP} {redistribute connected} {} + +{BGP} {redistribute connected} {} + Redistribute connected route to BGP process. + +.. index:: {BGP} {redistribute rip} {} + +{BGP} {redistribute rip} {} + Redistribute RIP route to BGP process. + +.. index:: {BGP} {redistribute ospf} {} + +{BGP} {redistribute ospf} {} + Redistribute OSPF route to BGP process. + +.. index:: {BGP} {redistribute vpn} {} + +{BGP} {redistribute vpn} {} + Redistribute VNC routes to BGP process. + +.. index:: {BGP} {update-delay `max-delay`} {} + +{BGP} {update-delay `max-delay`} {} +.. index:: {BGP} {update-delay `max-delay` `establish-wait`} {} + +{BGP} {update-delay `max-delay` `establish-wait`} {} + This feature is used to enable read-only mode on BGP process restart or when + BGP process is cleared using 'clear ip bgp \*'. When applicable, read-only mode + would begin as soon as the first peer reaches Established status and a timer + for max-delay seconds is started. + + During this mode BGP doesn't run any best-path or generate any updates to its + peers. This mode continues until: + 1. All the configured peers, except the shutdown peers, have sent explicit EOR + (End-Of-RIB) or an implicit-EOR. The first keep-alive after BGP has reached + Established is considered an implicit-EOR. + If the establish-wait optional value is given, then BGP will wait for + peers to reach established from the begining of the update-delay till the + establish-wait period is over, i.e. the minimum set of established peers for + which EOR is expected would be peers established during the establish-wait + window, not necessarily all the configured neighbors. + 2. max-delay period is over. + On hitting any of the above two conditions, BGP resumes the decision process + and generates updates to its peers. + + Default max-delay is 0, i.e. the feature is off by default. + +.. index:: {BGP} {table-map `route-map-name`} {} + +{BGP} {table-map `route-map-name`} {} + This feature is used to apply a route-map on route updates from BGP to Zebra. + All the applicable match operations are allowed, such as match on prefix, + next-hop, communities, etc. Set operations for this attach-point are limited + to metric and next-hop only. Any operation of this feature does not affect + BGPs internal RIB. + + Supported for ipv4 and ipv6 address families. It works on multi-paths as well, + however, metric setting is based on the best-path only. + +.. _BGP_Peer: + +BGP Peer +======== + + +.. _Defining_Peer: + +Defining Peer +------------- + +.. index:: {BGP} {neighbor `peer` remote-as `asn`} {} + +{BGP} {neighbor `peer` remote-as `asn`} {} + Creates a new neighbor whose remote-as is `asn`. `peer` + can be an IPv4 address or an IPv6 address.:: + + @group + router bgp 1 + neighbor 10.0.0.1 remote-as 2 + @end group + + In this case my router, in AS-1, is trying to peer with AS-2 at + 10.0.0.1. + + This command must be the first command used when configuring a neighbor. + If the remote-as is not specified, *bgpd* will complain like this::: + + can't find neighbor 10.0.0.1 + + +.. _BGP_Peer_commands: + +BGP Peer commands +----------------- + +In a `router bgp` clause there are neighbor specific configurations +required. + +.. index:: {BGP} {neighbor `peer` shutdown} {} + +{BGP} {neighbor `peer` shutdown} {} +.. index:: {BGP} {no neighbor `peer` shutdown} {} + +{BGP} {no neighbor `peer` shutdown} {} + Shutdown the peer. We can delete the neighbor's configuration by + `no neighbor `peer` remote-as @var{as-number`} but all + configuration of the neighbor will be deleted. When you want to + preserve the configuration, but want to drop the BGP peer, use this + syntax. + +.. index:: {BGP} {neighbor `peer` ebgp-multihop} {} + +{BGP} {neighbor `peer` ebgp-multihop} {} +.. index:: {BGP} {no neighbor `peer` ebgp-multihop} {} + +{BGP} {no neighbor `peer` ebgp-multihop} {} +.. index:: {BGP} {neighbor `peer` description ...} {} + +{BGP} {neighbor `peer` description ...} {} +.. index:: {BGP} {no neighbor `peer` description ...} {} + +{BGP} {no neighbor `peer` description ...} {} + Set description of the peer. + +.. index:: {BGP} {neighbor `peer` version `version`} {} + +{BGP} {neighbor `peer` version `version`} {} + Set up the neighbor's BGP version. `version` can be `4`, + `4+` or `4-`. BGP version `4` is the default value used for + BGP peering. BGP version `4+` means that the neighbor supports + Multiprotocol Extensions for BGP-4. BGP version `4-` is similar but + the neighbor speaks the old Internet-Draft revision 00's Multiprotocol + Extensions for BGP-4. Some routing software is still using this + version. + +.. index:: {BGP} {neighbor `peer` interface `ifname`} {} + +{BGP} {neighbor `peer` interface `ifname`} {} +.. index:: {BGP} {no neighbor `peer` interface `ifname`} {} + +{BGP} {no neighbor `peer` interface `ifname`} {} + When you connect to a BGP peer over an IPv6 link-local address, you + have to specify the `ifname` of the interface used for the + connection. To specify IPv4 session addresses, see the + `neighbor `peer` update-source` command below. + + This command is deprecated and may be removed in a future release. Its + use should be avoided. + +.. index:: {BGP} {neighbor `peer` next-hop-self [all]} {} + +{BGP} {neighbor `peer` next-hop-self [all]} {} +.. index:: {BGP} {no neighbor `peer` next-hop-self [all]} {} + +{BGP} {no neighbor `peer` next-hop-self [all]} {} + This command specifies an announced route's nexthop as being equivalent + to the address of the bgp router if it is learned via eBGP. + If the optional keyword `all` is specified the modifiation is done + also for routes learned via iBGP. + +.. index:: {BGP} {neighbor `peer` update-source ``} {} + +{BGP} {neighbor `peer` update-source ``} {} +.. index:: {BGP} {no neighbor `peer` update-source} {} + +{BGP} {no neighbor `peer` update-source} {} + Specify the IPv4 source address to use for the @acronym{BGP} session to this + neighbour, may be specified as either an IPv4 address directly or + as an interface name (in which case the *zebra* daemon MUST be running + in order for *bgpd* to be able to retrieve interface state).:: + + @group + router bgp 64555 + neighbor foo update-source 192.168.0.1 + neighbor bar update-source lo0 + @end group + + +.. index:: {BGP} {neighbor `peer` default-originate} {} + +{BGP} {neighbor `peer` default-originate} {} +.. index:: {BGP} {no neighbor `peer` default-originate} {} + +{BGP} {no neighbor `peer` default-originate} {} + *bgpd*'s default is to not announce the default route (0.0.0.0/0) even it + is in routing table. When you want to announce default routes to the + peer, use this command. + +.. index:: {BGP} {neighbor `peer` port `port`} {} + +{BGP} {neighbor `peer` port `port`} {} +.. index:: {BGP} {neighbor `peer` port `port`} {} + +{BGP} {neighbor `peer` port `port`} {} +.. index:: {BGP} {neighbor `peer` send-community} {} + +{BGP} {neighbor `peer` send-community} {} +.. index:: {BGP} {neighbor `peer` send-community} {} + +{BGP} {neighbor `peer` send-community} {} +.. index:: {BGP} {neighbor `peer` weight `weight`} {} + +{BGP} {neighbor `peer` weight `weight`} {} +.. index:: {BGP} {no neighbor `peer` weight `weight`} {} + +{BGP} {no neighbor `peer` weight `weight`} {} + This command specifies a default `weight` value for the neighbor's + routes. + +.. index:: {BGP} {neighbor `peer` maximum-prefix `number`} {} + +{BGP} {neighbor `peer` maximum-prefix `number`} {} +.. index:: {BGP} {no neighbor `peer` maximum-prefix `number`} {} + +{BGP} {no neighbor `peer` maximum-prefix `number`} {} +.. index:: {BGP} {neighbor `peer` local-as `as-number`} {} + +{BGP} {neighbor `peer` local-as `as-number`} {} +.. index:: {BGP} {neighbor `peer` local-as `as-number` no-prepend} {} + +{BGP} {neighbor `peer` local-as `as-number` no-prepend} {} +.. index:: {BGP} {neighbor `peer` local-as `as-number` no-prepend replace-as} {} + +{BGP} {neighbor `peer` local-as `as-number` no-prepend replace-as} {} +.. index:: {BGP} {no neighbor `peer` local-as} {} + +{BGP} {no neighbor `peer` local-as} {} + Specify an alternate AS for this BGP process when interacting with the + specified peer. With no modifiers, the specified local-as is prepended to + the received AS_PATH when receiving routing updates from the peer, and + prepended to the outgoing AS_PATH (after the process local AS) when + transmitting local routes to the peer. + + If the no-prepend attribute is specified, then the supplied local-as is not + prepended to the received AS_PATH. + + If the replace-as attribute is specified, then only the supplied local-as is + prepended to the AS_PATH when transmitting local-route updates to this peer. + + Note that replace-as can only be specified if no-prepend is. + + This command is only allowed for eBGP peers. + +.. index:: {BGP} {neighbor `peer` ttl-security hops `number`} {} + +{BGP} {neighbor `peer` ttl-security hops `number`} {} +.. index:: {BGP} {no neighbor `peer` ttl-security hops `number`} {} + +{BGP} {no neighbor `peer` ttl-security hops `number`} {} + This command enforces Generalized TTL Security Mechanism (GTSM), as + specified in RFC 5082. With this command, only neighbors that are the + specified number of hops away will be allowed to become neighbors. This + command is mututally exclusive with *ebgp-multihop*. + +.. _Peer_filtering: + +Peer filtering +-------------- + +.. index:: {BGP} {neighbor `peer` distribute-list `name` [in|out]} {} + +{BGP} {neighbor `peer` distribute-list `name` [in|out]} {} + This command specifies a distribute-list for the peer. `direct` is + @samp{in} or @samp{out}. + +.. index:: {BGP command} {neighbor `peer` prefix-list `name` [in|out]} {} + +{BGP command} {neighbor `peer` prefix-list `name` [in|out]} {} +.. index:: {BGP command} {neighbor `peer` filter-list `name` [in|out]} {} + +{BGP command} {neighbor `peer` filter-list `name` [in|out]} {} +.. index:: {BGP} {neighbor `peer` route-map `name` [in|out]} {} + +{BGP} {neighbor `peer` route-map `name` [in|out]} {} + Apply a route-map on the neighbor. `direct` must be `in` or + `out`. + +.. index:: {BGP} {bgp route-reflector allow-outbound-policy} {} + +{BGP} {bgp route-reflector allow-outbound-policy} {} + By default, attribute modification via route-map policy out is not reflected + on reflected routes. This option allows the modifications to be reflected as + well. Once enabled, it affects all reflected routes. + +.. _BGP_Peer_Group: + +BGP Peer Group +============== + +.. index:: {BGP} {neighbor `word` peer-group} {} + +{BGP} {neighbor `word` peer-group} {} + This command defines a new peer group. + +.. index:: {BGP} {neighbor `peer` peer-group `word`} {} + +{BGP} {neighbor `peer` peer-group `word`} {} + This command bind specific peer to peer group `word`. + +.. _BGP_Address_Family: + +BGP Address Family +================== + +Multiprotocol BGP enables BGP to carry routing information for multiple +Network Layer protocols. BGP supports multiple Address Family +Identifier (AFI), namely IPv4 and IPv6. Support is also provided for +multiple sets of per-AFI information via Subsequent Address Family +Identifiers (SAFI). In addition to unicast information, VPN information +@cite{RFC4364} and @cite{RFC4659}, and Encapsulation information +@cite{RFC5512} is supported. + +.. index:: {Command} {show ip bgp vpnv4 all} {} + +{Command} {show ip bgp vpnv4 all} {} +.. index:: {Command} {show ipv6 bgp vpn all} {} + +{Command} {show ipv6 bgp vpn all} {} + Print active IPV4 or IPV6 routes advertised via the VPN SAFI. + +.. index:: {Command} {show ip bgp encap all} {} + +{Command} {show ip bgp encap all} {} +.. index:: {Command} {show ipv6 bgp encap all} {} + +{Command} {show ipv6 bgp encap all} {} + Print active IPV4 or IPV6 routes advertised via the Encapsulation SAFI. + +.. index:: {Command} {show bgp ipv4 encap summary} {} + +{Command} {show bgp ipv4 encap summary} {} +.. index:: {Command} {show bgp ipv4 vpn summary} {} + +{Command} {show bgp ipv4 vpn summary} {} +.. index:: {Command} {show bgp ipv6 encap summary} {} + +{Command} {show bgp ipv6 encap summary} {} +.. index:: {Command} {show bgp ipv6 vpn summary} {} + +{Command} {show bgp ipv6 vpn summary} {} + Print a summary of neighbor connections for the specified AFI/SAFI combination. + +.. _Autonomous_System: + +Autonomous System +================= + +The @acronym{AS,Autonomous System} number is one of the essential +element of BGP. BGP is a distance vector routing protocol, and the +AS-Path framework provides distance vector metric and loop detection to +BGP. @cite{RFC1930, Guidelines for creation, selection, and +registration of an Autonomous System (AS)} provides some background on +the concepts of an AS. + +The AS number is a two octet value, ranging in value from 1 to 65535. +The AS numbers 64512 through 65535 are defined as private AS numbers. +Private AS numbers must not to be advertised in the global Internet. + +.. _Display_BGP_Routes_by_AS_Path: + +Display BGP Routes by AS Path +----------------------------- + +To show BGP routes which has specific AS path information `show ip bgp` command can be used. + +.. index:: Command {show bgp {ipv4|ipv6} regexp `line`} {} + +Command {show bgp {ipv4|ipv6} regexp `line`} {} + This commands displays BGP routes that matches a regular + expression `line` (:ref:`BGP_Regular_Expressions`). + +.. _AS_Path_Access_List: + +AS Path Access List +------------------- + +AS path access list is user defined AS path. + +.. index:: {Command} {ip as-path access-list `word` {permit|deny} `line`} {} + +{Command} {ip as-path access-list `word` {permit|deny} `line`} {} + This command defines a new AS path access list. + +.. index:: {Command} {no ip as-path access-list `word`} {} + +{Command} {no ip as-path access-list `word`} {} +.. index:: {Command} {no ip as-path access-list `word` {permit|deny} `line`} {} + +{Command} {no ip as-path access-list `word` {permit|deny} `line`} {} + +.. _Using_AS_Path_in_Route_Map: + +Using AS Path in Route Map +-------------------------- + +.. index:: {Route Map} {match as-path `word`} {} + +{Route Map} {match as-path `word`} {} + +.. index:: {Route Map} {set as-path prepend `as-path`} {} + +{Route Map} {set as-path prepend `as-path`} {} + Prepend the given string of AS numbers to the AS_PATH. + +.. index:: {Route Map} {set as-path prepend last-as `num`} {} + +{Route Map} {set as-path prepend last-as `num`} {} + Prepend the existing last AS number (the leftmost ASN) to the AS_PATH. + +.. _Private_AS_Numbers: + +Private AS Numbers +------------------ + + +.. _BGP_Communities_Attribute: + +BGP Communities Attribute +========================= + +BGP communities attribute is widely used for implementing policy +routing. Network operators can manipulate BGP communities attribute +based on their network policy. BGP communities attribute is defined +in @cite{RFC1997, BGP Communities Attribute} and +@cite{RFC1998, An Application of the BGP Community Attribute +in Multi-home Routing}. It is an optional transitive attribute, +therefore local policy can travel through different autonomous system. + +Communities attribute is a set of communities values. Each +communities value is 4 octet long. The following format is used to +define communities value. + + + +*AS:VAL* + This format represents 4 octet communities value. `AS` is high + order 2 octet in digit format. `VAL` is low order 2 octet in + digit format. This format is useful to define AS oriented policy + value. For example, `7675:80` can be used when AS 7675 wants to + pass local policy value 80 to neighboring peer. + +*internet* + `internet` represents well-known communities value 0. + +*no-export* + ``no-export`` represents well-known communities value ``NO_EXPORT`` @\* + @r{(0xFFFFFF01)}. All routes carry this value must not be advertised + to outside a BGP confederation boundary. If neighboring BGP peer is + part of BGP confederation, the peer is considered as inside a BGP + confederation boundary, so the route will be announced to the peer. + +*no-advertise* + ``no-advertise`` represents well-known communities value + ``NO_ADVERTISE`` @*@r{(0xFFFFFF02)}. All routes carry this value + must not be advertise to other BGP peers. + +*local-AS* + ``local-AS`` represents well-known communities value + ``NO_EXPORT_SUBCONFED`` @r{(0xFFFFFF03)}. All routes carry this + value must not be advertised to external BGP peers. Even if the + neighboring router is part of confederation, it is considered as + external BGP peer, so the route will not be announced to the peer. + +When BGP communities attribute is received, duplicated communities +value in the communities attribute is ignored and each communities +values are sorted in numerical order. + +.. _BGP_Community_Lists: + +BGP Community Lists +------------------- + +BGP community list is a user defined BGP communites attribute list. +BGP community list can be used for matching or manipulating BGP +communities attribute in updates. + +There are two types of community list. One is standard community +list and another is expanded community list. Standard community list +defines communities attribute. Expanded community list defines +communities attribute string with regular expression. Standard +community list is compiled into binary format when user define it. +Standard community list will be directly compared to BGP communities +attribute in BGP updates. Therefore the comparison is faster than +expanded community list. + +.. index:: Command {ip community-list standard `name` {permit|deny} `community`} {} + +Command {ip community-list standard `name` {permit|deny} `community`} {} + This command defines a new standard community list. `community` + is communities value. The `community` is compiled into community + structure. We can define multiple community list under same name. In + that case match will happen user defined order. Once the + community list matches to communities attribute in BGP updates it + return permit or deny by the community list definition. When there is + no matched entry, deny will be returned. When `community` is + empty it matches to any routes. + +.. index:: Command {ip community-list expanded `name` {permit|deny} `line`} {} + +Command {ip community-list expanded `name` {permit|deny} `line`} {} + This command defines a new expanded community list. `line` is a + string expression of communities attribute. `line` can be a + regular expression (:ref:`BGP_Regular_Expressions`) to match + the communities attribute in BGP updates. + +.. index:: Command {no ip community-list `name`} {} + +Command {no ip community-list `name`} {} +.. index:: Command {no ip community-list standard `name`} {} + +Command {no ip community-list standard `name`} {} +.. index:: Command {no ip community-list expanded `name`} {} + +Command {no ip community-list expanded `name`} {} + These commands delete community lists specified by `name`. All of + community lists shares a single name space. So community lists can be + removed simpley specifying community lists name. + +.. index:: {Command} {show ip community-list} {} + +{Command} {show ip community-list} {} +.. index:: {Command} {show ip community-list `name`} {} + +{Command} {show ip community-list `name`} {} + This command displays current community list information. When + `name` is specified the specified community list's information is + shown. + +:: + + # show ip community-list + Named Community standard list CLIST + permit 7675:80 7675:100 no-export + deny internet + Named Community expanded list EXPAND + permit : + + # show ip community-list CLIST + Named Community standard list CLIST + permit 7675:80 7675:100 no-export + deny internet + + +.. _Numbered_BGP_Community_Lists: + +Numbered BGP Community Lists +---------------------------- + +When number is used for BGP community list name, the number has +special meanings. Community list number in the range from 1 and 99 is +standard community list. Community list number in the range from 100 +to 199 is expanded community list. These community lists are called +as numbered community lists. On the other hand normal community lists +is called as named community lists. + +.. index:: Command {ip community-list <1-99> {permit|deny} `community`} {} + +Command {ip community-list <1-99> {permit|deny} `community`} {} + This command defines a new community list. <1-99> is standard + community list number. Community list name within this range defines + standard community list. When `community` is empty it matches to + any routes. + +.. index:: Command {ip community-list <100-199> {permit|deny} `community`} {} + +Command {ip community-list <100-199> {permit|deny} `community`} {} + This command defines a new community list. <100-199> is expanded + community list number. Community list name within this range defines + expanded community list. + +.. index:: Command {ip community-list `name` {permit|deny} `community`} {} + +Command {ip community-list `name` {permit|deny} `community`} {} + When community list type is not specifed, the community list type is + automatically detected. If `community` can be compiled into + communities attribute, the community list is defined as a standard + community list. Otherwise it is defined as an expanded community + list. This feature is left for backward compability. Use of this + feature is not recommended. + +.. _BGP_Community_in_Route_Map: + +BGP Community in Route Map +-------------------------- + +In Route Map (:ref:`Route_Map`), we can match or set BGP +communities attribute. Using this feature network operator can +implement their network policy based on BGP communities attribute. + +Following commands can be used in Route Map. + +.. index:: {Route Map} {match community `word`} {} + +{Route Map} {match community `word`} {} +.. index:: {Route Map} {match community `word` exact-match} {} + +{Route Map} {match community `word` exact-match} {} + This command perform match to BGP updates using community list + `word`. When the one of BGP communities value match to the one of + communities value in community list, it is match. When + `exact-match` keyword is spcified, match happen only when BGP + updates have completely same communities value specified in the + community list. + +.. index:: {Route Map} {set community none} {} + +{Route Map} {set community none} {} +.. index:: {Route Map} {set community `community`} {} + +{Route Map} {set community `community`} {} +.. index:: {Route Map} {set community `community` additive} {} + +{Route Map} {set community `community` additive} {} + This command manipulate communities value in BGP updates. When + `none` is specified as communities value, it removes entire + communities attribute from BGP updates. When `community` is not + `none`, specified communities value is set to BGP updates. If + BGP updates already has BGP communities value, the existing BGP + communities value is replaced with specified `community` value. + When `additive` keyword is specified, `community` is appended + to the existing communities value. + +.. index:: {Route Map} {set comm-list `word` delete} {} + +{Route Map} {set comm-list `word` delete} {} + This command remove communities value from BGP communities attribute. + The `word` is community list name. When BGP route's communities + value matches to the community list `word`, the communities value + is removed. When all of communities value is removed eventually, the + BGP update's communities attribute is completely removed. + +.. _Display_BGP_Routes_by_Community: + +Display BGP Routes by Community +------------------------------- + +To show BGP routes which has specific BGP communities attribute, +`show bgp {ipv4|ipv6}` command can be used. The +`community` and `community-list` subcommand can be used. + +.. index:: Command {show bgp {ipv4|ipv6} community} {} + +Command {show bgp {ipv4|ipv6} community} {} +.. index:: Command {show bgp {ipv4|ipv6} community `community`} {} + +Command {show bgp {ipv4|ipv6} community `community`} {} +.. index:: Command {show bgp {ipv4|ipv6} community `community` exact-match} {} + +Command {show bgp {ipv4|ipv6} community `community` exact-match} {} + `show bgp {ipv4|ipv6} community` displays BGP routes which has communities + attribute. Where the address family can be IPv4 or IPv6 among others. When + `community` is specified, BGP routes that matches `community` value is + displayed. For this command, `internet` keyword can't be used for + `community` value. When `exact-match` is specified, it display only + routes that have an exact match. + +.. index:: Command {show bgp {ipv4|ipv6} community-list `word`} {} + +Command {show bgp {ipv4|ipv6} community-list `word`} {} +.. index:: Command {show bgp {ipv4|ipv6} community-list `word` exact-match} {} + +Command {show bgp {ipv4|ipv6} community-list `word` exact-match} {} + This commands display BGP routes for the address family specified that matches + community list `word`. When `exact-match` is specified, display only + routes that have an exact match. + +.. _Using_BGP_Communities_Attribute: + +Using BGP Communities Attribute +------------------------------- + +Following configuration is the most typical usage of BGP communities +attribute. AS 7675 provides upstream Internet connection to AS 100. +When following configuration exists in AS 7675, AS 100 networks +operator can set local preference in AS 7675 network by setting BGP +communities attribute to the updates. + +:: + + router bgp 7675 + neighbor 192.168.0.1 remote-as 100 + address-family ipv4 unicast + neighbor 192.168.0.1 route-map RMAP in + exit-address-family + ! + ip community-list 70 permit 7675:70 + ip community-list 70 deny + ip community-list 80 permit 7675:80 + ip community-list 80 deny + ip community-list 90 permit 7675:90 + ip community-list 90 deny + ! + route-map RMAP permit 10 + match community 70 + set local-preference 70 + ! + route-map RMAP permit 20 + match community 80 + set local-preference 80 + ! + route-map RMAP permit 30 + match community 90 + set local-preference 90 + + +Following configuration announce 10.0.0.0/8 from AS 100 to AS 7675. +The route has communities value 7675:80 so when above configuration +exists in AS 7675, announced route's local preference will be set to +value 80. + +:: + + router bgp 100 + network 10.0.0.0/8 + neighbor 192.168.0.2 remote-as 7675 + address-family ipv4 unicast + neighbor 192.168.0.2 route-map RMAP out + exit-address-family + ! + ip prefix-list PLIST permit 10.0.0.0/8 + ! + route-map RMAP permit 10 + match ip address prefix-list PLIST + set community 7675:80 + + +Following configuration is an example of BGP route filtering using +communities attribute. This configuration only permit BGP routes +which has BGP communities value 0:80 or 0:90. Network operator can +put special internal communities value at BGP border router, then +limit the BGP routes announcement into the internal network. + +:: + + router bgp 7675 + neighbor 192.168.0.1 remote-as 100 + address-family ipv4 unicast + neighbor 192.168.0.1 route-map RMAP in + exit-address-family + ! + ip community-list 1 permit 0:80 0:90 + ! + route-map RMAP permit in + match community 1 + + +Following exmaple filter BGP routes which has communities value 1:1. +When there is no match community-list returns deny. To avoid +filtering all of routes, we need to define permit any at last. + +:: + + router bgp 7675 + neighbor 192.168.0.1 remote-as 100 + address-family ipv4 unicast + neighbor 192.168.0.1 route-map RMAP in + exit-address-family + ! + ip community-list standard FILTER deny 1:1 + ip community-list standard FILTER permit + ! + route-map RMAP permit 10 + match community FILTER + + +Communities value keyword `internet` has special meanings in +standard community lists. In below example `internet` act as +match any. It matches all of BGP routes even if the route does not +have communities attribute at all. So community list `INTERNET` +is same as above example's `FILTER`. + +:: + + ip community-list standard INTERNET deny 1:1 + ip community-list standard INTERNET permit internet + + +Following configuration is an example of communities value deletion. +With this configuration communities value 100:1 and 100:2 is removed +from BGP updates. For communities value deletion, only `permit` +community-list is used. `deny` community-list is ignored. + +:: + + router bgp 7675 + neighbor 192.168.0.1 remote-as 100 + address-family ipv4 unicast + neighbor 192.168.0.1 route-map RMAP in + exit-address-family + ! + ip community-list standard DEL permit 100:1 100:2 + ! + route-map RMAP permit 10 + set comm-list DEL delete + + +.. _BGP_Extended_Communities_Attribute: + +BGP Extended Communities Attribute +================================== + +BGP extended communities attribute is introduced with MPLS VPN/BGP +technology. MPLS VPN/BGP expands capability of network infrastructure +to provide VPN functionality. At the same time it requires a new +framework for policy routing. With BGP Extended Communities Attribute +we can use Route Target or Site of Origin for implementing network +policy for MPLS VPN/BGP. + +BGP Extended Communities Attribute is similar to BGP Communities +Attribute. It is an optional transitive attribute. BGP Extended +Communities Attribute can carry multiple Extended Community value. +Each Extended Community value is eight octet length. + +BGP Extended Communities Attribute provides an extended range +compared with BGP Communities Attribute. Adding to that there is a +type field in each value to provides community space structure. + +There are two format to define Extended Community value. One is AS +based format the other is IP address based format. + + + +*AS:VAL* + This is a format to define AS based Extended Community value. + `AS` part is 2 octets Global Administrator subfield in Extended + Community value. `VAL` part is 4 octets Local Administrator + subfield. `7675:100` represents AS 7675 policy value 100. + +*IP-Address:VAL* + This is a format to define IP address based Extended Community value. + `IP-Address` part is 4 octets Global Administrator subfield. + `VAL` part is 2 octets Local Administrator subfield. + `10.0.0.1:100` represents + +.. _BGP_Extended_Community_Lists: + +BGP Extended Community Lists +---------------------------- + +Expanded Community Lists is a user defined BGP Expanded Community +Lists. + +.. index:: Command {ip extcommunity-list standard `name` {permit|deny} `extcommunity`} {} + +Command {ip extcommunity-list standard `name` {permit|deny} `extcommunity`} {} + This command defines a new standard extcommunity-list. + `extcommunity` is extended communities value. The + `extcommunity` is compiled into extended community structure. We + can define multiple extcommunity-list under same name. In that case + match will happen user defined order. Once the extcommunity-list + matches to extended communities attribute in BGP updates it return + permit or deny based upon the extcommunity-list definition. When + there is no matched entry, deny will be returned. When + `extcommunity` is empty it matches to any routes. + +.. index:: Command {ip extcommunity-list expanded `name` {permit|deny} `line`} {} + +Command {ip extcommunity-list expanded `name` {permit|deny} `line`} {} + This command defines a new expanded extcommunity-list. `line` is + a string expression of extended communities attribute. `line` can + be a regular expression (:ref:`BGP_Regular_Expressions`) to match an + extended communities attribute in BGP updates. + +.. index:: Command {no ip extcommunity-list `name`} {} + +Command {no ip extcommunity-list `name`} {} +.. index:: Command {no ip extcommunity-list standard `name`} {} + +Command {no ip extcommunity-list standard `name`} {} +.. index:: Command {no ip extcommunity-list expanded `name`} {} + +Command {no ip extcommunity-list expanded `name`} {} + These commands delete extended community lists specified by + `name`. All of extended community lists shares a single name + space. So extended community lists can be removed simpley specifying + the name. + +.. index:: {Command} {show ip extcommunity-list} {} + +{Command} {show ip extcommunity-list} {} +.. index:: {Command} {show ip extcommunity-list `name`} {} + +{Command} {show ip extcommunity-list `name`} {} + This command displays current extcommunity-list information. When + `name` is specified the community list's information is shown. + +:: + + # show ip extcommunity-list + + +.. _BGP_Extended_Communities_in_Route_Map: + +BGP Extended Communities in Route Map +------------------------------------- + +.. index:: {Route Map} {match extcommunity `word`} {} + +{Route Map} {match extcommunity `word`} {} + +.. index:: {Route Map} {set extcommunity rt `extcommunity`} {} + +{Route Map} {set extcommunity rt `extcommunity`} {} + This command set Route Target value. + +.. index:: {Route Map} {set extcommunity soo `extcommunity`} {} + +{Route Map} {set extcommunity soo `extcommunity`} {} + This command set Site of Origin value. + +.. _BGP_Large_Communities_Attribute: + +BGP Large Communities Attribute +=============================== + +The BGP Large Communities attribute was introduced in Feb 2017 with +@cite{RFC8092, BGP Large Communities Attribute}. + +The BGP Large Communities Attribute is similar to the BGP Communities +Attribute except that it has 3 components instead of two and each of +which are 4 octets in length. Large Communities bring additional +functionality and convenience over traditional communities, specifically +the fact that the `GLOBAL` part below is now 4 octets wide allowing +AS4 operators seamless use. + + + +*GLOBAL:LOCAL1:LOCAL2* + This is the format to define Large Community values. Referencing + @cite{RFC8195, Use of BGP Large Communities} the values are commonly + referred to as follows. + The `GLOBAL` part is a 4 octet Global Administrator field, common + use of this field is the operators AS number. + The `LOCAL1` part is a 4 octet Local Data Part 1 subfield referred + to as a function. + The `LOCAL2` part is a 4 octet Local Data Part 2 field and referred + to as the parameter subfield. `65551:1:10` represents AS 65551 + function 1 and parameter 10. + The referenced RFC above gives some guidelines on recommended usage. + +.. _BGP_Large_Community_Lists: + +BGP Large Community Lists +------------------------- + +Two types of large community lists are supported, namely `standard` and +`expanded`. + +.. index:: Command {ip large-community-list standard `name` {permit|deny} `large-community`} {} + +Command {ip large-community-list standard `name` {permit|deny} `large-community`} {} + This command defines a new standard large-community-list. + `large-community` is the Large Community value. We + can add multiple large communities under same name. In that case + the match will happen in the user defined order. Once the large-community-list + matches the Large Communities attribute in BGP updates it will return + permit or deny based upon the large-community-list definition. When + there is no matched entry, a deny will be returned. When `large-community` + is empty it matches any routes. + +.. index:: Command {ip large-community-list expanded `name` {permit|deny} `line`} {} + +Command {ip large-community-list expanded `name` {permit|deny} `line`} {} + This command defines a new expanded large-community-list. Where `line` is + a string matching expression, it will be compared to the entire Large Communities + attribute as a string, with each large-community in order from lowest to highest. + `line` can also be a regular expression which matches this Large + Community attribute. + +.. index:: Command {no ip large-community-list `name`} {} + +Command {no ip large-community-list `name`} {} +.. index:: Command {no ip large-community-list standard `name`} {} + +Command {no ip large-community-list standard `name`} {} +.. index:: Command {no ip large-community-list expanded `name`} {} + +Command {no ip large-community-list expanded `name`} {} + These commands delete Large Community lists specified by + `name`. All Large Community lists share a single namespace. + This means Large Community lists can be removed by simply specifying the name. + +.. index:: {Command} {show ip large-community-list} {} + +{Command} {show ip large-community-list} {} +.. index:: {Command} {show ip large-community-list `name`} {} + +{Command} {show ip large-community-list `name`} {} + This command display current large-community-list information. When + `name` is specified the community list information is shown. + +.. index:: {Command} {show ip bgp large-community-info} {} + +{Command} {show ip bgp large-community-info} {} + This command displays the current large communities in use. + +.. _BGP_Large_Communities_in_Route_Map: + +BGP Large Communities in Route Map +---------------------------------- + +.. index:: {Route Map} {match large-community `line`} {} + +{Route Map} {match large-community `line`} {} + Where `line` can be a simple string to match, or a regular expression. + It is very important to note that this match occurs on the entire + large-community string as a whole, where each large-community is ordered + from lowest to highest. + +.. index:: {Route Map} {set large-community `large-community`} {} + +{Route Map} {set large-community `large-community`} {} +.. index:: {Route Map} {set large-community `large-community` `large-community`} {} + +{Route Map} {set large-community `large-community` `large-community`} {} +.. index:: {Route Map} {set large-community `large-community` additive} {} + +{Route Map} {set large-community `large-community` additive} {} + These commands are used for setting large-community values. The first + command will overwrite any large-communities currently present. + The second specifies two large-communities, which overwrites the current + large-community list. The third will add a large-community value without + overwriting other values. Multiple large-community values can be specified. + +.. _Displaying_BGP_information: + +Displaying BGP information +========================== + + +.. _Showing_BGP_information: + +Showing BGP information +----------------------- + +.. index:: {Command} {show ip bgp} {} + +{Command} {show ip bgp} {} +.. index:: {Command} {show ip bgp `A.B.C.D`} {} + +{Command} {show ip bgp `A.B.C.D`} {} +.. index:: {Command} {show ip bgp `X:X::X:X`} {} + +{Command} {show ip bgp `X:X::X:X`} {} + This command displays BGP routes. When no route is specified it + display all of IPv4 BGP routes. + +:: + + BGP table version is 0, local router ID is 10.1.1.1 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 1.1.1.1/32 0.0.0.0 0 32768 i + + Total number of prefixes 1 + + +.. index:: {Command} {show ip bgp regexp `line`} {} + +{Command} {show ip bgp regexp `line`} {} + This command displays BGP routes using AS path regular expression + (:ref:`BGP_Regular_Expressions`). + +.. index:: Command {show ip bgp community `community`} {} + +Command {show ip bgp community `community`} {} +.. index:: Command {show ip bgp community `community` exact-match} {} + +Command {show ip bgp community `community` exact-match} {} + This command displays BGP routes using `community` (:ref:`Display_BGP_Routes_by_Community`). + +.. index:: Command {show ip bgp community-list `word`} {} + +Command {show ip bgp community-list `word`} {} +.. index:: Command {show ip bgp community-list `word` exact-match} {} + +Command {show ip bgp community-list `word` exact-match} {} + This command displays BGP routes using community list (:ref:`Display_BGP_Routes_by_Community`). + +.. index:: {Command} {show bgp {ipv4|ipv6} summary} {} + +{Command} {show bgp {ipv4|ipv6} summary} {} + Show a bgp peer summary for the specified address family. + +.. index:: {Command} {show bgp {ipv4|ipv6} neighbor [`peer`]} {} + +{Command} {show bgp {ipv4|ipv6} neighbor [`peer`]} {} + This command shows information on a specific BGP `peer`. + +.. index:: {Command} {show bgp {ipv4|ipv6} dampening dampened-paths} {} + +{Command} {show bgp {ipv4|ipv6} dampening dampened-paths} {} + Display paths suppressed due to dampening. + +.. index:: {Command} {show bgp {ipv4|ipv6} dampening flap-statistics} {} + +{Command} {show bgp {ipv4|ipv6} dampening flap-statistics} {} + Display flap statistics of routes. + +.. _Other_BGP_commands: + +Other BGP commands +------------------ + +.. index:: {Command} {clear bgp {ipv4|ipv6} \*} {} + +{Command} {clear bgp {ipv4|ipv6} \*} {} + Clear all address family peers. + +.. index:: {Command} {clear bgp {ipv4|ipv6} `peer`} {} + +{Command} {clear bgp {ipv4|ipv6} `peer`} {} + Clear peers which have addresses of X.X.X.X + +.. index:: {Command} {clear bgp {ipv4|ipv6} `peer` soft in} {} + +{Command} {clear bgp {ipv4|ipv6} `peer` soft in} {} + Clear peer using soft reconfiguration. + +.. index:: {Command} {show debug} {} + +{Command} {show debug} {} +.. index:: {Command} {debug event} {} + +{Command} {debug event} {} +.. index:: {Command} {debug update} {} + +{Command} {debug update} {} +.. index:: {Command} {debug keepalive} {} + +{Command} {debug keepalive} {} +.. index:: {Command} {no debug event} {} + +{Command} {no debug event} {} +.. index:: {Command} {no debug update} {} + +{Command} {no debug update} {} +.. index:: {Command} {no debug keepalive} {} + +{Command} {no debug keepalive} {} + +.. _Capability_Negotiation: + +Capability Negotiation +====================== + +When adding IPv6 routing information exchange feature to BGP. There +were some proposals. @acronym{IETF,Internet Engineering Task Force} +@acronym{IDR, Inter Domain Routing} @acronym{WG, Working group} adopted +a proposal called Multiprotocol Extension for BGP. The specification +is described in @cite{RFC2283}. The protocol does not define new protocols. +It defines new attributes to existing BGP. When it is used exchanging +IPv6 routing information it is called BGP-4+. When it is used for +exchanging multicast routing information it is called MBGP. + +*bgpd* supports Multiprotocol Extension for BGP. So if remote +peer supports the protocol, *bgpd* can exchange IPv6 and/or +multicast routing information. + +Traditional BGP did not have the feature to detect remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 +unicast routes. This was a big problem using Multiprotocol Extension +for BGP to operational network. @cite{RFC2842, Capabilities +Advertisement with BGP-4} adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect +the remote peer's capabilities. If the peer is only configured as IPv4 +unicast neighbor, *bgpd* does not send these Capability +Negotiation packets (at least not unless other optional BGP features +require capability negotation). + +By default, Frr will bring up peering with minimal common capability +for the both sides. For example, local router has unicast and +multicast capabilitie and remote router has unicast capability. In +this case, the local router will establish the connection with unicast +only capability. When there are no common capabilities, Frr sends +Unsupported Capability error and then resets the connection. + +If you want to completely match capabilities with remote peer. Please +use *strict-capability-match* command. + +.. index:: {BGP} {neighbor `peer` strict-capability-match} {} + +{BGP} {neighbor `peer` strict-capability-match} {} +.. index:: {BGP} {no neighbor `peer` strict-capability-match} {} + +{BGP} {no neighbor `peer` strict-capability-match} {} + Strictly compares remote capabilities and local capabilities. If capabilities + are different, send Unsupported Capability error then reset connection. + + You may want to disable sending Capability Negotiation OPEN message + optional parameter to the peer when remote peer does not implement + Capability Negotiation. Please use *dont-capability-negotiate* + command to disable the feature. + +.. index:: {BGP} {neighbor `peer` dont-capability-negotiate} {} + +{BGP} {neighbor `peer` dont-capability-negotiate} {} +.. index:: {BGP} {no neighbor `peer` dont-capability-negotiate} {} + +{BGP} {no neighbor `peer` dont-capability-negotiate} {} + Suppress sending Capability Negotiation as OPEN message optional + parameter to the peer. This command only affects the peer is configured + other than IPv4 unicast configuration. + + When remote peer does not have capability negotiation feature, remote + peer will not send any capabilities at all. In that case, bgp + configures the peer with configured capabilities. + + You may prefer locally configured capabilities more than the negotiated + capabilities even though remote peer sends capabilities. If the peer + is configured by *override-capability*, *bgpd* ignores + received capabilities then override negotiated capabilities with + configured values. + +.. index:: {BGP} {neighbor `peer` override-capability} {} + +{BGP} {neighbor `peer` override-capability} {} +.. index:: {BGP} {no neighbor `peer` override-capability} {} + +{BGP} {no neighbor `peer` override-capability} {} + Override the result of Capability Negotiation with local configuration. + Ignore remote peer's capability value. + +.. _Route_Reflector: + +Route Reflector +=============== + +.. index:: {BGP} {bgp cluster-id `a.b.c.d`} {} + +{BGP} {bgp cluster-id `a.b.c.d`} {} + +.. index:: {BGP} {neighbor `peer` route-reflector-client} {} + +{BGP} {neighbor `peer` route-reflector-client} {} +.. index:: {BGP} {no neighbor `peer` route-reflector-client} {} + +{BGP} {no neighbor `peer` route-reflector-client} {} + +.. _Route_Server: + +Route Server +============ + +At an Internet Exchange point, many ISPs are connected to each other by +external BGP peering. Normally these external BGP connection are done by +@samp{full mesh} method. As with internal BGP full mesh formation, +this method has a scaling problem. + +This scaling problem is well known. Route Server is a method to resolve +the problem. Each ISP's BGP router only peers to Route Server. Route +Server serves as BGP information exchange to other BGP routers. By +applying this method, numbers of BGP connections is reduced from +O(n*(n-1)/2) to O(n). + +Unlike normal BGP router, Route Server must have several routing tables +for managing different routing policies for each BGP speaker. We call the +routing tables as different ``view`` s. *bgpd* can work as +normal BGP router or Route Server or both at the same time. + +.. _Multiple_instance: + +Multiple instance +----------------- + +To enable multiple view function of `bgpd`, you must turn on +multiple instance feature beforehand. + +.. index:: {Command} {bgp multiple-instance} {} + +{Command} {bgp multiple-instance} {} + Enable BGP multiple instance feature. After this feature is enabled, + you can make multiple BGP instances or multiple BGP views. + +.. index:: {Command} {no bgp multiple-instance} {} + +{Command} {no bgp multiple-instance} {} + Disable BGP multiple instance feature. You can not disable this feature + when BGP multiple instances or views exist. + +When you want to make configuration more Cisco like one, + +.. index:: {Command} {bgp config-type cisco} {} + +{Command} {bgp config-type cisco} {} + Cisco compatible BGP configuration output. + +When bgp config-type cisco is specified, + +'no synchronization' is displayed. +'no auto-summary' is displayed. + +'network' and 'aggregate-address' argument is displayed as +'A.B.C.D M.M.M.M' + +Frr: network 10.0.0.0/8 +Cisco: network 10.0.0.0 + +Frr: aggregate-address 192.168.0.0/24 +Cisco: aggregate-address 192.168.0.0 255.255.255.0 + +Community attribute handling is also different. If there is no +configuration is specified community attribute and extended community +attribute are sent to neighbor. When user manually disable the +feature community attribute is not sent to the neighbor. In case of +*bgp config-type cisco* is specified, community attribute is not +sent to the neighbor by default. To send community attribute user has +to specify *neighbor A.B.C.D send-community* command. + +:: + + ! + router bgp 1 + neighbor 10.0.0.1 remote-as 1 + address-family ipv4 unicast + no neighbor 10.0.0.1 send-community + exit-address-family + ! + router bgp 1 + neighbor 10.0.0.1 remote-as 1 + address-family ipv4 unicast + neighbor 10.0.0.1 send-community + exit-address-family + ! + + +.. index:: {Command} {bgp config-type zebra} {} + +{Command} {bgp config-type zebra} {} + Frr style BGP configuration. This is default. + +.. _BGP_instance_and_view: + +BGP instance and view +--------------------- + +BGP instance is a normal BGP process. The result of route selection +goes to the kernel routing table. You can setup different AS at the +same time when BGP multiple instance feature is enabled. + +.. index:: {Command} {router bgp `as-number`} {} + +{Command} {router bgp `as-number`} {} + Make a new BGP instance. You can use arbitrary word for the `name`. + +:: + + @group + bgp multiple-instance + ! + router bgp 1 + neighbor 10.0.0.1 remote-as 2 + neighbor 10.0.0.2 remote-as 3 + ! + router bgp 2 + neighbor 10.0.0.3 remote-as 4 + neighbor 10.0.0.4 remote-as 5 + @end group + + +BGP view is almost same as normal BGP process. The result of +route selection does not go to the kernel routing table. BGP view is +only for exchanging BGP routing information. + +.. index:: {Command} {router bgp `as-number` view `name`} {} + +{Command} {router bgp `as-number` view `name`} {} + Make a new BGP view. You can use arbitrary word for the `name`. This + view's route selection result does not go to the kernel routing table. + +With this command, you can setup Route Server like below. + +:: + + @group + bgp multiple-instance + ! + router bgp 1 view 1 + neighbor 10.0.0.1 remote-as 2 + neighbor 10.0.0.2 remote-as 3 + ! + router bgp 2 view 2 + neighbor 10.0.0.3 remote-as 4 + neighbor 10.0.0.4 remote-as 5 + @end group + + +.. _Routing_policy: + +Routing policy +-------------- + +You can set different routing policy for a peer. For example, you can +set different filter for a peer. + +:: + + @group + bgp multiple-instance + ! + router bgp 1 view 1 + neighbor 10.0.0.1 remote-as 2 + address-family ipv4 unicast + neighbor 10.0.0.1 distribute-list 1 in + exit-address-family + ! + router bgp 1 view 2 + neighbor 10.0.0.1 remote-as 2 + address-family ipv4 unicast + neighbor 10.0.0.1 distribute-list 2 in + exit-address-family + @end group + + +This means BGP update from a peer 10.0.0.1 goes to both BGP view 1 and view +2. When the update is inserted into view 1, distribute-list 1 is +applied. On the other hand, when the update is inserted into view 2, +distribute-list 2 is applied. + +.. _Viewing_the_view: + +Viewing the view +---------------- + +To display routing table of BGP view, you must specify view name. + +.. index:: {Command} {show ip bgp view `name`} {} + +{Command} {show ip bgp view `name`} {} + Display routing table of BGP view `name`. + +.. _BGP_Regular_Expressions: + +BGP Regular Expressions +======================= + +BGP regular expressions are based on `POSIX 1003.2` regular +expressions. The following description is just a quick subset of the +`POSIX` regular expressions. Adding to that, the special character +'_' is added. + + + +*.* + Matches any single character. + +* + Matches 0 or more occurrences of pattern. + ++ + Matches 1 or more occurrences of pattern. + +? + Match 0 or 1 occurrences of pattern. + +^ + Matches the beginning of the line. + +$ + Matches the end of the line. + +_ + Character `_` has special meanings in BGP regular expressions. + It matches to space and comma , and AS set delimiter { and } and AS + confederation delimiter `(` and `)`. And it also matches to + the beginning of the line and the end of the line. So `_` can be + used for AS value boundaries match. This character technically evaluates + to `(^|[,{}() ]|$)`. + +.. _How_to_set_up_a_6-Bone_connection: + +How to set up a 6-Bone connection +================================= + +:: + + @group + zebra configuration + =================== + ! + ! Actually there is no need to configure zebra + ! + + bgpd configuration + ================== + ! + ! This means that routes go through zebra and into the kernel. + ! + router zebra + ! + ! MP-BGP configuration + ! + router bgp 7675 + bgp router-id 10.0.0.1 + neighbor 3ffe:1cfa:0:2:2a0:c9ff:fe9e:f56 remote-as `as-number` + ! + address-family ipv6 + network 3ffe:506::/32 + neighbor 3ffe:1cfa:0:2:2a0:c9ff:fe9e:f56 activate + neighbor 3ffe:1cfa:0:2:2a0:c9ff:fe9e:f56 route-map set-nexthop out + neighbor 3ffe:1cfa:0:2:2c0:4fff:fe68:a231 remote-as `as-number` + neighbor 3ffe:1cfa:0:2:2c0:4fff:fe68:a231 route-map set-nexthop out + exit-address-family + ! + ipv6 access-list all permit any + ! + ! Set output nexthop address. + ! + route-map set-nexthop permit 10 + match ipv6 address all + set ipv6 nexthop global 3ffe:1cfa:0:2:2c0:4fff:fe68:a225 + set ipv6 nexthop local fe80::2c0:4fff:fe68:a225 + ! + ! logfile FILENAME is obsolete. Please use log file FILENAME + + log file bgpd.log + ! + @end group + + +.. _Dump_BGP_packets_and_table: + +Dump BGP packets and table +========================== + +.. index:: Command {dump bgp all `path` [`interval`]} {} + +Command {dump bgp all `path` [`interval`]} {} +.. index:: Command {dump bgp all-et `path` [`interval`]} {} + +Command {dump bgp all-et `path` [`interval`]} {} +.. index:: Command {no dump bgp all [`path`] [`interval`]} {} + +Command {no dump bgp all [`path`] [`interval`]} {} + Dump all BGP packet and events to `path` file. + If `interval` is set, a new file will be created for echo `interval` of seconds. + The path `path` can be set with date and time formatting (strftime). + The type ‘all-et’ enables support for Extended Timestamp Header (:ref:`Packet_Binary_Dump_Format`). + (:ref:`Packet_Binary_Dump_Format`) + +.. index:: Command {dump bgp updates `path` [`interval`]} {} + +Command {dump bgp updates `path` [`interval`]} {} +.. index:: Command {dump bgp updates-et `path` [`interval`]} {} + +Command {dump bgp updates-et `path` [`interval`]} {} +.. index:: Command {no dump bgp updates [`path`] [`interval`]} {} + +Command {no dump bgp updates [`path`] [`interval`]} {} + Dump only BGP updates messages to `path` file. + If `interval` is set, a new file will be created for echo `interval` of seconds. + The path `path` can be set with date and time formatting (strftime). + The type ‘updates-et’ enables support for Extended Timestamp Header (:ref:`Packet_Binary_Dump_Format`). + +.. index:: Command {dump bgp routes-mrt `path`} {} + +Command {dump bgp routes-mrt `path`} {} +.. index:: Command {dump bgp routes-mrt `path` `interval`} {} + +Command {dump bgp routes-mrt `path` `interval`} {} +.. index:: Command {no dump bgp route-mrt [`path`] [`interval`]} {} + +Command {no dump bgp route-mrt [`path`] [`interval`]} {} + Dump whole BGP routing table to `path`. This is heavy process. + The path `path` can be set with date and time formatting (strftime). + If `interval` is set, a new file will be created for echo `interval` of seconds. + + Note: the interval variable can also be set using hours and minutes: 04h20m00. + +BGP Configuration Examples +========================== + +Example of a session to an upstream, advertising only one prefix to it. + +:: + + router bgp 64512 + bgp router-id 10.236.87.1 + neighbor upstream peer-group + neighbor upstream remote-as 64515 + neighbor upstream capability dynamic + neighbor 10.1.1.1 peer-group upstream + neighbor 10.1.1.1 description ACME ISP + + address-family ipv4 unicast + network 10.236.87.0/24 + neighbor upstream prefix-list pl-allowed-adv out + exit-address-family + ! + ip prefix-list pl-allowed-adv seq 5 permit 82.195.133.0/25 + ip prefix-list pl-allowed-adv seq 10 deny any + + + +A more complex example. With upstream, peer and customer sessions. +Advertising global prefixes and NO_EXPORT prefixes and providing +actions for customer routes based on community values. Extensive use of +route-maps and the 'call' feature to support selective advertising of +prefixes. This example is intended as guidance only, it has NOT been +tested and almost certainly containts silly mistakes, if not serious +flaws. + +:: + + router bgp 64512 + bgp router-id 10.236.87.1 + neighbor upstream capability dynamic + neighbor cust capability dynamic + neighbor peer capability dynamic + neighbor 10.1.1.1 remote-as 64515 + neighbor 10.1.1.1 peer-group upstream + neighbor 10.2.1.1 remote-as 64516 + neighbor 10.2.1.1 peer-group upstream + neighbor 10.3.1.1 remote-as 64517 + neighbor 10.3.1.1 peer-group cust-default + neighbor 10.3.1.1 description customer1 + neighbor 10.4.1.1 remote-as 64518 + neighbor 10.4.1.1 peer-group cust + neighbor 10.4.1.1 description customer2 + neighbor 10.5.1.1 remote-as 64519 + neighbor 10.5.1.1 peer-group peer + neighbor 10.5.1.1 description peer AS 1 + neighbor 10.6.1.1 remote-as 64520 + neighbor 10.6.1.1 peer-group peer + neighbor 10.6.1.1 description peer AS 2 + + address-family ipv4 unicast + network 10.123.456.0/24 + network 10.123.456.128/25 route-map rm-no-export + neighbor upstream route-map rm-upstream-out out + neighbor cust route-map rm-cust-in in + neighbor cust route-map rm-cust-out out + neighbor cust send-community both + neighbor peer route-map rm-peer-in in + neighbor peer route-map rm-peer-out out + neighbor peer send-community both + neighbor 10.3.1.1 prefix-list pl-cust1-network in + neighbor 10.4.1.1 prefix-list pl-cust2-network in + neighbor 10.5.1.1 prefix-list pl-peer1-network in + neighbor 10.6.1.1 prefix-list pl-peer2-network in + exit-address-family + ! + ip prefix-list pl-default permit 0.0.0.0/0 + ! + ip prefix-list pl-upstream-peers permit 10.1.1.1/32 + ip prefix-list pl-upstream-peers permit 10.2.1.1/32 + ! + ip prefix-list pl-cust1-network permit 10.3.1.0/24 + ip prefix-list pl-cust1-network permit 10.3.2.0/24 + ! + ip prefix-list pl-cust2-network permit 10.4.1.0/24 + ! + ip prefix-list pl-peer1-network permit 10.5.1.0/24 + ip prefix-list pl-peer1-network permit 10.5.2.0/24 + ip prefix-list pl-peer1-network permit 192.168.0.0/24 + ! + ip prefix-list pl-peer2-network permit 10.6.1.0/24 + ip prefix-list pl-peer2-network permit 10.6.2.0/24 + ip prefix-list pl-peer2-network permit 192.168.1.0/24 + ip prefix-list pl-peer2-network permit 192.168.2.0/24 + ip prefix-list pl-peer2-network permit 172.16.1/24 + ! + ip as-path access-list asp-own-as permit ^$ + ip as-path access-list asp-own-as permit _64512_ + ! + ! ################################################################# + ! Match communities we provide actions for, on routes receives from + ! customers. Communities values of :X, with X, have actions: + ! + ! 100 - blackhole the prefix + ! 200 - set no_export + ! 300 - advertise only to other customers + ! 400 - advertise only to upstreams + ! 500 - set no_export when advertising to upstreams + ! 2X00 - set local_preference to X00 + ! + ! blackhole the prefix of the route + ip community-list standard cm-blackhole permit 64512:100 + ! + ! set no-export community before advertising + ip community-list standard cm-set-no-export permit 64512:200 + ! + ! advertise only to other customers + ip community-list standard cm-cust-only permit 64512:300 + ! + ! advertise only to upstreams + ip community-list standard cm-upstream-only permit 64512:400 + ! + ! advertise to upstreams with no-export + ip community-list standard cm-upstream-noexport permit 64512:500 + ! + ! set local-pref to least significant 3 digits of the community + ip community-list standard cm-prefmod-100 permit 64512:2100 + ip community-list standard cm-prefmod-200 permit 64512:2200 + ip community-list standard cm-prefmod-300 permit 64512:2300 + ip community-list standard cm-prefmod-400 permit 64512:2400 + ip community-list expanded cme-prefmod-range permit 64512:2... + ! + ! Informational communities + ! + ! 3000 - learned from upstream + ! 3100 - learned from customer + ! 3200 - learned from peer + ! + ip community-list standard cm-learnt-upstream permit 64512:3000 + ip community-list standard cm-learnt-cust permit 64512:3100 + ip community-list standard cm-learnt-peer permit 64512:3200 + ! + ! ################################################################### + ! Utility route-maps + ! + ! These utility route-maps generally should not used to permit/deny + ! routes, i.e. they do not have meaning as filters, and hence probably + ! should be used with 'on-match next'. These all finish with an empty + ! permit entry so as not interfere with processing in the caller. + ! + route-map rm-no-export permit 10 + set community additive no-export + route-map rm-no-export permit 20 + ! + route-map rm-blackhole permit 10 + description blackhole, up-pref and ensure it cant escape this AS + set ip next-hop 127.0.0.1 + set local-preference 10 + set community additive no-export + route-map rm-blackhole permit 20 + ! + ! Set local-pref as requested + route-map rm-prefmod permit 10 + match community cm-prefmod-100 + set local-preference 100 + route-map rm-prefmod permit 20 + match community cm-prefmod-200 + set local-preference 200 + route-map rm-prefmod permit 30 + match community cm-prefmod-300 + set local-preference 300 + route-map rm-prefmod permit 40 + match community cm-prefmod-400 + set local-preference 400 + route-map rm-prefmod permit 50 + ! + ! Community actions to take on receipt of route. + route-map rm-community-in permit 10 + description check for blackholing, no point continuing if it matches. + match community cm-blackhole + call rm-blackhole + route-map rm-community-in permit 20 + match community cm-set-no-export + call rm-no-export + on-match next + route-map rm-community-in permit 30 + match community cme-prefmod-range + call rm-prefmod + route-map rm-community-in permit 40 + ! + ! ##################################################################### + ! Community actions to take when advertising a route. + ! These are filtering route-maps, + ! + ! Deny customer routes to upstream with cust-only set. + route-map rm-community-filt-to-upstream deny 10 + match community cm-learnt-cust + match community cm-cust-only + route-map rm-community-filt-to-upstream permit 20 + ! + ! Deny customer routes to other customers with upstream-only set. + route-map rm-community-filt-to-cust deny 10 + match community cm-learnt-cust + match community cm-upstream-only + route-map rm-community-filt-to-cust permit 20 + ! + ! ################################################################### + ! The top-level route-maps applied to sessions. Further entries could + ! be added obviously.. + ! + ! Customers + route-map rm-cust-in permit 10 + call rm-community-in + on-match next + route-map rm-cust-in permit 20 + set community additive 64512:3100 + route-map rm-cust-in permit 30 + ! + route-map rm-cust-out permit 10 + call rm-community-filt-to-cust + on-match next + route-map rm-cust-out permit 20 + ! + ! Upstream transit ASes + route-map rm-upstream-out permit 10 + description filter customer prefixes which are marked cust-only + call rm-community-filt-to-upstream + on-match next + route-map rm-upstream-out permit 20 + description only customer routes are provided to upstreams/peers + match community cm-learnt-cust + ! + ! Peer ASes + ! outbound policy is same as for upstream + route-map rm-peer-out permit 10 + call rm-upstream-out + ! + route-map rm-peer-in permit 10 + set community additive 64512:3200 + + +@include rpki.texi diff --git a/doc/user/conf.py b/doc/user/conf.py new file mode 100644 index 0000000000..ebb8b828a1 --- /dev/null +++ b/doc/user/conf.py @@ -0,0 +1,293 @@ +# -*- coding: utf-8 -*- +# +# FRR documentation build configuration file, created by +# sphinx-quickstart on Tue Jan 31 16:00:52 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import re + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.todo'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'FRR' +copyright = u'2017, FRR' +author = u'FRR' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +# The short X.Y version. +version = u'?.?' +# The full version, including alpha/beta/rc tags. +release = u'?.?-?' + +val = re.compile('^S\["([^"]+)"\]="(.*)"$') +with open('../../config.status', 'r') as cfgstatus: + for ln in cfgstatus.readlines(): + m = val.match(ln) + if m is None: continue + if m.group(1) == 'PACKAGE_VERSION': + release = m.group(2) + version = release.split('-')[0] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'FRRdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'FRR.tex', u'FRR User Manual', + u'FRR', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'frr', u'FRR User Manual', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'FRR', u'FRR User Manual', + author, 'FRR', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/doc/user/defines.rst b/doc/user/defines.rst new file mode 100644 index 0000000000..014d66d0e8 --- /dev/null +++ b/doc/user/defines.rst @@ -0,0 +1,24 @@ +.. These are substitutions that were used in the original Texinfo docs. + They need to be recreated in RST by way of rst_prolog or a common include. + That, in turn, needs to be generated by make at compile time. + @c -*- texinfo -*- + @c doc/defines.texi. Generated from defines.texi.in by configure. + + @c Set variables + @set PACKAGE_NAME frr + @set PACKAGE_TARNAME frr + @set PACKAGE_STRING frr 3.1-dev + @set PACKAGE_URL https://frrouting.org/ + @set PACKAGE_VERSION 3.1-dev + @set AUTHORS Kunihiro Ishiguro, et al. + @set COPYRIGHT_YEAR 1999-2005 + @set COPYRIGHT_STR Copyright @copyright{} @value{COPYRIGHT_YEAR} @value{AUTHORS} + + @c These may vary with installation environment. + @set INSTALL_PREFIX_ETC /etc/frr + @set INSTALL_PREFIX_SBIN /usr/lib/frr + @set INSTALL_PREFIX_STATE /var/run/frr + @set INSTALL_PREFIX_MODULES /usr/lib/frr/modules + @set INSTALL_USER frr + @set INSTALL_GROUP frr + @set INSTALL_VTY_GROUP frrvty diff --git a/doc/user/eigrpd.rst b/doc/user/eigrpd.rst new file mode 100644 index 0000000000..effec5dc1e --- /dev/null +++ b/doc/user/eigrpd.rst @@ -0,0 +1,257 @@ +.. _EIGRP: + +***** +EIGRP +***** + +EIGRP -- Routing Information Protocol is widely deployed interior gateway +routing protocol. EIGRP was developed in the 1990's. EIGRP is a +@dfn{distance-vector} protocol and is based on the @dfn{dual} algorithms. +As a distance-vector protocol, the EIGRP router send updates to its +neighbors as networks change, thus allowing the convergence to a +known topology. + +*eigrpd* supports EIGRP as described in RFC7868 + +.. _Starting_and_Stopping_eigrpd: + +Starting and Stopping eigrpd +============================ + +The default configuration file name of *eigrpd*'s is +:file:`eigrpd.conf`. When invocation *eigrpd* searches directory +@value{INSTALL_PREFIX_ETC}. If :file:`eigrpd.conf` is not there next +search current directory. If an integrated config is specified +configuration is written into frr.conf + +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 like below: + +:: + + @group + # zebra -d + # eigrpd -d + @end group + + +Please note that *zebra* must be invoked before *eigrpd*. + +To stop *eigrpd*. Please use @command{kill `cat +/var/run/eigrpd.pid`}. Certain signals have special meanings to *eigrpd*. + + + +*SIGHUP* + +*SIGUSR1* + Rotate *eigrpd* Rotate the logfile. + +*SIGINT* + +*SIGTERM* + *eigrpd* sweeps all installed EIGRP routes then terminates properly. + +*eigrpd* invocation options. Common options that can be specified +(:ref:`Common_Invocation_Options`). + + + +*-r* + +*--retain* + When the program terminates, retain routes added by *eigrpd*. + +.. _EIGRP_Configuration: + +EIGRP Configuration +=================== + +.. index:: Command {router eigrp (1-65535)} {} + +Command {router eigrp (1-65535)} {} + The `router eigrp` command is necessary to enable EIGRP. To disable + EIGRP, use the `no router eigrp (1-65535)` command. EIGRP must be enabled before carrying out any of the EIGRP commands. + +.. index:: Command {no router eigrp (1-65535)} {} + +Command {no router eigrp (1-65535)} {} + Disable EIGRP. + +.. index:: {EIGRP Command} {network `network`} {} + +{EIGRP Command} {network `network`} {} +.. index:: {EIGRP Command} {no network `network`} {} + +{EIGRP Command} {no network `network`} {} + Set the EIGRP enable interface by `network`. The interfaces which + have addresses matching with `network` are enabled. + + This group of commands either enables or disables EIGRP interfaces between + certain numbers of a specified network address. For example, if the + network for 10.0.0.0/24 is EIGRP enabled, this would result in all the + addresses from 10.0.0.0 to 10.0.0.255 being enabled for EIGRP. The `no network` command will disable EIGRP for the specified network. + + Below is very simple EIGRP configuration. Interface `eth0` and + interface which address match to `10.0.0.0/8` are EIGRP enabled. + +:: + + @group + ! + router eigrp 1 + network 10.0.0.0/8 + ! + @end group + + + Passive interface + +.. index:: {EIGRP command} {passive-interface (`IFNAME`|default)} {} + +{EIGRP command} {passive-interface (`IFNAME`|default)} {} +.. index:: {EIGRP command} {no passive-interface `IFNAME`} {} + +{EIGRP command} {no passive-interface `IFNAME`} {} + This command sets the specified interface to passive mode. On passive mode + interface, all receiving packets are ignored and eigrpd does + not send either multicast or unicast EIGRP packets except to EIGRP neighbors + specified with `neighbor` command. The interface may be specified + as `default` to make eigrpd default to passive on all interfaces. + + The default is to be passive on all interfaces. + +.. _How_to_Announce_EIGRP_route: + +How to Announce EIGRP route +=========================== + +.. index:: {EIGRP command} {redistribute kernel} {} + +{EIGRP command} {redistribute kernel} {} +.. index:: {EIGRP command} {redistribute kernel metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} + +{EIGRP command} {redistribute kernel metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} +.. index:: {EIGRP command} {no redistribute kernel} {} + +{EIGRP command} {no redistribute kernel} {} + `redistribute kernel` redistributes routing information from + kernel route entries into the EIGRP tables. `no redistribute kernel` + disables the routes. + +.. index:: {EIGRP command} {redistribute static} {} + +{EIGRP command} {redistribute static} {} +.. index:: {EIGRP command} {redistribute static metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} + +{EIGRP command} {redistribute static metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} +.. index:: {EIGRP command} {no redistribute static} {} + +{EIGRP command} {no redistribute static} {} + `redistribute static` redistributes routing information from + static route entries into the EIGRP tables. `no redistribute static` + disables the routes. + +.. index:: {EIGRP command} {redistribute connected} {} + +{EIGRP command} {redistribute connected} {} +.. index:: {EIGRP command} {redistribute connected metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} + +{EIGRP command} {redistribute connected metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} +.. index:: {EIGRP command} {no redistribute connected} {} + +{EIGRP command} {no redistribute connected} {} + Redistribute connected routes into the EIGRP tables. `no redistribute connected` disables the connected routes in the EIGRP tables. + This command redistribute connected of the interface which EIGRP disabled. + The connected route on EIGRP enabled interface is announced by default. + +.. index:: {EIGRP command} {redistribute ospf} {} + +{EIGRP command} {redistribute ospf} {} +.. index:: {EIGRP command} {redistribute ospf metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} + +{EIGRP command} {redistribute ospf metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} +.. index:: {EIGRP command} {no redistribute ospf} {} + +{EIGRP command} {no redistribute ospf} {} + `redistribute ospf` redistributes routing information from + ospf route entries into the EIGRP tables. `no redistribute ospf` + disables the routes. + +.. index:: {EIGRP command} {redistribute bgp} {} + +{EIGRP command} {redistribute bgp} {} +.. index:: {EIGRP command} {redistribute bgp metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} + +{EIGRP command} {redistribute bgp metric (1-4294967295) (0-4294967295) (0-255) (1-255) (1-65535)} {} +.. index:: {EIGRP command} {no redistribute bgp} {} + +{EIGRP command} {no redistribute bgp} {} + `redistribute bgp` redistributes routing information from + bgp route entries into the EIGRP tables. `no redistribute bgp` + disables the routes. + +.. _Show_EIGRP_Information: + +Show EIGRP Information +====================== + +To display EIGRP routes. + +.. index:: Command {show ip eigrp topology} {} + +Command {show ip eigrp topology} {} + Show EIGRP routes. + +The command displays all EIGRP routes. + +.. index:: Command {show ip eigrp topology} {} + +Command {show ip eigrp topology} {} + The command displays current EIGRP status + +:: + + @group + eigrpd> **show ip eigrp topology** + # show ip eigrp topo + + EIGRP Topology Table for AS(4)/ID(0.0.0.0) + + Codes: P - Passive, A - Active, U - Update, Q - Query, R - Reply + r - reply Status, s - sia Status + + P 10.0.2.0/24, 1 successors, FD is 256256, serno: 0 + via Connected, enp0s3 + @end group + + +EIGRP Debug Commands +==================== + +Debug for EIGRP protocol. + +.. index:: Command {debug eigrp packets} {} + +Command {debug eigrp packets} {} + Debug eigrp packets + +`debug eigrp` will show EIGRP packets that are sent and recevied. + +.. index:: Command {debug eigrp transmit} {} + +Command {debug eigrp transmit} {} + Debug eigrp transmit events + +`debug eigrp transmit` will display detailed information about the EIGRP transmit events. + +.. index:: Command {show debugging eigrp} {} + +Command {show debugging eigrp} {} + Display *eigrpd*'s debugging option. + +`show debugging eigrp` will show all information currently set for eigrpd +debug. + diff --git a/doc/user/filter.rst b/doc/user/filter.rst new file mode 100644 index 0000000000..75f5933e7b --- /dev/null +++ b/doc/user/filter.rst @@ -0,0 +1,197 @@ +********* +Filtering +********* + +Frr provides many very flexible filtering features. Filtering is used +for both input and output of the routing information. Once filtering is +defined, it can be applied in any direction. + +@comment node-name, next, previous, up + +IP Access List +============== + +.. index:: {Command} {access-list `name` permit `ipv4-network`} {} + +{Command} {access-list `name` permit `ipv4-network`} {} +.. index:: {Command} {access-list `name` deny `ipv4-network`} {} + +{Command} {access-list `name` deny `ipv4-network`} {} + + Basic filtering is done by `access-list` as shown in the + following example. + +:: + + access-list filter deny 10.0.0.0/9 + access-list filter permit 10.0.0.0/8 + + + @comment node-name, next, previous, up + +IP Prefix List +============== + +*ip prefix-list* provides the most powerful prefix based +filtering mechanism. In addition to *access-list* functionality, +*ip prefix-list* has prefix length range specification and +sequential number specification. You can add or delete prefix based +filters to arbitrary points of prefix-list using sequential number specification. + +If no ip prefix-list is specified, it acts as permit. If *ip prefix-list* +is defined, and no match is found, default deny is applied. + +.. index:: {Command} {ip prefix-list `name` (permit|deny) `prefix` [le `len`] [ge `len`]} {} + +{Command} {ip prefix-list `name` (permit|deny) `prefix` [le `len`] [ge `len`]} {} +.. index:: {Command} {ip prefix-list `name` seq `number` (permit|deny) `prefix` [le `len`] [ge `len`]} {} + +{Command} {ip prefix-list `name` seq `number` (permit|deny) `prefix` [le `len`] [ge `len`]} {} + You can create *ip prefix-list* using above commands. + + + +*@asis{seq}* + seq `number` can be set either automatically or manually. In the + case that sequential numbers are set manually, the user may pick any + number less than 4294967295. In the case that sequential number are set + automatically, the sequential number will increase by a unit of five (5) + per list. If a list with no specified sequential number is created + after a list with a specified sequential number, the list will + automatically pick the next multiple of five (5) as the list number. + For example, if a list with number 2 already exists and a new list with + no specified number is created, the next list will be numbered 5. If + lists 2 and 7 already exist and a new list with no specified number is + created, the new list will be numbered 10. + + +*@asis{le}* + *le* command specifies prefix length. The prefix list will be + applied if the prefix length is less than or equal to the le prefix length. + + +*@asis{ge}* + *ge* command specifies prefix length. The prefix list will be + applied if the prefix length is greater than or equal to the ge prefix length. + + + Less than or equal to prefix numbers and greater than or equal to + prefix numbers can be used together. The order of the le and ge + commands does not matter. + + If a prefix list with a different sequential number but with the exact + same rules as a previous list is created, an error will result. + However, in the case that the sequential number and the rules are + exactly similar, no error will result. + + If a list with the same sequential number as a previous list is created, + the new list will overwrite the old list. + + Matching of IP Prefix is performed from the smaller sequential number to the + larger. The matching will stop once any rule has been applied. + + In the case of no le or ge command, the prefix length must match exactly the + length specified in the prefix list. + +.. index:: {Command} {no ip prefix-list `name`} {} + +{Command} {no ip prefix-list `name`} {} + +.. _ip_prefix-list_description: + +ip prefix-list description +-------------------------- + +.. index:: {Command} {ip prefix-list `name` description `desc`} {} + +{Command} {ip prefix-list `name` description `desc`} {} + Descriptions may be added to prefix lists. This command adds a + description to the prefix list. + +.. index:: {Command} {no ip prefix-list `name` description [`desc`]} {} + +{Command} {no ip prefix-list `name` description [`desc`]} {} + Deletes the description from a prefix list. It is possible to use the + command without the full description. + +.. _ip_prefix-list_sequential_number_control: + +ip prefix-list sequential number control +---------------------------------------- + +.. index:: {Command} {ip prefix-list sequence-number} {} + +{Command} {ip prefix-list sequence-number} {} + With this command, the IP prefix list sequential number is displayed. + This is the default behavior. + +.. index:: {Command} {no ip prefix-list sequence-number} {} + +{Command} {no ip prefix-list sequence-number} {} + With this command, the IP prefix list sequential number is not + displayed. + +.. _Showing_ip_prefix-list: + +Showing ip prefix-list +---------------------- + +.. index:: {Command} {show ip prefix-list} {} + +{Command} {show ip prefix-list} {} + Display all IP prefix lists. + +.. index:: {Command} {show ip prefix-list `name`} {} + +{Command} {show ip prefix-list `name`} {} + Show IP prefix list can be used with a prefix list name. + +.. index:: {Command} {show ip prefix-list `name` seq `num`} {} + +{Command} {show ip prefix-list `name` seq `num`} {} + Show IP prefix list can be used with a prefix list name and sequential + number. + +.. index:: {Command} {show ip prefix-list `name` `a.b.c.d/m`} {} + +{Command} {show ip prefix-list `name` `a.b.c.d/m`} {} + If the command longer is used, all prefix lists with prefix lengths equal to + or longer than the specified length will be displayed. + If the command first match is used, the first prefix length match will be + displayed. + +.. index:: {Command} {show ip prefix-list `name` `a.b.c.d/m` longer} {} + +{Command} {show ip prefix-list `name` `a.b.c.d/m` longer} {} +.. index:: {Command} {show ip prefix-list `name` `a.b.c.d/m` first-match} {} + +{Command} {show ip prefix-list `name` `a.b.c.d/m` first-match} {} +.. index:: {Command} {show ip prefix-list summary} {} + +{Command} {show ip prefix-list summary} {} +.. index:: {Command} {show ip prefix-list summary `name`} {} + +{Command} {show ip prefix-list summary `name`} {} +.. index:: {Command} {show ip prefix-list detail} {} + +{Command} {show ip prefix-list detail} {} +.. index:: {Command} {show ip prefix-list detail `name`} {} + +{Command} {show ip prefix-list detail `name`} {} + +Clear counter of ip prefix-list +------------------------------- + +.. index:: {Command} {clear ip prefix-list} {} + +{Command} {clear ip prefix-list} {} + Clears the counters of all IP prefix lists. Clear IP Prefix List can be + used with a specified name and prefix. + +.. index:: {Command} {clear ip prefix-list `name`} {} + +{Command} {clear ip prefix-list `name`} {} +.. index:: {Command} {clear ip prefix-list `name` `a.b.c.d/m`} {} + +{Command} {clear ip prefix-list `name` `a.b.c.d/m`} {} + diff --git a/doc/user/index.rst b/doc/user/index.rst new file mode 100644 index 0000000000..57225fc250 --- /dev/null +++ b/doc/user/index.rst @@ -0,0 +1,28 @@ +Welcome to FRR's documentation! +=============================== + +.. toctree:: + :maxdepth: 2 + + overview + installation + basic + main + ripd + ripngd + ospfd + ospf6d + isisd + nhrpd + bgp + babeld + routeserver + vnc + vtysh + filter + routemap + ipv6 + kernel + snmp + protocol + diff --git a/doc/user/installation.rst b/doc/user/installation.rst new file mode 100644 index 0000000000..8ede815f7e --- /dev/null +++ b/doc/user/installation.rst @@ -0,0 +1,329 @@ +.. _Installation: + +************ +Installation +************ + +.. index:: How to install FRR + +.. index:: Installation + +.. index:: Installing FRR + +.. index:: Building the system + +.. index:: Making FRR + +There are three steps for installing the software: configuration, +compilation, and installation. + +The easiest way to get FRR running is to issue the following +commands: + +:: + + % configure + % make + % make install + + +.. _Configure_the_Software: + +Configure the Software +====================== + + +.. _The_Configure_script_and_its_options: + +The Configure script and its options +------------------------------------ + +.. index:: Configuration options + +.. index:: Options for configuring + +.. index:: Build options + +.. index:: Distribution configuration + +.. index:: Options to `./configure` + +FRR has an excellent configure script which automatically detects most +host configurations. There are several additional configure options to +customize the build to include or exclude specific features and dependencies. + + + +*--disable-zebra* + Do not build zebra daemon. + +*--disable-ripd* + Do not build ripd. + +*--disable-ripngd* + Do not build ripngd. + +*--disable-ospfd* + Do not build ospfd. + +*--disable-ospf6d* + Do not build ospf6d. + +*--disable-bgpd* + Do not build bgpd. + +*--disable-bgp-announce* + Make *bgpd* which does not make bgp announcements at all. This + feature is good for using *bgpd* as a BGP announcement listener. + +*--enable-datacenter* + Enable system defaults to work as if in a Data Center. See defaults.h + for what is changed by this configure option. + +*--enable-snmp* + Enable SNMP support. By default, SNMP support is disabled. + +*--disable-ospfapi* + Disable support for OSPF-API, an API to interface directly with ospfd. + OSPF-API is enabled if --enable-opaque-lsa is set. + +*--disable-ospfclient* + Disable building of the example OSPF-API client. + +*--disable-ospf-ri* + Disable support for OSPF Router Information (RFC4970 & RFC5088) this + requires support for Opaque LSAs and Traffic Engineering. + +*--disable-isisd* + Do not build isisd. + +*--enable-isis-topology* + Enable IS-IS topology generator. + +*--enable-isis-te* + Enable Traffic Engineering Extension for ISIS (RFC5305) + +*--enable-multipath=`ARG`* + Enable support for Equal Cost Multipath. `ARG` is the maximum number + of ECMP paths to allow, set to 0 to allow unlimited number of paths. + +*--disable-rtadv* + Disable support IPV6 router advertisement in zebra. + +*--enable-gcc-rdynamic* + Pass the *-rdynamic* option to the linker driver. This is in most + cases neccessary for getting usable backtraces. This option defaults to on + if the compiler is detected as gcc, but giving an explicit enable/disable is + suggested. + +*--disable-backtrace* + Controls backtrace support for the crash handlers. This is autodetected by + default. Using the switch will enforce the requested behaviour, failing with + an error if support is requested but not available. On BSD systems, this + needs libexecinfo, while on glibc support for this is part of libc itself. + +*--enable-dev-build* + Turn on some options for compiling FRR within a development environment in + mind. Specifically turn on -g3 -O0 for compiling options and add inclusion + of grammar sandbox. + +*--enable-fuzzing* + Turn on some compile options to allow you to run fuzzing tools + against the system. This tools is intended as a developer + only tool and should not be used for normal operations + +You may specify any combination of the above options to the configure +script. By default, the executables are placed in :file:`/usr/local/sbin` +and the configuration files in :file:`/usr/local/etc`. The :file:`/usr/local/` +installation prefix and other directories may be changed using the following +options to the configuration script. + + + +*--prefix=`prefix`* + Install architecture-independent files in `prefix` [/usr/local]. + +*--sysconfdir=`dir`* + Look for configuration files in `dir` [`prefix`/etc]. Note + that sample configuration files will be installed here. + +*--localstatedir=`dir`* + Configure zebra to use `dir` for local state files, such + as pid files and unix sockets. + +:: + + % ./configure --disable-snmp + + +This command will configure zebra and the routing daemons. + +.. _Least-Privilege_support: + +Least-Privilege support +----------------------- + +.. index:: FRR Least-Privileges + +.. index:: FRR Privileges + +Additionally, you may configure zebra to drop its elevated privileges +shortly after startup and switch to another user. The configure script will +automatically try to configure this support. There are three configure +options to control the behaviour of FRR daemons. + + + +*--enable-user=`user`* + Switch to user `ARG` shortly after startup, and run as user `ARG` + in normal operation. + +*--enable-group=`group`* + Switch real and effective group to `group` shortly after + startup. + +*--enable-vty-group=`group`* + Create Unix Vty sockets (for use with vtysh) with group owndership set to + `group`. This allows one to create a seperate group which is + restricted to accessing only the Vty sockets, hence allowing one to + delegate this group to individual users, or to run vtysh setgid to + this group. + +The default user and group which will be configured is 'frr' if no user +or group is specified. Note that this user or group requires write access to +the local state directory (see --localstatedir) and requires at least read +access, and write access if you wish to allow daemons to write out their +configuration, to the configuration directory (see --sysconfdir). + +On systems which have the 'libcap' capabilities manipulation library +(currently only linux), the frr system will retain only minimal +capabilities required, further it will only raise these capabilities for +brief periods. On systems without libcap, frr will run as the user +specified and only raise its uid back to uid 0 for brief periods. + +.. _Linux_Notes: + +Linux Notes +----------- + +.. index:: Configuring FRR + +.. index:: Building on Linux boxes + +.. index:: Linux configurations + +There are several options available only to GNU/Linux systems: +@footnote{GNU/Linux has very flexible kernel configuration features}. If +you use GNU/Linux, make sure that the current kernel configuration is +what you want. FRR will run with any kernel configuration but some +recommendations do exist. + + + +*CONFIG_NETLINK* + Kernel/User netlink socket. This is a brand new feature which enables an + advanced interface between the Linux kernel and zebra (:ref:`Kernel_Interface`). + + +*CONFIG_RTNETLINK* + Routing messages. + This makes it possible to receive netlink routing messages. If you + specify this option, *zebra* can detect routing information + updates directly from the kernel (:ref:`Kernel_Interface`). + + +*CONFIG_IP_MULTICAST* + IP: multicasting. + This option should be specified when you use *ripd* (:ref:`RIP`) or + *ospfd* (:ref:`OSPFv2`) because these protocols use multicast. + + +IPv6 support has been added in GNU/Linux kernel version 2.2. If you +try to use the FRR IPv6 feature on a GNU/Linux kernel, please +make sure the following libraries have been installed. Please note that +these libraries will not be needed when you uses GNU C library 2.1 +or upper. + + + +*inet6-apps* + The `inet6-apps` package includes basic IPv6 related libraries such + as `inet_ntop` and `inet_pton`. Some basic IPv6 programs such + as *ping*, *ftp*, and *inetd* are also + included. The `inet-apps` can be found at + `ftp://ftp.inner.net/pub/ipv6/ `_. + + +*net-tools* + The `net-tools` package provides an IPv6 enabled interface and + routing utility. It contains *ifconfig*, *route*, + *netstat*, and other tools. `net-tools` may be found at + `http://www.tazenda.demon.co.uk/phil/net-tools/ `_. + + +.. _Build_the_Software: + +Build the Software +================== + +After configuring the software, you will need to compile it for your +system. Simply issue the command *make* in the root of the source +directory and the software will be compiled. Cliff Note versions of +different compilation examples can be found in the doc/Building_FRR_on_XXX.md +files. If you have *any* problems at this stage, be certain to send a +bug report :ref:`Bug_Reports`. + +:: + + % ./bootstrap.sh + % ./configure + % make + + +@comment node-name, next, previous, up + +Install the Software +==================== + +Installing the software to your system consists of copying the compiled +programs and supporting files to a standard location. After the +installation process has completed, these files have been copied +from your work directory to :file:`/usr/local/bin`, and :file:`/usr/local/etc`. + +To install the FRR suite, issue the following command at your shell +prompt: *make install*. + +:: + + % + % make install + % + + +FRR daemons have their own terminal interface or VTY. After +installation, you have to setup each beast's port number to connect to +them. Please add the following entries to :file:`/etc/services`. + +:: + + zebrasrv 2600/tcp # zebra service + zebra 2601/tcp # zebra vty + ripd 2602/tcp # RIPd vty + ripngd 2603/tcp # RIPngd vty + ospfd 2604/tcp # OSPFd vty + bgpd 2605/tcp # BGPd vty + ospf6d 2606/tcp # OSPF6d vty + ospfapi 2607/tcp # ospfapi + isisd 2608/tcp # ISISd vty + nhrpd 2610/tcp # nhrpd vty + pimd 2611/tcp # PIMd vty + + +If you use a FreeBSD newer than 2.2.8, the above entries are already +added to :file:`/etc/services` so there is no need to add it. If you +specify a port number when starting the daemon, these entries may not be +needed. + +You may need to make changes to the config files in +:file:`@value{INSTALL_PREFIX_ETC`/\*.conf}. :ref:`Config_Commands`. + diff --git a/doc/user/ipv6.rst b/doc/user/ipv6.rst new file mode 100644 index 0000000000..5c002467b7 --- /dev/null +++ b/doc/user/ipv6.rst @@ -0,0 +1,229 @@ +.. _IPv6_Support: + +************ +IPv6 Support +************ + +Frr fully supports IPv6 routing. As described so far, Frr supports +RIPng, OSPFv3, and BGP-4+. You can give IPv6 addresses to an interface +and configure static IPv6 routing information. Frr IPv6 also provides +automatic address configuration via a feature called `address auto configuration`. To do it, the router must send router advertisement +messages to the all nodes that exist on the network. + +Previous versions of Frr could be built without IPv6 support. This is +no longer possible. + +Router Advertisement +==================== + +.. index:: {Interface Command} {no ipv6 nd suppress-ra} {} + +{Interface Command} {no ipv6 nd suppress-ra} {} + Send router advertisment messages. + +.. index:: {Interface Command} {ipv6 nd suppress-ra} {} + +{Interface Command} {ipv6 nd suppress-ra} {} + Don't send router advertisment messages. + +.. index:: {Interface Command} {ipv6 nd prefix `ipv6prefix` [`valid-lifetime`] [`preferred-lifetime`] [off-link] [no-autoconfig] [router-address]} {} + +{Interface Command} {ipv6 nd prefix `ipv6prefix` [`valid-lifetime`] [`preferred-lifetime`] [off-link] [no-autoconfig] [router-address]} {} + Configuring the IPv6 prefix to include in router advertisements. Several prefix + specific optional parameters and flags may follow: + + +`` + `valid-lifetime` - the length of time in seconds during what the prefix is + valid for the purpose of on-link determination. Value `infinite` represents + infinity (i.e. a value of all one bits (`0xffffffff`)). + + Range: `<0-4294967295>` Default: `2592000` + + +`` + `preferred-lifetime` - the length of time in seconds during what addresses + generated from the prefix remain preferred. Value `infinite` represents + infinity. + + Range: `<0-4294967295>` Default: `604800` + + +`` + `off-link` - indicates that advertisement makes no statement about on-link or + off-link properties of the prefix. + + Default: not set, i.e. this prefix can be used for on-link determination. + + +`` + `no-autoconfig` - indicates to hosts on the local link that the specified prefix + cannot be used for IPv6 autoconfiguration. + + Default: not set, i.e. prefix can be used for autoconfiguration. + + +`` + `router-address` - indicates to hosts on the local link that the specified + prefix + contains a complete IP address by setting R flag. + + Default: not set, i.e. hosts do not assume a complete IP address is placed. + +.. index:: {Interface Command} {ipv6 nd ra-interval <1-1800>} {} + +{Interface Command} {ipv6 nd ra-interval <1-1800>} {} +.. index:: {Interface Command} {no ipv6 nd ra-interval [<1-1800>]} {} + +{Interface Command} {no ipv6 nd ra-interval [<1-1800>]} {} + The maximum time allowed between sending unsolicited multicast router + advertisements from the interface, in seconds. + + Default: `600` + +.. index:: {Interface Command} {ipv6 nd ra-interval msec <70-1800000>} {} + +{Interface Command} {ipv6 nd ra-interval msec <70-1800000>} {} +.. index:: {Interface Command} {no ipv6 nd ra-interval [msec <70-1800000>]} {} + +{Interface Command} {no ipv6 nd ra-interval [msec <70-1800000>]} {} + The maximum time allowed between sending unsolicited multicast router + advertisements from the interface, in milliseconds. + + Default: `600000` + +.. index:: {Interface Command} {ipv6 nd ra-lifetime <0-9000>} {} + +{Interface Command} {ipv6 nd ra-lifetime <0-9000>} {} +.. index:: {Interface Command} {no ipv6 nd ra-lifetime [<0-9000>]} {} + +{Interface Command} {no ipv6 nd ra-lifetime [<0-9000>]} {} + The value to be placed in the Router Lifetime field of router advertisements + sent from the interface, in seconds. Indicates the usefulness of the router + as a default router on this interface. Setting the value to zero indicates + that the router should not be considered a default router on this interface. + Must be either zero or between value specified with `ipv6 nd ra-interval` + (or default) and 9000 seconds. + + Default: `1800` + +.. index:: {Interface Command} {ipv6 nd reachable-time <1-3600000>} {} + +{Interface Command} {ipv6 nd reachable-time <1-3600000>} {} +.. index:: {Interface Command} {no ipv6 nd reachable-time [<1-3600000>]} {} + +{Interface Command} {no ipv6 nd reachable-time [<1-3600000>]} {} + The value to be placed in the Reachable Time field in the Router Advertisement + messages sent by the router, in milliseconds. The configured time enables the + router to detect unavailable neighbors. The value zero means unspecified (by + this router). + + Default: `0` + +.. index:: {Interface Command} {ipv6 nd managed-config-flag} {} + +{Interface Command} {ipv6 nd managed-config-flag} {} +.. index:: {Interface Command} {no ipv6 nd managed-config-flag} {} + +{Interface Command} {no ipv6 nd managed-config-flag} {} + Set/unset flag in IPv6 router advertisements which indicates to hosts that they + should use managed (stateful) protocol for addresses autoconfiguration in + addition to any addresses autoconfigured using stateless address + autoconfiguration. + + Default: not set + +.. index:: {Interface Command} {ipv6 nd other-config-flag} {} + +{Interface Command} {ipv6 nd other-config-flag} {} +.. index:: {Interface Command} {no ipv6 nd other-config-flag} {} + +{Interface Command} {no ipv6 nd other-config-flag} {} + Set/unset flag in IPv6 router advertisements which indicates to hosts that + they should use administered (stateful) protocol to obtain autoconfiguration + information other than addresses. + + Default: not set + +.. index:: {Interface Command} {ipv6 nd home-agent-config-flag} {} + +{Interface Command} {ipv6 nd home-agent-config-flag} {} +.. index:: {Interface Command} {no ipv6 nd home-agent-config-flag} {} + +{Interface Command} {no ipv6 nd home-agent-config-flag} {} + Set/unset flag in IPv6 router advertisements which indicates to hosts that + the router acts as a Home Agent and includes a Home Agent Option. + + Default: not set + +.. index:: {Interface Command} {ipv6 nd home-agent-preference <0-65535>} {} + +{Interface Command} {ipv6 nd home-agent-preference <0-65535>} {} +.. index:: {Interface Command} {no ipv6 nd home-agent-preference [<0-65535>]} {} + +{Interface Command} {no ipv6 nd home-agent-preference [<0-65535>]} {} + The value to be placed in Home Agent Option, when Home Agent config flag is set, + which indicates to hosts Home Agent preference. The default value of 0 stands + for the lowest preference possible. + + Default: 0 + +.. index:: {Interface Command} {ipv6 nd home-agent-lifetime <0-65520>} {} + +{Interface Command} {ipv6 nd home-agent-lifetime <0-65520>} {} +.. index:: {Interface Command} {no ipv6 nd home-agent-lifetime [<0-65520>]} {} + +{Interface Command} {no ipv6 nd home-agent-lifetime [<0-65520>]} {} + The value to be placed in Home Agent Option, when Home Agent config flag is set, + which indicates to hosts Home Agent Lifetime. The default value of 0 means to + place the current Router Lifetime value. + + Default: 0 + +.. index:: {Interface Command} {ipv6 nd adv-interval-option} {} + +{Interface Command} {ipv6 nd adv-interval-option} {} +.. index:: {Interface Command} {no ipv6 nd adv-interval-option} {} + +{Interface Command} {no ipv6 nd adv-interval-option} {} + Include an Advertisement Interval option which indicates to hosts the maximum time, + in milliseconds, between successive unsolicited Router Advertisements. + + Default: not set + +.. index:: {Interface Command} {ipv6 nd router-preference (high|medium|low)} {} + +{Interface Command} {ipv6 nd router-preference (high|medium|low)} {} +.. index:: {Interface Command} {no ipv6 nd router-preference [(high|medium|low)]} {} + +{Interface Command} {no ipv6 nd router-preference [(high|medium|low)]} {} + Set default router preference in IPv6 router advertisements per RFC4191. + + Default: medium + +.. index:: {Interface Command} {ipv6 nd mtu <1-65535>} {} + +{Interface Command} {ipv6 nd mtu <1-65535>} {} +.. index:: {Interface Command} {no ipv6 nd mtu [<1-65535>]} {} + +{Interface Command} {no ipv6 nd mtu [<1-65535>]} {} + Include an MTU (type 5) option in each RA packet to assist the attached hosts + in proper interface configuration. The announced value is not verified to be + consistent with router interface MTU. + + Default: don't advertise any MTU option + +:: + + @group + interface eth0 + no ipv6 nd suppress-ra + ipv6 nd prefix 2001:0DB8:5009::/64 + @end group + + + For more information see @cite{RFC2462 (IPv6 Stateless Address Autoconfiguration)} + , @cite{RFC4861 (Neighbor Discovery for IP Version 6 (IPv6))} + , @cite{RFC6275 (Mobility Support in IPv6)} + and @cite{RFC4191 (Default Router Preferences and More-Specific Routes)}. + diff --git a/doc/user/isisd.rst b/doc/user/isisd.rst new file mode 100644 index 0000000000..667af96057 --- /dev/null +++ b/doc/user/isisd.rst @@ -0,0 +1,641 @@ +.. _ISIS: + +**** +ISIS +**** + +@acronym{ISIS,Intermediate System to Intermediate System} is a routing protocol +which is described in @cite{ISO10589, RFC1195, RFC5308}. ISIS is an +@acronym{IGP,Interior Gateway Protocol}. Compared with @acronym{RIP}, +@acronym{ISIS} can provide scalable network support and faster +convergence times like @acronym{OSPF}. ISIS is widely used in large networks such as +@acronym{ISP,Internet Service Provider} and carrier backbone networks. + +.. _Configuring_isisd: + +Configuring isisd +================= + +There are no *isisd* specific options. Common options can be +specified (:ref:`Common_Invocation_Options`) to *isisd*. +*isisd* needs to acquire 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 @acronym{ISIS} +specific configuration file :file:`isisd.conf`. + +.. _ISIS_router: + +ISIS router +=========== + +To start ISIS process you have to specify the ISIS router. As of this +writing, *isisd* does not support multiple ISIS processes. + +.. index:: Command {router isis WORD} {} + +Command {router isis WORD} {} +.. index:: Command {no router isis WORD} {} + +Command {no router isis WORD} {} + .. _router_isis_WORD: + + Enable or disable the ISIS process by specifying the ISIS domain with 'WORD'. + *isisd* does not yet support multiple ISIS processes but you must specify + the name of ISIS process. The ISIS process name 'WORD' is then used for interface + (see command :ref:`ip_router_isis_WORD`). + +.. index:: {ISIS Command} {net XX.XXXX. ... .XXX.XX} {} + +{ISIS Command} {net XX.XXXX. ... .XXX.XX} {} +.. index:: {ISIS Command} {no net XX.XXXX. ... .XXX.XX} {} + +{ISIS Command} {no net XX.XXXX. ... .XXX.XX} {} + Set/Unset network entity title (NET) provided in ISO format. + +.. index:: {ISIS Command} {hostname dynamic} {} + +{ISIS Command} {hostname dynamic} {} +.. index:: {ISIS Command} {no hostname dynamic} {} + +{ISIS Command} {no hostname dynamic} {} + Enable support for dynamic hostname. + +.. index:: {ISIS Command} {area-password [clear | md5] } {} + +{ISIS Command} {area-password [clear | md5] } {} +.. index:: {ISIS Command} {domain-password [clear | md5] } {} + +{ISIS Command} {domain-password [clear | md5] } {} +.. index:: {ISIS Command} {no area-password} {} + +{ISIS Command} {no area-password} {} +.. index:: {ISIS Command} {no domain-password} {} + +{ISIS Command} {no domain-password} {} + Configure the authentication password for an area, respectively a domain, + as clear text or md5 one. + +.. index:: {ISIS Command} {log-adjacency-changes} {} + +{ISIS Command} {log-adjacency-changes} {} +.. index:: {ISIS Command} {no log-adjacency-changes} {} + +{ISIS Command} {no log-adjacency-changes} {} + Log changes in adjacency state. + +.. index:: {ISIS Command} {metric-style [narrow | transition | wide]} {} + +{ISIS Command} {metric-style [narrow | transition | wide]} {} +.. index:: {ISIS Command} {no metric-style} {} + +{ISIS Command} {no metric-style} {} + .. _metric-style: + + Set old-style (ISO 10589) or new-style packet formats: + - narrow Use old style of TLVs with narrow metric + - transition Send and accept both styles of TLVs during transition + - wide Use new style of TLVs to carry wider metric + +.. index:: {ISIS Command} {set-overload-bit} {} + +{ISIS Command} {set-overload-bit} {} +.. index:: {ISIS Command} {no set-overload-bit} {} + +{ISIS Command} {no set-overload-bit} {} + Set overload bit to avoid any transit traffic. + +.. _ISIS_Timer: + +ISIS Timer +========== + +.. index:: {ISIS Command} {lsp-gen-interval <1-120>} {} + +{ISIS Command} {lsp-gen-interval <1-120>} {} +.. index:: {ISIS Command} {lsp-gen-interval [level-1 | level-2] <1-120>} {} + +{ISIS Command} {lsp-gen-interval [level-1 | level-2] <1-120>} {} +.. index:: {ISIS Command} {no lsp-gen-interval} {} + +{ISIS Command} {no lsp-gen-interval} {} +.. index:: {ISIS Command} {no lsp-gen-interval [level-1 | level-2]} {} + +{ISIS Command} {no lsp-gen-interval [level-1 | level-2]} {} + Set minimum interval in seconds between regenerating same LSP, + globally, for an area (level-1) or a domain (level-2). + +.. index:: {ISIS Command} {lsp-refresh-interval <1-65235>} {} + +{ISIS Command} {lsp-refresh-interval <1-65235>} {} +.. index:: {ISIS Command} {lsp-refresh-interval [level-1 | level-2] <1-65235>} {} + +{ISIS Command} {lsp-refresh-interval [level-1 | level-2] <1-65235>} {} +.. index:: {ISIS Command} {no lsp-refresh-interval} {} + +{ISIS Command} {no lsp-refresh-interval} {} +.. index:: {ISIS Command} {no lsp-refresh-interval [level-1 | level-2]} {} + +{ISIS Command} {no lsp-refresh-interval [level-1 | level-2]} {} + Set LSP refresh interval in seconds, globally, for an area (level-1) or a domain (level-2). + +.. index:: {ISIS Command} {lsp-refresh-interval <1-65235>} {} + +{ISIS Command} {lsp-refresh-interval <1-65235>} {} +.. index:: {ISIS Command} {lsp-refresh-interval [level-1 | level-2] <1-65235>} {} + +{ISIS Command} {lsp-refresh-interval [level-1 | level-2] <1-65235>} {} +.. index:: {ISIS Command} {no lsp-refresh-interval} {} + +{ISIS Command} {no lsp-refresh-interval} {} +.. index:: {ISIS Command} {no lsp-refresh-interval [level-1 | level-2]} {} + +{ISIS Command} {no lsp-refresh-interval [level-1 | level-2]} {} + Set LSP refresh interval in seconds, globally, for an area (level-1) or a domain (level-2). + +.. index:: {ISIS Command} {max-lsp-lifetime <360-65535>} {} + +{ISIS Command} {max-lsp-lifetime <360-65535>} {} +.. index:: {ISIS Command} {max-lsp-lifetime [level-1 | level-2] <360-65535>} {} + +{ISIS Command} {max-lsp-lifetime [level-1 | level-2] <360-65535>} {} +.. index:: {ISIS Command} {no max-lsp-lifetime} {} + +{ISIS Command} {no max-lsp-lifetime} {} +.. index:: {ISIS Command} {no max-lsp-lifetime [level-1 | level-2]} {} + +{ISIS Command} {no max-lsp-lifetime [level-1 | level-2]} {} + Set LSP maximum LSP lifetime in seconds, globally, for an area (level-1) or a domain (level-2). + +.. index:: {ISIS Command} {spf-interval <1-120>} {} + +{ISIS Command} {spf-interval <1-120>} {} +.. index:: {ISIS Command} {spf-interval [level-1 | level-2] <1-120>} {} + +{ISIS Command} {spf-interval [level-1 | level-2] <1-120>} {} +.. index:: {ISIS Command} {no spf-interval} {} + +{ISIS Command} {no spf-interval} {} +.. index:: {ISIS Command} {no spf-interval [level-1 | level-2]} {} + +{ISIS Command} {no spf-interval [level-1 | level-2]} {} + Set minimum interval between consecutive SPF calculations in seconds. + +.. _ISIS_region: + +ISIS region +=========== + +.. index:: {ISIS Command} {is-type [level-1 | level-1-2 | level-2-only]} {} + +{ISIS Command} {is-type [level-1 | level-1-2 | level-2-only]} {} +.. index:: {ISIS Command} {no is-type} {} + +{ISIS Command} {no is-type} {} + Define the ISIS router behavior: + - level-1 Act as a station router only + - level-1-2 Act as both a station router and an area router + - level-2-only Act as an area router only + +.. _ISIS_interface: + +ISIS interface +============== + +.. index:: {Interface Command} {ip router isis WORD} {} + +{Interface Command} {ip router isis WORD} {} +.. index:: {Interface Command} {no ip router isis WORD} {} + +{Interface Command} {no ip router isis WORD} {} + .. _ip_router_isis_WORD: + + Activate ISIS adjacency on this interface. Note that the name + of ISIS instance must be the same as the one used to configure the ISIS process + (see command :ref:`router_isis_WORD`). + +.. index:: {Interface Command} {isis circuit-type [level-1 | level-1-2 | level-2]} {} + +{Interface Command} {isis circuit-type [level-1 | level-1-2 | level-2]} {} +.. index:: {Interface Command} {no isis circuit-type} {} + +{Interface Command} {no isis circuit-type} {} + Configure circuit type for interface: + - level-1 Level-1 only adjacencies are formed + - level-1-2 Level-1-2 adjacencies are formed + - level-2-only Level-2 only adjacencies are formed + +.. index:: {Interface Command} {isis csnp-interval <1-600>} {} + +{Interface Command} {isis csnp-interval <1-600>} {} +.. index:: {Interface Command} {isis csnp-interval <1-600> [level-1 | level-2]} {} + +{Interface Command} {isis csnp-interval <1-600> [level-1 | level-2]} {} +.. index:: {Interface Command} {no isis csnp-interval} {} + +{Interface Command} {no isis csnp-interval} {} +.. index:: {Interface Command} {no isis csnp-interval [level-1 | level-2]} {} + +{Interface Command} {no isis csnp-interval [level-1 | level-2]} {} + Set CSNP interval in seconds globally, for an area (level-1) or a domain (level-2). + +.. index:: {Interface Command} {isis hello padding} {} + +{Interface Command} {isis hello padding} {} + Add padding to IS-IS hello packets. + +.. index:: {Interface Command} {isis hello-interval <1-600>} {} + +{Interface Command} {isis hello-interval <1-600>} {} +.. index:: {Interface Command} {isis hello-interval <1-600> [level-1 | level-2]} {} + +{Interface Command} {isis hello-interval <1-600> [level-1 | level-2]} {} +.. index:: {Interface Command} {no isis hello-interval} {} + +{Interface Command} {no isis hello-interval} {} +.. index:: {Interface Command} {no isis hello-interval [level-1 | level-2]} {} + +{Interface Command} {no isis hello-interval [level-1 | level-2]} {} + Set Hello interval in seconds globally, for an area (level-1) or a domain (level-2). + +.. index:: {Interface Command} {isis hello-multiplier <2-100>} {} + +{Interface Command} {isis hello-multiplier <2-100>} {} +.. index:: {Interface Command} {isis hello-multiplier <2-100> [level-1 | level-2]} {} + +{Interface Command} {isis hello-multiplier <2-100> [level-1 | level-2]} {} +.. index:: {Interface Command} {no isis hello-multiplier} {} + +{Interface Command} {no isis hello-multiplier} {} +.. index:: {Interface Command} {no isis hello-multiplier [level-1 | level-2]} {} + +{Interface Command} {no isis hello-multiplier [level-1 | level-2]} {} + Set multiplier for Hello holding time globally, for an area (level-1) or a domain (level-2). + +.. index:: {Interface Command} {isis metric [<0-255> | <0-16777215>]} {} + +{Interface Command} {isis metric [<0-255> | <0-16777215>]} {} +.. index:: {Interface Command} {isis metric [<0-255> | <0-16777215>] [level-1 | level-2]} {} + +{Interface Command} {isis metric [<0-255> | <0-16777215>] [level-1 | level-2]} {} +.. index:: {Interface Command} {no isis metric} {} + +{Interface Command} {no isis metric} {} +.. index:: {Interface Command} {no isis metric [level-1 | level-2]} {} + +{Interface Command} {no isis metric [level-1 | level-2]} {} + Set default metric value globally, for an area (level-1) or a domain (level-2). + Max value depend if metric support narrow or wide value (see command :ref:`metric-style`). + +.. index:: {Interface Command} {isis network point-to-point} {} + +{Interface Command} {isis network point-to-point} {} +.. index:: {Interface Command} {no isis network point-to-point} {} + +{Interface Command} {no isis network point-to-point} {} + Set network type to 'Point-to-Point' (broadcast by default). + +.. index:: {Interface Command} {isis passive} {} + +{Interface Command} {isis passive} {} +.. index:: {Interface Command} {no isis passive} {} + +{Interface Command} {no isis passive} {} + Configure the passive mode for this interface. + +.. index:: {Interface Command} {isis password [clear | md5] } {} + +{Interface Command} {isis password [clear | md5] } {} +.. index:: {Interface Command} {no isis password} {} + +{Interface Command} {no isis password} {} + Configure the authentication password (clear or encoded text) for the interface. + +.. index:: {Interface Command} {isis priority <0-127>} {} + +{Interface Command} {isis priority <0-127>} {} +.. index:: {Interface Command} {isis priority <0-127> [level-1 | level-2]} {} + +{Interface Command} {isis priority <0-127> [level-1 | level-2]} {} +.. index:: {Interface Command} {no isis priority} {} + +{Interface Command} {no isis priority} {} +.. index:: {Interface Command} {no isis priority [level-1 | level-2]} {} + +{Interface Command} {no isis priority [level-1 | level-2]} {} + Set priority for Designated Router election, globally, for the area (level-1) + or the domain (level-2). + +.. index:: {Interface Command} {isis psnp-interval <1-120>} {} + +{Interface Command} {isis psnp-interval <1-120>} {} +.. index:: {Interface Command} {isis psnp-interval <1-120> [level-1 | level-2]} {} + +{Interface Command} {isis psnp-interval <1-120> [level-1 | level-2]} {} +.. index:: {Interface Command} {no isis psnp-interval} {} + +{Interface Command} {no isis psnp-interval} {} +.. index:: {Interface Command} {no isis psnp-interval [level-1 | level-2]} {} + +{Interface Command} {no isis psnp-interval [level-1 | level-2]} {} + Set PSNP interval in seconds globally, for an area (level-1) or a domain (level-2). + +.. _Showing_ISIS_information: + +Showing ISIS information +======================== + +.. index:: {Command} {show isis summary} {} + +{Command} {show isis summary} {} + Show summary information about ISIS. + +.. index:: {Command} {show isis hostname} {} + +{Command} {show isis hostname} {} + Show information about ISIS node. + +.. index:: {Command} {show isis interface} {} + +{Command} {show isis interface} {} +.. index:: {Command} {show isis interface detail} {} + +{Command} {show isis interface detail} {} +.. index:: {Command} {show isis interface } {} + +{Command} {show isis interface } {} + Show state and configuration of ISIS specified interface, or all + interfaces if no interface is given with or without details. + +.. index:: {Command} {show isis neighbor} {} + +{Command} {show isis neighbor} {} +.. index:: {Command} {show isis neighbor } {} + +{Command} {show isis neighbor } {} +.. index:: {Command} {show isis neighbor detail} {} + +{Command} {show isis neighbor detail} {} + Show state and information of ISIS specified neighbor, or all + neighbors if no system id is given with or without details. + +.. index:: {Command} {show isis database} {} + +{Command} {show isis database} {} +.. index:: {Command} {show isis database [detail]} {} + +{Command} {show isis database [detail]} {} +.. index:: {Command} {show isis database [detail]} {} + +{Command} {show isis database [detail]} {} +.. index:: {Command} {show isis database detail } {} + +{Command} {show isis database detail } {} + Show the ISIS database globally, for a specific LSP id without or with details. + +.. index:: {Command} {show isis topology} {} + +{Command} {show isis topology} {} +.. index:: {Command} {show isis topology [level-1|level-2]} {} + +{Command} {show isis topology [level-1|level-2]} {} + Show topology IS-IS paths to Intermediate Systems, globally, + in area (level-1) or domain (level-2). + +.. index:: {Command} {show ip route isis} {} + +{Command} {show ip route isis} {} + Show the ISIS routing table, as determined by the most recent SPF calculation. + +.. _Traffic_Engineering: + +Traffic Engineering +=================== + +.. index:: {ISIS Command} {mpls-te on} {} + +{ISIS Command} {mpls-te on} {} +.. index:: {ISIS Command} {no mpls-te} {} + +{ISIS Command} {no mpls-te} {} + Enable Traffic Engineering LSP flooding. + +.. index:: {ISIS Command} {mpls-te router-address } {} + +{ISIS Command} {mpls-te router-address } {} +.. index:: {ISIS Command} {no mpls-te router-address} {} + +{ISIS Command} {no mpls-te router-address} {} + Configure stable IP address for MPLS-TE. + +.. index:: {Command} {show isis mpls-te interface} {} + +{Command} {show isis mpls-te interface} {} +.. index:: {Command} {show isis mpls-te interface `interface`} {} + +{Command} {show isis mpls-te interface `interface`} {} + Show MPLS Traffic Engineering parameters for all or specified interface. + +.. index:: {Command} {show isis mpls-te router} {} + +{Command} {show isis mpls-te router} {} + Show Traffic Engineering router parameters. + +.. _Debugging_ISIS: + +Debugging ISIS +============== + +.. index:: {Command} {debug isis adj-packets} {} + +{Command} {debug isis adj-packets} {} +.. index:: {Command} {no debug isis adj-packets} {} + +{Command} {no debug isis adj-packets} {} + IS-IS Adjacency related packets. + +.. index:: {Command} {debug isis checksum-errors} {} + +{Command} {debug isis checksum-errors} {} +.. index:: {Command} {no debug isis checksum-errors} {} + +{Command} {no debug isis checksum-errors} {} + IS-IS LSP checksum errors. + +.. index:: {Command} {debug isis events} {} + +{Command} {debug isis events} {} +.. index:: {Command} {no debug isis events} {} + +{Command} {no debug isis events} {} + IS-IS Events. + +.. index:: {Command} {debug isis local-updates} {} + +{Command} {debug isis local-updates} {} +.. index:: {Command} {no debug isis local-updates} {} + +{Command} {no debug isis local-updates} {} + IS-IS local update packets. + +.. index:: {Command} {debug isis packet-dump} {} + +{Command} {debug isis packet-dump} {} +.. index:: {Command} {no debug isis packet-dump} {} + +{Command} {no debug isis packet-dump} {} + IS-IS packet dump. + +.. index:: {Command} {debug isis protocol-errors} {} + +{Command} {debug isis protocol-errors} {} +.. index:: {Command} {no debug isis protocol-errors} {} + +{Command} {no debug isis protocol-errors} {} + IS-IS LSP protocol errors. + +.. index:: {Command} {debug isis route-events} {} + +{Command} {debug isis route-events} {} +.. index:: {Command} {no debug isis route-events} {} + +{Command} {no debug isis route-events} {} + IS-IS Route related events. + +.. index:: {Command} {debug isis snp-packets} {} + +{Command} {debug isis snp-packets} {} +.. index:: {Command} {no debug isis snp-packets} {} + +{Command} {no debug isis snp-packets} {} + IS-IS CSNP/PSNP packets. + +.. index:: {Command} {debug isis spf-events} {} + +{Command} {debug isis spf-events} {} +.. index:: {Command} {debug isis spf-statistics} {} + +{Command} {debug isis spf-statistics} {} +.. index:: {Command} {debug isis spf-triggers} {} + +{Command} {debug isis spf-triggers} {} +.. index:: {Command} {no debug isis spf-events} {} + +{Command} {no debug isis spf-events} {} +.. index:: {Command} {no debug isis spf-statistics} {} + +{Command} {no debug isis spf-statistics} {} +.. index:: {Command} {no debug isis spf-triggers} {} + +{Command} {no debug isis spf-triggers} {} + IS-IS Shortest Path First Events, Timing and Statistic Data + and triggering events. + +.. index:: {Command} {debug isis update-packets} {} + +{Command} {debug isis update-packets} {} +.. index:: {Command} {no debug isis update-packets} {} + +{Command} {no debug isis update-packets} {} + Update related packets. + +.. index:: {Command} {show debugging isis} {} + +{Command} {show debugging isis} {} + Print which ISIS debug level is activate. + +ISIS Configuration Examples +=========================== + +A simple example, with MD5 authentication enabled: + +:: + + @group + ! + interface eth0 + ip router isis FOO + isis network point-to-point + isis circuit-type level-2-only + ! + router isis FOO + net 47.0023.0000.0000.0000.0000.0000.0000.1900.0004.00 + metric-style wide + is-type level-2-only + @end group + + +A Traffic Engineering configuration, with Inter-ASv2 support. + +- First, the 'zebra.conf' part: + +:: + + @group + hostname HOSTNAME + password PASSWORD + log file /var/log/zebra.log + ! + interface eth0 + ip address 10.2.2.2/24 + mpls-te on + mpls-te link metric 10 + mpls-te link max-bw 1.25e+06 + mpls-te link max-rsv-bw 1.25e+06 + mpls-te link unrsv-bw 0 1.25e+06 + mpls-te link unrsv-bw 1 1.25e+06 + mpls-te link unrsv-bw 2 1.25e+06 + mpls-te link unrsv-bw 3 1.25e+06 + mpls-te link unrsv-bw 4 1.25e+06 + mpls-te link unrsv-bw 5 1.25e+06 + mpls-te link unrsv-bw 6 1.25e+06 + mpls-te link unrsv-bw 7 1.25e+06 + mpls-te link rsc-clsclr 0xab + ! + interface eth1 + ip address 10.1.1.1/24 + mpls-te on + mpls-te link metric 10 + mpls-te link max-bw 1.25e+06 + mpls-te link max-rsv-bw 1.25e+06 + mpls-te link unrsv-bw 0 1.25e+06 + mpls-te link unrsv-bw 1 1.25e+06 + mpls-te link unrsv-bw 2 1.25e+06 + mpls-te link unrsv-bw 3 1.25e+06 + mpls-te link unrsv-bw 4 1.25e+06 + mpls-te link unrsv-bw 5 1.25e+06 + mpls-te link unrsv-bw 6 1.25e+06 + mpls-te link unrsv-bw 7 1.25e+06 + mpls-te link rsc-clsclr 0xab + mpls-te neighbor 10.1.1.2 as 65000 + @end group + + +- Then the 'isisd.conf' itself: + +:: + + @group + hostname HOSTNAME + password PASSWORD + log file /var/log/isisd.log + ! + ! + interface eth0 + ip router isis FOO + ! + interface eth1 + ip router isis FOO + ! + ! + router isis FOO + isis net 47.0023.0000.0000.0000.0000.0000.0000.1900.0004.00 + mpls-te on + mpls-te router-address 10.1.1.1 + ! + line vty + @end group + + diff --git a/doc/user/kernel.rst b/doc/user/kernel.rst new file mode 100644 index 0000000000..04559ffa9a --- /dev/null +++ b/doc/user/kernel.rst @@ -0,0 +1,51 @@ +**************** +Kernel Interface +**************** + +There are several different methods for reading kernel routing table +information, updating kernel routing tables, and for looking up +interfaces. + + + +*ioctl* + The @samp{ioctl} method is a very traditional way for reading or writing + kernel information. @samp{ioctl} can be used for looking up interfaces + and for modifying interface addresses, flags, mtu settings and other + types of information. Also, @samp{ioctl} can insert and delete kernel + routing table entries. It will soon be available on almost any platform + which zebra supports, but it is a little bit ugly thus far, so if a + better method is supported by the kernel, zebra will use that. + + +*sysctl* + @samp{sysctl} can lookup kernel information using MIB (Management + Information Base) syntax. Normally, it only provides a way of getting + information from the kernel. So one would usually want to change kernel + information using another method such as @samp{ioctl}. + + +*proc filesystem* + @samp{proc filesystem} provides an easy way of getting kernel + information. + + +*routing socket* + +*netlink* + On recent Linux kernels (2.0.x and 2.2.x), there is a kernel/user + communication support called `netlink`. It makes asynchronous + communication between kernel and Frr possible, similar to a routing + socket on BSD systems. + + Before you use this feature, be sure to select (in kernel configuration) + the kernel/netlink support option 'Kernel/User network link driver' and + 'Routing messages'. + + Today, the /dev/route special device file is obsolete. Netlink + communication is done by reading/writing over netlink socket. + + After the kernel configuration, please reconfigure and rebuild Frr. + You can use netlink as a dynamic routing update channel between Frr + and the kernel. + diff --git a/doc/user/main.rst b/doc/user/main.rst new file mode 100644 index 0000000000..a48a27d9c1 --- /dev/null +++ b/doc/user/main.rst @@ -0,0 +1,619 @@ +.. _Zebra: + +***** +Zebra +***** + +*zebra* is an IP routing manager. It provides kernel routing +table updates, interface lookups, and redistribution of routes between +different routing protocols. + +.. _Invoking_zebra: + +Invoking zebra +============== + +Besides the common invocation options (:ref:`Common_Invocation_Options`), the +*zebra* specific invocation options are listed below. + + + +*-b* + +*--batch* + Runs in batch mode. *zebra* parses configuration file and terminates + immediately. + + +*-k* + +*--keep_kernel* + When zebra starts up, don't delete old self inserted routes. + + +*-r* + +*--retain* + When program terminates, retain routes added by zebra. + + +.. _Interface_Commands: + +Interface Commands +================== + + +.. _Standard_Commands: + +Standard Commands +----------------- + +.. index:: Command {interface `ifname`} {} + +Command {interface `ifname`} {} + +.. index:: {Interface Command} {shutdown} {} + +{Interface Command} {shutdown} {} +.. index:: {Interface Command} {no shutdown} {} + +{Interface Command} {no shutdown} {} + Up or down the current interface. + +.. index:: {Interface Command} {ip address `address/prefix`} {} + +{Interface Command} {ip address `address/prefix`} {} +.. index:: {Interface Command} {ipv6 address `address/prefix`} {} + +{Interface Command} {ipv6 address `address/prefix`} {} +.. index:: {Interface Command} {no ip address `address/prefix`} {} + +{Interface Command} {no ip address `address/prefix`} {} +.. index:: {Interface Command} {no ipv6 address `address/prefix`} {} + +{Interface Command} {no ipv6 address `address/prefix`} {} + Set the IPv4 or IPv6 address/prefix for the interface. + +.. index:: {Interface Command} {ip address `local-addr` peer `peer-addr/prefix`} {} + +{Interface Command} {ip address `local-addr` peer `peer-addr/prefix`} {} +.. index:: {Interface Command} {no ip address `local-addr` peer `peer-addr/prefix`} {} + +{Interface Command} {no ip address `local-addr` peer `peer-addr/prefix`} {} + Configure an IPv4 Pointopoint address on the interface. + (The concept of PtP addressing does not exist for IPv6.) + + `local-addr` has no subnet mask since the local side in PtP + addressing is always a single (/32) address. `peer-addr/prefix` + can be an arbitrary subnet behind the other end of the link (or even on the + link in Point-to-Multipoint setups), though generally /32s are used. + +.. index:: {Interface Command} {ip address `address/prefix` secondary} {} + +{Interface Command} {ip address `address/prefix` secondary} {} +.. index:: {Interface Command} {no ip address `address/prefix` secondary} {} + +{Interface Command} {no ip address `address/prefix` secondary} {} + Set the secondary flag for this address. This causes ospfd to not treat the + address as a distinct subnet. + +.. index:: {Interface Command} {description `description` ...} {} + +{Interface Command} {description `description` ...} {} + Set description for the interface. + +.. index:: {Interface Command} {multicast} {} + +{Interface Command} {multicast} {} +.. index:: {Interface Command} {no multicast} {} + +{Interface Command} {no multicast} {} + Enable or disables multicast flag for the interface. + +.. index:: {Interface Command} {bandwidth <1-10000000>} {} + +{Interface Command} {bandwidth <1-10000000>} {} +.. index:: {Interface Command} {no bandwidth <1-10000000>} {} + +{Interface Command} {no bandwidth <1-10000000>} {} + Set bandwidth value of the interface in kilobits/sec. This is for + calculating OSPF cost. This command does not affect the actual device + configuration. + +.. index:: {Interface Command} {link-detect} {} + +{Interface Command} {link-detect} {} +.. index:: {Interface Command} {no link-detect} {} + +{Interface Command} {no link-detect} {} + Enable/disable link-detect on platforms which support this. Currently + only Linux and Solaris, and only where network interface drivers support reporting + link-state via the IFF_RUNNING flag. + +.. _Link_Parameters_Commands: + +Link Parameters Commands +------------------------ + +.. index:: {Interface Command} {link-params} {} + +{Interface Command} {link-params} {} +.. index:: {Interface Command} {no link-param} {} + +{Interface Command} {no link-param} {} + Enter into the link parameters sub node. At least 'enable' must be set to activate the link parameters, + and consequently Traffic Engineering on this interface. MPLS-TE must be enable at the OSPF (:ref:`OSPF_Traffic_Engineering`) + or ISIS (:ref:`ISIS_Traffic_Engineering`) router level in complement to this. + Disable link parameters for this interface. + + Under link parameter statement, the following commands set the different TE values: + +.. index:: link-params {enable} + +link-params {enable} + Enable link parameters for this interface. + +.. index:: link-params {metric <0-4294967295>} {} + +link-params {metric <0-4294967295>} {} +.. index:: link-params {max-bw `bandwidth`} {} + +link-params {max-bw `bandwidth`} {} +.. index:: link-params {max-rsv-bw `bandwidth`} {} + +link-params {max-rsv-bw `bandwidth`} {} +.. index:: link-params {unrsv-bw <0-7> `bandwidth`} {} + +link-params {unrsv-bw <0-7> `bandwidth`} {} +.. index:: link-params {admin-grp `bandwidth`} {} + +link-params {admin-grp `bandwidth`} {} + These commands specifies the Traffic Engineering parameters of the interface in conformity to RFC3630 (OSPF) + or RFC5305 (ISIS). + There are respectively the TE Metric (different from the OSPF or ISIS metric), Maximum Bandwidth (interface speed + by default), Maximum Reservable Bandwidth, Unreserved Bandwidth for each 0-7 priority and Admin Group (ISIS) or + Resource Class/Color (OSPF). + + Note that `bandwidth` are specified in IEEE floating point format and express in Bytes/second. + +.. index:: link-param {delay <0-16777215> [min <0-16777215> | max <0-16777215>]} {} + +link-param {delay <0-16777215> [min <0-16777215> | max <0-16777215>]} {} +.. index:: link-param {delay-variation <0-16777215>} {} + +link-param {delay-variation <0-16777215>} {} +.. index:: link-param {packet-loss `percentage`} {} + +link-param {packet-loss `percentage`} {} +.. index:: link-param {res-bw `bandwidth`} {} + +link-param {res-bw `bandwidth`} {} +.. index:: link-param {ava-bw `bandwidth`} {} + +link-param {ava-bw `bandwidth`} {} +.. index:: link-param {use-bw `bandwidth`} {} + +link-param {use-bw `bandwidth`} {} + These command specifies additionnal Traffic Engineering parameters of the interface in conformity to + draft-ietf-ospf-te-metrics-extension-05.txt and draft-ietf-isis-te-metrics-extension-03.txt. There are + respectively the delay, jitter, loss, available bandwidth, reservable bandwidth and utilized bandwidth. + + Note that `bandwidth` are specified in IEEE floating point format and express in Bytes/second. + Delays and delay variation are express in micro-second (µs). Loss is specified in `percentage` ranging + from 0 to 50.331642% by step of 0.000003. + +.. index:: link-param {neighbor as <0-65535>} {} + +link-param {neighbor as <0-65535>} {} +.. index:: link-param {no neighbor} {} + +link-param {no neighbor} {} + Specifies the remote ASBR IP address and Autonomous System (AS) number 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:: Command {ip route `network` `gateway`} {} + +Command {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. + +:: + + 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:: Command {ip route `network` `netmask` `gateway`} {} + +Command {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 + +:: + + 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:: Command {ip route `network` `gateway` `distance`} {} + +Command {ip route `network` `gateway` `distance`} {} + Installs the route with the specified distance. + +Multiple nexthop static route + +:: + + 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 + + +:: + + 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 (eg +default) should the specified gateways not be reachable. Eg: + +:: + + 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:: Command {ipv6 route `network` `gateway`} {} + +Command {ipv6 route `network` `gateway`} {} +.. index:: Command {ipv6 route `network` `gateway` `distance`} {} + +Command {ipv6 route `network` `gateway` `distance`} {} + These behave similarly to their ipv4 counterparts. + +.. index:: Command {ipv6 route `network` from `srcprefix` `gateway`} {} + +Command {ipv6 route `network` from `srcprefix` `gateway`} {} +.. index:: Command {ipv6 route `network` from `srcprefix` `gateway` `distance`} {} + +Command {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:: Command {table `tableno`} {} + +Command {table `tableno`} {} + Select the primary kernel routing table to be used. This only works + for kernels supporting multiple routing tables (like GNU/Linux 2.2.x + and later). After setting `tableno` with this command, + static routes defined after this are added to the specified table. + +.. _Multicast_RIB_Commands: + +Multicast RIB Commands +====================== + +The Multicast RIB provides a separate table of unicast destinations which +is used for Multicast Reverse Path Forwarding decisions. It is used with +a multicast source's IP address, hence contains not multicast group +addresses but unicast addresses. + +This table is fully separate from the default unicast table. However, +RPF lookup can include the unicast table. + +WARNING: RPF lookup results are non-responsive in this version of Frr, +i.e. multicast routing does not actively react to changes in underlying +unicast topology! + +.. index:: Command {ip multicast rpf-lookup-mode `mode`} {} + +Command {ip multicast rpf-lookup-mode `mode`} {} +.. index:: Command {no ip multicast rpf-lookup-mode [`mode`]} {} + +Command {no ip multicast rpf-lookup-mode [`mode`]} {} + `mode` sets the method used to perform RPF lookups. Supported modes: + + + +*urib-only* + Performs the lookup on the Unicast RIB. The Multicast RIB is never used. + +*mrib-only* + Performs the lookup on the Multicast RIB. The Unicast RIB is never used. + +*mrib-then-urib* + Tries to perform the lookup on the Multicast RIB. If any route is found, + that route is used. Otherwise, the Unicast RIB is tried. + +*lower-distance* + Performs a lookup on the Multicast RIB and Unicast RIB each. The result + with the lower administrative distance is used; if they're equal, the + Multicast RIB takes precedence. + +*longer-prefix* + Performs a lookup on the Multicast RIB and Unicast RIB each. The result + with the longer prefix length is used; if they're equal, the + Multicast RIB takes precedence. + + The `mrib-then-urib` setting is the default behavior if nothing is + configured. If this is the desired behavior, it should be explicitly + configured to make the configuration immune against possible changes in + what the default behavior is. + + WARNING: Unreachable routes do not receive special treatment and do not + cause fallback to a second lookup. + +.. index:: Command {show ip rpf `addr`} {} + +Command {show ip rpf `addr`} {} + Performs a Multicast RPF lookup, as configured with + *ip multicast rpf-lookup-mode `mode*`. `addr` specifies + the multicast source address to look up. + +:: + + > show ip rpf 192.0.2.1 + Routing entry for 192.0.2.0/24 using Unicast RIB + Known via "kernel", distance 0, metric 0, best + * 198.51.100.1, via eth0 + + + Indicates that a multicast source lookup for 192.0.2.1 would use an + Unicast RIB entry for 192.0.2.0/24 with a gateway of 198.51.100.1. + +.. index:: Command {show ip rpf} {} + +Command {show ip rpf} {} + Prints the entire Multicast RIB. Note that this is independent of the + configured RPF lookup mode, the Multicast RIB may be printed yet not + used at all. + +.. index:: Command {ip mroute `prefix` `nexthop` [`distance`]} {} + +Command {ip mroute `prefix` `nexthop` [`distance`]} {} +.. index:: Command {no ip mroute `prefix` `nexthop` [`distance`]} {} + +Command {no ip mroute `prefix` `nexthop` [`distance`]} {} + Adds a static route entry to the Multicast RIB. This performs exactly as + the *ip route* command, except that it inserts the route in the + Multicast RIB instead of the Unicast RIB. + +.. _zebra_Route_Filtering: + +zebra Route Filtering +===================== + +Zebra supports *prefix-list* and *route-map* to match +routes received from other frr components. The +*permit*/*deny* facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +.. index:: Command {ip protocol `protocol` route-map `routemap`} {} + +Command {ip protocol `protocol` route-map `routemap`} {} + Apply a route-map filter to routes for the specified protocol. `protocol` + can be **any** or one of + **system**, + **kernel**, + **connected**, + **static**, + **rip**, + **ripng**, + **ospf**, + **ospf6**, + **isis**, + **bgp**, + **hsls**. + +.. index:: {Route Map} {set src `address`} + +{Route Map} {set src `address`} + Within a route-map, set the preferred source address for matching routes + when installing in the kernel. + +:: + + The following creates a prefix-list that matches all addresses, a route-map + that sets the preferred source address, and applies the route-map to all + *rip* routes. + + @group + ip prefix-list ANY permit 0.0.0.0/0 le 32 + route-map RM1 permit 10 + match ip address prefix-list ANY + set src 10.0.0.1 + + ip protocol rip route-map RM1 + @end group + + +.. _zebra_FIB_push_interface: + +zebra FIB push interface +======================== + +Zebra supports a 'FIB push' interface that allows an external +component to learn the forwarding information computed by the Frr +routing suite. This is a loadable module that needs to be enabled +at startup as described in :ref:`Loadable_Module_Support`. + +In Frr, the Routing Information Base (RIB) resides inside +zebra. Routing protocols communicate their best routes to zebra, and +zebra computes the best route across protocols for each prefix. This +latter information makes up the Forwarding Information Base +(FIB). Zebra feeds the FIB to the kernel, which allows the IP stack in +the kernel to forward packets according to the routes computed by +Frr. The kernel FIB is updated in an OS-specific way. For example, +the `netlink` interface is used on Linux, and route sockets are +used on FreeBSD. + +The FIB push interface aims to provide a cross-platform mechanism to +support scenarios where the router has a forwarding path that is +distinct from the kernel, commonly a hardware-based fast path. In +these cases, the FIB needs to be maintained reliably in the fast path +as well. We refer to the component that programs the forwarding plane +(directly or indirectly) as the Forwarding Plane Manager or FPM. + +The FIB push interface comprises of a TCP connection between zebra and +the FPM. The connection is initiated by zebra -- that is, the FPM acts +as the TCP server. + +The relevant zebra code kicks in when zebra is configured with the +`--enable-fpm` flag. Zebra periodically attempts to connect to +the well-known FPM port. Once the connection is up, zebra starts +sending messages containing routes over the socket to the FPM. Zebra +sends a complete copy of the forwarding table to the FPM, including +routes that it may have picked up from the kernel. The existing +interaction of zebra with the kernel remains unchanged -- that is, the +kernel continues to receive FIB updates as before. + +The encapsulation header for the messages exchanged with the FPM is +defined by the file :file:`fpm/fpm.h` in the frr tree. The routes +themselves are encoded in netlink or protobuf format, with netlink +being the default. + +Protobuf is one of a number of new serialization formats wherein the +message schema is expressed in a purpose-built language. Code for +encoding/decoding to/from the wire format is generated from the +schema. Protobuf messages can be extended easily while maintaining +backward-compatibility with older code. Protobuf has the following +advantages over netlink: + +* + Code for serialization/deserialization is generated + automatically. This reduces the likelihood of bugs, allows third-party + programs to be integrated quickly, and makes it easy to add fields. +* + The message format is not tied to an OS (Linux), and can be evolved + independently. + +As mentioned before, zebra encodes routes sent to the FPM in netlink +format by default. The format can be controlled via the FPM module's +load-time option to zebra, which currently takes the values `netlink` +and `protobuf`. + +The zebra FPM interface uses replace semantics. That is, if a 'route +add' message for a prefix is followed by another 'route add' message, +the information in the second message is complete by itself, and +replaces the information sent in the first message. + +If the connection to the FPM goes down for some reason, zebra sends +the FPM a complete copy of the forwarding table(s) when it reconnects. + +zebra Terminal Mode Commands +============================ + +.. index:: Command {show ip route} {} + +Command {show ip route} {} + Display current routes which zebra holds in its database. + +:: + + @group + Router# show ip route + Codes: K - kernel route, C - connected, S - static, R - RIP, + B - BGP * - FIB route. + + K* 0.0.0.0/0 203.181.89.241 + S 0.0.0.0/0 203.181.89.1 + C* 127.0.0.0/8 lo + C* 203.181.89.240/28 eth0 + @end group + + +.. index:: Command {show ipv6 route} {} + +Command {show ipv6 route} {} +.. index:: Command {show interface} {} + +Command {show interface} {} +.. index:: Command {show ip prefix-list [`name`]} {} + +Command {show ip prefix-list [`name`]} {} +.. index:: Command {show route-map [`name`]} {} + +Command {show route-map [`name`]} {} +.. index:: Command {show ip protocol} {} + +Command {show ip protocol} {} +.. index:: Command {show ipforward} {} + +Command {show ipforward} {} + Display whether the host's IP forwarding function is enabled or not. + Almost any UNIX kernel can be configured with IP forwarding disabled. + If so, the box can't work as a router. + +.. index:: Command {show ipv6forward} {} + +Command {show ipv6forward} {} + Display whether the host's IP v6 forwarding is enabled or not. + +.. index:: Command {show zebra} {} + +Command {show zebra} {} + Display various statistics related to the installation and deletion + of routes, neighbor updates, and LSP's into the kernel. + +.. index:: Command {show zebra fpm stats} {} + +Command {show zebra fpm stats} {} + Display statistics related to the zebra code that interacts with the + optional Forwarding Plane Manager (FPM) component. + +.. index:: Command {clear zebra fpm stats} {} + +Command {clear zebra fpm stats} {} + Reset statistics related to the zebra code that interacts with the + optional Forwarding Plane Manager (FPM) component. + diff --git a/doc/user/nhrpd.rst b/doc/user/nhrpd.rst new file mode 100644 index 0000000000..24037f85b6 --- /dev/null +++ b/doc/user/nhrpd.rst @@ -0,0 +1,153 @@ +.. _NHRP: + +**** +NHRP +**** + +*nhrpd* is a daemon to support Next Hop Routing Protocol (NHRP). +NHRP is described in RFC2332. + +NHRP is used to improve the efficiency of routing computer network +traffic over Non-Broadcast, Multiple Access (NBMA) Networks. NHRP provides +an ARP-like solution that allows a system to dynamically learn the NBMA +address of the other systems that are part of that network, allowing +these systems to directly communicate without requiring traffic to use +an intermediate hop. + +Cisco Dynamic Multipoint VPN (DMVPN) is based on NHRP, and +@value{PACKAGE_NAME} nhrpd implements this scenario. + +.. _Routing_Design: + +Routing Design +============== + +nhrpd never handles routing of prefixes itself. You need to run some +real routing protocol (e.g. BGP) to advertise routes over the tunnels. +What nhrpd does it establishes 'shortcut routes' that optimizes the +routing protocol to avoid going through extra nodes in NBMA GRE mesh. + +nhrpd does route NHRP domain addresses individually using per-host prefixes. +This is similar to Cisco FlexVPN; but in contrast to opennhrp which uses +a generic subnet route. + +To create NBMA GRE tunnel you might use the following (linux terminal +commands): +:: + + @group + ip tunnel add gre1 mode gre key 42 ttl 64 + ip addr add 10.255.255.2/32 dev gre1 + ip link set gre1 up + @end group + + +Note that the IP-address is assigned as host prefix to gre1. nhrpd will +automatically create additional host routes pointing to gre1 when +a connection with these hosts is established. + +The gre1 subnet prefix should be announced by routing protocol from the +hub nodes (e.g. BGP 'network' announce). This allows the routing protocol +to decide which is the closest hub and determine the relay hub on prefix +basis when direct tunnel is not established. + +nhrpd will redistribute directly connected neighbors to zebra. Within +hub nodes, these routes should be internally redistributed using some +routing protocol (e.g. iBGP) to allow hubs to be able to relay all traffic. + +This can be achieved in hubs with the following bgp configuration (network +command defines the GRE subnet): +:: + + @group + router bgp 65555 + address-family ipv4 unicast + network 172.16.0.0/16 + redistribute nhrp + exit-address-family + @end group + + +.. _Configuring_NHRP: + +Configuring NHRP +================ + +FIXME + +.. _Hub_Functionality: + +Hub Functionality +================= + +In addition to routing nhrp redistributed host prefixes, the hub nodes +are also responsible to send NHRP Traffic Indication messages that +trigger creation of the shortcut tunnels. + +nhrpd sends Traffic Indication messages based on network traffic captured +using NFLOG. Typically you want to send Traffic Indications for network +traffic that is routed from gre1 back to gre1 in rate limited manner. +This can be achieved with the following iptables rule. + +:: + + @group + iptables -A FORWARD -i gre1 -o gre1 \\ + -m hashlimit --hashlimit-upto 4/minute --hashlimit-burst 1 \\ + --hashlimit-mode srcip,dstip --hashlimit-srcmask 24 --hashlimit-dstmask 24 \\ + --hashlimit-name loglimit-0 -j NFLOG --nflog-group 1 --nflog-range 128 + @end group + + +You can fine tune the src/dstmask according to the prefix lengths you +announce internal, add additional IP range matches, or rate limitation +if needed. However, the above should be good in most cases. + +This kernel NFLOG target's nflog-group is configured in global nhrp config +with: +:: + + @group + nhrp nflog-group 1 + @end group + + +To start sending these traffic notices out from hubs, use the nhrp +per-interface directive: +:: + + @group + interface gre1 + ip nhrp redirect + @end group + + +.. _Integration_with_IKE: + +Integration with IKE +==================== + +nhrpd needs tight integration with IKE daemon for various reasons. +Currently only strongSwan is supported as IKE daemon. + +nhrpd connects to strongSwan using VICI protocol based on UNIX socket +(hardcoded now as /var/run/charon.vici). + +strongSwan currently needs few patches applied. Please check out the +`http://git.alpinelinux.org/cgit/user/tteras/strongswan/log/?h=tteras-release,release `_ +and +`http://git.alpinelinux.org/cgit/user/tteras/strongswan/log/?h=tteras,working tree `_ +git repositories for the patches. + +.. _NHRP_Events: + +NHRP Events +=========== + +FIXME + +Configuration Example +===================== + +FIXME + diff --git a/doc/user/ospf6d.rst b/doc/user/ospf6d.rst new file mode 100644 index 0000000000..3644631c59 --- /dev/null +++ b/doc/user/ospf6d.rst @@ -0,0 +1,206 @@ +.. _OSPFv3: + +****** +OSPFv3 +****** + +*ospf6d* is a daemon support OSPF version 3 for IPv6 network. +OSPF for IPv6 is described in RFC2740. + +.. _OSPF6_router: + +OSPF6 router +============ + +.. index:: {Command} {router ospf6} {} + +{Command} {router ospf6} {} + +.. index:: {OSPF6 Command} {router-id `a.b.c.d`} {} + +{OSPF6 Command} {router-id `a.b.c.d`} {} + Set router's Router-ID. + +.. index:: {OSPF6 Command} {interface `ifname` area `area`} {} + +{OSPF6 Command} {interface `ifname` area `area`} {} + Bind interface to specified area, and start sending OSPF packets. `area` can + be specified as 0. + +.. index:: {OSPF6 Command} {timers throttle spf `delay` `initial-holdtime` `max-holdtime`} {} + +{OSPF6 Command} {timers throttle spf `delay` `initial-holdtime` `max-holdtime`} {} +.. index:: {OSPF6 Command} {no timers throttle spf} {} + +{OSPF6 Command} {no timers throttle spf} {} + This command sets the initial `delay`, the `initial-holdtime` + and the `maximum-holdtime` between when SPF is calculated and the + event which triggered the calculation. The times are specified in + milliseconds and must be in the range of 0 to 600000 milliseconds. + + The `delay` specifies the minimum amount of time to delay SPF + calculation (hence it affects how long SPF calculation is delayed after + an event which occurs outside of the holdtime of any previous SPF + calculation, and also serves as a minimum holdtime). + + Consecutive SPF calculations will always be seperated by at least + 'hold-time' milliseconds. The hold-time is adaptive and initially is + set to the `initial-holdtime` configured with the above command. + Events which occur within the holdtime of the previous SPF calculation + will cause the holdtime to be increased by `initial-holdtime`, bounded + by the `maximum-holdtime` configured with this command. If the adaptive + hold-time elapses without any SPF-triggering event occuring then + the current holdtime is reset to the `initial-holdtime`. + +:: + + @group + router ospf6 + timers throttle spf 200 400 10000 + @end group + + + In this example, the `delay` is set to 200ms, the @var{initial + holdtime} is set to 400ms and the `maximum holdtime` to 10s. Hence + there will always be at least 200ms between an event which requires SPF + calculation and the actual SPF calculation. Further consecutive SPF + calculations will always be seperated by between 400ms to 10s, the + hold-time increasing by 400ms each time an SPF-triggering event occurs + within the hold-time of the previous SPF calculation. + +.. index:: {OSPF6 Command} {auto-cost reference-bandwidth `cost`} {} + +{OSPF6 Command} {auto-cost reference-bandwidth `cost`} {} +.. index:: {OSPF6 Command} {no auto-cost reference-bandwidth} {} + +{OSPF6 Command} {no auto-cost reference-bandwidth} {} + This sets the reference bandwidth for cost calculations, where this + bandwidth is considered equivalent to an OSPF cost of 1, specified in + Mbits/s. The default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s + or higher will have a cost of 1. Cost of lower bandwidth links will be + scaled with reference to this cost). + + This configuration setting MUST be consistent across all routers + within the OSPF domain. + +.. _OSPF6_area: + +OSPF6 area +========== + +Area support for OSPFv3 is not yet implemented. + +.. _OSPF6_interface: + +OSPF6 interface +=============== + +.. index:: {Interface Command} {ipv6 ospf6 cost COST} {} + +{Interface Command} {ipv6 ospf6 cost COST} {} + Sets interface's output cost. Default value depends on the interface + bandwidth and on the auto-cost reference bandwidth. + +.. index:: {Interface Command} {ipv6 ospf6 hello-interval HELLOINTERVAL} {} + +{Interface Command} {ipv6 ospf6 hello-interval HELLOINTERVAL} {} + Sets interface's Hello Interval. Default 40 + +.. index:: {Interface Command} {ipv6 ospf6 dead-interval DEADINTERVAL} {} + +{Interface Command} {ipv6 ospf6 dead-interval DEADINTERVAL} {} + Sets interface's Router Dead Interval. Default value is 40. + +.. index:: {Interface Command} {ipv6 ospf6 retransmit-interval RETRANSMITINTERVAL} {} + +{Interface Command} {ipv6 ospf6 retransmit-interval RETRANSMITINTERVAL} {} + Sets interface's Rxmt Interval. Default value is 5. + +.. index:: {Interface Command} {ipv6 ospf6 priority PRIORITY} {} + +{Interface Command} {ipv6 ospf6 priority PRIORITY} {} + Sets interface's Router Priority. Default value is 1. + +.. index:: {Interface Command} {ipv6 ospf6 transmit-delay TRANSMITDELAY} {} + +{Interface Command} {ipv6 ospf6 transmit-delay TRANSMITDELAY} {} + Sets interface's Inf-Trans-Delay. Default value is 1. + +.. index:: {Interface Command} {ipv6 ospf6 network (broadcast|point-to-point)} {} + +{Interface Command} {ipv6 ospf6 network (broadcast|point-to-point)} {} + Set explicitly network type for specifed interface. + +.. _Redistribute_routes_to_OSPF6: + +Redistribute routes to OSPF6 +============================ + +.. index:: {OSPF6 Command} {redistribute static} {} + +{OSPF6 Command} {redistribute static} {} +.. index:: {OSPF6 Command} {redistribute connected} {} + +{OSPF6 Command} {redistribute connected} {} +.. index:: {OSPF6 Command} {redistribute ripng} {} + +{OSPF6 Command} {redistribute ripng} {} + +.. _Showing_OSPF6_information: + +Showing OSPF6 information +========================= + +.. index:: {Command} {show ipv6 ospf6 [INSTANCE_ID]} {} + +{Command} {show ipv6 ospf6 [INSTANCE_ID]} {} + INSTANCE_ID is an optional OSPF instance ID. To see router ID and OSPF + instance ID, simply type "show ipv6 ospf6 ". + +.. index:: {Command} {show ipv6 ospf6 database} {} + +{Command} {show ipv6 ospf6 database} {} + This command shows LSA database summary. You can specify the type of LSA. + +.. index:: {Command} {show ipv6 ospf6 interface} {} + +{Command} {show ipv6 ospf6 interface} {} + To see OSPF interface configuration like costs. + +.. index:: {Command} {show ipv6 ospf6 neighbor} {} + +{Command} {show ipv6 ospf6 neighbor} {} + Shows state and chosen (Backup) DR of neighbor. + +.. index:: {Command} {show ipv6 ospf6 request-list A.B.C.D} {} + +{Command} {show ipv6 ospf6 request-list A.B.C.D} {} + Shows requestlist of neighbor. + +.. index:: {Command} {show ipv6 route ospf6} {} + +{Command} {show ipv6 route ospf6} {} + This command shows internal routing table. + +.. index:: {Command} {show ipv6 ospf6 zebra} {} + +{Command} {show ipv6 ospf6 zebra} {} + Shows state about what is being redistributed between zebra and OSPF6 + +OSPF6 Configuration Examples +============================ + +Example of ospf6d configured on one interface and area: + +:: + + interface eth0 + ipv6 ospf6 instance-id 0 + ! + router ospf6 + router-id 212.17.55.53 + area 0.0.0.0 range 2001:770:105:2::/64 + interface eth0 area 0.0.0.0 + ! + + diff --git a/doc/user/ospf_fundamentals.rst b/doc/user/ospf_fundamentals.rst new file mode 100644 index 0000000000..c11c212da8 --- /dev/null +++ b/doc/user/ospf_fundamentals.rst @@ -0,0 +1,600 @@ +.. _OSPF_Fundamentals: + +OSPF Fundamentals +================= + +.. index:: Link-state routing protocol + +.. index:: Distance-vector routing protocol + +@acronym{OSPF} is, mostly, a link-state routing protocol. In contrast +to @dfn{distance-vector} protocols, such as @acronym{RIP} or +@acronym{BGP}, where routers describe available @dfn{paths} (i.e@. routes) +to each other, in @dfn{link-state} protocols routers instead +describe the state of their links to their immediate neighbouring +routers. + +.. index:: Link State Announcement + +.. index:: Link State Advertisement + +.. index:: LSA flooding + +.. index:: Link State DataBase + +Each router describes their link-state information in a message known +as an @acronym{LSA,Link State Advertisement}, which is then propogated +through to all other routers in a link-state routing domain, by a +process called @dfn{flooding}. Each router thus builds up an +@acronym{LSDB,Link State Database} of all the link-state messages. From +this collection of LSAs in the LSDB, each router can then calculate the +shortest path to any other router, based on some common metric, by +using an algorithm such as @url{http://www.cs.utexas.edu/users/EWD/, +Edgser Dijkstra}'s @acronym{SPF,Shortest Path First}. + +.. index:: Link-state routing protocol advantages + +By describing connectivity of a network in this way, in terms of +routers and links rather than in terms of the paths through a network, +a link-state protocol can use less bandwidth and converge more quickly +than other protocols. A link-state protocol need distribute only one +link-state message throughout the link-state domain when a link on any +single given router changes state, in order for all routers to +reconverge on the best paths through the network. In contrast, distance +vector protocols can require a progression of different path update +messages from a series of different routers in order to converge. + +.. index:: Link-state routing protocol disadvantages + +The disadvantage to a link-state protocol is that the process of +computing the best paths can be relatively intensive when compared to +distance-vector protocols, in which near to no computation need be done +other than (potentially) select between multiple routes. This overhead +is mostly negligible for modern embedded CPUs, even for networks with +thousands of nodes. The primary scaling overhead lies more in coping +with the ever greater frequency of LSA updates as the size of a +link-state area increases, in managing the @acronym{LSDB} and required +flooding. + +This section aims to give a distilled, but accurate, description of the +more important workings of @acronym{OSPF}@ which an administrator may need +to know to be able best configure and trouble-shoot @acronym{OSPF}@. + +OSPF Mechanisms +--------------- + +@acronym{OSPF} defines a range of mechanisms, concerned with detecting, +describing and propogating state through a network. These mechanisms +will nearly all be covered in greater detail further on. They may be +broadly classed as: + + + .. index:: OSPF Hello Protocol overview + + +*The Hello Protocol* + .. index:: OSPF Hello Protocol + + The OSPF Hello protocol allows OSPF to quickly detect changes in + two-way reachability between routers on a link. OSPF can additionally + avail of other sources of reachability information, such as link-state + information provided by hardware, or through dedicated reachability + protocols such as @acronym{BFD,Bi-directional Forwarding Detection}. + + OSPF also uses the Hello protocol to propagate certain state between + routers sharing a link, for example: + + +*Hello protocol configured state, such as the dead-interval.* + +*Router priority, for DR/BDR election.* + +*DR/BDR election results.* + +*Any optional capabilities supported by each router.* + + The Hello protocol is comparatively trivial and will not be explored in + greater detail than here. + + .. index:: OSPF LSA overview + + +*LSAs* + At the heart of @acronym{OSPF} are @acronym{LSA,Link State + Advertisement} messages. Despite the name, some @acronym{LSA}s do not, + strictly speaking, describe link-state information. Common + @acronym{LSA}s describe information such as: + + +** + Routers, in terms of their links. + +** + Networks, in terms of attached routers. + +** + Routes, external to a link-state domain: + + +*External Routes* + Routes entirely external to @acronym{OSPF}@. Routers originating such + routes are known as @acronym{ASBR,Autonomous-System Border Router} + routers. + + +*Summary Routes* + Routes which summarise routing information relating to OSPF areas + external to the OSPF link-state area at hand, originated by + @acronym{ABR,Area Boundary Router} routers. + + +*LSA Flooding* + OSPF defines several related mechanisms, used to manage synchronisation of + @acronym{LSDB}s between neighbours as neighbours form adjacencies and + the propogation, or @dfn{flooding} of new or updated @acronym{LSA}s. + + :ref:`OSPF_Flooding`. + + .. index:: OSPF Areas overview + + +*Areas* + OSPF provides for the protocol to be broken up into multiple smaller + and independent link-state areas. Each area must be connected to a + common backbone area by an @acronym{ABR,Area Boundary Router}. These + @acronym{ABR} routers are responsible for summarising the link-state + routing information of an area into @dfn{Summary LSAs}, possibly in a + condensed (i.e. aggregated) form, and then originating these summaries + into all other areas the @acronym{ABR} is connected to. + + Note that only summaries and external routes are passed between areas. + As these describe *paths*, rather than any router link-states, + routing between areas hence is by @dfn{distance-vector}, @strong{not} + link-state. + + :ref:`OSPF_Areas`. + +OSPF LSAs +--------- + +@acronym{LSA}s are the core object in OSPF@. Everything else in OSPF +revolves around detecting what to describe in LSAs, when to update +them, how to flood them throughout a network and how to calculate +routes from them. + +There are a variety of different @acronym{LSA}s, for purposes such +as describing actual link-state information, describing paths (i.e. +routes), describing bandwidth usage of links for +@acronym{TE,Traffic Engineering} purposes, and even arbitrary data +by way of *Opaque* @acronym{LSA}s. + +LSA Header +^^^^^^^^^^ + +All LSAs share a common header with the following information: + +* Type + + Different types of @acronym{LSA}s describe different things in + @acronym{OSPF}@. Types include: + + * Router LSA + * Network LSA + * Network Summary LSA + * Router Summary LSA + * AS-External LSA + + The specifics of the different types of LSA are examined below. + +* Advertising Router + + The Router ID of the router originating the LSA, see :ref:`ospf_router-id`. + +* LSA ID + + The ID of the LSA, which is typically derived in some way from the + information the LSA describes, e.g. a Router LSA uses the Router ID as + the LSA ID, a Network LSA will have the IP address of the @acronym{DR} + as its LSA ID@. + + The combination of the Type, ID and Advertising Router ID must uniquely + identify the @acronym{LSA}@. There can however be multiple instances of + an LSA with the same Type, LSA ID and Advertising Router ID, see + :ref:`OSPF_LSA_sequence_number,,LSA_Sequence_Number`. + +* Age + + A number to allow stale @acronym{LSA}s to, eventually, be purged by routers + from their @acronym{LSDB}s. + + The value nominally is one of seconds. An age of 3600, i.e. 1 hour, is + called the @dfn{MaxAge}. MaxAge LSAs are ignored in routing + calculations. LSAs must be periodically refreshed by their Advertising + Router before reaching MaxAge if they are to remain valid. + + Routers may deliberately flood LSAs with the age artificially set to + 3600 to indicate an LSA is no longer valid. This is called + @dfn{flushing} of an LSA@. + + It is not abnormal to see stale LSAs in the LSDB, this can occur where + a router has shutdown without flushing its LSA(s), e.g. where it has + become disconnected from the network. Such LSAs do little harm. + + .. _OSPF_LSA_sequence_number: + +* Sequence Number + + A number used to distinguish newer instances of an LSA from older instances. + +Link-State LSAs +^^^^^^^^^^^^^^^ + +Of all the various kinds of @acronym{LSA}s, just two types comprise the +actual link-state part of @acronym{OSPF}, Router @acronym{LSA}s and +Network @acronym{LSA}s. These LSA types are absolutely core to the +protocol. + +Instances of these LSAs are specific to the link-state area in which +they are originated. Routes calculated from these two LSA types are +called @dfn{intra-area routes}. + +* Router LSA + + Each OSPF Router must originate a router @acronym{LSA} to describe + itself. In it, the router lists each of its @acronym{OSPF} enabled + interfaces, for the given link-state area, in terms of: + + * Cost + + The output cost of that interface, scaled inversely to some commonly known + reference value, :ref:`OSPF_auto-cost_reference-bandwidth,,auto-cost_reference-bandwidth`. + + * Link Type + + * Transit Network + + A link to a multi-access network, on which the router has at least one + Full adjacency with another router. + + * @acronym{PtP,Point-to-Point} + + A link to a single remote router, with a Full adjacency. No + @acronym{DR, Designated Router} is elected on such links; no network + LSA is originated for such a link. + + * Stub + + A link with no adjacent neighbours, or a host route. + + * Link ID and Data + + These values depend on the Link Type: + + @multitable @columnfractions .18 .32 .32 + @headitem Link Type @tab Link ID @tab Link Data + + * Transit + @tab Link IP address of the @acronym{DR} + @tab Interface IP address + + * Point-to-Point + @tab Router ID of the remote router + @tab Local interface IP address, + or the @acronym{ifindex,MIB-II interface index} + for unnumbered links + + * Stub + @tab IP address + @tab Subnet Mask + + @end multitable + + Links on a router may be listed multiple times in the Router LSA, e.g. + a @acronym{PtP} interface on which OSPF is enabled must *always* + be described by a Stub link in the Router @acronym{LSA}, in addition to + being listed as PtP link in the Router @acronym{LSA} if the adjacency + with the remote router is Full. + + Stub links may also be used as a way to describe links on which OSPF is + *not* spoken, known as @dfn{passive interfaces}, see :ref:`OSPF_passive-interface,,passive-interface`. + +* Network LSA + + On multi-access links (e.g. ethernets, certain kinds of ATM and X@.25 + configurations), routers elect a @acronym{DR}@. The @acronym{DR} is + responsible for originating a Network @acronym{LSA}, which helps reduce + the information needed to describe multi-access networks with multiple + routers attached. The @acronym{DR} also acts as a hub for the flooding of + @acronym{LSA}s on that link, thus reducing flooding overheads. + + The contents of the Network LSA describes the: + + * Subnet Mask + + As the @acronym{LSA} ID of a Network LSA must be the IP address of the + @acronym{DR}, the Subnet Mask together with the @acronym{LSA} ID gives + you the network address. + + * Attached Routers + + Each router fully-adjacent with the @acronym{DR} is listed in the LSA, + by their Router-ID. This allows the corresponding Router @acronym{LSA}s to be + easily retrieved from the @acronym{LSDB}@. + +Summary of Link State LSAs: + +@multitable @columnfractions .18 .32 .40 +@headitem LSA Type @tab LSA ID Describes @tab LSA Data Describes + +* Router LSA +@tab The Router ID +@tab The @acronym{OSPF} enabled links of the router, within +a specific link-state area. + +* Network LSA +@tab The IP address of the @acronym{DR} for the network +@tab The Subnet Mask of the network, and the Router IDs of all routers +on the network. +@end multitable + +With an LSDB composed of just these two types of @acronym{LSA}, it is +possible to construct a directed graph of the connectivity between all +routers and networks in a given OSPF link-state area. So, not +surprisingly, when OSPF routers build updated routing tables, the first +stage of @acronym{SPF} calculation concerns itself only with these two +LSA types. + +Link-State LSA Examples +^^^^^^^^^^^^^^^^^^^^^^^ + +The example below (:ref:`OSPF_Link-State_LSA_Example`) shows two +@acronym{LSA}s, both originated by the same router (Router ID +192.168.0.49) and with the same @acronym{LSA} ID (192.168.0.49), but of +different LSA types. + +The first LSA being the router LSA describing 192.168.0.49's links: 2 links +to multi-access networks with fully-adjacent neighbours (i.e. Transit +links) and 1 being a Stub link (no adjacent neighbours). + +The second LSA being a Network LSA, for which 192.168.0.49 is the +@acronym{DR}, listing the Router IDs of 4 routers on that network which +are fully adjacent with 192.168.0.49. + +.. _OSPF_Link-State_LSA_Example: + +:: + + # show ip ospf database router 192.168.0.49 + + OSPF Router with ID (192.168.0.53) + + Router Link States (Area 0.0.0.0) + + LS age: 38 + Options: 0x2 : *|-|-|-|-|-|E|* + LS Flags: 0x6 + Flags: 0x2 : ASBR + LS Type: router-LSA + Link State ID: 192.168.0.49 + Advertising Router: 192.168.0.49 + LS Seq Number: 80000f90 + Checksum: 0x518b + Length: 60 + Number of Links: 3 + + Link connected to: a Transit Network + (Link ID) Designated Router address: 192.168.1.3 + (Link Data) Router Interface address: 192.168.1.3 + Number of TOS metrics: 0 + TOS 0 Metric: 10 + + Link connected to: a Transit Network + (Link ID) Designated Router address: 192.168.0.49 + (Link Data) Router Interface address: 192.168.0.49 + Number of TOS metrics: 0 + TOS 0 Metric: 10 + + Link connected to: Stub Network + (Link ID) Net: 192.168.3.190 + (Link Data) Network Mask: 255.255.255.255 + Number of TOS metrics: 0 + TOS 0 Metric: 39063 + # show ip ospf database network 192.168.0.49 + + OSPF Router with ID (192.168.0.53) + + Net Link States (Area 0.0.0.0) + + LS age: 285 + Options: 0x2 : *|-|-|-|-|-|E|* + LS Flags: 0x6 + LS Type: network-LSA + Link State ID: 192.168.0.49 (address of Designated Router) + Advertising Router: 192.168.0.49 + LS Seq Number: 80000074 + Checksum: 0x0103 + Length: 40 + Network Mask: /29 + Attached Router: 192.168.0.49 + Attached Router: 192.168.0.52 + Attached Router: 192.168.0.53 + Attached Router: 192.168.0.54 + + +Note that from one LSA, you can find the other. E.g. Given the +Network-LSA you have a list of Router IDs on that network, from which +you can then look up, in the local @acronym{LSDB}, the matching Router +LSA@. From that Router-LSA you may (potentially) find links to other +Transit networks and Routers IDs which can be used to lookup the +corresponding Router or Network LSA@. And in that fashion, one can find +all the Routers and Networks reachable from that starting @acronym{LSA}@. + +Given the Router LSA instead, you have the IP address of the +@acronym{DR} of any attached transit links. Network LSAs will have that IP +as their LSA ID, so you can then look up that Network LSA and from that +find all the attached routers on that link, leading potentially to more +links and Network and Router LSAs, etc. etc. + +From just the above two @acronym{LSA}s, one can already see the +following partial topology: +:: + + @group + + --------------------- Network: ...... + | Designated Router IP: 192.168.1.3 + | + IP: 192.168.1.3 + (transit link) + (cost: 10) + Router ID: 192.168.0.49(stub)---------- IP: 192.168.3.190/32 + (cost: 10) (cost: 39063) + (transit link) + IP: 192.168.0.49 + | + | + ------------------------------ Network: 192.168.0.48/29 + | | | Designated Router IP: 192.168.0.49 + | | | + | | Router ID: 192.168.0.54 + | | + | Router ID: 192.168.0.53 + | + Router ID: 192.168.0.52 + @end group + + +Note the Router IDs, though they look like IP addresses and often are +IP addresses, are not strictly speaking IP addresses, nor need they be +reachable addresses (though, OSPF will calculate routes to Router IDs). + +External LSAs +^^^^^^^^^^^^^ + +External, or "Type 5", @acronym{LSA}s describe routing information which is +entirely external to @acronym{OSPF}, and is "injected" into +@acronym{OSPF}@. Such routing information may have come from another +routing protocol, such as RIP or BGP, they may represent static routes +or they may represent a default route. + +An @acronym{OSPF} router which originates External @acronym{LSA}s is known as an +@acronym{ASBR,AS Boundary Router}. Unlike the link-state @acronym{LSA}s, and +most other @acronym{LSA}s, which are flooded only within the area in +which they originate, External @acronym{LSA}s are flooded through-out +the @acronym{OSPF} network to all areas capable of carrying External +@acronym{LSA}s (:ref:`OSPF_Areas`). + +Routes internal to OSPF (intra-area or inter-area) are always preferred +over external routes. + +The External @acronym{LSA} describes the following: + +* IP Network number + + The IP Network number of the route is described by the @acronym{LSA} ID + field. + +* IP Network Mask + + The body of the External LSA describes the IP Network Mask of the + route. This, together with the @acronym{LSA} ID, describes the prefix + of the IP route concerned. + +* Metric + + The cost of the External Route. This cost may be an OSPF cost (also + known as a "Type 1" metric), i.e. equivalent to the normal OSPF costs, + or an externally derived cost ("Type 2" metric) which is not comparable + to OSPF costs and always considered larger than any OSPF cost. Where + there are both Type 1 and 2 External routes for a route, the Type 1 is + always preferred. + +* Forwarding Address + + The address of the router to forward packets to for the route. This may + be, and usually is, left as 0 to specify that the ASBR originating the + External @acronym{LSA} should be used. There must be an internal OSPF + route to the forwarding address, for the forwarding address to be + useable. + +* Tag + + An arbitrary 4-bytes of data, not interpreted by OSPF, which may + carry whatever information about the route which OSPF speakers desire. + +AS External LSA Example +^^^^^^^^^^^^^^^^^^^^^^^ + +To illustrate, below is an example of an External @acronym{LSA} in the +@acronym{LSDB} of an OSPF router. It describes a route to the IP prefix +of 192.168.165.0/24, originated by the ASBR with Router-ID +192.168.0.49. The metric of 20 is external to OSPF. The forwarding +address is 0, so the route should forward to the originating ASBR if +selected. + +:: + + @group + # show ip ospf database external 192.168.165.0 + LS age: 995 + Options: 0x2 : *|-|-|-|-|-|E|* + LS Flags: 0x9 + LS Type: AS-external-LSA + Link State ID: 192.168.165.0 (External Network Number) + Advertising Router: 192.168.0.49 + LS Seq Number: 800001d8 + Checksum: 0xea27 + Length: 36 + Network Mask: /24 + Metric Type: 2 (Larger than any link state path) + TOS: 0 + Metric: 20 + Forward Address: 0.0.0.0 + External Route Tag: 0 + @end group + + +We can add this to our partial topology from above, which now looks +like: +:: + + @group + --------------------- Network: ...... + | Designated Router IP: 192.168.1.3 + | + IP: 192.168.1.3 /---- External route: 192.168.165.0/24 + (transit link) / Cost: 20 (External metric) + (cost: 10) / + Router ID: 192.168.0.49(stub)---------- IP: 192.168.3.190/32 + (cost: 10) (cost: 39063) + (transit link) + IP: 192.168.0.49 + | + | + ------------------------------ Network: 192.168.0.48/29 + | | | Designated Router IP: 192.168.0.49 + | | | + | | Router ID: 192.168.0.54 + | | + | Router ID: 192.168.0.53 + | + Router ID: 192.168.0.52 + @end group + + +Summary LSAs +^^^^^^^^^^^^ + +Summary LSAs are created by @acronym{ABR}s to summarise the destinations available within one area to other areas. These LSAs may describe IP networks, potentially in aggregated form, or @acronym{ASBR} routers. + +.. _OSPF_Flooding: + +OSPF Flooding +------------- + +.. _OSPF_Areas: + +OSPF Areas +---------- + + diff --git a/doc/user/ospfd.rst b/doc/user/ospfd.rst new file mode 100644 index 0000000000..78360c7503 --- /dev/null +++ b/doc/user/ospfd.rst @@ -0,0 +1,1280 @@ +.. _OSPFv2: + +****** +OSPFv2 +****** + +@acronym{OSPF,Open Shortest Path First} version 2 is a routing protocol +which is described in @cite{RFC2328, OSPF Version 2}. OSPF is an +@acronym{IGP,Interior Gateway Protocol}. Compared with @acronym{RIP}, +@acronym{OSPF} can provide scalable network support and faster +convergence times. OSPF is widely used in large networks such as +@acronym{ISP,Internet Service Provider} backbone and enterprise +networks. + +@include ospf_fundamentals.texi + +.. _Configuring_ospfd: + +Configuring ospfd +================= + +There are no *ospfd* specific options. Common options can be +specified (:ref:`Common_Invocation_Options`) to *ospfd*. +*ospfd* needs to acquire interface information from +*zebra* in order to function. 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 @acronym{OSPF} +specific configuration file :file:`ospfd.conf`. + +.. _OSPF_router: + +OSPF router +=========== + +To start OSPF process you have to specify the OSPF router. As of this +writing, *ospfd* does not support multiple OSPF processes. + +.. index:: Command {router ospf} {} + +Command {router ospf} {} +.. index:: Command {no router ospf} {} + +Command {no router ospf} {} + Enable or disable the OSPF process. *ospfd* does not yet + support multiple OSPF processes. So you can not specify an OSPF process + number. + +.. index:: {OSPF Command} {ospf router-id `a.b.c.d`} {} + +{OSPF Command} {ospf router-id `a.b.c.d`} {} +.. index:: {OSPF Command} {no ospf router-id} {} + +{OSPF Command} {no ospf router-id} {} + .. _ospf_router-id: + + This sets the router-ID of the OSPF process. The + router-ID may be an IP address of the router, but need not be - it can + be any arbitrary 32bit number. However it MUST be unique within the + entire OSPF domain to the OSPF speaker - bad things will happen if + multiple OSPF speakers are configured with the same router-ID! If one + is not specified then *ospfd* will obtain a router-ID + automatically from *zebra*. + +.. index:: {OSPF Command} {ospf abr-type `type`} {} + +{OSPF Command} {ospf abr-type `type`} {} +.. index:: {OSPF Command} {no ospf abr-type `type`} {} + +{OSPF Command} {no ospf abr-type `type`} {} + `type` can be cisco|ibm|shortcut|standard. The "Cisco" and "IBM" types + are equivalent. + + The OSPF standard for ABR behaviour does not allow an ABR to consider + routes through non-backbone areas when its links to the backbone are + down, even when there are other ABRs in attached non-backbone areas + which still can reach the backbone - this restriction exists primarily + to ensure routing-loops are avoided. + + With the "Cisco" or "IBM" ABR type, the default in this release of + Frr, this restriction is lifted, allowing an ABR to consider + summaries learnt from other ABRs through non-backbone areas, and hence + route via non-backbone areas as a last resort when, and only when, + backbone links are down. + + Note that areas with fully-adjacent virtual-links are considered to be + "transit capable" and can always be used to route backbone traffic, and + hence are unaffected by this setting (:ref:`OSPF_virtual-link`). + + More information regarding the behaviour controlled by this command can + be found in @cite{RFC 3509, Alternative Implementations of OSPF Area + Border Routers}, and @cite{draft-ietf-ospf-shortcut-abr-02.txt}. + + Quote: "Though the definition of the @acronym{ABR,Area Border Router} + in the OSPF specification does not require a router with multiple + attached areas to have a backbone connection, it is actually + necessary to provide successful routing to the inter-area and + external destinations. If this requirement is not met, all traffic + destined for the areas not connected to such an ABR or out of the + OSPF domain, is dropped. This document describes alternative ABR + behaviors implemented in Cisco and IBM routers." + +.. index:: {OSPF Command} {ospf rfc1583compatibility} {} + +{OSPF Command} {ospf rfc1583compatibility} {} +.. index:: {OSPF Command} {no ospf rfc1583compatibility} {} + +{OSPF Command} {no ospf rfc1583compatibility} {} + @cite{RFC2328}, the sucessor to @cite{RFC1583}, suggests according + to section G.2 (changes) in section 16.4 a change to the path + preference algorithm that prevents possible routing loops that were + possible in the old version of OSPFv2. More specifically it demands + that inter-area paths and intra-area backbone path are now of equal preference + but still both preferred to external paths. + + This command should NOT be set normally. + +.. index:: {OSPF Command} {log-adjacency-changes [detail]} {} + +{OSPF Command} {log-adjacency-changes [detail]} {} +.. index:: {OSPF Command} {no log-adjacency-changes [detail]} {} + +{OSPF Command} {no log-adjacency-changes [detail]} {} + Configures ospfd to log changes in adjacency. With the optional + detail argument, all changes in adjacency status are shown. Without detail, + only changes to full or regressions are shown. + +.. index:: {OSPF Command} {passive-interface `interface`} {} + +{OSPF Command} {passive-interface `interface`} {} +.. index:: {OSPF Command} {no passive-interface `interface`} {} + +{OSPF Command} {no passive-interface `interface`} {} + .. _OSPF_passive-interface: + + Do not speak OSPF interface on the + given interface, but do advertise the interface as a stub link in the + router-@acronym{LSA,Link State Advertisement} for this router. This + allows one to advertise addresses on such connected interfaces without + having to originate AS-External/Type-5 LSAs (which have global flooding + scope) - as would occur if connected addresses were redistributed into + OSPF (:ref:`Redistribute_routes_to_OSPF`)@. This is the only way to + advertise non-OSPF links into stub areas. + +.. index:: {OSPF Command} {timers throttle spf `delay` `initial-holdtime` `max-holdtime`} {} + +{OSPF Command} {timers throttle spf `delay` `initial-holdtime` `max-holdtime`} {} +.. index:: {OSPF Command} {no timers throttle spf} {} + +{OSPF Command} {no timers throttle spf} {} + This command sets the initial `delay`, the `initial-holdtime` + and the `maximum-holdtime` between when SPF is calculated and the + event which triggered the calculation. The times are specified in + milliseconds and must be in the range of 0 to 600000 milliseconds. + + The `delay` specifies the minimum amount of time to delay SPF + calculation (hence it affects how long SPF calculation is delayed after + an event which occurs outside of the holdtime of any previous SPF + calculation, and also serves as a minimum holdtime). + + Consecutive SPF calculations will always be seperated by at least + 'hold-time' milliseconds. The hold-time is adaptive and initially is + set to the `initial-holdtime` configured with the above command. + Events which occur within the holdtime of the previous SPF calculation + will cause the holdtime to be increased by `initial-holdtime`, bounded + by the `maximum-holdtime` configured with this command. If the adaptive + hold-time elapses without any SPF-triggering event occuring then + the current holdtime is reset to the `initial-holdtime`. The current + holdtime can be viewed with :ref:`show_ip_ospf`, where it is expressed as + a multiplier of the `initial-holdtime`. + +:: + + @group + router ospf + timers throttle spf 200 400 10000 + @end group + + + In this example, the `delay` is set to 200ms, the @var{initial + holdtime} is set to 400ms and the `maximum holdtime` to 10s. Hence + there will always be at least 200ms between an event which requires SPF + calculation and the actual SPF calculation. Further consecutive SPF + calculations will always be seperated by between 400ms to 10s, the + hold-time increasing by 400ms each time an SPF-triggering event occurs + within the hold-time of the previous SPF calculation. + + This command supercedes the *timers spf* command in previous Frr + releases. + +.. index:: {OSPF Command} {max-metric router-lsa [on-startup|on-shutdown] <5-86400>} {} + +{OSPF Command} {max-metric router-lsa [on-startup|on-shutdown] <5-86400>} {} +.. index:: {OSPF Command} {max-metric router-lsa administrative} {} + +{OSPF Command} {max-metric router-lsa administrative} {} +.. index:: {OSPF Command} {no max-metric router-lsa [on-startup|on-shutdown|administrative]} {} + +{OSPF Command} {no max-metric router-lsa [on-startup|on-shutdown|administrative]} {} + This enables @cite{RFC3137, OSPF Stub Router Advertisement} support, + where the OSPF process describes its transit links in its router-LSA as + having infinite distance so that other routers will avoid calculating + transit paths through the router while still being able to reach + networks through the router. + + This support may be enabled administratively (and indefinitely) or + conditionally. Conditional enabling of max-metric router-lsas can be + for a period of seconds after startup and/or for a period of seconds + prior to shutdown. + + Enabling this for a period after startup allows OSPF to converge fully + first without affecting any existing routes used by other routers, + while still allowing any connected stub links and/or redistributed + routes to be reachable. Enabling this for a period of time in advance + of shutdown allows the router to gracefully excuse itself from the OSPF + domain. + + Enabling this feature administratively allows for administrative + intervention for whatever reason, for an indefinite period of time. + Note that if the configuration is written to file, this administrative + form of the stub-router command will also be written to file. If + *ospfd* is restarted later, the command will then take effect + until manually deconfigured. + + Configured state of this feature as well as current status, such as the + number of second remaining till on-startup or on-shutdown ends, can be + viewed with the :ref:`show_ip_ospf` command. + +.. index:: {OSPF Command} {auto-cost reference-bandwidth <1-4294967>} {} + +{OSPF Command} {auto-cost reference-bandwidth <1-4294967>} {} +.. index:: {OSPF Command} {no auto-cost reference-bandwidth} {} + +{OSPF Command} {no auto-cost reference-bandwidth} {} + .. _OSPF_auto-cost_reference-bandwidth: + + This sets the reference + bandwidth for cost calculations, where this bandwidth is considered + equivalent to an OSPF cost of 1, specified in Mbits/s. The default is + 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will have a + cost of 1. Cost of lower bandwidth links will be scaled with reference + to this cost). + + This configuration setting MUST be consistent across all routers within the + OSPF domain. + +.. index:: {OSPF Command} {network `a.b.c.d/m` area `a.b.c.d`} {} + +{OSPF Command} {network `a.b.c.d/m` area `a.b.c.d`} {} +.. index:: {OSPF Command} {network `a.b.c.d/m` area `<0-4294967295>`} {} + +{OSPF Command} {network `a.b.c.d/m` area `<0-4294967295>`} {} +.. index:: {OSPF Command} {no network `a.b.c.d/m` area `a.b.c.d`} {} + +{OSPF Command} {no network `a.b.c.d/m` area `a.b.c.d`} {} +.. index:: {OSPF Command} {no network `a.b.c.d/m` area `<0-4294967295>`} {} + +{OSPF Command} {no network `a.b.c.d/m` area `<0-4294967295>`} {} + .. _OSPF_network_command: + + This command specifies the OSPF enabled interface(s). If the interface has + an address from range 192.168.1.0/24 then the command below enables ospf + on this interface so router can provide network information to the other + ospf routers via this interface. + +:: + + @group + router ospf + network 192.168.1.0/24 area 0.0.0.0 + @end group + + + Prefix length in interface must be equal or bigger (ie. smaller network) than + prefix length in network statement. For example statement above doesn't enable + ospf on interface with address 192.168.1.1/23, but it does on interface with + address 192.168.1.129/25. + + Note that the behavior when there is a peer address + defined on an interface changed after release 0.99.7. + Currently, if a peer prefix has been configured, + then we test whether the prefix in the network command contains + the destination prefix. Otherwise, we test whether the network command prefix + contains the local address prefix of the interface. + + In some cases it may be more convenient to enable OSPF on a per + interface/subnet basis (:ref:`OSPF_ip_ospf_area_command`). + + +.. _OSPF_area: + +OSPF area +========= + +.. index:: {OSPF Command} {area `a.b.c.d` range `a.b.c.d/m`} {} + +{OSPF Command} {area `a.b.c.d` range `a.b.c.d/m`} {} +.. index:: {OSPF Command} {area <0-4294967295> range `a.b.c.d/m`} {} + +{OSPF Command} {area <0-4294967295> range `a.b.c.d/m`} {} +.. index:: {OSPF Command} {no area `a.b.c.d` range `a.b.c.d/m`} {} + +{OSPF Command} {no area `a.b.c.d` range `a.b.c.d/m`} {} +.. index:: {OSPF Command} {no area <0-4294967295> range `a.b.c.d/m`} {} + +{OSPF Command} {no area <0-4294967295> range `a.b.c.d/m`} {} + Summarize intra area paths from specified area into one Type-3 summary-LSA + announced to other areas. This command can be used only in ABR and ONLY + router-LSAs (Type-1) and network-LSAs (Type-2) (ie. LSAs with scope area) can + be summarized. Type-5 AS-external-LSAs can't be summarized - their scope is AS. + Summarizing Type-7 AS-external-LSAs isn't supported yet by Frr. + +:: + + @group + router ospf + network 192.168.1.0/24 area 0.0.0.0 + network 10.0.0.0/8 area 0.0.0.10 + area 0.0.0.10 range 10.0.0.0/8 + @end group + + + With configuration above one Type-3 Summary-LSA with routing info 10.0.0.0/8 is + announced into backbone area if area 0.0.0.10 contains at least one intra-area + network (ie. described with router or network LSA) from this range. + +.. index:: {OSPF Command} {area `a.b.c.d` range IPV4_PREFIX not-advertise} {} + +{OSPF Command} {area `a.b.c.d` range IPV4_PREFIX not-advertise} {} +.. index:: {OSPF Command} {no area `a.b.c.d` range IPV4_PREFIX not-advertise} {} + +{OSPF Command} {no area `a.b.c.d` range IPV4_PREFIX not-advertise} {} + Instead of summarizing intra area paths filter them - ie. intra area paths from this + range are not advertised into other areas. + This command makes sense in ABR only. + +.. index:: {OSPF Command} {area `a.b.c.d` range IPV4_PREFIX substitute IPV4_PREFIX} {} + +{OSPF Command} {area `a.b.c.d` range IPV4_PREFIX substitute IPV4_PREFIX} {} +.. index:: {OSPF Command} {no area `a.b.c.d` range IPV4_PREFIX substitute IPV4_PREFIX} {} + +{OSPF Command} {no area `a.b.c.d` range IPV4_PREFIX substitute IPV4_PREFIX} {} + Substitute summarized prefix with another prefix. + +:: + + @group + router ospf + network 192.168.1.0/24 area 0.0.0.0 + network 10.0.0.0/8 area 0.0.0.10 + area 0.0.0.10 range 10.0.0.0/8 substitute 11.0.0.0/8 + @end group + + + One Type-3 summary-LSA with routing info 11.0.0.0/8 is announced into backbone area if + area 0.0.0.10 contains at least one intra-area network (ie. described with router-LSA or + network-LSA) from range 10.0.0.0/8. + This command makes sense in ABR only. + +.. index:: {OSPF Command} {area `a.b.c.d` virtual-link `a.b.c.d`} {} + +{OSPF Command} {area `a.b.c.d` virtual-link `a.b.c.d`} {} +.. index:: {OSPF Command} {area <0-4294967295> virtual-link `a.b.c.d`} {} + +{OSPF Command} {area <0-4294967295> virtual-link `a.b.c.d`} {} +.. index:: {OSPF Command} {no area `a.b.c.d` virtual-link `a.b.c.d`} {} + +{OSPF Command} {no area `a.b.c.d` virtual-link `a.b.c.d`} {} +.. index:: {OSPF Command} {no area <0-4294967295> virtual-link `a.b.c.d`} {} + +{OSPF Command} {no area <0-4294967295> virtual-link `a.b.c.d`} {} + .. _OSPF_virtual-link: + +.. index:: {OSPF Command} {area `a.b.c.d` shortcut} {} + +{OSPF Command} {area `a.b.c.d` shortcut} {} +.. index:: {OSPF Command} {area <0-4294967295> shortcut} {} + +{OSPF Command} {area <0-4294967295> shortcut} {} +.. index:: {OSPF Command} {no area `a.b.c.d` shortcut} {} + +{OSPF Command} {no area `a.b.c.d` shortcut} {} +.. index:: {OSPF Command} {no area <0-4294967295> shortcut} {} + +{OSPF Command} {no area <0-4294967295> shortcut} {} + Configure the area as Shortcut capable. See @cite{RFC3509}. This requires + that the 'abr-type' be set to 'shortcut'. + +.. index:: {OSPF Command} {area `a.b.c.d` stub} {} + +{OSPF Command} {area `a.b.c.d` stub} {} +.. index:: {OSPF Command} {area <0-4294967295> stub} {} + +{OSPF Command} {area <0-4294967295> stub} {} +.. index:: {OSPF Command} {no area `a.b.c.d` stub} {} + +{OSPF Command} {no area `a.b.c.d` stub} {} +.. index:: {OSPF Command} {no area <0-4294967295> stub} {} + +{OSPF Command} {no area <0-4294967295> stub} {} + Configure the area to be a stub area. That is, an area where no router + originates routes external to OSPF and hence an area where all external + routes are via the ABR(s). Hence, ABRs for such an area do not need + to pass AS-External LSAs (type-5s) or ASBR-Summary LSAs (type-4) into the + area. They need only pass Network-Summary (type-3) LSAs into such an area, + along with a default-route summary. + +.. index:: {OSPF Command} {area `a.b.c.d` stub no-summary} {} + +{OSPF Command} {area `a.b.c.d` stub no-summary} {} +.. index:: {OSPF Command} {area <0-4294967295> stub no-summary} {} + +{OSPF Command} {area <0-4294967295> stub no-summary} {} +.. index:: {OSPF Command} {no area `a.b.c.d` stub no-summary} {} + +{OSPF Command} {no area `a.b.c.d` stub no-summary} {} +.. index:: {OSPF Command} {no area <0-4294967295> stub no-summary} {} + +{OSPF Command} {no area <0-4294967295> stub no-summary} {} + Prevents an *ospfd* ABR from injecting inter-area + summaries into the specified stub area. + +.. index:: {OSPF Command} {area `a.b.c.d` default-cost <0-16777215>} {} + +{OSPF Command} {area `a.b.c.d` default-cost <0-16777215>} {} +.. index:: {OSPF Command} {no area `a.b.c.d` default-cost <0-16777215>} {} + +{OSPF Command} {no area `a.b.c.d` default-cost <0-16777215>} {} + Set the cost of default-summary LSAs announced to stubby areas. + +.. index:: {OSPF Command} {area `a.b.c.d` export-list NAME} {} + +{OSPF Command} {area `a.b.c.d` export-list NAME} {} +.. index:: {OSPF Command} {area <0-4294967295> export-list NAME} {} + +{OSPF Command} {area <0-4294967295> export-list NAME} {} +.. index:: {OSPF Command} {no area `a.b.c.d` export-list NAME} {} + +{OSPF Command} {no area `a.b.c.d` export-list NAME} {} +.. index:: {OSPF Command} {no area <0-4294967295> export-list NAME} {} + +{OSPF Command} {no area <0-4294967295> export-list NAME} {} + Filter Type-3 summary-LSAs announced to other areas originated from intra- + area paths from specified area. + +:: + + @group + router ospf + network 192.168.1.0/24 area 0.0.0.0 + network 10.0.0.0/8 area 0.0.0.10 + area 0.0.0.10 export-list foo + ! + access-list foo permit 10.10.0.0/16 + access-list foo deny any + @end group + + + With example above any intra-area paths from area 0.0.0.10 and from range + 10.10.0.0/16 (for example 10.10.1.0/24 and 10.10.2.128/30) are announced into + other areas as Type-3 summary-LSA's, but any others (for example 10.11.0.0/16 + or 10.128.30.16/30) aren't. + + This command is only relevant if the router is an ABR for the specified + area. + +.. index:: {OSPF Command} {area `a.b.c.d` import-list NAME} {} + +{OSPF Command} {area `a.b.c.d` import-list NAME} {} +.. index:: {OSPF Command} {area <0-4294967295> import-list NAME} {} + +{OSPF Command} {area <0-4294967295> import-list NAME} {} +.. index:: {OSPF Command} {no area `a.b.c.d` import-list NAME} {} + +{OSPF Command} {no area `a.b.c.d` import-list NAME} {} +.. index:: {OSPF Command} {no area <0-4294967295> import-list NAME} {} + +{OSPF Command} {no area <0-4294967295> import-list NAME} {} + Same as export-list, but it applies to paths announced into specified area as + Type-3 summary-LSAs. + +.. index:: {OSPF Command} {area `a.b.c.d` filter-list prefix NAME in} {} + +{OSPF Command} {area `a.b.c.d` filter-list prefix NAME in} {} +.. index:: {OSPF Command} {area `a.b.c.d` filter-list prefix NAME out} {} + +{OSPF Command} {area `a.b.c.d` filter-list prefix NAME out} {} +.. index:: {OSPF Command} {area <0-4294967295> filter-list prefix NAME in} {} + +{OSPF Command} {area <0-4294967295> filter-list prefix NAME in} {} +.. index:: {OSPF Command} {area <0-4294967295> filter-list prefix NAME out} {} + +{OSPF Command} {area <0-4294967295> filter-list prefix NAME out} {} +.. index:: {OSPF Command} {no area `a.b.c.d` filter-list prefix NAME in} {} + +{OSPF Command} {no area `a.b.c.d` filter-list prefix NAME in} {} +.. index:: {OSPF Command} {no area `a.b.c.d` filter-list prefix NAME out} {} + +{OSPF Command} {no area `a.b.c.d` filter-list prefix NAME out} {} +.. index:: {OSPF Command} {no area <0-4294967295> filter-list prefix NAME in} {} + +{OSPF Command} {no area <0-4294967295> filter-list prefix NAME in} {} +.. index:: {OSPF Command} {no area <0-4294967295> filter-list prefix NAME out} {} + +{OSPF Command} {no area <0-4294967295> filter-list prefix NAME out} {} + Filtering Type-3 summary-LSAs to/from area using prefix lists. This command + makes sense in ABR only. + +.. index:: {OSPF Command} {area `a.b.c.d` authentication} {} + +{OSPF Command} {area `a.b.c.d` authentication} {} +.. index:: {OSPF Command} {area <0-4294967295> authentication} {} + +{OSPF Command} {area <0-4294967295> authentication} {} +.. index:: {OSPF Command} {no area `a.b.c.d` authentication} {} + +{OSPF Command} {no area `a.b.c.d` authentication} {} +.. index:: {OSPF Command} {no area <0-4294967295> authentication} {} + +{OSPF Command} {no area <0-4294967295> authentication} {} + Specify that simple password authentication should be used for the given + area. + +.. index:: {OSPF Command} {area `a.b.c.d` authentication message-digest} {} + +{OSPF Command} {area `a.b.c.d` authentication message-digest} {} +.. index:: {OSPF Command} {area <0-4294967295> authentication message-digest} {} + +{OSPF Command} {area <0-4294967295> authentication message-digest} {} + .. _area_authentication_message-digest: + + Specify that OSPF packets + must be authenticated with MD5 HMACs within the given area. Keying + material must also be configured on a per-interface basis (:ref:`ip_ospf_message-digest-key`). + + MD5 authentication may also be configured on a per-interface basis + (:ref:`ip_ospf_authentication_message-digest`). Such per-interface + settings will override any per-area authentication setting. + +.. _OSPF_interface: + +OSPF interface +============== + +.. index:: {Interface Command} {ip ospf area `AREA` [`ADDR`]} {} + +{Interface Command} {ip ospf area `AREA` [`ADDR`]} {} +.. index:: {Interface Command} {no ip ospf area [`ADDR`]} {} + +{Interface Command} {no ip ospf area [`ADDR`]} {} + .. _OSPF_ip_ospf_area_command: + + Enable OSPF on the interface, optionally restricted to just the IP address + given by `ADDR`, putting it in the `AREA` area. Per interface area + settings take precedence to network commands (:ref:`OSPF_network_command`). + + If you have a lot of interfaces, and/or a lot of subnets, then enabling OSPF + via this command may result in a slight performance improvement. + +.. index:: {Interface Command} {ip ospf authentication-key `AUTH_KEY`} {} + +{Interface Command} {ip ospf authentication-key `AUTH_KEY`} {} +.. index:: {Interface Command} {no ip ospf authentication-key} {} + +{Interface Command} {no ip ospf authentication-key} {} + Set OSPF authentication key to a simple password. After setting `AUTH_KEY`, + all OSPF packets are authenticated. `AUTH_KEY` has length up to 8 chars. + + Simple text password authentication is insecure and deprecated in favour of + MD5 HMAC authentication (:ref:`ip_ospf_authentication_message-digest`). + +.. index:: {Interface Command} {ip ospf authentication message-digest} {} + +{Interface Command} {ip ospf authentication message-digest} {} + .. _ip_ospf_authentication_message-digest: + + Specify that MD5 HMAC + authentication must be used on this interface. MD5 keying material must + also be configured (:ref:`ip_ospf_message-digest-key`). Overrides any + authentication enabled on a per-area basis (:ref:`area_authentication_message-digest`). + + Note that OSPF MD5 authentication requires that time never go backwards + (correct time is NOT important, only that it never goes backwards), even + across resets, if ospfd is to be able to promptly reestabish adjacencies + with its neighbours after restarts/reboots. The host should have system + time be set at boot from an external or non-volatile source (eg battery backed clock, NTP, + etc.) or else the system clock should be periodically saved to non-volative + storage and restored at boot if MD5 authentication is to be expected to work + reliably. + +.. index:: {Interface Command} {ip ospf message-digest-key KEYID md5 KEY} {} + +{Interface Command} {ip ospf message-digest-key KEYID md5 KEY} {} +.. index:: {Interface Command} {no ip ospf message-digest-key} {} + +{Interface Command} {no ip ospf message-digest-key} {} + .. _ip_ospf_message-digest-key: + + Set OSPF authentication key to a + cryptographic password. The cryptographic algorithm is MD5. + + KEYID identifies secret key used to create the message digest. This ID + is part of the protocol and must be consistent across routers on a + link. + + KEY is the actual message digest key, of up to 16 chars (larger strings + will be truncated), and is associated with the given KEYID. + +.. index:: {Interface Command} {ip ospf cost <1-65535>} {} + +{Interface Command} {ip ospf cost <1-65535>} {} +.. index:: {Interface Command} {no ip ospf cost} {} + +{Interface Command} {no ip ospf cost} {} + Set link cost for the specified interface. The cost value is set to router-LSA's + metric field and used for SPF calculation. + +.. index:: {Interface Command} {ip ospf dead-interval <1-65535>} {} + +{Interface Command} {ip ospf dead-interval <1-65535>} {} +.. index:: {Interface Command} {ip ospf dead-interval minimal hello-multiplier <2-20>} {} + +{Interface Command} {ip ospf dead-interval minimal hello-multiplier <2-20>} {} +.. index:: {Interface Command} {no ip ospf dead-interval} {} + +{Interface Command} {no ip ospf dead-interval} {} + .. _ip_ospf_dead-interval_minimal: + + Set number of seconds for + RouterDeadInterval timer value used for Wait Timer and Inactivity + Timer. This value must be the same for all routers attached to a + common network. The default value is 40 seconds. + + If 'minimal' is specified instead, then the dead-interval is set to 1 + second and one must specify a hello-multiplier. The hello-multiplier + specifies how many Hellos to send per second, from 2 (every 500ms) to + 20 (every 50ms). Thus one can have 1s convergence time for OSPF. If this form + is specified, then the hello-interval advertised in Hello packets is set to + 0 and the hello-interval on received Hello packets is not checked, thus + the hello-multiplier need NOT be the same across multiple routers on a common + link. + +.. index:: {Interface Command} {ip ospf hello-interval <1-65535>} {} + +{Interface Command} {ip ospf hello-interval <1-65535>} {} +.. index:: {Interface Command} {no ip ospf hello-interval} {} + +{Interface Command} {no ip ospf hello-interval} {} + Set number of seconds for HelloInterval timer value. Setting this value, + Hello packet will be sent every timer value seconds on the specified interface. + This value must be the same for all routers attached to a common network. + The default value is 10 seconds. + + This command has no effect if :ref:`ip_ospf_dead-interval_minimal` is also + specified for the interface. + +.. index:: {Interface Command} {ip ospf network (broadcast|non-broadcast|point-to-multipoint|point-to-point)} {} + +{Interface Command} {ip ospf network (broadcast|non-broadcast|point-to-multipoint|point-to-point)} {} +.. index:: {Interface Command} {no ip ospf network} {} + +{Interface Command} {no ip ospf network} {} + Set explicitly network type for specifed interface. + +.. index:: {Interface Command} {ip ospf priority <0-255>} {} + +{Interface Command} {ip ospf priority <0-255>} {} +.. index:: {Interface Command} {no ip ospf priority} {} + +{Interface Command} {no ip ospf priority} {} + Set RouterPriority integer value. The router with the highest priority + will be more eligible to become Designated Router. Setting the value + to 0, makes the router ineligible to become Designated Router. The + default value is 1. + +.. index:: {Interface Command} {ip ospf retransmit-interval <1-65535>} {} + +{Interface Command} {ip ospf retransmit-interval <1-65535>} {} +.. index:: {Interface Command} {no ip ospf retransmit interval} {} + +{Interface Command} {no ip ospf retransmit interval} {} + Set number of seconds for RxmtInterval timer value. This value is used + when retransmitting Database Description and Link State Request packets. + The default value is 5 seconds. + +.. index:: {Interface Command} {ip ospf transmit-delay} {} + +{Interface Command} {ip ospf transmit-delay} {} +.. index:: {Interface Command} {no ip ospf transmit-delay} {} + +{Interface Command} {no ip ospf transmit-delay} {} + Set number of seconds for InfTransDelay value. LSAs' age should be + incremented by this value when transmitting. + The default value is 1 seconds. + +.. index:: {Interface Command} {ip ospf area (A.B.C.D|<0-4294967295>)} {} + +{Interface Command} {ip ospf area (A.B.C.D|<0-4294967295>)} {} +.. index:: {Interface Command} {no ip ospf area} {} + +{Interface Command} {no ip ospf area} {} + Enable ospf on an interface and set associated area. + +.. _Redistribute_routes_to_OSPF: + +Redistribute routes to OSPF +=========================== + +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp)} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp)} {} +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) `route-map`} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp) `route-map`} {} +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2)} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2)} {} +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) route-map `word`} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) route-map `word`} {} +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric <0-16777214>} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric <0-16777214>} {} +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric <0-16777214> route-map `word`} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric <0-16777214> route-map `word`} {} +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214>} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214>} {} +.. index:: {OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214> route-map `word`} {} + +{OSPF Command} {redistribute (kernel|connected|static|rip|bgp) metric-type (1|2) metric <0-16777214> route-map `word`} {} +.. index:: {OSPF Command} {no redistribute (kernel|connected|static|rip|bgp)} {} + +{OSPF Command} {no redistribute (kernel|connected|static|rip|bgp)} {} + .. _OSPF_redistribute: + + Redistribute routes of the specified protocol + or kind into OSPF, with the metric type and metric set if specified, + filtering the routes using the given route-map if specified. + Redistributed routes may also be filtered with distribute-lists, see + :ref:`ospf_distribute-list`. + + Redistributed routes are distributed as into OSPF as Type-5 External + LSAs into links to areas that accept external routes, Type-7 External LSAs + for NSSA areas and are not redistributed at all into Stub areas, where + external routes are not permitted. + + Note that for connected routes, one may instead use + @dfn{passive-interface}, see :ref:`OSPF_passive-interface`. + +.. index:: {OSPF Command} {default-information originate} {} + +{OSPF Command} {default-information originate} {} +.. index:: {OSPF Command} {default-information originate metric <0-16777214>} {} + +{OSPF Command} {default-information originate metric <0-16777214>} {} +.. index:: {OSPF Command} {default-information originate metric <0-16777214> metric-type (1|2)} {} + +{OSPF Command} {default-information originate metric <0-16777214> metric-type (1|2)} {} +.. index:: {OSPF Command} {default-information originate metric <0-16777214> metric-type (1|2) route-map `word`} {} + +{OSPF Command} {default-information originate metric <0-16777214> metric-type (1|2) route-map `word`} {} +.. index:: {OSPF Command} {default-information originate always} {} + +{OSPF Command} {default-information originate always} {} +.. index:: {OSPF Command} {default-information originate always metric <0-16777214>} {} + +{OSPF Command} {default-information originate always metric <0-16777214>} {} +.. index:: {OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2)} {} + +{OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2)} {} +.. index:: {OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2) route-map `word`} {} + +{OSPF Command} {default-information originate always metric <0-16777214> metric-type (1|2) route-map `word`} {} +.. index:: {OSPF Command} {no default-information originate} {} + +{OSPF Command} {no default-information originate} {} + Originate an AS-External (type-5) LSA describing a default route into + all external-routing capable areas, of the specified metric and metric + type. If the 'always' keyword is given then the default is always + advertised, even when there is no default present in the routing table. + +.. index:: {OSPF Command} {distribute-list NAME out (kernel|connected|static|rip|ospf} {} + +{OSPF Command} {distribute-list NAME out (kernel|connected|static|rip|ospf} {} +.. index:: {OSPF Command} {no distribute-list NAME out (kernel|connected|static|rip|ospf} {} + +{OSPF Command} {no distribute-list NAME out (kernel|connected|static|rip|ospf} {} + .. _ospf_distribute-list: + + Apply the access-list filter, NAME, to + redistributed routes of the given type before allowing the routes to + redistributed into OSPF (:ref:`OSPF_redistribute`). + +.. index:: {OSPF Command} {default-metric <0-16777214>} {} + +{OSPF Command} {default-metric <0-16777214>} {} +.. index:: {OSPF Command} {no default-metric} {} + +{OSPF Command} {no default-metric} {} +.. index:: {OSPF Command} {distance <1-255>} {} + +{OSPF Command} {distance <1-255>} {} +.. index:: {OSPF Command} {no distance <1-255>} {} + +{OSPF Command} {no distance <1-255>} {} +.. index:: {OSPF Command} {distance ospf (intra-area|inter-area|external) <1-255>} {} + +{OSPF Command} {distance ospf (intra-area|inter-area|external) <1-255>} {} +.. index:: {OSPF Command} {no distance ospf} {} + +{OSPF Command} {no distance ospf} {} +.. index:: {Command} {router zebra} {} + +{Command} {router zebra} {} +.. index:: {Command} {no router zebra} {} + +{Command} {no router zebra} {} + +.. _Showing_OSPF_information: + +Showing OSPF information +======================== + +.. index:: {Command} {show ip ospf} {} + +{Command} {show ip ospf} {} + .. _show_ip_ospf: + + Show information on a variety of general OSPF and + area state and configuration information. + +.. index:: {Command} {show ip ospf interface [INTERFACE]} {} + +{Command} {show ip ospf interface [INTERFACE]} {} + Show state and configuration of OSPF the specified interface, or all + interfaces if no interface is given. + +.. index:: {Command} {show ip ospf neighbor} {} + +{Command} {show ip ospf neighbor} {} +.. index:: {Command} {show ip ospf neighbor INTERFACE} {} + +{Command} {show ip ospf neighbor INTERFACE} {} +.. index:: {Command} {show ip ospf neighbor detail} {} + +{Command} {show ip ospf neighbor detail} {} +.. index:: {Command} {show ip ospf neighbor INTERFACE detail} {} + +{Command} {show ip ospf neighbor INTERFACE detail} {} +.. index:: {Command} {show ip ospf database} {} + +{Command} {show ip ospf database} {} +.. index:: {Command} {show ip ospf database (asbr-summary|external|network|router|summary)} {} + +{Command} {show ip ospf database (asbr-summary|external|network|router|summary)} {} +.. index:: {Command} {show ip ospf database (asbr-summary|external|network|router|summary) `link-state-id`} {} + +{Command} {show ip ospf database (asbr-summary|external|network|router|summary) `link-state-id`} {} +.. index:: {Command} {show ip ospf database (asbr-summary|external|network|router|summary) `link-state-id` adv-router `adv-router`} {} + +{Command} {show ip ospf database (asbr-summary|external|network|router|summary) `link-state-id` adv-router `adv-router`} {} +.. index:: {Command} {show ip ospf database (asbr-summary|external|network|router|summary) adv-router `adv-router`} {} + +{Command} {show ip ospf database (asbr-summary|external|network|router|summary) adv-router `adv-router`} {} +.. index:: {Command} {show ip ospf database (asbr-summary|external|network|router|summary) `link-state-id` self-originate} {} + +{Command} {show ip ospf database (asbr-summary|external|network|router|summary) `link-state-id` self-originate} {} +.. index:: {Command} {show ip ospf database (asbr-summary|external|network|router|summary) self-originate} {} + +{Command} {show ip ospf database (asbr-summary|external|network|router|summary) self-originate} {} +.. index:: {Command} {show ip ospf database max-age} {} + +{Command} {show ip ospf database max-age} {} +.. index:: {Command} {show ip ospf database self-originate} {} + +{Command} {show ip ospf database self-originate} {} +.. index:: {Command} {show ip ospf route} {} + +{Command} {show ip ospf route} {} + Show the OSPF routing table, as determined by the most recent SPF calculation. + +.. _Opaque_LSA: + +Opaque LSA +========== + +.. index:: {OSPF Command} {ospf opaque-lsa} {} + +{OSPF Command} {ospf opaque-lsa} {} +.. index:: {OSPF Command} {capability opaque} {} + +{OSPF Command} {capability opaque} {} +.. index:: {OSPF Command} {no ospf opaque-lsa} {} + +{OSPF Command} {no ospf opaque-lsa} {} +.. index:: {OSPF Command} {no capability opaque} {} + +{OSPF Command} {no capability opaque} {} + *ospfd* support Opaque LSA (RFC2370) as fondment for MPLS Traffic Engineering LSA. Prior to used MPLS TE, opaque-lsa must be enable in the configuration file. Alternate command could be "mpls-te on" (:ref:`OSPF_Traffic_Engineering`). + +.. index:: {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external)} {} + +{Command} {show ip ospf database (opaque-link|opaque-area|opaque-external)} {} +.. index:: {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) `link-state-id`} {} + +{Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) `link-state-id`} {} +.. index:: {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) `link-state-id` adv-router `adv-router`} {} + +{Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) `link-state-id` adv-router `adv-router`} {} +.. index:: {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) adv-router `adv-router`} {} + +{Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) adv-router `adv-router`} {} +.. index:: {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) `link-state-id` self-originate} {} + +{Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) `link-state-id` self-originate} {} +.. index:: {Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) self-originate} {} + +{Command} {show ip ospf database (opaque-link|opaque-area|opaque-external) self-originate} {} + Show Opaque LSA from the database. + +.. _Traffic_Engineering: + +Traffic Engineering +=================== + +.. index:: {OSPF Command} {mpls-te on} {} + +{OSPF Command} {mpls-te on} {} +.. index:: {OSPF Command} {no mpls-te} {} + +{OSPF Command} {no mpls-te} {} + Enable Traffic Engineering LSA flooding. + +.. index:: {OSPF Command} {mpls-te router-address } {} + +{OSPF Command} {mpls-te router-address } {} +.. index:: {OSPF Command} {no mpls-te} {} + +{OSPF Command} {no mpls-te} {} + Configure stable IP address for MPLS-TE. This IP address is then advertise in Opaque LSA Type-10 TLV=1 (TE) + option 1 (Router-Address). + +.. index:: {OSPF Command} {mpls-te inter-as area |as} {} + +{OSPF Command} {mpls-te inter-as area |as} {} +.. index:: {OSPF Command} {no mpls-te inter-as} {} + +{OSPF Command} {no mpls-te inter-as} {} + Enable RFC5392 suuport - Inter-AS TE v2 - to flood Traffic Engineering parameters of Inter-AS link. + 2 modes are supported: AREA and AS; LSA are flood in AREA with Opaque Type-10, + respectively in AS with Opaque Type-11. In all case, Opaque-LSA TLV=6. + +.. index:: {Command} {show ip ospf mpls-te interface} {} + +{Command} {show ip ospf mpls-te interface} {} +.. index:: {Command} {show ip ospf mpls-te interface `interface`} {} + +{Command} {show ip ospf mpls-te interface `interface`} {} + Show MPLS Traffic Engineering parameters for all or specified interface. + +.. index:: {Command} {show ip ospf mpls-te router} {} + +{Command} {show ip ospf mpls-te router} {} + Show Traffic Engineering router parameters. + +.. _Router_Information: + +Router Information +================== + +.. index:: {OSPF Command} {router-info [as | area ]} {} + +{OSPF Command} {router-info [as | area ]} {} +.. index:: {OSPF Command} {no router-info} {} + +{OSPF Command} {no router-info} {} + Enable Router Information (RFC4970) LSA advertisement with AS scope (default) or Area scope flooding + when area is specified. + +.. index:: {OSPF Command} {pce address } {} + +{OSPF Command} {pce address } {} +.. index:: {OSPF Command} {no pce address} {} + +{OSPF Command} {no pce address} {} +.. index:: {OSPF Command} {pce domain as <0-65535>} {} + +{OSPF Command} {pce domain as <0-65535>} {} +.. index:: {OSPF Command} {no pce domain as <0-65535>} {} + +{OSPF Command} {no pce domain as <0-65535>} {} +.. index:: {OSPF Command} {pce neighbor as <0-65535>} {} + +{OSPF Command} {pce neighbor as <0-65535>} {} +.. index:: {OSPF Command} {no pce neighbor as <0-65535>} {} + +{OSPF Command} {no pce neighbor as <0-65535>} {} +.. index:: {OSPF Command} {pce flag BITPATTERN} {} + +{OSPF Command} {pce flag BITPATTERN} {} +.. index:: {OSPF Command} {no pce flag} {} + +{OSPF Command} {no pce flag} {} +.. index:: {OSPF Command} {pce scope BITPATTERN} {} + +{OSPF Command} {pce scope BITPATTERN} {} +.. index:: {OSPF Command} {no pce scope} {} + +{OSPF Command} {no pce scope} {} + The commands are conform to RFC 5088 and allow OSPF router announce Path Compuatation Elemenent (PCE) capabilities + through the Router Information (RI) LSA. Router Information must be enable prior to this. The command set/unset + respectively the PCE IP adress, Autonomous System (AS) numbers of controlled domains, neighbor ASs, flag and scope. + For flag and scope, please refer to RFC5088 for the BITPATTERN recognition. Multiple 'pce neighbor' command could + be specified in order to specify all PCE neighbours. + +.. index:: {Command} {show ip ospf router-info} {} + +{Command} {show ip ospf router-info} {} + Show Router Capabilities flag. +.. index:: {Command} {show ip ospf router-info pce} {} + +{Command} {show ip ospf router-info pce} {} + Show Router Capabilities PCE parameters. + +.. _Debugging_OSPF: + +Debugging OSPF +============== + +.. index:: {Command} {debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all) (send|recv) [detail]} {} + +{Command} {debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all) (send|recv) [detail]} {} +.. index:: {Command} {no debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all) (send|recv) [detail]} {} + +{Command} {no debug ospf packet (hello|dd|ls-request|ls-update|ls-ack|all) (send|recv) [detail]} {} + Dump Packet for debugging + +.. index:: {Command} {debug ospf ism} {} + +{Command} {debug ospf ism} {} +.. index:: {Command} {debug ospf ism (status|events|timers)} {} + +{Command} {debug ospf ism (status|events|timers)} {} +.. index:: {Command} {no debug ospf ism} {} + +{Command} {no debug ospf ism} {} +.. index:: {Command} {no debug ospf ism (status|events|timers)} {} + +{Command} {no debug ospf ism (status|events|timers)} {} + Show debug information of Interface State Machine + +.. index:: {Command} {debug ospf nsm} {} + +{Command} {debug ospf nsm} {} +.. index:: {Command} {debug ospf nsm (status|events|timers)} {} + +{Command} {debug ospf nsm (status|events|timers)} {} +.. index:: {Command} {no debug ospf nsm} {} + +{Command} {no debug ospf nsm} {} +.. index:: {Command} {no debug ospf nsm (status|events|timers)} {} + +{Command} {no debug ospf nsm (status|events|timers)} {} + Show debug information of Network State Machine + +.. index:: {Command} {debug ospf event} {} + +{Command} {debug ospf event} {} +.. index:: {Command} {no debug ospf event} {} + +{Command} {no debug ospf event} {} + Show debug information of OSPF event + +.. index:: {Command} {debug ospf nssa} {} + +{Command} {debug ospf nssa} {} +.. index:: {Command} {no debug ospf nssa} {} + +{Command} {no debug ospf nssa} {} + Show debug information about Not So Stub Area + +.. index:: {Command} {debug ospf lsa} {} + +{Command} {debug ospf lsa} {} +.. index:: {Command} {debug ospf lsa (generate|flooding|refresh)} {} + +{Command} {debug ospf lsa (generate|flooding|refresh)} {} +.. index:: {Command} {no debug ospf lsa} {} + +{Command} {no debug ospf lsa} {} +.. index:: {Command} {no debug ospf lsa (generate|flooding|refresh)} {} + +{Command} {no debug ospf lsa (generate|flooding|refresh)} {} + Show debug detail of Link State messages + +.. index:: {Command} {debug ospf te} {} + +{Command} {debug ospf te} {} +.. index:: {Command} {no debug ospf te} {} + +{Command} {no debug ospf te} {} + Show debug information about Traffic Engineering LSA + +.. index:: {Command} {debug ospf zebra} {} + +{Command} {debug ospf zebra} {} +.. index:: {Command} {debug ospf zebra (interface|redistribute)} {} + +{Command} {debug ospf zebra (interface|redistribute)} {} +.. index:: {Command} {no debug ospf zebra} {} + +{Command} {no debug ospf zebra} {} +.. index:: {Command} {no debug ospf zebra (interface|redistribute)} {} + +{Command} {no debug ospf zebra (interface|redistribute)} {} + Show debug information of ZEBRA API + +.. index:: {Command} {show debugging ospf} {} + +{Command} {show debugging ospf} {} + +OSPF Configuration Examples +=========================== + +A simple example, with MD5 authentication enabled: + +:: + + @group + ! + interface bge0 + ip ospf authentication message-digest + ip ospf message-digest-key 1 md5 ABCDEFGHIJK + ! + router ospf + network 192.168.0.0/16 area 0.0.0.1 + area 0.0.0.1 authentication message-digest + @end group + + +An @acronym{ABR} router, with MD5 authentication and performing summarisation +of networks between the areas: + +:: + + @group + ! + password ABCDEF + log file /var/log/frr/ospfd.log + service advanced-vty + ! + interface eth0 + ip ospf authentication message-digest + ip ospf message-digest-key 1 md5 ABCDEFGHIJK + ! + interface ppp0 + ! + interface br0 + ip ospf authentication message-digest + ip ospf message-digest-key 2 md5 XYZ12345 + ! + router ospf + ospf router-id 192.168.0.1 + redistribute connected + passive interface ppp0 + network 192.168.0.0/24 area 0.0.0.0 + network 10.0.0.0/16 area 0.0.0.0 + network 192.168.1.0/24 area 0.0.0.1 + area 0.0.0.0 authentication message-digest + area 0.0.0.0 range 10.0.0.0/16 + area 0.0.0.0 range 192.168.0.0/24 + area 0.0.0.1 authentication message-digest + area 0.0.0.1 range 10.2.0.0/16 + ! + @end group + + +A Traffic Engineering configuration, with Inter-ASv2 support. + +- First, the 'zebra.conf' part: + +:: + + @group + hostname HOSTNAME + password PASSWORD + log file /var/log/zebra.log + ! + interface eth0 + ip address 198.168.1.1/24 + mpls-te on + mpls-te link metric 10 + mpls-te link max-bw 1.25e+06 + mpls-te link max-rsv-bw 1.25e+06 + mpls-te link unrsv-bw 0 1.25e+06 + mpls-te link unrsv-bw 1 1.25e+06 + mpls-te link unrsv-bw 2 1.25e+06 + mpls-te link unrsv-bw 3 1.25e+06 + mpls-te link unrsv-bw 4 1.25e+06 + mpls-te link unrsv-bw 5 1.25e+06 + mpls-te link unrsv-bw 6 1.25e+06 + mpls-te link unrsv-bw 7 1.25e+06 + mpls-te link rsc-clsclr 0xab + ! + interface eth1 + ip address 192.168.2.1/24 + mpls-te on + mpls-te link metric 10 + mpls-te link max-bw 1.25e+06 + mpls-te link max-rsv-bw 1.25e+06 + mpls-te link unrsv-bw 0 1.25e+06 + mpls-te link unrsv-bw 1 1.25e+06 + mpls-te link unrsv-bw 2 1.25e+06 + mpls-te link unrsv-bw 3 1.25e+06 + mpls-te link unrsv-bw 4 1.25e+06 + mpls-te link unrsv-bw 5 1.25e+06 + mpls-te link unrsv-bw 6 1.25e+06 + mpls-te link unrsv-bw 7 1.25e+06 + mpls-te link rsc-clsclr 0xab + mpls-te neighbor 192.168.2.2 as 65000 + @end group + + +- Then the 'ospfd.conf' itself: + +:: + + @group + hostname HOSTNAME + password PASSWORD + log file /var/log/ospfd.log + ! + ! + interface eth0 + ip ospf hello-interval 60 + ip ospf dead-interval 240 + ! + interface eth1 + ip ospf hello-interval 60 + ip ospf dead-interval 240 + ! + ! + router ospf + ospf router-id 192.168.1.1 + network 192.168.0.0/16 area 1 + ospf opaque-lsa + mpls-te + mpls-te router-address 192.168.1.1 + mpls-te inter-as area 1 + ! + line vty + @end group + + +A router information example with PCE advsertisement: + +:: + + @group + ! + router ospf + ospf router-id 192.168.1.1 + network 192.168.0.0/16 area 1 + capability opaque + mpls-te + mpls-te router-address 192.168.1.1 + router-info area 0.0.0.1 + pce address 192.168.1.1 + pce flag 0x80 + pce domain as 65400 + pce neighbor as 65500 + pce neighbor as 65200 + pce scope 0x80 + ! + @end group + + diff --git a/doc/user/overview.rst b/doc/user/overview.rst new file mode 100644 index 0000000000..6393d0ba07 --- /dev/null +++ b/doc/user/overview.rst @@ -0,0 +1,367 @@ +.. _Overview: + +******** +Overview +******** + +.. index:: Overview + +`@value{PACKAGE_URL <@value{PACKAGE_URL>`_,,Frr} is a routing software package that +provides TCP/IP based routing services with routing protocols support such +as RIPv1, RIPv2, RIPng, OSPFv2, OSPFv3, IS-IS, BGP-4, and BGP-4+ (:ref:`Supported_RFCs`). Frr also supports special BGP Route Reflector and Route Server +behavior. In addition to traditional IPv4 routing protocols, Frr also +supports IPv6 routing protocols. With SNMP daemon which supports SMUX and AgentX +protocol, Frr provides routing protocol MIBs (:ref:`SNMP_Support`). + +Frr uses an advanced software architecture to provide you with a high +quality, multi server routing engine. Frr has an interactive user +interface for each routing protocol and supports common client commands. +Due to this design, you can add new protocol daemons to Frr easily. You +can use Frr library as your program's client user interface. + +Frr is distributed under the @sc{gnu} General Public License. + +@comment node-name, next, previous, up + +About Frr +========= + +.. index:: About Frr + +Today, TCP/IP networks are covering all of the world. The Internet has +been deployed in many countries, companies, and to the home. When you +connect to the Internet your packet will pass many routers which have TCP/IP +routing functionality. + +A system with Frr installed acts as a dedicated router. With Frr, +your machine exchanges routing information with other routers using routing +protocols. Frr uses this information to update the kernel routing table +so that the right data goes to the right place. You can dynamically change +the configuration and you may view routing table information from the Frr +terminal interface. + +Adding to routing protocol support, Frr can setup interface's flags, +interface's address, static routes and so on. If you have a small network, +or a stub network, or xDSL connection, configuring the Frr routing +software is very easy. The only thing you have to do is to set up the +interfaces and put a few commands about static routes and/or default routes. +If the network is rather large, or if the network structure changes +frequently, you will want to take advantage of Frr's dynamic routing +protocol support for protocols such as RIP, OSPF, IS-IS or BGP. + +Traditionally, UNIX based router configuration is done by +*ifconfig* and *route* commands. Status of routing +table is displayed by *netstat* utility. Almost of these commands +work only if the user has root privileges. Frr has a different system +administration method. There are two user modes in Frr. One is normal +mode, the other is enable mode. Normal mode user can only view system +status, enable mode user can change system configuration. This UNIX account +independent feature will be great help to the router administrator. + +Currently, Frr supports common unicast routing protocols, that is BGP, +OSPF, RIP and IS-IS. Upcoming for MPLS support, an implementation of LDP is +currently being prepared for merging. Implementations of BFD and PIM-SSM +(IPv4) also exist, but are not actively being worked on. + +The ultimate goal of the Frr project is making a productive, quality, free +TCP/IP routing software package. + +@comment node-name, next, previous, up + +System Architecture +=================== + +.. index:: System architecture + +.. index:: Software architecture + +.. index:: Software internals + +Traditional routing software is made as a one process program which +provides all of the routing protocol functionalities. Frr takes a +different approach. It is made from a collection of several daemons that +work together to build the routing table. There may be several +protocol-specific routing daemons and zebra the kernel routing manager. + +The *ripd* daemon handles the RIP protocol, while +*ospfd* is a daemon which supports OSPF version 2. +*bgpd* supports the BGP-4 protocol. For changing the kernel +routing table and for redistribution of routes between different routing +protocols, there is a kernel routing table manager *zebra* daemon. +It is easy to add a new routing protocol daemons to the entire routing +system without affecting any other software. You need to run only the +protocol daemon associated with routing protocols in use. Thus, user may +run a specific daemon and send routing reports to a central routing console. + +There is no need for these daemons to be running on the same machine. You +can even run several same protocol daemons on the same machine. This +architecture creates new possibilities for the routing system. + +:: + + @group + +----+ +----+ +-----+ +-----+ + |bgpd| |ripd| |ospfd| |zebra| + +----+ +----+ +-----+ +-----+ + | + +---------------------------|--+ + | v | + | UNIX Kernel routing table | + | | + +------------------------------+ + + Frr System Architecture + @end group + + +Multi-process architecture brings extensibility, modularity and +maintainability. At the same time it also brings many configuration files +and terminal interfaces. Each daemon has it's own configuration file and +terminal interface. When you configure a static route, it must be done in +*zebra* configuration file. When you configure BGP network it must +be done in *bgpd* configuration file. This can be a very annoying +thing. To resolve the problem, Frr provides integrated user interface +shell called *vtysh*. *vtysh* connects to each daemon with +UNIX domain socket and then works as a proxy for user input. + +Frr was planned to use multi-threaded mechanism when it runs with a +kernel that supports multi-threads. But at the moment, the thread library +which comes with @sc{gnu}/Linux or FreeBSD has some problems with running +reliable services such as routing software, so we don't use threads at all. +Instead we use the *select(2)* system call for multiplexing the +events. + +@comment node-name, next, previous, up + +Supported Platforms +=================== + +.. index:: Supported platforms + +.. index:: Frr on other systems + +.. index:: Compatibility with other systems + +.. index:: Operating systems that support Frr + +Currently Frr supports @sc{gnu}/Linux and BSD. Porting Frr +to other platforms is not too difficult as platform dependent code should +most be limited to the *zebra* daemon. Protocol daemons are mostly +platform independent. Please let us know when you find out Frr runs on a +platform which is not listed below. + +The list of officially supported platforms are listed below. Note that +Frr may run correctly on other platforms, and may run with partial +functionality on further platforms. + +@sp 1 + +* + @sc{gnu}/Linux +* + FreeBSD +* + NetBSD +* + OpenBSD + +Versions of these platforms that are older than around 2 years from the point +of their original release (in case of @sc{gnu}/Linux, this is since the kernel's +release on kernel.org) may need some work. Similarly, the following platforms +may work with some effort: + +@sp 1 + +* + Solaris +* + Mac OSX + +Also note that, in particular regarding proprietary platforms, compiler +and C library choice will affect Frr. Only recent versions of the +following C compilers are well-tested: + +@sp 1 + +* + @sc{gnu}'s GCC +* + LLVM's clang +* + Intel's ICC + +@comment node-name, next, previous, up + +Supported RFCs +============== + +Below is the list of currently supported RFC's. + + + +*@asis{RFC1058}* + @cite{Routing Information Protocol. C.L. Hedrick. Jun-01-1988.} + + +*@asis{RF2082}* + @cite{RIP-2 MD5 Authentication. F. Baker, R. Atkinson. January 1997.} + + +*@asis{RFC2453}* + @cite{RIP Version 2. G. Malkin. November 1998.} + + +*@asis{RFC2080}* + @cite{RIPng for IPv6. G. Malkin, R. Minnear. January 1997.} + + +*@asis{RFC2328}* + @cite{OSPF Version 2. J. Moy. April 1998.} + + +*@asis{RFC2370}* + @cite{The OSPF Opaque LSA Option R. Coltun. July 1998.} + + +*@asis{RFC3101}* + @cite{The OSPF Not-So-Stubby Area (NSSA) Option P. Murphy. January 2003.} + + +*@asis{RFC2740}* + @cite{OSPF for IPv6. R. Coltun, D. Ferguson, J. Moy. December 1999.} + + +*@asis{RFC1771}* + @cite{A Border Gateway Protocol 4 (BGP-4). Y. Rekhter & T. Li. March 1995.} + + +*@asis{RFC1965}* + @cite{Autonomous System Confederations for BGP. P. Traina. June 1996.} + + +*@asis{RFC1997}* + @cite{BGP Communities Attribute. R. Chandra, P. Traina & T. Li. August 1996.} + + +*@asis{RFC2545}* + @cite{Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing. P. Marques, F. Dupont. March 1999.} + + +*@asis{RFC2796}* + @cite{BGP Route Reflection An alternative to full mesh IBGP. T. Bates & R. Chandrasekeran. June 1996.} + + +*@asis{RFC2858}* + @cite{Multiprotocol Extensions for BGP-4. T. Bates, Y. Rekhter, R. Chandra, D. Katz. June 2000.} + + +*@asis{RFC2842}* + @cite{Capabilities Advertisement with BGP-4. R. Chandra, J. Scudder. May 2000.} + + +*@asis{RFC3137}* + @cite{OSPF Stub Router Advertisement, A. Retana, L. Nguyen, R. White, A. Zinin, D. McPherson. June 2001} + +When SNMP support is enabled, below RFC is also supported. + + + +*@asis{RFC1227}* + @cite{SNMP MUX protocol and MIB. M.T. Rose. May-01-1991.} + + +*@asis{RFC1657}* + @cite{Definitions of Managed Objects for the Fourth Version of the + Border Gateway Protocol (BGP-4) using SMIv2. S. Willis, J. Burruss, + J. Chu, Editor. July 1994.} + + +*@asis{RFC1724}* + @cite{RIP Version 2 MIB Extension. G. Malkin & F. Baker. November 1994.} + + +*@asis{RFC1850}* + @cite{OSPF Version 2 Management Information Base. F. Baker, R. Coltun. + November 1995.} + + +*@asis{RFC2741}* + @cite{Agent Extensibility (AgentX) Protocol. M. Daniele, B. Wijnen. January 2000.} + + +@comment node-name, next, previous, up + +How to get Frr +============== + +The official Frr web-site is located at: + +`@value{PACKAGE_URL <@value{PACKAGE_URL>`_} + +and contains further information, as well as links to additional +resources. + +`@value{PACKAGE_URL <@value{PACKAGE_URL>`_,Frr} is a fork of Quagga, whose +web-site is located at: + +`http://www.quagga.net/ `_. + +@comment node-name, next, previous, up + +Mailing List +============ + +.. index:: How to get in touch with Frr + +.. index:: Mailing Frr + +.. index:: Contact information + +.. index:: Mailing lists + +There is a mailing list for discussions about Frr. If you have any +comments or suggestions to Frr, please subscribe to: + +`https://lists.frrouting.org/listinfo/frog `_. + +The `@value{PACKAGE_URL <@value{PACKAGE_URL>`_,,Frr} site has further information on +the available mailing lists, see: + +`https://lists.frrouting.org/ `_ + +Bug Reports +=========== + +.. index:: Bug Reports + +.. index:: Bug hunting + +.. index:: Found a bug? + +.. index:: Reporting bugs + +.. index:: Reporting software errors + +.. index:: Errors in the software + +If you think you have found a bug, please send a bug report to: + +`http://github.com/frrouting/frr/issues `_ + +When you send a bug report, please be careful about the points below. + +* + Please note what kind of OS you are using. If you use the IPv6 stack + please note that as well. +* + Please show us the results of `netstat -rn` and `ifconfig -a`. + Information from zebra's VTY command `show ip route` will also be + helpful. +* + Please send your configuration file with the report. If you specify + arguments to the configure script please note that too. + +Bug reports are very important for us to improve the quality of Frr. +Frr is still in the development stage, but please don't hesitate to +send a bug report to `http://github.com/frrouting/frr/issues `_. + diff --git a/doc/user/protocol.rst b/doc/user/protocol.rst new file mode 100644 index 0000000000..2a9b76df03 --- /dev/null +++ b/doc/user/protocol.rst @@ -0,0 +1,128 @@ +.. _Zebra_Protocol + +************** +Zebra Protocol +************** + +Overview of the Zebra Protocol +============================== + +Zebra Protocol is used by protocol daemons to communicate with the +zebra daemon. + +Each protocol daemon may request and send information to and from the +zebra daemon such as interface states, routing state, +nexthop-validation, and so on. Protocol daemons may also install routes +with zebra. The zebra daemon manages which route is installed into the +forwarding table with the kernel. + +Zebra Protocol is a streaming protocol, with a common header. Two +versions of the header are in use. Version 0 is implicitely versioned. +Version 1 has an explicit version field. Version 0 can be distinguished +from all other versions by examining the 3rd byte of the header, which +contains a marker value for all versions bar version 0. The marker byte +corresponds to the command field in version 0, and the marker value is +a reserved command in version 0. + +We do not anticipate there will be further versions of the header for +the foreseeable future, as the command field in version 1 is wide +enough to allow for future extensions to done compatibly through +seperate commands. + +Version 0 is used by all versions of GNU Zebra as of this writing, and +versions of Quagga up to and including Quagga 0.98. Version 2 was created +for 0.99.21 of Quagga. Version 3 designates VRF compatibility and was +released in 1.0. Version 4 will be used as of Frr 2.0 to indicate that +we are a different Routing Suite now and to hopefully prevent accidental +Quagga <-> FRR issues. + +Zebra Protocol Definition +========================= + +Zebra Protocol Header (version 0) +---------------------------------- + +:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-------------------------------+---------------+ + | Length (2) | Command (1) | + +-------------------------------+---------------+ + + +Zebra Protocol Common Header (version 1) +---------------------------------------- + +:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-------------------------------+---------------+-------------+ + | Length (2) | Marker (1) | Version (1) | + +-------------------------------+---------------+-------------+ + | Command (2) | + +-------------------------------+ + + +Zebra Protocol Header Field Definitions +--------------------------------------- + +@table @samp +@item Length +Total packet length including this header. The minimum length is 3 +bytes for version 0 messages and 6 bytes for version 1 messages. + +@item Marker +Static marker with a value of 255 always. This is to allow version 0 +Zserv headers (which do not include version explicitely) to be +distinguished from versioned headers. Not present in version 0 +messages. + +@item Version +Version number of the Zserv message. Clients should not continue +processing messages past the version field for versions they do not +recognise. Not present in version 0 messages. + +@item Command +The Zebra Protocol command. +@end table + +Zebra Protocol Commands +----------------------- + +@multitable {ZEBRA_REDISTRIBUTE_DEFAULT_DELETE_WHATEVER} {99999} +@headitem Command @tab Value +@item ZEBRA_INTERFACE_ADD +@tab 1 +@item ZEBRA_INTERFACE_DELETE +@tab 2 +@item ZEBRA_INTERFACE_ADDRESS_ADD +@tab 3 +@item ZEBRA_INTERFACE_ADDRESS_DELETE +@tab 4 +@item ZEBRA_INTERFACE_UP +@tab 5 +@item ZEBRA_INTERFACE_DOWN +@tab 6 +@item ZEBRA_IPV4_ROUTE_ADD +@tab 7 +@item ZEBRA_IPV4_ROUTE_DELETE +@tab 8 +@item ZEBRA_IPV6_ROUTE_ADD +@tab 9 +@item ZEBRA_IPV6_ROUTE_DELETE +@tab 10 +@item ZEBRA_REDISTRIBUTE_ADD +@tab 11 +@item ZEBRA_REDISTRIBUTE_DELETE +@tab 12 +@item ZEBRA_REDISTRIBUTE_DEFAULT_ADD +@tab 13 +@item ZEBRA_REDISTRIBUTE_DEFAULT_DELETE +@tab 14 +@item ZEBRA_IPV4_NEXTHOP_LOOKUP +@tab 15 +@item ZEBRA_IPV6_NEXTHOP_LOOKUP +@tab 16 +@end multitable diff --git a/doc/user/ripd.rst b/doc/user/ripd.rst new file mode 100644 index 0000000000..0aae9bcc39 --- /dev/null +++ b/doc/user/ripd.rst @@ -0,0 +1,738 @@ +.. _RIP: + +*** +RIP +*** + +RIP -- Routing Information Protocol is widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the +XNS routing protocol. RIP is a @dfn{distance-vector} protocol and is +based on the @dfn{Bellman-Ford} algorithms. As a distance-vector +protocol, RIP router send updates to its neighbors periodically, thus +allowing the convergence to a known topology. In each update, the +distance to any given network will be broadcasted to its neighboring +router. + +*ripd* supports RIP version 2 as described in RFC2453 and RIP +version 1 as described in RFC1058. + +.. _Starting_and_Stopping_ripd: + +Starting and Stopping ripd +========================== + +The default configuration file name of *ripd*'s is +:file:`ripd.conf`. When invocation *ripd* searches directory +@value{INSTALL_PREFIX_ETC}. If :file:`ripd.conf` is not there next +search current directory. + +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: + +:: + + @group + # zebra -d + # ripd -d + @end group + + +Please note that *zebra* must be invoked before *ripd*. + +To stop *ripd*. Please use @command{kill `cat +/var/run/ripd.pid`}. Certain signals have special meaningss to *ripd*. + + + +*SIGHUP* + Reload configuration file :file:`ripd.conf`. All configurations are + reseted. All routes learned so far are cleared and removed from routing + table. + +*SIGUSR1* + Rotate *ripd* logfile. + +*SIGINT* + +*SIGTERM* + *ripd* sweeps all installed RIP routes then terminates properly. + +*ripd* invocation options. Common options that can be specified +(:ref:`Common_Invocation_Options`). + + + +*-r* + +*--retain* + When the program terminates, retain routes added by *ripd*. + +.. _RIP_netmask: + +RIP netmask +----------- + +The netmask features of *ripd* support both version 1 and version 2 of +RIP. Version 1 of RIP originally contained no netmask information. In +RIP version 1, network classes were originally used to determine the +size of the netmask. Class A networks use 8 bits of mask, Class B +networks use 16 bits of masks, while Class C networks use 24 bits of +mask. Today, the most widely used method of a network mask is assigned +to the packet on the basis of the interface that received the packet. +Version 2 of RIP supports a variable length subnet mask (VLSM). By +extending the subnet mask, the mask can be divided and reused. Each +subnet can be used for different purposes such as large to middle size +LANs and WAN links. Frr *ripd* does not support the non-sequential +netmasks that are included in RIP Version 2. + +In a case of similar information with the same prefix and metric, the +old information will be suppressed. Ripd does not currently support +equal cost multipath routing. + +.. _RIP_Configuration: + +RIP Configuration +================= + +.. index:: Command {router rip} {} + +Command {router rip} {} + The `router rip` command is necessary to enable RIP. To disable + RIP, use the `no router rip` command. RIP must be enabled before + carrying out any of the RIP commands. + +.. index:: Command {no router rip} {} + +Command {no router rip} {} + Disable RIP. + +.. index:: {RIP Command} {network `network`} {} + +{RIP Command} {network `network`} {} +.. index:: {RIP Command} {no network `network`} {} + +{RIP Command} {no network `network`} {} + Set the RIP enable interface by `network`. The interfaces which + have addresses matching with `network` are enabled. + + This group of commands either enables or disables RIP interfaces between + certain numbers of a specified network address. For example, if the + network for 10.0.0.0/24 is RIP enabled, this would result in all the + addresses from 10.0.0.0 to 10.0.0.255 being enabled for RIP. The `no network` command will disable RIP for the specified network. + +.. index:: {RIP Command} {network `ifname`} {} + +{RIP Command} {network `ifname`} {} +.. index:: {RIP Command} {no network `ifname`} {} + +{RIP Command} {no network `ifname`} {} + Set a RIP enabled interface by `ifname`. Both the sending and + receiving of RIP packets will be enabled on the port specified in the + `network ifname` command. The `no network ifname` command will disable + RIP on the specified interface. + +.. index:: {RIP Command} {neighbor `a.b.c.d`} {} + +{RIP Command} {neighbor `a.b.c.d`} {} +.. index:: {RIP Command} {no neighbor `a.b.c.d`} {} + +{RIP Command} {no neighbor `a.b.c.d`} {} + Specify RIP neighbor. When a neighbor doesn't understand multicast, + this command is used to specify neighbors. In some cases, not all + routers will be able to understand multicasting, where packets are sent + to a network or a group of addresses. In a situation where a neighbor + cannot process multicast packets, it is necessary to establish a direct + link between routers. The neighbor command allows the network + administrator to specify a router as a RIP neighbor. The `no neighbor a.b.c.d` command will disable the RIP neighbor. + + Below is very simple RIP configuration. Interface `eth0` and + interface which address match to `10.0.0.0/8` are RIP enabled. + +:: + + @group + ! + router rip + network 10.0.0.0/8 + network eth0 + ! + @end group + + + Passive interface + +.. index:: {RIP command} {passive-interface (`IFNAME`|default)} {} + +{RIP command} {passive-interface (`IFNAME`|default)} {} +.. index:: {RIP command} {no passive-interface `IFNAME`} {} + +{RIP command} {no passive-interface `IFNAME`} {} + This command sets the specified interface to passive mode. On passive mode + interface, all receiving packets are processed as normal and ripd does + not send either multicast or unicast RIP packets except to RIP neighbors + specified with `neighbor` command. The interface may be specified + as `default` to make ripd default to passive on all interfaces. + + The default is to be passive on all interfaces. + + RIP split-horizon + +.. index:: {Interface command} {ip split-horizon} {} + +{Interface command} {ip split-horizon} {} +.. index:: {Interface command} {no ip split-horizon} {} + +{Interface command} {no ip split-horizon} {} + Control split-horizon on the interface. Default is `ip split-horizon`. If you don't perform split-horizon on the interface, + please specify `no ip split-horizon`. + +.. _RIP_Version_Control: + +RIP Version Control +=================== + +RIP can be configured to send either Version 1 or Version 2 packets. +The default is to send RIPv2 while accepting both RIPv1 and RIPv2 (and +replying with packets of the appropriate version for REQUESTS / +triggered updates). The version to receive and send can be specified +globally, and further overriden on a per-interface basis if needs be +for send and receive seperately (see below). + +It is important to note that RIPv1 can not be authenticated. Further, +if RIPv1 is enabled then RIP will reply to REQUEST packets, sending the +state of its RIP routing table to any remote routers that ask on +demand. For a more detailed discussion on the security implications of +RIPv1 see :ref:`RIP_Authentication`. + +.. index:: {RIP Command} {version `version`} {} + +{RIP Command} {version `version`} {} + Set RIP version to accept for reads and send. `version` + can be either `1'' or `2''. + + Disabling RIPv1 by specifying version 2 is STRONGLY encouraged, + :ref:`RIP_Authentication`. This may become the default in a future + release. + + Default: Send Version 2, and accept either version. + +.. index:: {RIP Command} {no version} {} + +{RIP Command} {no version} {} + Reset the global version setting back to the default. + +.. index:: {Interface command} {ip rip send version `version`} {} + +{Interface command} {ip rip send version `version`} {} + `version` can be `1', `2' or `1 2'. + + This interface command overrides the global rip version setting, and + selects which version of RIP to send packets with, for this interface + specifically. Choice of RIP Version 1, RIP Version 2, or both versions. + In the latter case, where `1 2' is specified, packets will be both + broadcast and multicast. + + Default: Send packets according to the global version (version 2) + +.. index:: {Interface command} {ip rip receive version `version`} {} + +{Interface command} {ip rip receive version `version`} {} + `version` can be `1', `2' or `1 2'. + + This interface command overrides the global rip version setting, and + selects which versions of RIP packets will be accepted on this + interface. Choice of RIP Version 1, RIP Version 2, or both. + + Default: Accept packets according to the global setting (both 1 and 2). + +.. _How_to_Announce_RIP_route: + +How to Announce RIP route +========================= + +.. index:: {RIP command} {redistribute kernel} {} + +{RIP command} {redistribute kernel} {} +.. index:: {RIP command} {redistribute kernel metric <0-16>} {} + +{RIP command} {redistribute kernel metric <0-16>} {} +.. index:: {RIP command} {redistribute kernel route-map `route-map`} {} + +{RIP command} {redistribute kernel route-map `route-map`} {} +.. index:: {RIP command} {no redistribute kernel} {} + +{RIP command} {no redistribute kernel} {} + `redistribute kernel` redistributes routing information from + kernel route entries into the RIP tables. `no redistribute kernel` + disables the routes. + +.. index:: {RIP command} {redistribute static} {} + +{RIP command} {redistribute static} {} +.. index:: {RIP command} {redistribute static metric <0-16>} {} + +{RIP command} {redistribute static metric <0-16>} {} +.. index:: {RIP command} {redistribute static route-map `route-map`} {} + +{RIP command} {redistribute static route-map `route-map`} {} +.. index:: {RIP command} {no redistribute static} {} + +{RIP command} {no redistribute static} {} + `redistribute static` redistributes routing information from + static route entries into the RIP tables. `no redistribute static` + disables the routes. + +.. index:: {RIP command} {redistribute connected} {} + +{RIP command} {redistribute connected} {} +.. index:: {RIP command} {redistribute connected metric <0-16>} {} + +{RIP command} {redistribute connected metric <0-16>} {} +.. index:: {RIP command} {redistribute connected route-map `route-map`} {} + +{RIP command} {redistribute connected route-map `route-map`} {} +.. index:: {RIP command} {no redistribute connected} {} + +{RIP command} {no redistribute connected} {} + Redistribute connected routes into the RIP tables. `no redistribute connected` disables the connected routes in the RIP tables. + This command redistribute connected of the interface which RIP disabled. + The connected route on RIP enabled interface is announced by default. + +.. index:: {RIP command} {redistribute ospf} {} + +{RIP command} {redistribute ospf} {} +.. index:: {RIP command} {redistribute ospf metric <0-16>} {} + +{RIP command} {redistribute ospf metric <0-16>} {} +.. index:: {RIP command} {redistribute ospf route-map `route-map`} {} + +{RIP command} {redistribute ospf route-map `route-map`} {} +.. index:: {RIP command} {no redistribute ospf} {} + +{RIP command} {no redistribute ospf} {} + `redistribute ospf` redistributes routing information from + ospf route entries into the RIP tables. `no redistribute ospf` + disables the routes. + +.. index:: {RIP command} {redistribute bgp} {} + +{RIP command} {redistribute bgp} {} +.. index:: {RIP command} {redistribute bgp metric <0-16>} {} + +{RIP command} {redistribute bgp metric <0-16>} {} +.. index:: {RIP command} {redistribute bgp route-map `route-map`} {} + +{RIP command} {redistribute bgp route-map `route-map`} {} +.. index:: {RIP command} {no redistribute bgp} {} + +{RIP command} {no redistribute bgp} {} + `redistribute bgp` redistributes routing information from + bgp route entries into the RIP tables. `no redistribute bgp` + disables the routes. + + If you want to specify RIP only static routes: + +.. index:: {RIP command} {default-information originate} {} + +{RIP command} {default-information originate} {} +.. index:: {RIP command} {route `a.b.c.d/m`} {} + +{RIP command} {route `a.b.c.d/m`} {} +.. index:: {RIP command} {no route `a.b.c.d/m`} {} + +{RIP command} {no route `a.b.c.d/m`} {} + This command is specific to Frr. The `route` command makes a static + route only inside RIP. This command should be used only by advanced + users who are particularly knowledgeable about the RIP protocol. In + most cases, we recommend creating a static route in Frr and + redistributing it in RIP using `redistribute static`. + +.. _Filtering_RIP_Routes: + +Filtering RIP Routes +==================== + +RIP routes can be filtered by a distribute-list. + +.. index:: Command {distribute-list `access_list` `direct` `ifname`} {} + +Command {distribute-list `access_list` `direct` `ifname`} {} + You can apply access lists to the interface with a `distribute-list` + command. `access_list` is the access list name. `direct` is + @samp{in} or @samp{out}. If `direct` is @samp{in} the access list + is applied to input packets. + + The `distribute-list` command can be used to filter the RIP path. + `distribute-list` can apply access-lists to a chosen interface. + First, one should specify the access-list. Next, the name of the + access-list is used in the distribute-list command. For example, in the + following configuration @samp{eth0} will permit only the paths that + match the route 10.0.0.0/8 + +:: + + @group + ! + router rip + distribute-list private in eth0 + ! + access-list private permit 10 10.0.0.0/8 + access-list private deny any + ! + @end group + + +`distribute-list` can be applied to both incoming and outgoing data. + +.. index:: Command {distribute-list prefix `prefix_list` (in|out) `ifname`} {} + +Command {distribute-list prefix `prefix_list` (in|out) `ifname`} {} + You can apply prefix lists to the interface with a + `distribute-list` command. `prefix_list` is the prefix list + name. Next is the direction of @samp{in} or @samp{out}. If + `direct` is @samp{in} the access list is applied to input packets. + +.. _RIP_Metric_Manipulation: + +RIP Metric Manipulation +======================= + +RIP metric is a value for distance for the network. Usually +*ripd* increment the metric when the network information is +received. Redistributed routes' metric is set to 1. + +.. index:: {RIP command} {default-metric <1-16>} {} + +{RIP command} {default-metric <1-16>} {} +.. index:: {RIP command} {no default-metric <1-16>} {} + +{RIP command} {no default-metric <1-16>} {} + This command modifies the default metric value for redistributed routes. The + default value is 1. This command does not affect connected route + even if it is redistributed by *redistribute connected*. To modify + connected route's metric value, please use @command{redistribute + connected metric} or *route-map*. *offset-list* also + affects connected routes. + +.. index:: {RIP command} {offset-list `access-list` (in|out)} {} + +{RIP command} {offset-list `access-list` (in|out)} {} +.. index:: {RIP command} {offset-list `access-list` (in|out) `ifname`} {} + +{RIP command} {offset-list `access-list` (in|out) `ifname`} {} + +.. _RIP_distance: + +RIP distance +============ + +Distance value is used in zebra daemon. Default RIP distance is 120. + +.. index:: {RIP command} {distance <1-255>} {} + +{RIP command} {distance <1-255>} {} +.. index:: {RIP command} {no distance <1-255>} {} + +{RIP command} {no distance <1-255>} {} + Set default RIP distance to specified value. + +.. index:: {RIP command} {distance <1-255> `A.B.C.D/M`} {} + +{RIP command} {distance <1-255> `A.B.C.D/M`} {} +.. index:: {RIP command} {no distance <1-255> `A.B.C.D/M`} {} + +{RIP command} {no distance <1-255> `A.B.C.D/M`} {} + Set default RIP distance to specified value when the route's source IP + address matches the specified prefix. + +.. index:: {RIP command} {distance <1-255> `A.B.C.D/M` `access-list`} {} + +{RIP command} {distance <1-255> `A.B.C.D/M` `access-list`} {} +.. index:: {RIP command} {no distance <1-255> `A.B.C.D/M` `access-list`} {} + +{RIP command} {no distance <1-255> `A.B.C.D/M` `access-list`} {} + Set default RIP distance to specified value when the route's source IP + address matches the specified prefix and the specified access-list. + +.. _RIP_route-map: + +RIP route-map +============= + +Usage of *ripd*'s route-map support. + +Optional argument route-map MAP_NAME can be added to each `redistribute` +statement. + +:: + + redistribute static [route-map MAP_NAME] + redistribute connected [route-map MAP_NAME] + ..... + + +Cisco applies route-map _before_ routes will exported to rip route table. +In current Frr's test implementation, *ripd* applies route-map +after routes are listed in the route table and before routes will be +announced to an interface (something like output filter). I think it is not +so clear, but it is draft and it may be changed at future. + +Route-map statement (:ref:`Route_Map`) is needed to use route-map +functionality. + +.. index:: {Route Map} {match interface `word`} {} + +{Route Map} {match interface `word`} {} + This command match to incoming interface. Notation of this match is + different from Cisco. Cisco uses a list of interfaces - NAME1 NAME2 + ... NAMEN. Ripd allows only one name (maybe will change in the + future). Next - Cisco means interface which includes next-hop of + routes (it is somewhat similar to "ip next-hop" statement). Ripd + means interface where this route will be sent. This difference is + because "next-hop" of same routes which sends to different interfaces + must be different. Maybe it'd be better to made new matches - say + "match interface-out NAME" or something like that. + +.. index:: {Route Map} {match ip address `word`} {} + +{Route Map} {match ip address `word`} {} +.. index:: {Route Map} {match ip address prefix-list `word`} {} + +{Route Map} {match ip address prefix-list `word`} {} + Match if route destination is permitted by access-list. + +.. index:: {Route Map} {match ip next-hop `word`} {} + +{Route Map} {match ip next-hop `word`} {} +.. index:: {Route Map} {match ip next-hop prefix-list `word`} {} + +{Route Map} {match ip next-hop prefix-list `word`} {} + Match if route next-hop (meaning next-hop listed in the rip route-table + as displayed by "show ip rip") is permitted by access-list. + +.. index:: {Route Map} {match metric <0-4294967295>} {} + +{Route Map} {match metric <0-4294967295>} {} + This command match to the metric value of RIP updates. For other + protocol compatibility metric range is shown as <0-4294967295>. But + for RIP protocol only the value range <0-16> make sense. + +.. index:: {Route Map} {set ip next-hop A.B.C.D} {} + +{Route Map} {set ip next-hop A.B.C.D} {} + This command set next hop value in RIPv2 protocol. This command does + not affect RIPv1 because there is no next hop field in the packet. + +.. index:: {Route Map} {set metric <0-4294967295>} {} + +{Route Map} {set metric <0-4294967295>} {} + Set a metric for matched route when sending announcement. The metric + value range is very large for compatibility with other protocols. For + RIP, valid metric values are from 1 to 16. + +.. _RIP_Authentication: + +RIP Authentication +================== + +RIPv2 allows packets to be authenticated via either an insecure plain +text password, included with the packet, or via a more secure MD5 based +@acronym{HMAC, keyed-Hashing for Message AuthentiCation}, +RIPv1 can not be authenticated at all, thus when authentication is +configured `ripd` will discard routing updates received via RIPv1 +packets. + +However, unless RIPv1 reception is disabled entirely, +:ref:`RIP_Version_Control`, RIPv1 REQUEST packets which are received, +which query the router for routing information, will still be honoured +by `ripd`, and `ripd` WILL reply to such packets. This allows +`ripd` to honour such REQUESTs (which sometimes is used by old +equipment and very simple devices to bootstrap their default route), +while still providing security for route updates which are received. + +In short: Enabling authentication prevents routes being updated by +unauthenticated remote routers, but still can allow routes (I.e. the +entire RIP routing table) to be queried remotely, potentially by anyone +on the internet, via RIPv1. + +To prevent such unauthenticated querying of routes disable RIPv1, +:ref:`RIP_Version_Control`. + +.. index:: {Interface command} {ip rip authentication mode md5} {} + +{Interface command} {ip rip authentication mode md5} {} +.. index:: {Interface command} {no ip rip authentication mode md5} {} + +{Interface command} {no ip rip authentication mode md5} {} + Set the interface with RIPv2 MD5 authentication. + +.. index:: {Interface command} {ip rip authentication mode text} {} + +{Interface command} {ip rip authentication mode text} {} +.. index:: {Interface command} {no ip rip authentication mode text} {} + +{Interface command} {no ip rip authentication mode text} {} + Set the interface with RIPv2 simple password authentication. + +.. index:: {Interface command} {ip rip authentication string `string`} {} + +{Interface command} {ip rip authentication string `string`} {} +.. index:: {Interface command} {no ip rip authentication string `string`} {} + +{Interface command} {no ip rip authentication string `string`} {} + RIP version 2 has simple text authentication. This command sets + authentication string. The string must be shorter than 16 characters. + +.. index:: {Interface command} {ip rip authentication key-chain `key-chain`} {} + +{Interface command} {ip rip authentication key-chain `key-chain`} {} +.. index:: {Interface command} {no ip rip authentication key-chain `key-chain`} {} + +{Interface command} {no ip rip authentication key-chain `key-chain`} {} + Specifiy Keyed MD5 chain. + +:: + + ! + key chain test + key 1 + key-string test + ! + interface eth1 + ip rip authentication mode md5 + ip rip authentication key-chain test + ! + + +.. _RIP_Timers: + +RIP Timers +========== + +.. index:: {RIP command} {timers basic `update` `timeout` `garbage`} {} + +{RIP command} {timers basic `update` `timeout` `garbage`} {} + + RIP protocol has several timers. User can configure those timers' values + by `timers basic` command. + + The default settings for the timers are as follows: + + +`` + The update timer is 30 seconds. Every update timer seconds, the RIP + process is awakened to send an unsolicited Response message containing + the complete routing table to all neighboring RIP routers. + + +`` + The timeout timer is 180 seconds. Upon expiration of the timeout, the + route is no longer valid; however, it is retained in the routing table + for a short time so that neighbors can be notified that the route has + been dropped. + + +`` + The garbage collect timer is 120 seconds. Upon expiration of the + garbage-collection timer, the route is finally removed from the routing + table. + + + The `timers basic` command allows the the default values of the timers + listed above to be changed. + +.. index:: {RIP command} {no timers basic} {} + +{RIP command} {no timers basic} {} + The `no timers basic` command will reset the timers to the default + settings listed above. + +.. _Show_RIP_Information: + +Show RIP Information +==================== + +To display RIP routes. + +.. index:: Command {show ip rip} {} + +Command {show ip rip} {} + Show RIP routes. + +The command displays all RIP routes. For routes that are received +through RIP, this command will display the time the packet was sent and +the tag information. This command will also display this information +for routes redistributed into RIP. + +.. index:: Command {show ip rip status} {} + +Command {show ip rip status} {} + The command displays current RIP status. It includes RIP timer, + filtering, version, RIP enabled interface and RIP peer inforation. + +:: + + @group + ripd> **show ip rip status** + Routing Protocol is "rip" + Sending updates every 30 seconds with +/-50%, next due in 35 seconds + Timeout after 180 seconds, garbage collect after 120 seconds + Outgoing update filter list for all interface is not set + Incoming update filter list for all interface is not set + Default redistribution metric is 1 + Redistributing: kernel connected + Default version control: send version 2, receive version 2 + Interface Send Recv + Routing for Networks: + eth0 + eth1 + 1.1.1.1 + 203.181.89.241 + Routing Information Sources: + Gateway BadPackets BadRoutes Distance Last Update + @end group + + +RIP Debug Commands +================== + +Debug for RIP protocol. + +.. index:: Command {debug rip events} {} + +Command {debug rip events} {} + Debug rip events. + +`debug rip` will show RIP events. Sending and receiving +packets, timers, and changes in interfaces are events shown with *ripd*. + +.. index:: Command {debug rip packet} {} + +Command {debug rip packet} {} + Debug rip packet. + +`debug rip packet` will display detailed information about the RIP +packets. The origin and port number of the packet as well as a packet +dump is shown. + +.. index:: Command {debug rip zebra} {} + +Command {debug rip zebra} {} + Debug rip between zebra communication. + +This command will show the communication between *ripd* and +*zebra*. The main information will include addition and deletion of +paths to the kernel and the sending and receiving of interface information. + +.. index:: Command {show debugging rip} {} + +Command {show debugging rip} {} + Display *ripd*'s debugging option. + +`show debugging rip` will show all information currently set for ripd +debug. + diff --git a/doc/user/ripngd.rst b/doc/user/ripngd.rst new file mode 100644 index 0000000000..2c4bfa2c35 --- /dev/null +++ b/doc/user/ripngd.rst @@ -0,0 +1,93 @@ +.. _RIPng: + +***** +RIPng +***** + +*ripngd* supports the RIPng protocol as described in RFC2080. It's an +IPv6 reincarnation of the RIP protocol. + +.. _Invoking_ripngd: + +Invoking ripngd +=============== + +There are no `ripngd` specific invocation options. Common options +can be specified (:ref:`Common_Invocation_Options`). + +.. _ripngd_Configuration: + +ripngd Configuration +==================== + +Currently ripngd supports the following commands: + +.. index:: Command {router ripng} {} + +Command {router ripng} {} + Enable RIPng. + +.. index:: {RIPng Command} {flush_timer `time`} {} + +{RIPng Command} {flush_timer `time`} {} + Set flush timer. + +.. index:: {RIPng Command} {network `network`} {} + +{RIPng Command} {network `network`} {} + Set RIPng enabled interface by `network` + +.. index:: {RIPng Command} {network `ifname`} {} + +{RIPng Command} {network `ifname`} {} + Set RIPng enabled interface by `ifname` + +.. index:: {RIPng Command} {route `network`} {} + +{RIPng Command} {route `network`} {} + Set RIPng static routing announcement of `network`. + +.. index:: Command {router zebra} {} + +Command {router zebra} {} + This command is the default and does not appear in the configuration. + With this statement, RIPng routes go to the *zebra* daemon. + +.. _ripngd_Terminal_Mode_Commands: + +ripngd Terminal Mode Commands +============================= + +.. index:: Command {show ip ripng} {} + +Command {show ip ripng} {} + +.. index:: Command {show debugging ripng} {} + +Command {show debugging ripng} {} +.. index:: Command {debug ripng events} {} + +Command {debug ripng events} {} +.. index:: Command {debug ripng packet} {} + +Command {debug ripng packet} {} +.. index:: Command {debug ripng zebra} {} + +Command {debug ripng zebra} {} + +ripngd Filtering Commands +========================= + +.. index:: Command {distribute-list `access_list` (in|out) `ifname`} {} + +Command {distribute-list `access_list` (in|out) `ifname`} {} + You can apply an access-list to the interface using the + `distribute-list` command. `access_list` is an access-list + name. `direct` is @samp{in} or @samp{out}. If `direct` is + @samp{in}, the access-list is applied only to incoming packets. + +:: + + distribute-list local-only out sit1 + + diff --git a/doc/user/routemap.rst b/doc/user/routemap.rst new file mode 100644 index 0000000000..0be62d4100 --- /dev/null +++ b/doc/user/routemap.rst @@ -0,0 +1,310 @@ +.. _Route_Map: + +********* +Route Map +********* + +Route maps provide a means to both filter and/or apply actions to +route, hence allowing policy to be applied to routes. + +Route-maps are an ordered list of route-map entries. Each entry may +specify up to four distincts sets of clauses: + + + +*Matching Policy* + This specifies the policy implied if the @samp{Matching Conditions} are + met or not met, and which actions of the route-map are to be taken, if + any. The two possibilities are: + + +** + @samp{permit}: If the entry matches, then carry out the @samp{Set + Actions}. Then finish processing the route-map, permitting the route, + unless an @samp{Exit Action} indicates otherwise. + + +** + @samp{deny}: If the entry matches, then finish processing the route-map and + deny the route (return @samp{deny}). + + The @samp{Matching Policy} is specified as part of the command which + defines the ordered entry in the route-map. See below. + + +*Matching Conditions* + A route-map entry may, optionally, specify one or more conditions which + must be matched if the entry is to be considered further, as governed + by the Match Policy. If a route-map entry does not explicitely specify + any matching conditions, then it always matches. + + +*Set Actions* + A route-map entry may, optionally, specify one or more @samp{Set + Actions} to set or modify attributes of the route. + + +*Call Action* + Call to another route-map, after any @samp{Set Actions} have been + carried out. If the route-map called returns @samp{deny} then + processing of the route-map finishes and the route is denied, + regardless of the @samp{Matching Policy} or the @samp{Exit Policy}. If + the called route-map returns @samp{permit}, then @samp{Matching Policy} + and @samp{Exit Policy} govern further behaviour, as normal. + + +*Exit Policy* + An entry may, optionally, specify an alternative @samp{Exit Policy} to + take if the entry matched, rather than the normal policy of exiting the + route-map and permitting the route. The two possibilities are: + + +** + @samp{next}: Continue on with processing of the route-map entries. + + +** + @samp{goto N}: Jump ahead to the first route-map entry whose order in + the route-map is >= N. Jumping to a previous entry is not permitted. + +The default action of a route-map, if no entries match, is to deny. +I.e. a route-map essentially has as its last entry an empty @samp{deny} +entry, which matches all routes. To change this behaviour, one must +specify an empty @samp{permit} entry as the last entry in the route-map. + +To summarise the above: + +@multitable {permit} {action} {No Match} +@headitem @tab Match @tab No Match +* *Permit* @tab action @tab cont +* *Deny* @tab deny @tab cont +@end multitable + + + +*action* + +** + Apply *set* statements + + +** + If *call* is present, call given route-map. If that returns a @samp{deny}, finish + processing and return @samp{deny}. + + +** + If @samp{Exit Policy} is *next*, goto next route-map entry + + +** + If @samp{Exit Policy} is *goto*, goto first entry whose order in the list + is >= the given order. + + +** + Finish processing the route-map and permit the route. + + +*deny* + +** + The route is denied by the route-map (return @samp{deny}). + + +*cont* + +** + goto next route-map entry + +.. _Route_Map_Command: + +Route Map Command +================= + +.. index:: {Command} {route-map `route-map-name` (permit|deny) `order`} {} + +{Command} {route-map `route-map-name` (permit|deny) `order`} {} + + Configure the `order`'th entry in `route-map-name` with + @samp{Match Policy} of either *permit* or *deny*. + + +.. _Route_Map_Match_Command: + +Route Map Match Command +======================= + +.. index:: {Route-map Command} {match ip address `access_list`} {} + +{Route-map Command} {match ip address `access_list`} {} + Matches the specified `access_list` + +.. index:: {Route-map Command} {match ip address `prefix-list`} {} + +{Route-map Command} {match ip address `prefix-list`} {} + Matches the specified `prefix-list` + +.. index:: {Route-map Command} {match ip address prefix-len `0-32`} {} + +{Route-map Command} {match ip address prefix-len `0-32`} {} + Matches the specified `prefix-len`. This is a Zebra specific command. + +.. index:: {Route-map Command} {match ipv6 address `access_list`} {} + +{Route-map Command} {match ipv6 address `access_list`} {} + Matches the specified `access_list` + +.. index:: {Route-map Command} {match ipv6 address `prefix-list`} {} + +{Route-map Command} {match ipv6 address `prefix-list`} {} + Matches the specified `prefix-list` + +.. index:: {Route-map Command} {match ipv6 address prefix-len `0-128`} {} + +{Route-map Command} {match ipv6 address prefix-len `0-128`} {} + Matches the specified `prefix-len`. This is a Zebra specific command. + +.. index:: {Route-map Command} {match ip next-hop `ipv4_addr`} {} + +{Route-map Command} {match ip next-hop `ipv4_addr`} {} + Matches the specified `ipv4_addr`. + +.. index:: {Route-map Command} {match aspath `as_path`} {} + +{Route-map Command} {match aspath `as_path`} {} + Matches the specified `as_path`. + +.. index:: {Route-map Command} {match metric `metric`} {} + +{Route-map Command} {match metric `metric`} {} + Matches the specified `metric`. + +.. index:: {Route-map Command} {match local-preference `metric`} {} + +{Route-map Command} {match local-preference `metric`} {} + Matches the specified `local-preference`. + +.. index:: {Route-map Command} {match community `community_list`} {} + +{Route-map Command} {match community `community_list`} {} + Matches the specified `community_list` + +.. index:: {Route-map Command} {match peer `ipv4_addr`} {} + +{Route-map Command} {match peer `ipv4_addr`} {} + This is a BGP specific match command. Matches the peer ip address + if the neighbor was specified in this manner. + +.. index:: {Route-map Command} {match peer `ipv6_addr`} {} + +{Route-map Command} {match peer `ipv6_addr`} {} + This is a BGP specific match command. Matches the peer ipv6 + address if the neighbor was specified in this manner. + +.. index:: {Route-map Command} {match peer `interface_name`} {} + +{Route-map Command} {match peer `interface_name`} {} + This is a BGP specific match command. Matches the peer + interface name specified if the neighbor was specified + in this manner. + +.. _Route_Map_Set_Command: + +Route Map Set Command +===================== + +.. index:: {Route-map Command} {set ip next-hop `ipv4_address`} {} + +{Route-map Command} {set ip next-hop `ipv4_address`} {} + Set the BGP nexthop address. + +.. index:: {Route-map Command} {set local-preference `local_pref`} {} + +{Route-map Command} {set local-preference `local_pref`} {} + Set the BGP local preference to `local_pref`. + +.. index:: {Route-map Command} {set weight `weight`} {} + +{Route-map Command} {set weight `weight`} {} + Set the route's weight. + +.. index:: {Route-map Command} {set metric `metric`} {} + +{Route-map Command} {set metric `metric`} {} + .. _routemap_set_metric: + + Set the BGP attribute MED. + +.. index:: {Route-map Command} {set as-path prepend `as_path`} {} + +{Route-map Command} {set as-path prepend `as_path`} {} + Set the BGP AS path to prepend. + +.. index:: {Route-map Command} {set community `community`} {} + +{Route-map Command} {set community `community`} {} + Set the BGP community attribute. + +.. index:: {Route-map Command} {set ipv6 next-hop global `ipv6_address`} {} + +{Route-map Command} {set ipv6 next-hop global `ipv6_address`} {} + Set the BGP-4+ global IPv6 nexthop address. + +.. index:: {Route-map Command} {set ipv6 next-hop local `ipv6_address`} {} + +{Route-map Command} {set ipv6 next-hop local `ipv6_address`} {} + Set the BGP-4+ link local IPv6 nexthop address. + +.. _Route_Map_Call_Command: + +Route Map Call Command +====================== + +.. index:: {Route-map Command} {call `name`} {} + +{Route-map Command} {call `name`} {} + Call route-map `name`. If it returns deny, deny the route and + finish processing the route-map. + +.. _Route_Map_Exit_Action_Command: + +Route Map Exit Action Command +============================= + +.. index:: {Route-map Command} {on-match next} {} + +{Route-map Command} {on-match next} {} +.. index:: {Route-map Command} {continue} {} + +{Route-map Command} {continue} {} + Proceed on to the next entry in the route-map. + +.. index:: {Route-map Command} {on-match goto `N`} {} + +{Route-map Command} {on-match goto `N`} {} +.. index:: {Route-map Command} {continue `N`} {} + +{Route-map Command} {continue `N`} {} + Proceed processing the route-map at the first entry whose order is >= N + +Route Map Examples +================== + +A simple example of a route-map: + +:: + + @group + route-map test permit 10 + match ip address 10 + set local-preference 200 + @end group + + +This means that if a route matches ip access-list number 10 it's +local-preference value is set to 200. + +See :ref:`BGP_Configuration_Examples` for examples of more sophisticated +useage of route-maps, including of the @samp{call} action. + diff --git a/doc/user/routeserver.rst b/doc/user/routeserver.rst new file mode 100644 index 0000000000..ac73e30b87 --- /dev/null +++ b/doc/user/routeserver.rst @@ -0,0 +1,18 @@ +.. _Configuring_Frr_as_a_Route_Server: + +********************************* +Configuring Frr as a Route Server +********************************* + +The purpose of a Route Server is to centralize the peerings between BGP +speakers. For example if we have an exchange point scenario with four BGP +speakers, each of which maintaining a BGP peering with the other three +(:ref:`fig:full-mesh`), we can convert it into a centralized scenario where +each of the four establishes a single BGP peering against the Route Server +(:ref:`fig:route-server`). + +We will first describe briefly the Route Server model implemented by Frr. +We will explain the commands that have been added for configuring that +model. And finally we will show a full example of Frr configured as Route +Server. + diff --git a/doc/user/rpki.rst b/doc/user/rpki.rst new file mode 100644 index 0000000000..bf99940e39 --- /dev/null +++ b/doc/user/rpki.rst @@ -0,0 +1,277 @@ +.. _Prefix_Origin_Validation_Using_RPKI: + +Prefix Origin Validation Using RPKI +=================================== + +Prefix Origin Validation allows BGP routers to verify if the origin AS of +an IP prefix is legitimate to announce this IP prefix. The required +attestation objects are stored in the Resource Public Key Infrastructure +(@acronym{RPKI}). However, RPKI-enabled routers do not store cryptographic +data itself but only validation information. The validation of the +cryptographic data (so called Route Origin Authorization, or short +@acronym{ROA}, objects) will be performed by trusted cache servers. The +RPKI/RTR protocol defines a standard mechanism to maintain the exchange of +the prefix/origin AS mapping between the cache server and routers. +In combination with a BGP Prefix Origin Validation scheme a router is able +to verify received BGP updates without suffering from cryptographic +complexity. + +The RPKI/RTR protocol is defined in @cite{RFC6810, The Resource Public Key +Infrastructure (RPKI) to Router Protocol}, and the validation scheme in +@cite{RFC6811, BGP Prefix Origin Validation}. The current version of Prefix +Origin Validation in FRR implements both RFCs. + +For a more detailed but still easy-to-read background, we suggest the +following two articles: + +* @cite{Geoff Huston, Randy Bush: Securing BGP, In: The Internet + Protocol Journal, Volume 14, No. 2, 2011.} + `http://www.cisco.com/web/about/ac123/ac147/archived_issues/ipj_14-2/142_bgp.html `_ + +* @cite{Geoff Huston: Resource Certification, In: The Internet Protocol + Journal, Volume 12, No.1, 2009.} + `http://www.cisco.com/web/about/ac123/ac147/archived_issues/ipj_12-1/121_resource.html `_ + +.. _Features_of_the_Current_Implementation: + +Features of the Current Implementation +-------------------------------------- + +In a nutshell, the current implementation provides the following features + +* The BGP router can connect to one or more RPKI cache servers to + receive validated prefix to origin AS mappings. + Advanced failover can be implemented by server sockets with different + preference values. + +* If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. + +* By default, enabling RPKI does not change best path selection. In + particular, invalid prefixes will still be considered during best path + selection. However, the router can be configured to ignore all invalid + prefixes. + +* Route maps can be configured to match a specific RPKI validation + state. This allows the creation of local policies, which handle BGP routes + based on the outcome of the Prefix Origin Validation. + + +.. _Enabling_RPKI: + +Enabling RPKI +------------- + +.. index:: {Command} {rpki} {} + +{Command} {rpki} {} + This command enables the RPKI configuration mode. Most commands that start + with *rpki* can only be used in this mode. + + When it is used in a telnet session, leaving of this mode cause rpki to be initialized. + + Executing this command alone does not activate prefix + validation. You need to configure at least one reachable cache server. See section + :ref:`Configuring_RPKI/RTR_Cache_Servers` for configuring a cache server. + +.. _Configuring_RPKI/RTR_Cache_Servers: + +Configuring RPKI/RTR Cache Servers +---------------------------------- + +The following commands are independent of a specific cache server. + +.. index:: {RPKI Command} {rpki polling_period <1-3600>} {} + +{RPKI Command} {rpki polling_period <1-3600>} {} +.. index:: {RPKI Command} {no rpki polling_period} {} + +{RPKI Command} {no rpki polling_period} {} + Set the number of seconds the router waits until the router asks the cache again + for updated data. + + The default value is 300 seconds. + +.. index:: {RPKI Command} {rpki timeout <1-4,294,967,296>} {} + +{RPKI Command} {rpki timeout <1-4,294,967,296>} {} +.. index:: {RPKI Command} {no rpki timeout} {} + +{RPKI Command} {no rpki timeout} {} + Set the number of seconds the router waits for the cache reply. If the + cache server is not replying within this time period, the router deletes + all received prefix records from the prefix table. + + The default value is 600 seconds. + +.. index:: {RPKI Command} {rpki initial-synchronisation-timeout <1-4,294,967,296>} {} + +{RPKI Command} {rpki initial-synchronisation-timeout <1-4,294,967,296>} {} +.. index:: {RPKI Command} {no rpki initial-synchronisation-timeout} {} + +{RPKI Command} {no rpki initial-synchronisation-timeout} {} + Set the number of seconds until the first synchronization with the cache + server needs to be completed. If the timeout expires, BGP routing is + started without RPKI. The router will try to establish the cache server + connection in the background. + + The default value is 30 seconds. + + The following commands configure one or multiple cache servers. + +.. index:: {RPKI Socket Command} {rpki cache (`A.B.C.D`|`WORD`) `PORT` [`SSH_USERNAME`] [`SSH_PRIVKEY_PATH`] [`SSH_PUBKEY_PATH`] [`KNOWN_HOSTS_PATH`] `PREFERENCE`} {} + +{RPKI Socket Command} {rpki cache (`A.B.C.D`|`WORD`) `PORT` [`SSH_USERNAME`] [`SSH_PRIVKEY_PATH`] [`SSH_PUBKEY_PATH`] [`KNOWN_HOSTS_PATH`] `PREFERENCE`} {} +.. index:: {RPKI Socket Command} {no rpki cache (`A.B.C.D`|`WORD`) [`PORT`] `PREFERENCE`} {} + +{RPKI Socket Command} {no rpki cache (`A.B.C.D`|`WORD`) [`PORT`] `PREFERENCE`} {} + Add a cache server to the socket. By default, the connection between + router and cache server is based on plain TCP. Protecting the connection + between router and cache server by SSH is optional. + Deleting a socket removes the associated cache server and + terminates the existing connection. + + + +*`A.B.C.D`|`WORD`* + Address of the cache server. + + +*`PORT`* + Port number to connect to the cache server + + +*`SSH_USERNAME`* + SSH username to establish an SSH connection to the cache server. + + +*`SSH_PRIVKEY_PATH`* + Local path that includes the private key file of the router. + + +*`SSH_PUBKEY_PATH`* + Local path that includes the public key file of the router. + + +*`KNOWN_HOSTS_PATH`* + Local path that includes the known hosts file. The default value depends on the + configuration of the operating system environment, usually + :file:`~/.ssh/known_hosts`. + + +.. _Validating_BGP_Updates: + +Validating BGP Updates +---------------------- + +.. index:: {Route Map Command} {match rpki {notfound|invalid|valid}} {} + +{Route Map Command} {match rpki {notfound|invalid|valid}} {} +.. index:: {Route Map Command} {no match rpki {notfound|invalid|valid}} {} + +{Route Map Command} {no match rpki {notfound|invalid|valid}} {} + Create a clause for a route map to match prefixes with the specified RPKI state. + + @strong{Note} that the matching of invalid prefixes requires that invalid + prefixes are considered for best path selection, i.e., @command{bgp + bestpath prefix-validate disallow-invalid} is not enabled. + + In the following example, the router prefers valid routes over invalid + prefixes because invalid routes have a lower local preference. +:: + + ! Allow for invalid routes in route selection process + route bgp 60001 + ! + ! Set local preference of invalid prefixes to 10 + route-map rpki permit 10 + match rpki invalid + set local-preference 10 + ! + ! Set local preference of valid prefixes to 500 + route-map rpki permit 500 + match rpki valid + set local-preference 500 + + + +.. _Debugging: + +Debugging +--------- + +.. index:: {Command} {debug rpki} {} + +{Command} {debug rpki} {} +.. index:: {Command} {no debug rpki} {} + +{Command} {no debug rpki} {} + Enable or disable debugging output for RPKI. + +.. _Displaying_RPKI: + +Displaying RPKI +--------------- + +.. index:: {Command} {show rpki prefix-table} {} + +{Command} {show rpki prefix-table} {} + Display all validated prefix to origin AS mappings/records which have been + received from the cache servers and stored in the router. Based on this data, + the router validates BGP Updates. + +.. index:: {Command} {show rpki cache-connection} {} + +{Command} {show rpki cache-connection} {} + Display all configured cache servers, whether active or not. + +RPKI Configuration Example +-------------------------- + +:: + + hostname bgpd1 + password zebra + ! log stdout + debug bgp updates + debug bgp keepalives + debug rpki + ! + rpki + rpki polling_period 1000 + rpki timeout 10 + ! SSH Example: + rpki cache example.com 22 rtr-ssh ./ssh_key/id_rsa ./ssh_key/id_rsa.pub preference 1 + ! TCP Example: + rpki cache rpki-validator.realmv6.org 8282 preference 2 + exit + ! + router bgp 60001 + bgp router-id 141.22.28.223 + network 192.168.0.0/16 + neighbor 123.123.123.0 remote-as 60002 + neighbor 123.123.123.0 route-map rpki in + ! + address-family ipv6 + neighbor 123.123.123.0 activate + neighbor 123.123.123.0 route-map rpki in + exit-address-family + ! + route-map rpki permit 10 + match rpki invalid + set local-preference 10 + ! + route-map rpki permit 20 + match rpki notfound + set local-preference 20 + ! + route-map rpki permit 30 + match rpki valid + set local-preference 30 + ! + route-map rpki permit 40 + ! + + diff --git a/doc/user/snmp.rst b/doc/user/snmp.rst new file mode 100644 index 0000000000..286104e396 --- /dev/null +++ b/doc/user/snmp.rst @@ -0,0 +1,207 @@ +.. _SNMP_Support: + +************ +SNMP Support +************ + +@acronym{SNMP,Simple Network Managing Protocol} is a widely implemented +feature for collecting network information from router and/or host. +Frr itself does not support SNMP agent (server daemon) functionality +but is able to connect to a SNMP agent using the SMUX protocol +(@cite{RFC1227}) or the AgentX protocol (@cite{RFC2741}) and make the +routing protocol MIBs available through it. + +Note that SNMP Support needs to be enabled at compile-time and loaded as +module on daemon startup. Refer to :ref:`Loadable_Module_Support` on +the latter. + +.. _Getting_and_installing_an_SNMP_agent: + +Getting and installing an SNMP agent +==================================== + +There are several SNMP agent which support SMUX or AgentX. We recommend to use the latest +version of `net-snmp` which was formerly known as `ucd-snmp`. +It is free and open software and available at `http://www.net-snmp.org/ `_ +and as binary package for most Linux distributions. +`net-snmp` has to be compiled with `--with-mib-modules=agentx` to +be able to accept connections from Frr using AgentX protocol or with +`--with-mib-modules=smux` to use SMUX protocol. + +Nowadays, SMUX is a legacy protocol. The AgentX protocol should be +preferred for any new deployment. Both protocols have the same coverage. + +.. _AgentX_configuration: + +AgentX configuration +==================== + +To enable AgentX protocol support, Frr must have been build with the +`--enable-snmp` or `--enable-snmp=agentx` option. Both the +master SNMP agent (snmpd) and each of the Frr daemons must be +configured. In `/etc/snmp/snmpd.conf`, `master agentx` +directive should be added. In each of the Frr daemons, `agentx` +command will enable AgentX support. + +:: + + /etc/snmp/snmpd.conf: + # + # example access restrictions setup + # + com2sec readonly default public + group MyROGroup v1 readonly + view all included .1 80 + access MyROGroup "" any noauth exact all none none + # + # enable master agent for AgentX subagents + # + master agentx + + /etc/frr/ospfd.conf: + ! ... the rest of ospfd.conf has been omitted for clarity ... + ! + agentx + ! + + +Upon successful connection, you should get something like this in the +log of each Frr daemons: + +:: + + 2012/05/25 11:39:08 ZEBRA: snmp[info]: NET-SNMP version 5.4.3 AgentX subagent connected + + +Then, you can use the following command to check everything works as expected: + +:: + + # snmpwalk -c public -v1 localhost .1.3.6.1.2.1.14.1.1 + OSPF-MIB::ospfRouterId.0 = IpAddress: 192.168.42.109 + [...] + + +The AgentX protocol can be transported over a Unix socket or using TCP +or UDP. It usually defaults to a Unix socket and depends on how NetSNMP +was built. If need to configure Frr to use another transport, you can +configure it through `/etc/snmp/frr.conf`: + +:: + + /etc/snmp/frr.conf: + [snmpd] + # Use a remote master agent + agentXSocket tcp:192.168.15.12:705 + + +.. _SMUX_configuration: + +SMUX configuration +================== + +To enable SMUX protocol support, Frr must have been build with the +`--enable-snmp=smux` option. + +A separate connection has then to be established between the +SNMP agent (snmpd) and each of the Frr daemons. This connections +each use different OID numbers and passwords. Be aware that this OID +number is not the one that is used in queries by clients, it is solely +used for the intercommunication of the daemons. + +In the following example the ospfd daemon will be connected to the +snmpd daemon using the password "frr_ospfd". For testing it is +recommending to take exactly the below snmpd.conf as wrong access +restrictions can be hard to debug. + +:: + + /etc/snmp/snmpd.conf: + # + # example access restrictions setup + # + com2sec readonly default public + group MyROGroup v1 readonly + view all included .1 80 + access MyROGroup "" any noauth exact all none none + # + # the following line is relevant for Frr + # + smuxpeer .1.3.6.1.4.1.3317.1.2.5 frr_ospfd + + /etc/frr/ospf: + ! ... the rest of ospfd.conf has been omitted for clarity ... + ! + smux peer .1.3.6.1.4.1.3317.1.2.5 frr_ospfd + ! + + +After restarting snmpd and frr, a successful connection can be verified in +the syslog and by querying the SNMP daemon: + +:: + + snmpd[12300]: [smux_accept] accepted fd 12 from 127.0.0.1:36255 + snmpd[12300]: accepted smux peer: \\ + oid GNOME-PRODUCT-ZEBRA-MIB::ospfd, frr-0.96.5 + + # snmpwalk -c public -v1 localhost .1.3.6.1.2.1.14.1.1 + OSPF-MIB::ospfRouterId.0 = IpAddress: 192.168.42.109 + + +Be warned that the current version (5.1.1) of the Net-SNMP daemon writes a line +for every SNMP connect to the syslog which can lead to enormous log file sizes. +If that is a problem you should consider to patch snmpd and comment out the +troublesome `snmp_log()` line in the function +`netsnmp_agent_check_packet()` in `agent/snmp_agent.c`. + +MIB and command reference +========================= + +The following OID numbers are used for the interprocess communication of snmpd and +the Frr daemons with SMUX only. +:: + + (OIDs below .iso.org.dod.internet.private.enterprises) + zebra .1.3.6.1.4.1.3317.1.2.1 .gnome.gnomeProducts.zebra.zserv + bgpd .1.3.6.1.4.1.3317.1.2.2 .gnome.gnomeProducts.zebra.bgpd + ripd .1.3.6.1.4.1.3317.1.2.3 .gnome.gnomeProducts.zebra.ripd + ospfd .1.3.6.1.4.1.3317.1.2.5 .gnome.gnomeProducts.zebra.ospfd + ospf6d .1.3.6.1.4.1.3317.1.2.6 .gnome.gnomeProducts.zebra.ospf6d + + +Sadly, SNMP has not been implemented in all daemons yet. The following +OID numbers are used for querying the SNMP daemon by a client: +:: + + zebra .1.3.6.1.2.1.4.24 .iso.org.dot.internet.mgmt.mib-2.ip.ipForward + ospfd .1.3.6.1.2.1.14 .iso.org.dot.internet.mgmt.mib-2.ospf + bgpd .1.3.6.1.2.1.15 .iso.org.dot.internet.mgmt.mib-2.bgp + ripd .1.3.6.1.2.1.23 .iso.org.dot.internet.mgmt.mib-2.rip2 + ospf6d .1.3.6.1.3.102 .iso.org.dod.internet.experimental.ospfv3 + + +The following syntax is understood by the Frr daemons for configuring SNMP using SMUX: +.. index:: {Command} {smux peer `oid`} {} + +{Command} {smux peer `oid`} {} +.. index:: {Command} {no smux peer `oid`} {} + +{Command} {no smux peer `oid`} {} + +.. index:: {Command} {smux peer `oid` `password`} {} + +{Command} {smux peer `oid` `password`} {} +.. index:: {Command} {no smux peer `oid` `password`} {} + +{Command} {no smux peer `oid` `password`} {} + Here is the syntax for using AgentX: +.. index:: {Command} {agentx} {} + +{Command} {agentx} {} +.. index:: {Command} {no agentx} {} + +{Command} {no agentx} {} + + @include snmptrap.texi + diff --git a/doc/user/snmptrap.rst b/doc/user/snmptrap.rst new file mode 100644 index 0000000000..70d5bcdc2f --- /dev/null +++ b/doc/user/snmptrap.rst @@ -0,0 +1,200 @@ +Handling SNMP Traps +=================== + +To handle snmp traps make sure your snmp setup of frr works +correctly as described in the frr documentation in :ref:`SNMP_Support`. + +The BGP4 mib will send traps on peer up/down events. These should be +visible in your snmp logs with a message similar to: + +@samp{snmpd[13733]: Got trap from peer on fd 14} + +To react on these traps they should be handled by a trapsink. Configure +your trapsink by adding the following lines to :file:`/etc/snmpd/snmpd.conf`: + +:: + + # send traps to the snmptrapd on localhost + trapsink localhost + + +This will send all traps to an snmptrapd running on localhost. You can +of course also use a dedicated management station to catch traps. +Configure the snmptrapd daemon by adding the following line to +:file:`/etc/snmpd/snmptrapd.conf`: + +:: + + traphandle .1.3.6.1.4.1.3317.1.2.2 /etc/snmp/snmptrap_handle.sh + + +This will use the bash script :file:`/etc/snmp/snmptrap_handle.sh` to handle +the BGP4 traps. To add traps for other protocol daemons, lookup their +appropriate OID from their mib. (For additional information about which +traps are supported by your mib, lookup the mib on +`http://www.oidview.com/mibs/detail.html `_). + +Make sure snmptrapd is started. + +The snmptrap_handle.sh script I personally use for handling BGP4 traps +is below. You can of course do all sorts of things when handling traps, +like sound a siren, have your display flash, etc., be creative ;). + +@verbatim +#!/bin/bash + +# routers name +ROUTER=`hostname -s` + +#email address use to sent out notification +EMAILADDR="john@doe.com" +#email address used (allongside above) where warnings should be sent +EMAILADDR_WARN="sms-john@doe.com" + +# type of notification +TYPE="Notice" + +# local snmp community for getting AS belonging to peer +COMMUNITY="" + +# if a peer address is in $WARN_PEERS a warning should be sent +WARN_PEERS="192.0.2.1" + +# get stdin +INPUT=`cat -` + +# get some vars from stdin +uptime=`echo $INPUT | cut -d' ' -f5` +peer=`echo $INPUT | cut -d' ' -f8 | sed -e 's/SNMPv2-SMI::mib-2.15.3.1.14.//g'` +peerstate=`echo $INPUT | cut -d' ' -f13` +errorcode=`echo $INPUT | cut -d' ' -f9 | sed -e 's/\\"//g'` +suberrorcode=`echo $INPUT | cut -d' ' -f10 | sed -e 's/\\"//g'` +remoteas=`snmpget -v2c -c $COMMUNITY localhost SNMPv2-SMI::mib-2.15.3.1.9.$peer | cut -d' ' -f4` + +WHOISINFO=`whois -h whois.ripe.net " -r AS$remoteas" | egrep '(as-name|descr)'` +asname=`echo "$WHOISINFO" | grep "^as-name:" | sed -e 's/^as-name://g' -e 's/ //g' -e 's/^ //g' | uniq` +asdescr=`echo "$WHOISINFO" | grep "^descr:" | sed -e 's/^descr://g' -e 's/ //g' -e 's/^ //g' | uniq` + +# if peer address is in $WARN_PEER, the email should also +# be sent to $EMAILADDR_WARN +for ip in $WARN_PEERS; do +if [ "x$ip" == "x$peer" ]; then +EMAILADDR="$EMAILADDR,$EMAILADDR_WARN" +TYPE="WARNING" +break +fi +done + +# convert peer state +case "$peerstate" in +1) peerstate="Idle" ;; +2) peerstate="Connect" ;; +3) peerstate="Active" ;; +4) peerstate="Opensent" ;; +5) peerstate="Openconfirm" ;; +6) peerstate="Established" ;; +*) peerstate="Unknown" ;; +esac + +# get textual messages for errors +case "$errorcode" in +00) +error="No error" +suberror="" +;; +01) +error="Message Header Error" +case "$suberrorcode" in +01) suberror="Connection Not Synchronized" ;; +02) suberror="Bad Message Length" ;; +03) suberror="Bad Message Type" ;; +*) suberror="Unknown" ;; +esac +;; +02) +error="OPEN Message Error" +case "$suberrorcode" in +01) suberror="Unsupported Version Number" ;; +02) suberror="Bad Peer AS" ;; +03) suberror="Bad BGP Identifier" ;; +04) suberror="Unsupported Optional Parameter" ;; +05) suberror="Authentication Failure" ;; +06) suberror="Unacceptable Hold Time" ;; +*) suberror="Unknown" ;; +esac +;; +03) +error="UPDATE Message Error" +case "$suberrorcode" in +01) suberror="Malformed Attribute List" ;; +02) suberror="Unrecognized Well-known Attribute" ;; +03) suberror="Missing Well-known Attribute" ;; +04) suberror="Attribute Flags Error" ;; +05) suberror="Attribute Length Error" ;; +06) suberror="Invalid ORIGIN Attribute" ;; +07) suberror="AS Routing Loop" ;; +08) suberror="Invalid NEXT_HOP Attribute" ;; +09) suberror="Optional Attribute Error" ;; +10) suberror="Invalid Network Field" ;; +11) suberror="Malformed AS_PATH" ;; +*) suberror="Unknown" ;; +esac +;; +04) +error="Hold Timer Expired" +suberror="" +;; +05) +error="Finite State Machine Error" +suberror="" +;; +06) +error="Cease" +case "$suberrorcode" in +01) suberror="Maximum Number of Prefixes Reached" ;; +02) suberror="Administratively Shutdown" ;; +03) suberror="Peer Unconfigured" ;; +04) suberror="Administratively Reset" ;; +05) suberror="Connection Rejected" ;; +06) suberror="Other Configuration Change" ;; +07) suberror="Connection collision resolution" ;; +08) suberror="Out of Resource" ;; +09) suberror="MAX" ;; +*) suberror="Unknown" ;; +esac +;; +*) +error="Unknown" +suberror="" +;; +esac + +# create textual message from errorcodes +if [ "x$suberror" == "x" ]; then +NOTIFY="$errorcode ($error)" +else +NOTIFY="$errorcode/$suberrorcode ($error/$suberror)" +fi + +# form a decent subject +SUBJECT="$TYPE: $ROUTER [bgp] $peer is $peerstate: $NOTIFY" +# create the email body +MAIL=`cat << EOF +BGP notification on router $ROUTER. + +Peer: $peer +AS: $remoteas +New state: $peerstate +Notification: $NOTIFY + +Info: +$asname +$asdescr + +Snmpd uptime: $uptime +EOF` + +# mail the notification +echo "$MAIL" | mail -s "$SUBJECT" $EMAILADDR +@end verbatim + diff --git a/doc/user/vnc.rst b/doc/user/vnc.rst new file mode 100644 index 0000000000..6d9c4c40fe --- /dev/null +++ b/doc/user/vnc.rst @@ -0,0 +1,1023 @@ +.. _VNC_and_VNC-GW: + +************** +VNC and VNC-GW +************** + +This chapter describes how to use +Virtual Network Control (@acronym{VNC}) services, +including Network Virtualization Authority (@acronym{NVA}) and +VNC Gateway (@acronym{VNC-GW}) functions. +Background information on NVAs, +Network Virtualization Edges (@acronym{NVE}s), underlay networks (@acronym{UN}s), +and virtual networks (@acronym{VN}s) is available from the +`https://datatracker.ietf.org/wg/nvo3,IETF Network Virtualization Overlays (@acronym{NVO3 `_) Working Group}. +VNC Gateways (@acronym{VNC-GW}s) support the import/export of routing +information between VNC and customer edge routers (@acronym{CE}s) +operating within a VN. Both IP/Layer 3 (L3) VNs, and IP with +Ethernet/Layer 2 (L2) VNs are supported. + +BGP, with IP VPNs and Tunnel Encapsulation, is used to distribute VN +information between NVAs. BGP based IP VPN support is defined in +@cite{RFC4364, BGP/MPLS IP Virtual Private Networks (VPNs)}, and +@cite{RFC4659, BGP-MPLS IP Virtual Private Network (VPN) Extension for +IPv6 VPN }. Both the Encapsulation Subsequent Address Family Identifier +(SAFI) and the Tunnel Encapsulation Attribute, @cite{RFC5512, The BGP +Encapsulation Subsequent Address Family Identifier (SAFI) and the BGP +Tunnel Encapsulation Attribute}, are supported. + +The protocol that is used to communicate routing and Ethernet / Layer 2 +(L2) forwarding information between NVAs and NVEs is referred to as the +Remote Forwarder Protocol (RFP). `OpenFlow` is an example +RFP. Specific RFP implementations may choose to implement either a +`hard-state` or `soft-state` prefix and address registration +model. To support a `soft-state` refresh model, a `lifetime` +in seconds is associated with all registrations and responses. + +The chapter also provides sample configurations for basic example scenarios. + +.. _Configuring_VNC: + +Configuring VNC +=============== + +Virtual Network Control (@acronym{VNC}) service configuration commands +appear in the `router bgp` section of the BGPD configuration file +(:ref:`BGP_Configuration_Examples`). The commands are broken down into +the following areas: + +`General VNC` configuration applies to general VNC operation and is +primarily used to control the method used to advertise tunnel +information. + +`Remote Forwarder Protocol (RFP)` configuration relates to the +protocol used between NVAs and NVEs. + +`VNC Defaults` provides default parameters for registered NVEs. + +`VNC NVE Group` provides for configuration of a specific set of +registered NVEs and overrides default parameters. + +`Redistribution` and `Export` control VNC-GW operation, i.e., +the import/export of routing +information between VNC and customer edge routers (@acronym{CE}s) +operating within a VN. + +.. _General_VNC_Configuration: + +General VNC Configuration +------------------------- + +.. index:: {VNC} {vnc advertise-un-method encap-safi|encap-attr} {} + +{VNC} {vnc advertise-un-method encap-safi|encap-attr} {} + Advertise NVE underlay-network IP addresses using the encapsulation SAFI + (`encap-safi`) or the UN address sub-TLV of the Tunnel Encapsulation attribute + (`encap-attr`). When `encap-safi` is used, neighbors under + `address-family encap` and/or `address-family encapv6` must be + configured. The default is `encap-attr`. + +.. _RFP_Related_Configuration: + +RFP Related Configuration +------------------------- + +The protocol that is used to communicate routing and Ethernet / L2 +forwarding information between NVAs and NVEs is referred to as the +Remote Forwarder Protocol (RFP). Currently, only a simple example RFP +is included in Frr. Developers may use this example as a starting +point to integrate Frr with an RFP of their choosing, e.g., +`OpenFlow`. The example code includes the following sample +configuration: + +.. index:: {RFP} {rfp example-config-value `VALUE`} + +{RFP} {rfp example-config-value `VALUE`} + This is a simple example configuration parameter included as part of the + RFP example code. `VALUE` must be in the range of 0 to 4294967295. + +.. _VNC_Defaults_Configuration: + +VNC Defaults Configuration +-------------------------- + +The VNC Defaults section allows the user to specify default values for +configuration parameters for all registered NVEs. +Default values are overridden by :ref:`VNC_NVE_Group_Configuration`. + +.. index:: {VNC} {vnc defaults} {} + +{VNC} {vnc defaults} {} + Enter VNC configuration mode for specifying VNC default behaviors. Use + `exit-vnc` to leave VNC configuration mode. `vnc defaults` is optional. + +:: + + vnc defaults + ... various VNC defaults + exit-vnc + + +These are the statements that can appear between `vnc defaults` +and `exit-vnc`. + +.. index:: {VNC} {rt import `rt-list`} {} + +{VNC} {rt import `rt-list`} {} +.. index:: {VNC} {rt export `rt-list`} {} + +{VNC} {rt export `rt-list`} {} +.. index:: {VNC} {rt both `rt-list`} {} + +{VNC} {rt both `rt-list`} {} + Specify default route target import and export lists. `rt-list` is a + space-separated list of route targets, each element of which is + in one of the following forms: + + +`IPv4-address`:`two-byte-integer` + +`four-byte-autonomous-system-number`:`two-byte-integer` + +`two-byte-autonomous-system-number`:`four-byte-integer` + + If no default import RT list is specified, then the default import RT + list is empty. + If no default export RT list is specified, then the default export RT + list is empty. + + A complete definition of these parameters is + given below (:ref:`VNC_NVE_Group_Configuration`). + +.. index:: {VNC} {rd `route-distinguisher`} + +{VNC} {rd `route-distinguisher`} + Specify the default route distinguisher (RD) for routes advertised via BGP + VPNs. The route distinguisher must be in one of four forms: + + +`IPv4-address`:`two-byte-integer` + +`four-byte-autonomous-system-number`:`two-byte-integer` + +`two-byte-autonomous-system-number`:`four-byte-integer` + +auto:vn:`two-byte-integer` + + If RD is specified in the defaults section, the default RD + value is `two-byte-autonomous-system-number=0`:`four-byte-integer=0`. + + A complete definition of this parameter is + given below (:ref:`VNC_NVE_Group_Configuration`). + +.. index:: {VNC} {l2rd `nve-id-value`} + +{VNC} {l2rd `nve-id-value`} + Set the value used to distinguish NVEs connected to the same logical + Ethernet segment (i.e., L2VPN). + + A complete definition of this parameter is + given below (:ref:`VNC_NVE_Group_Configuration`). + +.. index:: {VNC} {response-lifetime `lifetime`|infinite} {} + +{VNC} {response-lifetime `lifetime`|infinite} {} + Specify the default lifetime to be included in RFP + response messages sent to NVEs. + + A complete definition of this parameter is + given below (:ref:`VNC_NVE_Group_Configuration`). + +.. index:: {VNC} {export bgp|zebra route-map MAP-NAME} + +{VNC} {export bgp|zebra route-map MAP-NAME} + Specify that the named route-map should be applied to routes + being exported to bgp or zebra. + +.. index:: {VNC} {export bgp|zebra no route-map} + +{VNC} {export bgp|zebra no route-map} + Specify that no route-map should be applied to routes + being exported to bgp or zebra. + +.. index:: {VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} + +{VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} + Specify that the named prefix-list filter should be applied to + routes being exported to bgp or zebra. + Prefix-lists for ipv4 and ipv6 are independent of each other. + +.. index:: {VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} + +{VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} + Specify that no prefix-list filter should be applied to + routes being exported to bgp or zebra. + +.. index:: {VNC} {exit-vnc} {} + +{VNC} {exit-vnc} {} + Exit VNC configuration mode. + +.. _VNC_NVE_Group_Configuration: + +VNC NVE Group Configuration +--------------------------- + +A NVE Group corresponds to a specific set of NVEs. A Client NVE is +assigned to an NVE Group based on whether there is a match for either +its virtual or underlay network address against the VN and/or UN address +prefixes specified in the NVE Group definition. When an NVE Group +definition specifies both VN and UN address prefixes, then an NVE must +match both prefixes in order to be assigned to the NVE Group. In the +event that multiple NVE Groups match based on VN and/or UN addresses, +the NVE is assigned to the first NVE Group listed in the configuration. +If an NVE is not assigned to an NVE Group, its messages will be ignored. + +Configuration values specified for an NVE group apply to all +member NVEs and override configuration values specified in the VNC +Defaults section. + +@strong{At least one `nve-group` is mandatory for useful VNC +operation.} + +.. index:: {VNC} {vnc nve-group `name`} {} + +{VNC} {vnc nve-group `name`} {} + Enter VNC configuration mode for defining the NVE group `name`. + Use `exit` or `exit-vnc` to exit group configuration mode. + +:: + + vnc nve-group group1 + ... configuration commands + exit-vnc + + +.. index:: {VNC} {no vnc nve-group `name`} {} + +{VNC} {no vnc nve-group `name`} {} + Delete the NVE group named `name`. + +The following statements are valid in an NVE group definition: + +.. index:: {VNC} {l2rd `nve-id-value`} + +{VNC} {l2rd `nve-id-value`} + Set the value used to distinguish NVEs connected to the same physical + Ethernet segment (i.e., at the same location)@footnote{The nve-id is + carried in the route + distinguisher. It is the second octet of the eight-octet route + distinguisher generated for Ethernet / L2 advertisements. + The first octet is a constant 0xFF, and the third through eighth + octets are set to the L2 ethernet address being advertised.} + + The nve-id subfield may be specified as either a literal value + in the range 1-255, or it may be specified as `auto:vn`, which + means to use the least-significant octet of the originating + NVE's VN address. + +.. index:: {VNC} {prefix vn|un A.B.C.D/M|X:X::X:X/M} {} + +{VNC} {prefix vn|un A.B.C.D/M|X:X::X:X/M} {} + .. _prefix: + + Specify the matching prefix for this NVE group by either virtual-network address + (`vn`) or underlay-network address (`un`). Either or both virtual-network + and underlay-network prefixes may be specified. Subsequent virtual-network or + underlay-network values within a `vnc nve-group` `exit-vnc` + block override their respective previous values. + + These prefixes are used only for determining assignments of NVEs + to NVE Groups. + +.. index:: {VNC} {rd `route-distinguisher`} + +{VNC} {rd `route-distinguisher`} + Specify the route distinguisher for routes advertised via BGP + VPNs. The route distinguisher must be in one of these forms: + + +`IPv4-address`:`two-byte-integer` + +`four-byte-autonomous-system-number`:`two-byte-integer` + +`two-byte-autonomous-system-number`:`four-byte-integer` + +auto:vn:`two-byte-integer` + + Routes originated by NVEs in the NVE group will use + the group's specified `route-distinguisher` when they are + advertised via BGP. + If the `auto` form is specified, it means that a matching NVE has + its RD set to + `rd_type=IP=1`:`IPv4-address=VN-address`:`two-byte-integer`, + for IPv4 VN addresses and + `rd_type=IP=1`:`IPv4-address=Last-four-bytes-of-VN-address`:`two-byte-integer`, + for IPv6 VN addresses. + + If the NVE group definition does not specify a `route-distinguisher`, + then the default `route-distinguisher` is used. + If neither a group nor a default `route-distinguisher` is + configured, then the advertised RD is set to + `two-byte-autonomous-system-number=0`:`four-byte-integer=0`. + +.. index:: {VNC} {response-lifetime `lifetime`|infinite} {} + +{VNC} {response-lifetime `lifetime`|infinite} {} + Specify the response lifetime, in seconds, to be included in RFP + response messages sent to NVEs. If the value + 'infinite' is given, an infinite lifetime will be used. + + Note that this parameter is not the same as the lifetime supplied by + NVEs in RFP registration messages. This parameter does not affect + the lifetime value attached to routes sent by this server via BGP. + + If the NVE group definition does not specify a `response-lifetime`, + the default `response-lifetime` will be used. + If neither a group nor a default `response-lifetime` is configured, + the value 3600 will be used. The maximum response lifetime is 2147483647. + +.. index:: {VNC} {rt export `rt-list`} {} + +{VNC} {rt export `rt-list`} {} +.. index:: {VNC} {rt import `rt-list`} {} + +{VNC} {rt import `rt-list`} {} +.. index:: {VNC} {rt both `rt-list`} {} + +{VNC} {rt both `rt-list`} {} + Specify route target import and export lists. `rt-list` is a + space-separated list of route targets, each element of which is + in one of the following forms: + + +`IPv4-address`:`two-byte-integer` + +`four-byte-autonomous-system-number`:`two-byte-integer` + +`two-byte-autonomous-system-number`:`four-byte-integer` + + The first form, `rt export`, specifies an `export rt-list`. + The `export rt-list` will be attached to routes originated by + NVEs in the NVE group when they are advertised via BGP. + If the NVE group definition does not specify an `export rt-list`, + then the default `export rt-list` is used. + If neither a group nor a default `export rt-list` is configured, + then no RT list will be sent; in turn, these routes will probably + not be processed + by receiving NVAs. + + The second form, `rt import` specifies an `import rt-list`, + which is a filter for incoming routes. + In order to be made available to NVEs in the group, + incoming BGP VPN and @w{ENCAP} @w{SAFI} (when `vnc advertise-un-method encap-safi` is set) routes must have + RT lists that have at least one route target in common with the + group's `import rt-list`. + + If the NVE group definition does not specify an import filter, + then the default `import rt-list` is used. + If neither a group nor a default `import rt-list` is configured, + there can be no RT intersections when receiving BGP routes and + therefore no incoming BGP routes will be processed for the group. + + The third, `rt both`, is a shorthand way of specifying both + lists simultaneously, and is equivalent to `rt export `rt-list`` + followed by `rt import `rt-list``. + +.. index:: {VNC} {export bgp|zebra route-map MAP-NAME} + +{VNC} {export bgp|zebra route-map MAP-NAME} + Specify that the named route-map should be applied to routes + being exported to bgp or zebra. + This paramter is used in conjunction with + :ref:`Configuring_Export_of_Routes_to_Other_Routing_Protocols`. + This item is optional. + +.. index:: {VNC} {export bgp|zebra no route-map} + +{VNC} {export bgp|zebra no route-map} + Specify that no route-map should be applied to routes + being exported to bgp or zebra. + This paramter is used in conjunction with + :ref:`Configuring_Export_of_Routes_to_Other_Routing_Protocols`. + This item is optional. + +.. index:: {VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} + +{VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} + Specify that the named prefix-list filter should be applied to + routes being exported to bgp or zebra. + Prefix-lists for ipv4 and ipv6 are independent of each other. + This paramter is used in conjunction with + :ref:`Configuring_Export_of_Routes_to_Other_Routing_Protocols`. + This item is optional. + +.. index:: {VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} + +{VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} + Specify that no prefix-list filter should be applied to + routes being exported to bgp or zebra. + This paramter is used in conjunction with + :ref:`Configuring_Export_of_Routes_to_Other_Routing_Protocols`. + This item is optional. + +.. _VNC_L2_Group_Configuration: + +VNC L2 Group Configuration +-------------------------- + +The route targets advertised with prefixes and addresses registered by +an NVE are determined based on the NVE's associated VNC NVE Group +Configuration, :ref:`VNC_NVE_Group_Configuration`. Layer 2 (L2) Groups +are used to override the route targets for an NVE's Ethernet +registrations based on the Logical Network Identifier and label value. +A Logical Network Identifier is used to uniquely identify a logical +Ethernet segment and is conceptually similar to the Ethernet Segment +Identifier defined in @cite{RFC7432, BGP MPLS-Based Ethernet VPN}. Both +the Logical Network Identifier and Label are passed to VNC via RFP +prefix and address registration. + +Note that a corresponding NVE group configuration must be present, and +that other NVE associated configuration information, notably RD, is +not impacted by L2 Group Configuration. + +.. index:: {VNC} {vnc l2-group `name`} {} + +{VNC} {vnc l2-group `name`} {} + Enter VNC configuration mode for defining the L2 group `name`. + Use `exit` or `exit-vnc` to exit group configuration mode. + +:: + + vnc l2-group group1 + ... configuration commands + exit-vnc + + +.. index:: {VNC} {no vnc l2-group `name`} {} + +{VNC} {no vnc l2-group `name`} {} + Delete the L2 group named `name`. + +The following statements are valid in a L2 group definition: + +.. index:: {VNC} {logical-network-id `VALUE`} + +{VNC} {logical-network-id `VALUE`} + Define the Logical Network Identifier with a value in the range of + 0-4294967295 that identifies the logical Ethernet segment. + +.. index:: {VNC} {labels `label-list`} + +{VNC} {labels `label-list`} +.. index:: {VNC} {no labels `label-list`} + +{VNC} {no labels `label-list`} + Add or remove labels associated with the group. `label-list` is a + space separated list of label values in the range of 0-1048575. + +.. index:: {VNC} {rt import `rt-target`} {} + +{VNC} {rt import `rt-target`} {} +.. index:: {VNC} {rt export `rt-target`} {} + +{VNC} {rt export `rt-target`} {} +.. index:: {VNC} {rt both `rt-target`} {} + +{VNC} {rt both `rt-target`} {} + Specify the route target import and export value associated with the + group. A complete definition of these parameters is given above, + :ref:`VNC_NVE_Group_Configuration`. + +.. _Configuring_Redistribution_of_Routes_from_Other_Routing_Protocols: + +Configuring Redistribution of Routes from Other Routing Protocols +----------------------------------------------------------------- + +Routes from other protocols (including BGP) can be provided to VNC (both +for RFP and for redistribution via BGP) +from three sources: the zebra kernel routing process; +directly from the main (default) unicast BGP RIB; or directly +from a designated BGP unicast exterior routing RIB instance. + +The protocol named in the `vnc redistribute` command indicates +the route source: +`bgp-direct` routes come directly from the main (default) +unicast BGP RIB and are available for RFP and are redistributed via BGP; +`bgp-direct-to-nve-groups` routes come directly from a designated +BGP unicast routing RIB and are made available only to RFP; +and routes from other protocols come from the zebra kernel +routing process. +Note that the zebra process does not need to be active if +only `bgp-direct` or `bgp-direct-to-nve-groups` routes are used. + +`zebra` routes +^^^^^^^^^^^^^^ + +Routes originating from protocols other than BGP must be obtained +via the zebra routing process. +Redistribution of these routes into VNC does not support policy mechanisms +such as prefix-lists or route-maps. + +`bgp-direct` routes +^^^^^^^^^^^^^^^^^^^ + +`bgp-direct` redistribution supports policy via +prefix lists and route-maps. This policy is applied to incoming +original unicast routes before the redistribution translations +(described below) are performed. + +Redistribution of `bgp-direct` routes is performed in one of three +possible modes: `plain`, `nve-group`, or `resolve-nve`. +The default mode is `plain`. +These modes indicate the kind of translations applied to routes before +they are added to the VNC RIB. + +In `plain` mode, the route's next hop is unchanged and the RD is set +based on the next hop. +For `bgp-direct` redistribution, the following translations are performed: + +* + The VN address is set to the original unicast route's next hop address. +* + The UN address is NOT set. (VN->UN mapping will occur via + ENCAP route or attribute, based on `vnc advertise-un-method` + setting, generated by the RFP registration of the actual NVE) +* + The RD is set to as if auto:vn:0 were specified (i.e., + `rd_type=IP=1`:`IPv4-address=VN-address`:`two-byte-integer=0`) +* + The RT list is included in the extended community list copied from the + original unicast route (i.e., it must be set in the original unicast route). + +In `nve-group` mode, routes are registered with VNC as +if they came from an NVE in the nve-group designated in the +`vnc redistribute nve-group` command. The following +translations are performed: + +* + The next hop/VN address is set to the VN prefix configured for the + redistribute nve-group. +* + The UN address is set to the UN prefix configured for the + redistribute nve-group. +* + The RD is set to the RD configured for the redistribute nve-group. +* + The RT list is set to the RT list configured for the redistribute nve-group. + If `bgp-direct` routes are being redistributed, + any extended communities present in the original unicast route + will also be included. + +In `resolve-nve` mode, the next hop of the original BGP route is +typically the address of an NVE connected router (CE) connected by one or +more NVEs. +Each of the connected NVEs will register, via RFP, a VNC host route +to the CE. +This mode may be though of as a mechanism to proxy RFP registrations +of BGP unicast routes on behalf of registering NVEs. + +Multiple copies of the BGP route, one per matching NVE host route, will be +added to VNC. +In other words, for a given BGP unicast route, each instance of a +RFP-registered host route to the unicast route's next hop will result +in an instance of an imported VNC route. +Each such imported VNC route will have a prefix equal to the original +BGP unicast route's prefix, and a next hop equal to the next hop of the +matching RFP-registered host route. +If there is no RFP-registered host route to the next hop of the BGP unicast +route, no corresponding VNC route will be imported. + +The following translations are applied: + +* + The Next Hop is set to the next hop of the NVE route (i.e., the + VN address of the NVE). + +* + The extended community list in the new route is set to the + union of: + + * + Any extended communities in the original BGP route + * + Any extended communities in the NVE route + * + An added route-origin extended community with the next hop of the + original BGP route + is added to the new route. + The value of the local administrator field defaults 5226 but may + be configured by the user via the `roo-ec-local-admin` parameter. + +* + The Tunnel Encapsulation attribute is set to the value of the Tunnel + Encapsulation attribute of the NVE route, if any. + + +`bgp-direct-to-nve-groups` routes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Unicast routes from the main or a designated instance of BGP +may be redistributed to VNC as bgp-direct-to-nve-groups routes. These +routes are NOT announced via BGP, +but they are made available for local RFP lookup in response to +queries from NVEs. + +A non-main/default BGP instance is configured using the +`bgp multiple-instance` and `router bgp AS view NAME` +commands as described elsewhere in this document. + +In order for a route in the unicast BGP RIB to be made +available to a querying NVE, there must already be, available to +that NVE, an (interior) VNC route matching the next hop address +of the unicast route. +When the unicast route is provided to the NVE, its next hop +is replaced by the next hop of the corresponding +NVE. If there are multiple longest-prefix-match VNC routes, +the unicast route will be replicated for each. + +There is currently no policy (prefix-list or route-map) support +for `bgp-direct-to-nve-groups` routes. + +Redistribution Command Syntax +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: {VNC} {vnc redistribute ipv4|ipv6 bgp|bgp-direct|ipv6 bgp-direct-to-nve-groups|connected|kernel|ospf|rip|static} {} + +{VNC} {vnc redistribute ipv4|ipv6 bgp|bgp-direct|ipv6 bgp-direct-to-nve-groups|connected|kernel|ospf|rip|static} {} +.. index:: {VNC} {vnc redistribute ipv4|ipv6 bgp-direct-to-nve-groups view `VIEWNAME`} {} + +{VNC} {vnc redistribute ipv4|ipv6 bgp-direct-to-nve-groups view `VIEWNAME`} {} +.. index:: {VNC} {no vnc redistribute ipv4|ipv6 bgp|bgp-direct|bgp-direct-to-nve-groups|connected|kernel|ospf|rip|static} {} + +{VNC} {no vnc redistribute ipv4|ipv6 bgp|bgp-direct|bgp-direct-to-nve-groups|connected|kernel|ospf|rip|static} {} + Import (or do not import) prefixes from another routing + protocols. Specify both the address family to import (`ipv4` or + `ipv6`) and the protocol (`bgp`, `bgp-direct`, + `bgp-direct-to-nve-groups`, `connected`, + `kernel`, `ospf`, `rip`, or `static`). Repeat + this statement as needed for each combination of address family and + routing protocol. + Prefixes from protocol `bgp-direct` are imported from unicast BGP + in the same bgpd process. + Prefixes from all other protocols (including `bgp`) are imported + via the `zebra` kernel routing process. + +.. index:: {VNC} {vnc redistribute mode plain|nve-group|resolve-nve} + +{VNC} {vnc redistribute mode plain|nve-group|resolve-nve} + Redistribute routes from other protocols into VNC using the + specified mode. + Not all combinations of modes and protocols are supported. + +.. index:: {VNC} {vnc redistribute nve-group `group-name`} {} + +{VNC} {vnc redistribute nve-group `group-name`} {} +.. index:: {VNC} {no vnc redistribute nve-group `group-name`} {} + +{VNC} {no vnc redistribute nve-group `group-name`} {} + When using `nve-group` mode, + assign (or do not assign) the NVE group `group-name` to routes + redistributed from another routing protocol. `group-name` + must be configured using `vnc nve-group`. + + The VN and UN prefixes of the nve-group must both be configured, + and each prefix must be specified as a full-length (/32 for IPv4, + /128 for IPv6) prefix. + +.. index:: {VNC} {vnc redistribute lifetime `lifetime`|infinite} {} + +{VNC} {vnc redistribute lifetime `lifetime`|infinite} {} + Assign a registration lifetime, either `lifetime` seconds or + `infinite`, to prefixes redistributed from other routing + protocols as if they had been received via RFP registration messages + from an NVE. `lifetime` can be any integer between 1 and + 4294967295, inclusive. + +.. index:: {VNC} {vnc redistribute resolve-nve roo-ec-local-admin `0-65536`} + +{VNC} {vnc redistribute resolve-nve roo-ec-local-admin `0-65536`} + Assign a value to the local-administrator subfield used in the + Route Origin extended community that is assigned to routes exported + under the `resolve-nve` mode. The default value is `5226`. + + The following four `prefix-list` and `route-map` commands + may be specified in the context of an nve-group or not. + If they are specified in the context of an nve-group, they + apply only if the redistribution mode is `nve-group`, + and then only for routes being redistributed from + `bgp-direct`. + If they are specified outside the context of an nve-group, then + they apply only for redistribution modes `plain` and `resolve-nve`, + and then only for routes being redistributed from `bgp-direct`. + +.. index:: {VNC} {vnc redistribute bgp-direct (ipv4|ipv6) prefix-list `LIST-NAME`} + +{VNC} {vnc redistribute bgp-direct (ipv4|ipv6) prefix-list `LIST-NAME`} + When redistributing `bgp-direct` routes, + specifies that the named prefix-list should be applied. + +.. index:: {VNC} {vnc redistribute bgp-direct no (ipv4|ipv6) prefix-list} + +{VNC} {vnc redistribute bgp-direct no (ipv4|ipv6) prefix-list} + When redistributing `bgp-direct` routes, + specifies that no prefix-list should be applied. + +.. index:: {VNC} {vnc redistribute bgp-direct route-map `MAP-NAME`} + +{VNC} {vnc redistribute bgp-direct route-map `MAP-NAME`} + When redistributing `bgp-direct` routes, + specifies that the named route-map should be applied. + +.. index:: {VNC} {vnc redistribute bgp-direct no route-map} + +{VNC} {vnc redistribute bgp-direct no route-map} + When redistributing `bgp-direct` routes, + specifies that no route-map should be applied. + +.. _Configuring_Export_of_Routes_to_Other_Routing_Protocols: + +Configuring Export of Routes to Other Routing Protocols +------------------------------------------------------- + +Routes from VNC (both for RFP and for redistribution via BGP) can be +provided to other protocols, either via zebra or directly to BGP. + +It is important to note that when exporting routes to other protocols, +the downstream protocol must also be configured to import the routes. +For example, when VNC routes are exported to unicast BGP, the BGP +configuration must include a corresponding `redistribute vnc-direct` +statement. + +.. index:: {VNC} {export bgp|zebra mode none|group-nve|registering-nve|ce} + +{VNC} {export bgp|zebra mode none|group-nve|registering-nve|ce} + Specify how routes should be exported to bgp or zebra. + If the mode is `none`, routes are not exported. + If the mode is `group-nve`, routes are exported according + to nve-group or vrf-policy group configuration (:ref:`VNC_NVE_Group_Configuration`): if a group is configured to + allow export, then each prefix visible to the group is exported + with next hops set to the currently-registered NVEs. + If the mode is `registering-nve`, then all VNC routes are + exported with their original next hops. + If the mode is `ce`, only VNC routes that have an NVE connected CE Router + encoded in a Route Origin Extended Community are exported. + This extended community must have an administrative value that + matches the configured `roo-ec-local-admin` value. + The next hop of the exported route is set to the encoded + NVE connected CE Router. + + The default for both bgp and zebra is mode `none`. + +.. index:: {VNC} {vnc export bgp|zebra group-nve group `group-name`} + +{VNC} {vnc export bgp|zebra group-nve group `group-name`} +.. index:: {VNC} {vnc export bgp|zebra group-nve no group `group-name`} + +{VNC} {vnc export bgp|zebra group-nve no group `group-name`} + When export mode is `group-nve`, + export (or do not export) prefixes from the specified nve-group or + vrf-policy group + to unicast BGP or to zebra. + Repeat this statement as needed for each nve-group to be exported. + Each VNC prefix that is exported will result in N exported routes to the + prefix, each with a next hop corresponding to one of the N NVEs currently + associated with the nve-group. + +.. index:: {VNC} export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME + +{VNC} export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME + When export mode is `ce` or `registering-nve`, + specifies that the named prefix-list should be applied to routes + being exported to bgp or zebra. + Prefix-lists for ipv4 and ipv6 are independent of each other. + +.. index:: {VNC} export bgp|zebra no ipv4|ipv6 prefix-list + +{VNC} export bgp|zebra no ipv4|ipv6 prefix-list + When export mode is `ce` or `registering-nve`, + specifies that no prefix-list should be applied to routes + being exported to bgp or zebra. + +.. index:: {VNC} export bgp|zebra route-map MAP-NAME + +{VNC} export bgp|zebra route-map MAP-NAME + When export mode is `ce` or `registering-nve`, + specifies that the named route-map should be applied to routes + being exported to bgp or zebra. + +.. index:: {VNC} export bgp|zebra no route-map + +{VNC} export bgp|zebra no route-map + When export mode is `ce` or `registering-nve`, + specifies that no route-map should be applied to routes + being exported to bgp or zebra. + + When the export mode is `group-nve`, policy for exported + routes is specified per-NVE-group or vrf-policy group inside a `nve-group` `RFG-NAME` block + via the following commands(:ref:`VNC_NVE_Group_Configuration`): + +.. index:: {VNC} {export bgp|zebra route-map MAP-NAME} + +{VNC} {export bgp|zebra route-map MAP-NAME} + This command is valid inside a `nve-group` `RFG-NAME` block. + It specifies that the named route-map should be applied to routes + being exported to bgp or zebra. + +.. index:: {VNC} {export bgp|zebra no route-map} + +{VNC} {export bgp|zebra no route-map} + This command is valid inside a `nve-group` `RFG-NAME` block. + It specifies that no route-map should be applied to routes + being exported to bgp or zebra. + +.. index:: {VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} + +{VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} + This command is valid inside a `nve-group` `RFG-NAME` block. + It specifies that the named prefix-list filter should be applied to + routes being exported to bgp or zebra. + Prefix-lists for ipv4 and ipv6 are independent of each other. + +.. index:: {VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} + +{VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} + This command is valid inside a `nve-group` `RFG-NAME` block. + It specifies that no prefix-list filter should be applied to + routes being exported to bgp or zebra. + +.. _Manual_Address_Control: + +Manual Address Control +====================== + +The commands in this section can be used to augment normal dynamic VNC. +The `add vnc` commands can be used to manually add IP prefix or +Ethernet MAC address forwarding information. The `clear vnc` +commands can be used to remove manually and dynamically added +information. + +.. index:: {Command} {add vnc prefix (A.B.C.D/M|X:X::X:X/M) vn (A.B.C.D|X:X::X:X) un (A.B.C.D|X:X::X:X) [cost <0-255>] [lifetime (infinite|<1-4294967295>)] [local-next-hop (A.B.C.D|X:X::X:X) [local-cost <0-255>]]} {} + +{Command} {add vnc prefix (A.B.C.D/M|X:X::X:X/M) vn (A.B.C.D|X:X::X:X) un (A.B.C.D|X:X::X:X) [cost <0-255>] [lifetime (infinite|<1-4294967295>)] [local-next-hop (A.B.C.D|X:X::X:X) [local-cost <0-255>]]} {} + Register an IP prefix on behalf of the NVE identified by the VN and UN + addresses. The `cost` parameter provides the administrative + preference of the forwarding information for remote advertisement. If + omitted, it defaults to 255 (lowest preference). The `lifetime` + parameter identifies the period, in seconds, that the information + remains valid. If omitted, it defaults to `infinite`. The optional + `local-next-hop` parameter is used to configure a nexthop to be + used by an NVE to reach the prefix via a locally connected CE router. + This information remains local to the NVA, i.e., not passed to other + NVAs, and is only passed to registered NVEs. When specified, it is also + possible to provide a `local-cost` parameter to provide a + forwarding preference. If omitted, it defaults to 255 (lowest + preference). + +.. index:: {Command} {add vnc mac xx:xx:xx:xx:xx:xx virtual-network-identifier <1-4294967295> vn (A.B.C.D|X:X::X:X) un (A.B.C.D|X:X::X:X) [prefix (A.B.C.D/M|X:X::X:X/M)] [cost <0-255>] [lifetime (infinite|<1-4294967295>)]} {} + +{Command} {add vnc mac xx:xx:xx:xx:xx:xx virtual-network-identifier <1-4294967295> vn (A.B.C.D|X:X::X:X) un (A.B.C.D|X:X::X:X) [prefix (A.B.C.D/M|X:X::X:X/M)] [cost <0-255>] [lifetime (infinite|<1-4294967295>)]} {} + Register a MAC address for a logical Ethernet (L2VPN) on behalf of the + NVE identified by the VN and UN addresses. + The optional `prefix` parameter is to support enable IP address + mediation for the given prefix. The `cost` parameter provides the administrative + preference of the forwarding information. If omitted, it defaults to + 255. The `lifetime` parameter identifies the period, in seconds, + that the information remains valid. If omitted, it defaults to + `infinite`. + +.. index:: {Command} {clear vnc prefix (*|A.B.C.D/M|X:X::X:X/M) (*|[(vn|un) (A.B.C.D|X:X::X:X|*) [(un|vn) (A.B.C.D|X:X::X:X|*)] [mac xx:xx:xx:xx:xx:xx] [local-next-hop (A.B.C.D|X:X::X:X)])} {} + +{Command} {clear vnc prefix (*|A.B.C.D/M|X:X::X:X/M) (*|[(vn|un) (A.B.C.D|X:X::X:X|*) [(un|vn) (A.B.C.D|X:X::X:X|*)] [mac xx:xx:xx:xx:xx:xx] [local-next-hop (A.B.C.D|X:X::X:X)])} {} + Delete the information identified by prefix, VN address, and UN address. + Any or all of these parameters may be wilcarded to (potentially) match + more than one registration. + The optional `mac` parameter specifies a layer-2 MAC address + that must match the registration(s) to be deleted. + The optional `local-next-hop` parameter is used to + delete specific local nexthop information. + +.. index:: {Command} {clear vnc mac (*|xx:xx:xx:xx:xx:xx) virtual-network-identifier (*|<1-4294967295>) (*|[(vn|un) (A.B.C.D|X:X::X:X|*) [(un|vn) (A.B.C.D|X:X::X:X|*)] [prefix (*|A.B.C.D/M|X:X::X:X/M)])} {} + +{Command} {clear vnc mac (*|xx:xx:xx:xx:xx:xx) virtual-network-identifier (*|<1-4294967295>) (*|[(vn|un) (A.B.C.D|X:X::X:X|*) [(un|vn) (A.B.C.D|X:X::X:X|*)] [prefix (*|A.B.C.D/M|X:X::X:X/M)])} {} + Delete mac forwarding information. + Any or all of these parameters may be wilcarded to (potentially) match + more than one registration. + The default value for the `prefix` parameter is the wildcard value `*`. + +.. index:: {Command} {clear vnc nve (*|((vn|un) (A.B.C.D|X:X::X:X) [(un|vn) (A.B.C.D|X:X::X:X)])) } {} + +{Command} {clear vnc nve (*|((vn|un) (A.B.C.D|X:X::X:X) [(un|vn) (A.B.C.D|X:X::X:X)])) } {} + Delete prefixes associated with the NVE specified by the given VN and UN + addresses. + It is permissible to specify only one of VN or UN, in which case + any matching registration will be deleted. + It is also permissible to specify `*` in lieu of any VN or UN + address, in which case all registrations will match. + +.. _Other_VNC-Related_Commands: + +Other VNC-Related Commands +========================== + +Note: VNC-Related configuration can be obtained via the `show running-configuration` command when in `enable` mode. + +The following commands are used to clear and display +Virtual Network Control related information: + +.. index:: {COMMAND} {clear vnc counters} {} + +{COMMAND} {clear vnc counters} {} + Reset the counter values stored by the NVA. Counter + values can be seen using the `show vnc` commands listed above. This + command is only available in `enable` mode. + +.. index:: {Command} {show vnc summary} {} + +{Command} {show vnc summary} {} + Print counter values and other general information + about the NVA. Counter values can be reset + using the `clear vnc counters` command listed below. + +.. index:: {Command} {show vnc nves} {} + +{Command} {show vnc nves} {} +.. index:: {Command} {show vnc nves vn|un `address`} {} + +{Command} {show vnc nves vn|un `address`} {} + Display the NVA's current clients. Specifying `address` + limits the output to the NVEs whose addresses match `address`. + The time since the NVA last communicated with the NVE, per-NVE + summary counters and each NVE's addresses will be displayed. + +.. index:: {Command} {show vnc queries} {} + +{Command} {show vnc queries} {} +.. index:: {Command} {show vnc queries `prefix`} {} + +{Command} {show vnc queries `prefix`} {} + Display active Query information. Queries remain valid for the default + Response Lifetime (:ref:`VNC_Defaults_Configuration`) or NVE-group + Response Lifetime (:ref:`VNC_NVE_Group_Configuration`). Specifying + `prefix` limits the output to Query Targets that fall within + `prefix`. + + Query information is provided for each querying NVE, and includes the + Query Target and the time remaining before the information is removed. + +.. index:: {Command} {show vnc registrations [all|local|remote|holddown|imported]} {} + +{Command} {show vnc registrations [all|local|remote|holddown|imported]} {} +.. index:: {Command} {show vnc registrations [all|local|remote|holddown|imported] `prefix`} {} + +{Command} {show vnc registrations [all|local|remote|holddown|imported] `prefix`} {} + Display local, remote, holddown, and/or imported registration information. + Local registrations are routes received via RFP, which are present in the + NVA Registrations Cache. + Remote registrations are routes received via BGP (VPN SAFIs), which + are present in the NVE-group import tables. + Holddown registrations are local and remote routes that have been + withdrawn but whose holddown timeouts have not yet elapsed. + Imported information represents routes that are imported into NVA and + are made available to querying NVEs. Depending on configuration, + imported routes may also be advertised via BGP. + Specifying `prefix` limits the output to the registered prefixes that + fall within `prefix`. + + Registration information includes the registered prefix, the registering + NVE addresses, the registered administrative cost, the registration + lifetime and the time since the information was registered or, in the + case of Holddown registrations, the amount of time remaining before the + information is removed. + +.. index:: {Command} {show vnc responses [active|removed]} {} + +{Command} {show vnc responses [active|removed]} {} +.. index:: {Command} {show vnc responses [active|removed] `prefix`} {} + +{Command} {show vnc responses [active|removed] `prefix`} {} + Display all, active and/or removed response information which are + present in the NVA Responses Cache. Responses remain valid for the + default Response Lifetime (:ref:`VNC_Defaults_Configuration`) or + NVE-group Response Lifetime (:ref:`VNC_NVE_Group_Configuration`.) + When Removal Responses are enabled (:ref:`General_VNC_Configuration`), + such responses are listed for the Response Lifetime. Specifying + `prefix` limits the output to the addresses that fall within + `prefix`. + + Response information is provided for each querying NVE, and includes + the response prefix, the prefix-associated registering NVE addresses, + the administrative cost, the provided response lifetime and the time + remaining before the information is to be removed or will become inactive. + +.. index:: {Command} {show memory vnc} {} + +{Command} {show memory vnc} {} + Print the number of memory items allocated by the NVA. + +.. _Example_VNC_and_VNC-GW_Configurations: + +Example VNC and VNC-GW Configurations +===================================== + + diff --git a/doc/user/vtysh.rst b/doc/user/vtysh.rst new file mode 100644 index 0000000000..d6ed3631a2 --- /dev/null +++ b/doc/user/vtysh.rst @@ -0,0 +1,171 @@ +.. _VTY_shell: + +********* +VTY shell +********* + +*vtysh* provides a combined frontend to all Frr daemons in a +single combined session. It is enabled by default at build time, but can +be disabled through the *--disable-vtysh* option to +*./configure*. + +*vtysh* has a configuration file, :file:`vtysh.conf`. The location +of that file cannot be changed from :file:`@value{INSTALL_PREFIX_ETC`} since +it contains options controlling authentication behavior. This file will +also not be written by configuration-save commands, it is intended to be +updated manually by an administrator with an external editor. + +@quotation Warning +This also means the *hostname* and *banner motd* commands +(which both do have effect for vtysh) need to be manually updated in +:file:`vtysh.conf`. +@end quotation + +Permissions and setup requirements +================================== + +*vtysh* connects to running daemons through Unix sockets located in +:file:`@value{INSTALL_PREFIX_STATE`}. Running vtysh thus requires access to +that directory, plus membership in the *@value{INSTALL_VTY_GROUP*} +group (which is the group that the daemons will change ownership of their +sockets to). + +To restrict access to Frr configuration, make sure no unauthorized users +are members of the *@value{INSTALL_VTY_GROUP*} group. + +PAM support (experimental) +-------------------------- + +vtysh has working (but rather useless) PAM support. It will perform +an "authenticate" PAM call using *@value{PACKAGE_NAME*} as service +name. No other (accounting, session, password change) calls will be +performed by vtysh. + +Users using vtysh still need to have appropriate access to the daemons' +VTY sockets, usually by being member of the *@value{INSTALL_VTY_GROUP*} +group. If they have this membership, PAM support is useless since they can +connect to daemons and issue commands using some other tool. Alternatively, +the *vtysh* binary could be made SGID (set group ID) to the +*@value{INSTALL_VTY_GROUP*} group. @strong{No security guarantees are +made for this configuration}. + +.. index:: {Command} {username `username` nopassword} {} + +{Command} {username `username` nopassword} {} + If PAM support is enabled at build-time, this command allows disabling the + use of PAM on a per-user basis. If vtysh finds that an user is trying to + use vtysh and a "nopassword" entry is found, no calls to PAM will be made + at all. + + +.. _Integrated_configuration_mode: + +Integrated configuration mode +============================= + +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`. + +:file:`frr.conf` is located in :file:`@value{INSTALL_PREFIX_ETC`}. All +daemons check for the existence of this file at startup, and if it exists +will not load their individual configuration files. Instead, +*vtysh -b* must be invoked to process :file:`frr.conf` and apply +its settings to the individual daemons. + +@quotation Warning +*vtysh -b* must also be executed after restarting any daemon. +@end quotation + +Configuration saving, file ownership and permissions +---------------------------------------------------- + +The :file:`frr.conf` file is not written by any of the daemons; instead +*vtysh* contains the neccessary logic to collect configuration from +all of the daemons, combine it and write it out. + +@quotation Warning +Daemons must be running for *vtysh* to be able to collect their +configuration. Any configuration from non-running daemons is permanently +lost after doing a configuration save. +@end quotation + +Since the *vtysh* command may be running as ordinary user on the +system, configuration writes will be tried through *watchfrr*, +using the *write integrated* command internally. Since +*watchfrr* is running as superuser, *vtysh* is able to +ensure correct ownership and permissions on :file:`frr.conf`. + +If *watchfrr* is not running or the configuration write fails, +*vtysh* will attempt to directly write to the file. This is likely +to fail if running as unprivileged user; alternatively it may leave the +file with incorrect owner or permissions. + +Writing the configuration can be triggered directly by invoking +*vtysh -w*. This may be useful for scripting. Note this command +should be run as either the superuser or the Frr user. + +We recommend you do not mix the use of the two types of files. Further, it +is better not to use the integrated frr.conf file, as any syntax error in +it can lead to /all/ of your daemons being unable to start up. Per daemon +files are more robust as impact of errors in configuration are limited to +the daemon in whose file the error is made. + +.. index:: {Command} {service integrated-vtysh-config} {} + +{Command} {service integrated-vtysh-config} {} +.. index:: {Command} {no service integrated-vtysh-config} {} + +{Command} {no service integrated-vtysh-config} {} + Control whether integrated :file:`frr.conf` file is written when + 'write file' is issued. + + These commands need to be placed in :file:`vtysh.conf` to have any effect. + Note that since :file:`vtysh.conf` is not written by Frr itself, they + therefore need to be manually placed in that file. + + This command has 3 states: + + +`` + *service integrated-vtysh-config* + + *vtysh* will always write :file:`frr.conf`. + + +`` + *no service integrated-vtysh-config* + + *vtysh* will never write :file:`frr.conf`; instead it will ask + daemons to write their individual configuration files. + + +`` + Neither option present (default) + + *vtysh* will check whether :file:`frr.conf` exists. If it does, + configuration writes will update that file. Otherwise, writes are performed + through the individual daemons. + + This command is primarily intended for packaging/distribution purposes, to + preset one of the two operating modes and ensure consistent operation across + installations. + +.. index:: {Command} {write integrated} {} + +{Command} {write integrated} {} + Unconditionally (regardless of *service integrated-vtysh-config* + setting) write out integrated :file:`frr.conf` file through + *watchfrr*. If *watchfrr* is not running, this command + is unavailable. + + +Caveats +======= + +Configuration changes made while some daemon is not running will be invisible +to that daemon. The daemon will start up with its saved configuration +(either in its individual configuration file, or in :file:`frr.conf`). +This is particularly troublesome for route-maps and prefix lists, which would +otherwise be synchronized between daemons. + diff --git a/doc/vnc.texi b/doc/vnc.texi deleted file mode 100644 index c44519a9f3..0000000000 --- a/doc/vnc.texi +++ /dev/null @@ -1,1596 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the Frr Manual. -@c @value{COPYRIGHT_STR} -@c See file frr.texi for copying conditions. - -@node VNC and VNC-GW -@chapter VNC and VNC-GW -This chapter describes how to use -Virtual Network Control (@acronym{VNC}) services, -including Network Virtualization Authority (@acronym{NVA}) and -VNC Gateway (@acronym{VNC-GW}) functions. -Background information on NVAs, -Network Virtualization Edges (@acronym{NVE}s), underlay networks (@acronym{UN}s), -and virtual networks (@acronym{VN}s) is available from the -@url{https://datatracker.ietf.org/wg/nvo3,IETF Network Virtualization Overlays (@acronym{NVO3}) Working Group}. -VNC Gateways (@acronym{VNC-GW}s) support the import/export of routing -information between VNC and customer edge routers (@acronym{CE}s) -operating within a VN. Both IP/Layer 3 (L3) VNs, and IP with -Ethernet/Layer 2 (L2) VNs are supported. - -BGP, with IP VPNs and Tunnel Encapsulation, is used to distribute VN -information between NVAs. BGP based IP VPN support is defined in -@cite{RFC4364, BGP/MPLS IP Virtual Private Networks (VPNs)}, and -@cite{RFC4659, BGP-MPLS IP Virtual Private Network (VPN) Extension for -IPv6 VPN }. Both the Encapsulation Subsequent Address Family Identifier -(SAFI) and the Tunnel Encapsulation Attribute, @cite{RFC5512, The BGP -Encapsulation Subsequent Address Family Identifier (SAFI) and the BGP -Tunnel Encapsulation Attribute}, are supported. - -The protocol that is used to communicate routing and Ethernet / Layer 2 -(L2) forwarding information between NVAs and NVEs is referred to as the -Remote Forwarder Protocol (RFP). @code{OpenFlow} is an example -RFP. Specific RFP implementations may choose to implement either a -@code{hard-state} or @code{soft-state} prefix and address registration -model. To support a @code{soft-state} refresh model, a @var{lifetime} -in seconds is associated with all registrations and responses. - -The chapter also provides sample configurations for basic example scenarios. - -@menu -* Configuring VNC Services:: -* Manual Address Control:: -* Other VNC-Related Commands:: -* Example VNC and VNC-GW Configurations:: -* Release Notes:: -@end menu - -@node Configuring VNC Services -@section Configuring VNC - -Virtual Network Control (@acronym{VNC}) service configuration commands -appear in the @code{router bgp} section of the BGPD configuration file -(@pxref{BGP Configuration Examples}). The commands are broken down into -the following areas: - -@menu -* General VNC Configuration:: -* RFP Related Configuration:: -* VNC Defaults Configuration:: -* VNC NVE Group Configuration:: -* VNC L2 Group Configuration:: -* Configuring Redistribution of Routes from Other Routing Protocols:: -* Configuring Export of Routes to Other Routing Protocols:: -@end menu - -@code{General VNC} configuration applies to general VNC operation and is -primarily used to control the method used to advertise tunnel -information. - -@code{Remote Forwarder Protocol (RFP)} configuration relates to the -protocol used between NVAs and NVEs. - -@code{VNC Defaults} provides default parameters for registered NVEs. - -@code{VNC NVE Group} provides for configuration of a specific set of -registered NVEs and overrides default parameters. - -@code{Redistribution} and @code{Export} control VNC-GW operation, i.e., -the import/export of routing -information between VNC and customer edge routers (@acronym{CE}s) -operating within a VN. - -@node General VNC Configuration -@subsection General VNC Configuration - -@deffn {VNC} {vnc advertise-un-method encap-safi|encap-attr} {} -Advertise NVE underlay-network IP addresses using the encapsulation SAFI -(@code{encap-safi}) or the UN address sub-TLV of the Tunnel Encapsulation attribute -(@code{encap-attr}). When @code{encap-safi} is used, neighbors under -@code{address-family encap} and/or @code{address-family encapv6} must be -configured. The default is @code{encap-attr}. -@end deffn - -@node RFP Related Configuration -@subsection RFP Related Configuration - -The protocol that is used to communicate routing and Ethernet / L2 -forwarding information between NVAs and NVEs is referred to as the -Remote Forwarder Protocol (RFP). Currently, only a simple example RFP -is included in Frr. Developers may use this example as a starting -point to integrate Frr with an RFP of their choosing, e.g., -@code{OpenFlow}. The example code includes the following sample -configuration: - -@deffn {RFP} {rfp example-config-value @var{VALUE}} -This is a simple example configuration parameter included as part of the -RFP example code. @code{VALUE} must be in the range of 0 to 4294967295. -@end deffn - -@node VNC Defaults Configuration -@subsection VNC Defaults Configuration - -The VNC Defaults section allows the user to specify default values for -configuration parameters for all registered NVEs. -Default values are overridden by @ref{VNC NVE Group Configuration}. - -@deffn {VNC} {vnc defaults} {} -Enter VNC configuration mode for specifying VNC default behaviors. Use -@code{exit-vnc} to leave VNC configuration mode. @code{vnc -defaults} is optional. - -@example -vnc defaults - ... various VNC defaults -exit-vnc -@end example -@end deffn - -These are the statements that can appear between @code{vnc defaults} -and @code{exit-vnc}. - -@deffn {VNC} {rt import @var{rt-list}} {} -@deffnx {VNC} {rt export @var{rt-list}} {} -@deffnx {VNC} {rt both @var{rt-list}} {} - -Specify default route target import and export lists. @var{rt-list} is a -space-separated list of route targets, each element of which is -in one of the following forms: -@itemize -@item @var{IPv4-address}:@var{two-byte-integer} -@item @var{four-byte-autonomous-system-number}:@var{two-byte-integer} -@item @var{two-byte-autonomous-system-number}:@var{four-byte-integer} -@end itemize - -If no default import RT list is specified, then the default import RT -list is empty. -If no default export RT list is specified, then the default export RT -list is empty. - -A complete definition of these parameters is -given below (@pxref{VNC NVE Group Configuration}). - -@end deffn - -@deffn {VNC} {rd @var{route-distinguisher}} - -Specify the default route distinguisher (RD) for routes advertised via BGP -VPNs. The route distinguisher must be in one of four forms: -@itemize -@item @var{IPv4-address}:@var{two-byte-integer} -@item @var{four-byte-autonomous-system-number}:@var{two-byte-integer} -@item @var{two-byte-autonomous-system-number}:@var{four-byte-integer} -@item auto:vn:@var{two-byte-integer} -@end itemize - -If RD is specified in the defaults section, the default RD -value is @var{two-byte-autonomous-system-number=0}:@var{four-byte-integer=0}. - -A complete definition of this parameter is -given below (@pxref{VNC NVE Group Configuration}). -@end deffn - -@deffn {VNC} {l2rd @var{nve-id-value}} -Set the value used to distinguish NVEs connected to the same logical -Ethernet segment (i.e., L2VPN). - -A complete definition of this parameter is -given below (@pxref{VNC NVE Group Configuration}). -@end deffn - -@deffn {VNC} {response-lifetime @var{lifetime}|infinite} {} -Specify the default lifetime to be included in RFP -response messages sent to NVEs. - -A complete definition of this parameter is -given below (@pxref{VNC NVE Group Configuration}). - -@end deffn - -@deffn {VNC} {export bgp|zebra route-map MAP-NAME} -Specify that the named route-map should be applied to routes -being exported to bgp or zebra. -@end deffn - -@deffn {VNC} {export bgp|zebra no route-map} -Specify that no route-map should be applied to routes -being exported to bgp or zebra. -@end deffn - -@deffn {VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} -Specify that the named prefix-list filter should be applied to -routes being exported to bgp or zebra. -Prefix-lists for ipv4 and ipv6 are independent of each other. -@end deffn - -@deffn {VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} -Specify that no prefix-list filter should be applied to -routes being exported to bgp or zebra. -@end deffn - -@deffn {VNC} {exit-vnc} {} -Exit VNC configuration mode. -@end deffn - -@c The following example @code{vnc defaults} defines a route target import-export -@c list for the route targets 1000:1 and 1000:2; a default route -@c distinguisher, 4444:10; and a default response lifetime of 500 -@c seconds. -@c -@c @example -@c vnc defaults -@c rt both 1000:1 1000:2 -@c rd 4444:10 -@c response-lifetime 500 -@c exit-vnc -@c @end example - -@node VNC NVE Group Configuration -@subsection VNC NVE Group Configuration - -A NVE Group corresponds to a specific set of NVEs. A Client NVE is -assigned to an NVE Group based on whether there is a match for either -its virtual or underlay network address against the VN and/or UN address -prefixes specified in the NVE Group definition. When an NVE Group -definition specifies both VN and UN address prefixes, then an NVE must -match both prefixes in order to be assigned to the NVE Group. In the -event that multiple NVE Groups match based on VN and/or UN addresses, -the NVE is assigned to the first NVE Group listed in the configuration. -If an NVE is not assigned to an NVE Group, its messages will be ignored. - -Configuration values specified for an NVE group apply to all -member NVEs and override configuration values specified in the VNC -Defaults section. - -@strong{At least one @code{nve-group} is mandatory for useful VNC -operation.} - -@deffn {VNC} {vnc nve-group @var{name}} {} -Enter VNC configuration mode for defining the NVE group @var{name}. -Use @code{exit} or @code{exit-vnc} to exit group configuration mode. - -@example -vnc nve-group group1 - ... configuration commands -exit-vnc -@end example -@end deffn - -@deffn {VNC} {no vnc nve-group @var{name}} {} -Delete the NVE group named @var{name}. -@end deffn - -The following statements are valid in an NVE group definition: - -@deffn {VNC} {l2rd @var{nve-id-value}} -Set the value used to distinguish NVEs connected to the same physical -Ethernet segment (i.e., at the same location)@footnote{The nve-id is -carried in the route -distinguisher. It is the second octet of the eight-octet route -distinguisher generated for Ethernet / L2 advertisements. -The first octet is a constant 0xFF, and the third through eighth -octets are set to the L2 ethernet address being advertised.} - -The nve-id subfield may be specified as either a literal value -in the range 1-255, or it may be specified as @code{auto:vn}, which -means to use the least-significant octet of the originating -NVE's VN address. -@end deffn - -@deffn {VNC} {prefix vn|un A.B.C.D/M|X:X::X:X/M} {} -@anchor{prefix} -Specify the matching prefix for this NVE group by either virtual-network address -(@code{vn}) or underlay-network address (@code{un}). Either or both virtual-network -and underlay-network prefixes may be specified. Subsequent virtual-network or -underlay-network values within a @code{vnc nve-group} @code{exit-vnc} -block override their respective previous values. - -These prefixes are used only for determining assignments of NVEs -to NVE Groups. -@end deffn - -@deffn {VNC} {rd @var{route-distinguisher}} -Specify the route distinguisher for routes advertised via BGP -VPNs. The route distinguisher must be in one of these forms: -@itemize -@item @var{IPv4-address}:@var{two-byte-integer} -@item @var{four-byte-autonomous-system-number}:@var{two-byte-integer} -@item @var{two-byte-autonomous-system-number}:@var{four-byte-integer} -@item auto:vn:@var{two-byte-integer} -@end itemize - -Routes originated by NVEs in the NVE group will use -the group's specified @var{route-distinguisher} when they are -advertised via BGP. -If the @code{auto} form is specified, it means that a matching NVE has -its RD set to -@var{rd_type=IP=1}:@var{IPv4-address=VN-address}:@var{two-byte-integer}, -for IPv4 VN addresses and -@var{rd_type=IP=1}:@var{IPv4-address=Last-four-bytes-of-VN-address}:@var{two-byte-integer}, -for IPv6 VN addresses. - -If the NVE group definition does not specify a @var{route-distinguisher}, -then the default @var{route-distinguisher} is used. -If neither a group nor a default @var{route-distinguisher} is -configured, then the advertised RD is set to -@var{two-byte-autonomous-system-number=0}:@var{four-byte-integer=0}. -@end deffn - -@deffn {VNC} {response-lifetime @var{lifetime}|infinite} {} -Specify the response lifetime, in seconds, to be included in RFP -response messages sent to NVEs. If the value -``infinite'' is given, an infinite lifetime will be used. - -Note that this parameter is not the same as the lifetime supplied by -NVEs in RFP registration messages. This parameter does not affect -the lifetime value attached to routes sent by this server via BGP. - -If the NVE group definition does not specify a @var{response-lifetime}, -the default @var{response-lifetime} will be used. -If neither a group nor a default @var{response-lifetime} is configured, -the value 3600 will be used. The maximum response lifetime is 2147483647. -@end deffn - -@deffn {VNC} {rt export @var{rt-list}} {} -@deffnx {VNC} {rt import @var{rt-list}} {} -@deffnx {VNC} {rt both @var{rt-list}} {} -Specify route target import and export lists. @var{rt-list} is a -space-separated list of route targets, each element of which is -in one of the following forms: -@itemize -@item @var{IPv4-address}:@var{two-byte-integer} -@item @var{four-byte-autonomous-system-number}:@var{two-byte-integer} -@item @var{two-byte-autonomous-system-number}:@var{four-byte-integer} -@end itemize - -The first form, @code{rt export}, specifies an @var{export rt-list}. -The @var{export rt-list} will be attached to routes originated by -NVEs in the NVE group when they are advertised via BGP. -If the NVE group definition does not specify an @var{export rt-list}, -then the default @var{export rt-list} is used. -If neither a group nor a default @var{export rt-list} is configured, -then no RT list will be sent; in turn, these routes will probably -not be processed -by receiving NVAs. - -The second form, @code{rt import} specifies an @var{import rt-list}, -which is a filter for incoming routes. -In order to be made available to NVEs in the group, -incoming BGP VPN and @w{ENCAP} @w{SAFI} (when @code{vnc -advertise-un-method encap-safi} is set) routes must have -RT lists that have at least one route target in common with the -group's @var{import rt-list}. - -If the NVE group definition does not specify an import filter, -then the default @var{import rt-list} is used. -If neither a group nor a default @var{import rt-list} is configured, -there can be no RT intersections when receiving BGP routes and -therefore no incoming BGP routes will be processed for the group. - -The third, @code{rt both}, is a shorthand way of specifying both -lists simultaneously, and is equivalent to @code{rt export @var{rt-list}} -followed by @code{rt import @var{rt-list}}. -@end deffn - -@deffn {VNC} {export bgp|zebra route-map MAP-NAME} -Specify that the named route-map should be applied to routes -being exported to bgp or zebra. -This paramter is used in conjunction with -@ref{Configuring Export of Routes to Other Routing Protocols}. -This item is optional. -@end deffn - -@deffn {VNC} {export bgp|zebra no route-map} -Specify that no route-map should be applied to routes -being exported to bgp or zebra. -This paramter is used in conjunction with -@ref{Configuring Export of Routes to Other Routing Protocols}. -This item is optional. -@end deffn - -@deffn {VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} -Specify that the named prefix-list filter should be applied to -routes being exported to bgp or zebra. -Prefix-lists for ipv4 and ipv6 are independent of each other. -This paramter is used in conjunction with -@ref{Configuring Export of Routes to Other Routing Protocols}. -This item is optional. -@end deffn - -@deffn {VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} -Specify that no prefix-list filter should be applied to -routes being exported to bgp or zebra. -This paramter is used in conjunction with -@ref{Configuring Export of Routes to Other Routing Protocols}. -This item is optional. -@end deffn - -@c The following example shows two @code{vnc nve-group} definitions. The first one, -@c ``group1'', applies to the IPV4 virtual-network route prefix 172.16/16. It -@c sets the response lifetime to 200 seconds. It defines a route target -@c import-export filter for the route targets 1000:1 and 1000:2 -@c -@c The second @code{vnc nve-group} definition, ``group2'', applies to the IPV6 -@c underlay-network route prefix 10.0.2/24. It defines the same response -@c lifetime and import-export filter as ``group1''. -@c -@c @example -@c vnc nve-group group1 -@c prefix vn 172.16/16 -@c response-lifetime 200 -@c rt both 1000:1 1000:2 -@c exit-vnc -@c -@c vnc nve-group group2 -@c prefix un 10.0.2/24 -@c response-lifetime 200 -@c rt both 1000:1 1000:2 -@c exit-vnc -@c @end example - -@node VNC L2 Group Configuration -@subsection VNC L2 Group Configuration - -The route targets advertised with prefixes and addresses registered by -an NVE are determined based on the NVE's associated VNC NVE Group -Configuration, @pxref{VNC NVE Group Configuration}. Layer 2 (L2) Groups -are used to override the route targets for an NVE's Ethernet -registrations based on the Logical Network Identifier and label value. -A Logical Network Identifier is used to uniquely identify a logical -Ethernet segment and is conceptually similar to the Ethernet Segment -Identifier defined in @cite{RFC7432, BGP MPLS-Based Ethernet VPN}. Both -the Logical Network Identifier and Label are passed to VNC via RFP -prefix and address registration. - -Note that a corresponding NVE group configuration must be present, and -that other NVE associated configuration information, notably RD, is -not impacted by L2 Group Configuration. - -@deffn {VNC} {vnc l2-group @var{name}} {} -Enter VNC configuration mode for defining the L2 group @var{name}. -Use @code{exit} or @code{exit-vnc} to exit group configuration mode. - -@example -vnc l2-group group1 - ... configuration commands -exit-vnc -@end example -@end deffn - -@deffn {VNC} {no vnc l2-group @var{name}} {} -Delete the L2 group named @var{name}. -@end deffn - -The following statements are valid in a L2 group definition: - -@deffn {VNC} {logical-network-id @var{VALUE}} -Define the Logical Network Identifier with a value in the range of -0-4294967295 that identifies the logical Ethernet segment. -@end deffn - -@deffn {VNC} {labels @var{label-list}} -@deffnx {VNC} {no labels @var{label-list}} -Add or remove labels associated with the group. @var{label-list} is a -space separated list of label values in the range of 0-1048575. -@end deffn - -@deffn {VNC} {rt import @var{rt-target}} {} -@deffnx {VNC} {rt export @var{rt-target}} {} -@deffnx {VNC} {rt both @var{rt-target}} {} -Specify the route target import and export value associated with the -group. A complete definition of these parameters is given above, -@pxref{VNC NVE Group Configuration}. -@end deffn - - -@node Configuring Redistribution of Routes from Other Routing Protocols -@subsection Configuring Redistribution of Routes from Other Routing Protocols - -Routes from other protocols (including BGP) can be provided to VNC (both -for RFP and for redistribution via BGP) -from three sources: the zebra kernel routing process; -directly from the main (default) unicast BGP RIB; or directly -from a designated BGP unicast exterior routing RIB instance. - -The protocol named in the @code{vnc redistribute} command indicates -the route source: -@code{bgp-direct} routes come directly from the main (default) -unicast BGP RIB and are available for RFP and are redistributed via BGP; -@code{bgp-direct-to-nve-groups} routes come directly from a designated -BGP unicast routing RIB and are made available only to RFP; -and routes from other protocols come from the zebra kernel -routing process. -Note that the zebra process does not need to be active if -only @code{bgp-direct} or @code{bgp-direct-to-nve-groups} routes are used. - -@subsubsection @code{zebra} routes - -Routes originating from protocols other than BGP must be obtained -via the zebra routing process. -Redistribution of these routes into VNC does not support policy mechanisms -such as prefix-lists or route-maps. - -@subsubsection @code{bgp-direct} routes - -@code{bgp-direct} redistribution supports policy via -prefix lists and route-maps. This policy is applied to incoming -original unicast routes before the redistribution translations -(described below) are performed. - -Redistribution of @code{bgp-direct} routes is performed in one of three -possible modes: @code{plain}, @code{nve-group}, or @code{resolve-nve}. -The default mode is @code{plain}. -These modes indicate the kind of translations applied to routes before -they are added to the VNC RIB. - -In @code{plain} mode, the route's next hop is unchanged and the RD is set -based on the next hop. -For @code{bgp-direct} redistribution, the following translations are performed: -@itemize @bullet -@item -The VN address is set to the original unicast route's next hop address. -@item -The UN address is NOT set. (VN->UN mapping will occur via -ENCAP route or attribute, based on @code{vnc advertise-un-method} -setting, generated by the RFP registration of the actual NVE) -@item -The RD is set to as if auto:vn:0 were specified (i.e., -@var{rd_type=IP=1}:@var{IPv4-address=VN-address}:@var{two-byte-integer=0}) -@item -The RT list is included in the extended community list copied from the -original unicast route (i.e., it must be set in the original unicast route). -@end itemize - - - -In @code{nve-group} mode, routes are registered with VNC as -if they came from an NVE in the nve-group designated in the -@code{vnc redistribute nve-group} command. The following -translations are performed: - -@itemize @bullet -@item -The next hop/VN address is set to the VN prefix configured for the -redistribute nve-group. -@item -The UN address is set to the UN prefix configured for the -redistribute nve-group. -@item -The RD is set to the RD configured for the redistribute nve-group. -@item -The RT list is set to the RT list configured for the redistribute nve-group. -If @code{bgp-direct} routes are being redistributed, -any extended communities present in the original unicast route -will also be included. -@end itemize - - -In @code{resolve-nve} mode, the next hop of the original BGP route is -typically the address of an NVE connected router (CE) connected by one or -more NVEs. -Each of the connected NVEs will register, via RFP, a VNC host route -to the CE. -This mode may be though of as a mechanism to proxy RFP registrations -of BGP unicast routes on behalf of registering NVEs. - -Multiple copies of the BGP route, one per matching NVE host route, will be -added to VNC. -In other words, for a given BGP unicast route, each instance of a -RFP-registered host route to the unicast route's next hop will result -in an instance of an imported VNC route. -Each such imported VNC route will have a prefix equal to the original -BGP unicast route's prefix, and a next hop equal to the next hop of the -matching RFP-registered host route. -If there is no RFP-registered host route to the next hop of the BGP unicast -route, no corresponding VNC route will be imported. - -The following translations are applied: - -@itemize @bullet -@item -The Next Hop is set to the next hop of the NVE route (i.e., the -VN address of the NVE). - -@item -The extended community list in the new route is set to the -union of: -@itemize @minus -@item -Any extended communities in the original BGP route -@item -Any extended communities in the NVE route -@item -An added route-origin extended community with the next hop of the -original BGP route -is added to the new route. -The value of the local administrator field defaults 5226 but may -be configured by the user via the @code{roo-ec-local-admin} parameter. -@end itemize - -@item -The Tunnel Encapsulation attribute is set to the value of the Tunnel -Encapsulation attribute of the NVE route, if any. - -@end itemize - -@subsubsection @code{bgp-direct-to-nve-groups} routes - -Unicast routes from the main or a designated instance of BGP -may be redistributed to VNC as bgp-direct-to-nve-groups routes. These -routes are NOT announced via BGP, -but they are made available for local RFP lookup in response to -queries from NVEs. - -A non-main/default BGP instance is configured using the -@code{bgp multiple-instance} and @code{router bgp AS view NAME} -commands as described elsewhere in this document. - -In order for a route in the unicast BGP RIB to be made -available to a querying NVE, there must already be, available to -that NVE, an (interior) VNC route matching the next hop address -of the unicast route. -When the unicast route is provided to the NVE, its next hop -is replaced by the next hop of the corresponding -NVE. If there are multiple longest-prefix-match VNC routes, -the unicast route will be replicated for each. - -There is currently no policy (prefix-list or route-map) support -for @code{bgp-direct-to-nve-groups} routes. - -@subsubsection Redistribution Command Syntax - -@deffn {VNC} {vnc redistribute ipv4|ipv6 bgp|bgp-direct|ipv6 bgp-direct-to-nve-groups|connected|kernel|ospf|rip|static} {} -@deffnx {VNC} {vnc redistribute ipv4|ipv6 bgp-direct-to-nve-groups view @var{VIEWNAME}} {} -@deffnx {VNC} {no vnc redistribute ipv4|ipv6 bgp|bgp-direct|bgp-direct-to-nve-groups|connected|kernel|ospf|rip|static} {} -Import (or do not import) prefixes from another routing -protocols. Specify both the address family to import (@code{ipv4} or -@code{ipv6}) and the protocol (@code{bgp}, @code{bgp-direct}, -@code{bgp-direct-to-nve-groups}, @code{connected}, -@code{kernel}, @code{ospf}, @code{rip}, or @code{static}). Repeat -this statement as needed for each combination of address family and -routing protocol. -Prefixes from protocol @code{bgp-direct} are imported from unicast BGP -in the same bgpd process. -Prefixes from all other protocols (including @code{bgp}) are imported -via the @code{zebra} kernel routing process. -@end deffn - -@deffn {VNC} {vnc redistribute mode plain|nve-group|resolve-nve} -Redistribute routes from other protocols into VNC using the -specified mode. -Not all combinations of modes and protocols are supported. -@end deffn - -@deffn {VNC} {vnc redistribute nve-group @var{group-name}} {} -@deffnx {VNC} {no vnc redistribute nve-group @var{group-name}} {} -When using @code{nve-group} mode, -assign (or do not assign) the NVE group @var{group-name} to routes -redistributed from another routing protocol. @var{group-name} -must be configured using @code{vnc nve-group}. - -The VN and UN prefixes of the nve-group must both be configured, -and each prefix must be specified as a full-length (/32 for IPv4, -/128 for IPv6) prefix. -@end deffn - -@deffn {VNC} {vnc redistribute lifetime @var{lifetime}|infinite} {} -Assign a registration lifetime, either @var{lifetime} seconds or -@code{infinite}, to prefixes redistributed from other routing -protocols as if they had been received via RFP registration messages -from an NVE. @var{lifetime} can be any integer between 1 and -4294967295, inclusive. -@end deffn - -@deffn {VNC} {vnc redistribute resolve-nve roo-ec-local-admin @var{0-65536}} -Assign a value to the local-administrator subfield used in the -Route Origin extended community that is assigned to routes exported -under the @code{resolve-nve} mode. The default value is @var{5226}. -@end deffn - -The following four @code{prefix-list} and @code{route-map} commands -may be specified in the context of an nve-group or not. -If they are specified in the context of an nve-group, they -apply only if the redistribution mode is @code{nve-group}, -and then only for routes being redistributed from -@code{bgp-direct}. -If they are specified outside the context of an nve-group, then -they apply only for redistribution modes @code{plain} and @code{resolve-nve}, -and then only for routes being redistributed from @code{bgp-direct}. - -@deffn {VNC} {vnc redistribute bgp-direct (ipv4|ipv6) prefix-list @var{LIST-NAME}} -When redistributing @code{bgp-direct} routes, -specifies that the named prefix-list should be applied. -@end deffn - -@deffn {VNC} {vnc redistribute bgp-direct no (ipv4|ipv6) prefix-list} -When redistributing @code{bgp-direct} routes, -specifies that no prefix-list should be applied. -@end deffn - -@deffn {VNC} {vnc redistribute bgp-direct route-map @var{MAP-NAME}} -When redistributing @code{bgp-direct} routes, -specifies that the named route-map should be applied. -@end deffn - -@deffn {VNC} {vnc redistribute bgp-direct no route-map} -When redistributing @code{bgp-direct} routes, -specifies that no route-map should be applied. -@end deffn - -@node Configuring Export of Routes to Other Routing Protocols -@subsection Configuring Export of Routes to Other Routing Protocols - -Routes from VNC (both for RFP and for redistribution via BGP) can be -provided to other protocols, either via zebra or directly to BGP. - -It is important to note that when exporting routes to other protocols, -the downstream protocol must also be configured to import the routes. -For example, when VNC routes are exported to unicast BGP, the BGP -configuration must include a corresponding @code{redistribute vnc-direct} -statement. - -@deffn {VNC} {export bgp|zebra mode none|group-nve|registering-nve|ce} -Specify how routes should be exported to bgp or zebra. -If the mode is @code{none}, routes are not exported. -If the mode is @code{group-nve}, routes are exported according -to nve-group or vrf-policy group configuration (@pxref{VNC NVE Group Configuration}): if a group is configured to -allow export, then each prefix visible to the group is exported -with next hops set to the currently-registered NVEs. -If the mode is @code{registering-nve}, then all VNC routes are -exported with their original next hops. -If the mode is @code{ce}, only VNC routes that have an NVE connected CE Router -encoded in a Route Origin Extended Community are exported. -This extended community must have an administrative value that -matches the configured @code{roo-ec-local-admin} value. -The next hop of the exported route is set to the encoded -NVE connected CE Router. - -The default for both bgp and zebra is mode @code{none}. -@end deffn - -@deffn {VNC} {vnc export bgp|zebra group-nve group @var{group-name}} -@deffnx {VNC} {vnc export bgp|zebra group-nve no group @var{group-name}} -When export mode is @code{group-nve}, -export (or do not export) prefixes from the specified nve-group or -vrf-policy group -to unicast BGP or to zebra. -Repeat this statement as needed for each nve-group to be exported. -Each VNC prefix that is exported will result in N exported routes to the -prefix, each with a next hop corresponding to one of the N NVEs currently -associated with the nve-group. -@end deffn - -@deffn {VNC} export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME -When export mode is @code{ce} or @code{registering-nve}, -specifies that the named prefix-list should be applied to routes -being exported to bgp or zebra. -Prefix-lists for ipv4 and ipv6 are independent of each other. -@end deffn - -@deffn {VNC} export bgp|zebra no ipv4|ipv6 prefix-list -When export mode is @code{ce} or @code{registering-nve}, -specifies that no prefix-list should be applied to routes -being exported to bgp or zebra. -@end deffn - -@deffn {VNC} export bgp|zebra route-map MAP-NAME -When export mode is @code{ce} or @code{registering-nve}, -specifies that the named route-map should be applied to routes -being exported to bgp or zebra. -@end deffn - -@deffn {VNC} export bgp|zebra no route-map -When export mode is @code{ce} or @code{registering-nve}, -specifies that no route-map should be applied to routes -being exported to bgp or zebra. -@end deffn - -When the export mode is @code{group-nve}, policy for exported -routes is specified per-NVE-group or vrf-policy group inside a @code{nve-group} @var{RFG-NAME} block -via the following commands(@pxref{VNC NVE Group Configuration}): - -@deffn {VNC} {export bgp|zebra route-map MAP-NAME} -This command is valid inside a @code{nve-group} @var{RFG-NAME} block. -It specifies that the named route-map should be applied to routes -being exported to bgp or zebra. -@end deffn - -@deffn {VNC} {export bgp|zebra no route-map} -This command is valid inside a @code{nve-group} @var{RFG-NAME} block. -It specifies that no route-map should be applied to routes -being exported to bgp or zebra. -@end deffn - -@deffn {VNC} {export bgp|zebra ipv4|ipv6 prefix-list LIST-NAME} -This command is valid inside a @code{nve-group} @var{RFG-NAME} block. -It specifies that the named prefix-list filter should be applied to -routes being exported to bgp or zebra. -Prefix-lists for ipv4 and ipv6 are independent of each other. -@end deffn - -@deffn {VNC} {export bgp|zebra no ipv4|ipv6 prefix-list} -This command is valid inside a @code{nve-group} @var{RFG-NAME} block. -It specifies that no prefix-list filter should be applied to -routes being exported to bgp or zebra. -@end deffn - -@node Manual Address Control -@section Manual Address Control - -The commands in this section can be used to augment normal dynamic VNC. -The @code{add vnc} commands can be used to manually add IP prefix or -Ethernet MAC address forwarding information. The @code{clear vnc} -commands can be used to remove manually and dynamically added -information. - -@deffn {Command} {add vnc prefix (A.B.C.D/M|X:X::X:X/M) vn (A.B.C.D|X:X::X:X) un (A.B.C.D|X:X::X:X) [cost <0-255>] [lifetime (infinite|<1-4294967295>)] [local-next-hop (A.B.C.D|X:X::X:X) [local-cost <0-255>]]} {} -Register an IP prefix on behalf of the NVE identified by the VN and UN -addresses. The @code{cost} parameter provides the administrative -preference of the forwarding information for remote advertisement. If -omitted, it defaults to 255 (lowest preference). The @code{lifetime} -parameter identifies the period, in seconds, that the information -remains valid. If omitted, it defaults to @var{infinite}. The optional -@code{local-next-hop} parameter is used to configure a nexthop to be -used by an NVE to reach the prefix via a locally connected CE router. -This information remains local to the NVA, i.e., not passed to other -NVAs, and is only passed to registered NVEs. When specified, it is also -possible to provide a @code{local-cost} parameter to provide a -forwarding preference. If omitted, it defaults to 255 (lowest -preference). -@end deffn - - -@deffn {Command} {add vnc mac xx:xx:xx:xx:xx:xx virtual-network-identifier <1-4294967295> vn (A.B.C.D|X:X::X:X) un (A.B.C.D|X:X::X:X) [prefix (A.B.C.D/M|X:X::X:X/M)] [cost <0-255>] [lifetime (infinite|<1-4294967295>)]} {} -Register a MAC address for a logical Ethernet (L2VPN) on behalf of the -NVE identified by the VN and UN addresses. -The optional @code{prefix} parameter is to support enable IP address -mediation for the given prefix. The @code{cost} parameter provides the administrative -preference of the forwarding information. If omitted, it defaults to -255. The @code{lifetime} parameter identifies the period, in seconds, -that the information remains valid. If omitted, it defaults to -@var{infinite}. -@end deffn - -@deffn {Command} {clear vnc prefix (*|A.B.C.D/M|X:X::X:X/M) (*|[(vn|un) (A.B.C.D|X:X::X:X|*) [(un|vn) (A.B.C.D|X:X::X:X|*)] [mac xx:xx:xx:xx:xx:xx] [local-next-hop (A.B.C.D|X:X::X:X)])} {} -Delete the information identified by prefix, VN address, and UN address. -Any or all of these parameters may be wilcarded to (potentially) match -more than one registration. -The optional @code{mac} parameter specifies a layer-2 MAC address -that must match the registration(s) to be deleted. -The optional @code{local-next-hop} parameter is used to -delete specific local nexthop information. -@end deffn - -@deffn {Command} {clear vnc mac (*|xx:xx:xx:xx:xx:xx) virtual-network-identifier (*|<1-4294967295>) (*|[(vn|un) (A.B.C.D|X:X::X:X|*) [(un|vn) (A.B.C.D|X:X::X:X|*)] [prefix (*|A.B.C.D/M|X:X::X:X/M)])} {} -Delete mac forwarding information. -Any or all of these parameters may be wilcarded to (potentially) match -more than one registration. -The default value for the @code{prefix} parameter is the wildcard value @var{*}. -@end deffn - -@deffn {Command} {clear vnc nve (*|((vn|un) (A.B.C.D|X:X::X:X) [(un|vn) (A.B.C.D|X:X::X:X)])) } {} -Delete prefixes associated with the NVE specified by the given VN and UN -addresses. -It is permissible to specify only one of VN or UN, in which case -any matching registration will be deleted. -It is also permissible to specify @code{*} in lieu of any VN or UN -address, in which case all registrations will match. -@end deffn - -@node Other VNC-Related Commands -@section Other VNC-Related Commands - -Note: VNC-Related configuration can be obtained via the @code{show -running-configuration} command when in @code{enable} mode. - -The following commands are used to clear and display -Virtual Network Control related information: - -@deffn {COMMAND} {clear vnc counters} {} -Reset the counter values stored by the NVA. Counter -values can be seen using the @code{show vnc} commands listed above. This -command is only available in @code{enable} mode. -@end deffn - -@deffn {Command} {show vnc summary} {} -Print counter values and other general information -about the NVA. Counter values can be reset -using the @code{clear vnc counters} command listed below. -@end deffn - -@deffn {Command} {show vnc nves} {} -@deffnx {Command} {show vnc nves vn|un @var{address}} {} -Display the NVA's current clients. Specifying @var{address} -limits the output to the NVEs whose addresses match @var{address}. -The time since the NVA last communicated with the NVE, per-NVE -summary counters and each NVE's addresses will be displayed. -@end deffn - -@deffn {Command} {show vnc queries} {} -@deffnx {Command} {show vnc queries @var{prefix}} {} -Display active Query information. Queries remain valid for the default -Response Lifetime (@pxref{VNC Defaults Configuration}) or NVE-group -Response Lifetime (@pxref{VNC NVE Group Configuration}). Specifying -@var{prefix} limits the output to Query Targets that fall within -@var{prefix}. - -Query information is provided for each querying NVE, and includes the -Query Target and the time remaining before the information is removed. -@end deffn - -@deffn {Command} {show vnc registrations [all|local|remote|holddown|imported]} {} -@deffnx {Command} {show vnc registrations [all|local|remote|holddown|imported] @var{prefix}} {} -Display local, remote, holddown, and/or imported registration information. -Local registrations are routes received via RFP, which are present in the -NVA Registrations Cache. -Remote registrations are routes received via BGP (VPN SAFIs), which -are present in the NVE-group import tables. -Holddown registrations are local and remote routes that have been -withdrawn but whose holddown timeouts have not yet elapsed. -Imported information represents routes that are imported into NVA and -are made available to querying NVEs. Depending on configuration, -imported routes may also be advertised via BGP. -Specifying @var{prefix} limits the output to the registered prefixes that -fall within @var{prefix}. - -Registration information includes the registered prefix, the registering -NVE addresses, the registered administrative cost, the registration -lifetime and the time since the information was registered or, in the -case of Holddown registrations, the amount of time remaining before the -information is removed. -@end deffn - -@deffn {Command} {show vnc responses [active|removed]} {} -@deffnx {Command} {show vnc responses [active|removed] @var{prefix}} {} -Display all, active and/or removed response information which are -present in the NVA Responses Cache. Responses remain valid for the -default Response Lifetime (@pxref{VNC Defaults Configuration}) or -NVE-group Response Lifetime (@pxref{VNC NVE Group Configuration}.) -When Removal Responses are enabled (@pxref{General VNC Configuration}), -such responses are listed for the Response Lifetime. Specifying -@var{prefix} limits the output to the addresses that fall within -@var{prefix}. - -Response information is provided for each querying NVE, and includes -the response prefix, the prefix-associated registering NVE addresses, -the administrative cost, the provided response lifetime and the time -remaining before the information is to be removed or will become inactive. -@end deffn - -@deffn {Command} {show memory vnc} {} -Print the number of memory items allocated by the NVA. -@end deffn - -@node Example VNC and VNC-GW Configurations -@section Example VNC and VNC-GW Configurations - -@menu -* Mesh NVA Configuration:: -* Mesh NVA and VNC-GW Configuration:: -* VNC with Frr Route Reflector Configuration:: -* VNC with Commercial Route Reflector Configuration:: -* VNC with Redundant Route Reflectors Configuration:: -@c * Interfacing VNC to an IGP:: -@end menu - -@node Mesh NVA Configuration -@subsection Mesh NVA Configuration - -This example includes three NVAs, nine NVEs, and two NVE groups. Note -that while not shown, a single physical device may support multiple -logical NVEs. @ref{fig:fig-vnc-mesh} shows @code{NVA 1} -(192.168.1.100), @code{NVA 2} (192.168.1.101), and @code{NVA 3} -(192.168.1.102), which are connected in a full mesh. Each is a -member of the autonomous system 64512. Each NVA provides VNC -services to three NVE clients in the 172.16.0.0/16 virtual-network -address range. The 172.16.0.0/16 address range is partitioned into -two NVE groups, @code{group1} (172.16.0.0/17) and @code{group2} -(172.16.128.0/17). - -Each NVE belongs to either NVE group @code{group1} or NVE group -@code{group2}. The NVEs @code{NVE 1}, @code{NVE 2}, @code{NVE -4}, @code{NVE 7}, and @code{NVE 8} are members of the NVE group -@code{group1}. The NVEs @code{NVE 3}, @code{NVE 5}, @code{NVE -6}, and @code{NVE 9} are members of the NVE group @code{group2}. - -Each NVA advertises NVE underlay-network IP addresses using the -Tunnel Encapsulation Attribute. - -@float Figure,fig:fig-vnc-mesh -@center @image{fig-vnc-mesh,400pt,,Three-way Mesh} -@caption{A three-way full mesh with three NVEs per NVA} -@end float - -@file{bgpd.conf} for @code{NVA 1} (192.168.1.100) -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.100 - - neighbor 192.168.1.101 remote-as 64512 - neighbor 192.168.1.102 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.101 activate - neighbor 192.168.1.102 activate - exit-address-family - - vnc defaults - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc - - vnc nve-group group1 - prefix vn 172.16.0.0/17 - rt both 1000:1 - exit-vnc - - vnc nve-group group2 - prefix vn 172.16.128.0/17 - rt both 1000:2 - exit-vnc - -exit -@end verbatim - -@file{bgpd.conf} for @code{NVA 2} (192.168.1.101): -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.101 - - neighbor 192.168.1.100 remote-as 64512 - neighbor 192.168.1.102 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - neighbor 192.168.1.102 activate - exit-address-family - - vnc nve-group group1 - prefix vn 172.16.0.0/17 - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc -exit -@end verbatim - -@file{bgpd.conf} for @code{NVA 3} (192.168.1.102): -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.102 - - neighbor 192.168.1.101 remote-as 64512 - neighbor 192.168.1.102 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - neighbor 192.168.1.101 activate - exit-address-family - - vnc defaults - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc - - vnc nve-group group1 - prefix vn 172.16.128.0/17 - exit-vnc -exit -@end verbatim - -@node Mesh NVA and VNC-GW Configuration -@subsection Mesh NVA and VNC-GW Configuration - -This example includes two NVAs, each with two associated NVEs, and two -VNC-GWs, each supporting two CE routers physically attached to the four -NVEs. Note that this example is showing a more complex configuration -where VNC-GW is separated from normal NVA functions; it is equally -possible to simplify the configuration and combine NVA and VNC-GW -functions in a single frr instance. - -@float Figure,fig:fig-vnc-gw -@center @image{fig-vnc-gw,400pt,,Frr VNC Gateway} -@caption{Meshed NVEs and VNC-GWs} -@end float - -As shown in @ref{fig:fig-vnc-gw}, NVAs and VNC-GWs are connected in a -full iBGP mesh. The VNC-GWs each have two CEs configured as -route-reflector clients. Each client provides BGP updates with unicast -routes that the VNC-GW reflects to the other client. The VNC-GW also -imports these unicast routes into VPN routes to be shared with the other -VNC-GW and the two NVAs. This route importation is controlled with the -@code{vnc redistribute} statements shown in the configuration. -Similarly, registrations sent by NVEs via RFP to the NVAs are exported -by the VNC-GWs to the route-reflector clients as unicast routes. RFP -registrations exported this way have a next-hop address of the CE behind -the connected (registering) NVE. Exporting VNC routes as IPv4 unicast -is enabled with the @code{vnc export} command below. - -The configuration for @code{VNC-GW 1} is shown below. -@verbatim -router bgp 64512 - bgp router-id 192.168.1.101 - bgp cluster-id 1.2.3.4 - neighbor 192.168.1.102 remote-as 64512 - neighbor 192.168.1.103 remote-as 64512 - neighbor 192.168.1.104 remote-as 64512 - neighbor 172.16.1.2 remote-as 64512 - neighbor 172.16.2.2 remote-as 64512 - ! - address-family ipv4 unicast - redistribute vnc-direct - no neighbor 192.168.1.102 activate - no neighbor 192.168.1.103 activate - no neighbor 192.168.1.104 activate - neighbor 172.16.1.2 route-reflector-client - neighbor 172.16.2.2 route-reflector-client - exit-address-family - ! - address-family vpnv4 unicast - neighbor 192.168.1.102 activate - neighbor 192.168.1.103 activate - neighbor 192.168.1.104 activate - exit-address-family - vnc export bgp mode ce - vnc redistribute mode resolve-nve - vnc redistribute ipv4 bgp-direct - exit -@end verbatim - -Note that in the VNC-GW configuration, the neighboring VNC-GW and -NVAs each have a statement disabling the IPv4 unicast address family. -IPv4 unicast is on by default and this prevents the other VNC-GW and -NVAs from learning unicast routes advertised by the route-reflector clients. - -Configuration for @code{NVA 2}: -@verbatim -router bgp 64512 - bgp router-id 192.168.1.104 - neighbor 192.168.1.101 remote-as 64512 - neighbor 192.168.1.102 remote-as 64512 - neighbor 192.168.1.103 remote-as 64512 - ! - address-family ipv4 unicast - no neighbor 192.168.1.101 activate - no neighbor 192.168.1.102 activate - no neighbor 192.168.1.103 activate - exit-address-family - ! - address-family vpnv4 unicast - neighbor 192.168.1.101 activate - neighbor 192.168.1.102 activate - neighbor 192.168.1.103 activate - exit-address-family - ! - vnc defaults - response-lifetime 3600 - exit-vnc - vnc nve-group nve1 - prefix vn 172.16.1.1/32 - response-lifetime 3600 - rt both 1000:1 1000:2 - exit-vnc - vnc nve-group nve2 - prefix vn 172.16.2.1/32 - response-lifetime 3600 - rt both 1000:1 1000:2 - exit-vnc - exit -@end verbatim - -@c TBD make this its own example: -@c -@c @float Figure,fig:fig-vnc-gw-rr -@c @center @image{fig-vnc-gw-rr,400pt,,Frr VNC Gateway with RR} -@c @end float -@c An NVA can also import unicast routes from BGP without advertising the -@c imported routes as VPN routes. Such imported routes, while not -@c distributed to other NVAs or VNC-GWs, are are available to NVEs via -@c RFP query messages sent to the NVA. @ref{fig:fig-vnc-gw-rr} -@c shows an example topology where unicast routes are imported into NVAs -@c from a Route Reflector. (@pxref{Route Reflector} for route reflector -@c configuration details.) The following three lines can be added to the -@c @code{NVA 1} and @code{NVA 2} configurations to import routes into VNC -@c for local VNC use: -@c -@c @verbatim -@c neighbor 192.168.1.105 remote-as 64512 -@c vnc redistribute mode plain -@c vnc redistribute ipv4 bgp-direct-to-nve-groups -@c @end verbatim - -@node VNC with Frr Route Reflector Configuration -@subsection VNC with Frr Route Reflector Configuration -A route reflector eliminates the need for a fully meshed NVA -network by acting as the hub between NVAs. -@ref{fig:fig-vnc-frr-route-reflector} shows BGP route reflector -@code{BGP Route Reflector 1} (192.168.1.100) as a route reflector for -NVAs @code{NVA 2}(192.168.1.101) and @code{NVA 3} -(192.168.1.102). - -@float Figure,fig:fig-vnc-frr-route-reflector -@center @image{fig-vnc-frr-route-reflector,400pt,,Frr Route Reflector} -@caption{Two NVAs and a BGP Route Reflector} -@end float - -@code{NVA 2} and @code{NVA 3} -advertise NVE underlay-network IP addresses using the Tunnel Encapsulation Attribute. -@code{BGP Route Reflector 1} ``reflects'' advertisements from -@code{NVA 2} to @code{NVA 3} and vice versa. - -As in the example of @ref{Mesh NVA Configuration}, there are two NVE groups. -The 172.16.0.0/16 address range is partitioned into two NVE groups, -@code{group1} (172.16.0.0/17) and @code{group2} (172.16.128.0/17). -The NVE @code{NVE 4}, @code{NVE 7}, and @code{NVE 8} are -members of the NVE group @code{group1}. The NVEs @code{NVE 5}, -@code{NVE 6}, and @code{NVE 9} are members of the NVE group -@code{group2}. - -@file{bgpd.conf} for @code{BGP Route Reflector 1} on 192.168.1.100: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.100 - - neighbor 192.168.1.101 remote-as 64512 - neighbor 192.168.1.101 port 7179 - neighbor 192.168.1.101 description iBGP-client-192-168-1-101 - - neighbor 192.168.1.102 remote-as 64512 - neighbor 192.168.1.102 port 7179 - neighbor 192.168.1.102 description iBGP-client-192-168-1-102 - - address-family ipv4 unicast - neighbor 192.168.1.101 route-reflector-client - neighbor 192.168.1.102 route-reflector-client - exit-address-family - - address-family vpnv4 - neighbor 192.168.1.101 activate - neighbor 192.168.1.102 activate - - neighbor 192.168.1.101 route-reflector-client - neighbor 192.168.1.102 route-reflector-client - exit-address-family - -exit -@end verbatim - -@file{bgpd.conf} for @code{NVA 2} on 192.168.1.101: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.101 - - neighbor 192.168.1.100 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - exit-address-family - - vnc nve-group group1 - prefix vn 172.16.0.0/17 - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc -exit -@end verbatim - -@file{bgpd.conf} for @code{NVA 2} on 192.168.1.102: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.102 - - neighbor 192.168.1.100 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - exit-address-family - - vnc defaults - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc - - vnc nve-group group1 - prefix vn 172.16.128.0/17 - exit-vnc -exit -@end verbatim - -While not shown, an NVA can also be configured as a route reflector. - -@node VNC with Commercial Route Reflector Configuration -@subsection VNC with Commercial Route Reflector Configuration -This example is identical to @ref{VNC with Frr Route Reflector -Configuration} with the exception that the route reflector is a -commercial router. Only the -VNC-relevant configuration is provided. - -@float Figure,fig:fig-vnc-commercial-route-reflector -@center @image{fig-vnc-commercial-route-reflector,400pt,,Commercial Route Reflector} -@caption{Two NVAs with a commercial route reflector} -@end float - -@file{bgpd.conf} for BGP route reflector @code{Commercial Router} on 192.168.1.104: -@verbatim -version 8.5R1.13; -routing-options { - rib inet.0 { - static { - route 172.16.0.0/16 next-hop 192.168.1.104; - } - } - autonomous-system 64512; - resolution { - rib inet.3 { - resolution-ribs inet.0; - } - rib bgp.l3vpn.0 { - resolution-ribs inet.0; - } - } -} -protocols { - bgp { - advertise-inactive; - family inet { - labeled-unicast; - } - group 1 { - type internal; - advertise-inactive; - advertise-peer-as; - import h; - family inet { - unicast; - } - family inet-vpn { - unicast; - } - cluster 192.168.1.104; - neighbor 192.168.1.101; - neighbor 192.168.1.102; - } - } -} -policy-options { - policy-statement h { - from protocol bgp; - then { - as-path-prepend 64512; - accept; - } - } -} -@end verbatim - -@file{bgpd.conf} for @code{NVA 2} on 192.168.1.101: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.101 - - neighbor 192.168.1.100 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - exit-address-family - - vnc nve-group group1 - prefix vn 172.16.0.0/17 - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc -exit -@end verbatim - -@file{bgpd.conf} for @code{NVA 3} on 192.168.1.102: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.102 - - neighbor 192.168.1.100 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - exit-address-family - - vnc defaults - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc - - vnc nve-group group1 - prefix vn 172.16.128.0/17 - exit-vnc -exit -@end verbatim - -@node VNC with Redundant Route Reflectors Configuration -@subsection VNC with Redundant Route Reflectors Configuration -This example combines the previous two (@ref{VNC with Frr Route -Reflector Configuration} and @ref{VNC with Commercial Route Reflector -Configuration}) into a redundant route reflector configuration. BGP -route reflectors @code{BGP Route Reflector 1} and @code{Commercial Router} -are the route reflectors for NVAs @code{NVA 2} and -@code{NVA 3}. The two NVAs have connections to both -route reflectors. - -@float Figure,fig:fig-vnc-redundant-route-reflectors -@center @image{fig-vnc-redundant-route-reflectors,400pt,,Redundant Route Reflectors} -@caption{Frr-based NVA with redundant route reflectors} -@end float - -@file{bgpd.conf} for @code{Bgpd Route Reflector 1} on 192.168.1.100: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.100 - bgp cluster-id 192.168.1.100 - - neighbor 192.168.1.104 remote-as 64512 - - neighbor 192.168.1.101 remote-as 64512 - neighbor 192.168.1.101 description iBGP-client-192-168-1-101 - neighbor 192.168.1.101 route-reflector-client - - neighbor 192.168.1.102 remote-as 64512 - neighbor 192.168.1.102 description iBGP-client-192-168-1-102 - neighbor 192.168.1.102 route-reflector-client - - address-family vpnv4 - neighbor 192.168.1.101 activate - neighbor 192.168.1.102 activate - neighbor 192.168.1.104 activate - - neighbor 192.168.1.101 route-reflector-client - neighbor 192.168.1.102 route-reflector-client - exit-address-family -exit -@end verbatim - -@file{bgpd.conf} for @code{NVA 2} on 192.168.1.101: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.101 - - neighbor 192.168.1.100 remote-as 64512 - neighbor 192.168.1.104 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - neighbor 192.168.1.104 activate - exit-address-family - - vnc nve-group group1 - prefix vn 172.16.0.0/17 - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc -exit -@end verbatim - -@file{bgpd.conf} for @code{NVA 3} on 192.168.1.102: -@verbatim -router bgp 64512 - - bgp router-id 192.168.1.102 - - neighbor 192.168.1.100 remote-as 64512 - neighbor 192.168.1.104 remote-as 64512 - - address-family vpnv4 - neighbor 192.168.1.100 activate - neighbor 192.168.1.104 activate - exit-address-family - - vnc defaults - rd 64512:1 - response-lifetime 200 - rt both 1000:1 1000:2 - exit-vnc - - vnc nve-group group1 - prefix vn 172.16.128.0/17 - exit-vnc -exit -@end verbatim - -@file{bgpd.conf} for the Commercial Router route reflector on -192.168.1.104: -@verbatim -routing-options { - rib inet.0 { - static { - route 172.16.0.0/16 next-hop 192.168.1.104; - } - } - autonomous-system 64512; - resolution { - rib inet.3 { - resolution-ribs inet.0; - } - rib bgp.l3vpn.0 { - resolution-ribs inet.0; - } - } -} -protocols { - bgp { - advertise-inactive; - family inet { - labeled-unicast; - } - group 1 { - type internal; - advertise-inactive; - advertise-peer-as; - import h; - family inet { - unicast; - } - family inet-vpn { - unicast; - } - cluster 192.168.1.104; - neighbor 192.168.1.101; - neighbor 192.168.1.102; - } - - group 2 { - type internal; - advertise-inactive; - advertise-peer-as; - import h; - family inet { - unicast; - } - family inet-vpn { - unicast; - } - neighbor 192.168.1.100; - } - - } -} -policy-options { - policy-statement h { - from protocol bgp; - then { - as-path-prepend 64512; - accept; - } - } -} -@end verbatim - -@node Release Notes -@section Release Notes - -@c A paragraph that introduces our release notes. - -@c outer list, one item per VNC release, items preceded by bullet -@itemize @bullet -@item - -@c @item -@end itemize - -@evenheading @thispage@|@|@thistitle -@oddheading @thischapter@|@|@thispage -@everyfooting - diff --git a/doc/vtysh.texi b/doc/vtysh.texi deleted file mode 100644 index de681c8013..0000000000 --- a/doc/vtysh.texi +++ /dev/null @@ -1,161 +0,0 @@ -@node VTY shell -@chapter VTY shell - -@menu -* Integrated configuration mode:: -@end menu - -@command{vtysh} provides a combined frontend to all Frr daemons in a -single combined session. It is enabled by default at build time, but can -be disabled through the @option{--disable-vtysh} option to -@command{./configure}. - -@command{vtysh} has a configuration file, @file{vtysh.conf}. The location -of that file cannot be changed from @file{@value{INSTALL_PREFIX_ETC}} since -it contains options controlling authentication behavior. This file will -also not be written by configuration-save commands, it is intended to be -updated manually by an administrator with an external editor. - -@quotation Warning -This also means the @command{hostname} and @command{banner motd} commands -(which both do have effect for vtysh) need to be manually updated in -@file{vtysh.conf}. -@end quotation - -@section Permissions and setup requirements - -@command{vtysh} connects to running daemons through Unix sockets located in -@file{@value{INSTALL_PREFIX_STATE}}. Running vtysh thus requires access to -that directory, plus membership in the @emph{@value{INSTALL_VTY_GROUP}} -group (which is the group that the daemons will change ownership of their -sockets to). - -To restrict access to Frr configuration, make sure no unauthorized users -are members of the @emph{@value{INSTALL_VTY_GROUP}} group. - -@subsection PAM support (experimental) - -vtysh has working (but rather useless) PAM support. It will perform -an "authenticate" PAM call using @emph{@value{PACKAGE_NAME}} as service -name. No other (accounting, session, password change) calls will be -performed by vtysh. - -Users using vtysh still need to have appropriate access to the daemons' -VTY sockets, usually by being member of the @emph{@value{INSTALL_VTY_GROUP}} -group. If they have this membership, PAM support is useless since they can -connect to daemons and issue commands using some other tool. Alternatively, -the @command{vtysh} binary could be made SGID (set group ID) to the -@emph{@value{INSTALL_VTY_GROUP}} group. @strong{No security guarantees are -made for this configuration}. - -@deffn {Command} {username @var{username} nopassword} {} - -If PAM support is enabled at build-time, this command allows disabling the -use of PAM on a per-user basis. If vtysh finds that an user is trying to -use vtysh and a "nopassword" entry is found, no calls to PAM will be made -at all. - -@end deffn - -@node Integrated configuration mode -@section Integrated configuration mode - -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}. - -@file{frr.conf} is located in @file{@value{INSTALL_PREFIX_ETC}}. All -daemons check for the existence of this file at startup, and if it exists -will not load their individual configuration files. Instead, -@command{vtysh -b} must be invoked to process @file{frr.conf} and apply -its settings to the individual daemons. - -@quotation Warning -@command{vtysh -b} must also be executed after restarting any daemon. -@end quotation - -@subsection Configuration saving, file ownership and permissions - -The @file{frr.conf} file is not written by any of the daemons; instead -@command{vtysh} contains the neccessary logic to collect configuration from -all of the daemons, combine it and write it out. - -@quotation Warning -Daemons must be running for @command{vtysh} to be able to collect their -configuration. Any configuration from non-running daemons is permanently -lost after doing a configuration save. -@end quotation - -Since the @command{vtysh} command may be running as ordinary user on the -system, configuration writes will be tried through @command{watchfrr}, -using the @command{write integrated} command internally. Since -@command{watchfrr} is running as superuser, @command{vtysh} is able to -ensure correct ownership and permissions on @file{frr.conf}. - -If @command{watchfrr} is not running or the configuration write fails, -@command{vtysh} will attempt to directly write to the file. This is likely -to fail if running as unprivileged user; alternatively it may leave the -file with incorrect owner or permissions. - -Writing the configuration can be triggered directly by invoking -@command{vtysh -w}. This may be useful for scripting. Note this command -should be run as either the superuser or the Frr user. - -We recommend you do not mix the use of the two types of files. Further, it -is better not to use the integrated frr.conf file, as any syntax error in -it can lead to /all/ of your daemons being unable to start up. Per daemon -files are more robust as impact of errors in configuration are limited to -the daemon in whose file the error is made. - -@deffn {Command} {service integrated-vtysh-config} {} -@deffnx {Command} {no service integrated-vtysh-config} {} - -Control whether integrated @file{frr.conf} file is written when -'write file' is issued. - -These commands need to be placed in @file{vtysh.conf} to have any effect. -Note that since @file{vtysh.conf} is not written by Frr itself, they -therefore need to be manually placed in that file. - -This command has 3 states: -@itemize @bullet -@item -@command{service integrated-vtysh-config} - -@command{vtysh} will always write @file{frr.conf}. - -@item -@command{no service integrated-vtysh-config} - -@command{vtysh} will never write @file{frr.conf}; instead it will ask -daemons to write their individual configuration files. - -@item -Neither option present (default) - -@command{vtysh} will check whether @file{frr.conf} exists. If it does, -configuration writes will update that file. Otherwise, writes are performed -through the individual daemons. -@end itemize - -This command is primarily intended for packaging/distribution purposes, to -preset one of the two operating modes and ensure consistent operation across -installations. -@end deffn - -@deffn {Command} {write integrated} {} - -Unconditionally (regardless of @command{service integrated-vtysh-config} -setting) write out integrated @file{frr.conf} file through -@command{watchfrr}. If @command{watchfrr} is not running, this command -is unavailable. - -@end deffn - -@section Caveats - -Configuration changes made while some daemon is not running will be invisible -to that daemon. The daemon will start up with its saved configuration -(either in its individual configuration file, or in @file{frr.conf}). -This is particularly troublesome for route-maps and prefix lists, which would -otherwise be synchronized between daemons.