RAdv: Documentation for more specific routes

diff --git a/doc/bird.sgml b/doc/bird.sgml
index c549e3c3db2ef43845bf5617f365924cfe675b80..129e9c083ac30a2e68a7716266ea312fe4ba6554 100644 (file)
--- 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