From cf3e3845c205dacf2720cdb76a9a004a816d2e6f Mon Sep 17 00:00:00 2001 From: "Ondrej Zajicek (work)" Date: Sun, 10 Dec 2017 22:47:38 +0100 Subject: [PATCH] Doc: Documentation update --- doc/bird.sgml | 339 +++++++++++++++++++++++----------------------- sysdep/unix/krt.h | 2 +- 2 files changed, 167 insertions(+), 174 deletions(-) diff --git a/doc/bird.sgml b/doc/bird.sgml index 3ec6612a..8309e051 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -91,6 +91,7 @@ supports: the Border Gateway Protocol (BGPv4) the Routing Information Protocol (RIPv2, RIPng) the Open Shortest Path First protocol (OSPFv2, OSPFv3) + the Babel Routing Protocol the Router Advertisements for IPv6 hosts a virtual protocol for exchange of routes between different routing tables on a single host @@ -228,17 +229,17 @@ default tables -- -These routing tables are not kernel forwarding tables. No forwarding is done in BIRD. -If you want to forward packets using the routes in BIRD's tables, you may -use the Kernel protocol (see below) to synchronize them with kernel's FIBs. +These routing tables are not kernel forwarding tables. No forwarding is done by +BIRD. If you want to forward packets using the routes in BIRD tables, you may +use the Kernel protocol (see below) to synchronize them with kernel FIBs.

-Every nettype defines a (kind of) primary key on routes. Every route source -can supply one route for every possible primary key; new route announcement -replaces the old route from the same source, keeping other routes intact. -BIRD always chooses the best route for every primary key among the known -routes and keeps the others as suboptimal. When the best route is retracted, -BIRD re-runs the best route selection algorithm to find the current best route. +Every nettype defines a (kind of) primary key on routes. Every route source can +supply one route for every possible primary key; new route announcement replaces +the old route from the same source, keeping other routes intact. BIRD always +chooses the best route for each primary key among the known routes and keeps the +others as suboptimal. When the best route is retracted, BIRD re-runs the best +route selection algorithm to find the current best route.

The global best route selection algorithm is (roughly) as follows: @@ -246,12 +247,12 @@ The global best route selection algorithm is (roughly) as follows: Preferences of the routes are compared. Source protocol instance preferences are compared. - If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined. If source protocols are the same (e.g. BGP vs. BGP), the protocol's route selection algorithm is invoked. + If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined. -

Every route consists of several attributes (read more about them in the section); the common for all routes are: +

Every route consists of several attributes (read more about them in the + section); the common for all +routes are: IP address of router which told us about this route @@ -281,7 +284,7 @@ regardless on this difference.

Other attributes depend on nettypes. Some of them are part of the primary key, these are marked (PK). IPv4 and IPv6 routes -

The traditional routes. Configuration keywords are VPN IPv4 and IPv6 routes -

Routes for IPv4 and IPv6 with VPN Route Distinguisher (). Configuration keywords are Route Origin Authorization for IPv4 and IPv6 -

These entries can be used to validate route origination of BGP routes. -An ROA entry specifies prefixes which could be originated by an AS number. +A ROA entry specifies prefixes which could be originated by an AS number. Their keywords are @@ -316,7 +319,7 @@ Their keywords are Flowspec for IPv4 and IPv6 -

Flowspec rules are a form of firewall and traffic flow control rules distributed mostly via BGP. These rules may help the operators stop various @@ -357,12 +360,12 @@ In that case, every next hop has also its weight. Protocols and channels

BIRD's protocol is an abstract class of producers and consumers of the routes. +

BIRD protocol is an abstract class of producers and consumers of the routes. Each protocol may run in multiple instances and bind on one side to route tables via channels, on the other side to specified listen sockets (BGP), interfaces (Babel, OSPF, RIP), APIs (Kernel, Direct), or nothing (Static, Pipe). -

There are also two protocols which do not have any channels -- BFD and Device. +

There are also two protocols that do not have any channels -- BFD and Device. Both of them are kind of service for other protocols.

Each protocol is connected to a routing table through a channel. Some protocols @@ -439,12 +442,14 @@ protocol rip {

+ Protocol options

There are several options that give sense only with certain protocols: @@ -693,7 +681,7 @@ agreement"). options, in that case for given interface the first matching interface option is used. - This option is allowed in Babel, BFD, Direct, OSPF, RAdv and RIP + This option is allowed in Babel, BFD, Device, Direct, OSPF, RAdv and RIP protocols. In OSPF protocol it is used in the + Channel options

Every channel belongs to a protocol and is configured inside its block. The -minimal channel config is empty, then it uses the default values. -The channel's name implies its nettype. +minimal channel config is empty, then it uses the default values. The name of +the channel implies its nettype.

When retracting a route, Babel sends instead an unreachable route for a little while (according to RFC). The -interaction of this behavior with other protocols is not well tested and strange things may happen. +

When retracting a route, Babel generates an unreachable route for a little +while (according to RFC). The interaction of this behavior with other protocols +is not well tested and strange things may happen. + BFD

-

As the Device protocol doesn't generate any routes, it cannot have @@ -2684,18 +2684,21 @@ any attributes. Example configuration looks like this:

protocol device { scan time 10; # Scan the interfaces often - primary "eth0" 192.168.1.1; - primary 192.168.0.0/16; + interface "eth0" { + preferred 192.168.1.1; + preferred 2001:db8:1:10::1; + }; } + Direct

The Direct protocol is a simple generator of device routes for all the directly connected networks according to the list of interfaces provided by the -kernel via the Device protocol. The Direct protocol supports IPv4 and IPv6 channels -in any count. +kernel via the Device protocol. The Direct protocol supports both IPv4 and IPv6 +channels.

The question is whether it is a good idea to have such device routes in BIRD routing table. OS kernel usually handles device routes for directly connected @@ -2739,13 +2742,13 @@ on Linux systems BIRD cannot change non-BIRD route in the kernel routing table.

protocol direct { - interface "-arc*", "*"; # Exclude the ARCnets ipv4; - ipv4 { table myothertable; }; ipv6; + interface "-arc*", "*"; # Exclude the ARCnets } + Kernel

The Kernel protocol supports both IPv4 and IPv6 channels; only one of them +can be configured in each protocol instance. Configuration

OSPF v2 needs one IPv4 channel, OSPF v3 needs one IPv6 channel. +

OSPFv2 needs one IPv4 channel. OSPFv3 needs either one IPv6 channel, or one +IPv4 channel (). Therefore, it is possible to use OSPFv3 for both +IPv4 and Pv6 routing, but it is necessary to have two protocol instances anyway. +If no channel is configured, appropriate channel is defined with default +parameters. protocol ospf [v2|v3] <name> { @@ -3114,8 +3115,8 @@ protocol ospf [v2|v3] <name> { (equal-cost multipath) routes. Such routes are used when there are several directions to the destination, each with the same (computed) cost. This option also allows to specify a limit on maximum number of - nexthops in one route. By default, ECMP is disabled. If enabled, - default value of the limit is 16. + nexthops in one route. By default, ECMP is enabled if supported by + Kernel. Default value of the limit is 16. This option specifies whether OSPF should merge external routes from @@ -3354,7 +3355,7 @@ protocol ospf [v2|v3] <name> { are immediately considered unreachable and only the address of the iface (instead of whole network prefix) is propagated. It is possible that some hardware drivers or platforms do not implement this feature. - Default value is no. + Default value is yes. OSPF could use BFD protocol as an advisory mechanism for neighbor @@ -3441,8 +3442,6 @@ network. This attribute is read-only. Default is protocol ospf MyOSPF { - rfc1583compat yes; - tick 2; ipv4 { export filter { if source = RTS_BGP then { @@ -3549,17 +3548,14 @@ exporting a selected subset of one table to another one. Configuration

Technically, the Pipe protocol is just a channel connected to a table on both sides. -Therefore, the configuration block for Essentially, the Pipe protocol is just a channel connected to a table on both +sides. Therefore, the configuration block for - Specifies the mode for the pipe to work in. Default is transparent. Attributes @@ -3586,35 +3582,27 @@ Pipe protocol while decreasing their preferences and correcting their BGP paths to reflect the AS boundary crossing. -table as1; # Define the tables -table as2; +ipv4 table as1; # Define the tables +ipv4 table as2; protocol kernel kern1 { # Synchronize them with the kernel - ipv4 { table as1; }; + ipv4 { table as1; export all; }; kernel table 1; } protocol kernel kern2 { - ipv4 { table as2; }; + ipv4 { table as2; export all; }; kernel table 2; } protocol bgp bgp1 { # The outside connections - ipv4 { - table as1; - export all; - import all; - }; + ipv4 { table as1; export all; }; local as 1; neighbor 192.168.0.1 as 1001; } protocol bgp bgp2 { - ipv4 { - table as2; - export all; - import all; - }; + ipv4 { table as2; export all; }; local as 2; neighbor 10.0.0.1 as 1002; } @@ -3657,7 +3645,7 @@ addresses and choose a default route. BIRD implements router behavior as defined in , router preferences and specific routes (), and DNS extensions (). -

The RAdv protocols supports only IPv6 channels. +

The RAdv protocols supports just IPv6 channel. Configuration

Prefix specific options @@ -3879,7 +3866,6 @@ definitions, prefix definitions and DNS definitions: valid DNS servers. Default: 3 * -

DNSSL specific options: @@ -3917,10 +3903,10 @@ definitions, prefix definitions and DNS definitions:

-table radv_routes; # Manually configured routes go here +ipv6 table radv_routes; # Manually configured routes go here protocol static { - table radv_routes; + ipv6 { table radv_routes; }; route 2001:0DB8:4000::/48 unreachable; route 2001:0DB8:4010::/48 unreachable; @@ -3933,8 +3919,7 @@ protocol static { protocol radv { propagate routes yes; # Propagate the routes from the radv_routes table - table radv_routes; - export all; + ipv6 { table radv_routes; export all; }; interface "eth2" { max ra interval 5; # Fast failover with more routers @@ -3970,6 +3955,7 @@ protocol radv { } + RIP

protocol rip { - import all; - export all; + ipv4 { + import all; + export all; + }; interface "eth*" { metric 2; port 1520; @@ -4241,6 +4232,7 @@ protocol rip { } + RPKI Introduction @@ -4248,7 +4240,7 @@ protocol rip {

The Resource Public Key Infrastructure (RPKI) is mechanism for origin validation of BGP routes (RFC 6480). BIRD supports only so-called RPKI-based origin validation. There is implemented RPKI to Router (RPKI-RTR) protocol (RFC -6810). It uses some of the RPKI data to allow a router to verify that the +6810). It uses some of the RPKI data to allow a router to verify that the autonomous system announcing an IP address prefix is in fact authorized to do so. This is not crypto checked so can be violated. But it should prevent the vast majority of accidental hijackings on the Internet today, e.g. the famous @@ -4294,10 +4286,10 @@ protocol rpki [<name>] { } -

Alse note that you have to specify the ROA channel. -If you want to import only IPv4 prefixes you have -to specify only roa4 channel. Similarly with IPv6 prefixes only. If you want to -fetch both IPv4 and even IPv6 ROAs you have to specify both channels. +

Alse note that you have to specify the ROA channel. If you want to import +only IPv4 prefixes you have to specify only roa4 channel. Similarly with IPv6 +prefixes only. If you want to fetch both IPv4 and even IPv6 ROAs you have to +specify both channels. RPKI protocol options @@ -4365,21 +4357,20 @@ roa6 table r6; protocol rpki { debug all; - + roa4 { table r4; }; roa6 { table r6; }; # Please, do not use rpki-validator.realmv6.org in production remote "rpki-validator.realmv6.org" port 8282; - + retry keep 5; refresh keep 30; expire 600; } -filter peer_in { - if (roa_check(r4, net, bgp_path.last) = ROA_INVALID || - roa_check(r6, net, bgp_path.last) = ROA_INVALID) then +filter peer_in_v4 { + if (roa_check(r4, net, bgp_path.last) = ROA_INVALID) then { print "Ignore invalid ROA ", net, " for ASN ", bgp_path.last; reject; @@ -4391,7 +4382,7 @@ protocol bgp { debug all; local as 65000; neighbor 192.168.2.1 as 65001; - import filter peer_in; + ipv4 { import filter peer_in_v4; }; } @@ -4402,23 +4393,22 @@ roa6 table r6; protocol rpki { debug all; - + roa4 { table r4; }; roa6 { table r6; }; - + remote 127.0.0.1 port 2345; transport ssh { bird private key "/home/birdgeek/.ssh/id_rsa"; remote public key "/home/birdgeek/.ssh/known_hosts"; user "birdgeek"; }; - + # Default interval values } - Static