From 18352188ed7415ddb3aa7b0d7a2fc16d57a2d5d2 Mon Sep 17 00:00:00 2001
From: Michal 'vorner' Vaner <michal.vaner@nic.cz>
Date: Tue, 19 Sep 2017 17:23:31 +0200
Subject: [PATCH] RAdv: Documentation for more specific routes

---
 doc/bird.sgml | 94 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 83 insertions(+), 11 deletions(-)

diff --git a/doc/bird.sgml b/doc/bird.sgml
index c549e3c3..129e9c08 100644
--- a/doc/bird.sgml
+++ b/doc/bird.sgml
@@ -3336,7 +3336,8 @@ time intervals or as an answer to a request) 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 id="4861"> and also the DNS extensions from <rfc id="6106">.
+in <rfc id="4861">, router preferences and specific routes (<rfc id="4191">),
+and DNS extensions (<rfc id="6106">).
 
 <sect1>Configuration
 <label id="radv-config">
@@ -3373,7 +3374,7 @@ definitions, prefix definitions and DNS definitions:
 	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.
-dsc-iface
+
 	<tag><label id="radv-dnssl">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
@@ -3398,6 +3399,18 @@ dsc-iface
 	default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
 	also be configured as <cf/sensitive/ for a prefix, which would cause
 	autoconfigured IPs to be deprecated or even removed.
+
+	<tag><label id="radv-propagate-routes">propagate routes <m/switch/</tag>
+	This option controls propagation of more specific routes, as defined in
+	<rfc id="4191">. If enabled, all routes exported to the RAdv protocol,
+	with the exception of the trigger prefix, are added to advertisments as
+	additional options. The lifetime and preference of advertised routes can
+	be set individually by <cf/ra_lifetime/ and <cf/ra_preference/ route
+	attributes, or per interface by <cf/route lifetime/ and
+	<cf/route preference/ options. Default: disabled.
+
+	Note that the RFC discourages from sending more than 17 routes and
+	recommends the routes to be configured manually.
 </descrip>
 
 <p>Interface specific options:
@@ -3444,21 +3457,45 @@ dsc-iface
 	hosts. Valid values are 0-255, 0 means unspecified. Default: 64
 
 	<tag><label id="radv-iface-default-lifetime">default lifetime <m/expr/ [sensitive <m/switch/]</tag>
-	This option specifies the time (in seconds) how long (after the receipt
+	This option specifies the time (in seconds) how long (since the receipt
 	of RA) hosts may use the router as a default router. 0 means do not use
 	as a default router. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
 	Default: 3 * <cf/max ra	interval/, <cf/sensitive/ yes.
 
-	<tag><label id="radv-iface-linger-time">linger time <m/expr/</tag>
-	When a prefix disappears, it is advertised for some time with 0
-	lifetime, to inform clients the prefix is no longer usable. This option
-	sets the time for how long it is advertised (in seconds). Maximum is
-	3600, 0 means disabled. Default: 300.
-
-	<tag><label id="radv-iface-default-preference-low">default preference low|medium|high</tag>
+	<tag><label id="radv-iface-default-preference">default preference low|medium|high</tag>
 	This option specifies the Default Router Preference value to advertise
 	to hosts. Default: medium.
 
+	<tag><label id="radv-iface-route-lifetime">route lifetime <m/expr/ [sensitive <m/switch/]</tag>
+	This option specifies the default value of advertised lifetime for
+	specific routes; i.e., the time (in seconds) for how long (since the
+	receipt of RA) hosts should consider these routes valid. A special value
+	0xffffffff represents infinity. The lifetime can be overriden on a per
+	route basis by the <ref id="rta-ra-lifetime" name="ra_lifetime"> route
+	attribute. Default: 3 * <cf/max ra interval/, <cf/sensitive/ no.
+
+	For the <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
+	If <cf/sensitive/ is enabled, even the routes with the <cf/ra_lifetime/
+	attribute become sensitive to the trigger.
+
+	<tag><label id="radv-iface-route-preference">route preference low|medium|high</tag>
+	This option specifies the default value of advertised route preference
+	for specific routes. The value can be overriden on a per route basis by
+	the <ref id="rta-ra-preference" name="ra_preference"> route attribute.
+	Default: medium.
+
+	<tag><label id="radv-prefix-linger-time">prefix linger time <m/expr/</tag>
+	When a prefix or a route disappears, it is advertised for some time with
+	zero lifetime, to inform clients it is no longer valid. This option
+	specifies the time (in seconds) for how long prefixes are advertised
+	that way. Default: 3 * <cf/max ra interval/.
+
+	<tag><label id="radv-route-linger-time">route linger time <m/expr/</tag>
+	When a prefix or a route disappears, it is advertised for some time with
+	zero lifetime, to inform clients it is no longer valid. This option
+	specifies the time (in seconds) for how long routes are advertised
+	that way. Default: 3 * <cf/max ra interval/.
+
 	<tag><label id="radv-iface-rdnss-local">rdnss local <m/switch/</tag>
 	Use only local (interface-specific) RDNSS definitions for this
 	interface. Otherwise, both global and local definitions are used. Could
@@ -3505,7 +3542,6 @@ dsc-iface
 	<cf/sensitive/ no.
 </descrip>
 
-
 <p>RDNSS specific options:
 
 <descrip>
@@ -3538,12 +3574,48 @@ dsc-iface
 	RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/.
 </descrip>
 
+<sect1>Attributes
+<label id="radv-attr">
+
+<p>RAdv defines two route attributes:
+
+<descrip>
+	<tag><label id="rta-ra-preference">enum ra_preference/</tag>
+	The preference of the route. The value can be <it/RA_PREF_LOW/,
+	<it/RA_PREF_MEDIUM/ or <it/RA_PREF_HIGH/. If the attribute is not set,
+	the <ref id="radv-iface-route-preference" name="route preference">
+	option is used.
+
+	<tag><label id="rta-ra-lifetime">int ra_lifetime/</tag>
+	The advertised lifetime of the route, in seconds. The special value of
+	0xffffffff represents infinity. If the attribute is not set, the
+	<ref id="radv-iface-route-lifetime" name="route lifetime">
+	option is used.
+</descrip>
 
 <sect1>Example
 <label id="radv-exam">
 
 <p><code>
+table radv_routes;			# Manually configured routes go here
+
+protocol static {
+	table radv_routes;
+
+	route 2001:0DB8:4000::/48 unreachable;
+	route 2001:0DB8:4010::/48 unreachable;
+
+	route 2001:0DB8:4020::/48 unreachable {
+		ra_preference = RA_PREF_HIGH;
+		ra_lifetime = 3600;
+	};
+}
+
 protocol radv {
+	propagate routes yes;		# Propagate the routes from the radv_routes table
+	table radv_routes;
+	export all;
+
 	interface "eth2" {
 		max ra interval 5;	# Fast failover with more routers
 		managed yes;		# Using DHCPv6 on eth2