Documentation update,

diff --git a/doc/bird.sgml b/doc/bird.sgml
index 3f2e46e7bad4560b38503e5631d7957650948e76..86ae5b0d0e197f3e136ddf7f79158784c15c5045 100644 (file)
--- 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.