From 1f64a487a065cc27c52ab0d3d38b7c82926fea70 Mon Sep 17 00:00:00 2001 From: Ondrej Filip Date: Thu, 15 Aug 2013 13:29:33 +0200 Subject: [PATCH 1/4] Symbol names enclosed by apostrophes can contain colons. --- conf/cf-lex.l | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf/cf-lex.l b/conf/cf-lex.l index 50f390e0..b1bbeae2 100644 --- a/conf/cf-lex.l +++ b/conf/cf-lex.l @@ -172,7 +172,7 @@ else: { return ELSECOL; } -({ALPHA}{ALNUM}*|[']({ALNUM}|[-]|[\.])*[']) { +({ALPHA}{ALNUM}*|[']({ALNUM}|[-]|[\.]|[:])*[']) { if(*yytext == '\'') { yytext[yyleng-1] = 0; yytext++; From 6d90e57332e102e261d69a1a05dfaa19fb31d933 Mon Sep 17 00:00:00 2001 From: Ondrej Filip Date: Thu, 15 Aug 2013 19:54:18 +0200 Subject: [PATCH 2/4] Typo in documentation fixed. --- doc/bird.sgml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/bird.sgml b/doc/bird.sgml index 6bf443e1..a2266424 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -1496,8 +1496,8 @@ for each neighbor using the following configuration parameters: route limit The maximal number of routes that may be imported from the protocol. If the route limit is - exceeded, the connection is closed with error. Limit is currently implemented as - disable after error When an error is encountered (either locally or by the other side), disable the instance automatically From e628cad0ca9eb7d9bf4141e57201169c46faa661 Mon Sep 17 00:00:00 2001 From: Ondrej Filip Date: Thu, 15 Aug 2013 20:20:05 +0200 Subject: [PATCH 3/4] BGP option 'route limit' is marked as obsolete. 'import limit' should be used instead. --- doc/bird-6.html | 1731 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1731 insertions(+) create mode 100644 doc/bird-6.html diff --git a/doc/bird-6.html b/doc/bird-6.html new file mode 100644 index 00000000..d21209ee --- /dev/null +++ b/doc/bird-6.html @@ -0,0 +1,1731 @@ + + + + + BIRD User's Guide: Protocols + + + + + +Next +Previous +Contents +
+

6. Protocols

+ +

6.1 BGP +

+ +

The Border Gateway Protocol is the routing protocol used for backbone +level routing in the today's Internet. Contrary to the other protocols, its convergence +doesn't rely on all routers following the same rules for route selection, +making it possible to implement any routing policy at any router in the +network, the only restriction being that if a router advertises a route, +it must accept and forward packets according to it. +

+

BGP works in terms of autonomous systems (often abbreviated as +AS). Each AS is a part of the network with common management and +common routing policy. It is identified by a unique 16-bit number +(ASN). Routers within each AS usually exchange AS-internal routing +information with each other using an interior gateway protocol (IGP, +such as OSPF or RIP). Boundary routers at the border of +the AS communicate global (inter-AS) network reachability information with +their neighbors in the neighboring AS'es via exterior BGP (eBGP) and +redistribute received information to other routers in the AS via +interior BGP (iBGP). +

+

Each BGP router sends to its neighbors updates of the parts of its +routing table it wishes to export along with complete path information +(a list of AS'es the packet will travel through if it uses the particular +route) in order to avoid routing loops. +

+

BIRD supports all requirements of the BGP4 standard as defined in +RFC 4271 +ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt +It also supports the community attributes +(RFC 1997 +ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt), +capability negotiation +(RFC 3392 +ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt), +MD5 password authentication +(RFC 2385 +ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt), +extended communities +(RFC 4360 +ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt), +route reflectors +(RFC 4456 +ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt), +multiprotocol extensions +(RFC 4760 +ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt), +4B AS numbers +(RFC 4893 +ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt), +and 4B AS numbers in extended communities +(RFC 5668 +ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt). +

+

For IPv6, it uses the standard multiprotocol extensions defined in +RFC 2283 +ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt +including changes described in the +latest draft +ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt +and applied to IPv6 according to +RFC 2545 +ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt. +

+

Route selection rules

+ +

BGP doesn't have any simple metric, so the rules for selection of an optimal +route among multiple BGP routes with the same preference are a bit more complex +and they are implemented according to the following algorithm. It starts the first +rule, if there are more "best" routes, then it uses the second rule to choose +among them and so on. +

+

    +
  • Prefer route with the highest Local Preference attribute.
    • +
  • Prefer route with the shortest AS path.
    • +
  • Prefer IGP origin over EGP and EGP origin over incomplete.
    • +
  • Prefer the lowest value of the Multiple Exit Discriminator.
    • +
  • Prefer routes received via eBGP over ones received via iBGP.
    • +
  • Prefer routes with lower internal distance to a boundary router.
    • +
  • Prefer the route with the lowest value of router ID of the +advertising router.
    • +
+

+

IGP routing table

+ +

BGP is mainly concerned with global network reachability and with +routes to other autonomous systems. When such routes are redistributed +to routers in the AS via BGP, they contain IP addresses of a boundary +routers (in route attribute NEXT_HOP). BGP depends on existing IGP +routing table with AS-internal routes to determine immediate next hops +for routes and to know their internal distances to boundary routers +for the purpose of BGP route selection. In BIRD, there is usually +one routing table used for both IGP routes and BGP routes. +

+

Configuration

+ +

Each instance of the BGP corresponds to one neighboring router. +This allows to set routing policy and all the other parameters differently +for each neighbor using the following configuration parameters: +

+

+
local [ip] as number

Define which AS we +are part of. (Note that contrary to other IP routers, BIRD is +able to act as a router located in multiple AS'es +simultaneously, but in such cases you need to tweak the BGP +paths manually in the filters to get consistent behavior.) +Optional ip argument specifies a source address, +equivalent to the source address option (see below). +This parameter is mandatory. +

+

neighbor ip as number

Define neighboring router +this instance will be talking to and what AS it's located in. Unless +you use the multihop clause, it must be directly connected to one +of your router's interfaces. In case the neighbor is in the same AS +as we are, we automatically switch to iBGP. This parameter is mandatory. +

+

multihop [number]

Configure multihop BGP +session to a neighbor that isn't directly connected. +Accurately, this option should be used if the configured +neighbor IP address does not match with any local network +subnets. Such IP address have to be reachable through system +routing table. For multihop BGP it is recommended to +explicitly configure source address to have it +stable. Optional number argument can be used to specify +the number of hops (used for TTL). Note that the number of +networks (edges) in a path is counted, i.e. if two BGP +speakers are separated by one router, the number of hops is +2. Default: switched off. +

+

source address ip

Define local address we +should use for next hop calculation and as a source address +for the BGP session. Default: the address of the local +end of the interface our neighbor is connected to. +

+

next hop self

Avoid calculation of the Next Hop +attribute and always advertise our own source address as a +next hop. This needs to be used only occasionally to +circumvent misconfigurations of other routers. Default: +disabled. +

+

next hop keep

Forward the received Next Hop +attribute even in situations where the local address should be +used instead, like when the route is sent to an interface with +a different subnet. Default: disabled. +

+

missing lladdr self|drop|ignore

Next Hop attribute +in BGP-IPv6 sometimes contains just the global IPv6 address, +but sometimes it has to contain both global and link-local +IPv6 addresses. This option specifies what to do if BIRD have +to send both addresses but does not know link-local address. +This situation might happen when routes from other protocols +are exported to BGP, or when improper updates are received +from BGP peers. self means that BIRD advertises its own +local address instead. drop means that BIRD skips that +prefixes and logs error. ignore means that BIRD ignores +the problem and sends just the global address (and therefore +forms improper BGP update). Default: self, unless BIRD +is configured as a route server (option rs client), in +that case default is ignore, because route servers usually +do not forward packets themselves. +

+

gateway direct|recursive

For received routes, their +gw (immediate next hop) attribute is computed from +received bgp_next_hop attribute. This option specifies +how it is computed. Direct mode means that the IP address from +bgp_next_hop is used if it is directly reachable, +otherwise the neighbor IP address is used. Recursive mode +means that the gateway is computed by an IGP routing table +lookup for the IP address from bgp_next_hop. Recursive +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. Recursive +mode is incompatible with +sorted tables. Default: direct for singlehop eBGP, +recursive otherwise. +

+

igp table name

Specifies a table that is used +as an IGP routing table. Default: the same as the table BGP is +connected to. +

+

ttl security switch

Use GTSM (RFC 5082 - the +generalized TTL security mechanism). GTSM protects against +spoofed packets by ignoring received packets with a smaller +than expected TTL. To work properly, GTSM have to be enabled +on both sides of a BGP session. If both ttl security and +multihop options are enabled, multihop option should +specify proper hop value to compute expected TTL. Kernel +support required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: +since long ago, IPv4 only. Note that full (ICMP protection, +for example) RFC 5082 support is provided by Linux +only. Default: disabled. +

+

password string

Use this password for MD5 authentication +of BGP sessions. Default: no authentication. Password has to be set by +external utility (e.g. setkey(8)) on BSD systems. +

+

passive switch

Standard BGP behavior is both +initiating outgoing connections and accepting incoming +connections. In passive mode, outgoing connections are not +initiated. Default: off. +

+

rr client

Be a route reflector and treat the neighbor as +a route reflection client. Default: disabled. +

+

rr cluster id IPv4 address

Route reflectors use cluster id +to avoid route reflection loops. When there is one route reflector in a cluster +it usually uses its router id as a cluster id, but when there are more route +reflectors in a cluster, these need to be configured (using this option) to +use a common cluster id. Clients in a cluster need not know their cluster +id and this option is not allowed for them. Default: the same as router id. +

+

rs client

Be a route server and treat the neighbor +as a route server client. A route server is used as a +replacement for full mesh EBGP routing in Internet exchange +points in a similar way to route reflectors used in IBGP routing. +BIRD does not implement obsoleted RFC 1863, but uses ad-hoc implementation, +which behaves like plain EBGP but reduces modifications to advertised route +attributes to be transparent (for example does not prepend its AS number to +AS PATH attribute and keeps MED attribute). Default: disabled. +

+

secondary switch

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 +sorted. Default: off. +

+

enable route refresh switch

When BGP speaker +changes its import filter, it has to re-examine all routes +received from its neighbor against the new filter. As these +routes might not be available, there is a BGP protocol +extension Route Refresh (specified in RFC 2918) that allows +BGP speaker to request re-advertisement of all routes from its +neighbor. This option specifies whether BIRD advertises this +capability and accepts such requests. Even when disabled, BIRD +can send route refresh requests. Default: on. +

+

interpret communities switch

RFC 1997 demands +that BGP speaker should process well-known communities like +no-export (65535, 65281) or no-advertise (65535, 65282). For +example, received route carrying a no-adverise community +should not be advertised to any of its neighbors. If this +option is enabled (which is by default), BIRD has such +behavior automatically (it is evaluated when a route is +exported to the BGP protocol just before the export filter). +Otherwise, this integrated processing of well-known +communities is disabled. In that case, similar behavior can be +implemented in the export filter. Default: on. +

+

enable as4 switch

BGP protocol was designed to use 2B AS numbers +and was extended later to allow 4B AS number. BIRD supports 4B AS extension, +but by disabling this option it can be persuaded not to advertise it and +to maintain old-style sessions with its neighbors. This might be useful for +circumventing bugs in neighbor's implementation of 4B AS extension. +Even when disabled (off), BIRD behaves internally as AS4-aware BGP router. +Default: on. +

+

capabilities switch

Use capability advertisement +to advertise optional capabilities. This is standard behavior +for newer BGP implementations, but there might be some older +BGP implementations that reject such connection attempts. +When disabled (off), features that request it (4B AS support) +are also disabled. Default: on, with automatic fallback to +off when received capability-related error. +

+

advertise ipv4 switch

Advertise IPv4 multiprotocol capability. +This is not a correct behavior according to the strict interpretation +of RFC 4760, but it is widespread and required by some BGP +implementations (Cisco and Quagga). This option is relevant +to IPv4 mode with enabled capability advertisement only. Default: on. +

+

route limit number

The maximal number of routes +that may be imported from the protocol. If the route limit is +exceeded, the connection is closed with an error. Limit is currently implemented as +import limit number action restart. This option is obsolete and it is +replaced by +import limit option. Default: no limit. +

+

disable after error switch

When an error is encountered (either +locally or by the other side), disable the instance automatically +and wait for an administrator to fix the problem manually. Default: off. +

+

hold time number

Time in seconds to wait for a Keepalive +message from the other side before considering the connection stale. +Default: depends on agreement with the neighboring router, we prefer +240 seconds if the other side is willing to accept it. +

+

startup hold time number

Value of the hold timer used +before the routers have a chance to exchange open messages and agree +on the real value. Default: 240 seconds. +

+

keepalive time number

Delay in seconds between sending +of two consecutive Keepalive messages. Default: One third of the hold time. +

+

connect retry time number

Time in seconds to wait before +retrying a failed attempt to connect. Default: 120 seconds. +

+

start delay time number

Delay in seconds between protocol +startup and the first attempt to connect. Default: 5 seconds. +

+

error wait time number,number

Minimum and maximum delay in seconds between a protocol +failure (either local or reported by the peer) and automatic restart. +Doesn't apply when disable after error is configured. If consecutive +errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300. +

+

error forget time number

Maximum time in seconds between two protocol +failures to treat them as a error sequence which makes the error wait time +increase exponentially. Default: 300 seconds. +

+

path metric switch

Enable comparison of path lengths +when deciding which BGP route is the best one. Default: on. +

+

med metric switch

Enable comparison of MED +attributes (during best route selection) even between routes +received from different ASes. This may be useful if all MED +attributes contain some consistent metric, perhaps enforced in +import filters of AS boundary routers. If this option is +disabled, MED attributes are compared only if routes are +received from the same AS (which is the standard behavior). +Default: off. +

+

deterministic med switch

BGP route selection +algorithm is often viewed as a comparison between individual +routes (e.g. if a new route appears and is better than the +current best one, it is chosen as the new best one). But the +proper route selection, as specified by RFC 4271, cannot be +fully implemented in that way. The problem is mainly in +handling the MED attribute. BIRD, by default, uses an +simplification based on individual route comparison, which in +some cases may lead to temporally dependent behavior (i.e. the +selection is dependent on the order in which routes appeared). +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 med metric option. This option is +incompatible with +sorted tables. +Default: off. +

+

igp metric switch

Enable comparison of internal +distances to boundary routers during best route selection. Default: on. +

+

prefer older switch

Standard route selection algorithm +breaks ties by comparing router IDs. This changes the behavior +to prefer older routes (when both are external and from different +peer). For details, see RFC 5004. Default: off. +

+

default bgp_med number

Value of the Multiple Exit +Discriminator to be used during route selection when the MED attribute +is missing. Default: 0. +

+

default bgp_local_pref number

A default value +for the Local Preference attribute. It is used when a new +Local Preference attribute is attached to a route by the BGP +protocol itself (for example, if a route is received through +eBGP and therefore does not have such attribute). Default: 100 +(0 in pre-1.2.0 versions of BIRD). +

+

+

Attributes

+ +

BGP defines several route attributes. Some of them (those marked with `I' in the +table below) are available on internal BGP connections only, some of them (marked +with `O') are optional. +

+

+
bgppath bgp_path

Sequence of AS numbers describing the AS path +the packet will travel through when forwarded according to the particular route. +In case of internal BGP it doesn't contain the number of the local AS. +

+

int bgp_local_pref [I]

Local preference value used for +selection among multiple BGP routes (see the selection rules above). It's +used as an additional metric which is propagated through the whole local AS. +

+

int bgp_med [O]

The Multiple Exit Discriminator of the route +is an optional attribute which is used on external (inter-AS) links to +convey to an adjacent AS the optimal entry point into the local AS. +The received attribute is also propagated over internal BGP links. +The attribute value is zeroed when a route is exported to an external BGP +instance to ensure that the attribute received from a neighboring AS is +not propagated to other neighboring ASes. A new value might be set in +the export filter of an external BGP instance. +See RFC 4451 +ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt +for further discussion of BGP MED attribute. +

+

enum bgp_origin

Origin of the route: either ORIGIN_IGP +if the route has originated in an interior routing protocol or +ORIGIN_EGP if it's been imported from the EGP protocol +(nowadays it seems to be obsolete) or ORIGIN_INCOMPLETE if the origin +is unknown. +

+

ip bgp_next_hop

Next hop to be used for forwarding of packets +to this destination. On internal BGP connections, it's an address of the +originating router if it's inside the local AS or a boundary router the +packet will leave the AS through if it's an exterior route, so each BGP +speaker within the AS has a chance to use the shortest interior path +possible to this point. +

+

void bgp_atomic_aggr [O]

This is an optional attribute +which carries no value, but the sole presence of which indicates that the route +has been aggregated from multiple routes by some router on the path from +the originator. +

+

clist bgp_community [O]

List of community values associated +with the route. Each such value is a pair (represented as a pair data +type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines +the community and the second one being a per-AS identifier. There are lots +of uses of the community mechanism, but generally they are used to carry +policy information like "don't export to USA peers". As each AS can define +its own routing policy, it also has a complete freedom about which community +attributes it defines and what will their semantics be. +

+

eclist bgp_ext_community [O]

List of extended community +values associated with the route. Extended communities have similar usage +as plain communities, but they have an extended range (to allow 4B ASNs) +and a nontrivial structure with a type field. Individual community values are +represented using an ec data type inside the filters. +

+

quad bgp_originator_id [I, O]

This attribute is created by the +route reflector when reflecting the route and contains the router ID of the +originator of the route in the local AS. +

+

clist bgp_cluster_list [I, O]

This attribute contains a list +of cluster IDs of route reflectors. Each route reflector prepends its +cluster ID when reflecting the route. +

+

+

Example

+ +

+

+
+protocol bgp {
+        local as 65000;                      # Use a private AS number
+        neighbor 198.51.100.130 as 64496;    # Our neighbor ...
+        multihop;                            # ... which is connected indirectly
+        export filter {                      # We use non-trivial export rules
+                if source = RTS_STATIC then { # Export only static routes
+                        # Assign our community
+                        bgp_community.add((65000,64501));
+                        # Artificially increase path length
+                        # by advertising local AS number twice
+                        if bgp_path ~ [= 65000 =] then
+                                bgp_path.prepend(65000);
+                        accept;
+                }
+                reject;
+        };
+        import all;
+        source address 198.51.100.14;   # Use a non-standard source address
+}
+
+
+

+

6.2 Device +

+ +

The Device protocol is not a real routing protocol. It doesn't generate +any routes and it only serves as a module for getting information about network +interfaces from the kernel. +

+

Except for very unusual circumstances, you probably should include +this protocol in the configuration since almost all other protocols +require network interfaces to be defined for them to work with. +

+

Configuration

+ +

+

+
scan time number

Time in seconds between two scans +of the network interface list. On systems where we are notified about +interface status changes asynchronously (such as newer versions of +Linux), we need to scan the list only in order to avoid confusion by lost +notification messages, so the default time is set to a large value. +

+

primary [ "mask" ] prefix

If a network interface has more than one network address, BIRD +has to choose one of them as a primary one. By default, BIRD +chooses the lexicographically smallest address as the primary +one. +

This option allows to specify which network address should be +chosen as a primary one. Network addresses that match +prefix are preferred to non-matching addresses. If more +primary options are used, the first one has the highest +preference. If "mask" is specified, then such +primary option is relevant only to matching network +interfaces. +

In all cases, an address marked by operating system as +secondary cannot be chosen as the primary one. +

+

+

As the Device protocol doesn't generate any routes, it cannot have +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;
+}
+
+
+

+

6.3 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 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 networks by itself so we don't need (and don't +want) to export these routes to the kernel protocol. OSPF protocol +creates device routes for its interfaces itself and BGP protocol is +usually used for exporting aggregate routes. Although there are some +use cases that use the direct protocol (like abusing eBGP as an IGP +routing protocol), in most cases it is not needed to have these device +routes in BIRD routing table and to use the direct protocol. +

+

There is one notable case when you definitely want to use the +direct protocol -- running BIRD on BSD systems. Having high priority +device routes for directly connected networks from the direct protocol +protects kernel device routes from being overwritten or removed by IGP +routes during some transient network conditions, because a lower +priority IGP route for the same network is not exported to the kernel +routing table. This is an issue on BSD systems only, as on Linux +systems BIRD cannot change non-BIRD route in the kernel routing table. +

+

The only configurable thing about direct is what interfaces it watches: +

+

+

+
interface pattern [, ...]

By default, the Direct +protocol will generate device routes for all the interfaces +available. If you want to restrict it to some subset of interfaces +(for example if you're using multiple routing tables for policy +routing and some of the policy domains don't contain all interfaces), +just use this clause. +

+

+

Direct device routes don't contain any specific attributes. +

+

Example config might look like this: +

+

+

+
+protocol direct {
+        interface "-arc*", "*";         # Exclude the ARCnets
+}
+
+
+

+

6.4 Kernel +

+ +

The Kernel protocol is not a real routing protocol. Instead of communicating +with other routers in the network, it performs synchronization of BIRD's routing +tables with the OS kernel. Basically, it sends all routing table updates to the kernel +and from time to time it scans the kernel tables to see whether some routes have +disappeared (for example due to unnoticed up/down transition of an interface) +or whether an `alien' route has been added by someone else (depending on the +learn switch, such routes are either ignored or accepted to our +table). +

+

Unfortunately, there is one thing that makes the routing table +synchronization a bit more complicated. In the kernel routing table +there are also device routes for directly connected networks. These +routes are usually managed by OS itself (as a part of IP address +configuration) and we don't want to touch that. They are completely +ignored during the scan of the kernel tables and also the export of +device routes from BIRD tables to kernel routing tables is restricted +to prevent accidental interference. This restriction can be disabled using +device routes switch. +

+

If your OS supports only a single routing table, you can configure +only one instance of the Kernel protocol. If it supports multiple +tables (in order to allow policy routing; such an OS is for example +Linux), you can run as many instances as you want, but each of them +must be connected to a different BIRD routing table and to a different +kernel table. +

+

Because the kernel protocol is partially integrated with the +connected routing table, there are two limitations - it is not +possible to connect more kernel protocols to the same routing table +and changing route destination/gateway in an export +filter of a kernel protocol does not work. Both limitations can be +overcome using another routing table and the pipe protocol. +

+

Configuration

+ +

+

+
persist switch

Tell BIRD to leave all its routes in the +routing tables when it exits (instead of cleaning them up). +

scan time number

Time in seconds between two consecutive scans of the +kernel routing table. +

learn switch

Enable learning of routes added to the kernel +routing tables by other routing daemons or by the system administrator. +This is possible only on systems which support identification of route +authorship. +

+

device routes switch

Enable export of device +routes to the kernel routing table. By default, such routes +are rejected (with the exception of explicitly configured +device routes from the static protocol) regardless of the +export filter to protect device routes in kernel routing table +(managed by OS itself) from accidental overwriting or erasing. +

+

kernel table number

Select which kernel table should +this particular instance of the Kernel protocol work with. Available +only on systems supporting multiple routing tables. +

+

+

Attributes

+ +

The Kernel protocol defines several attributes. These attributes +are translated to appropriate system (and OS-specific) route attributes. +We support these attributes: +

+

+
int krt_source

The original source of the imported +kernel route. The value is system-dependent. On Linux, it is +a value of the protocol field of the route. See +/etc/iproute2/rt_protos for common values. On BSD, it is +based on STATIC and PROTOx flags. The attribute is read-only. +

+

int krt_metric

The kernel metric of +the route. When multiple same routes are in a kernel routing +table, the Linux kernel chooses one with lower metric. +

+

ip krt_prefsrc

(Linux) The preferred source address. +Used in source address selection for outgoing packets. Have to +be one of IP addresses of the router. +

+

int krt_realm

(Linux) The realm of the route. Can be +used for traffic classification. +

+

+

Example

+ +

A simple configuration can look this way: +

+

+

+
+protocol kernel {
+        export all;
+}
+
+
+

+

Or for a system with two routing tables: +

+

+

+
+protocol kernel {               # Primary routing table
+        learn;                  # Learn alien routes from the kernel
+        persist;                # Don't remove routes on bird shutdown
+        scan time 10;           # Scan kernel routing table every 10 seconds
+        import all;
+        export all;
+}
+
+protocol kernel {               # Secondary routing table
+        table auxtable;
+        kernel table 100;
+        export all;
+}
+
+
+

+

6.5 OSPF +

+ +

Introduction

+ +

Open Shortest Path First (OSPF) is a quite complex interior gateway +protocol. The current IPv4 version (OSPFv2) is defined in RFC +2328 +ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt and +the current IPv6 version (OSPFv3) is defined in RFC 5340 +ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt It's a link state +(a.k.a. shortest path first) protocol -- each router maintains a +database describing the autonomous system's topology. Each participating +router has an identical copy of the database and all routers run the +same algorithm calculating a shortest path tree with themselves as a +root. OSPF chooses the least cost path as the best path. +

+

In OSPF, the autonomous system can be split to several areas in order +to reduce the amount of resources consumed for exchanging the routing +information and to protect the other areas from incorrect routing data. +Topology of the area is hidden to the rest of the autonomous system. +

+

Another very important feature of OSPF is that +it can keep routing information from other protocols (like Static or BGP) +in its link state database as external routes. Each external route can +be tagged by the advertising router, making it possible to pass additional +information between routers on the boundary of the autonomous system. +

+

OSPF quickly detects topological changes in the autonomous system (such +as router interface failures) and calculates new loop-free routes after a short +period of convergence. Only a minimal amount of +routing traffic is involved. +

+

Each router participating in OSPF routing periodically sends Hello messages +to all its interfaces. This allows neighbors to be discovered dynamically. +Then the neighbors exchange theirs parts of the link state database and keep it +identical by flooding updates. The flooding process is reliable and ensures +that each router detects all changes. +

+

Configuration

+ +

In the main part of configuration, there can be multiple definitions of +OSPF areas, each with a different id. These definitions includes many other +switches and multiple definitions of interfaces. Definition of interface +may contain many switches and constant definitions and list of neighbors +on nonbroadcast networks. +

+

+
+protocol ospf <name> {
+        rfc1583compat <switch>;
+        stub router <switch>;
+        tick <num>;
+        ecmp <switch> [limit <num>];
+        area <id> {
+                stub;
+                nssa;
+                summary <switch>;
+                default nssa <switch>;
+                default cost <num>;
+                default cost2 <num>;
+                translator <switch>;
+                translator stability <num>;
+
+                networks {
+                        <prefix>;
+                        <prefix> hidden;
+                }
+                external {
+                        <prefix>;
+                        <prefix> hidden;
+                        <prefix> tag <num>;
+                }
+                stubnet <prefix>;
+                stubnet <prefix> {
+                        hidden <switch>;
+                        summary <switch>;
+                        cost <num>;
+                }
+                interface <interface pattern> [instance <num>] {
+                        cost <num>;
+                        stub <switch>;
+                        hello <num>;
+                        poll <num>;
+                        retransmit <num>;
+                        priority <num>;
+                        wait <num>;
+                        dead count <num>;
+                        dead <num>;
+                        rx buffer [normal|large|<num>];
+                        type [broadcast|bcast|pointopoint|ptp|
+                                nonbroadcast|nbma|pointomultipoint|ptmp];
+                        strict nonbroadcast <switch>;
+                        real broadcast <switch>;
+                        ptp netmask <switch>;
+                        check link <switch>;
+                        ecmp weight <num>;
+                        ttl security [<switch>; | tx only]
+                        tx class|dscp <num>;
+                        tx priority <num>;
+                        authentication [none|simple|cryptographic];
+                        password "<text>";
+                        password "<text>" {
+                                id <num>;
+                                generate from "<date>";
+                                generate to "<date>";
+                                accept from "<date>";
+                                accept to "<date>";
+                        };
+                        neighbors {
+                                <ip>;
+                                <ip> eligible;
+                        };
+                };
+                virtual link <id> [instance <num>] {
+                        hello <num>;
+                        retransmit <num>;
+                        wait <num>;
+                        dead count <num>;
+                        dead <num>;
+                        authentication [none|simple|cryptographic];
+                        password "<text>";
+                };
+        };
+}
+
+
+

+

+
rfc1583compat switch

This option controls compatibility of routing table +calculation with RFC 1583 +ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt. Default +value is no. +

+

stub router switch

This option configures the router to be a stub router, i.e., +a router that participates in the OSPF topology but does not +allow transit traffic. In OSPFv2, this is implemented by +advertising maximum metric for outgoing links, as suggested +by RFC 3137 +ftp://ftp.rfc-editor.org/in-notes/rfc3137.txt. +In OSPFv3, the stub router behavior is announced by clearing +the R-bit in the router LSA. Default value is no. +

+

tick num

The routing table calculation and clean-up of areas' databases +is not performed when a single link state +change arrives. To lower the CPU utilization, it's processed later +at periodical intervals of num seconds. The default value is 1. +

+

ecmp switch [limit number]

This option specifies whether OSPF is allowed to generate +ECMP (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 maximal number of nexthops in one route. By +default, ECMP is disabled. If enabled, default value of the +limit is 16. +

+

area id

This defines an OSPF area with given area ID (an integer or an IPv4 +address, similarly to a router ID). The most important area is +the backbone (ID 0) to which every other area must be connected. +

+

stub

This option configures the area to be a stub area. External +routes are not flooded into stub areas. Also summary LSAs can be +limited in stub areas (see option summary). +By default, the area is not a stub area. +

+

nssa

This option configures the area to be a NSSA (Not-So-Stubby +Area). NSSA is a variant of a stub area which allows a +limited way of external route propagation. Global external +routes are not propagated into a NSSA, but an external route +can be imported into NSSA as a (area-wide) NSSA-LSA (and +possibly translated and/or aggregated on area boundary). +By default, the area is not NSSA. +

+

summary switch

This option controls propagation of summary LSAs into stub or +NSSA areas. If enabled, summary LSAs are propagated as usual, +otherwise just the default summary route (0.0.0.0/0) is +propagated (this is sometimes called totally stubby area). If +a stub area has more area boundary routers, propagating +summary LSAs could lead to more efficient routing at the cost +of larger link state database. Default value is no. +

+

default nssa switch

When summary option is enabled, default summary route is +no longer propagated to the NSSA. In that case, this option +allows to originate default route as NSSA-LSA to the NSSA. +Default value is no. +

+

default cost num

This option controls the cost of a default route propagated to +stub and NSSA areas. Default value is 1000. +

+

default cost2 num

When a default route is originated as NSSA-LSA, its cost +can use either type 1 or type 2 metric. This option allows +to specify the cost of a default route in type 2 metric. +By default, type 1 metric (option default cost) is used. +

+

translator switch

This option controls translation of NSSA-LSAs into external +LSAs. By default, one translator per NSSA is automatically +elected from area boundary routers. If enabled, this area +boundary router would unconditionally translate all NSSA-LSAs +regardless of translator election. Default value is no. +

+

translator stability num

This option controls the translator stability interval (in +seconds). When the new translator is elected, the old one +keeps translating until the interval is over. Default value +is 40. +

+

networks { set }

Definition of area IP ranges. This is used in summary LSA origination. +Hidden networks are not propagated into other areas. +

+

external { set }

Definition of external area IP ranges for NSSAs. This is used +for NSSA-LSA translation. Hidden networks are not translated +into external LSAs. Networks can have configured route tag. +

+

stubnet prefix { options }

Stub networks are networks that are not transit networks +between OSPF routers. They are also propagated through an +OSPF area as a part of a link state database. By default, +BIRD generates a stub network record for each primary network +address on each OSPF interface that does not have any OSPF +neighbors, and also for each non-primary network address on +each OSPF interface. This option allows to alter a set of +stub networks propagated by this router. +

Each instance of this option adds a stub network with given +network prefix to the set of propagated stub network, unless +option hidden is used. It also suppresses default stub +networks for given network prefix. When option +summary is used, also default stub networks that are +subnetworks of given stub network are suppressed. This might +be used, for example, to aggregate generated stub networks. +

+

interface pattern [instance num]

Defines that the specified interfaces belong to the area being defined. +See +interface common option for detailed description. +In OSPFv3, you can specify instance ID for that interface +description, so it is possible to have several instances of +that interface with different options or even in different areas. +

+

virtual link id [instance num]

Virtual link to router with the router id. Virtual link acts +as a point-to-point interface belonging to backbone. The +actual area is used as transport area. This item cannot be in +the backbone. In OSPFv3, you could also use several virtual +links to one destination with different instance IDs. +

+

cost num

Specifies output cost (metric) of an interface. Default value is 10. +

+

stub switch

If set to interface it does not listen to any packet and does not send +any hello. Default value is no. +

+

hello num

Specifies interval in seconds between sending of Hello messages. Beware, all +routers on the same network need to have the same hello interval. +Default value is 10. +

+

poll num

Specifies interval in seconds between sending of Hello messages for +some neighbors on NBMA network. Default value is 20. +

+

retransmit num

Specifies interval in seconds between retransmissions of unacknowledged updates. +Default value is 5. +

+

priority num

On every multiple access network (e.g., the Ethernet) Designed Router +and Backup Designed router are elected. These routers have some +special functions in the flooding process. Higher priority increases +preferences in this election. Routers with priority 0 are not +eligible. Default value is 1. +

+

wait num

After start, router waits for the specified number of seconds between starting +election and building adjacency. Default value is 40. +

+

dead count num

When the router does not receive any messages from a neighbor in +dead count*hello seconds, it will consider the neighbor down. +

+

dead num

When the router does not receive any messages from a neighbor in +dead seconds, it will consider the neighbor down. If both directives +dead count and dead are used, dead has precendence. +

+

rx buffer num

This sets the size of buffer used for receiving packets. The buffer should +be bigger than maximal size of any packets. Value NORMAL (default) +means 2*MTU, value LARGE means maximal allowed packet - 65535. +

+

type broadcast|bcast

BIRD detects a type of a connected network automatically, but +sometimes it's convenient to force use of a different type +manually. On broadcast networks (like ethernet), flooding +and Hello messages are sent using multicasts (a single packet +for all the neighbors). A designated router is elected and it +is responsible for synchronizing the link-state databases and +originating network LSAs. This network type cannot be used on +physically NBMA networks and on unnumbered networks (networks +without proper IP prefix). +

+

type pointopoint|ptp

Point-to-point networks connect just 2 routers together. No +election is performed and no network LSA is originated, which +makes it simpler and faster to establish. This network type +is useful not only for physically PtP ifaces (like PPP or +tunnels), but also for broadcast networks used as PtP links. +This network type cannot be used on physically NBMA networks. +

+

type nonbroadcast|nbma

On NBMA networks, the packets are sent to each neighbor +separately because of lack of multicast capabilities. +Like on broadcast networks, a designated router is elected, +which plays a central role in propagation of LSAs. +This network type cannot be used on unnumbered networks. +

+

type pointomultipoint|ptmp

This is another network type designed to handle NBMA +networks. In this case the NBMA network is treated as a +collection of PtP links. This is useful if not every pair of +routers on the NBMA network has direct communication, or if +the NBMA network is used as an (possibly unnumbered) PtP +link. +

+

strict nonbroadcast switch

If set, don't send hello to any undefined neighbor. This switch +is ignored on other than NBMA or PtMP networks. Default value is no. +

+

real broadcast switch

In type broadcast or type ptp network +configuration, OSPF packets are sent as IP multicast +packets. This option changes the behavior to using +old-fashioned IP broadcast packets. This may be useful as a +workaround if IP multicast for some reason does not work or +does not work reliably. This is a non-standard option and +probably is not interoperable with other OSPF +implementations. Default value is no. +

+

ptp netmask switch

In type ptp network configurations, OSPFv2 +implementations should ignore received netmask field in hello +packets and should send hello packets with zero netmask field +on unnumbered PtP links. But some OSPFv2 implementations +perform netmask checking even for PtP links. This option +specifies whether real netmask will be used in hello packets +on type ptp interfaces. You should ignore this option +unless you meet some compatibility problems related to this +issue. Default value is no for unnumbered PtP links, yes +otherwise. +

+

check link switch

If set, a hardware link state (reported by OS) is taken into +consideration. When a link disappears (e.g. an ethernet cable is +unplugged), neighbors 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. +

+

ttl security [switch | tx only]

TTL security is a feature that protects routing protocols +from remote spoofed packets by using TTL 255 instead of TTL 1 +for protocol packets destined to neighbors. Because TTL is +decremented when packets are forwarded, it is non-trivial to +spoof packets with TTL 255 from remote locations. Note that +this option would interfere with OSPF virtual links. +

If this option is enabled, the router will send OSPF packets +with TTL 255 and drop received packets with TTL less than +255. If this option si set to tx only, TTL 255 is used +for sent packets, but is not checked for received +packets. Default value is no. +

+

tx class|dscp|priority num

These options specify the ToS/DiffServ/Traffic class/Priority +of the outgoing OSPF packets. See +tx class common option for detailed description. +

+

ecmp weight num

When ECMP (multipath) routes are allowed, this value specifies +a relative weight used for nexthops going through the iface. +Allowed values are 1-256. Default value is 1. +

+

authentication none

No passwords are sent in OSPF packets. This is the default value. +

+

authentication simple

Every packet carries 8 bytes of password. Received packets +lacking this password are ignored. This authentication mechanism is +very weak. +

+

authentication cryptographic

16-byte long MD5 digest is appended to every packet. For the digest +generation 16-byte long passwords are used. Those passwords are +not sent via network, so this mechanism is quite secure. +Packets can still be read by an attacker. +

+

password "text"

An 8-byte or 16-byte password used for authentication. +See +password common option for detailed description. +

+

neighbors { set }

A set of neighbors to which Hello messages on NBMA or PtMP +networks are to be sent. For NBMA networks, some of them +could be marked as eligible. In OSPFv3, link-local addresses +should be used, using global ones is possible, but it is +nonstandard and might be problematic. And definitely, +link-local and global addresses should not be mixed. +

+

+

+

Attributes

+ +

OSPF defines four route attributes. Each internal route has a metric. +Metric is ranging from 1 to infinity (65535). +External routes use metric type 1 or metric type 2. +A metric of type 1 is comparable with internal metric, a +metric of type 2 is always longer +than any metric of type 1 or any internal metric. +Internal metric or metric of type 1 is stored in attribute +ospf_metric1, metric type 2 is stored in attribute ospf_metric2. +If you specify both metrics only metric1 is used. +

Each external route can also carry attribute ospf_tag which is a +32-bit integer which is used when exporting routes to other protocols; +otherwise, it doesn't affect routing inside the OSPF domain at all. +The fourth attribute ospf_router_id is a router ID of the router +advertising that route/network. This attribute is read-only. Default +is ospf_metric2 = 10000 and ospf_tag = 0. +

+

Example

+ +

+

+

+
+protocol ospf MyOSPF {
+        rfc1583compat yes;
+        tick 2;
+        export filter {
+                if source = RTS_BGP then {
+                        ospf_metric1 = 100;
+                        accept;
+                }
+                reject;
+        };
+        area 0.0.0.0 {
+                interface "eth*" {
+                        cost 11;
+                        hello 15;
+                        priority 100;
+                        retransmit 7;
+                        authentication simple;
+                        password "aaa";
+                };
+                interface "ppp*" {
+                        cost 100;
+                        authentication cryptographic;
+                        password "abc" {
+                                id 1;
+                                generate to "22-04-2003 11:00:06";
+                                accept from "17-01-2001 12:01:05";
+                        };
+                        password "def" {
+                                id 2;
+                                generate to "22-07-2005 17:03:21";
+                                accept from "22-02-2001 11:34:06";
+                        };
+                };
+                interface "arc0" {
+                        cost 10;
+                        stub yes;
+                };
+                interface "arc1";
+        };
+        area 120 {
+                stub yes;
+                networks {
+                        172.16.1.0/24;
+                        172.16.2.0/24 hidden;
+                }
+                interface "-arc0" , "arc*" {
+                        type nonbroadcast;
+                        authentication none;
+                        strict nonbroadcast yes;
+                        wait 120;
+                        poll 40;
+                        dead count 8;
+                        neighbors {
+                                192.168.120.1 eligible;
+                                192.168.120.2;
+                                192.168.120.10;
+                        };
+                };
+        };
+}
+
+
+

+

6.6 Pipe +

+ +

Introduction

+ +

The Pipe protocol serves as a link between two routing tables, allowing routes to be +passed from a table declared as primary (i.e., the one the pipe is connected to using the +table configuration keyword) to the secondary one (declared using peer table) +and vice versa, depending on what's allowed by the filters. Export filters control export +of routes from the primary table to the secondary one, import filters control the opposite +direction. +

+

The Pipe protocol may work in the transparent mode mode or in the opaque mode. +In the transparent mode, the Pipe protocol retransmits all routes from +one table to the other table, retaining their original source and +attributes. If import and export filters are set to accept, then both +tables would have the same content. The transparent mode is the default mode. +

+

In the opaque mode, the Pipe protocol retransmits optimal route +from one table to the other table in a similar way like other +protocols send and receive routes. Retransmitted route will have the +source set to the Pipe protocol, which may limit access to protocol +specific route attributes. This mode is mainly for compatibility, it +is not suggested for new configs. The mode can be changed by +mode option. +

+

The primary use of multiple routing tables and the Pipe protocol is for policy routing, +where handling of a single packet doesn't depend only on its destination address, but also +on its source address, source interface, protocol type and other similar parameters. +In many systems (Linux being a good example), the kernel allows to enforce routing policies +by defining routing rules which choose one of several routing tables to be used for a packet +according to its parameters. Setting of these rules is outside the scope of BIRD's work +(on Linux, you can use the ip command), but you can create several routing tables in BIRD, +connect them to the kernel ones, use filters to control which routes appear in which tables +and also you can employ the Pipe protocol for exporting a selected subset of one table to +another one. +

+

Configuration

+ +

+

+
peer table table

Defines secondary routing table to connect to. The +primary one is selected by the table keyword. +

+

mode opaque|transparent

Specifies the mode for the pipe to work in. Default is transparent. +

+

+

Attributes

+ +

The Pipe protocol doesn't define any route attributes. +

+

Example

+ +

Let's consider a router which serves as a boundary router of two different autonomous +systems, each of them connected to a subset of interfaces of the router, having its own +exterior connectivity and wishing to use the other AS as a backup connectivity in case +of outage of its own exterior line. +

+

Probably the simplest solution to this situation is to use two routing tables (we'll +call them as1 and as2) and set up kernel routing rules, so that packets having +arrived from interfaces belonging to the first AS will be routed according to as1 +and similarly for the second AS. Thus we have split our router to two logical routers, +each one acting on its own routing table, having its own routing protocols on its own +interfaces. In order to use the other AS's routes for backup purposes, we can pass +the routes between the tables through a Pipe protocol while decreasing their preferences +and correcting their BGP paths to reflect the AS boundary crossing. +

+

+
+table as1;                              # Define the tables
+table as2;
+
+protocol kernel kern1 {                 # Synchronize them with the kernel
+        table as1;
+        kernel table 1;
+}
+
+protocol kernel kern2 {
+        table as2;
+        kernel table 2;
+}
+
+protocol bgp bgp1 {                     # The outside connections
+        table as1;
+        local as 1;
+        neighbor 192.168.0.1 as 1001;
+        export all;
+        import all;
+}
+
+protocol bgp bgp2 {
+        table as2;
+        local as 2;
+        neighbor 10.0.0.1 as 1002;
+        export all;
+        import all;
+}
+
+protocol pipe {                         # The Pipe
+        table as1;
+        peer table as2;
+        export filter {
+                if net ~ [ 1.0.0.0/8+] then {   # Only AS1 networks
+                        if preference>10 then preference = preference-10;
+                        if source=RTS_BGP then bgp_path.prepend(1);
+                        accept;
+                }
+                reject;
+        };
+        import filter {
+                if net ~ [ 2.0.0.0/8+] then {   # Only AS2 networks
+                        if preference>10 then preference = preference-10;
+                        if source=RTS_BGP then bgp_path.prepend(2);
+                        accept;
+                }
+                reject;
+        };
+}
+
+
+

+

6.7 RAdv +

+ +

Introduction

+ +

The RAdv protocol is an implementation of Router Advertisements, +which are used in the IPv6 stateless autoconfiguration. IPv6 routers +send (in irregular 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 4861 +ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt +and also the DNS extensions from +RFC 6106 +ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt. +

+

Configuration

+ +

There are several classes of definitions in RAdv configuration -- +interface definitions, prefix definitions and DNS definitions: +

+

+
interface pattern [, ...] { options }

Interface definitions specify a set of interfaces on which the +protocol is activated and contain interface specific options. +See +interface common options for +detailed description. +

+

prefix prefix { options }

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 +its options are used. If no matching prefix definition is +found, the prefix is used with default options. +

Prefix definitions can be either global or interface-specific. +The second ones are part of interface options. The prefix +definition matching is done in the first-match style, when +interface-specific definitions are processed before global +definitions. As expected, the prefix definition is matching if +the network prefix is a subnet of the prefix in prefix +definition. +

+

rdnss { options }

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 rdnss +address 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 rdnss local option. +

+

dnssl { options }

DNSSL definitions allow to specify a list of advertised DNS +search domains together with their options. Like rdnss +above, multiple definitions are cumulative, they can be used +also as interface-specific options and there is a short +variant dnssl domain that just specifies one DNS +search domain. +

+ +

trigger prefix

RAdv protocol could be configured to change its behavior based +on availability of routes. When this option is used, the +protocol waits in suppressed state until a trigger route +(for the specified network) is exported to the protocol, the +protocol also returnsd to suppressed state if the +trigger route disappears. Note that route export depends +on specified export filter, as usual. This option could be +used, e.g., for handling failover in multihoming scenarios. +

During suppressed state, router advertisements are generated, +but with some fields zeroed. Exact behavior depends on which +fields are zeroed, this can be configured by +sensitive option for appropriate fields. By default, just +default lifetime (also called router lifetime) is +zeroed, which means hosts cannot use the router as a default +router. preferred lifetime and valid lifetime could +also be configured as sensitive for a prefix, which would +cause autoconfigured IPs to be deprecated or even removed. +

+

+

Interface specific options: +

+

+
max ra interval expr

Unsolicited router advertisements are sent in irregular time +intervals. This option specifies the maximum length of these +intervals, in seconds. Valid values are 4-1800. Default: 600 +

+

min ra interval expr

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. +

+

min delay expr

The minimum delay between two consecutive router advertisements, +in seconds. Default: 3 +

+

managed switch

This option specifies whether hosts should use DHCPv6 for +IP address configuration. Default: no +

+

other config switch

This option specifies whether hosts should use DHCPv6 to +receive other configuration information. Default: no +

+

link mtu expr

This option specifies which value of MTU should be used by +hosts. 0 means unspecified. Default: 0 +

+

reachable time expr

This option specifies the time (in milliseconds) how long +hosts should assume a neighbor is reachable (from the last +confirmation). Maximum is 3600000, 0 means unspecified. +Default 0. +

+

retrans timer expr

This option specifies the time (in milliseconds) how long +hosts should wait before retransmitting Neighbor Solicitation +messages. 0 means unspecified. Default 0. +

+

current hop limit expr

This option specifies which value of Hop Limit should be used +by hosts. Valid values are 0-255, 0 means unspecified. Default: 64 +

+

default lifetime expr [sensitive switch]

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. For +sensitive option, see +trigger. +Default: 3 * max ra interval, sensitive yes. +

+

rdnss local switch

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. +

+

dnssl local switch

Use only local DNSSL definitions for this interface. See +rdnss local option above. Default: no. +

+

+

+

Prefix specific options: +

+

+
skip switch

This option allows to specify that given prefix should not be +advertised. This is useful for making exceptions from a +default policy of advertising all prefixes. Note that for +withdrawing an already advertised prefix it is more useful to +advertise it with zero valid lifetime. Default: no +

+

onlink switch

This option specifies whether hosts may use the advertised +prefix for onlink determination. Default: yes +

+

autonomous switch

This option specifies whether hosts may use the advertised +prefix for stateless autoconfiguration. Default: yes +

+

valid lifetime expr [sensitive switch]

This option specifies the time (in seconds) how long (after +the receipt of RA) the prefix information is valid, i.e., +autoconfigured IP addresses can be assigned and hosts with +that IP addresses are considered directly reachable. 0 means +the prefix is no longer valid. For sensitive option, see +trigger. Default: 86400 (1 day), sensitive no. +

+

preferred lifetime expr [sensitive switch]

This option specifies the time (in seconds) how long (after +the receipt of RA) IP addresses generated from the prefix +using stateless autoconfiguration remain preferred. For +sensitive option, see +trigger. +Default: 14400 (4 hours), sensitive no. +

+

+

+

RDNSS specific options: +

+

+
ns address

This option specifies one recursive DNS server. Can be used +multiple times for multiple servers. It is mandatory to have +at least one ns option in rdnss definition. +

+

lifetime [mult] expr

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 mult is used) in +multiples of max ra interval. Note that RDNSS information +is also invalidated when default lifetime expires. 0 +means these addresses are no longer valid DNS servers. +Default: 3 * max ra interval. +

+

+

+

DNSSL specific options: +

+

+
domain address

This option specifies one DNS search domain. Can be used +multiple times for multiple domains. It is mandatory to have +at least one domain option in dnssl definition. +

+

lifetime [mult] expr

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 lifetime option above. +Default: 3 * max ra interval. +

+

+

+

Example

+ +

+

+
+protocol radv {
+        interface "eth2" {
+                max ra interval 5;      # Fast failover with more routers
+                managed yes;            # Using DHCPv6 on eth2
+                prefix ::/0 {
+                        autonomous off; # So do not autoconfigure any IP
+                };
+        };
+
+        interface "eth*";               # No need for any other options
+
+        prefix 2001:0DB8:1234::/48 {
+                preferred lifetime 0;   # Deprecated address range
+        };
+
+        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";
+        };
+}
+
+
+

+

6.8 RIP +

+ +

Introduction

+ +

The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors) +distances to all networks it can reach. When a router hears distance to another network, it increments +it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes +unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus +interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in +RIP) and all routers know that network is unreachable. RIP tries to minimize situations where +counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use +RIP on networks where maximal distance is higher than 15 hosts. You can read more about RIP at +http://www.ietf.org/html.charters/rip-charter.html. Both IPv4 +(RFC 1723 +ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt) +and IPv6 (RFC 2080 +ftp://ftp.rfc-editor.org/in-notes/rfc2080.txt) versions of RIP are supported by BIRD, historical RIPv1 (RFC 1058 +ftp://ftp.rfc-editor.org/in-notes/rfc1058.txt)is +not currently supported. RIPv4 MD5 authentication (RFC 2082 +ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt) is supported. +

+

RIP is a very simple protocol, and it has a lot of shortcomings. Slow +convergence, big network load and inability to handle larger networks +makes it pretty much obsolete. (It is still usable on very small networks.) +

+

Configuration

+ +

In addition to options common for all to other protocols, RIP supports the following ones: +

+

+
authentication none|plaintext|md5

selects authentication method to be used. none means that +packets are not authenticated at all, plaintext means that a plaintext password is embedded +into each packet, and md5 means that packets are authenticated using a MD5 cryptographic +hash. If you set authentication to not-none, it is a good idea to add password +section. Default: none. +

+

honor always|neighbor|never

specifies when should requests for dumping routing table +be honored. (Always, when sent from a host on a directly connected +network or never.) Routing table updates are honored only from +neighbors, that is not configurable. Default: never. +

+

+

There are some options that can be specified per-interface: +

+

+
metric num

This option specifies the metric of the interface. Valid +

+

mode multicast|broadcast|quiet|nolisten|version1

This option selects the mode for RIP to work in. If nothing is +specified, RIP runs in multicast mode. version1 is +currently equivalent to broadcast, and it makes RIP talk +to a broadcast address even through multicast mode is +possible. quiet option means that RIP will not transmit +any periodic messages to this interface and nolisten +means that RIP will send to this interface butnot listen to it. +

+

ttl security [switch | tx only]

TTL security is a feature that protects routing protocols +from remote spoofed packets by using TTL 255 instead of TTL 1 +for protocol packets destined to neighbors. Because TTL is +decremented when packets are forwarded, it is non-trivial to +spoof packets with TTL 255 from remote locations. +

If this option is enabled, the router will send RIP packets +with TTL 255 and drop received packets with TTL less than +255. If this option si set to tx only, TTL 255 is used +for sent packets, but is not checked for received +packets. Such setting does not offer protection, but offers +compatibility with neighbors regardless of whether they use +ttl security. +

Note that for RIPng, TTL security is a standard behavior +(required by RFC 2080), but BIRD uses tx only by +default, for compatibility with older versions. For IPv4 RIP, +default value is no. +

+

tx class|dscp|priority num

These options specify the ToS/DiffServ/Traffic class/Priority +of the outgoing RIP packets. See +tx class common option for detailed description. +

+

+

The following options generally override behavior specified in RFC. If you use any of these +options, BIRD will no longer be RFC-compliant, which means it will not be able to talk to anything +other than equally configured BIRD. I have warned you. +

+

+
port number

selects IP port to operate on, default 520. (This is useful when testing BIRD, if you +set this to an address >1024, you will not need to run bird with UID==0). +

+

infinity number

selects the value of infinity, default is 16. Bigger values will make protocol convergence +even slower. +

+

period number

specifies the number of seconds between periodic updates. Default is 30 seconds. A lower +number will mean faster convergence but bigger network +load. Do not use values lower than 12. +

+

timeout time number

specifies how old route has to be to be considered unreachable. Default is 4*period. +

+

garbage time number

specifies how old route has to be to be discarded. Default is 10*period. +

+

+

Attributes

+ +

RIP defines two route attributes: +

+

+
int rip_metric

RIP metric of the route (ranging from 0 to infinity). +When routes from different RIP instances are available and all of them have the same +preference, BIRD prefers the route with lowest rip_metric. +When importing a non-RIP route, the metric defaults to 5. +

+

int rip_tag

RIP route tag: a 16-bit number which can be used +to carry additional information with the route (for example, an originating AS number +in case of external routes). When importing a non-RIP route, the tag defaults to 0. +

+

+

Example

+ +

+

+
+protocol rip MyRIP_test {
+        debug all;
+        port 1520;
+        period 12;
+        garbage time 60;
+        interface "eth0" { metric 3; mode multicast; };
+        interface "eth*" { metric 2; mode broadcast; };
+        honor neighbor;
+        authentication none;
+        import filter { print "importing"; accept; };
+        export filter { print "exporting"; accept; };
+}
+
+
+

+

6.9 Static +

+ +

The Static protocol doesn't communicate with other routers in the network, +but instead it allows you to define routes manually. This is often used for +specifying how to forward packets to parts of the network which don't use +dynamic routing at all and also for defining sink routes (i.e., those +telling to return packets as undeliverable if they are in your IP block, +you don't have any specific destination for them and you don't want to send +them out through the default route to prevent routing loops). +

+

There are five types of static routes: `classical' routes telling +to forward packets to a neighboring router, multipath routes +specifying several (possibly weighted) neighboring routers, device +routes specifying forwarding to hosts on a directly connected network, +recursive routes computing their nexthops by doing route table lookups +for a given IP and special routes (sink, blackhole etc.) which specify +a special action to be done instead of forwarding the packet. +

+

When the particular destination is not available (the interface is down or +the next hop of the route is not a neighbor at the moment), Static just +uninstalls the route from the table it is connected to and adds it again as soon +as the destination becomes adjacent again. +

+

The Static protocol does not have many configuration options. The +definition of the protocol contains mainly a list of static routes: +

+

+
route prefix via ip

Static route through +a neighboring router. +

route prefix multipath via ip [weight num] [via ...]

Static multipath route. Contains several nexthops (gateways), possibly +with their weights. +

route prefix via "interface"

Static device +route through an interface to hosts on a directly connected network. +

route prefix recursive ip

Static recursive route, +its nexthop depends on a route table lookup for given IP address. +

route prefix blackhole|unreachable|prohibit

Special routes +specifying to silently drop the packet, return it as unreachable or return +it as administratively prohibited. First two targets are also known +as drop and reject. +

+

check link switch

If set, hardware link states of network interfaces are taken +into consideration. When link disappears (e.g. ethernet cable +is unplugged), static routes directing to that interface are +removed. It is possible that some hardware drivers or +platforms do not implement this feature. Default: off. +

+

igp table name

Specifies a table that is used +for route table lookups of recursive routes. Default: the +same table as the protocol is connected to. +

+

+

Static routes have no specific attributes. +

+

Example static config might look like this: +

+

+

+
+protocol static {
+        table testable;                  # Connect to a non-default routing table
+        route 0.0.0.0/0 via 198.51.100.130; # Default route
+        route 10.0.0.0/8 multipath       # Multipath route
+                via 198.51.100.10 weight 2
+                via 198.51.100.20
+                via 192.0.2.1;
+        route 203.0.113.0/24 unreachable; # Sink route
+        route 10.2.0.0/24 via "arc0";    # Secondary network
+}
+
+
+

+

+Next +Previous +Contents + + From b0a8c7fc8547eef21ede33887580b5e867ee742c Mon Sep 17 00:00:00 2001 From: Ondrej Filip Date: Thu, 15 Aug 2013 20:26:50 +0200 Subject: [PATCH 4/4] Wrong change commited - 'route limit' marked as obsolete. --- doc/bird-6.html | 1731 ----------------------------------------------- doc/bird.sgml | 5 +- 2 files changed, 3 insertions(+), 1733 deletions(-) delete mode 100644 doc/bird-6.html diff --git a/doc/bird-6.html b/doc/bird-6.html deleted file mode 100644 index d21209ee..00000000 --- a/doc/bird-6.html +++ /dev/null @@ -1,1731 +0,0 @@ - - - - - BIRD User's Guide: Protocols - - - - - -Next -Previous -Contents -
-

6. Protocols

- -

6.1 BGP -

- -

The Border Gateway Protocol is the routing protocol used for backbone -level routing in the today's Internet. Contrary to the other protocols, its convergence -doesn't rely on all routers following the same rules for route selection, -making it possible to implement any routing policy at any router in the -network, the only restriction being that if a router advertises a route, -it must accept and forward packets according to it. -

-

BGP works in terms of autonomous systems (often abbreviated as -AS). Each AS is a part of the network with common management and -common routing policy. It is identified by a unique 16-bit number -(ASN). Routers within each AS usually exchange AS-internal routing -information with each other using an interior gateway protocol (IGP, -such as OSPF or RIP). Boundary routers at the border of -the AS communicate global (inter-AS) network reachability information with -their neighbors in the neighboring AS'es via exterior BGP (eBGP) and -redistribute received information to other routers in the AS via -interior BGP (iBGP). -

-

Each BGP router sends to its neighbors updates of the parts of its -routing table it wishes to export along with complete path information -(a list of AS'es the packet will travel through if it uses the particular -route) in order to avoid routing loops. -

-

BIRD supports all requirements of the BGP4 standard as defined in -RFC 4271 -ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt -It also supports the community attributes -(RFC 1997 -ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt), -capability negotiation -(RFC 3392 -ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt), -MD5 password authentication -(RFC 2385 -ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt), -extended communities -(RFC 4360 -ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt), -route reflectors -(RFC 4456 -ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt), -multiprotocol extensions -(RFC 4760 -ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt), -4B AS numbers -(RFC 4893 -ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt), -and 4B AS numbers in extended communities -(RFC 5668 -ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt). -

-

For IPv6, it uses the standard multiprotocol extensions defined in -RFC 2283 -ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt -including changes described in the -latest draft -ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt -and applied to IPv6 according to -RFC 2545 -ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt. -

-

Route selection rules

- -

BGP doesn't have any simple metric, so the rules for selection of an optimal -route among multiple BGP routes with the same preference are a bit more complex -and they are implemented according to the following algorithm. It starts the first -rule, if there are more "best" routes, then it uses the second rule to choose -among them and so on. -

-

    -
  • Prefer route with the highest Local Preference attribute.
    • -
  • Prefer route with the shortest AS path.
    • -
  • Prefer IGP origin over EGP and EGP origin over incomplete.
    • -
  • Prefer the lowest value of the Multiple Exit Discriminator.
    • -
  • Prefer routes received via eBGP over ones received via iBGP.
    • -
  • Prefer routes with lower internal distance to a boundary router.
    • -
  • Prefer the route with the lowest value of router ID of the -advertising router.
    • -
-

-

IGP routing table

- -

BGP is mainly concerned with global network reachability and with -routes to other autonomous systems. When such routes are redistributed -to routers in the AS via BGP, they contain IP addresses of a boundary -routers (in route attribute NEXT_HOP). BGP depends on existing IGP -routing table with AS-internal routes to determine immediate next hops -for routes and to know their internal distances to boundary routers -for the purpose of BGP route selection. In BIRD, there is usually -one routing table used for both IGP routes and BGP routes. -

-

Configuration

- -

Each instance of the BGP corresponds to one neighboring router. -This allows to set routing policy and all the other parameters differently -for each neighbor using the following configuration parameters: -

-

-
local [ip] as number

Define which AS we -are part of. (Note that contrary to other IP routers, BIRD is -able to act as a router located in multiple AS'es -simultaneously, but in such cases you need to tweak the BGP -paths manually in the filters to get consistent behavior.) -Optional ip argument specifies a source address, -equivalent to the source address option (see below). -This parameter is mandatory. -

-

neighbor ip as number

Define neighboring router -this instance will be talking to and what AS it's located in. Unless -you use the multihop clause, it must be directly connected to one -of your router's interfaces. In case the neighbor is in the same AS -as we are, we automatically switch to iBGP. This parameter is mandatory. -

-

multihop [number]

Configure multihop BGP -session to a neighbor that isn't directly connected. -Accurately, this option should be used if the configured -neighbor IP address does not match with any local network -subnets. Such IP address have to be reachable through system -routing table. For multihop BGP it is recommended to -explicitly configure source address to have it -stable. Optional number argument can be used to specify -the number of hops (used for TTL). Note that the number of -networks (edges) in a path is counted, i.e. if two BGP -speakers are separated by one router, the number of hops is -2. Default: switched off. -

-

source address ip

Define local address we -should use for next hop calculation and as a source address -for the BGP session. Default: the address of the local -end of the interface our neighbor is connected to. -

-

next hop self

Avoid calculation of the Next Hop -attribute and always advertise our own source address as a -next hop. This needs to be used only occasionally to -circumvent misconfigurations of other routers. Default: -disabled. -

-

next hop keep

Forward the received Next Hop -attribute even in situations where the local address should be -used instead, like when the route is sent to an interface with -a different subnet. Default: disabled. -

-

missing lladdr self|drop|ignore

Next Hop attribute -in BGP-IPv6 sometimes contains just the global IPv6 address, -but sometimes it has to contain both global and link-local -IPv6 addresses. This option specifies what to do if BIRD have -to send both addresses but does not know link-local address. -This situation might happen when routes from other protocols -are exported to BGP, or when improper updates are received -from BGP peers. self means that BIRD advertises its own -local address instead. drop means that BIRD skips that -prefixes and logs error. ignore means that BIRD ignores -the problem and sends just the global address (and therefore -forms improper BGP update). Default: self, unless BIRD -is configured as a route server (option rs client), in -that case default is ignore, because route servers usually -do not forward packets themselves. -

-

gateway direct|recursive

For received routes, their -gw (immediate next hop) attribute is computed from -received bgp_next_hop attribute. This option specifies -how it is computed. Direct mode means that the IP address from -bgp_next_hop is used if it is directly reachable, -otherwise the neighbor IP address is used. Recursive mode -means that the gateway is computed by an IGP routing table -lookup for the IP address from bgp_next_hop. Recursive -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. Recursive -mode is incompatible with -sorted tables. Default: direct for singlehop eBGP, -recursive otherwise. -

-

igp table name

Specifies a table that is used -as an IGP routing table. Default: the same as the table BGP is -connected to. -

-

ttl security switch

Use GTSM (RFC 5082 - the -generalized TTL security mechanism). GTSM protects against -spoofed packets by ignoring received packets with a smaller -than expected TTL. To work properly, GTSM have to be enabled -on both sides of a BGP session. If both ttl security and -multihop options are enabled, multihop option should -specify proper hop value to compute expected TTL. Kernel -support required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: -since long ago, IPv4 only. Note that full (ICMP protection, -for example) RFC 5082 support is provided by Linux -only. Default: disabled. -

-

password string

Use this password for MD5 authentication -of BGP sessions. Default: no authentication. Password has to be set by -external utility (e.g. setkey(8)) on BSD systems. -

-

passive switch

Standard BGP behavior is both -initiating outgoing connections and accepting incoming -connections. In passive mode, outgoing connections are not -initiated. Default: off. -

-

rr client

Be a route reflector and treat the neighbor as -a route reflection client. Default: disabled. -

-

rr cluster id IPv4 address

Route reflectors use cluster id -to avoid route reflection loops. When there is one route reflector in a cluster -it usually uses its router id as a cluster id, but when there are more route -reflectors in a cluster, these need to be configured (using this option) to -use a common cluster id. Clients in a cluster need not know their cluster -id and this option is not allowed for them. Default: the same as router id. -

-

rs client

Be a route server and treat the neighbor -as a route server client. A route server is used as a -replacement for full mesh EBGP routing in Internet exchange -points in a similar way to route reflectors used in IBGP routing. -BIRD does not implement obsoleted RFC 1863, but uses ad-hoc implementation, -which behaves like plain EBGP but reduces modifications to advertised route -attributes to be transparent (for example does not prepend its AS number to -AS PATH attribute and keeps MED attribute). Default: disabled. -

-

secondary switch

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 -sorted. Default: off. -

-

enable route refresh switch

When BGP speaker -changes its import filter, it has to re-examine all routes -received from its neighbor against the new filter. As these -routes might not be available, there is a BGP protocol -extension Route Refresh (specified in RFC 2918) that allows -BGP speaker to request re-advertisement of all routes from its -neighbor. This option specifies whether BIRD advertises this -capability and accepts such requests. Even when disabled, BIRD -can send route refresh requests. Default: on. -

-

interpret communities switch

RFC 1997 demands -that BGP speaker should process well-known communities like -no-export (65535, 65281) or no-advertise (65535, 65282). For -example, received route carrying a no-adverise community -should not be advertised to any of its neighbors. If this -option is enabled (which is by default), BIRD has such -behavior automatically (it is evaluated when a route is -exported to the BGP protocol just before the export filter). -Otherwise, this integrated processing of well-known -communities is disabled. In that case, similar behavior can be -implemented in the export filter. Default: on. -

-

enable as4 switch

BGP protocol was designed to use 2B AS numbers -and was extended later to allow 4B AS number. BIRD supports 4B AS extension, -but by disabling this option it can be persuaded not to advertise it and -to maintain old-style sessions with its neighbors. This might be useful for -circumventing bugs in neighbor's implementation of 4B AS extension. -Even when disabled (off), BIRD behaves internally as AS4-aware BGP router. -Default: on. -

-

capabilities switch

Use capability advertisement -to advertise optional capabilities. This is standard behavior -for newer BGP implementations, but there might be some older -BGP implementations that reject such connection attempts. -When disabled (off), features that request it (4B AS support) -are also disabled. Default: on, with automatic fallback to -off when received capability-related error. -

-

advertise ipv4 switch

Advertise IPv4 multiprotocol capability. -This is not a correct behavior according to the strict interpretation -of RFC 4760, but it is widespread and required by some BGP -implementations (Cisco and Quagga). This option is relevant -to IPv4 mode with enabled capability advertisement only. Default: on. -

-

route limit number

The maximal number of routes -that may be imported from the protocol. If the route limit is -exceeded, the connection is closed with an error. Limit is currently implemented as -import limit number action restart. This option is obsolete and it is -replaced by -import limit option. Default: no limit. -

-

disable after error switch

When an error is encountered (either -locally or by the other side), disable the instance automatically -and wait for an administrator to fix the problem manually. Default: off. -

-

hold time number

Time in seconds to wait for a Keepalive -message from the other side before considering the connection stale. -Default: depends on agreement with the neighboring router, we prefer -240 seconds if the other side is willing to accept it. -

-

startup hold time number

Value of the hold timer used -before the routers have a chance to exchange open messages and agree -on the real value. Default: 240 seconds. -

-

keepalive time number

Delay in seconds between sending -of two consecutive Keepalive messages. Default: One third of the hold time. -

-

connect retry time number

Time in seconds to wait before -retrying a failed attempt to connect. Default: 120 seconds. -

-

start delay time number

Delay in seconds between protocol -startup and the first attempt to connect. Default: 5 seconds. -

-

error wait time number,number

Minimum and maximum delay in seconds between a protocol -failure (either local or reported by the peer) and automatic restart. -Doesn't apply when disable after error is configured. If consecutive -errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300. -

-

error forget time number

Maximum time in seconds between two protocol -failures to treat them as a error sequence which makes the error wait time -increase exponentially. Default: 300 seconds. -

-

path metric switch

Enable comparison of path lengths -when deciding which BGP route is the best one. Default: on. -

-

med metric switch

Enable comparison of MED -attributes (during best route selection) even between routes -received from different ASes. This may be useful if all MED -attributes contain some consistent metric, perhaps enforced in -import filters of AS boundary routers. If this option is -disabled, MED attributes are compared only if routes are -received from the same AS (which is the standard behavior). -Default: off. -

-

deterministic med switch

BGP route selection -algorithm is often viewed as a comparison between individual -routes (e.g. if a new route appears and is better than the -current best one, it is chosen as the new best one). But the -proper route selection, as specified by RFC 4271, cannot be -fully implemented in that way. The problem is mainly in -handling the MED attribute. BIRD, by default, uses an -simplification based on individual route comparison, which in -some cases may lead to temporally dependent behavior (i.e. the -selection is dependent on the order in which routes appeared). -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 med metric option. This option is -incompatible with -sorted tables. -Default: off. -

-

igp metric switch

Enable comparison of internal -distances to boundary routers during best route selection. Default: on. -

-

prefer older switch

Standard route selection algorithm -breaks ties by comparing router IDs. This changes the behavior -to prefer older routes (when both are external and from different -peer). For details, see RFC 5004. Default: off. -

-

default bgp_med number

Value of the Multiple Exit -Discriminator to be used during route selection when the MED attribute -is missing. Default: 0. -

-

default bgp_local_pref number

A default value -for the Local Preference attribute. It is used when a new -Local Preference attribute is attached to a route by the BGP -protocol itself (for example, if a route is received through -eBGP and therefore does not have such attribute). Default: 100 -(0 in pre-1.2.0 versions of BIRD). -

-

-

Attributes

- -

BGP defines several route attributes. Some of them (those marked with `I' in the -table below) are available on internal BGP connections only, some of them (marked -with `O') are optional. -

-

-
bgppath bgp_path

Sequence of AS numbers describing the AS path -the packet will travel through when forwarded according to the particular route. -In case of internal BGP it doesn't contain the number of the local AS. -

-

int bgp_local_pref [I]

Local preference value used for -selection among multiple BGP routes (see the selection rules above). It's -used as an additional metric which is propagated through the whole local AS. -

-

int bgp_med [O]

The Multiple Exit Discriminator of the route -is an optional attribute which is used on external (inter-AS) links to -convey to an adjacent AS the optimal entry point into the local AS. -The received attribute is also propagated over internal BGP links. -The attribute value is zeroed when a route is exported to an external BGP -instance to ensure that the attribute received from a neighboring AS is -not propagated to other neighboring ASes. A new value might be set in -the export filter of an external BGP instance. -See RFC 4451 -ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt -for further discussion of BGP MED attribute. -

-

enum bgp_origin

Origin of the route: either ORIGIN_IGP -if the route has originated in an interior routing protocol or -ORIGIN_EGP if it's been imported from the EGP protocol -(nowadays it seems to be obsolete) or ORIGIN_INCOMPLETE if the origin -is unknown. -

-

ip bgp_next_hop

Next hop to be used for forwarding of packets -to this destination. On internal BGP connections, it's an address of the -originating router if it's inside the local AS or a boundary router the -packet will leave the AS through if it's an exterior route, so each BGP -speaker within the AS has a chance to use the shortest interior path -possible to this point. -

-

void bgp_atomic_aggr [O]

This is an optional attribute -which carries no value, but the sole presence of which indicates that the route -has been aggregated from multiple routes by some router on the path from -the originator. -

-

clist bgp_community [O]

List of community values associated -with the route. Each such value is a pair (represented as a pair data -type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines -the community and the second one being a per-AS identifier. There are lots -of uses of the community mechanism, but generally they are used to carry -policy information like "don't export to USA peers". As each AS can define -its own routing policy, it also has a complete freedom about which community -attributes it defines and what will their semantics be. -

-

eclist bgp_ext_community [O]

List of extended community -values associated with the route. Extended communities have similar usage -as plain communities, but they have an extended range (to allow 4B ASNs) -and a nontrivial structure with a type field. Individual community values are -represented using an ec data type inside the filters. -

-

quad bgp_originator_id [I, O]

This attribute is created by the -route reflector when reflecting the route and contains the router ID of the -originator of the route in the local AS. -

-

clist bgp_cluster_list [I, O]

This attribute contains a list -of cluster IDs of route reflectors. Each route reflector prepends its -cluster ID when reflecting the route. -

-

-

Example

- -

-

-
-protocol bgp {
-        local as 65000;                      # Use a private AS number
-        neighbor 198.51.100.130 as 64496;    # Our neighbor ...
-        multihop;                            # ... which is connected indirectly
-        export filter {                      # We use non-trivial export rules
-                if source = RTS_STATIC then { # Export only static routes
-                        # Assign our community
-                        bgp_community.add((65000,64501));
-                        # Artificially increase path length
-                        # by advertising local AS number twice
-                        if bgp_path ~ [= 65000 =] then
-                                bgp_path.prepend(65000);
-                        accept;
-                }
-                reject;
-        };
-        import all;
-        source address 198.51.100.14;   # Use a non-standard source address
-}
-
-
-

-

6.2 Device -

- -

The Device protocol is not a real routing protocol. It doesn't generate -any routes and it only serves as a module for getting information about network -interfaces from the kernel. -

-

Except for very unusual circumstances, you probably should include -this protocol in the configuration since almost all other protocols -require network interfaces to be defined for them to work with. -

-

Configuration

- -

-

-
scan time number

Time in seconds between two scans -of the network interface list. On systems where we are notified about -interface status changes asynchronously (such as newer versions of -Linux), we need to scan the list only in order to avoid confusion by lost -notification messages, so the default time is set to a large value. -

-

primary [ "mask" ] prefix

If a network interface has more than one network address, BIRD -has to choose one of them as a primary one. By default, BIRD -chooses the lexicographically smallest address as the primary -one. -

This option allows to specify which network address should be -chosen as a primary one. Network addresses that match -prefix are preferred to non-matching addresses. If more -primary options are used, the first one has the highest -preference. If "mask" is specified, then such -primary option is relevant only to matching network -interfaces. -

In all cases, an address marked by operating system as -secondary cannot be chosen as the primary one. -

-

-

As the Device protocol doesn't generate any routes, it cannot have -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;
-}
-
-
-

-

6.3 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 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 networks by itself so we don't need (and don't -want) to export these routes to the kernel protocol. OSPF protocol -creates device routes for its interfaces itself and BGP protocol is -usually used for exporting aggregate routes. Although there are some -use cases that use the direct protocol (like abusing eBGP as an IGP -routing protocol), in most cases it is not needed to have these device -routes in BIRD routing table and to use the direct protocol. -

-

There is one notable case when you definitely want to use the -direct protocol -- running BIRD on BSD systems. Having high priority -device routes for directly connected networks from the direct protocol -protects kernel device routes from being overwritten or removed by IGP -routes during some transient network conditions, because a lower -priority IGP route for the same network is not exported to the kernel -routing table. This is an issue on BSD systems only, as on Linux -systems BIRD cannot change non-BIRD route in the kernel routing table. -

-

The only configurable thing about direct is what interfaces it watches: -

-

-

-
interface pattern [, ...]

By default, the Direct -protocol will generate device routes for all the interfaces -available. If you want to restrict it to some subset of interfaces -(for example if you're using multiple routing tables for policy -routing and some of the policy domains don't contain all interfaces), -just use this clause. -

-

-

Direct device routes don't contain any specific attributes. -

-

Example config might look like this: -

-

-

-
-protocol direct {
-        interface "-arc*", "*";         # Exclude the ARCnets
-}
-
-
-

-

6.4 Kernel -

- -

The Kernel protocol is not a real routing protocol. Instead of communicating -with other routers in the network, it performs synchronization of BIRD's routing -tables with the OS kernel. Basically, it sends all routing table updates to the kernel -and from time to time it scans the kernel tables to see whether some routes have -disappeared (for example due to unnoticed up/down transition of an interface) -or whether an `alien' route has been added by someone else (depending on the -learn switch, such routes are either ignored or accepted to our -table). -

-

Unfortunately, there is one thing that makes the routing table -synchronization a bit more complicated. In the kernel routing table -there are also device routes for directly connected networks. These -routes are usually managed by OS itself (as a part of IP address -configuration) and we don't want to touch that. They are completely -ignored during the scan of the kernel tables and also the export of -device routes from BIRD tables to kernel routing tables is restricted -to prevent accidental interference. This restriction can be disabled using -device routes switch. -

-

If your OS supports only a single routing table, you can configure -only one instance of the Kernel protocol. If it supports multiple -tables (in order to allow policy routing; such an OS is for example -Linux), you can run as many instances as you want, but each of them -must be connected to a different BIRD routing table and to a different -kernel table. -

-

Because the kernel protocol is partially integrated with the -connected routing table, there are two limitations - it is not -possible to connect more kernel protocols to the same routing table -and changing route destination/gateway in an export -filter of a kernel protocol does not work. Both limitations can be -overcome using another routing table and the pipe protocol. -

-

Configuration

- -

-

-
persist switch

Tell BIRD to leave all its routes in the -routing tables when it exits (instead of cleaning them up). -

scan time number

Time in seconds between two consecutive scans of the -kernel routing table. -

learn switch

Enable learning of routes added to the kernel -routing tables by other routing daemons or by the system administrator. -This is possible only on systems which support identification of route -authorship. -

-

device routes switch

Enable export of device -routes to the kernel routing table. By default, such routes -are rejected (with the exception of explicitly configured -device routes from the static protocol) regardless of the -export filter to protect device routes in kernel routing table -(managed by OS itself) from accidental overwriting or erasing. -

-

kernel table number

Select which kernel table should -this particular instance of the Kernel protocol work with. Available -only on systems supporting multiple routing tables. -

-

-

Attributes

- -

The Kernel protocol defines several attributes. These attributes -are translated to appropriate system (and OS-specific) route attributes. -We support these attributes: -

-

-
int krt_source

The original source of the imported -kernel route. The value is system-dependent. On Linux, it is -a value of the protocol field of the route. See -/etc/iproute2/rt_protos for common values. On BSD, it is -based on STATIC and PROTOx flags. The attribute is read-only. -

-

int krt_metric

The kernel metric of -the route. When multiple same routes are in a kernel routing -table, the Linux kernel chooses one with lower metric. -

-

ip krt_prefsrc

(Linux) The preferred source address. -Used in source address selection for outgoing packets. Have to -be one of IP addresses of the router. -

-

int krt_realm

(Linux) The realm of the route. Can be -used for traffic classification. -

-

-

Example

- -

A simple configuration can look this way: -

-

-

-
-protocol kernel {
-        export all;
-}
-
-
-

-

Or for a system with two routing tables: -

-

-

-
-protocol kernel {               # Primary routing table
-        learn;                  # Learn alien routes from the kernel
-        persist;                # Don't remove routes on bird shutdown
-        scan time 10;           # Scan kernel routing table every 10 seconds
-        import all;
-        export all;
-}
-
-protocol kernel {               # Secondary routing table
-        table auxtable;
-        kernel table 100;
-        export all;
-}
-
-
-

-

6.5 OSPF -

- -

Introduction

- -

Open Shortest Path First (OSPF) is a quite complex interior gateway -protocol. The current IPv4 version (OSPFv2) is defined in RFC -2328 -ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt and -the current IPv6 version (OSPFv3) is defined in RFC 5340 -ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt It's a link state -(a.k.a. shortest path first) protocol -- each router maintains a -database describing the autonomous system's topology. Each participating -router has an identical copy of the database and all routers run the -same algorithm calculating a shortest path tree with themselves as a -root. OSPF chooses the least cost path as the best path. -

-

In OSPF, the autonomous system can be split to several areas in order -to reduce the amount of resources consumed for exchanging the routing -information and to protect the other areas from incorrect routing data. -Topology of the area is hidden to the rest of the autonomous system. -

-

Another very important feature of OSPF is that -it can keep routing information from other protocols (like Static or BGP) -in its link state database as external routes. Each external route can -be tagged by the advertising router, making it possible to pass additional -information between routers on the boundary of the autonomous system. -

-

OSPF quickly detects topological changes in the autonomous system (such -as router interface failures) and calculates new loop-free routes after a short -period of convergence. Only a minimal amount of -routing traffic is involved. -

-

Each router participating in OSPF routing periodically sends Hello messages -to all its interfaces. This allows neighbors to be discovered dynamically. -Then the neighbors exchange theirs parts of the link state database and keep it -identical by flooding updates. The flooding process is reliable and ensures -that each router detects all changes. -

-

Configuration

- -

In the main part of configuration, there can be multiple definitions of -OSPF areas, each with a different id. These definitions includes many other -switches and multiple definitions of interfaces. Definition of interface -may contain many switches and constant definitions and list of neighbors -on nonbroadcast networks. -

-

-
-protocol ospf <name> {
-        rfc1583compat <switch>;
-        stub router <switch>;
-        tick <num>;
-        ecmp <switch> [limit <num>];
-        area <id> {
-                stub;
-                nssa;
-                summary <switch>;
-                default nssa <switch>;
-                default cost <num>;
-                default cost2 <num>;
-                translator <switch>;
-                translator stability <num>;
-
-                networks {
-                        <prefix>;
-                        <prefix> hidden;
-                }
-                external {
-                        <prefix>;
-                        <prefix> hidden;
-                        <prefix> tag <num>;
-                }
-                stubnet <prefix>;
-                stubnet <prefix> {
-                        hidden <switch>;
-                        summary <switch>;
-                        cost <num>;
-                }
-                interface <interface pattern> [instance <num>] {
-                        cost <num>;
-                        stub <switch>;
-                        hello <num>;
-                        poll <num>;
-                        retransmit <num>;
-                        priority <num>;
-                        wait <num>;
-                        dead count <num>;
-                        dead <num>;
-                        rx buffer [normal|large|<num>];
-                        type [broadcast|bcast|pointopoint|ptp|
-                                nonbroadcast|nbma|pointomultipoint|ptmp];
-                        strict nonbroadcast <switch>;
-                        real broadcast <switch>;
-                        ptp netmask <switch>;
-                        check link <switch>;
-                        ecmp weight <num>;
-                        ttl security [<switch>; | tx only]
-                        tx class|dscp <num>;
-                        tx priority <num>;
-                        authentication [none|simple|cryptographic];
-                        password "<text>";
-                        password "<text>" {
-                                id <num>;
-                                generate from "<date>";
-                                generate to "<date>";
-                                accept from "<date>";
-                                accept to "<date>";
-                        };
-                        neighbors {
-                                <ip>;
-                                <ip> eligible;
-                        };
-                };
-                virtual link <id> [instance <num>] {
-                        hello <num>;
-                        retransmit <num>;
-                        wait <num>;
-                        dead count <num>;
-                        dead <num>;
-                        authentication [none|simple|cryptographic];
-                        password "<text>";
-                };
-        };
-}
-
-
-

-

-
rfc1583compat switch

This option controls compatibility of routing table -calculation with RFC 1583 -ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt. Default -value is no. -

-

stub router switch

This option configures the router to be a stub router, i.e., -a router that participates in the OSPF topology but does not -allow transit traffic. In OSPFv2, this is implemented by -advertising maximum metric for outgoing links, as suggested -by RFC 3137 -ftp://ftp.rfc-editor.org/in-notes/rfc3137.txt. -In OSPFv3, the stub router behavior is announced by clearing -the R-bit in the router LSA. Default value is no. -

-

tick num

The routing table calculation and clean-up of areas' databases -is not performed when a single link state -change arrives. To lower the CPU utilization, it's processed later -at periodical intervals of num seconds. The default value is 1. -

-

ecmp switch [limit number]

This option specifies whether OSPF is allowed to generate -ECMP (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 maximal number of nexthops in one route. By -default, ECMP is disabled. If enabled, default value of the -limit is 16. -

-

area id

This defines an OSPF area with given area ID (an integer or an IPv4 -address, similarly to a router ID). The most important area is -the backbone (ID 0) to which every other area must be connected. -

-

stub

This option configures the area to be a stub area. External -routes are not flooded into stub areas. Also summary LSAs can be -limited in stub areas (see option summary). -By default, the area is not a stub area. -

-

nssa

This option configures the area to be a NSSA (Not-So-Stubby -Area). NSSA is a variant of a stub area which allows a -limited way of external route propagation. Global external -routes are not propagated into a NSSA, but an external route -can be imported into NSSA as a (area-wide) NSSA-LSA (and -possibly translated and/or aggregated on area boundary). -By default, the area is not NSSA. -

-

summary switch

This option controls propagation of summary LSAs into stub or -NSSA areas. If enabled, summary LSAs are propagated as usual, -otherwise just the default summary route (0.0.0.0/0) is -propagated (this is sometimes called totally stubby area). If -a stub area has more area boundary routers, propagating -summary LSAs could lead to more efficient routing at the cost -of larger link state database. Default value is no. -

-

default nssa switch

When summary option is enabled, default summary route is -no longer propagated to the NSSA. In that case, this option -allows to originate default route as NSSA-LSA to the NSSA. -Default value is no. -

-

default cost num

This option controls the cost of a default route propagated to -stub and NSSA areas. Default value is 1000. -

-

default cost2 num

When a default route is originated as NSSA-LSA, its cost -can use either type 1 or type 2 metric. This option allows -to specify the cost of a default route in type 2 metric. -By default, type 1 metric (option default cost) is used. -

-

translator switch

This option controls translation of NSSA-LSAs into external -LSAs. By default, one translator per NSSA is automatically -elected from area boundary routers. If enabled, this area -boundary router would unconditionally translate all NSSA-LSAs -regardless of translator election. Default value is no. -

-

translator stability num

This option controls the translator stability interval (in -seconds). When the new translator is elected, the old one -keeps translating until the interval is over. Default value -is 40. -

-

networks { set }

Definition of area IP ranges. This is used in summary LSA origination. -Hidden networks are not propagated into other areas. -

-

external { set }

Definition of external area IP ranges for NSSAs. This is used -for NSSA-LSA translation. Hidden networks are not translated -into external LSAs. Networks can have configured route tag. -

-

stubnet prefix { options }

Stub networks are networks that are not transit networks -between OSPF routers. They are also propagated through an -OSPF area as a part of a link state database. By default, -BIRD generates a stub network record for each primary network -address on each OSPF interface that does not have any OSPF -neighbors, and also for each non-primary network address on -each OSPF interface. This option allows to alter a set of -stub networks propagated by this router. -

Each instance of this option adds a stub network with given -network prefix to the set of propagated stub network, unless -option hidden is used. It also suppresses default stub -networks for given network prefix. When option -summary is used, also default stub networks that are -subnetworks of given stub network are suppressed. This might -be used, for example, to aggregate generated stub networks. -

-

interface pattern [instance num]

Defines that the specified interfaces belong to the area being defined. -See -interface common option for detailed description. -In OSPFv3, you can specify instance ID for that interface -description, so it is possible to have several instances of -that interface with different options or even in different areas. -

-

virtual link id [instance num]

Virtual link to router with the router id. Virtual link acts -as a point-to-point interface belonging to backbone. The -actual area is used as transport area. This item cannot be in -the backbone. In OSPFv3, you could also use several virtual -links to one destination with different instance IDs. -

-

cost num

Specifies output cost (metric) of an interface. Default value is 10. -

-

stub switch

If set to interface it does not listen to any packet and does not send -any hello. Default value is no. -

-

hello num

Specifies interval in seconds between sending of Hello messages. Beware, all -routers on the same network need to have the same hello interval. -Default value is 10. -

-

poll num

Specifies interval in seconds between sending of Hello messages for -some neighbors on NBMA network. Default value is 20. -

-

retransmit num

Specifies interval in seconds between retransmissions of unacknowledged updates. -Default value is 5. -

-

priority num

On every multiple access network (e.g., the Ethernet) Designed Router -and Backup Designed router are elected. These routers have some -special functions in the flooding process. Higher priority increases -preferences in this election. Routers with priority 0 are not -eligible. Default value is 1. -

-

wait num

After start, router waits for the specified number of seconds between starting -election and building adjacency. Default value is 40. -

-

dead count num

When the router does not receive any messages from a neighbor in -dead count*hello seconds, it will consider the neighbor down. -

-

dead num

When the router does not receive any messages from a neighbor in -dead seconds, it will consider the neighbor down. If both directives -dead count and dead are used, dead has precendence. -

-

rx buffer num

This sets the size of buffer used for receiving packets. The buffer should -be bigger than maximal size of any packets. Value NORMAL (default) -means 2*MTU, value LARGE means maximal allowed packet - 65535. -

-

type broadcast|bcast

BIRD detects a type of a connected network automatically, but -sometimes it's convenient to force use of a different type -manually. On broadcast networks (like ethernet), flooding -and Hello messages are sent using multicasts (a single packet -for all the neighbors). A designated router is elected and it -is responsible for synchronizing the link-state databases and -originating network LSAs. This network type cannot be used on -physically NBMA networks and on unnumbered networks (networks -without proper IP prefix). -

-

type pointopoint|ptp

Point-to-point networks connect just 2 routers together. No -election is performed and no network LSA is originated, which -makes it simpler and faster to establish. This network type -is useful not only for physically PtP ifaces (like PPP or -tunnels), but also for broadcast networks used as PtP links. -This network type cannot be used on physically NBMA networks. -

-

type nonbroadcast|nbma

On NBMA networks, the packets are sent to each neighbor -separately because of lack of multicast capabilities. -Like on broadcast networks, a designated router is elected, -which plays a central role in propagation of LSAs. -This network type cannot be used on unnumbered networks. -

-

type pointomultipoint|ptmp

This is another network type designed to handle NBMA -networks. In this case the NBMA network is treated as a -collection of PtP links. This is useful if not every pair of -routers on the NBMA network has direct communication, or if -the NBMA network is used as an (possibly unnumbered) PtP -link. -

-

strict nonbroadcast switch

If set, don't send hello to any undefined neighbor. This switch -is ignored on other than NBMA or PtMP networks. Default value is no. -

-

real broadcast switch

In type broadcast or type ptp network -configuration, OSPF packets are sent as IP multicast -packets. This option changes the behavior to using -old-fashioned IP broadcast packets. This may be useful as a -workaround if IP multicast for some reason does not work or -does not work reliably. This is a non-standard option and -probably is not interoperable with other OSPF -implementations. Default value is no. -

-

ptp netmask switch

In type ptp network configurations, OSPFv2 -implementations should ignore received netmask field in hello -packets and should send hello packets with zero netmask field -on unnumbered PtP links. But some OSPFv2 implementations -perform netmask checking even for PtP links. This option -specifies whether real netmask will be used in hello packets -on type ptp interfaces. You should ignore this option -unless you meet some compatibility problems related to this -issue. Default value is no for unnumbered PtP links, yes -otherwise. -

-

check link switch

If set, a hardware link state (reported by OS) is taken into -consideration. When a link disappears (e.g. an ethernet cable is -unplugged), neighbors 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. -

-

ttl security [switch | tx only]

TTL security is a feature that protects routing protocols -from remote spoofed packets by using TTL 255 instead of TTL 1 -for protocol packets destined to neighbors. Because TTL is -decremented when packets are forwarded, it is non-trivial to -spoof packets with TTL 255 from remote locations. Note that -this option would interfere with OSPF virtual links. -

If this option is enabled, the router will send OSPF packets -with TTL 255 and drop received packets with TTL less than -255. If this option si set to tx only, TTL 255 is used -for sent packets, but is not checked for received -packets. Default value is no. -

-

tx class|dscp|priority num

These options specify the ToS/DiffServ/Traffic class/Priority -of the outgoing OSPF packets. See -tx class common option for detailed description. -

-

ecmp weight num

When ECMP (multipath) routes are allowed, this value specifies -a relative weight used for nexthops going through the iface. -Allowed values are 1-256. Default value is 1. -

-

authentication none

No passwords are sent in OSPF packets. This is the default value. -

-

authentication simple

Every packet carries 8 bytes of password. Received packets -lacking this password are ignored. This authentication mechanism is -very weak. -

-

authentication cryptographic

16-byte long MD5 digest is appended to every packet. For the digest -generation 16-byte long passwords are used. Those passwords are -not sent via network, so this mechanism is quite secure. -Packets can still be read by an attacker. -

-

password "text"

An 8-byte or 16-byte password used for authentication. -See -password common option for detailed description. -

-

neighbors { set }

A set of neighbors to which Hello messages on NBMA or PtMP -networks are to be sent. For NBMA networks, some of them -could be marked as eligible. In OSPFv3, link-local addresses -should be used, using global ones is possible, but it is -nonstandard and might be problematic. And definitely, -link-local and global addresses should not be mixed. -

-

-

-

Attributes

- -

OSPF defines four route attributes. Each internal route has a metric. -Metric is ranging from 1 to infinity (65535). -External routes use metric type 1 or metric type 2. -A metric of type 1 is comparable with internal metric, a -metric of type 2 is always longer -than any metric of type 1 or any internal metric. -Internal metric or metric of type 1 is stored in attribute -ospf_metric1, metric type 2 is stored in attribute ospf_metric2. -If you specify both metrics only metric1 is used. -

Each external route can also carry attribute ospf_tag which is a -32-bit integer which is used when exporting routes to other protocols; -otherwise, it doesn't affect routing inside the OSPF domain at all. -The fourth attribute ospf_router_id is a router ID of the router -advertising that route/network. This attribute is read-only. Default -is ospf_metric2 = 10000 and ospf_tag = 0. -

-

Example

- -

-

-

-
-protocol ospf MyOSPF {
-        rfc1583compat yes;
-        tick 2;
-        export filter {
-                if source = RTS_BGP then {
-                        ospf_metric1 = 100;
-                        accept;
-                }
-                reject;
-        };
-        area 0.0.0.0 {
-                interface "eth*" {
-                        cost 11;
-                        hello 15;
-                        priority 100;
-                        retransmit 7;
-                        authentication simple;
-                        password "aaa";
-                };
-                interface "ppp*" {
-                        cost 100;
-                        authentication cryptographic;
-                        password "abc" {
-                                id 1;
-                                generate to "22-04-2003 11:00:06";
-                                accept from "17-01-2001 12:01:05";
-                        };
-                        password "def" {
-                                id 2;
-                                generate to "22-07-2005 17:03:21";
-                                accept from "22-02-2001 11:34:06";
-                        };
-                };
-                interface "arc0" {
-                        cost 10;
-                        stub yes;
-                };
-                interface "arc1";
-        };
-        area 120 {
-                stub yes;
-                networks {
-                        172.16.1.0/24;
-                        172.16.2.0/24 hidden;
-                }
-                interface "-arc0" , "arc*" {
-                        type nonbroadcast;
-                        authentication none;
-                        strict nonbroadcast yes;
-                        wait 120;
-                        poll 40;
-                        dead count 8;
-                        neighbors {
-                                192.168.120.1 eligible;
-                                192.168.120.2;
-                                192.168.120.10;
-                        };
-                };
-        };
-}
-
-
-

-

6.6 Pipe -

- -

Introduction

- -

The Pipe protocol serves as a link between two routing tables, allowing routes to be -passed from a table declared as primary (i.e., the one the pipe is connected to using the -table configuration keyword) to the secondary one (declared using peer table) -and vice versa, depending on what's allowed by the filters. Export filters control export -of routes from the primary table to the secondary one, import filters control the opposite -direction. -

-

The Pipe protocol may work in the transparent mode mode or in the opaque mode. -In the transparent mode, the Pipe protocol retransmits all routes from -one table to the other table, retaining their original source and -attributes. If import and export filters are set to accept, then both -tables would have the same content. The transparent mode is the default mode. -

-

In the opaque mode, the Pipe protocol retransmits optimal route -from one table to the other table in a similar way like other -protocols send and receive routes. Retransmitted route will have the -source set to the Pipe protocol, which may limit access to protocol -specific route attributes. This mode is mainly for compatibility, it -is not suggested for new configs. The mode can be changed by -mode option. -

-

The primary use of multiple routing tables and the Pipe protocol is for policy routing, -where handling of a single packet doesn't depend only on its destination address, but also -on its source address, source interface, protocol type and other similar parameters. -In many systems (Linux being a good example), the kernel allows to enforce routing policies -by defining routing rules which choose one of several routing tables to be used for a packet -according to its parameters. Setting of these rules is outside the scope of BIRD's work -(on Linux, you can use the ip command), but you can create several routing tables in BIRD, -connect them to the kernel ones, use filters to control which routes appear in which tables -and also you can employ the Pipe protocol for exporting a selected subset of one table to -another one. -

-

Configuration

- -

-

-
peer table table

Defines secondary routing table to connect to. The -primary one is selected by the table keyword. -

-

mode opaque|transparent

Specifies the mode for the pipe to work in. Default is transparent. -

-

-

Attributes

- -

The Pipe protocol doesn't define any route attributes. -

-

Example

- -

Let's consider a router which serves as a boundary router of two different autonomous -systems, each of them connected to a subset of interfaces of the router, having its own -exterior connectivity and wishing to use the other AS as a backup connectivity in case -of outage of its own exterior line. -

-

Probably the simplest solution to this situation is to use two routing tables (we'll -call them as1 and as2) and set up kernel routing rules, so that packets having -arrived from interfaces belonging to the first AS will be routed according to as1 -and similarly for the second AS. Thus we have split our router to two logical routers, -each one acting on its own routing table, having its own routing protocols on its own -interfaces. In order to use the other AS's routes for backup purposes, we can pass -the routes between the tables through a Pipe protocol while decreasing their preferences -and correcting their BGP paths to reflect the AS boundary crossing. -

-

-
-table as1;                              # Define the tables
-table as2;
-
-protocol kernel kern1 {                 # Synchronize them with the kernel
-        table as1;
-        kernel table 1;
-}
-
-protocol kernel kern2 {
-        table as2;
-        kernel table 2;
-}
-
-protocol bgp bgp1 {                     # The outside connections
-        table as1;
-        local as 1;
-        neighbor 192.168.0.1 as 1001;
-        export all;
-        import all;
-}
-
-protocol bgp bgp2 {
-        table as2;
-        local as 2;
-        neighbor 10.0.0.1 as 1002;
-        export all;
-        import all;
-}
-
-protocol pipe {                         # The Pipe
-        table as1;
-        peer table as2;
-        export filter {
-                if net ~ [ 1.0.0.0/8+] then {   # Only AS1 networks
-                        if preference>10 then preference = preference-10;
-                        if source=RTS_BGP then bgp_path.prepend(1);
-                        accept;
-                }
-                reject;
-        };
-        import filter {
-                if net ~ [ 2.0.0.0/8+] then {   # Only AS2 networks
-                        if preference>10 then preference = preference-10;
-                        if source=RTS_BGP then bgp_path.prepend(2);
-                        accept;
-                }
-                reject;
-        };
-}
-
-
-

-

6.7 RAdv -

- -

Introduction

- -

The RAdv protocol is an implementation of Router Advertisements, -which are used in the IPv6 stateless autoconfiguration. IPv6 routers -send (in irregular 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 4861 -ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt -and also the DNS extensions from -RFC 6106 -ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt. -

-

Configuration

- -

There are several classes of definitions in RAdv configuration -- -interface definitions, prefix definitions and DNS definitions: -

-

-
interface pattern [, ...] { options }

Interface definitions specify a set of interfaces on which the -protocol is activated and contain interface specific options. -See -interface common options for -detailed description. -

-

prefix prefix { options }

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 -its options are used. If no matching prefix definition is -found, the prefix is used with default options. -

Prefix definitions can be either global or interface-specific. -The second ones are part of interface options. The prefix -definition matching is done in the first-match style, when -interface-specific definitions are processed before global -definitions. As expected, the prefix definition is matching if -the network prefix is a subnet of the prefix in prefix -definition. -

-

rdnss { options }

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 rdnss -address 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 rdnss local option. -

-

dnssl { options }

DNSSL definitions allow to specify a list of advertised DNS -search domains together with their options. Like rdnss -above, multiple definitions are cumulative, they can be used -also as interface-specific options and there is a short -variant dnssl domain that just specifies one DNS -search domain. -

- -

trigger prefix

RAdv protocol could be configured to change its behavior based -on availability of routes. When this option is used, the -protocol waits in suppressed state until a trigger route -(for the specified network) is exported to the protocol, the -protocol also returnsd to suppressed state if the -trigger route disappears. Note that route export depends -on specified export filter, as usual. This option could be -used, e.g., for handling failover in multihoming scenarios. -

During suppressed state, router advertisements are generated, -but with some fields zeroed. Exact behavior depends on which -fields are zeroed, this can be configured by -sensitive option for appropriate fields. By default, just -default lifetime (also called router lifetime) is -zeroed, which means hosts cannot use the router as a default -router. preferred lifetime and valid lifetime could -also be configured as sensitive for a prefix, which would -cause autoconfigured IPs to be deprecated or even removed. -

-

-

Interface specific options: -

-

-
max ra interval expr

Unsolicited router advertisements are sent in irregular time -intervals. This option specifies the maximum length of these -intervals, in seconds. Valid values are 4-1800. Default: 600 -

-

min ra interval expr

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. -

-

min delay expr

The minimum delay between two consecutive router advertisements, -in seconds. Default: 3 -

-

managed switch

This option specifies whether hosts should use DHCPv6 for -IP address configuration. Default: no -

-

other config switch

This option specifies whether hosts should use DHCPv6 to -receive other configuration information. Default: no -

-

link mtu expr

This option specifies which value of MTU should be used by -hosts. 0 means unspecified. Default: 0 -

-

reachable time expr

This option specifies the time (in milliseconds) how long -hosts should assume a neighbor is reachable (from the last -confirmation). Maximum is 3600000, 0 means unspecified. -Default 0. -

-

retrans timer expr

This option specifies the time (in milliseconds) how long -hosts should wait before retransmitting Neighbor Solicitation -messages. 0 means unspecified. Default 0. -

-

current hop limit expr

This option specifies which value of Hop Limit should be used -by hosts. Valid values are 0-255, 0 means unspecified. Default: 64 -

-

default lifetime expr [sensitive switch]

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. For -sensitive option, see -trigger. -Default: 3 * max ra interval, sensitive yes. -

-

rdnss local switch

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. -

-

dnssl local switch

Use only local DNSSL definitions for this interface. See -rdnss local option above. Default: no. -

-

-

-

Prefix specific options: -

-

-
skip switch

This option allows to specify that given prefix should not be -advertised. This is useful for making exceptions from a -default policy of advertising all prefixes. Note that for -withdrawing an already advertised prefix it is more useful to -advertise it with zero valid lifetime. Default: no -

-

onlink switch

This option specifies whether hosts may use the advertised -prefix for onlink determination. Default: yes -

-

autonomous switch

This option specifies whether hosts may use the advertised -prefix for stateless autoconfiguration. Default: yes -

-

valid lifetime expr [sensitive switch]

This option specifies the time (in seconds) how long (after -the receipt of RA) the prefix information is valid, i.e., -autoconfigured IP addresses can be assigned and hosts with -that IP addresses are considered directly reachable. 0 means -the prefix is no longer valid. For sensitive option, see -trigger. Default: 86400 (1 day), sensitive no. -

-

preferred lifetime expr [sensitive switch]

This option specifies the time (in seconds) how long (after -the receipt of RA) IP addresses generated from the prefix -using stateless autoconfiguration remain preferred. For -sensitive option, see -trigger. -Default: 14400 (4 hours), sensitive no. -

-

-

-

RDNSS specific options: -

-

-
ns address

This option specifies one recursive DNS server. Can be used -multiple times for multiple servers. It is mandatory to have -at least one ns option in rdnss definition. -

-

lifetime [mult] expr

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 mult is used) in -multiples of max ra interval. Note that RDNSS information -is also invalidated when default lifetime expires. 0 -means these addresses are no longer valid DNS servers. -Default: 3 * max ra interval. -

-

-

-

DNSSL specific options: -

-

-
domain address

This option specifies one DNS search domain. Can be used -multiple times for multiple domains. It is mandatory to have -at least one domain option in dnssl definition. -

-

lifetime [mult] expr

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 lifetime option above. -Default: 3 * max ra interval. -

-

-

-

Example

- -

-

-
-protocol radv {
-        interface "eth2" {
-                max ra interval 5;      # Fast failover with more routers
-                managed yes;            # Using DHCPv6 on eth2
-                prefix ::/0 {
-                        autonomous off; # So do not autoconfigure any IP
-                };
-        };
-
-        interface "eth*";               # No need for any other options
-
-        prefix 2001:0DB8:1234::/48 {
-                preferred lifetime 0;   # Deprecated address range
-        };
-
-        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";
-        };
-}
-
-
-

-

6.8 RIP -

- -

Introduction

- -

The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors) -distances to all networks it can reach. When a router hears distance to another network, it increments -it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes -unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus -interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in -RIP) and all routers know that network is unreachable. RIP tries to minimize situations where -counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use -RIP on networks where maximal distance is higher than 15 hosts. You can read more about RIP at -http://www.ietf.org/html.charters/rip-charter.html. Both IPv4 -(RFC 1723 -ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt) -and IPv6 (RFC 2080 -ftp://ftp.rfc-editor.org/in-notes/rfc2080.txt) versions of RIP are supported by BIRD, historical RIPv1 (RFC 1058 -ftp://ftp.rfc-editor.org/in-notes/rfc1058.txt)is -not currently supported. RIPv4 MD5 authentication (RFC 2082 -ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt) is supported. -

-

RIP is a very simple protocol, and it has a lot of shortcomings. Slow -convergence, big network load and inability to handle larger networks -makes it pretty much obsolete. (It is still usable on very small networks.) -

-

Configuration

- -

In addition to options common for all to other protocols, RIP supports the following ones: -

-

-
authentication none|plaintext|md5

selects authentication method to be used. none means that -packets are not authenticated at all, plaintext means that a plaintext password is embedded -into each packet, and md5 means that packets are authenticated using a MD5 cryptographic -hash. If you set authentication to not-none, it is a good idea to add password -section. Default: none. -

-

honor always|neighbor|never

specifies when should requests for dumping routing table -be honored. (Always, when sent from a host on a directly connected -network or never.) Routing table updates are honored only from -neighbors, that is not configurable. Default: never. -

-

-

There are some options that can be specified per-interface: -

-

-
metric num

This option specifies the metric of the interface. Valid -

-

mode multicast|broadcast|quiet|nolisten|version1

This option selects the mode for RIP to work in. If nothing is -specified, RIP runs in multicast mode. version1 is -currently equivalent to broadcast, and it makes RIP talk -to a broadcast address even through multicast mode is -possible. quiet option means that RIP will not transmit -any periodic messages to this interface and nolisten -means that RIP will send to this interface butnot listen to it. -

-

ttl security [switch | tx only]

TTL security is a feature that protects routing protocols -from remote spoofed packets by using TTL 255 instead of TTL 1 -for protocol packets destined to neighbors. Because TTL is -decremented when packets are forwarded, it is non-trivial to -spoof packets with TTL 255 from remote locations. -

If this option is enabled, the router will send RIP packets -with TTL 255 and drop received packets with TTL less than -255. If this option si set to tx only, TTL 255 is used -for sent packets, but is not checked for received -packets. Such setting does not offer protection, but offers -compatibility with neighbors regardless of whether they use -ttl security. -

Note that for RIPng, TTL security is a standard behavior -(required by RFC 2080), but BIRD uses tx only by -default, for compatibility with older versions. For IPv4 RIP, -default value is no. -

-

tx class|dscp|priority num

These options specify the ToS/DiffServ/Traffic class/Priority -of the outgoing RIP packets. See -tx class common option for detailed description. -

-

-

The following options generally override behavior specified in RFC. If you use any of these -options, BIRD will no longer be RFC-compliant, which means it will not be able to talk to anything -other than equally configured BIRD. I have warned you. -

-

-
port number

selects IP port to operate on, default 520. (This is useful when testing BIRD, if you -set this to an address >1024, you will not need to run bird with UID==0). -

-

infinity number

selects the value of infinity, default is 16. Bigger values will make protocol convergence -even slower. -

-

period number

specifies the number of seconds between periodic updates. Default is 30 seconds. A lower -number will mean faster convergence but bigger network -load. Do not use values lower than 12. -

-

timeout time number

specifies how old route has to be to be considered unreachable. Default is 4*period. -

-

garbage time number

specifies how old route has to be to be discarded. Default is 10*period. -

-

-

Attributes

- -

RIP defines two route attributes: -

-

-
int rip_metric

RIP metric of the route (ranging from 0 to infinity). -When routes from different RIP instances are available and all of them have the same -preference, BIRD prefers the route with lowest rip_metric. -When importing a non-RIP route, the metric defaults to 5. -

-

int rip_tag

RIP route tag: a 16-bit number which can be used -to carry additional information with the route (for example, an originating AS number -in case of external routes). When importing a non-RIP route, the tag defaults to 0. -

-

-

Example

- -

-

-
-protocol rip MyRIP_test {
-        debug all;
-        port 1520;
-        period 12;
-        garbage time 60;
-        interface "eth0" { metric 3; mode multicast; };
-        interface "eth*" { metric 2; mode broadcast; };
-        honor neighbor;
-        authentication none;
-        import filter { print "importing"; accept; };
-        export filter { print "exporting"; accept; };
-}
-
-
-

-

6.9 Static -

- -

The Static protocol doesn't communicate with other routers in the network, -but instead it allows you to define routes manually. This is often used for -specifying how to forward packets to parts of the network which don't use -dynamic routing at all and also for defining sink routes (i.e., those -telling to return packets as undeliverable if they are in your IP block, -you don't have any specific destination for them and you don't want to send -them out through the default route to prevent routing loops). -

-

There are five types of static routes: `classical' routes telling -to forward packets to a neighboring router, multipath routes -specifying several (possibly weighted) neighboring routers, device -routes specifying forwarding to hosts on a directly connected network, -recursive routes computing their nexthops by doing route table lookups -for a given IP and special routes (sink, blackhole etc.) which specify -a special action to be done instead of forwarding the packet. -

-

When the particular destination is not available (the interface is down or -the next hop of the route is not a neighbor at the moment), Static just -uninstalls the route from the table it is connected to and adds it again as soon -as the destination becomes adjacent again. -

-

The Static protocol does not have many configuration options. The -definition of the protocol contains mainly a list of static routes: -

-

-
route prefix via ip

Static route through -a neighboring router. -

route prefix multipath via ip [weight num] [via ...]

Static multipath route. Contains several nexthops (gateways), possibly -with their weights. -

route prefix via "interface"

Static device -route through an interface to hosts on a directly connected network. -

route prefix recursive ip

Static recursive route, -its nexthop depends on a route table lookup for given IP address. -

route prefix blackhole|unreachable|prohibit

Special routes -specifying to silently drop the packet, return it as unreachable or return -it as administratively prohibited. First two targets are also known -as drop and reject. -

-

check link switch

If set, hardware link states of network interfaces are taken -into consideration. When link disappears (e.g. ethernet cable -is unplugged), static routes directing to that interface are -removed. It is possible that some hardware drivers or -platforms do not implement this feature. Default: off. -

-

igp table name

Specifies a table that is used -for route table lookups of recursive routes. Default: the -same table as the protocol is connected to. -

-

-

Static routes have no specific attributes. -

-

Example static config might look like this: -

-

-

-
-protocol static {
-        table testable;                  # Connect to a non-default routing table
-        route 0.0.0.0/0 via 198.51.100.130; # Default route
-        route 10.0.0.0/8 multipath       # Multipath route
-                via 198.51.100.10 weight 2
-                via 198.51.100.20
-                via 192.0.2.1;
-        route 203.0.113.0/24 unreachable; # Sink route
-        route 10.2.0.0/24 via "arc0";    # Secondary network
-}
-
-
-

-

-Next -Previous -Contents - - diff --git a/doc/bird.sgml b/doc/bird.sgml index a2266424..5ceb8ab9 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -477,7 +477,7 @@ to zero to disable it. An empty is equivalent to import limit [ +