From: Ondrej Zajicek <santiago@crfreenet.org>
Date: Tue, 24 Jul 2012 18:12:14 +0000 (+0200)
Subject: Documentation update,
X-Git-Tag: v1.3.8^2~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=48cf5e84e6ed17578e4ad43c5ef54d6ff7d825c4;p=thirdparty%2Fbird.git

Documentation update,
---

diff --git a/doc/bird.sgml b/doc/bird.sgml
index 3f2e46e7b..86ae5b0d0 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -215,7 +215,27 @@ an <it/import/ filter checks routes in the opposite direction.
 When the routing table gets a route from a protocol, it recalculates
 the selected route and broadcasts it to all protocols connected to
 the table. The protocols typically send the update to other routers
-in the network.
+in the network. Note that although most protocols are interested 
+in receiving just selected routes, some protocols (e.g. the <cf/Pipe/
+protocol) receive and process all entries in routing tables (accepted
+by filters).
+
+<p><label id="dsc-sorted">Usually, a routing table just chooses a
+selected route from a list of entries for one network. But if the
+<cf/sorted/ option is activated, these lists of entries are kept
+completely sorted (according to preference or some protocol-dependent
+metric).
+
+This is needed for some features of some protocols
+(e.g. <cf/secondary/ option of BGP protocol, which allows to accept
+not just a selected route, but the first route (in the sorted list)
+that is accepted by filters), but it is incompatible with some other
+features (e.g. <cf/deterministic med/ option of BGP protocol, which
+activates a way of choosing selected route that cannot be described
+using comparison and ordering). Minor advantage is that routes are
+shown sorted in <cf/show route/, minor disadvantage is that it is
+slightly more computationally expensive.
+
 
 <chapt>Configuration
 
@@ -354,11 +374,14 @@ protocol rip {
 	defaults are here for a compatibility with older versions
 	and might change in the future.
 
-	<tag>table <m/name/</tag> Create a new routing table. The default
-	routing table is created implicitly, other routing tables have
-	to be added by this command.
+	<tag>table <m/name/ [sorted]</tag>
+	Create a new routing table. The default routing table is
+	created implicitly, other routing tables have to be added by
+	this command. Option <cf/sorted/ can be used to enable
+	sorting of routes, see <ref id="dsc-sorted" name="sorted table">
+	description for details.
 
-	<tag>roa table [ { roa table options ... } ] <m/name/</tag>
+	<tag>roa table <m/name/ [ { roa table options ... } ]</tag>
 	Create a new ROA (Route Origin Authorization) table. ROA
 	tables can be used to validate route origination of BGP
 	routes. A ROA table contains ROA entries, each consist of a
@@ -1270,8 +1293,10 @@ for each neighbor using the following configuration parameters:
 	mode is the behavior specified by the BGP standard. Direct
 	mode is simpler, does not require any routes in a routing
 	table, and was used in older versions of BIRD, but does not
-	handle well nontrivial iBGP setups and multihop. Default:
-	<cf/direct/ for singlehop eBGP, <cf/recursive/ otherwise.
+	handle well nontrivial iBGP setups and multihop.  Recursive
+	mode is incompatible with <ref id="dsc-sorted" name="sorted
+	tables">. Default: <cf/direct/ for singlehop eBGP,
+	<cf/recursive/ otherwise.
 
 	<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
@@ -1317,6 +1342,16 @@ for each neighbor using the following configuration parameters:
 	attributes to be transparent (for example does not prepend its AS number to
 	AS PATH attribute and keeps MED attribute). Default: disabled.
 
+	<tag>secondary <m/switch/</tag> Usually, if an import filter
+	rejects a selected route, no other route is propagated for
+	that network. This option allows to try the next route in
+	order until one that is accepted is found or all routes for
+	that network are rejected. This can be used for route servers
+	that need to propagate different tables to each client but do
+	not want to have these tables explicitly (to conserve memory).
+	This option requires that the connected routing table is
+	<ref id="dsc-sorted" name="sorted">. Default: off.
+
 	<tag>enable route refresh <m/switch/</tag> When BGP speaker
 	changes its import filter, it has to re-examine all routes
 	received from its neighbor against the new filter. As these
@@ -1422,7 +1457,9 @@ for each neighbor using the following configuration parameters:
 	This option enables a different (and slower) algorithm
 	implementing proper RFC 4271 route selection, which is
 	deterministic. Alternative way how to get deterministic
-	behavior is to use <cf/med metric/ option. Default: off.
+	behavior is to use <cf/med metric/ option. This option is
+	incompatible with <ref id="dsc-sorted" name="sorted tables">.
+	Default: off.
 
 	<tag>igp metric <m/switch/</tag> Enable comparison of internal
  	distances to boundary routers during best route selection. Default: on.