From 48cf5e84e6ed17578e4ad43c5ef54d6ff7d825c4 Mon Sep 17 00:00:00 2001
From: Ondrej Zajicek <santiago@crfreenet.org>
Date: Tue, 24 Jul 2012 20:12:14 +0200
Subject: [PATCH] Documentation update,

---
 doc/bird.sgml | 53 +++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 45 insertions(+), 8 deletions(-)

diff --git a/doc/bird.sgml b/doc/bird.sgml
index 3f2e46e7..86ae5b0d 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.