Merge branch 'master' of ssh://git.nic.cz/birdv1.3.8

1 files changed, 136 insertions, 18 deletions

diff --git a/doc/bird.sgml b/doc/bird.sgml
index b43eb263..24bc3026 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
@@ -454,7 +477,7 @@ to zero to disable it. An empty <cf><m/switch/</cf> is equivalent to <cf/on/
 	problems in details of its behavior -- the number of exported
 	routes can temporarily exceed the limit without triggering it
 	during protocol reload, exported routes counter ignores route
-	blocking and block action also blocks route updates of alread
+	blocking and block action also blocks route updates of already
 	accepted routes -- and these details will probably change in
 	the future. Default: <cf/none/.
 
@@ -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.
@@ -2321,22 +2358,25 @@ advertisement packets to connected networks. These packets contain
 basic information about a local network (e.g. a list of network
 prefixes), which allows network hosts to autoconfigure network
 addresses and choose a default route. BIRD implements router behavior
-as defined in RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">.
+as defined in
+RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">
+and also the DNS extensions from
+RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">.
 
 <sect1>Configuration
 
-<p>There are two classes of definitions in RAdv configuration --
-interface definitions and prefix definitions:
+<p>There are several classes of definitions in RAdv configuration --
+interface definitions, prefix definitions and DNS definitions:
 
 <descrip>
-	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag> 
+	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag>
 	Interface definitions specify a set of interfaces on which the
 	protocol is activated and contain interface specific options.
 	See <ref id="dsc-iface" name="interface"> common options for
 	detailed description.
 
-	<tag>prefix <m/prefix/ { <m/options/ }</tag> 
-	Prefix definitions allows to modify a list of advertised
+	<tag>prefix <m/prefix/ { <m/options/ }</tag>
+	Prefix definitions allow to modify a list of advertised
 	prefixes. By default, the advertised prefixes are the same as
 	the network prefixes assigned to the interface. For each
 	network prefix, the matching prefix definition is found and
@@ -2350,6 +2390,24 @@ interface definitions and prefix definitions:
 	definitions. As expected, the prefix definition is matching if
 	the network prefix is a subnet of the prefix in prefix
 	definition.
+
+	<tag>rdnss { <m/options/ }</tag>
+	RDNSS definitions allow to specify a list of advertised
+	recursive DNS servers together with their options. As options
+	are seldom necessary, there is also a short variant <cf>rdnss
+	<m/address/</cf> that just specifies one DNS server. Multiple
+	definitions are cumulative. RDNSS definitions may also be
+	interface-specific when used inside interface options. By
+	default, interface uses both global and interface-specific
+	options, but that can be changed by <cf/rdnss local/ option.
+
+	<tag>dnssl { <m/options/ }</tag>
+	DNSSL definitions allow to specify a list of advertised DNS
+	search domains together with their options. Like <cf/rdnss/
+	above, multiple definitions are cumulative, they can be used
+	also as interface-specific options and there is a short
+	variant <cf>dnssl <m/domain/</cf> that just specifies one DNS
+        search domain.
 </descrip>
 
 <p>Interface specific options:
@@ -2362,8 +2420,8 @@ interface definitions and prefix definitions:
 
 	<tag>min ra interval <m/expr/</tag>
 	This option specifies the minimum length of that intervals, in
-	seconds. Must be at least 3 and at most 3/4 * max ra interval.
-	Default: about 1/3 * max ra interval.
+	seconds. Must be at least 3 and at most 3/4 * <cf/max ra interval/.
+	Default: about 1/3 * <cf/max ra interval/.
 
 	<tag>min delay <m/expr/</tag>
 	The minimum delay between two consecutive router advertisements,
@@ -2400,7 +2458,17 @@ interface definitions and prefix definitions:
 	This option specifies the time (in seconds) how long (after
 	the receipt of RA) hosts may use the router as a default
 	router. 0 means do not use as a default router. Default: 3 *
-	max ra interval.
+	<cf/max ra interval/.
+
+	<tag>rdnss local <m/bool/</tag>
+	Use only local (interface-specific) RDNSS definitions for this
+	interface. Otherwise, both global and local definitions are
+	used. Could also be used to disable RDNSS for given interface
+	if no local definitons are specified. Default: no.
+
+	<tag>dnssl local <m/bool/</tag>
+	Use only local DNSSL definitions for this interface. See
+	<cf/rdnss local/ option above. Default: no.
 </descrip>
 
 
@@ -2429,6 +2497,42 @@ interface definitions and prefix definitions:
 	14400 (4 hours)
 </descrip>
 
+
+<p>RDNSS specific options:
+
+<descrip>
+	<tag>ns <m/address/</tag>
+	This option specifies one recursive DNS server. Can be used
+	multiple times for multiple servers. It is mandatory to have
+	at least one <cf/ns/ option in <cf/rdnss/ definition.
+
+	<tag>lifetime [mult] <m/expr/</tag>
+	This option specifies the time how long the RDNSS information
+        may be used by clients after the receipt of RA. It is
+        expressed either in seconds or (when <cf/mult/ is used) in
+        multiples of <cf/max ra interval/. Note that RDNSS information
+        is also invalidated when <cf/default lifetime/ expires. 0
+        means these addresses are no longer valid DNS servers.
+	Default: 3 * <cf/max ra interval/.
+</descrip>
+
+
+<p>DNSSL specific options:
+
+<descrip>
+	<tag>domain <m/address/</tag>
+	This option specifies one DNS search domain. Can be used
+	multiple times for multiple domains. It is mandatory to have
+	at least one <cf/domain/ option in <cf/dnssl/ definition.
+
+	<tag>lifetime [mult] <m/expr/</tag>
+	This option specifies the time how long the DNSSL information
+        may be used by clients after the receipt of RA. Details are
+	the same as for RDNSS <cf/lifetime/ option above.
+	Default: 3 * <cf/max ra interval/.
+</descrip>
+
+
 <sect1>Example
 
 <p><code>
@@ -2450,6 +2554,20 @@ protocol radv {
 	prefix 2001:0DB8:2000::/48 {
 		autonomous off;		# Do not autoconfigure
 	};
+
+	rdnss 2001:0DB8:1234::10;	# Short form of RDNSS
+
+	rdnss {
+		lifetime mult 10;
+		ns 2001:0DB8:1234::11;
+		ns 2001:0DB8:1234::12;
+	};
+
+	dnssl {
+		lifetime 3600;
+		domain "abc.com";
+		domain "xyz.com";
+	};
 }
 </code>