Added BGP documentation.

1 files changed, 155 insertions, 6 deletions

diff --git a/doc/bird.sgml b/doc/bird.sgml
index a366957..4cfcd33 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -61,7 +61,7 @@ and Zebra <HTMLURL URL="http://www.zebra.org">), but their capabilities are very
 they are very hard to configure and maintain.
 
 <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
-to support all the routing technology used in today's Internet or planned to be
+to support all the routing technology used in the today's Internet or planned to be
 used in near future and to have a clean extensible architecture allowing new routing
 protocols to be incorporated easily. Among other features, BIRD supports:
 
@@ -454,7 +454,7 @@ if 1234 = i then printn "."; else { print "*** FAIL: if 1 else"; }
 <sect1>BGP
 
 <p>The Border Gateway Protocol is the routing protocol used for backbone
-level routing in today's Internet. Contrary to other protocols, its convergence
+level routing in the today's Internet. Contrary to other protocols, its convergence
 doesn't rely on all routers following the same rules for route selection,
 making it possible to implement any routing policy at any router in the
 network, the only restriction being that if a router advertises a route,
@@ -472,16 +472,165 @@ routing table it wishes to export along with complete path information
 (a list of AS'es the packet will travel through if it uses that particular
 route) in order to avoid routing loops.
 
-<p>In BIRD, each instance of BGP corresponds to one neighboring router.
-This allows to set routing policy and all other parameters differently
-for each neighbor.
+<p>BIRD supports all requirements of the BGP4 standard as defined in
+RFC 1771<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1771.txt">
+including several enhancements from the
+latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-09.txt">.
+It also supports the community attributes as per
+RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">,
+capability negotiation draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-cap-neg-06.txt">.
+For IPv6, it uses the standard multiprotocol extensions defined in
+RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
+including changes described in the
+latest draft <htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
+and applied to IPv6 according to
+RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
+
+<sect2>Route selection rules
+
+<p>BGP doesn't have any simple metric, so the rules for selection of an optimal
+route among multiple BGP routes with the same preference are a bit more complex
+and are implemented according to the following algorithm. First it uses the first
+rule, if there are more "best" routes, then it uses the second rule to choose
+among them and so on.
+
+<itemize>
+	<item>Prefer route with the highest local preference attribute.
+	<item>Prefer route with the shortest AS path.
+	<item>Prefer IGP origin over EGP and EGP over incomplete.
+	<item>Prefer the lowest value of the Multiple Exit Discriminator.
+	<item>Prefer internal routes over external routes.
+	<item>Prefer route with the lowest value of router ID of the
+	advertising router.
+</itemize>
 
 <sect2>Configuration
 
+<p>Each instance of the BGP corresponds to one neighboring router.
+This allows to set routing policy and all other parameters differently
+for each neighbor using the following protocol parameters:
+
+<descrip>
+	<tag>local as <m/number/</tag> Define which AS we are part of. (Note that
+	contrary to other IP routers, BIRD is able to act as a router located
+	in multiple AS'es simultaneously, but in such cases you need to tweak
+	the BGP paths manually in the filters to get consistent behavior.)
+	This parameter is mandatory.
+	<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router
+	this instance will be talking to and what AS it's located in. Unless
+	you use the <cf/multihop/ clause, it must be directly connected to one
+	of your router's interfaces. This parameter is mandatory.
+	<tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
+	neighbor which is connected at most <m/number/ hops far and to which
+	we should route via our direct neighbor with address <m/ip/.
+	Default: switched off.
+	<tag>next hop self</tag> Avoid calculation of the Next Hop attribute
+	and always advertise our own source address (see below) as a next hop.
+	This needs to be used only
+	occasionally to circumvent misconfigurations of other routers.
+	Default: disabled.
+	<tag>source address <m/ip/</tag> Define local address we should use
+	for next hop calculation. Default: the address of the local end
+	of the interface our neighbor is connected to.
+	<tag>disable after error <m/switch/</tag> When an error is encountered (either
+	locally or by the other side), disable the instance automatically
+	and wait for an administrator to solve the problem manually. Default: off.
+	<tag>hold time <m/number/</tag> Time in seconds to wait for a keepalive
+	message from the other side before considering the connection stale.
+	Default: depends on agreement with the neighboring router, we prefer
+	240 seconds if the other side is willing to accept it.
+	<tag>startup hold time <m/number/</tag> Value of the hold timer used
+	before the routers have a chance to exchange OPEN messages and agree
+	on the real value. Default: 240 seconds.
+	<tag>keepalive time <m/number/</tag> Delay in seconds between sending
+	of two consecutive keepalive messages. Default: One third of the hold time.
+	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
+	retrying a failed connect attempt. Default: 120 seconds.
+	<tag>start delay time <m/number/</tag> Delay in seconds between protocol
+	startup and first attempt to connect. Default: 5 seconds.
+	<tag>error wait time <m/number/, <m/number/</tag> Minimum and maximum delay in seconds between protocol
+	failure (either local or reported by the peer) and automatic startup.
+	Doesn't apply when <cf/disable after error/ is configured. If consecutive
+	errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300.
+	<tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol
+	failures to treat them as a error sequence which makes the <cf/error wait time/
+	increase exponentially. Default: 300 seconds.
+	<tag>path metric <m/switch/</tag> Enable comparison of path lengths
+	when deciding which BGP route is the best one. Default: on.
+	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
+	Discriminator to be used during route selection when the MED attribute
+	is missing. Default: infinite.
+	<tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference
+	to be used during route selection when the Local Preference attribute
+	is missing. Default: 0.
+</descrip>
+
 <sect2>Attributes
 
+<p>BGP defines several route attributes. Some of them (those marked with `I' in the
+table below) are available on internal BGP connections only, some of them (marked
+with `O') are optional.
+
+<descrip>
+	<tag>path <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
+	the packet will travel through when forwarded according to this route. On
+	internal BGP connections it doesn't contain the number of the local AS.
+	<tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for
+	selection among multiple BGP routes (see the selection rules above). It's
+	used as an additional metric which is propagated through the whole local AS.
+	<tag>int <cf/bgp_med/ [IO]</tag> The Multiple Exit Discriminator of the route
+	which is an optional attribute which is often used within the local AS to
+	reflect interior distances to various boundary routers. See the route selection
+	rules above for exact semantics.
+	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
+	if the route has originated in interior routing protocol of an AS or
+	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
+	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
+	is unknown.
+	<tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets
+	to this destination. On internal BGP connections, it's an address of the
+	originating router if it's inside the local AS or a boundary router the
+	packet will leave the AS through if it's an exterior route, so each BGP
+	speaker within the AS has a chance to use the shortest interior path
+	possible to this point.
+	<tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute
+	which carries no value, but which sole presence indicates that the route
+	has been aggregated from multiple routes by some AS on the path from
+	the originator.
+<!-- we don't handle aggregators right since they are of a very obscure type
+	<tag>bgp_aggregator</tag>
+-->
+	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
+	with the route. Each such value is a pair (represented as a <cf/pair/ data
+	type inside the filters) of 16-bit integers, the first of them containing a number of the AS which defines
+	the community and the second one is a per-AS identifier. There are lots
+	of uses of the community mechanism, but generally they are used to carry
+	policy information like "don't export to USA peers". As each AS can define
+	its own routing policy, it's also has a complete freedom about which community
+	attributes it defines and what their semantics will be.
+</descrip>
+
 <sect2>Example
 
+<p><code>
+protocol bgp {
+	local as 65000;				# Use a private AS number
+	neighbor 62.168.0.130 as 5588;		# Our neighbor
+	multihop 20 via 62.168.0.13;		# Which is connected indirectly
+	export filter {				# We use non-trivial export rules
+		if source = RTS_STATIC then {	# Export only static routes
+			bgp_community.add((65000,5678));  # Assign our community
+			if bgp_path ~ / 65000 / then	  # Artificially increase path length
+				bgp_path.prepend(65000);  # by prepending local AS number twice
+			accept;
+		}
+		reject;
+	};
+	import all;
+	source address 62.168.0.1;		# Use non-standard source address
+}
+</code>
+
 <sect1>Device
 
 <p>The Device protocol is not a real routing protocol as it doesn't generate
@@ -492,7 +641,7 @@ interfaces from the kernel.
 this protocol in the configuration since almost all other protocol
 require network interfaces to be defined in order to work.
 
-<p>Only configurable thing is interface scan time:
+<p>The only configurable thing is interface scan time:
 
 <p><descrip>
 	<tag>scan time <m/number/</tag> Time in seconds between two scans