From 1ec522538fb81a56b068c087d0a842faf7aa7869 Mon Sep 17 00:00:00 2001
From: Ondrej Zajicek <santiago@crfreenet.org>
Date: Tue, 19 Nov 2013 22:33:48 +0100
Subject: BFD protocol, ready for release.

Supports OSPF and BGP and also statically configured sessions.
---
 doc/bird.sgml | 195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 192 insertions(+), 3 deletions(-)

(limited to 'doc/bird.sgml')

diff --git a/doc/bird.sgml b/doc/bird.sgml
index 3cd80c32..3bc0e453 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -1244,6 +1244,178 @@ undefined value is regarded as empty clist for most purposes.
 
 <chapt>Protocols
 
+<sect><label id="sect-bfd">BFD
+
+<sect1>Introduction
+
+<p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
+is an independent tool providing liveness and failure detection. Routing
+protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
+liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
+seconds by default in OSPF, could be set down to several seconds). BFD offers
+universal, fast and low-overhead mechanism for failure detection, which could be
+attached to any routing protocol in an advisory role.
+
+<p>BFD consists of mostly independent BFD sessions. Each session monitors an
+unicast bidirectional path between two BFD-enabled routers. This is done by
+periodically sending control packets in both directions. BFD does not handle
+neighbor discovery, BFD sessions are created on demand by request of other
+protocols (like OSPF or BGP), which supply appropriate information like IP
+addresses and associated interfaces. When a session changes its state, these
+protocols are notified and act accordingly (e.g. break an OSPF adjacency when
+the BFD session went down).
+
+<p>BIRD implements basic BFD behavior as defined in
+RFC 5880<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5880.txt">
+(some advanced features like the echo mode or authentication are not implemented),
+IP transport for BFD as defined in
+RFC 5881<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5881.txt"> and
+RFC 5883<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5883.txt">
+and interaction with client protocols as defined in
+RFC 5882<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5882.txt">.
+
+<p>Note that BFD implementation in BIRD is currently a new feature in
+development, expect some rough edges and possible UI and configuration changes
+in the future. Also note that we currently support at most one protocol instance.
+
+<sect1>Configuration
+
+<p>BFD configuration consists mainly of multiple definitions of interfaces.
+Most BFD config options are session specific. When a new session is requested
+and dynamically created, it is configured from one of these definitions. For
+sessions to directly connected neighbors, <cf/interface/ definitions are chosen
+based on the interface associated with the session, while <cf/multihop/
+definition is used for multihop sessions. If no definition is relevant, the
+session is just created with the default configuration. Therefore, an empty BFD
+configuration is often sufficient.
+
+<p>Note that to use BFD for other protocols like OSPF or BGP, these protocols
+also have to be configured to request BFD sessions, usually by <cf/bfd/ option.
+
+<p>Some of BFD session options require <m/time/ value, which has to be specified
+with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds
+are allowed as units, practical minimum values are usually in order of tens of
+milliseconds.
+
+<code>
+protocol bfd [&lt;name&gt;] {
+	interface &lt;interface pattern&gt; {
+		interval &lt;time&gt;;
+		min rx interval &lt;time&gt;;
+		min tx interval &lt;time&gt;;
+		idle tx interval &lt;time&gt;;
+		multiplier &lt;num&gt;;
+		passive &lt;switch&gt;;
+	};
+	multihop {
+		interval &lt;time&gt;;
+		min rx interval &lt;time&gt;;
+		min tx interval &lt;time&gt;;
+		idle tx interval &lt;time&gt;;
+		multiplier &lt;num&gt;;
+		passive &lt;switch&gt;;
+	};
+	neighbor &lt;ip&gt; [dev "&lt;interface&gt;"] [local &lt;ip&gt;] [multihop &lt;switch&gt;];
+}
+</code>
+
+<descrip>
+	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag>
+	Interface definitions allow to specify options for sessions associated
+	with such interfaces and also may contain interface specific options.
+	See <ref id="dsc-iface" name="interface"> common option for a detailed
+	description of interface patterns. Note that contrary to the behavior of
+	<cf/interface/ definitions of other protocols, BFD protocol would accept
+	sessions (in default configuration) even on interfaces not covered by
+	such definitions.
+
+	<tag>multihop { <m/options/ }</tag>
+	Multihop definitions allow to specify options for multihop BFD sessions,
+	in the same manner as <cf/interface/ definitions are used for directly
+	connected sessions. Currently only one such definition (for all multihop
+	sessions) could be used.
+
+	<tag>neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>
+	BFD sessions are usually created on demand as requested by other
+	protocols (like OSPF or BGP). This option allows to explicitly add
+	a BFD session to the specified neighbor regardless of such requests.
+	
+	The session is identified by the IP address of the neighbor, with
+	optional specification of used interface and local IP.  By default
+	the neighbor must be directly connected, unless the the session is
+	configured as multihop. Note that local IP must be specified for
+	multihop sessions.
+</descrip>
+
+<p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):
+
+<descrip>
+	<tag>interval <m/time/</tag>
+	BFD ensures availability of the forwarding path associated with the
+	session by periodically sending BFD control packets in both
+	directions. The rate of such packets is controlled by two options,
+	<cf/min rx interval/ and <cf/min tx interval/ (see below). This option
+	is just a shorthand to set both of these options together.
+
+	<tag>min rx interval <m/time/</tag>
+	This option specifies the minimum RX interval, which is announced to the
+	neighbor and used there to limit the neighbor's rate of generated BFD
+	control packets. Default: 10 ms.
+
+	<tag>min tx interval <m/time/</tag>
+	This option specifies the desired TX interval, which controls the rate
+	of generated BFD control packets (together with <cf/min rx interval/
+	announced by the neighbor). Note that this value is used only if the BFD
+	session is up, otherwise the value of <cf/idle tx interval/ is used
+	instead. Default: 100 ms.
+
+	<tag>idle tx interval <m/time/</tag>
+	In order to limit unnecessary traffic in cases where a neighbor is not
+	available or not running BFD, the rate of generated BFD control packets
+	is lower when the BFD session is not up. This option specifies the
+	desired TX interval in such cases instead of <cf/min tx interval/.
+	Default: 1 s.
+
+	<tag>multiplier <m/num/</tag>
+	Failure detection time for BFD sessions is based on established rate of
+	BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this
+	multiplier, which is essentially (ignoring jitter) a number of missed
+	packets after which the session is declared down. Note that rates and
+	multipliers could be different in each direction of a BFD session.
+	Default: 5.
+
+	<tag>passive <m/switch/</tag>
+	Generally, both BFD session endpoinds try to establish the session by
+	sending control packets to the other side. This option allows to enable
+	passive mode, which means that the router does not send BFD packets
+	until it has received one from the other side. Default: disabled.
+</descrip>
+
+<sect1>Example
+
+<p><code>
+protocol bfd {
+	interface "eth*" {
+		min rx interval 20 ms;
+		min tx interval 50 ms;
+		idle tx interval 300 ms;
+	};
+	interface "gre*" {
+		interval 200 ms;
+		multiplier 10;
+		passive;
+	};
+	multihop {
+		interval 200 ms;
+		multiplier 10;
+	};
+
+	neighbor 192.168.1.10;
+	neighbor 192.168.2.2 dev "eth2";
+	neighbor 192.168.10.1 local 192.168.1.1 multihop;
+}
+</code>
+
 <sect>BGP
 
 <p>The Border Gateway Protocol is the routing protocol used for backbone
@@ -1258,8 +1430,8 @@ AS). Each AS is a part of the network with common management and
 common routing policy. It is identified by a unique 16-bit number
 (ASN).  Routers within each AS usually exchange AS-internal routing
 information with each other using an interior gateway protocol (IGP,
-such as OSPF or RIP). Boundary routers at the border of
-the AS communicate global (inter-AS) network reachability information with
+such as OSPF or RIP). Boundary routers at the border of the AS
+communicate global (inter-AS) network reachability information with
 their neighbors in the neighboring AS'es via exterior BGP (eBGP) and
 redistribute received information to other routers in the AS via
 interior BGP (iBGP).
@@ -1412,7 +1584,15 @@ for each neighbor using the following configuration parameters:
 	<tag>igp table <m/name/</tag> Specifies a table that is used
 	as an IGP routing table. Default: the same as the table BGP is
 	connected to.
-	
+
+	<tag>bfd <M>switch</M></tag>
+	BGP could use BFD protocol as an advisory mechanism for neighbor
+	liveness and failure detection. If enabled, BIRD setups a BFD session
+	for the BGP neighbor and tracks its liveness by it. This has an
+	advantage of an order of magnitude lower detection times in case of
+	failure. Note that BFD protocol also has to be configured, see
+	<ref id="sect-bfd" name="BFD"> section for details. Default: disabled.
+
 	<tag>ttl security <m/switch/</tag> Use GTSM (RFC 5082 - the
 	generalized TTL security mechanism). GTSM protects against
 	spoofed packets by ignoring received packets with a smaller
@@ -1986,6 +2166,7 @@ protocol ospf &lt;name&gt; {
 			real broadcast &lt;switch&gt;;
 			ptp netmask &lt;switch&gt;;
 			check link &lt;switch&gt;;
+			bfd &lt;switch&gt;;
 			ecmp weight &lt;num&gt;;
 			ttl security [&lt;switch&gt;; | tx only]
 			tx class|dscp &lt;num&gt;;
@@ -2260,6 +2441,14 @@ protocol ospf &lt;name&gt; {
 	 prefix) is propagated. It is possible that some hardware
 	 drivers or platforms do not implement this feature. Default value is no.
 
+	<tag>bfd <M>switch</M></tag>
+	OSPF could use BFD protocol as an advisory mechanism for neighbor
+	liveness and failure detection. If enabled, BIRD setups a BFD session
+	for each OSPF neighbor and tracks its liveness by it. This has an
+	advantage of an order of magnitude lower detection times in case of
+	failure. Note that BFD protocol also has to be configured, see
+	<ref id="sect-bfd" name="BFD"> section for details. Default value is no.
+
 	<tag>ttl security [<m/switch/ | tx only]</tag>
 	 TTL security is a feature that protects routing protocols
 	 from remote spoofed packets by using TTL 255 instead of TTL 1
-- 
cgit v1.2.3