embedaddon/bird/doc/bird.sgml - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc / bird.sgml
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Aug 22 12:33:54 2017 UTC (6 years, 10 months ago) by misho
Branches: bird, MAIN
CVS tags: v1_6_3p0, v1_6_3, HEAD

bird 1.6.3

1: <!doctype birddoc system> 2: 3:  20: 21: <book> 22: 23: <title>BIRD User's Guide 24: <author> 25: Ondrej Filip <it/<feela@network.cz>/, 26: Pavel Machek <it/<pavel@ucw.cz>/, 27: Martin Mares <it/<mj@ucw.cz>/, 28: Ondrej Zajicek <it/<santiago@crfreenet.org>/ 29: </author> 30: 31: <abstract> 32: This document contains user documentation for the BIRD Internet Routing Daemon project. 33: </abstract> 34: 35:  36: <toc> 37: 38:  39: 40: 41: <chapt>Introduction 42: <label id="intro"> 43: 44: <sect>What is BIRD 45: <label id="what-is-bird"> 46: 47: The name `BIRD' is actually an acronym standing for `BIRD Internet Routing 48: Daemon'. Let's take a closer look at the meaning of the name: 49: 50: <em/BIRD/: Well, we think we have already explained that. It's an acronym 51: standing for `BIRD Internet Routing Daemon', you remember, don't you? :-) 52: 53: <em/Internet Routing/: It's a program (well, a daemon, as you are going to 54: discover in a moment) which works as a dynamic router in an Internet type 55: network (that is, in a network running either the IPv4 or the IPv6 protocol). 56: Routers are devices which forward packets between interconnected networks in 57: order to allow hosts not connected directly to the same local area network to 58: communicate with each other. They also communicate with the other routers in the 59: Internet to discover the topology of the network which allows them to find 60: optimal (in terms of some metric) rules for forwarding of packets (which are 61: called routing tables) and to adapt themselves to the changing conditions such 62: as outages of network links, building of new connections and so on. Most of 63: these routers are costly dedicated devices running obscure firmware which is 64: hard to configure and not open to any changes (on the other hand, their special 65: hardware design allows them to keep up with lots of high-speed network 66: interfaces, better than general-purpose computer does). Fortunately, most 67: operating systems of the UNIX family allow an ordinary computer to act as a 68: router and forward packets belonging to the other hosts, but only according to a 69: statically configured table. 70: 71: A <em/Routing Daemon/ is in UNIX terminology a non-interactive program 72: running on background which does the dynamic part of Internet routing, that is 73: it communicates with the other routers, calculates routing tables and sends them 74: to the OS kernel which does the actual packet forwarding. There already exist 75: other such routing daemons: routed (RIP only), GateD (non-free), 76: <HTMLURL URL="http://www.zebra.org" name="Zebra"> and 77: <HTMLURL URL="http://sourceforge.net/projects/mrt" name="MRTD">, 78: but their capabilities are limited and they are relatively hard to configure 79: and maintain. 80: 81: BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings, 82: to support all the routing technology used in the today's Internet or planned to 83: be used in near future and to have a clean extensible architecture allowing new 84: routing protocols to be incorporated easily. Among other features, BIRD 85: supports: 86: 87: <itemize> 88: <item>both IPv4 and IPv6 protocols 89: <item>multiple routing tables 90: <item>the Border Gateway Protocol (BGPv4) 91: <item>the Routing Information Protocol (RIPv2) 92: <item>the Open Shortest Path First protocol (OSPFv2, OSPFv3) 93: <item>the Router Advertisements for IPv6 hosts 94: <item>a virtual protocol for exchange of routes between different 95: routing tables on a single host 96: <item>a command-line interface allowing on-line control and inspection 97: of status of the daemon 98: <item>soft reconfiguration (no need to use complex online commands to 99: change the configuration, just edit the configuration file and 100: notify BIRD to re-read it and it will smoothly switch itself to 101: the new configuration, not disturbing routing protocols unless 102: they are affected by the configuration changes) 103: <item>a powerful language for route filtering 104: </itemize> 105: 106: BIRD has been developed at the Faculty of Math and Physics, Charles 107: University, Prague, Czech Republic as a student project. It can be freely 108: distributed under the terms of the GNU General Public License. 109: 110: BIRD has been designed to work on all UNIX-like systems. It has been 111: developed and tested under Linux 2.0 to 2.6, and then ported to FreeBSD, NetBSD 112: and OpenBSD, porting to other systems (even non-UNIX ones) should be relatively 113: easy due to its highly modular architecture. 114: 115: BIRD supports either IPv4 or IPv6 protocol, but have to be compiled separately 116: for each one. Therefore, a dualstack router would run two instances of BIRD (one 117: for IPv4 and one for IPv6), with completely separate setups (configuration 118: files, tools ...). 119: 120: 121: <sect>Installing BIRD 122: <label id="install"> 123: 124: On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) 125: and Perl, installing BIRD should be as easy as: 126: 127: <code> 128: ./configure 129: make 130: make install 131: vi /usr/local/etc/bird.conf 132: bird 133: </code> 134: 135: You can use <tt>./configure --help</tt> to get a list of configure 136: options. The most important ones are: <tt/--enable-ipv6/ which enables building 137: of an IPv6 version of BIRD, <tt/--with-protocols=/ to produce a slightly smaller 138: BIRD executable by configuring out routing protocols you don't use, and 139: <tt/--prefix=/ to install BIRD to a place different from <file>/usr/local</file>. 140: 141: 142: <sect>Running BIRD 143: <label id="argv"> 144: 145: You can pass several command-line options to bird: 146: 147: <descrip> 148: <tag><label id="argv-config">-c <m/config name/</tag> 149: use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>. 150: 151: <tag><label id="argv-debug">-d</tag> 152: enable debug messages and run bird in foreground. 153: 154: <tag><label id="argv-log-file">-D <m/filename of debug log/</tag> 155: log debugging information to given file instead of stderr. 156: 157: <tag><label id="argv-foreground">-f</tag> 158: run bird in foreground. 159: 160: <tag><label id="argv-group">-g <m/group/</tag> 161: use that group ID, see the next section for details. 162: 163: <tag><label id="argv-help">-h, --help</tag> 164: display command-line options to bird. 165: 166: <tag><label id="argv-local">-l</tag> 167: look for a configuration file and a communication socket in the current 168: working directory instead of in default system locations. However, paths 169: specified by options <cf/-c/, <cf/-s/ have higher priority. 170: 171: <tag><label id="argv-parse">-p</tag> 172: just parse the config file and exit. Return value is zero if the config 173: file is valid, nonzero if there are some errors. 174: 175: <tag><label id="argv-pid">-P <m/name of PID file/</tag> 176: create a PID file with given filename. 177: 178: <tag><label id="argv-recovery">-R</tag> 179: apply graceful restart recovery after start. 180: 181: <tag><label id="argv-socket">-s <m/name of communication socket/</tag> 182: use given filename for a socket for communications with the client, 183: default is <it/prefix/<file>/var/run/bird.ctl</file>. 184: 185: <tag><label id="argv-user">-u <m/user/</tag> 186: drop privileges and use that user ID, see the next section for details. 187: 188: <tag><label id="argv-version">--version</tag> 189: display bird version. 190: </descrip> 191: 192: BIRD writes messages about its work to log files or syslog (according to config). 193: 194: 195: <sect>Privileges 196: <label id="privileges"> 197: 198: BIRD, as a routing daemon, uses several privileged operations (like setting 199: routing table and using raw sockets). Traditionally, BIRD is executed and runs 200: with root privileges, which may be prone to security problems. The recommended 201: way is to use a privilege restriction (options <cf/-u/, <cf/-g/). In that case 202: BIRD is executed with root privileges, but it changes its user and group ID to 203: an unprivileged ones, while using Linux capabilities to retain just required 204: privileges (capabilities CAP_NET_*). Note that the control socket is created 205: before the privileges are dropped, but the config file is read after that. The 206: privilege restriction is not implemented in BSD port of BIRD. 207: 208: An unprivileged user (as an argument to <cf/-u/ options) may be the user 209: <cf/nobody/, but it is suggested to use a new dedicated user account (like 210: <cf/bird/). The similar considerations apply for the group option, but there is 211: one more condition -- the users in the same group can use <file/birdc/ to 212: control BIRD. 213: 214: Finally, there is a possibility to use external tools to run BIRD in an 215: environment with restricted privileges. This may need some configuration, but it 216: is generally easy -- BIRD needs just the standard library, privileges to read 217: the config file and create the control socket and the CAP_NET_* capabilities. 218: 219: 220: <chapt>About routing tables 221: <label id="routing-tables"> 222: 223: BIRD has one or more routing tables which may or may not be synchronized with 224: OS kernel and which may or may not be synchronized with each other (see the Pipe 225: protocol). Each routing table contains a list of known routes. Each route 226: consists of: 227: 228: <itemize> 229: <item>network prefix this route is for (network address and prefix 230: length -- the number of bits forming the network part of the 231: address; also known as a netmask) 232: <item>preference of this route 233: <item>IP address of router which told us about this route 234: <item>IP address of router we should forward the packets to using this 235: route 236: <item>other attributes common to all routes 237: <item>dynamic attributes defined by protocols which may or may not be 238: present (typically protocol metrics) 239: </itemize> 240: 241: Routing table maintains multiple entries for a network, but at most one entry 242: for one network and one protocol. The entry with the highest preference is used 243: for routing (we will call such an entry the <it/selected route/). If there are 244: more entries with the same preference and they are from the same protocol, the 245: protocol decides (typically according to metrics). If they aren't, an internal 246: ordering is used to break the tie. You can get the list of route attributes in 247: the Route attributes section. 248: 249: Each protocol is connected to a routing table through two filters which can 250: accept, reject and modify the routes. An <it/export/ filter checks routes passed 251: from the routing table to the protocol, an <it/import/ filter checks routes in 252: the opposite direction. When the routing table gets a route from a protocol, it 253: recalculates the selected route and broadcasts it to all protocols connected to 254: the table. The protocols typically send the update to other routers in the 255: network. Note that although most protocols are interested in receiving just 256: selected routes, some protocols (e.g. the <cf/Pipe/ protocol) receive and 257: process all entries in routing tables (accepted by filters). 258: 259: <label id="dsc-table-sorted">Usually, a routing table just chooses a selected route 260: from a list of entries for one network. But if the <cf/sorted/ option is 261: activated, these lists of entries are kept completely sorted (according to 262: preference or some protocol-dependent metric). This is needed for some features 263: of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to 264: accept not just a selected route, but the first route (in the sorted list) that 265: is accepted by filters), but it is incompatible with some other features (e.g. 266: <cf/deterministic med/ option of BGP protocol, which activates a way of choosing 267: selected route that cannot be described using comparison and ordering). Minor 268: advantage is that routes are shown sorted in <cf/show route/, minor disadvantage 269: is that it is slightly more computationally expensive. 270: 271: 272: <sect>Graceful restart 273: <label id="graceful-restart"> 274: 275: When BIRD is started after restart or crash, it repopulates routing tables in 276: an uncoordinated manner, like after clean start. This may be impractical in some 277: cases, because if the forwarding plane (i.e. kernel routing tables) remains 278: intact, then its synchronization with BIRD would temporarily disrupt packet 279: forwarding until protocols converge. Graceful restart is a mechanism that could 280: help with this issue. Generally, it works by starting protocols and letting them 281: repopulate routing tables while deferring route propagation until protocols 282: acknowledge their convergence. Note that graceful restart behavior have to be 283: configured for all relevant protocols and requires protocol-specific support 284: (currently implemented for Kernel and BGP protocols), it is activated for 285: particular boot by option <cf/-R/. 286: 287: 288: <chapt>Configuration 289: <label id="config"> 290: 291: <sect>Introduction 292: <label id="config-intro"> 293: 294: BIRD is configured using a text configuration file. Upon startup, BIRD reads 295: <it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option 296: is given). Configuration may be changed at user's request: if you modify the 297: config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new 298: config. Then there's the client which allows you to talk with BIRD in an 299: extensive way. 300: 301: In the config, everything on a line after <cf/#/ or inside <cf>/* */</cf> is 302: a comment, whitespace characters are treated as a single space. If there's a 303: variable number of options, they are grouped using the <cf/{ }/ brackets. Each 304: option is terminated by a <cf/;/. Configuration is case sensitive. There are two 305: ways how to name symbols (like protocol names, filter names, constants etc.). You 306: can either use a simple string starting with a letter followed by any 307: combination of letters and numbers (e.g. "R123", "myfilter", "bgp5") or you can 308: enclose the name into apostrophes (<cf/'/) and than you can use any combination 309: of numbers, letters. hyphens, dots and colons (e.g. "'1:strange-name'", 310: "'-NAME-'", "'cool::name'"). 311: 312: Here is an example of a simple config file. It enables synchronization of 313: routing tables with OS kernel, scans for new network interfaces every 10 seconds 314: and runs RIP on all network interfaces found. 315: 316: <code> 317: protocol kernel { 318: persist; # Don't remove routes on BIRD shutdown 319: scan time 20; # Scan kernel routing table every 20 seconds 320: export all; # Default is export none 321: } 322: 323: protocol device { 324: scan time 10; # Scan interfaces every 10 seconds 325: } 326: 327: protocol rip { 328: export all; 329: import all; 330: interface "*"; 331: } 332: </code> 333: 334: 335: <sect>Global options 336: <label id="global-opts"> 337: 338: <descrip> 339: <tag><label id="opt-include">include "<m/filename/"</tag> 340: This statement causes inclusion of a new file. <m/Filename/ could also 341: be a wildcard, in that case matching files are included in alphabetic 342: order. The maximal depth is 8. Note that this statement could be used 343: anywhere in the config file, not just as a top-level option. 344: 345: <tag><label id="opt-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag> 346: Set logging of messages having the given class (either <cf/all/ or 347: <cf/{ error|trace [, <m/.../] }/ etc.) into selected destination (a file specified 348: as a filename string, syslog with optional name argument, or the stderr 349: output). Classes are: 350: <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems, 351: <cf/debug/ for debugging messages, 352: <cf/trace/ when you want to know what happens in the network, 353: <cf/remote/ for messages about misbehavior of remote machines, 354: <cf/auth/ about authentication failures, 355: <cf/bug/ for internal BIRD bugs. 356: You may specify more than one <cf/log/ line to establish logging to 357: multiple destinations. Default: log everything to the system log. 358: 359: <tag><label id="opt-debug-protocols">debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag> 360: Set global defaults of protocol debugging options. See <cf/debug/ in the 361: following section. Default: off. 362: 363: <tag><label id="opt-debug-commands">debug commands <m/number/</tag> 364: Control logging of client connections (0 for no logging, 1 for logging 365: of connects and disconnects, 2 and higher for logging of all client 366: commands). Default: 0. 367: 368: <tag><label id="opt-debug-latency">debug latency <m/switch/</tag> 369: Activate tracking of elapsed time for internal events. Recent events 370: could be examined using <cf/dump events/ command. Default: off. 371: 372: <tag><label id="opt-debug-latency-limit">debug latency limit <m/time/</tag> 373: If <cf/debug latency/ is enabled, this option allows to specify a limit 374: for elapsed time. Events exceeding the limit are logged. Default: 1 s. 375: 376: <tag><label id="opt-watchdog-warn">watchdog warning <m/time/</tag> 377: Set time limit for I/O loop cycle. If one iteration took more time to 378: complete, a warning is logged. Default: 5 s. 379: 380: <tag><label id="opt-watchdog-timeout">watchdog timeout <m/time/</tag> 381: Set time limit for I/O loop cycle. If the limit is breached, BIRD is 382: killed by abort signal. The timeout has effective granularity of 383: seconds, zero means disabled. Default: disabled (0). 384: 385: <tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag> 386: Set MRTdump file name. This option must be specified to allow MRTdump 387: feature. Default: no dump file. 388: 389: <tag><label id="opt-mrtdump-protocols">mrtdump protocols all|off|{ states|messages [, <m/.../] }</tag> 390: Set global defaults of MRTdump options. See <cf/mrtdump/ in the 391: following section. Default: off. 392: 393: <tag><label id="opt-filter">filter <m/name local variables/{ <m/commands/ }</tag> 394: Define a filter. You can learn more about filters in the following 395: chapter. 396: 397: <tag><label id="opt-function">function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> 398: Define a function. You can learn more about functions in the following chapter. 399: 400: <tag><label id="opt-protocol">protocol rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag> 401: Define a protocol instance called <cf><m/name/</cf> (or with a name like 402: "rip5" generated automatically if you don't specify any 403: <cf><m/name/</cf>). You can learn more about configuring protocols in 404: their own chapters. When <cf>from <m/name2/</cf> expression is used, 405: initial protocol options are taken from protocol or template 406: <cf><m/name2/</cf> You can run more than one instance of most protocols 407: (like RIP or BGP). By default, no instances are configured. 408: 409: <tag><label id="opt-template">template rip|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag> 410: Define a protocol template instance called <m/name/ (or with a name like 411: "bgp1" generated automatically if you don't specify any <m/name/). 412: Protocol templates can be used to group common options when many 413: similarly configured protocol instances are to be defined. Protocol 414: instances (and other templates) can use templates by using <cf/from/ 415: expression and the name of the template. At the moment templates (and 416: <cf/from/ expression) are not implemented for OSPF protocol. 417: 418: <tag><label id="opt-define">define <m/constant/ = <m/expression/</tag> 419: Define a constant. You can use it later in every place you could use a 420: value of the same type. Besides, there are some predefined numeric 421: constants based on /etc/iproute2/rt_* files. A list of defined constants 422: can be seen (together with other symbols) using 'show symbols' command. 423: 424: <tag><label id="opt-router-id">router id <m/IPv4 address/</tag> 425: Set BIRD's router ID. It's a world-wide unique identification of your 426: router, usually one of router's IPv4 addresses. Default: in IPv4 427: version, the lowest IP address of a non-loopback interface. In IPv6 428: version, this option is mandatory. 429: 430: <tag><label id="opt-router-id-from">router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../]</tag> 431: Set BIRD's router ID based on an IP address of an interface specified by 432: an interface pattern. The option is applicable for IPv4 version only. 433: See <ref id="proto-iface" name="interface"> section for detailed 434: description of interface patterns with extended clauses. 435: 436: <tag><label id="opt-listen-bgp">listen bgp [address <m/address/] [port <m/port/] [dual]</tag> 437: This option allows to specify address and port where BGP protocol should 438: listen. It is global option as listening socket is common to all BGP 439: instances. Default is to listen on all addresses (0.0.0.0) and port 179. 440: In IPv6 mode, option <cf/dual/ can be used to specify that BGP socket 441: should accept both IPv4 and IPv6 connections (but even in that case, 442: BIRD would accept IPv6 routes only). Such behavior was default in older 443: versions of BIRD. 444: 445: <tag><label id="opt-graceful-restart">graceful restart wait <m/number/</tag> 446: During graceful restart recovery, BIRD waits for convergence of routing 447: protocols. This option allows to specify a timeout for the recovery to 448: prevent waiting indefinitely if some protocols cannot converge. Default: 449: 240 seconds. 450: 451: <tag><label id="opt-timeformat">timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag> 452: This option allows to specify a format of date/time used by BIRD. The 453: first argument specifies for which purpose such format is used. 454: <cf/route/ is a format used in 'show route' command output, 455: <cf/protocol/ is used in 'show protocols' command output, <cf/base/ is 456: used for other commands and <cf/log/ is used in a log file. 457: 458: "<m/format1/" is a format string using <it/strftime(3)/ notation (see 459: <it/man strftime/ for details). <m/limit> and "<m/format2/" allow to 460: specify the second format string for times in past deeper than <m/limit/ 461: seconds. There are few shorthands: <cf/iso long/ is a ISO 8601 date/time 462: format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F %T"/. 463: <cf/iso short/ is a variant of ISO 8601 that uses just the time format 464: (hh:mm:ss) for near times (up to 20 hours in the past) and the date 465: format (YYYY-MM-DD) for far times. This is a shorthand for 466: <cf/"%T" 72000 "%F"/. 467: 468: By default, BIRD uses the <cf/iso short/ format for <cf/route/ and 469: <cf/protocol/ times, and the <cf/iso long/ format for <cf/base/ and 470: <cf/log/ times. 471: 472: In pre-1.4.0 versions, BIRD used an short, ad-hoc format for <cf/route/ 473: and <cf/protocol/ times, and a <cf/iso long/ similar format (DD-MM-YYYY 474: hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats could be set by 475: <cf/old short/ and <cf/old long/ compatibility shorthands. 476: 477: <tag><label id="opt-table">table <m/name/ [sorted]</tag> 478: Create a new routing table. The default routing table is created 479: implicitly, other routing tables have to be added by this command. 480: Option <cf/sorted/ can be used to enable sorting of routes, see 481: <ref id="dsc-table-sorted" name="sorted table"> description for details. 482: 483: <tag><label id="opt-roa-table">roa table <m/name/ [ { <m/roa table options .../ } ]</tag> 484: Create a new ROA (Route Origin Authorization) table. ROA tables can be 485: used to validate route origination of BGP routes. A ROA table contains 486: ROA entries, each consist of a network prefix, a max prefix length and 487: an AS number. A ROA entry specifies prefixes which could be originated 488: by that AS number. ROA tables could be filled with data from RPKI (<rfc 489: id="6480">) or from public databases like Whois. ROA tables are 490: examined by <cf/roa_check()/ operator in filters. 491: 492: Currently, there is just one option, <cf>roa <m/prefix/ max <m/num/ as 493: <m/num/</cf>, which can be used to populate the ROA table with static 494: ROA entries. The option may be used multiple times. Other entries can be 495: added dynamically by <cf/add roa/ command. 496: 497: <tag><label id="opt-eval">eval <m/expr/</tag> 498: Evaluates given filter expression. It is used by us for testing of filters. 499: </descrip> 500: 501: 502: <sect>Protocol options 503: <label id="protocol-opts"> 504: 505: For each protocol instance, you can configure a bunch of options. Some of 506: them (those described in this section) are generic, some are specific to the 507: protocol (see sections talking about the protocols). 508: 509: Several options use a <m/switch/ argument. It can be either <cf/on/, 510: <cf/yes/ or a numeric expression with a non-zero value for the option to be 511: enabled or <cf/off/, <cf/no/ or a numeric expression evaluating to zero to 512: disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means 513: agreement"). 514: 515: <descrip> 516: <tag><label id="proto-preference">preference <m/expr/</tag> 517: Sets the preference of routes generated by this protocol. Default: 518: protocol dependent. 519: 520: <tag><label id="proto-disabled">disabled <m/switch/</tag> 521: Disables the protocol. You can change the disable/enable status from the 522: command line interface without needing to touch the configuration. 523: Disabled protocols are not activated. Default: protocol is enabled. 524: 525: <tag><label id="proto-debug">debug all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag> 526: Set protocol debugging options. If asked, each protocol is capable of 527: writing trace messages about its work to the log (with category 528: <cf/trace/). You can either request printing of <cf/all/ trace messages 529: or only of the types selected: <cf/states/ for protocol state changes 530: (protocol going up, down, starting, stopping etc.), <cf/routes/ for 531: routes exchanged with the routing table, <cf/filters/ for details on 532: route filtering, <cf/interfaces/ for interface change events sent to the 533: protocol, <cf/events/ for events internal to the protocol and <cf/packets/ 534: for packets sent and received by the protocol. Default: off. 535: 536: <tag><label id="proto-mrtdump">mrtdump all|off|{ states|messages [, <m/.../] }</tag> 537: Set protocol MRTdump flags. MRTdump is a standard binary format for 538: logging information from routing protocols and daemons. These flags 539: control what kind of information is logged from the protocol to the 540: MRTdump file (which must be specified by global <cf/mrtdump/ option, see 541: the previous section). Although these flags are similar to flags of 542: <cf/debug/ option, their meaning is different and protocol-specific. For 543: BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs 544: received BGP messages. Other protocols does not support MRTdump yet. 545: 546: <tag><label id="proto-router-id">router id <m/IPv4 address/</tag> 547: This option can be used to override global router id for a given 548: protocol. Default: uses global router id. 549: 550: <tag><label id="proto-import">import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> 551: Specify a filter to be used for filtering routes coming from the 552: protocol to the routing table. <cf/all/ is shorthand for <cf/where true/ 553: and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/. 554: 555: <tag><label id="proto-export">export <m/filter/</tag> 556: This is similar to the <cf>import</cf> keyword, except that it works in 557: the direction from the routing table to the protocol. Default: <cf/none/. 558: 559: <tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag> 560: Usually, if an import filter rejects a route, the route is forgotten. 561: When this option is active, these routes are kept in the routing table, 562: but they are hidden and not propagated to other protocols. But it is 563: possible to show them using <cf/show route filtered/. Note that this 564: option does not work for the pipe protocol. Default: off. 565: 566: <tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag> 567: Specify an import route limit (a maximum number of routes imported from 568: the protocol) and optionally the action to be taken when the limit is 569: hit. Warn action just prints warning log message. Block action discards 570: new routes coming from the protocol. Restart and disable actions shut 571: the protocol down like appropriate commands. Disable is the default 572: action if an action is not explicitly specified. Note that limits are 573: reset during protocol reconfigure, reload or restart. Default: <cf/off/. 574: 575: <tag><label id="proto-receive-limit">receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag> 576: Specify an receive route limit (a maximum number of routes received from 577: the protocol and remembered). It works almost identically to <cf>import 578: limit</cf> option, the only difference is that if <cf/import keep 579: filtered/ option is active, filtered routes are counted towards the 580: limit and blocked routes are forgotten, as the main purpose of the 581: receive limit is to protect routing tables from overflow. Import limit, 582: on the contrary, counts accepted routes only and routes blocked by the 583: limit are handled like filtered routes. Default: <cf/off/. 584: 585: <tag><label id="proto-export-limit">export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag> 586: Specify an export route limit, works similarly to the <cf>import 587: limit</cf> option, but for the routes exported to the protocol. This 588: option is experimental, there are some problems in details of its 589: behavior -- the number of exported routes can temporarily exceed the 590: limit without triggering it during protocol reload, exported routes 591: counter ignores route blocking and block action also blocks route 592: updates of already accepted routes -- and these details will probably 593: change in the future. Default: <cf/off/. 594: 595: <tag><label id="proto-description">description "<m/text/"</tag> 596: This is an optional description of the protocol. It is displayed as a 597: part of the output of 'show route all' command. 598: 599: <tag><label id="proto-table">table <m/name/</tag> 600: Connect this protocol to a non-default routing table. 601: </descrip> 602: 603: There are several options that give sense only with certain protocols: 604: 605: <descrip> 606: <tag><label id="proto-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../] [ { <m/option/; [<m/.../] } ]</tag> 607: Specifies a set of interfaces on which the protocol is activated with 608: given interface-specific options. A set of interfaces specified by one 609: interface option is described using an interface pattern. The interface 610: pattern consists of a sequence of clauses (separated by commas), each 611: clause is a mask specified as a shell-like pattern. Interfaces are 612: matched by their name. 613: 614: An interface matches the pattern if it matches any of its clauses. If 615: the clause begins with <cf/-/, matching interfaces are excluded. Patterns 616: are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/ 617: means eth0 and all non-ethernets. 618: 619: Some protocols (namely OSPFv2 and Direct) support extended clauses that 620: may contain a mask, a prefix, or both of them. An interface matches such 621: clause if its name matches the mask (if specified) and its address 622: matches the prefix (if specified). Extended clauses are used when the 623: protocol handles multiple addresses on an interface independently. 624: 625: An interface option can be used more times with different interface-specific 626: options, in that case for given interface the first matching interface 627: option is used. 628: 629: This option is allowed in Babel, BFD, Direct, OSPF, RAdv and RIP 630: protocols, but in OSPF protocol it is used in the <cf/area/ subsection. 631: 632: Default: none. 633: 634: Examples: 635: 636: <cf>interface "*" { type broadcast; };</cf> - start the protocol on all 637: interfaces with <cf>type broadcast</cf> option. 638: 639: <cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the 640: protocol on enumerated interfaces with <cf>type ptp</cf> option. 641: 642: <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol 643: on all interfaces that have address from 192.168.0.0/16, but not from 644: 192.168.1.0/24. 645: 646: <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol 647: on all interfaces that have address from 192.168.0.0/16, but not from 648: 192.168.1.0/24. 649: 650: <cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all 651: ethernet interfaces that have address from 192.168.1.0/24. 652: 653: <tag><label id="proto-tx-class">tx class|dscp <m/num/</tag> 654: This option specifies the value of ToS/DS/Class field in IP headers of 655: the outgoing protocol packets. This may affect how the protocol packets 656: are processed by the network relative to the other network traffic. With 657: <cf/class/ keyword, the value (0-255) is used for the whole ToS/Class 658: octet (but two bits reserved for ECN are ignored). With <cf/dscp/ 659: keyword, the value (0-63) is used just for the DS field in the octet. 660: Default value is 0xc0 (DSCP 0x30 - CS6). 661: 662: <tag><label id="proto-tx-priority">tx priority <m/num/</tag> 663: This option specifies the local packet priority. This may affect how the 664: protocol packets are processed in the local TX queues. This option is 665: Linux specific. Default value is 7 (highest priority, privileged traffic). 666: 667: <tag><label id="proto-pass">password "<m/password/" [ { <m>password options</m> } ]</tag> 668: Specifies a password that can be used by the protocol as a shared secret 669: key. Password option can be used more times to specify more passwords. 670: If more passwords are specified, it is a protocol-dependent decision 671: which one is really used. Specifying passwords does not mean that 672: authentication is enabled, authentication can be enabled by separate, 673: protocol-dependent <cf/authentication/ option. 674: 675: This option is allowed in BFD, OSPF and RIP protocols. BGP has also 676: <cf/password/ option, but it is slightly different and described 677: separately. 678: Default: none. 679: </descrip> 680: 681: Password option can contain section with some (not necessary all) password sub-options: 682: 683: <descrip> 684: <tag><label id="proto-pass-id">id <M>num</M></tag> 685: ID of the password, (1-255). If it is not used, BIRD will choose ID based 686: on an order of the password item in the interface. For example, second 687: password item in one interface will have default ID 2. ID is used by 688: some routing protocols to identify which password was used to 689: authenticate protocol packets. 690: 691: <tag><label id="proto-pass-gen-from">generate from "<m/time/"</tag> 692: The start time of the usage of the password for packet signing. 693: The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>. 694: 695: <tag><label id="proto-pass-gen-to">generate to "<m/time/"</tag> 696: The last time of the usage of the password for packet signing. 697: 698: <tag><label id="proto-pass-accept-from">accept from "<m/time/"</tag> 699: The start time of the usage of the password for packet verification. 700: 701: <tag><label id="proto-pass-accept-to">accept to "<m/time/"</tag> 702: The last time of the usage of the password for packet verification. 703: 704: <tag><label id="proto-pass-from">from "<m/time/"</tag> 705: Shorthand for setting both <cf/generate from/ and <cf/accept from/. 706: 707: <tag><label id="proto-pass-to">to "<m/time/"</tag> 708: Shorthand for setting both <cf/generate to/ and <cf/accept to/. 709: 710: <tag><label id="proto-pass-algorithm">algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 )</tag> 711: The message authentication algorithm for the password when cryptographic 712: authentication is enabled. The default value depends on the protocol. 713: For RIP and OSPFv2 it is Keyed-MD5 (for compatibility), for OSPFv3 714: protocol it is HMAC-SHA-256. 715: 716: </descrip> 717: 718: <chapt>Remote control 719: <label id="remote-control"> 720: 721: You can use the command-line client <file>birdc</file> to talk with a running 722: BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless 723: changed with the <tt/-s/ option given to both the server and the client). The 724: commands can perform simple actions such as enabling/disabling of protocols, 725: telling BIRD to show various information, telling it to show routing table 726: filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to 727: get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD 728: client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can 729: be passed to the client, to make it dump numeric return codes along with the 730: messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your 731: own applications could do that, too -- the format of communication between BIRD 732: and <file/birdc/ is stable (see the programmer's documentation). 733: 734: There is also lightweight variant of BIRD client called <file/birdcl/, which 735: does not support command line editing and history and has minimal dependencies. 736: This is useful for running BIRD in resource constrained environments, where 737: Readline library (required for regular BIRD client) is not available. 738: 739: Many commands have the <m/name/ of the protocol instance as an argument. 740: This argument can be omitted if there exists only a single instance. 741: 742: Here is a brief list of supported functions: 743: 744: <descrip> 745: <tag><label id="cli-show-status">show status</tag> 746: Show router status, that is BIRD version, uptime and time from last 747: reconfiguration. 748: 749: <tag><label id="cli-show-interfaces">show interfaces [summary]</tag> 750: Show the list of interfaces. For each interface, print its type, state, 751: MTU and addresses assigned. 752: 753: <tag><label id="cli-show-protocols">show protocols [all]</tag> 754: Show list of protocol instances along with tables they are connected to 755: and protocol status, possibly giving verbose information, if <cf/all/ is 756: specified. 757: 758: <tag><label id="cli-show-ospf-iface">show ospf interface [<m/name/] ["<m/interface/"]</tag> 759: Show detailed information about OSPF interfaces. 760: 761: <tag><label id="cli-show-ospf-neighbors">show ospf neighbors [<m/name/] ["<m/interface/"]</tag> 762: Show a list of OSPF neighbors and a state of adjacency to them. 763: 764: <tag><label id="cli-show-ospf-state">show ospf state [all] [<m/name/]</tag> 765: Show detailed information about OSPF areas based on a content of the 766: link-state database. It shows network topology, stub networks, 767: aggregated networks and routers from other areas and external routes. 768: The command shows information about reachable network nodes, use option 769: <cf/all/ to show information about all network nodes in the link-state 770: database. 771: 772: <tag><label id="cli-show-ospf-topology">show ospf topology [all] [<m/name/]</tag> 773: Show a topology of OSPF areas based on a content of the link-state 774: database. It is just a stripped-down version of 'show ospf state'. 775: 776: <tag><label id="cli-show-ospf-lsadb">show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag> 777: Show contents of an OSPF LSA database. Options could be used to filter 778: entries. 779: 780: <tag><label id="cli-show-rip-interfaces">show rip interfaces [<m/name/] ["<m/interface/"]</tag> 781: Show detailed information about RIP interfaces. 782: 783: <tag><label id="cli-show-rip-neighbors">show rip neighbors [<m/name/] ["<m/interface/"]</tag> 784: Show a list of RIP neighbors and associated state. 785: 786: <tag><label id="cli-show-static">show static [<m/name/]</tag> 787: Show detailed information about static routes. 788: 789: <tag><label id="cli-show-bfd-sessions">show bfd sessions [<m/name/]</tag> 790: Show information about BFD sessions. 791: 792: <tag><label id="cli-show-symbols">show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag> 793: Show the list of symbols defined in the configuration (names of 794: protocols, routing tables etc.). 795: 796: <tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table <m/t/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag> 797: Show contents of a routing table (by default of the main one or the 798: table attached to a respective protocol), that is routes, their metrics 799: and (in case the <cf/all/ switch is given) all their attributes. 800: 801: You can specify a <m/prefix/ if you want to print routes for a 802: specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get 803: the entry which will be used for forwarding of packets to the given 804: destination. By default, all routes for each network are printed with 805: the selected one at the top, unless <cf/primary/ is given in which case 806: only the selected route is shown. 807: 808: You can also ask for printing only routes processed and accepted by 809: a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ } 810: </cf> or matching a given condition (<cf>where <m/condition/</cf>). 811: 812: The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for 813: printing of routes that are exported to the specified protocol. 814: With <cf/preexport/, the export filter of the protocol is skipped. 815: With <cf/noexport/, routes rejected by the export filter are printed 816: instead. Note that routes not exported to the protocol for other reasons 817: (e.g. secondary routes or routes imported from that protocol) are not 818: printed even with <cf/noexport/. 819: 820: You can also select just routes added by a specific protocol. 821: <cf>protocol <m/p/</cf>. 822: 823: If BIRD is configured to keep filtered routes (see <cf/import keep 824: filtered/ option), you can show them instead of routes by using 825: <cf/filtered/ switch. 826: 827: The <cf/stats/ switch requests showing of route statistics (the 828: number of networks, number of routes before and after filtering). If 829: you use <cf/count/ instead, only the statistics will be printed. 830: 831: <tag><label id="cli-show-roa">show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/]</tag> 832: Show contents of a ROA table (by default of the first one). You can 833: specify a <m/prefix/ to print ROA entries for a specific network. If you 834: use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route 835: validation of the network prefix; i.e., ROA entries whose prefixes cover 836: the network prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA 837: entries covered by the network prefix. You could also use <cf/as/ option 838: to show just entries for given AS. 839: 840: <tag><label id="cli-add-roa">add roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag> 841: Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/ 842: compared to <it/static/ entries specified in the config file. These 843: dynamic entries survive reconfiguration. 844: 845: <tag><label id="cli-delete-roa">delete roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag> 846: Delete the specified ROA entry from a ROA table. Only dynamic ROA 847: entries (i.e., the ones added by <cf/add roa/ command) can be deleted. 848: 849: <tag><label id="cli-flush-roa">flush roa [table <m/t/]</tag> 850: Remove all dynamic ROA entries from a ROA table. 851: 852: <tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag> 853: Reload configuration from a given file. BIRD will smoothly switch itself 854: to the new configuration, protocols are reconfigured if possible, 855: restarted otherwise. Changes in filters usually lead to restart of 856: affected protocols. 857: 858: If <cf/soft/ option is used, changes in filters does not cause BIRD to 859: restart affected protocols, therefore already accepted routes (according 860: to old filters) would be still propagated, but new routes would be 861: processed according to the new filters. 862: 863: If <cf/timeout/ option is used, config timer is activated. The new 864: configuration could be either confirmed using <cf/configure confirm/ 865: command, or it will be reverted to the old one when the config timer 866: expires. This is useful for cases when reconfiguration breaks current 867: routing and a router becomes inaccessible for an administrator. The 868: config timeout expiration is equivalent to <cf/configure undo/ 869: command. The timeout duration could be specified, default is 300 s. 870: 871: <tag><label id="cli-configure-confirm">configure confirm</tag> 872: Deactivate the config undo timer and therefore confirm the current 873: configuration. 874: 875: <tag><label id="cli-configure-undo">configure undo</tag> 876: Undo the last configuration change and smoothly switch back to the 877: previous (stored) configuration. If the last configuration change was 878: soft, the undo change is also soft. There is only one level of undo, but 879: in some specific cases when several reconfiguration requests are given 880: immediately in a row and the intermediate ones are skipped then the undo 881: also skips them back. 882: 883: <tag><label id="cli-configure-check">configure check ["<m/config file/"]</tag> 884: Read and parse given config file, but do not use it. useful for checking 885: syntactic and some semantic validity of an config file. 886: 887: <tag><label id="cli-enable-disable-restart">enable|disable|restart <m/name/|"<m/pattern/"|all</tag> 888: Enable, disable or restart a given protocol instance, instances matching 889: the <cf><m/pattern/</cf> or <cf/all/ instances. 890: 891: <tag><label id="cli-reload">reload [in|out] <m/name/|"<m/pattern/"|all</tag> 892: Reload a given protocol instance, that means re-import routes from the 893: protocol instance and re-export preferred routes to the instance. If 894: <cf/in/ or <cf/out/ options are used, the command is restricted to one 895: direction (re-import or re-export). 896: 897: This command is useful if appropriate filters have changed but the 898: protocol instance was not restarted (or reloaded), therefore it still 899: propagates the old set of routes. For example when <cf/configure soft/ 900: command was used to change filters. 901: 902: Re-export always succeeds, but re-import is protocol-dependent and might 903: fail (for example, if BGP neighbor does not support route-refresh 904: extension). In that case, re-export is also skipped. Note that for the 905: pipe protocol, both directions are always reloaded together (<cf/in/ or 906: <cf/out/ options are ignored in that case). 907: 908: <tag><label id="cli-down">down</tag> 909: Shut BIRD down. 910: 911: <tag><label id="cli-debug">debug <m/protocol/|<m/pattern/|all all|off|{ states|routes|filters|events|packets [, <m/.../] }</tag> 912: Control protocol debugging. 913: 914: <tag><label id="cli-dump">dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag> 915: Dump contents of internal data structures to the debugging output. 916: 917: <tag><label id="cli-echo">echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag> 918: Control echoing of log messages to the command-line output. 919: See <ref id="opt-log" name="log option"> for a list of log classes. 920: 921: <tag><label id="cli-eval">eval <m/expr/</tag> 922: Evaluate given expression. 923: </descrip> 924: 925: 926: <chapt>Filters 927: <label id="filters"> 928: 929: <sect>Introduction 930: <label id="filters-intro"> 931: 932: BIRD contains a simple programming language. (No, it can't yet read mail :-). 933: There are two objects in this language: filters and functions. Filters are 934: interpreted by BIRD core when a route is being passed between protocols and 935: routing tables. The filter language contains control structures such as if's and 936: switches, but it allows no loops. An example of a filter using many features can 937: be found in <file>filter/test.conf</file>. 938: 939: Filter gets the route, looks at its attributes and modifies some of them if 940: it wishes. At the end, it decides whether to pass the changed route through 941: (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks like 942: this: 943: 944: <code> 945: filter not_too_far 946: int var; 947: { 948: if defined( rip_metric ) then 949: var = rip_metric; 950: else { 951: var = 1; 952: rip_metric = 1; 953: } 954: if rip_metric > 10 then 955: reject "RIP metric is too big"; 956: else 957: accept "ok"; 958: } 959: </code> 960: 961: As you can see, a filter has a header, a list of local variables, and a body. 962: The header consists of the <cf/filter/ keyword followed by a (unique) name of 963: filter. The list of local variables consists of <cf><M>type name</M>;</cf> 964: pairs where each pair defines one local variable. The body consists of <cf> 965: { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You 966: can group several statements to a single compound statement by using braces 967: (<cf>{ <M>statements</M> }</cf>) which is useful if you want to make a bigger 968: block of code conditional. 969: 970: BIRD supports functions, so that you don't have to repeat the same blocks of 971: code over and over. Functions can have zero or more parameters and they can have 972: local variables. Recursion is not allowed. Function definitions look like this: 973: 974: <code> 975: function name () 976: int local_variable; 977: { 978: local_variable = 5; 979: } 980: 981: function with_parameters (int parameter) 982: { 983: print parameter; 984: } 985: </code> 986: 987: Unlike in C, variables are declared after the <cf/function/ line, but before 988: the first <cf/{/. You can't declare variables in nested blocks. Functions are 989: called like in C: <cf>name(); with_parameters(5);</cf>. Function may return 990: values using the <cf>return <m/[expr]/</cf> command. Returning a value exits 991: from current function (this is similar to C). 992: 993: Filters are declared in a way similar to functions except they can't have 994: explicit parameters. They get a route table entry as an implicit parameter, it 995: is also passed automatically to any functions called. The filter must terminate 996: with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in 997: filter, the route is rejected. 998: 999: A nice trick to debug filters is to use <cf>show route filter <m/name/</cf> 1000: from the command line client. An example session might look like: 1001: 1002: <code> 1003: pavel@bug:~/bird$ ./birdc -s bird.ctl 1004: BIRD 0.0.0 ready. 1005: bird> show route 1006: 10.0.0.0/8 dev eth0 [direct1 23:21] (240) 1007: 195.113.30.2/32 dev tunl1 [direct1 23:21] (240) 1008: 127.0.0.0/8 dev lo [direct1 23:21] (240) 1009: bird> show route ? 1010: show route [<prefix>] [table <t>] [filter <f>] [all] [primary]... 1011: bird> show route filter { if 127.0.0.5 &tilde; net then accept; } 1012: 127.0.0.0/8 dev lo [direct1 23:21] (240) 1013: bird> 1014: </code> 1015: 1016: 1017: <sect>Data types 1018: <label id="data-types"> 1019: 1020: Each variable and each value has certain type. Booleans, integers and enums 1021: are incompatible with each other (that is to prevent you from shooting in the 1022: foot). 1023: 1024: <descrip> 1025: <tag><label id="type-bool">bool</tag> 1026: This is a boolean type, it can have only two values, <cf/true/ and 1027: <cf/false/. Boolean is the only type you can use in <cf/if/ statements. 1028: 1029: <tag><label id="type-int">int</tag> 1030: This is a general integer type. It is an unsigned 32bit type; i.e., you 1031: can expect it to store values from 0 to 4294967295. Overflows are not 1032: checked. You can use <cf/0x1234/ syntax to write hexadecimal values. 1033: 1034: <tag><label id="type-pair">pair</tag> 1035: This is a pair of two short integers. Each component can have values 1036: from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/. 1037: The same syntax can also be used to construct a pair from two arbitrary 1038: integer expressions (for example <cf/(1+2,a)/). 1039: 1040: <tag><label id="type-quad">quad</tag> 1041: This is a dotted quad of numbers used to represent router IDs (and 1042: others). Each component can have a value from 0 to 255. Literals of 1043: this type are written like IPv4 addresses. 1044: 1045: <tag><label id="type-string">string</tag> 1046: This is a string of characters. There are no ways to modify strings in 1047: filters. You can pass them between functions, assign them to variables 1048: of type <cf/string/, print such variables, use standard string 1049: comparison operations (e.g. <cf/=, !=, <, >, <=, >=/), but 1050: you can't concatenate two strings. String literals are written as 1051: <cf/"This is a string constant"/. Additionally matching (<cf/&tilde;, 1052: !&tilde;/) operators could be used to match a string value against 1053: a shell pattern (represented also as a string). 1054: 1055: <tag><label id="type-ip">ip</tag> 1056: This type can hold a single IP address. Depending on the compile-time 1057: configuration of BIRD you are using, it is either an IPv4 or IPv6 1058: address. IP addresses are written in the standard notation 1059: (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator 1060: <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but 1061: first <cf><M>num</M></cf> bits from the IP address. So 1062: <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. 1063: 1064: <tag><label id="type-prefix">prefix</tag> 1065: This type can hold a network prefix consisting of IP address and prefix 1066: length. Prefix literals are written as <cf><m/ipaddress//<m/pxlen/</cf>, 1067: or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special 1068: operators on prefixes: <cf/.ip/ which extracts the IP address from the 1069: pair, and <cf/.len/, which separates prefix length from the pair. 1070: So <cf>1.2.0.0/16.len = 16</cf> is true. 1071: 1072: <tag><label id="type-ec">ec</tag> 1073: This is a specialized type used to represent BGP extended community 1074: values. It is essentially a 64bit value, literals of this type are 1075: usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where 1076: <cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a 1077: route target / route origin communities), the format and possible values 1078: of <cf/key/ and <cf/value/ are usually integers, but it depends on the 1079: used kind. Similarly to pairs, ECs can be constructed using expressions 1080: for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where 1081: <cf/myas/ is an integer variable). 1082: 1083: <tag><label id="type-lc">lc</tag> 1084: This is a specialized type used to represent BGP large community 1085: values. It is essentially a triplet of 32bit values, where the first 1086: value is reserved for the AS number of the issuer, while meaning of 1087: remaining parts is defined by the issuer. Literals of this type are 1088: written as <cf/(123, 456, 789)/, with any integer values. Similarly to 1089: pairs, LCs can be constructed using expressions for its parts, (e.g. 1090: <cf/(myas, 10+20, 3*10)/, where <cf/myas/ is an integer variable). 1091: 1092: <tag><label id="type-set">int|pair|quad|ip|prefix|ec|lc|enum set</tag> 1093: Filters recognize four types of sets. Sets are similar to strings: you 1094: can pass them around but you can't modify them. Literals of type <cf>int 1095: set</cf> look like <cf> [ 1, 2, 5..7 ]</cf>. As you can see, both simple 1096: values and ranges are permitted in sets. 1097: 1098: For pair sets, expressions like <cf/(123,*)/ can be used to denote 1099: ranges (in that case <cf/(123,0)..(123,65535)/). You can also use 1100: <cf/(123,5..100)/ for range <cf/(123,5)..(123,100)/. You can also use 1101: <cf/*/ and <cf/a..b/ expressions in the first part of a pair, note that 1102: such expressions are translated to a set of intervals, which may be 1103: memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20), 1104: (1,4..20), (2,4..20), ... (65535, 4..20)/. 1105: 1106: EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123, 1107: 10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation 1108: (like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range 1109: for ASNs). 1110: 1111: Also LC sets use similar expressions like pair sets. You can use ranges 1112: and wildcards, but if one field uses that, more specific (later) fields 1113: must be wildcards. E.g., <cf/(10, 20..30, *)/ or <cf/(10, 20, 30..40)/ 1114: is valid, while <cf/(10, *, 20..30)/ or <cf/(10, 20..30, 40)/ is not 1115: valid. 1116: 1117: You can also use expressions for int, pair, EC and LC set values. 1118: However, it must be possible to evaluate these expressions before daemon 1119: boots. So you can use only constants inside them. E.g. 1120: 1121: <code> 1122: define one=1; 1123: define myas=64500; 1124: int set odds; 1125: pair set ps; 1126: ec set es; 1127: 1128: odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ]; 1129: ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ]; 1130: es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ]; 1131: </code> 1132: 1133: Sets of prefixes are special: their literals does not allow ranges, but 1134: allows prefix patterns that are written 1135: as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>. 1136: Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix 1137: pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if the 1138: first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are 1139: identical and <cf>len1 <= ip1 <= len2</cf>. A valid prefix pattern 1140: has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not 1141: constrained by <cf/low/ or <cf/high/. Obviously, a prefix matches a 1142: prefix set literal if it matches any prefix pattern in the prefix set 1143: literal. 1144: 1145: There are also two shorthands for prefix patterns: <cf><m/address//<m/len/+</cf> 1146: is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf> 1147: (where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means 1148: network prefix <cf><m/address//<m/len/</cf> and all its subnets. 1149: <cf><m/address//<m/len/-</cf> is a shorthand for 1150: <cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix 1151: <cf><m/address//<m/len/</cf> and all its supernets (network prefixes 1152: that contain it). 1153: 1154: For example, <cf>[ 1.0.0.0/8, 2.0.0.0/8+, 3.0.0.0/8-, 4.0.0.0/8{16,24} 1155: ]</cf> matches prefix <cf>1.0.0.0/8</cf>, all subprefixes of 1156: <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes 1157: <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf> 1158: matches all prefixes (regardless of IP address) whose prefix length is 1159: 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP 1160: address <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> 1161: is true, but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false. 1162: 1163: Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed 1164: in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 1165: <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as 1166: <cf>192.168.0.0/16{24,32}</cf>. 1167: 1168: <tag><label id="type-enum">enum</tag> 1169: Enumeration types are fixed sets of possibilities. You can't define your 1170: own variables of such type, but some route attributes are of enumeration 1171: type. Enumeration types are incompatible with each other. 1172: 1173: <tag><label id="type-bgppath">bgppath</tag> 1174: BGP path is a list of autonomous system numbers. You can't write 1175: literals of this type. There are several special operators on bgppaths: 1176: 1177: <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/. 1178: 1179: <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/. 1180: 1181: <cf><m/P/.last_nonaggregated</cf> returns the last ASN in the non-aggregated part of the path <m/P/. 1182: 1183: Both <cf/first/ and <cf/last/ return zero if there is no appropriate 1184: ASN, for example if the path contains an AS set element as the first (or 1185: the last) part. If the path ends with an AS set, <cf/last_nonaggregated/ 1186: may be used to get last ASN before any AS set. 1187: 1188: <cf><m/P/.len</cf> returns the length of path <m/P/. 1189: 1190: <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and 1191: returns the result. 1192: 1193: <cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from 1194: from path <m/P/ and returns the result. <m/A/ may also be an integer 1195: set, in that case the operator deletes all ASNs from path <m/P/ that are 1196: also members of set <m/A/. 1197: 1198: <cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are 1199: not members of integer set <m/A/. I.e., <cf/filter/ do the same as 1200: <cf/delete/ with inverted set <m/A/. 1201: 1202: Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to 1203: <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute 1204: (for example <cf/bgp_path/). Similarly for <cf/delete/ and <cf/filter/. 1205: 1206: <tag><label id="type-bgpmask">bgpmask</tag> 1207: BGP masks are patterns used for BGP path matching (using <cf>path 1208: &tilde; [= 2 3 5 * =]</cf> syntax). The masks resemble wildcard patterns 1209: as used by UNIX shells. Autonomous system numbers match themselves, 1210: <cf/*/ matches any (even empty) sequence of arbitrary AS numbers and 1211: <cf/?/ matches one arbitrary AS number. For example, if <cf>bgp_path</cf> 1212: is 4 3 2 1, then: <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, 1213: but <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false. BGP mask 1214: expressions can also contain integer expressions enclosed in parenthesis 1215: and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. You can 1216: also use ranges, for example <tt>[= * 3..5 2 100..200 * =]</tt>. 1217: There is also old (deprecated) syntax that uses / .. / instead of [= .. =] 1218: and ? instead of *. 1219: 1220: <tag><label id="type-clist">clist</tag> 1221: Clist is similar to a set, except that unlike other sets, it can be 1222: modified. The type is used for community list (a set of pairs) and for 1223: cluster list (a set of quads). There exist no literals of this type. 1224: There are three special operators on clists: 1225: 1226: <cf><m/C/.len</cf> returns the length of clist <m/C/. 1227: 1228: <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and 1229: returns the result. If item <m/P/ is already in clist <m/C/, it does 1230: nothing. <m/P/ may also be a clist, in that case all its members are 1231: added; i.e., it works as clist union. 1232: 1233: <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) <m/P/ from clist 1234: <m/C/ and returns the result. If clist <m/C/ does not contain item 1235: <m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that 1236: case the operator deletes all items from clist <m/C/ that are also 1237: members of set <m/P/. Moreover, <m/P/ may also be a clist, which works 1238: analogously; i.e., it works as clist difference. 1239: 1240: <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are 1241: not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same 1242: as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which 1243: works analogously; i.e., it works as clist intersection. 1244: 1245: Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to 1246: <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute (for 1247: example <cf/bgp_community/). Similarly for <cf/delete/ and <cf/filter/. 1248: 1249: <tag><label id="type-eclist">eclist</tag> 1250: Eclist is a data type used for BGP extended community lists. Eclists 1251: are very similar to clists, but they are sets of ECs instead of pairs. 1252: The same operations (like <cf/add/, <cf/delete/ or <cf/&tilde;/ and 1253: <cf/!&tilde;/ membership operators) can be used to modify or test 1254: eclists, with ECs instead of pairs as arguments. 1255: 1256: <tag/lclist/ 1257: Lclist is a data type used for BGP large community lists. Like eclists, 1258: lclists are very similar to clists, but they are sets of LCs instead of 1259: pairs. The same operations (like <cf/add/, <cf/delete/ or <cf/&tilde;/ 1260: and <cf/!&tilde;/ membership operators) can be used to modify or test 1261: lclists, with LCs instead of pairs as arguments. 1262: </descrip> 1263: 1264: 1265: <sect>Operators 1266: <label id="operators"> 1267: 1268: The filter language supports common integer operators <cf>(+,-,*,/)</cf>, 1269: parentheses <cf/(a*(b+c))/, comparison <cf/(a=b, a!=b, a<b, a>=b)/. 1270: Logical operations include unary not (<cf/!/), and (<cf/&&/) and or 1271: (<cf/||/). Special operators include (<cf/&tilde;/, 1272: <cf/!&tilde;/) for "is (not) element of a set" operation - it can be used on 1273: element and set of elements of the same type (returning true if element is 1274: contained in the given set), or on two strings (returning true if first string 1275: matches a shell-like pattern stored in second string) or on IP and prefix 1276: (returning true if IP is within the range defined by that prefix), or on prefix 1277: and prefix (returning true if first prefix is more specific than second one) or 1278: on bgppath and bgpmask (returning true if the path matches the mask) or on 1279: number and bgppath (returning true if the number is in the path) or on bgppath 1280: and int (number) set (returning true if any ASN from the path is in the set) or 1281: on pair/quad and clist (returning true if the pair/quad is element of the 1282: clist) or on clist and pair/quad set (returning true if there is an element of 1283: the clist that is also a member of the pair/quad set). 1284: 1285: There is one operator related to ROA infrastructure - <cf/roa_check()/. It 1286: examines a ROA table and does <rfc id="6483"> route origin validation for a 1287: given network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which 1288: checks current route (which should be from BGP to have AS_PATH argument) in the 1289: specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA, 1290: ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant 1291: ROAs but none of them match. There is also an extended variant 1292: <cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a 1293: prefix and an ASN as arguments. 1294: 1295: 1296: <sect>Control structures 1297: <label id="control-structures"> 1298: 1299: Filters support two control structures: conditions and case switches. 1300: 1301: Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/command1/; 1302: else <m/command2/;</cf> and you can use <cf>{ <m/command_1/; <m/command_2/; 1303: <M>...</M> }</cf> instead of either command. The <cf>else</cf> clause may be 1304: omitted. If the <cf><m>boolean expression</m></cf> is true, <m/command1/ is 1305: executed, otherwise <m/command2/ is executed. 1306: 1307: The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case 1308: <m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ 1309: ... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be 1310: on the left side of the &tilde; operator and anything that could be a member of 1311: a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ 1312: grouping. If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements 1313: between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches 1314: neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed. 1315: 1316: Here is example that uses <cf/if/ and <cf/case/ structures: 1317: 1318: <code> 1319: case arg1 { 1320: 2: print "two"; print "I can do more commands without {}"; 1321: 3 .. 5: print "three to five"; 1322: else: print "something else"; 1323: } 1324: 1325: if 1234 = i then printn "."; else { 1326: print "not 1234"; 1327: print "You need {} around multiple commands"; 1328: } 1329: </code> 1330: 1331: 1332: <sect>Route attributes 1333: <label id="route-attributes"> 1334: 1335: A filter is implicitly passed a route, and it can access its attributes just 1336: like it accesses variables. Attempts to access undefined attribute result in a 1337: runtime error; you can check if an attribute is defined by using the 1338: <cf>defined( <m>attribute</m> )</cf> operator. One notable exception to this 1339: rule are attributes of clist type, where undefined value is regarded as empty 1340: clist for most purposes. 1341: 1342: <descrip> 1343: <tag><label id="rta-net"><m/prefix/ net</tag> 1344: Network the route is talking about. Read-only. (See the chapter about 1345: routing tables.) 1346: 1347: <tag><label id="rta-scope"><m/enum/ scope</tag> 1348: The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes 1349: local to this host, <cf/SCOPE_LINK/ for those specific for a physical 1350: link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and 1351: <cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not 1352: interpreted by BIRD and can be used to mark routes in filters. The 1353: default value for new routes is <cf/SCOPE_UNIVERSE/. 1354: 1355: <tag><label id="rta-preference"><m/int/ preference</tag> 1356: Preference of the route. Valid values are 0-65535. (See the chapter 1357: about routing tables.) 1358: 1359: <tag><label id="rta-from"><m/ip/ from</tag> 1360: The router which the route has originated from. 1361: 1362: <tag><label id="rta-gw"><m/ip/ gw</tag> 1363: Next hop packets routed using this route should be forwarded to. 1364: 1365: <tag><label id="rta-proto"><m/string/ proto</tag> 1366: The name of the protocol which the route has been imported from. 1367: Read-only. 1368: 1369: <tag><label id="rta-source"><m/enum/ source</tag> 1370: what protocol has told me about this route. Possible values: 1371: <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/, 1372: <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/, 1373: <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, 1374: <cf/RTS_PIPE/, <cf/RTS_BABEL/. 1375: 1376: <tag><label id="rta-cast"><m/enum/ cast</tag> 1377: Route type (Currently <cf/RTC_UNICAST/ for normal routes, 1378: <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will be used in 1379: the future for broadcast, multicast and anycast routes). Read-only. 1380: 1381: <tag><label id="rta-dest"><m/enum/ dest</tag> 1382: Type of destination the packets should be sent to 1383: (<cf/RTD_ROUTER/ for forwarding to a neighboring router, 1384: <cf/RTD_DEVICE/ for routing to a directly-connected network, 1385: <cf/RTD_MULTIPATH/ for multipath destinations, 1386: <cf/RTD_BLACKHOLE/ for packets to be silently discarded, 1387: <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be 1388: returned with ICMP host unreachable / ICMP administratively prohibited 1389: messages). Can be changed, but only to <cf/RTD_BLACKHOLE/, 1390: <cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/. 1391: 1392: <tag><label id="rta-ifname"><m/string/ ifname</tag> 1393: Name of the outgoing interface. Sink routes (like blackhole, unreachable 1394: or prohibit) and multipath routes have no interface associated with 1395: them, so <cf/ifname/ returns an empty string for such routes. Read-only. 1396: 1397: <tag><label id="rta-ifindex"><m/int/ ifindex</tag> 1398: Index of the outgoing interface. System wide index of the interface. May 1399: be used for interface matching, however indexes might change on interface 1400: creation/removal. Zero is returned for routes with undefined outgoing 1401: interfaces. Read-only. 1402: 1403: <tag><label id="rta-igp-metric"><m/int/ igp_metric</tag> 1404: The optional attribute that can be used to specify a distance to the 1405: network for routes that do not have a native protocol metric attribute 1406: (like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to 1407: compare internal distances to boundary routers (see below). It is also 1408: used when the route is exported to OSPF as a default value for OSPF type 1409: 1 metric. 1410: </descrip> 1411: 1412: There also exist some protocol-specific attributes which are described in the 1413: corresponding protocol sections. 1414: 1415: 1416: <sect>Other statements 1417: <label id="other-statements"> 1418: 1419: The following statements are available: 1420: 1421: <descrip> 1422: <tag><label id="assignment"><m/variable/ = <m/expr/</tag> 1423: Set variable to a given value. 1424: 1425: <tag><label id="filter-accept-reject">accept|reject [ <m/expr/ ]</tag> 1426: Accept or reject the route, possibly printing <cf><m>expr</m></cf>. 1427: 1428: <tag><label id="return">return <m/expr/</tag> 1429: Return <cf><m>expr</m></cf> from the current function, the function ends 1430: at this point. 1431: 1432: <tag><label id="print">print|printn <m/expr/ [<m/, expr.../]</tag> 1433: Prints given expressions; useful mainly while debugging filters. The 1434: <cf/printn/ variant does not terminate the line. 1435: 1436: <tag><label id="quitbird">quitbird</tag> 1437: Terminates BIRD. Useful when debugging the filter interpreter. 1438: </descrip> 1439: 1440: 1441: <chapt>Protocols 1442: <label id="protocols"> 1443: 1444: <sect>Babel 1445: <label id="babel"> 1446: 1447: <sect1>Introduction 1448: <label id="babel-intro"> 1449: 1450: The Babel protocol 1451: (<rfc id="6126">) is a loop-avoiding distance-vector routing protocol that is 1452: robust and efficient both in ordinary wired networks and in wireless mesh 1453: networks. Babel is conceptually very simple in its operation and "just works" 1454: in its default configuration, though some configuration is possible and in some 1455: cases desirable. 1456: 1457: While the Babel protocol is dual stack (i.e., can carry both IPv4 and IPv6 1458: routes over the same IPv6 transport), BIRD presently implements only the IPv6 1459: subset of the protocol. No Babel extensions are implemented, but the BIRD 1460: implementation can coexist with implementations using the extensions (and will 1461: just ignore extension messages). 1462: 1463: The Babel protocol implementation in BIRD is currently in alpha stage. 1464: 1465: <sect1>Configuration 1466: <label id="babel-config"> 1467: 1468: Babel supports no global configuration options apart from those common to all 1469: other protocols, but supports the following per-interface configuration options: 1470: 1471: <code> 1472: protocol babel [<name>] { 1473: interface <interface pattern> { 1474: type <wired|wireless>; 1475: rxcost <number>; 1476: hello interval <number>; 1477: update interval <number>; 1478: port <number>; 1479: tx class|dscp <number>; 1480: tx priority <number>; 1481: rx buffer <number>; 1482: tx length <number>; 1483: check link <switch>; 1484: }; 1485: } 1486: </code> 1487: 1488: <descrip> 1489: <tag><label id="babel-type">type wired|wireless </tag> 1490: This option specifies the interface type: Wired or wireless. Wired 1491: interfaces are considered more reliable, and so the default hello 1492: interval is higher, and a neighbour is considered unreachable after only 1493: a small number of "hello" packets are lost. On wireless interfaces, 1494: hello packets are sent more often, and the ETX link quality estimation 1495: technique is used to compute the metrics of routes discovered over this 1496: interface. This technique will gradually degrade the metric of routes 1497: when packets are lost rather than the more binary up/down mechanism of 1498: wired type links. Default: <cf/wired/. 1499: 1500: <tag><label id="babel-rxcost">rxcost <m/num/</tag> 1501: This specifies the RX cost of the interface. The route metrics will be 1502: computed from this value with a mechanism determined by the interface 1503: <cf/type/. Default: 96 for wired interfaces, 256 for wireless. 1504: 1505: <tag><label id="babel-hello">hello interval <m/num/</tag> 1506: Interval at which periodic "hello" messages are sent on this interface, 1507: in seconds. Default: 4 seconds. 1508: 1509: <tag><label id="babel-update">update interval <m/num/</tag> 1510: Interval at which periodic (full) updates are sent. Default: 4 times the 1511: hello interval. 1512: 1513: <tag><label id="babel-port">port <m/number/</tag> 1514: This option selects an UDP port to operate on. The default is to operate 1515: on port 6696 as specified in the Babel RFC. 1516: 1517: <tag><label id="babel-tx-class">tx class|dscp|priority <m/number/</tag> 1518: These options specify the ToS/DiffServ/Traffic class/Priority of the 1519: outgoing Babel packets. See <ref id="proto-tx-class" name="tx class"> common 1520: option for detailed description. 1521: 1522: <tag><label id="babel-rx-buffer">rx buffer <m/number/</tag> 1523: This option specifies the size of buffers used for packet processing. 1524: The buffer size should be bigger than maximal size of received packets. 1525: The default value is the interface MTU, and the value will be clamped to a 1526: minimum of 512 bytes + IP packet overhead. 1527: 1528: <tag><label id="babel-tx-length">tx length <m/number/</tag> 1529: This option specifies the maximum length of generated Babel packets. To 1530: avoid IP fragmentation, it should not exceed the interface MTU value. 1531: The default value is the interface MTU value, and the value will be 1532: clamped to a minimum of 512 bytes + IP packet overhead. 1533: 1534: <tag><label id="babel-check-link">check link <m/switch/</tag> 1535: If set, the hardware link state (as reported by OS) is taken into 1536: consideration. When the link disappears (e.g. an ethernet cable is 1537: unplugged), neighbors are immediately considered unreachable and all 1538: routes received from them are withdrawn. It is possible that some 1539: hardware drivers or platforms do not implement this feature. Default: 1540: yes. 1541: </descrip> 1542: 1543: <sect1>Attributes 1544: <label id="babel-attr"> 1545: 1546: Babel defines just one attribute: the internal babel metric of the route. It 1547: is exposed as the <cf/babel_metric/ attribute and has range from 1 to infinity 1548: (65535). 1549: 1550: <sect1>Example 1551: <label id="babel-exam"> 1552: 1553: <code> 1554: protocol babel { 1555: interface "eth*" { 1556: type wired; 1557: }; 1558: interface "wlan0", "wlan1" { 1559: type wireless; 1560: hello interval 1; 1561: rxcost 512; 1562: }; 1563: interface "tap0"; 1564: 1565: # This matches the default of babeld: redistribute all addresses 1566: # configured on local interfaces, plus re-distribute all routes received 1567: # from other babel peers. 1568: 1569: export where (source = RTS_DEVICE) || (source = RTS_BABEL); 1570: } 1571: </code> 1572: 1573: 1574: <sect>BFD 1575: <label id="bfd"> 1576: 1577: <sect1>Introduction 1578: <label id="bfd-intro"> 1579: 1580: Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it 1581: is an independent tool providing liveness and failure detection. Routing 1582: protocols like OSPF and BGP use integrated periodic "hello" messages to monitor 1583: liveness of neighbors, but detection times of these mechanisms are high (e.g. 40 1584: seconds by default in OSPF, could be set down to several seconds). BFD offers 1585: universal, fast and low-overhead mechanism for failure detection, which could be 1586: attached to any routing protocol in an advisory role. 1587: 1588: BFD consists of mostly independent BFD sessions. Each session monitors an 1589: unicast bidirectional path between two BFD-enabled routers. This is done by 1590: periodically sending control packets in both directions. BFD does not handle 1591: neighbor discovery, BFD sessions are created on demand by request of other 1592: protocols (like OSPF or BGP), which supply appropriate information like IP 1593: addresses and associated interfaces. When a session changes its state, these 1594: protocols are notified and act accordingly (e.g. break an OSPF adjacency when 1595: the BFD session went down). 1596: 1597: BIRD implements basic BFD behavior as defined in <rfc id="5880"> (some 1598: advanced features like the echo mode or authentication are not implemented), IP 1599: transport for BFD as defined in <rfc id="5881"> and <rfc id="5883"> and 1600: interaction with client protocols as defined in <rfc id="5882">. 1601: 1602: Note that BFD implementation in BIRD is currently a new feature in 1603: development, expect some rough edges and possible UI and configuration changes 1604: in the future. Also note that we currently support at most one protocol instance. 1605: 1606: BFD packets are sent with a dynamic source port number. Linux systems use by 1607: default a bit different dynamic port range than the IANA approved one 1608: (49152-65535). If you experience problems with compatibility, please adjust 1609: <cf>/proc/sys/net/ipv4/ip_local_port_range</cf> 1610: 1611: <sect1>Configuration 1612: <label id="bfd-config"> 1613: 1614: BFD configuration consists mainly of multiple definitions of interfaces. 1615: Most BFD config options are session specific. When a new session is requested 1616: and dynamically created, it is configured from one of these definitions. For 1617: sessions to directly connected neighbors, <cf/interface/ definitions are chosen 1618: based on the interface associated with the session, while <cf/multihop/ 1619: definition is used for multihop sessions. If no definition is relevant, the 1620: session is just created with the default configuration. Therefore, an empty BFD 1621: configuration is often sufficient. 1622: 1623: Note that to use BFD for other protocols like OSPF or BGP, these protocols 1624: also have to be configured to request BFD sessions, usually by <cf/bfd/ option. 1625: 1626: Some of BFD session options require <m/time/ value, which has to be specified 1627: with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds 1628: are allowed as units, practical minimum values are usually in order of tens of 1629: milliseconds. 1630: 1631: <code> 1632: protocol bfd [<name>] { 1633: interface <interface pattern> { 1634: interval <time>; 1635: min rx interval <time>; 1636: min tx interval <time>; 1637: idle tx interval <time>; 1638: multiplier <num>; 1639: passive <switch>; 1640: authentication none; 1641: authentication simple; 1642: authentication [meticulous] keyed md5|sha1; 1643: password "<text>"; 1644: password "<text>" { 1645: id <num>; 1646: generate from "<date>"; 1647: generate to "<date>"; 1648: accept from "<date>"; 1649: accept to "<date>"; 1650: from "<date>"; 1651: to "<date>"; 1652: }; 1653: }; 1654: multihop { 1655: interval <time>; 1656: min rx interval <time>; 1657: min tx interval <time>; 1658: idle tx interval <time>; 1659: multiplier <num>; 1660: passive <switch>; 1661: }; 1662: neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>]; 1663: } 1664: </code> 1665: 1666: <descrip> 1667: <tag><label id="bfd-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag> 1668: Interface definitions allow to specify options for sessions associated 1669: with such interfaces and also may contain interface specific options. 1670: See <ref id="proto-iface" name="interface"> common option for a detailed 1671: description of interface patterns. Note that contrary to the behavior of 1672: <cf/interface/ definitions of other protocols, BFD protocol would accept 1673: sessions (in default configuration) even on interfaces not covered by 1674: such definitions. 1675: 1676: <tag><label id="bfd-multihop">multihop { <m/options/ }</tag> 1677: Multihop definitions allow to specify options for multihop BFD sessions, 1678: in the same manner as <cf/interface/ definitions are used for directly 1679: connected sessions. Currently only one such definition (for all multihop 1680: sessions) could be used. 1681: 1682: <tag><label id="bfd-neighbor">neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag> 1683: BFD sessions are usually created on demand as requested by other 1684: protocols (like OSPF or BGP). This option allows to explicitly add 1685: a BFD session to the specified neighbor regardless of such requests. 1686: 1687: The session is identified by the IP address of the neighbor, with 1688: optional specification of used interface and local IP. By default 1689: the neighbor must be directly connected, unless the session is 1690: configured as multihop. Note that local IP must be specified for 1691: multihop sessions. 1692: </descrip> 1693: 1694: Session specific options (part of <cf/interface/ and <cf/multihop/ definitions): 1695: 1696: <descrip> 1697: <tag><label id="bfd-interval">interval <m/time/</tag> 1698: BFD ensures availability of the forwarding path associated with the 1699: session by periodically sending BFD control packets in both 1700: directions. The rate of such packets is controlled by two options, 1701: <cf/min rx interval/ and <cf/min tx interval/ (see below). This option 1702: is just a shorthand to set both of these options together. 1703: 1704: <tag><label id="bfd-min-rx-interval">min rx interval <m/time/</tag> 1705: This option specifies the minimum RX interval, which is announced to the 1706: neighbor and used there to limit the neighbor's rate of generated BFD 1707: control packets. Default: 10 ms. 1708: 1709: <tag><label id="bfd-min-tx-interval">min tx interval <m/time/</tag> 1710: This option specifies the desired TX interval, which controls the rate 1711: of generated BFD control packets (together with <cf/min rx interval/ 1712: announced by the neighbor). Note that this value is used only if the BFD 1713: session is up, otherwise the value of <cf/idle tx interval/ is used 1714: instead. Default: 100 ms. 1715: 1716: <tag><label id="bfd-idle-tx-interval">idle tx interval <m/time/</tag> 1717: In order to limit unnecessary traffic in cases where a neighbor is not 1718: available or not running BFD, the rate of generated BFD control packets 1719: is lower when the BFD session is not up. This option specifies the 1720: desired TX interval in such cases instead of <cf/min tx interval/. 1721: Default: 1 s. 1722: 1723: <tag><label id="bfd-multiplier">multiplier <m/num/</tag> 1724: Failure detection time for BFD sessions is based on established rate of 1725: BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this 1726: multiplier, which is essentially (ignoring jitter) a number of missed 1727: packets after which the session is declared down. Note that rates and 1728: multipliers could be different in each direction of a BFD session. 1729: Default: 5. 1730: 1731: <tag><label id="bfd-passive">passive <m/switch/</tag> 1732: Generally, both BFD session endpoints try to establish the session by 1733: sending control packets to the other side. This option allows to enable 1734: passive mode, which means that the router does not send BFD packets 1735: until it has received one from the other side. Default: disabled. 1736: 1737: <tag>authentication none</tag> 1738: No passwords are sent in BFD packets. This is the default value. 1739: 1740: <tag>authentication simple</tag> 1741: Every packet carries 16 bytes of password. Received packets lacking this 1742: password are ignored. This authentication mechanism is very weak. 1743: 1744: <tag>authentication [meticulous] keyed md5|sha1</tag> 1745: An authentication code is appended to each packet. The cryptographic 1746: algorithm is keyed MD5 or keyed SHA-1. Note that the algorithm is common 1747: for all keys (on one interface), in contrast to OSPF or RIP, where it 1748: is a per-key option. Passwords (keys) are not sent open via network. 1749: 1750: The <cf/meticulous/ variant means that cryptographic sequence numbers 1751: are increased for each sent packet, while in the basic variant they are 1752: increased about once per second. Generally, the <cf/meticulous/ variant 1753: offers better resistance to replay attacks but may require more 1754: computation. 1755: 1756: <tag>password "<M>text</M>"</tag> 1757: Specifies a password used for authentication. See <ref id="dsc-pass" 1758: name="password"> common option for detailed description. Note that 1759: password option <cf/algorithm/ is not available in BFD protocol. The 1760: algorithm is selected by <cf/authentication/ option for all passwords. 1761: 1762: </descrip> 1763: 1764: <sect1>Example 1765: <label id="bfd-exam"> 1766: 1767: <code> 1768: protocol bfd { 1769: interface "eth*" { 1770: min rx interval 20 ms; 1771: min tx interval 50 ms; 1772: idle tx interval 300 ms; 1773: }; 1774: interface "gre*" { 1775: interval 200 ms; 1776: multiplier 10; 1777: passive; 1778: }; 1779: multihop { 1780: interval 200 ms; 1781: multiplier 10; 1782: }; 1783: 1784: neighbor 192.168.1.10; 1785: neighbor 192.168.2.2 dev "eth2"; 1786: neighbor 192.168.10.1 local 192.168.1.1 multihop; 1787: } 1788: </code> 1789: 1790: 1791: <sect>BGP 1792: <label id="bgp"> 1793: 1794: The Border Gateway Protocol is the routing protocol used for backbone level 1795: routing in the today's Internet. Contrary to other protocols, its convergence 1796: does not rely on all routers following the same rules for route selection, 1797: making it possible to implement any routing policy at any router in the network, 1798: the only restriction being that if a router advertises a route, it must accept 1799: and forward packets according to it. 1800: 1801: BGP works in terms of autonomous systems (often abbreviated as AS). Each AS 1802: is a part of the network with common management and common routing policy. It is 1803: identified by a unique 16-bit number (ASN). Routers within each AS usually 1804: exchange AS-internal routing information with each other using an interior 1805: gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of 1806: the AS communicate global (inter-AS) network reachability information with their 1807: neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute 1808: received information to other routers in the AS via interior BGP (iBGP). 1809: 1810: Each BGP router sends to its neighbors updates of the parts of its routing 1811: table it wishes to export along with complete path information (a list of AS'es 1812: the packet will travel through if it uses the particular route) in order to 1813: avoid routing loops. 1814: 1815: BIRD supports all requirements of the BGP4 standard as defined in 1816: <rfc id="4271"> It also supports the community attributes (<rfc id="1997">), 1817: capability negotiation (<rfc id="5492">), MD5 password authentication (<rfc 1818: id="2385">), extended communities (<rfc id="4360">), route reflectors (<rfc 1819: id="4456">), graceful restart (<rfc id="4724">), multiprotocol extensions 1820: (<rfc id="4760">), 4B AS numbers (<rfc id="4893">), and 4B AS numbers in 1821: extended communities (<rfc id="5668">). 1822: 1823: 1824: For IPv6, it uses the standard multiprotocol extensions defined in 1825: <rfc id="4760"> and applied to IPv6 according to <rfc id="2545">. 1826: 1827: <sect1>Route selection rules 1828: <label id="bgp-route-select-rules"> 1829: 1830: BGP doesn't have any simple metric, so the rules for selection of an optimal 1831: route among multiple BGP routes with the same preference are a bit more complex 1832: and they are implemented according to the following algorithm. It starts the 1833: first rule, if there are more "best" routes, then it uses the second rule to 1834: choose among them and so on. 1835: 1836: <itemize> 1837: <item>Prefer route with the highest Local Preference attribute. 1838: <item>Prefer route with the shortest AS path. 1839: <item>Prefer IGP origin over EGP and EGP origin over incomplete. 1840: <item>Prefer the lowest value of the Multiple Exit Discriminator. 1841: <item>Prefer routes received via eBGP over ones received via iBGP. 1842: <item>Prefer routes with lower internal distance to a boundary router. 1843: <item>Prefer the route with the lowest value of router ID of the 1844: advertising router. 1845: </itemize> 1846: 1847: <sect1>IGP routing table 1848: <label id="bgp-igp-routing-table"> 1849: 1850: BGP is mainly concerned with global network reachability and with routes to 1851: other autonomous systems. When such routes are redistributed to routers in the 1852: AS via BGP, they contain IP addresses of a boundary routers (in route attribute 1853: NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to 1854: determine immediate next hops for routes and to know their internal distances to 1855: boundary routers for the purpose of BGP route selection. In BIRD, there is 1856: usually one routing table used for both IGP routes and BGP routes. 1857: 1858: <sect1>Configuration 1859: <label id="bgp-config"> 1860: 1861: Each instance of the BGP corresponds to one neighboring router. This allows 1862: to set routing policy and all the other parameters differently for each neighbor 1863: using the following configuration parameters: 1864: 1865: <descrip> 1866: <tag><label id="bgp-local">local [<m/ip/] as <m/number/</tag> 1867: Define which AS we are part of. (Note that contrary to other IP routers, 1868: BIRD is able to act as a router located in multiple AS'es simultaneously, 1869: but in such cases you need to tweak the BGP paths manually in the filters 1870: to get consistent behavior.) Optional <cf/ip/ argument specifies a source 1871: address, equivalent to the <cf/source address/ option (see below). This 1872: parameter is mandatory. 1873: 1874: <tag><label id="bgp-neighbor">neighbor [<m/ip/] [port <m/number/] [as <m/number/]</tag> 1875: Define neighboring router this instance will be talking to and what AS 1876: it is located in. In case the neighbor is in the same AS as we are, we 1877: automatically switch to iBGP. Optionally, the remote port may also be 1878: specified. The parameter may be used multiple times with different 1879: sub-options (e.g., both <cf/neighbor 10.0.0.1 as 65000;/ and 1880: <cf/neighbor 10.0.0.1; neighbor as 65000;/ are valid). This parameter is 1881: mandatory. 1882: 1883: <tag><label id="bgp-iface">interface <m/string/</tag> 1884: Define interface we should use for link-local BGP IPv6 sessions. 1885: Interface can also be specified as a part of <cf/neighbor address/ 1886: (e.g., <cf/neighbor fe80::1234%eth0 as 65000;/). It is an error to use 1887: this parameter for non link-local sessions. 1888: 1889: <tag><label id="bgp-direct">direct</tag> 1890: Specify that the neighbor is directly connected. The IP address of the 1891: neighbor must be from a directly reachable IP range (i.e. associated 1892: with one of your router's interfaces), otherwise the BGP session 1893: wouldn't start but it would wait for such interface to appear. The 1894: alternative is the <cf/multihop/ option. Default: enabled for eBGP. 1895: 1896: <tag><label id="bgp-multihop">multihop [<m/number/]</tag> 1897: Configure multihop BGP session to a neighbor that isn't directly 1898: connected. Accurately, this option should be used if the configured 1899: neighbor IP address does not match with any local network subnets. Such 1900: IP address have to be reachable through system routing table. The 1901: alternative is the <cf/direct/ option. For multihop BGP it is 1902: recommended to explicitly configure the source address to have it 1903: stable. Optional <cf/number/ argument can be used to specify the number 1904: of hops (used for TTL). Note that the number of networks (edges) in a 1905: path is counted; i.e., if two BGP speakers are separated by one router, 1906: the number of hops is 2. Default: enabled for iBGP. 1907: 1908: <tag><label id="bgp-source-address">source address <m/ip/</tag> 1909: Define local address we should use for next hop calculation and as a 1910: source address for the BGP session. Default: the address of the local 1911: end of the interface our neighbor is connected to. 1912: 1913: <tag><label id="bgp-next-hop-self">next hop self</tag> 1914: Avoid calculation of the Next Hop attribute and always advertise our own 1915: source address as a next hop. This needs to be used only occasionally to 1916: circumvent misconfigurations of other routers. Default: disabled. 1917: 1918: <tag><label id="bgp-next-hop-keep">next hop keep</tag> 1919: Forward the received Next Hop attribute even in situations where the 1920: local address should be used instead, like when the route is sent to an 1921: interface with a different subnet. Default: disabled. 1922: 1923: <tag><label id="bgp-missing-lladdr">missing lladdr self|drop|ignore</tag> 1924: Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6 1925: address, but sometimes it has to contain both global and link-local IPv6 1926: addresses. This option specifies what to do if BIRD have to send both 1927: addresses but does not know link-local address. This situation might 1928: happen when routes from other protocols are exported to BGP, or when 1929: improper updates are received from BGP peers. <cf/self/ means that BIRD 1930: advertises its own local address instead. <cf/drop/ means that BIRD 1931: skips that prefixes and logs error. <cf/ignore/ means that BIRD ignores 1932: the problem and sends just the global address (and therefore forms 1933: improper BGP update). Default: <cf/self/, unless BIRD is configured as a 1934: route server (option <cf/rs client/), in that case default is <cf/ignore/, 1935: because route servers usually do not forward packets themselves. 1936: 1937: <tag><label id="bgp-gateway">gateway direct|recursive</tag> 1938: For received routes, their <cf/gw/ (immediate next hop) attribute is 1939: computed from received <cf/bgp_next_hop/ attribute. This option 1940: specifies how it is computed. Direct mode means that the IP address from 1941: <cf/bgp_next_hop/ is used if it is directly reachable, otherwise the 1942: neighbor IP address is used. Recursive mode means that the gateway is 1943: computed by an IGP routing table lookup for the IP address from 1944: <cf/bgp_next_hop/. Note that there is just one level of indirection in 1945: recursive mode - the route obtained by the lookup must not be recursive 1946: itself, to prevent mutually recursive routes. 1947: 1948: Recursive mode is the behavior specified by the BGP 1949: standard. Direct mode is simpler, does not require any routes in a 1950: routing table, and was used in older versions of BIRD, but does not 1951: handle well nontrivial iBGP setups and multihop. Recursive mode is 1952: incompatible with <ref id="dsc-table-sorted" name="sorted tables">. Default: 1953: <cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions. 1954: 1955: <tag><label id="bgp-igp-table">igp table <m/name/</tag> 1956: Specifies a table that is used as an IGP routing table. Default: the 1957: same as the table BGP is connected to. 1958: 1959: <tag><label id="bgp-check-link">check link <M>switch</M></tag> 1960: BGP could use hardware link state into consideration. If enabled, 1961: BIRD tracks the link state of the associated interface and when link 1962: disappears (e.g. an ethernet cable is unplugged), the BGP session is 1963: immediately shut down. Note that this option cannot be used with 1964: multihop BGP. Default: disabled. 1965: 1966: <tag><label id="bgp-bfd">bfd <M>switch</M></tag> 1967: BGP could use BFD protocol as an advisory mechanism for neighbor 1968: liveness and failure detection. If enabled, BIRD setups a BFD session 1969: for the BGP neighbor and tracks its liveness by it. This has an 1970: advantage of an order of magnitude lower detection times in case of 1971: failure. Note that BFD protocol also has to be configured, see 1972: <ref id="bfd" name="BFD"> section for details. Default: disabled. 1973: 1974: <tag><label id="bgp-ttl-security">ttl security <m/switch/</tag> 1975: Use GTSM (<rfc id="5082"> - the generalized TTL security mechanism). GTSM 1976: protects against spoofed packets by ignoring received packets with a 1977: smaller than expected TTL. To work properly, GTSM have to be enabled on 1978: both sides of a BGP session. If both <cf/ttl security/ and 1979: <cf/multihop/ options are enabled, <cf/multihop/ option should specify 1980: proper hop value to compute expected TTL. Kernel support required: 1981: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only. 1982: Note that full (ICMP protection, for example) <rfc id="5082"> support is 1983: provided by Linux only. Default: disabled. 1984: 1985: <tag><label id="bgp-pass">password <m/string/</tag> 1986: Use this password for MD5 authentication of BGP sessions (<rfc id="2385">). When 1987: used on BSD systems, see also <cf/setkey/ option below. Default: no 1988: authentication. 1989: 1990: <tag><label id="bgp-setkey">setkey <m/switch/</tag> 1991: On BSD systems, keys for TCP MD5 authentication are stored in the global 1992: SA/SP database, which can be accessed by external utilities (e.g. 1993: setkey(8)). BIRD configures security associations in the SA/SP database 1994: automatically based on <cf/password/ options (see above), this option 1995: allows to disable automatic updates by BIRD when manual configuration by 1996: external utilities is preferred. Note that automatic SA/SP database 1997: updates are currently implemented only for FreeBSD. Passwords have to be 1998: set manually by an external utility on NetBSD and OpenBSD. Default: 1999: enabled (ignored on non-FreeBSD). 2000: 2001: <tag><label id="bgp-passive">passive <m/switch/</tag> 2002: Standard BGP behavior is both initiating outgoing connections and 2003: accepting incoming connections. In passive mode, outgoing connections 2004: are not initiated. Default: off. 2005: 2006: <tag><label id="bgp-rr-client">rr client</tag> 2007: Be a route reflector and treat the neighbor as a route reflection 2008: client. Default: disabled. 2009: 2010: <tag><label id="bgp-rr-cluster-id">rr cluster id <m/IPv4 address/</tag> 2011: Route reflectors use cluster id to avoid route reflection loops. When 2012: there is one route reflector in a cluster it usually uses its router id 2013: as a cluster id, but when there are more route reflectors in a cluster, 2014: these need to be configured (using this option) to use a common cluster 2015: id. Clients in a cluster need not know their cluster id and this option 2016: is not allowed for them. Default: the same as router id. 2017: 2018: <tag><label id="bgp-rs-client">rs client</tag> 2019: Be a route server and treat the neighbor as a route server client. 2020: A route server is used as a replacement for full mesh EBGP routing in 2021: Internet exchange points in a similar way to route reflectors used in 2022: IBGP routing. BIRD does not implement obsoleted <rfc id="1863">, but 2023: uses ad-hoc implementation, which behaves like plain EBGP but reduces 2024: modifications to advertised route attributes to be transparent (for 2025: example does not prepend its AS number to AS PATH attribute and 2026: keeps MED attribute). Default: disabled. 2027: 2028: <tag><label id="bgp-secondary">secondary <m/switch/</tag> 2029: Usually, if an export filter rejects a selected route, no other route is 2030: propagated for that network. This option allows to try the next route in 2031: order until one that is accepted is found or all routes for that network 2032: are rejected. This can be used for route servers that need to propagate 2033: different tables to each client but do not want to have these tables 2034: explicitly (to conserve memory). This option requires that the connected 2035: routing table is <ref id="dsc-table-sorted" name="sorted">. Default: off. 2036: 2037: <tag><label id="bgp-add-paths">add paths <m/switch/|rx|tx</tag> 2038: Standard BGP can propagate only one path (route) per destination network 2039: (usually the selected one). This option controls the add-path protocol 2040: extension, which allows to advertise any number of paths to a 2041: destination. Note that to be active, add-path has to be enabled on both 2042: sides of the BGP session, but it could be enabled separately for RX and 2043: TX direction. When active, all available routes accepted by the export 2044: filter are advertised to the neighbor. Default: off. 2045: 2046: <tag><label id="bgp-allow-local-as">allow local as [<m/number/]</tag> 2047: BGP prevents routing loops by rejecting received routes with the local 2048: AS number in the AS path. This option allows to loose or disable the 2049: check. Optional <cf/number/ argument can be used to specify the maximum 2050: number of local ASNs in the AS path that is allowed for received 2051: routes. When the option is used without the argument, the check is 2052: completely disabled and you should ensure loop-free behavior by some 2053: other means. Default: 0 (no local AS number allowed). 2054: 2055: <tag><label id="bgp-enable-route-refresh">enable route refresh <m/switch/</tag> 2056: After the initial route exchange, BGP protocol uses incremental updates 2057: to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker 2058: changes its import filter, or if there is suspicion of inconsistency) it 2059: is necessary to do a new complete route exchange. BGP protocol extension 2060: Route Refresh (<rfc id="2918">) allows BGP speaker to request 2061: re-advertisement of all routes from its neighbor. BGP protocol 2062: extension Enhanced Route Refresh (<rfc id="7313">) specifies explicit 2063: begin and end for such exchanges, therefore the receiver can remove 2064: stale routes that were not advertised during the exchange. This option 2065: specifies whether BIRD advertises these capabilities and supports 2066: related procedures. Note that even when disabled, BIRD can send route 2067: refresh requests. Default: on. 2068: 2069: <tag><label id="bgp-graceful-restart">graceful restart <m/switch/|aware</tag> 2070: When a BGP speaker restarts or crashes, neighbors will discard all 2071: received paths from the speaker, which disrupts packet forwarding even 2072: when the forwarding plane of the speaker remains intact. <rfc 2073: id="4724"> specifies an optional graceful restart mechanism to 2074: alleviate this issue. This option controls the mechanism. It has three 2075: states: Disabled, when no support is provided. Aware, when the graceful 2076: restart support is announced and the support for restarting neighbors 2077: is provided, but no local graceful restart is allowed (i.e. 2078: receiving-only role). Enabled, when the full graceful restart 2079: support is provided (i.e. both restarting and receiving role). Note 2080: that proper support for local graceful restart requires also 2081: configuration of other protocols. Default: aware. 2082: 2083: <tag><label id="bgp-graceful-restart-time">graceful restart time <m/number/</tag> 2084: The restart time is announced in the BGP graceful restart capability 2085: and specifies how long the neighbor would wait for the BGP session to 2086: re-establish after a restart before deleting stale routes. Default: 2087: 120 seconds. 2088: 2089: <tag><label id="bgp-interpret-communities">interpret communities <m/switch/</tag> 2090: <rfc id="1997"> demands that BGP speaker should process well-known 2091: communities like no-export (65535, 65281) or no-advertise (65535, 2092: 65282). For example, received route carrying a no-adverise community 2093: should not be advertised to any of its neighbors. If this option is 2094: enabled (which is by default), BIRD has such behavior automatically (it 2095: is evaluated when a route is exported to the BGP protocol just before 2096: the export filter). Otherwise, this integrated processing of 2097: well-known communities is disabled. In that case, similar behavior can 2098: be implemented in the export filter. Default: on. 2099: 2100: <tag><label id="bgp-enable-as4">enable as4 <m/switch/</tag> 2101: BGP protocol was designed to use 2B AS numbers and was extended later to 2102: allow 4B AS number. BIRD supports 4B AS extension, but by disabling this 2103: option it can be persuaded not to advertise it and to maintain old-style 2104: sessions with its neighbors. This might be useful for circumventing bugs 2105: in neighbor's implementation of 4B AS extension. Even when disabled 2106: (off), BIRD behaves internally as AS4-aware BGP router. Default: on. 2107: 2108: <tag><label id="bgp-enable-extended-messages">enable extended messages <m/switch/</tag> 2109: The BGP protocol uses maximum message length of 4096 bytes. This option 2110: provides an extension to allow extended messages with length up 2111: to 65535 bytes. Default: off. 2112: 2113: <tag><label id="bgp-capabilities">capabilities <m/switch/</tag> 2114: Use capability advertisement to advertise optional capabilities. This is 2115: standard behavior for newer BGP implementations, but there might be some 2116: older BGP implementations that reject such connection attempts. When 2117: disabled (off), features that request it (4B AS support) are also 2118: disabled. Default: on, with automatic fallback to off when received 2119: capability-related error. 2120: 2121: <tag><label id="bgp-advertise-ipv4">advertise ipv4 <m/switch/</tag> 2122: Advertise IPv4 multiprotocol capability. This is not a correct behavior 2123: according to the strict interpretation of <rfc id="4760">, but it is 2124: widespread and required by some BGP implementations (Cisco and Quagga). 2125: This option is relevant to IPv4 mode with enabled capability 2126: advertisement only. Default: on. 2127: 2128: <tag><label id="bgp-route-limit">route limit <m/number/</tag> 2129: The maximal number of routes that may be imported from the protocol. If 2130: the route limit is exceeded, the connection is closed with an error. 2131: Limit is currently implemented as <cf>import limit <m/number/ action 2132: restart</cf>. This option is obsolete and it is replaced by 2133: <ref id="proto-import-limit" name="import limit option">. Default: no limit. 2134: 2135: <tag><label id="bgp-disable-after-error">disable after error <m/switch/</tag> 2136: When an error is encountered (either locally or by the other side), 2137: disable the instance automatically and wait for an administrator to fix 2138: the problem manually. Default: off. 2139: 2140: <tag><label id="bgp-hold-time">hold time <m/number/</tag> 2141: Time in seconds to wait for a Keepalive message from the other side 2142: before considering the connection stale. Default: depends on agreement 2143: with the neighboring router, we prefer 240 seconds if the other side is 2144: willing to accept it. 2145: 2146: <tag><label id="bgp-startup-hold-time">startup hold time <m/number/</tag> 2147: Value of the hold timer used before the routers have a chance to exchange 2148: open messages and agree on the real value. Default: 240 seconds. 2149: 2150: <tag><label id="bgp-keepalive-time">keepalive time <m/number/</tag> 2151: Delay in seconds between sending of two consecutive Keepalive messages. 2152: Default: One third of the hold time. 2153: 2154: <tag><label id="bgp-connect-delay-time">connect delay time <m/number/</tag> 2155: Delay in seconds between protocol startup and the first attempt to 2156: connect. Default: 5 seconds. 2157: 2158: <tag><label id="bgp-connect-retry-time">connect retry time <m/number/</tag> 2159: Time in seconds to wait before retrying a failed attempt to connect. 2160: Default: 120 seconds. 2161: 2162: <tag><label id="bgp-error-wait-time">error wait time <m/number/,<m/number/</tag> 2163: Minimum and maximum delay in seconds between a protocol failure (either 2164: local or reported by the peer) and automatic restart. Doesn't apply 2165: when <cf/disable after error/ is configured. If consecutive errors 2166: happen, the delay is increased exponentially until it reaches the 2167: maximum. Default: 60, 300. 2168: 2169: <tag><label id="bgp-error-forget-time">error forget time <m/number/</tag> 2170: Maximum time in seconds between two protocol failures to treat them as a 2171: error sequence which makes <cf/error wait time/ increase exponentially. 2172: Default: 300 seconds. 2173: 2174: <tag><label id="bgp-path-metric">path metric <m/switch/</tag> 2175: Enable comparison of path lengths when deciding which BGP route is the 2176: best one. Default: on. 2177: 2178: <tag><label id="bgp-med-metric">med metric <m/switch/</tag> 2179: Enable comparison of MED attributes (during best route selection) even 2180: between routes received from different ASes. This may be useful if all 2181: MED attributes contain some consistent metric, perhaps enforced in 2182: import filters of AS boundary routers. If this option is disabled, MED 2183: attributes are compared only if routes are received from the same AS 2184: (which is the standard behavior). Default: off. 2185: 2186: <tag><label id="bgp-deterministic-med">deterministic med <m/switch/</tag> 2187: BGP route selection algorithm is often viewed as a comparison between 2188: individual routes (e.g. if a new route appears and is better than the 2189: current best one, it is chosen as the new best one). But the proper 2190: route selection, as specified by <rfc id="4271">, cannot be fully 2191: implemented in that way. The problem is mainly in handling the MED 2192: attribute. BIRD, by default, uses an simplification based on individual 2193: route comparison, which in some cases may lead to temporally dependent 2194: behavior (i.e. the selection is dependent on the order in which routes 2195: appeared). This option enables a different (and slower) algorithm 2196: implementing proper <rfc id="4271"> route selection, which is 2197: deterministic. Alternative way how to get deterministic behavior is to 2198: use <cf/med metric/ option. This option is incompatible with <ref 2199: id="dsc-table-sorted" name="sorted tables">. Default: off. 2200: 2201: <tag><label id="bgp-igp-metric">igp metric <m/switch/</tag> 2202: Enable comparison of internal distances to boundary routers during best 2203: route selection. Default: on. 2204: 2205: <tag><label id="bgp-prefer-older">prefer older <m/switch/</tag> 2206: Standard route selection algorithm breaks ties by comparing router IDs. 2207: This changes the behavior to prefer older routes (when both are external 2208: and from different peer). For details, see <rfc id="5004">. Default: off. 2209: 2210: <tag><label id="bgp-default-med">default bgp_med <m/number/</tag> 2211: Value of the Multiple Exit Discriminator to be used during route 2212: selection when the MED attribute is missing. Default: 0. 2213: 2214: <tag><label id="bgp-default-local-pref">default bgp_local_pref <m/number/</tag> 2215: A default value for the Local Preference attribute. It is used when 2216: a new Local Preference attribute is attached to a route by the BGP 2217: protocol itself (for example, if a route is received through eBGP and 2218: therefore does not have such attribute). Default: 100 (0 in pre-1.2.0 2219: versions of BIRD). 2220: </descrip> 2221: 2222: <sect1>Attributes 2223: <label id="bgp-attr"> 2224: 2225: BGP defines several route attributes. Some of them (those marked with 2226: `<tt/I/' in the table below) are available on internal BGP connections only, 2227: some of them (marked with `<tt/O/') are optional. 2228: 2229: <descrip> 2230: <tag><label id="rta-bgp-path">bgppath bgp_path/</tag> 2231: Sequence of AS numbers describing the AS path the packet will travel 2232: through when forwarded according to the particular route. In case of 2233: internal BGP it doesn't contain the number of the local AS. 2234: 2235: <tag><label id="rta-bgp-local-pref">int bgp_local_pref/ [I]</tag> 2236: Local preference value used for selection among multiple BGP routes (see 2237: the selection rules above). It's used as an additional metric which is 2238: propagated through the whole local AS. 2239: 2240: <tag><label id="rta-bgp-med">int bgp_med/ [O]</tag> 2241: The Multiple Exit Discriminator of the route is an optional attribute 2242: which is used on external (inter-AS) links to convey to an adjacent AS 2243: the optimal entry point into the local AS. The received attribute is 2244: also propagated over internal BGP links. The attribute value is zeroed 2245: when a route is exported to an external BGP instance to ensure that the 2246: attribute received from a neighboring AS is not propagated to other 2247: neighboring ASes. A new value might be set in the export filter of an 2248: external BGP instance. See <rfc id="4451"> for further discussion of 2249: BGP MED attribute. 2250: 2251: <tag><label id="rta-bgp-origin">enum bgp_origin/</tag> 2252: Origin of the route: either <cf/ORIGIN_IGP/ if the route has originated 2253: in an interior routing protocol or <cf/ORIGIN_EGP/ if it's been imported 2254: from the <tt>EGP</tt> protocol (nowadays it seems to be obsolete) or 2255: <cf/ORIGIN_INCOMPLETE/ if the origin is unknown. 2256: 2257: <tag><label id="rta-bgp-next-hop">ip bgp_next_hop/</tag> 2258: Next hop to be used for forwarding of packets to this destination. On 2259: internal BGP connections, it's an address of the originating router if 2260: it's inside the local AS or a boundary router the packet will leave the 2261: AS through if it's an exterior route, so each BGP speaker within the AS 2262: has a chance to use the shortest interior path possible to this point. 2263: 2264: <tag><label id="rta-bgp-atomic-aggr">void bgp_atomic_aggr/ [O]</tag> 2265: This is an optional attribute which carries no value, but the sole 2266: presence of which indicates that the route has been aggregated from 2267: multiple routes by some router on the path from the originator. 2268: 2269:  2272: <tag><label id="rta-bgp-community">clist bgp_community/ [O]</tag> 2273: List of community values associated with the route. Each such value is a 2274: pair (represented as a <cf/pair/ data type inside the filters) of 16-bit 2275: integers, the first of them containing the number of the AS which 2276: defines the community and the second one being a per-AS identifier. 2277: There are lots of uses of the community mechanism, but generally they 2278: are used to carry policy information like "don't export to USA peers". 2279: As each AS can define its own routing policy, it also has a complete 2280: freedom about which community attributes it defines and what will their 2281: semantics be. 2282: 2283: <tag><label id="rta-bgp-ext-community">eclist bgp_ext_community/ [O]</tag> 2284: List of extended community values associated with the route. Extended 2285: communities have similar usage as plain communities, but they have an 2286: extended range (to allow 4B ASNs) and a nontrivial structure with a type 2287: field. Individual community values are represented using an <cf/ec/ data 2288: type inside the filters. 2289: 2290: <tag><label id="rta-bgp-large-community">lclist <cf/bgp_large_community/ [O]</tag> 2291: List of large community values associated with the route. Large BGP 2292: communities is another variant of communities, but contrary to extended 2293: communities they behave very much the same way as regular communities, 2294: just larger -- they are uniform untyped triplets of 32bit numbers. 2295: Individual community values are represented using an <cf/lc/ data type 2296: inside the filters. 2297: 2298: <tag><label id="rta-bgp-originator-id">quad bgp_originator_id/ [I, O]</tag> 2299: This attribute is created by the route reflector when reflecting the 2300: route and contains the router ID of the originator of the route in the 2301: local AS. 2302: 2303: <tag><label id="rta-bgp-cluster-list">clist bgp_cluster_list/ [I, O]</tag> 2304: This attribute contains a list of cluster IDs of route reflectors. Each 2305: route reflector prepends its cluster ID when reflecting the route. 2306: </descrip> 2307: 2308: <sect1>Example 2309: <label id="bgp-exam"> 2310: 2311: <code> 2312: protocol bgp { 2313: local as 65000; # Use a private AS number 2314: neighbor 198.51.100.130 as 64496; # Our neighbor ... 2315: multihop; # ... which is connected indirectly 2316: export filter { # We use non-trivial export rules 2317: if source = RTS_STATIC then { # Export only static routes 2318: # Assign our community 2319: bgp_community.add((65000,64501)); 2320: # Artificially increase path length 2321: # by advertising local AS number twice 2322: if bgp_path ~ [= 65000 =] then 2323: bgp_path.prepend(65000); 2324: accept; 2325: } 2326: reject; 2327: }; 2328: import all; 2329: source address 198.51.100.14; # Use a non-standard source address 2330: } 2331: </code> 2332: 2333: 2334: <sect>Device 2335: <label id="device"> 2336: 2337: The Device protocol is not a real routing protocol. It doesn't generate any 2338: routes and it only serves as a module for getting information about network 2339: interfaces from the kernel. 2340: 2341: Except for very unusual circumstances, you probably should include this 2342: protocol in the configuration since almost all other protocols require network 2343: interfaces to be defined for them to work with. 2344: 2345: <sect1>Configuration 2346: <label id="device-config"> 2347: 2348: <descrip> 2349: 2350: <tag><label id="device-scan-time">scan time <m/number/</tag> 2351: Time in seconds between two scans of the network interface list. On 2352: systems where we are notified about interface status changes 2353: asynchronously (such as newer versions of Linux), we need to scan the 2354: list only in order to avoid confusion by lost notification messages, 2355: so the default time is set to a large value. 2356: 2357: <tag><label id="device-primary">primary [ "<m/mask/" ] <m/prefix/</tag> 2358: If a network interface has more than one network address, BIRD has to 2359: choose one of them as a primary one. By default, BIRD chooses the 2360: lexicographically smallest address as the primary one. 2361: 2362: This option allows to specify which network address should be chosen as 2363: a primary one. Network addresses that match <m/prefix/ are preferred to 2364: non-matching addresses. If more <cf/primary/ options are used, the first 2365: one has the highest preference. If "<m/mask/" is specified, then such 2366: <cf/primary/ option is relevant only to matching network interfaces. 2367: 2368: In all cases, an address marked by operating system as secondary cannot 2369: be chosen as the primary one. 2370: </descrip> 2371: 2372: As the Device protocol doesn't generate any routes, it cannot have 2373: any attributes. Example configuration looks like this: 2374: 2375: <code> 2376: protocol device { 2377: scan time 10; # Scan the interfaces often 2378: primary "eth0" 192.168.1.1; 2379: primary 192.168.0.0/16; 2380: } 2381: </code> 2382: 2383: 2384: <sect>Direct 2385: <label id="direct"> 2386: 2387: The Direct protocol is a simple generator of device routes for all the 2388: directly connected networks according to the list of interfaces provided by the 2389: kernel via the Device protocol. 2390: 2391: The question is whether it is a good idea to have such device routes in BIRD 2392: routing table. OS kernel usually handles device routes for directly connected 2393: networks by itself so we don't need (and don't want) to export these routes to 2394: the kernel protocol. OSPF protocol creates device routes for its interfaces 2395: itself and BGP protocol is usually used for exporting aggregate routes. Although 2396: there are some use cases that use the direct protocol (like abusing eBGP as an 2397: IGP routing protocol), in most cases it is not needed to have these device 2398: routes in BIRD routing table and to use the direct protocol. 2399: 2400: There is one notable case when you definitely want to use the direct protocol 2401: -- running BIRD on BSD systems. Having high priority device routes for directly 2402: connected networks from the direct protocol protects kernel device routes from 2403: being overwritten or removed by IGP routes during some transient network 2404: conditions, because a lower priority IGP route for the same network is not 2405: exported to the kernel routing table. This is an issue on BSD systems only, as 2406: on Linux systems BIRD cannot change non-BIRD route in the kernel routing table. 2407: 2408: There are just few configuration options for the Direct protocol: 2409: 2410: <descrip> 2411: <tag><label id="direct-iface">interface <m/pattern/ [, <m/.../]</tag> 2412: By default, the Direct protocol will generate device routes for all the 2413: interfaces available. If you want to restrict it to some subset of 2414: interfaces or addresses (e.g. if you're using multiple routing tables 2415: for policy routing and some of the policy domains don't contain all 2416: interfaces), just use this clause. See <ref id="proto-iface" name="interface"> 2417: common option for detailed description. The Direct protocol uses 2418: extended interface clauses. 2419: 2420: <tag><label id="direct-check-link">check link <m/switch/</tag> 2421: If enabled, a hardware link state (reported by OS) is taken into 2422: consideration. Routes for directly connected networks are generated only 2423: if link up is reported and they are withdrawn when link disappears 2424: (e.g., an ethernet cable is unplugged). Default value is no. 2425: </descrip> 2426: 2427: Direct device routes don't contain any specific attributes. 2428: 2429: Example config might look like this: 2430: 2431: <code> 2432: protocol direct { 2433: interface "-arc*", "*"; # Exclude the ARCnets 2434: } 2435: </code> 2436: 2437: 2438: <sect>Kernel 2439: <label id="krt"> 2440: 2441: The Kernel protocol is not a real routing protocol. Instead of communicating 2442: with other routers in the network, it performs synchronization of BIRD's routing 2443: tables with the OS kernel. Basically, it sends all routing table updates to the 2444: kernel and from time to time it scans the kernel tables to see whether some 2445: routes have disappeared (for example due to unnoticed up/down transition of an 2446: interface) or whether an `alien' route has been added by someone else (depending 2447: on the <cf/learn/ switch, such routes are either ignored or accepted to our 2448: table). 2449: 2450: Unfortunately, there is one thing that makes the routing table synchronization 2451: a bit more complicated. In the kernel routing table there are also device routes 2452: for directly connected networks. These routes are usually managed by OS itself 2453: (as a part of IP address configuration) and we don't want to touch that. They 2454: are completely ignored during the scan of the kernel tables and also the export 2455: of device routes from BIRD tables to kernel routing tables is restricted to 2456: prevent accidental interference. This restriction can be disabled using 2457: <cf/device routes/ switch. 2458: 2459: If your OS supports only a single routing table, you can configure only one 2460: instance of the Kernel protocol. If it supports multiple tables (in order to 2461: allow policy routing; such an OS is for example Linux), you can run as many 2462: instances as you want, but each of them must be connected to a different BIRD 2463: routing table and to a different kernel table. 2464: 2465: Because the kernel protocol is partially integrated with the connected 2466: routing table, there are two limitations - it is not possible to connect more 2467: kernel protocols to the same routing table and changing route destination 2468: (gateway) in an export filter of a kernel protocol does not work. Both 2469: limitations can be overcome using another routing table and the pipe protocol. 2470: 2471: <sect1>Configuration 2472: <label id="krt-config"> 2473: 2474: <descrip> 2475: <tag><label id="krt-persist">persist <m/switch/</tag> 2476: Tell BIRD to leave all its routes in the routing tables when it exits 2477: (instead of cleaning them up). 2478: 2479: <tag><label id="krt-scan-time">scan time <m/number/</tag> 2480: Time in seconds between two consecutive scans of the kernel routing 2481: table. 2482: 2483: <tag><label id="krt-learn">learn <m/switch/</tag> 2484: Enable learning of routes added to the kernel routing tables by other 2485: routing daemons or by the system administrator. This is possible only on 2486: systems which support identification of route authorship. 2487: 2488: <tag><label id="krt-device-routes">device routes <m/switch/</tag> 2489: Enable export of device routes to the kernel routing table. By default, 2490: such routes are rejected (with the exception of explicitly configured 2491: device routes from the static protocol) regardless of the export filter 2492: to protect device routes in kernel routing table (managed by OS itself) 2493: from accidental overwriting or erasing. 2494: 2495: <tag><label id="krt-kernel-table">kernel table <m/number/</tag> 2496: Select which kernel table should this particular instance of the Kernel 2497: protocol work with. Available only on systems supporting multiple 2498: routing tables. 2499: 2500: <tag><label id="krt-metric">metric <m/number/</tag> (Linux) 2501: Use specified value as a kernel metric (priority) for all routes sent to 2502: the kernel. When multiple routes for the same network are in the kernel 2503: routing table, the Linux kernel chooses one with lower metric. Also, 2504: routes with different metrics do not clash with each other, therefore 2505: using dedicated metric value is a reliable way to avoid overwriting 2506: routes from other sources (e.g. kernel device routes). Metric 0 has a 2507: special meaning of undefined metric, in which either OS default is used, 2508: or per-route metric can be set using <cf/krt_metric/ attribute. Default: 2509: 0 (undefined). 2510: 2511: <tag><label id="krt-graceful-restart">graceful restart <m/switch/</tag> 2512: Participate in graceful restart recovery. If this option is enabled and 2513: a graceful restart recovery is active, the Kernel protocol will defer 2514: synchronization of routing tables until the end of the recovery. Note 2515: that import of kernel routes to BIRD is not affected. 2516: 2517: <tag><label id="krt-merge-paths">merge paths <M>switch</M> [limit <M>number</M>]</tag> 2518: Usually, only best routes are exported to the kernel protocol. With path 2519: merging enabled, both best routes and equivalent non-best routes are 2520: merged during export to generate one ECMP (equal-cost multipath) route 2521: for each network. This is useful e.g. for BGP multipath. Note that best 2522: routes are still pivotal for route export (responsible for most 2523: properties of resulting ECMP routes), while exported non-best routes are 2524: responsible just for additional multipath next hops. This option also 2525: allows to specify a limit on maximal number of nexthops in one route. By 2526: default, multipath merging is disabled. If enabled, default value of the 2527: limit is 16. 2528: </descrip> 2529: 2530: <sect1>Attributes 2531: <label id="krt-attr"> 2532: 2533: The Kernel protocol defines several attributes. These attributes are 2534: translated to appropriate system (and OS-specific) route attributes. We support 2535: these attributes: 2536: 2537: <descrip> 2538: <tag><label id="rta-krt-source">int krt_source/</tag> 2539: The original source of the imported kernel route. The value is 2540: system-dependent. On Linux, it is a value of the protocol field of the 2541: route. See /etc/iproute2/rt_protos for common values. On BSD, it is 2542: based on STATIC and PROTOx flags. The attribute is read-only. 2543: 2544: <tag><label id="rta-krt-metric">int krt_metric/</tag> (Linux) 2545: The kernel metric of the route. When multiple same routes are in a 2546: kernel routing table, the Linux kernel chooses one with lower metric. 2547: Note that preferred way to set kernel metric is to use protocol option 2548: <cf/metric/, unless per-route metric values are needed. 2549: 2550: <tag><label id="rta-krt-prefsrc">ip krt_prefsrc/</tag> (Linux) 2551: The preferred source address. Used in source address selection for 2552: outgoing packets. Has to be one of the IP addresses of the router. 2553: 2554: <tag><label id="rta-krt-realm">int krt_realm/</tag> (Linux) 2555: The realm of the route. Can be used for traffic classification. 2556: 2557: <tag><label id="rta-krt-scope">int krt_scope/</tag> (Linux IPv4) 2558: The scope of the route. Valid values are 0-254, although Linux kernel 2559: may reject some values depending on route type and nexthop. It is 2560: supposed to represent `indirectness' of the route, where nexthops of 2561: routes are resolved through routes with a higher scope, but in current 2562: kernels anything below <it/link/ (253) is treated as <it/global/ (0). 2563: When not present, global scope is implied for all routes except device 2564: routes, where link scope is used by default. 2565: </descrip> 2566: 2567: In Linux, there is also a plenty of obscure route attributes mostly focused 2568: on tuning TCP performance of local connections. BIRD supports most of these 2569: attributes, see Linux or iproute2 documentation for their meaning. Attributes 2570: <cf/krt_lock_*/ and <cf/krt_feature_*/ have type bool, others have type int. 2571: Supported attributes are: 2572: 2573: <cf/krt_mtu/, <cf/krt_lock_mtu/, <cf/krt_window/, <cf/krt_lock_window/, 2574: <cf/krt_rtt/, <cf/krt_lock_rtt/, <cf/krt_rttvar/, <cf/krt_lock_rttvar/, 2575: <cf/krt_sstresh/, <cf/krt_lock_sstresh/, <cf/krt_cwnd/, <cf/krt_lock_cwnd/, 2576: <cf/krt_advmss/, <cf/krt_lock_advmss/, <cf/krt_reordering/, <cf/krt_lock_reordering/, 2577: <cf/krt_hoplimit/, <cf/krt_lock_hoplimit/, <cf/krt_rto_min/, <cf/krt_lock_rto_min/, 2578: <cf/krt_initcwnd/, <cf/krt_initrwnd/, <cf/krt_quickack/, 2579: <cf/krt_feature_ecn/, <cf/krt_feature_allfrag/ 2580: 2581: <sect1>Example 2582: <label id="krt-exam"> 2583: 2584: A simple configuration can look this way: 2585: 2586: <code> 2587: protocol kernel { 2588: export all; 2589: } 2590: </code> 2591: 2592: Or for a system with two routing tables: 2593: 2594: <code> 2595: protocol kernel { # Primary routing table 2596: learn; # Learn alien routes from the kernel 2597: persist; # Don't remove routes on bird shutdown 2598: scan time 10; # Scan kernel routing table every 10 seconds 2599: import all; 2600: export all; 2601: } 2602: 2603: protocol kernel { # Secondary routing table 2604: table auxtable; 2605: kernel table 100; 2606: export all; 2607: } 2608: </code> 2609: 2610: 2611: <sect>OSPF 2612: <label id="ospf"> 2613: 2614: <sect1>Introduction 2615: <label id="ospf-intro"> 2616: 2617: Open Shortest Path First (OSPF) is a quite complex interior gateway 2618: protocol. The current IPv4 version (OSPFv2) is defined in <rfc id="2328"> and 2619: the current IPv6 version (OSPFv3) is defined in <rfc id="5340"> It's a link 2620: state (a.k.a. shortest path first) protocol -- each router maintains a database 2621: describing the autonomous system's topology. Each participating router has an 2622: identical copy of the database and all routers run the same algorithm 2623: calculating a shortest path tree with themselves as a root. OSPF chooses the 2624: least cost path as the best path. 2625: 2626: In OSPF, the autonomous system can be split to several areas in order to 2627: reduce the amount of resources consumed for exchanging the routing information 2628: and to protect the other areas from incorrect routing data. Topology of the area 2629: is hidden to the rest of the autonomous system. 2630: 2631: Another very important feature of OSPF is that it can keep routing information 2632: from other protocols (like Static or BGP) in its link state database as external 2633: routes. Each external route can be tagged by the advertising router, making it 2634: possible to pass additional information between routers on the boundary of the 2635: autonomous system. 2636: 2637: OSPF quickly detects topological changes in the autonomous system (such as 2638: router interface failures) and calculates new loop-free routes after a short 2639: period of convergence. Only a minimal amount of routing traffic is involved. 2640: 2641: Each router participating in OSPF routing periodically sends Hello messages 2642: to all its interfaces. This allows neighbors to be discovered dynamically. Then 2643: the neighbors exchange theirs parts of the link state database and keep it 2644: identical by flooding updates. The flooding process is reliable and ensures that 2645: each router detects all changes. 2646: 2647: <sect1>Configuration 2648: <label id="ospf-config"> 2649: 2650: In the main part of configuration, there can be multiple definitions of OSPF 2651: areas, each with a different id. These definitions includes many other switches 2652: and multiple definitions of interfaces. Definition of interface may contain many 2653: switches and constant definitions and list of neighbors on nonbroadcast 2654: networks. 2655: 2656: <code> 2657: protocol ospf <name> { 2658: rfc1583compat <switch>; 2659: instance id <num>; 2660: stub router <switch>; 2661: tick <num>; 2662: ecmp <switch> [limit <num>]; 2663: merge external <switch>; 2664: area <id> { 2665: stub; 2666: nssa; 2667: summary <switch>; 2668: default nssa <switch>; 2669: default cost <num>; 2670: default cost2 <num>; 2671: translator <switch>; 2672: translator stability <num>; 2673: 2674: networks { 2675: <prefix>; 2676: <prefix> hidden; 2677: } 2678: external { 2679: <prefix>; 2680: <prefix> hidden; 2681: <prefix> tag <num>; 2682: } 2683: stubnet <prefix>; 2684: stubnet <prefix> { 2685: hidden <switch>; 2686: summary <switch>; 2687: cost <num>; 2688: } 2689: interface <interface pattern> [instance <num>] { 2690: cost <num>; 2691: stub <switch>; 2692: hello <num>; 2693: poll <num>; 2694: retransmit <num>; 2695: priority <num>; 2696: wait <num>; 2697: dead count <num>; 2698: dead <num>; 2699: secondary <switch>; 2700: rx buffer [normal|large|<num>]; 2701: tx length <num>; 2702: type [broadcast|bcast|pointopoint|ptp| 2703: nonbroadcast|nbma|pointomultipoint|ptmp]; 2704: link lsa suppression <switch>; 2705: strict nonbroadcast <switch>; 2706: real broadcast <switch>; 2707: ptp netmask <switch>; 2708: check link <switch>; 2709: bfd <switch>; 2710: ecmp weight <num>; 2711: ttl security [<switch>; | tx only] 2712: tx class|dscp <num>; 2713: tx priority <num>; 2714: authentication none|simple|cryptographic; 2715: password "<text>"; 2716: password "<text>" { 2717: id <num>; 2718: generate from "<date>"; 2719: generate to "<date>"; 2720: accept from "<date>"; 2721: accept to "<date>"; 2722: from "<date>"; 2723: to "<date>"; 2724: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 ); 2725: }; 2726: neighbors { 2727: <ip>; 2728: <ip> eligible; 2729: }; 2730: }; 2731: virtual link <id> [instance <num>] { 2732: hello <num>; 2733: retransmit <num>; 2734: wait <num>; 2735: dead count <num>; 2736: dead <num>; 2737: authentication none|simple|cryptographic; 2738: password "<text>"; 2739: password "<text>" { 2740: id <num>; 2741: generate from "<date>"; 2742: generate to "<date>"; 2743: accept from "<date>"; 2744: accept to "<date>"; 2745: from "<date>"; 2746: to "<date>"; 2747: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 ); 2748: }; 2749: }; 2750: }; 2751: } 2752: </code> 2753: 2754: <descrip> 2755: <tag><label id="ospf-rfc1583compat">rfc1583compat <M>switch</M></tag> 2756: This option controls compatibility of routing table calculation with 2757: <rfc id="1583">. Default value is no. 2758: 2759: <tag><label id="ospf-instance-id">instance id <m/num/</tag> 2760: When multiple OSPF protocol instances are active on the same links, they 2761: should use different instance IDs to distinguish their packets. Although 2762: it could be done on per-interface basis, it is often preferred to set 2763: one instance ID to whole OSPF domain/topology (e.g., when multiple 2764: instances are used to represent separate logical topologies on the same 2765: physical network). This option specifies the default instance ID for all 2766: interfaces of the OSPF instance. Note that this option, if used, must 2767: precede interface definitions. Default value is 0. 2768: 2769: <tag><label id="ospf-stub-router">stub router <M>switch</M></tag> 2770: This option configures the router to be a stub router, i.e., a router 2771: that participates in the OSPF topology but does not allow transit 2772: traffic. In OSPFv2, this is implemented by advertising maximum metric 2773: for outgoing links. In OSPFv3, the stub router behavior is announced by 2774: clearing the R-bit in the router LSA. See <rfc id="6987"> for details. 2775: Default value is no. 2776: 2777: <tag><label id="ospf-tick">tick <M>num</M></tag> 2778: The routing table calculation and clean-up of areas' databases is not 2779: performed when a single link state change arrives. To lower the CPU 2780: utilization, it's processed later at periodical intervals of <m/num/ 2781: seconds. The default value is 1. 2782: 2783: <tag><label id="ospf-ecmp">ecmp <M>switch</M> [limit <M>number</M>]</tag> 2784: This option specifies whether OSPF is allowed to generate ECMP 2785: (equal-cost multipath) routes. Such routes are used when there are 2786: several directions to the destination, each with the same (computed) 2787: cost. This option also allows to specify a limit on maximum number of 2788: nexthops in one route. By default, ECMP is disabled. If enabled, 2789: default value of the limit is 16. 2790: 2791: <tag><label id="ospf-merge-external">merge external <M>switch</M></tag> 2792: This option specifies whether OSPF should merge external routes from 2793: different routers/LSAs for the same destination. When enabled together 2794: with <cf/ecmp/, equal-cost external routes will be combined to multipath 2795: routes in the same way as regular routes. When disabled, external routes 2796: from different LSAs are treated as separate even if they represents the 2797: same destination. Default value is no. 2798: 2799: <tag><label id="ospf-area">area <M>id</M></tag> 2800: This defines an OSPF area with given area ID (an integer or an IPv4 2801: address, similarly to a router ID). The most important area is the 2802: backbone (ID 0) to which every other area must be connected. 2803: 2804: <tag><label id="ospf-stub">stub</tag> 2805: This option configures the area to be a stub area. External routes are 2806: not flooded into stub areas. Also summary LSAs can be limited in stub 2807: areas (see option <cf/summary/). By default, the area is not a stub 2808: area. 2809: 2810: <tag><label id="ospf-nssa">nssa</tag> 2811: This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA 2812: is a variant of a stub area which allows a limited way of external route 2813: propagation. Global external routes are not propagated into a NSSA, but 2814: an external route can be imported into NSSA as a (area-wide) NSSA-LSA 2815: (and possibly translated and/or aggregated on area boundary). By 2816: default, the area is not NSSA. 2817: 2818: <tag><label id="ospf-summary">summary <M>switch</M></tag> 2819: This option controls propagation of summary LSAs into stub or NSSA 2820: areas. If enabled, summary LSAs are propagated as usual, otherwise just 2821: the default summary route (0.0.0.0/0) is propagated (this is sometimes 2822: called totally stubby area). If a stub area has more area boundary 2823: routers, propagating summary LSAs could lead to more efficient routing 2824: at the cost of larger link state database. Default value is no. 2825: 2826: <tag><label id="ospf-default-nssa">default nssa <M>switch</M></tag> 2827: When <cf/summary/ option is enabled, default summary route is no longer 2828: propagated to the NSSA. In that case, this option allows to originate 2829: default route as NSSA-LSA to the NSSA. Default value is no. 2830: 2831: <tag><label id="ospf-default-cost">default cost <M>num</M></tag> 2832: This option controls the cost of a default route propagated to stub and 2833: NSSA areas. Default value is 1000. 2834: 2835: <tag><label id="ospf-default-cost2">default cost2 <M>num</M></tag> 2836: When a default route is originated as NSSA-LSA, its cost can use either 2837: type 1 or type 2 metric. This option allows to specify the cost of a 2838: default route in type 2 metric. By default, type 1 metric (option 2839: <cf/default cost/) is used. 2840: 2841: <tag><label id="ospf-translator">translator <M>switch</M></tag> 2842: This option controls translation of NSSA-LSAs into external LSAs. By 2843: default, one translator per NSSA is automatically elected from area 2844: boundary routers. If enabled, this area boundary router would 2845: unconditionally translate all NSSA-LSAs regardless of translator 2846: election. Default value is no. 2847: 2848: <tag><label id="ospf-translator-stability">translator stability <M>num</M></tag> 2849: This option controls the translator stability interval (in seconds). 2850: When the new translator is elected, the old one keeps translating until 2851: the interval is over. Default value is 40. 2852: 2853: <tag><label id="ospf-networks">networks { <m/set/ }</tag> 2854: Definition of area IP ranges. This is used in summary LSA origination. 2855: Hidden networks are not propagated into other areas. 2856: 2857: <tag><label id="ospf-external">external { <m/set/ }</tag> 2858: Definition of external area IP ranges for NSSAs. This is used for 2859: NSSA-LSA translation. Hidden networks are not translated into external 2860: LSAs. Networks can have configured route tag. 2861: 2862: <tag><label id="ospf-stubnet">stubnet <m/prefix/ { <m/options/ }</tag> 2863: Stub networks are networks that are not transit networks between OSPF 2864: routers. They are also propagated through an OSPF area as a part of a 2865: link state database. By default, BIRD generates a stub network record 2866: for each primary network address on each OSPF interface that does not 2867: have any OSPF neighbors, and also for each non-primary network address 2868: on each OSPF interface. This option allows to alter a set of stub 2869: networks propagated by this router. 2870: 2871: Each instance of this option adds a stub network with given network 2872: prefix to the set of propagated stub network, unless option <cf/hidden/ 2873: is used. It also suppresses default stub networks for given network 2874: prefix. When option <cf/summary/ is used, also default stub networks 2875: that are subnetworks of given stub network are suppressed. This might be 2876: used, for example, to aggregate generated stub networks. 2877: 2878: <tag><label id="ospf-iface">interface <M>pattern</M> [instance <m/num/]</tag> 2879: Defines that the specified interfaces belong to the area being defined. 2880: See <ref id="proto-iface" name="interface"> common option for detailed 2881: description. In OSPFv2, extended interface clauses are used, because 2882: each network prefix is handled as a separate virtual interface. 2883: 2884: You can specify alternative instance ID for the interface definition, 2885: therefore it is possible to have several instances of that interface 2886: with different options or even in different areas. For OSPFv2, instance 2887: ID support is an extension (<rfc id="6549">) and is supposed to be set 2888: per-protocol. For OSPFv3, it is an integral feature. 2889: 2890: <tag><label id="ospf-virtual-link">virtual link <M>id</M> [instance <m/num/]</tag> 2891: Virtual link to router with the router id. Virtual link acts as a 2892: point-to-point interface belonging to backbone. The actual area is used 2893: as a transport area. This item cannot be in the backbone. Like with 2894: <cf/interface/ option, you could also use several virtual links to one 2895: destination with different instance IDs. 2896: 2897: <tag><label id="ospf-cost">cost <M>num</M></tag> 2898: Specifies output cost (metric) of an interface. Default value is 10. 2899: 2900: <tag><label id="ospf-stub-iface">stub <M>switch</M></tag> 2901: If set to interface it does not listen to any packet and does not send 2902: any hello. Default value is no. 2903: 2904: <tag><label id="ospf-hello">hello <M>num</M></tag> 2905: Specifies interval in seconds between sending of Hello messages. Beware, 2906: all routers on the same network need to have the same hello interval. 2907: Default value is 10. 2908: 2909: <tag><label id="ospf-poll">poll <M>num</M></tag> 2910: Specifies interval in seconds between sending of Hello messages for some 2911: neighbors on NBMA network. Default value is 20. 2912: 2913: <tag><label id="ospf-retransmit">retransmit <M>num</M></tag> 2914: Specifies interval in seconds between retransmissions of unacknowledged 2915: updates. Default value is 5. 2916: 2917: <tag><label id="ospf-priority">priority <M>num</M></tag> 2918: On every multiple access network (e.g., the Ethernet) Designated Router 2919: and Backup Designated router are elected. These routers have some special 2920: functions in the flooding process. Higher priority increases preferences 2921: in this election. Routers with priority 0 are not eligible. Default 2922: value is 1. 2923: 2924: <tag><label id="ospf-wait">wait <M>num</M></tag> 2925: After start, router waits for the specified number of seconds between 2926: starting election and building adjacency. Default value is 4*<m/hello/. 2927: 2928: <tag><label id="ospf-dead-count">dead count <M>num</M></tag> 2929: When the router does not receive any messages from a neighbor in 2930: <m/dead count/*<m/hello/ seconds, it will consider the neighbor down. 2931: 2932: <tag><label id="ospf-dead">dead <M>num</M></tag> 2933: When the router does not receive any messages from a neighbor in 2934: <m/dead/ seconds, it will consider the neighbor down. If both directives 2935: <cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precedence. 2936: 2937: <tag><label id="ospf-secondary">secondary <M>switch</M></tag> 2938: On BSD systems, older versions of BIRD supported OSPFv2 only for the 2939: primary IP address of an interface, other IP ranges on the interface 2940: were handled as stub networks. Since v1.4.1, regular operation on 2941: secondary IP addresses is supported, but disabled by default for 2942: compatibility. This option allows to enable it. The option is a 2943: transitional measure, will be removed in the next major release as the 2944: behavior will be changed. On Linux systems, the option is irrelevant, as 2945: operation on non-primary addresses is already the regular behavior. 2946: 2947: <tag><label id="ospf-rx-buffer">rx buffer <M>num</M></tag> 2948: This option allows to specify the size of buffers used for packet 2949: processing. The buffer size should be bigger than maximal size of any 2950: packets. By default, buffers are dynamically resized as needed, but a 2951: fixed value could be specified. Value <cf/large/ means maximal allowed 2952: packet size - 65535. 2953: 2954: <tag><label id="ospf-tx-length">tx length <M>num</M></tag> 2955: Transmitted OSPF messages that contain large amount of information are 2956: segmented to separate OSPF packets to avoid IP fragmentation. This 2957: option specifies the soft ceiling for the length of generated OSPF 2958: packets. Default value is the MTU of the network interface. Note that 2959: larger OSPF packets may still be generated if underlying OSPF messages 2960: cannot be splitted (e.g. when one large LSA is propagated). 2961: 2962: <tag><label id="ospf-type-bcast">type broadcast|bcast</tag> 2963: BIRD detects a type of a connected network automatically, but sometimes 2964: it's convenient to force use of a different type manually. On broadcast 2965: networks (like ethernet), flooding and Hello messages are sent using 2966: multicasts (a single packet for all the neighbors). A designated router 2967: is elected and it is responsible for synchronizing the link-state 2968: databases and originating network LSAs. This network type cannot be used 2969: on physically NBMA networks and on unnumbered networks (networks without 2970: proper IP prefix). 2971: 2972: <tag><label id="ospf-type-ptp">type pointopoint|ptp</tag> 2973: Point-to-point networks connect just 2 routers together. No election is 2974: performed and no network LSA is originated, which makes it simpler and 2975: faster to establish. This network type is useful not only for physically 2976: PtP ifaces (like PPP or tunnels), but also for broadcast networks used 2977: as PtP links. This network type cannot be used on physically NBMA 2978: networks. 2979: 2980: <tag><label id="ospf-type-nbma">type nonbroadcast|nbma</tag> 2981: On NBMA networks, the packets are sent to each neighbor separately 2982: because of lack of multicast capabilities. Like on broadcast networks, 2983: a designated router is elected, which plays a central role in propagation 2984: of LSAs. This network type cannot be used on unnumbered networks. 2985: 2986: <tag><label id="ospf-type-ptmp">type pointomultipoint|ptmp</tag> 2987: This is another network type designed to handle NBMA networks. In this 2988: case the NBMA network is treated as a collection of PtP links. This is 2989: useful if not every pair of routers on the NBMA network has direct 2990: communication, or if the NBMA network is used as an (possibly 2991: unnumbered) PtP link. 2992: 2993: <tag><label id="ospf-link-lsa-suppression">link lsa suppression <m/switch/</tag> 2994: In OSPFv3, link LSAs are generated for each link, announcing link-local 2995: IPv6 address of the router to its local neighbors. These are useless on 2996: PtP or PtMP networks and this option allows to suppress the link LSA 2997: origination for such interfaces. The option is ignored on other than PtP 2998: or PtMP interfaces. Default value is no. 2999: 3000: <tag><label id="ospf-strict-nonbroadcast">strict nonbroadcast <m/switch/</tag> 3001: If set, don't send hello to any undefined neighbor. This switch is 3002: ignored on other than NBMA or PtMP interfaces. Default value is no. 3003: 3004: <tag><label id="ospf-real-broadcast">real broadcast <m/switch/</tag> 3005: In <cf/type broadcast/ or <cf/type ptp/ network configuration, OSPF 3006: packets are sent as IP multicast packets. This option changes the 3007: behavior to using old-fashioned IP broadcast packets. This may be useful 3008: as a workaround if IP multicast for some reason does not work or does 3009: not work reliably. This is a non-standard option and probably is not 3010: interoperable with other OSPF implementations. Default value is no. 3011: 3012: <tag><label id="ospf-ptp-netmask">ptp netmask <m/switch/</tag> 3013: In <cf/type ptp/ network configurations, OSPFv2 implementations should 3014: ignore received netmask field in hello packets and should send hello 3015: packets with zero netmask field on unnumbered PtP links. But some OSPFv2 3016: implementations perform netmask checking even for PtP links. This option 3017: specifies whether real netmask will be used in hello packets on <cf/type 3018: ptp/ interfaces. You should ignore this option unless you meet some 3019: compatibility problems related to this issue. Default value is no for 3020: unnumbered PtP links, yes otherwise. 3021: 3022: <tag><label id="ospf-check-link">check link <M>switch</M></tag> 3023: If set, a hardware link state (reported by OS) is taken into consideration. 3024: When a link disappears (e.g. an ethernet cable is unplugged), neighbors 3025: are immediately considered unreachable and only the address of the iface 3026: (instead of whole network prefix) is propagated. It is possible that 3027: some hardware drivers or platforms do not implement this feature. 3028: Default value is no. 3029: 3030: <tag><label id="ospf-bfd">bfd <M>switch</M></tag> 3031: OSPF could use BFD protocol as an advisory mechanism for neighbor 3032: liveness and failure detection. If enabled, BIRD setups a BFD session 3033: for each OSPF neighbor and tracks its liveness by it. This has an 3034: advantage of an order of magnitude lower detection times in case of 3035: failure. Note that BFD protocol also has to be configured, see 3036: <ref id="bfd" name="BFD"> section for details. Default value is no. 3037: 3038: <tag><label id="ospf-ttl-security">ttl security [<m/switch/ | tx only]</tag> 3039: TTL security is a feature that protects routing protocols from remote 3040: spoofed packets by using TTL 255 instead of TTL 1 for protocol packets 3041: destined to neighbors. Because TTL is decremented when packets are 3042: forwarded, it is non-trivial to spoof packets with TTL 255 from remote 3043: locations. Note that this option would interfere with OSPF virtual 3044: links. 3045: 3046: If this option is enabled, the router will send OSPF packets with TTL 3047: 255 and drop received packets with TTL less than 255. If this option si 3048: set to <cf/tx only/, TTL 255 is used for sent packets, but is not 3049: checked for received packets. Default value is no. 3050: 3051: <tag><label id="ospf-tx-class">tx class|dscp|priority <m/num/</tag> 3052: These options specify the ToS/DiffServ/Traffic class/Priority of the 3053: outgoing OSPF packets. See <ref id="proto-tx-class" name="tx class"> common 3054: option for detailed description. 3055: 3056: <tag><label id="ospf-ecmp-weight">ecmp weight <M>num</M></tag> 3057: When ECMP (multipath) routes are allowed, this value specifies a 3058: relative weight used for nexthops going through the iface. Allowed 3059: values are 1-256. Default value is 1. 3060: 3061: <tag><label id="ospf-auth-none">authentication none</tag> 3062: No passwords are sent in OSPF packets. This is the default value. 3063: 3064: <tag><label id="ospf-auth-simple">authentication simple</tag> 3065: Every packet carries 8 bytes of password. Received packets lacking this 3066: password are ignored. This authentication mechanism is very weak. 3067: This option is not available in OSPFv3. 3068: 3069: <tag><label id="ospf-auth-cryptographic">authentication cryptographic</tag> 3070: An authentication code is appended to every packet. The specific 3071: cryptographic algorithm is selected by option <cf/algorithm/ for each 3072: key. The default cryptographic algorithm for OSPFv2 keys is Keyed-MD5 3073: and for OSPFv3 keys is HMAC-SHA-256. Passwords are not sent open via 3074: network, so this mechanism is quite secure. Packets can still be read by 3075: an attacker. 3076: 3077: <tag><label id="ospf-pass">password "<M>text</M>"</tag> 3078: Specifies a password used for authentication. See 3079: <ref id="proto-pass" name="password"> common option for detailed 3080: description. 3081: 3082: <tag><label id="ospf-neighbors">neighbors { <m/set/ } </tag> 3083: A set of neighbors to which Hello messages on NBMA or PtMP networks are 3084: to be sent. For NBMA networks, some of them could be marked as eligible. 3085: In OSPFv3, link-local addresses should be used, using global ones is 3086: possible, but it is nonstandard and might be problematic. And definitely, 3087: link-local and global addresses should not be mixed. 3088: </descrip> 3089: 3090: <sect1>Attributes 3091: <label id="ospf-attr"> 3092: 3093: OSPF defines four route attributes. Each internal route has a <cf/metric/. 3094: 3095: Metric is ranging from 1 to infinity (65535). External routes use 3096: <cf/metric type 1/ or <cf/metric type 2/. A <cf/metric of type 1/ is comparable 3097: with internal <cf/metric/, a <cf/metric of type 2/ is always longer than any 3098: <cf/metric of type 1/ or any <cf/internal metric/. <cf/Internal metric/ or 3099: <cf/metric of type 1/ is stored in attribute <cf/ospf_metric1/, <cf/metric type 3100: 2/ is stored in attribute <cf/ospf_metric2/. If you specify both metrics only 3101: metric1 is used. 3102: 3103: Each external route can also carry attribute <cf/ospf_tag/ which is a 32-bit 3104: integer which is used when exporting routes to other protocols; otherwise, it 3105: doesn't affect routing inside the OSPF domain at all. The fourth attribute 3106: <cf/ospf_router_id/ is a router ID of the router advertising that route / 3107: network. This attribute is read-only. Default is <cf/ospf_metric2 = 10000/ and 3108: <cf/ospf_tag = 0/. 3109: 3110: <sect1>Example 3111: <label id="ospf-exam"> 3112: 3113: <code> 3114: protocol ospf MyOSPF { 3115: rfc1583compat yes; 3116: tick 2; 3117: export filter { 3118: if source = RTS_BGP then { 3119: ospf_metric1 = 100; 3120: accept; 3121: } 3122: reject; 3123: }; 3124: area 0.0.0.0 { 3125: interface "eth*" { 3126: cost 11; 3127: hello 15; 3128: priority 100; 3129: retransmit 7; 3130: authentication simple; 3131: password "aaa"; 3132: }; 3133: interface "ppp*" { 3134: cost 100; 3135: authentication cryptographic; 3136: password "abc" { 3137: id 1; 3138: generate to "22-04-2003 11:00:06"; 3139: accept from "17-01-2001 12:01:05"; 3140: algorithm hmac sha384; 3141: }; 3142: password "def" { 3143: id 2; 3144: generate to "22-07-2005 17:03:21"; 3145: accept from "22-02-2001 11:34:06"; 3146: algorithm hmac sha512; 3147: }; 3148: }; 3149: interface "arc0" { 3150: cost 10; 3151: stub yes; 3152: }; 3153: interface "arc1"; 3154: }; 3155: area 120 { 3156: stub yes; 3157: networks { 3158: 172.16.1.0/24; 3159: 172.16.2.0/24 hidden; 3160: } 3161: interface "-arc0" , "arc*" { 3162: type nonbroadcast; 3163: authentication none; 3164: strict nonbroadcast yes; 3165: wait 120; 3166: poll 40; 3167: dead count 8; 3168: neighbors { 3169: 192.168.120.1 eligible; 3170: 192.168.120.2; 3171: 192.168.120.10; 3172: }; 3173: }; 3174: }; 3175: } 3176: </code> 3177: 3178: 3179: <sect>Pipe 3180: <label id="pipe"> 3181: 3182: <sect1>Introduction 3183: <label id="pipe-intro"> 3184: 3185: The Pipe protocol serves as a link between two routing tables, allowing 3186: routes to be passed from a table declared as primary (i.e., the one the pipe is 3187: connected to using the <cf/table/ configuration keyword) to the secondary one 3188: (declared using <cf/peer table/) and vice versa, depending on what's allowed by 3189: the filters. Export filters control export of routes from the primary table to 3190: the secondary one, import filters control the opposite direction. 3191: 3192: The Pipe protocol may work in the transparent mode mode or in the opaque 3193: mode. In the transparent mode, the Pipe protocol retransmits all routes from 3194: one table to the other table, retaining their original source and attributes. 3195: If import and export filters are set to accept, then both tables would have 3196: the same content. The transparent mode is the default mode. 3197: 3198: In the opaque mode, the Pipe protocol retransmits optimal route from one 3199: table to the other table in a similar way like other protocols send and receive 3200: routes. Retransmitted route will have the source set to the Pipe protocol, which 3201: may limit access to protocol specific route attributes. This mode is mainly for 3202: compatibility, it is not suggested for new configs. The mode can be changed by 3203: <tt/mode/ option. 3204: 3205: The primary use of multiple routing tables and the Pipe protocol is for 3206: policy routing, where handling of a single packet doesn't depend only on its 3207: destination address, but also on its source address, source interface, protocol 3208: type and other similar parameters. In many systems (Linux being a good example), 3209: the kernel allows to enforce routing policies by defining routing rules which 3210: choose one of several routing tables to be used for a packet according to its 3211: parameters. Setting of these rules is outside the scope of BIRD's work (on 3212: Linux, you can use the <tt/ip/ command), but you can create several routing 3213: tables in BIRD, connect them to the kernel ones, use filters to control which 3214: routes appear in which tables and also you can employ the Pipe protocol for 3215: exporting a selected subset of one table to another one. 3216: 3217: <sect1>Configuration 3218: <label id="pipe-config"> 3219: 3220: <descrip> 3221: <tag><label id="pipe-peer-table">peer table <m/table/</tag> 3222: Defines secondary routing table to connect to. The primary one is 3223: selected by the <cf/table/ keyword. 3224: 3225: <tag><label id="pipe-mode">mode opaque|transparent</tag> 3226: Specifies the mode for the pipe to work in. Default is transparent. 3227: </descrip> 3228: 3229: <sect1>Attributes 3230: <label id="pipe-attr"> 3231: 3232: The Pipe protocol doesn't define any route attributes. 3233: 3234: <sect1>Example 3235: <label id="pipe-exam"> 3236: 3237: Let's consider a router which serves as a boundary router of two different 3238: autonomous systems, each of them connected to a subset of interfaces of the 3239: router, having its own exterior connectivity and wishing to use the other AS as 3240: a backup connectivity in case of outage of its own exterior line. 3241: 3242: Probably the simplest solution to this situation is to use two routing tables 3243: (we'll call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that 3244: packets having arrived from interfaces belonging to the first AS will be routed 3245: according to <cf/as1/ and similarly for the second AS. Thus we have split our 3246: router to two logical routers, each one acting on its own routing table, having 3247: its own routing protocols on its own interfaces. In order to use the other AS's 3248: routes for backup purposes, we can pass the routes between the tables through a 3249: Pipe protocol while decreasing their preferences and correcting their BGP paths 3250: to reflect the AS boundary crossing. 3251: 3252: <code> 3253: table as1; # Define the tables 3254: table as2; 3255: 3256: protocol kernel kern1 { # Synchronize them with the kernel 3257: table as1; 3258: kernel table 1; 3259: } 3260: 3261: protocol kernel kern2 { 3262: table as2; 3263: kernel table 2; 3264: } 3265: 3266: protocol bgp bgp1 { # The outside connections 3267: table as1; 3268: local as 1; 3269: neighbor 192.168.0.1 as 1001; 3270: export all; 3271: import all; 3272: } 3273: 3274: protocol bgp bgp2 { 3275: table as2; 3276: local as 2; 3277: neighbor 10.0.0.1 as 1002; 3278: export all; 3279: import all; 3280: } 3281: 3282: protocol pipe { # The Pipe 3283: table as1; 3284: peer table as2; 3285: export filter { 3286: if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks 3287: if preference>10 then preference = preference-10; 3288: if source=RTS_BGP then bgp_path.prepend(1); 3289: accept; 3290: } 3291: reject; 3292: }; 3293: import filter { 3294: if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks 3295: if preference>10 then preference = preference-10; 3296: if source=RTS_BGP then bgp_path.prepend(2); 3297: accept; 3298: } 3299: reject; 3300: }; 3301: } 3302: </code> 3303: 3304: 3305: <sect>RAdv 3306: <label id="radv"> 3307: 3308: <sect1>Introduction 3309: <label id="radv-intro"> 3310: 3311: The RAdv protocol is an implementation of Router Advertisements, which are 3312: used in the IPv6 stateless autoconfiguration. IPv6 routers send (in irregular 3313: time intervals or as an answer to a request) advertisement packets to connected 3314: networks. These packets contain basic information about a local network (e.g. a 3315: list of network prefixes), which allows network hosts to autoconfigure network 3316: addresses and choose a default route. BIRD implements router behavior as defined 3317: in <rfc id="4861"> and also the DNS extensions from <rfc id="6106">. 3318: 3319: <sect1>Configuration 3320: <label id="radv-config"> 3321: 3322: There are several classes of definitions in RAdv configuration -- interface 3323: definitions, prefix definitions and DNS definitions: 3324: 3325: <descrip> 3326: <tag><label id="radv-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag> 3327: Interface definitions specify a set of interfaces on which the 3328: protocol is activated and contain interface specific options. 3329: See <ref id="proto-iface" name="interface"> common options for 3330: detailed description. 3331: 3332: <tag><label id="radv-prefix">prefix <m/prefix/ { <m/options/ }</tag> 3333: Prefix definitions allow to modify a list of advertised prefixes. By 3334: default, the advertised prefixes are the same as the network prefixes 3335: assigned to the interface. For each network prefix, the matching prefix 3336: definition is found and its options are used. If no matching prefix 3337: definition is found, the prefix is used with default options. 3338: 3339: Prefix definitions can be either global or interface-specific. The 3340: second ones are part of interface options. The prefix definition 3341: matching is done in the first-match style, when interface-specific 3342: definitions are processed before global definitions. As expected, the 3343: prefix definition is matching if the network prefix is a subnet of the 3344: prefix in prefix definition. 3345: 3346: <tag><label id="radv-rdnss">rdnss { <m/options/ }</tag> 3347: RDNSS definitions allow to specify a list of advertised recursive DNS 3348: servers together with their options. As options are seldom necessary, 3349: there is also a short variant <cf>rdnss <m/address/</cf> that just 3350: specifies one DNS server. Multiple definitions are cumulative. RDNSS 3351: definitions may also be interface-specific when used inside interface 3352: options. By default, interface uses both global and interface-specific 3353: options, but that can be changed by <cf/rdnss local/ option. 3354: dsc-iface 3355: <tag><label id="radv-dnssl">dnssl { <m/options/ }</tag> 3356: DNSSL definitions allow to specify a list of advertised DNS search 3357: domains together with their options. Like <cf/rdnss/ above, multiple 3358: definitions are cumulative, they can be used also as interface-specific 3359: options and there is a short variant <cf>dnssl <m/domain/</cf> that just 3360: specifies one DNS search domain. 3361: 3362: <tag><label id="radv-trigger">trigger <m/prefix/</tag> 3363: RAdv protocol could be configured to change its behavior based on 3364: availability of routes. When this option is used, the protocol waits in 3365: suppressed state until a <it/trigger route/ (for the specified network) 3366: is exported to the protocol, the protocol also returnsd to suppressed 3367: state if the <it/trigger route/ disappears. Note that route export 3368: depends on specified export filter, as usual. This option could be used, 3369: e.g., for handling failover in multihoming scenarios. 3370: 3371: During suppressed state, router advertisements are generated, but with 3372: some fields zeroed. Exact behavior depends on which fields are zeroed, 3373: this can be configured by <cf/sensitive/ option for appropriate 3374: fields. By default, just <cf/default lifetime/ (also called <cf/router 3375: lifetime/) is zeroed, which means hosts cannot use the router as a 3376: default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could 3377: also be configured as <cf/sensitive/ for a prefix, which would cause 3378: autoconfigured IPs to be deprecated or even removed. 3379: </descrip> 3380: 3381: Interface specific options: 3382: 3383: <descrip> 3384: <tag><label id="radv-iface-max-ra-interval">max ra interval <m/expr/</tag> 3385: Unsolicited router advertisements are sent in irregular time intervals. 3386: This option specifies the maximum length of these intervals, in seconds. 3387: Valid values are 4-1800. Default: 600 3388: 3389: <tag><label id="radv-iface-min-ra-interval">min ra interval <m/expr/</tag> 3390: This option specifies the minimum length of that intervals, in seconds. 3391: Must be at least 3 and at most 3/4 * <cf/max ra interval/. Default: 3392: about 1/3 * <cf/max ra interval/. 3393: 3394: <tag><label id="radv-iface-min-delay">min delay <m/expr/</tag> 3395: The minimum delay between two consecutive router advertisements, in 3396: seconds. Default: 3 3397: 3398: <tag><label id="radv-iface-managed">managed <m/switch/</tag> 3399: This option specifies whether hosts should use DHCPv6 for IP address 3400: configuration. Default: no 3401: 3402: <tag><label id="radv-iface-other-config">other config <m/switch/</tag> 3403: This option specifies whether hosts should use DHCPv6 to receive other 3404: configuration information. Default: no 3405: 3406: <tag><label id="radv-iface-link-mtu">link mtu <m/expr/</tag> 3407: This option specifies which value of MTU should be used by hosts. 0 3408: means unspecified. Default: 0 3409: 3410: <tag><label id="radv-iface-reachable-time">reachable time <m/expr/</tag> 3411: This option specifies the time (in milliseconds) how long hosts should 3412: assume a neighbor is reachable (from the last confirmation). Maximum is 3413: 3600000, 0 means unspecified. Default 0. 3414: 3415: <tag><label id="radv-iface-retrans-timer">retrans timer <m/expr/</tag> 3416: This option specifies the time (in milliseconds) how long hosts should 3417: wait before retransmitting Neighbor Solicitation messages. 0 means 3418: unspecified. Default 0. 3419: 3420: <tag><label id="radv-iface-current-hop-limit">current hop limit <m/expr/</tag> 3421: This option specifies which value of Hop Limit should be used by 3422: hosts. Valid values are 0-255, 0 means unspecified. Default: 64 3423: 3424: <tag><label id="radv-iface-default-lifetime">default lifetime <m/expr/ [sensitive <m/switch/]</tag> 3425: This option specifies the time (in seconds) how long (after the receipt 3426: of RA) hosts may use the router as a default router. 0 means do not use 3427: as a default router. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">. 3428: Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes. 3429: 3430: <tag><label id="radv-iface-default-preference-low">default preference low|medium|high</tag> 3431: This option specifies the Default Router Preference value to advertise 3432: to hosts. Default: medium. 3433: 3434: <tag><label id="radv-iface-rdnss-local">rdnss local <m/switch/</tag> 3435: Use only local (interface-specific) RDNSS definitions for this 3436: interface. Otherwise, both global and local definitions are used. Could 3437: also be used to disable RDNSS for given interface if no local definitons 3438: are specified. Default: no. 3439: 3440: <tag><label id="radv-iface-dnssl-local">dnssl local <m/switch/</tag> 3441: Use only local DNSSL definitions for this interface. See <cf/rdnss local/ 3442: option above. Default: no. 3443: </descrip> 3444: 3445: 3446: Prefix specific options 3447: 3448: <descrip> 3449: <tag><label id="radv-prefix-skip">skip <m/switch/</tag> 3450: This option allows to specify that given prefix should not be 3451: advertised. This is useful for making exceptions from a default policy 3452: of advertising all prefixes. Note that for withdrawing an already 3453: advertised prefix it is more useful to advertise it with zero valid 3454: lifetime. Default: no 3455: 3456: <tag><label id="radv-prefix-onlink">onlink <m/switch/</tag> 3457: This option specifies whether hosts may use the advertised prefix for 3458: onlink determination. Default: yes 3459: 3460: <tag><label id="radv-prefix-autonomous">autonomous <m/switch/</tag> 3461: This option specifies whether hosts may use the advertised prefix for 3462: stateless autoconfiguration. Default: yes 3463: 3464: <tag><label id="radv-prefix-valid-lifetime">valid lifetime <m/expr/ [sensitive <m/switch/]</tag> 3465: This option specifies the time (in seconds) how long (after the 3466: receipt of RA) the prefix information is valid, i.e., autoconfigured 3467: IP addresses can be assigned and hosts with that IP addresses are 3468: considered directly reachable. 0 means the prefix is no longer 3469: valid. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">. 3470: Default: 86400 (1 day), <cf/sensitive/ no. 3471: 3472: <tag><label id="radv-prefix-preferred-lifetime">preferred lifetime <m/expr/ [sensitive <m/switch/]</tag> 3473: This option specifies the time (in seconds) how long (after the 3474: receipt of RA) IP addresses generated from the prefix using stateless 3475: autoconfiguration remain preferred. For <cf/sensitive/ option, 3476: see <ref id="radv-trigger" name="trigger">. Default: 14400 (4 hours), 3477: <cf/sensitive/ no. 3478: </descrip> 3479: 3480: 3481: RDNSS specific options: 3482: 3483: <descrip> 3484: <tag><label id="radv-rdnss-ns">ns <m/address/</tag> 3485: This option specifies one recursive DNS server. Can be used multiple 3486: times for multiple servers. It is mandatory to have at least one 3487: <cf/ns/ option in <cf/rdnss/ definition. 3488: 3489: <tag><label id="radv-rdnss-lifetime">lifetime [mult] <m/expr/</tag> 3490: This option specifies the time how long the RDNSS information may be 3491: used by clients after the receipt of RA. It is expressed either in 3492: seconds or (when <cf/mult/ is used) in multiples of <cf/max ra 3493: interval/. Note that RDNSS information is also invalidated when 3494: <cf/default lifetime/ expires. 0 means these addresses are no longer 3495: valid DNS servers. Default: 3 * <cf/max ra interval/. 3496: </descrip> 3497: 3498: 3499: DNSSL specific options: 3500: 3501: <descrip> 3502: <tag><label id="radv-dnssl-domain">domain <m/address/</tag> 3503: This option specifies one DNS search domain. Can be used multiple times 3504: for multiple domains. It is mandatory to have at least one <cf/domain/ 3505: option in <cf/dnssl/ definition. 3506: 3507: <tag><label id="radv-dnssl-lifetime">lifetime [mult] <m/expr/</tag> 3508: This option specifies the time how long the DNSSL information may be 3509: used by clients after the receipt of RA. Details are the same as for 3510: RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/. 3511: </descrip> 3512: 3513: 3514: <sect1>Example 3515: <label id="radv-exam"> 3516: 3517: <code> 3518: protocol radv { 3519: interface "eth2" { 3520: max ra interval 5; # Fast failover with more routers 3521: managed yes; # Using DHCPv6 on eth2 3522: prefix ::/0 { 3523: autonomous off; # So do not autoconfigure any IP 3524: }; 3525: }; 3526: 3527: interface "eth*"; # No need for any other options 3528: 3529: prefix 2001:0DB8:1234::/48 { 3530: preferred lifetime 0; # Deprecated address range 3531: }; 3532: 3533: prefix 2001:0DB8:2000::/48 { 3534: autonomous off; # Do not autoconfigure 3535: }; 3536: 3537: rdnss 2001:0DB8:1234::10; # Short form of RDNSS 3538: 3539: rdnss { 3540: lifetime mult 10; 3541: ns 2001:0DB8:1234::11; 3542: ns 2001:0DB8:1234::12; 3543: }; 3544: 3545: dnssl { 3546: lifetime 3600; 3547: domain "abc.com"; 3548: domain "xyz.com"; 3549: }; 3550: } 3551: </code> 3552: 3553: 3554: <sect>RIP 3555: <label id="rip"> 3556: 3557: <sect1>Introduction 3558: <label id="rip-intro"> 3559: 3560: The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, 3561: where each router broadcasts (to all its neighbors) distances to all networks it 3562: can reach. When a router hears distance to another network, it increments it and 3563: broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some 3564: network goes unreachable, routers keep telling each other that its distance is 3565: the original distance plus 1 (actually, plus interface metric, which is usually 3566: one). After some time, the distance reaches infinity (that's 15 in RIP) and all 3567: routers know that network is unreachable. RIP tries to minimize situations where 3568: counting to infinity is necessary, because it is slow. Due to infinity being 16, 3569: you can't use RIP on networks where maximal distance is higher than 15 3570: hosts. 3571: 3572: BIRD supports RIPv1 (<rfc id="1058">), RIPv2 (<rfc id="2453">), RIPng (<rfc 3573: id="2080">), and RIP cryptographic authentication (<rfc id="4822">). 3574: 3575: RIP is a very simple protocol, and it has a lot of shortcomings. Slow 3576: convergence, big network load and inability to handle larger networks makes it 3577: pretty much obsolete. It is still usable on very small networks. 3578: 3579: <sect1>Configuration 3580: <label id="rip-config"> 3581: 3582: RIP configuration consists mainly of common protocol options and interface 3583: definitions, most RIP options are interface specific. 3584: 3585: <code> 3586: protocol rip [<name>] { 3587: infinity <number>; 3588: ecmp <switch> [limit <number>]; 3589: interface <interface pattern> { 3590: metric <number>; 3591: mode multicast|broadcast; 3592: passive <switch>; 3593: address <ip>; 3594: port <number>; 3595: version 1|2; 3596: split horizon <switch>; 3597: poison reverse <switch>; 3598: check zero <switch>; 3599: update time <number>; 3600: timeout time <number>; 3601: garbage time <number>; 3602: ecmp weight <number>; 3603: ttl security <switch>; | tx only; 3604: tx class|dscp <number>; 3605: tx priority <number>; 3606: rx buffer <number>; 3607: tx length <number>; 3608: check link <switch>; 3609: authentication none|plaintext|cryptographic; 3610: password "<text>"; 3611: password "<text>" { 3612: id <num>; 3613: generate from "<date>"; 3614: generate to "<date>"; 3615: accept from "<date>"; 3616: accept to "<date>"; 3617: from "<date>"; 3618: to "<date>"; 3619: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 ); 3620: }; 3621: }; 3622: } 3623: </code> 3624: 3625: <descrip> 3626: <tag><label id="rip-infinity">infinity <M>number</M></tag> 3627: Selects the distance of infinity. Bigger values will make 3628: protocol convergence even slower. The default value is 16. 3629: 3630: <tag><label id="rip-ecmp">ecmp <M>switch</M> [limit <M>number</M>]</tag> 3631: This option specifies whether RIP is allowed to generate ECMP 3632: (equal-cost multipath) routes. Such routes are used when there are 3633: several directions to the destination, each with the same (computed) 3634: cost. This option also allows to specify a limit on maximum number of 3635: nexthops in one route. By default, ECMP is disabled. If enabled, 3636: default value of the limit is 16. 3637: 3638: <tag><label id="rip-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag> 3639: Interface definitions specify a set of interfaces on which the 3640: protocol is activated and contain interface specific options. 3641: See <ref id="proto-iface" name="interface"> common options for 3642: detailed description. 3643: </descrip> 3644: 3645: Interface specific options: 3646: 3647: <descrip> 3648: <tag><label id="rip-iface-metric">metric <m/num/</tag> 3649: This option specifies the metric of the interface. When a route is 3650: received from the interface, its metric is increased by this value 3651: before further processing. Valid values are 1-255, but values higher 3652: than infinity has no further meaning. Default: 1. 3653: 3654: <tag><label id="rip-iface-mode">mode multicast|broadcast</tag> 3655: This option selects the mode for RIP to use on the interface. The 3656: default is multicast mode for RIPv2 and broadcast mode for RIPv1. 3657: RIPng always uses the multicast mode. 3658: 3659: <tag><label id="rip-iface-passive">passive <m/switch/</tag> 3660: Passive interfaces receive routing updates but do not transmit any 3661: messages. Default: no. 3662: 3663: <tag><label id="rip-iface-address">address <m/ip/</tag> 3664: This option specifies a destination address used for multicast or 3665: broadcast messages, the default is the official RIP (224.0.0.9) or RIPng 3666: (ff02::9) multicast address, or an appropriate broadcast address in the 3667: broadcast mode. 3668: 3669: <tag><label id="rip-iface-port">port <m/number/</tag> 3670: This option selects an UDP port to operate on, the default is the 3671: official RIP (520) or RIPng (521) port. 3672: 3673: <tag><label id="rip-iface-version">version 1|2</tag> 3674: This option selects the version of RIP used on the interface. For RIPv1, 3675: automatic subnet aggregation is not implemented, only classful network 3676: routes and host routes are propagated. Note that BIRD allows RIPv1 to be 3677: configured with features that are defined for RIPv2 only, like 3678: authentication or using multicast sockets. The default is RIPv2 for IPv4 3679: RIP, the option is not supported for RIPng, as no further versions are 3680: defined. 3681: 3682: <tag><label id="rip-iface-version-only">version only <m/switch/</tag> 3683: Regardless of RIP version configured for the interface, BIRD accepts 3684: incoming packets of any RIP version. This option restrict accepted 3685: packets to the configured version. Default: no. 3686: 3687: <tag><label id="rip-iface-split-horizon">split horizon <m/switch/</tag> 3688: Split horizon is a scheme for preventing routing loops. When split 3689: horizon is active, routes are not regularly propagated back to the 3690: interface from which they were received. They are either not propagated 3691: back at all (plain split horizon) or propagated back with an infinity 3692: metric (split horizon with poisoned reverse). Therefore, other routers 3693: on the interface will not consider the router as a part of an 3694: independent path to the destination of the route. Default: yes. 3695: 3696: <tag><label id="rip-iface-poison-reverse">poison reverse <m/switch/</tag> 3697: When split horizon is active, this option specifies whether the poisoned 3698: reverse variant (propagating routes back with an infinity metric) is 3699: used. The poisoned reverse has some advantages in faster convergence, 3700: but uses more network traffic. Default: yes. 3701: 3702: <tag><label id="rip-iface-check-zero">check zero <m/switch/</tag> 3703: Received RIPv1 packets with non-zero values in reserved fields should 3704: be discarded. This option specifies whether the check is performed or 3705: such packets are just processed as usual. Default: yes. 3706: 3707: <tag><label id="rip-iface-update-time">update time <m/number/</tag> 3708: Specifies the number of seconds between periodic updates. A lower number 3709: will mean faster convergence but bigger network load. Default: 30. 3710: 3711: <tag><label id="rip-iface-timeout-time">timeout time <m/number/</tag> 3712: Specifies the time interval (in seconds) between the last received route 3713: announcement and the route expiration. After that, the network is 3714: considered unreachable, but still is propagated with infinity distance. 3715: Default: 180. 3716: 3717: <tag><label id="rip-iface-garbage-time">garbage time <m/number/</tag> 3718: Specifies the time interval (in seconds) between the route expiration 3719: and the removal of the unreachable network entry. The garbage interval, 3720: when a route with infinity metric is propagated, is used for both 3721: internal (after expiration) and external (after withdrawal) routes. 3722: Default: 120. 3723: 3724: <tag><label id="rip-iface-ecmp-weight">ecmp weight <m/number/</tag> 3725: When ECMP (multipath) routes are allowed, this value specifies a 3726: relative weight used for nexthops going through the iface. Valid 3727: values are 1-256. Default value is 1. 3728: 3729: <tag><label id="rip-iface-auth">authentication none|plaintext|cryptographic</tag> 3730: Selects authentication method to be used. <cf/none/ means that packets 3731: are not authenticated at all, <cf/plaintext/ means that a plaintext 3732: password is embedded into each packet, and <cf/cryptographic/ means that 3733: packets are authenticated using some cryptographic hash function 3734: selected by option <cf/algorithm/ for each key. The default 3735: cryptographic algorithm for RIP keys is Keyed-MD5. If you set 3736: authentication to not-none, it is a good idea to add <cf>password</cf> 3737: section. Default: none. 3738: 3739: <tag><label id="rip-iface-pass">password "<m/text/"</tag> 3740: Specifies a password used for authentication. See <ref id="proto-pass" 3741: name="password"> common option for detailed description. 3742: 3743: <tag><label id="rip-iface-ttl-security">ttl security [<m/switch/ | tx only]</tag> 3744: TTL security is a feature that protects routing protocols from remote 3745: spoofed packets by using TTL 255 instead of TTL 1 for protocol packets 3746: destined to neighbors. Because TTL is decremented when packets are 3747: forwarded, it is non-trivial to spoof packets with TTL 255 from remote 3748: locations. 3749: 3750: If this option is enabled, the router will send RIP packets with TTL 255 3751: and drop received packets with TTL less than 255. If this option si set 3752: to <cf/tx only/, TTL 255 is used for sent packets, but is not checked 3753: for received packets. Such setting does not offer protection, but offers 3754: compatibility with neighbors regardless of whether they use ttl 3755: security. 3756: 3757: For RIPng, TTL security is a standard behavior (required by <rfc 3758: id="2080">) and therefore default value is yes. For IPv4 RIP, default 3759: value is no. 3760: 3761: <tag><label id="rip-iface-tx-class">tx class|dscp|priority <m/number/</tag> 3762: These options specify the ToS/DiffServ/Traffic class/Priority of the 3763: outgoing RIP packets. See <ref id="proto-tx-class" name="tx class"> common 3764: option for detailed description. 3765: 3766: <tag><label id="rip-iface-rx-buffer">rx buffer <m/number/</tag> 3767: This option specifies the size of buffers used for packet processing. 3768: The buffer size should be bigger than maximal size of received packets. 3769: The default value is 532 for IPv4 RIP and interface MTU value for RIPng. 3770: 3771: <tag><label id="rip-iface-tx-length">tx length <m/number/</tag> 3772: This option specifies the maximum length of generated RIP packets. To 3773: avoid IP fragmentation, it should not exceed the interface MTU value. 3774: The default value is 532 for IPv4 RIP and interface MTU value for RIPng. 3775: 3776: <tag><label id="rip-iface-check-link">check link <m/switch/</tag> 3777: If set, the hardware link state (as reported by OS) is taken into 3778: consideration. When the link disappears (e.g. an ethernet cable is 3779: unplugged), neighbors are immediately considered unreachable and all 3780: routes received from them are withdrawn. It is possible that some 3781: hardware drivers or platforms do not implement this feature. 3782: Default: no. 3783: </descrip> 3784: 3785: <sect1>Attributes 3786: <label id="rip-attr"> 3787: 3788: RIP defines two route attributes: 3789: 3790: <descrip> 3791: <tag><label id="rta-rip-metric">int rip_metric/</tag> 3792: RIP metric of the route (ranging from 0 to <cf/infinity/). When routes 3793: from different RIP instances are available and all of them have the same 3794: preference, BIRD prefers the route with lowest <cf/rip_metric/. When a 3795: non-RIP route is exported to RIP, the default metric is 1. 3796: 3797: <tag><label id="rta-rip-tag">int rip_tag/</tag> 3798: RIP route tag: a 16-bit number which can be used to carry additional 3799: information with the route (for example, an originating AS number in 3800: case of external routes). When a non-RIP route is exported to RIP, the 3801: default tag is 0. 3802: </descrip> 3803: 3804: <sect1>Example 3805: <label id="rip-exam"> 3806: 3807: <code> 3808: protocol rip { 3809: debug all; 3810: port 1520; 3811: period 12; 3812: garbage time 60; 3813: interface "eth0" { metric 3; mode multicast; }; 3814: interface "eth*" { metric 2; mode broadcast; }; 3815: authentication cryptographic; 3816: password "secret-shared-key" { algorithm hmac sha256; }; 3817: import filter { print "importing"; accept; }; 3818: export filter { print "exporting"; accept; }; 3819: } 3820: </code> 3821: 3822: 3823: <sect>Static 3824: <label id="static"> 3825: 3826: The Static protocol doesn't communicate with other routers in the network, 3827: but instead it allows you to define routes manually. This is often used for 3828: specifying how to forward packets to parts of the network which don't use 3829: dynamic routing at all and also for defining sink routes (i.e., those telling to 3830: return packets as undeliverable if they are in your IP block, you don't have any 3831: specific destination for them and you don't want to send them out through the 3832: default route to prevent routing loops). 3833: 3834: There are five types of static routes: `classical' routes telling to forward 3835: packets to a neighboring router, multipath routes specifying several (possibly 3836: weighted) neighboring routers, device routes specifying forwarding to hosts on a 3837: directly connected network, recursive routes computing their nexthops by doing 3838: route table lookups for a given IP, and special routes (sink, blackhole etc.) 3839: which specify a special action to be done instead of forwarding the packet. 3840: 3841: When the particular destination is not available (the interface is down or 3842: the next hop of the route is not a neighbor at the moment), Static just 3843: uninstalls the route from the table it is connected to and adds it again as soon 3844: as the destination becomes adjacent again. 3845: 3846: There are three classes of definitions in Static protocol configuration -- 3847: global options, static route definitions, and per-route options. Usually, the 3848: definition of the protocol contains mainly a list of static routes. 3849: 3850: Global options: 3851: 3852: <descrip> 3853: <tag><label id="static-check-link">check link <m/switch/</tag> 3854: If set, hardware link states of network interfaces are taken into 3855: consideration. When link disappears (e.g. ethernet cable is unplugged), 3856: static routes directing to that interface are removed. It is possible 3857: that some hardware drivers or platforms do not implement this feature. 3858: Default: off. 3859: 3860: <tag><label id="static-igp-table">igp table <m/name/</tag> 3861: Specifies a table that is used for route table lookups of recursive 3862: routes. Default: the same table as the protocol is connected to. 3863: </descrip> 3864: 3865: Route definitions (each may also contain a block of per-route options): 3866: 3867: <descrip> 3868: <tag><label id="static-route-via-ip">route <m/prefix/ via <m/ip/</tag> 3869: Static route through a neighboring router. For link-local next hops, 3870: interface can be specified as a part of the address (e.g., 3871: <cf/via fe80::1234%eth0/). 3872: 3873: <tag><label id="static-route-via-mpath">route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [bfd <m/switch/] [via <m/.../]</tag> 3874: Static multipath route. Contains several nexthops (gateways), possibly 3875: with their weights. 3876: 3877: <tag><label id="static-route-via-iface">route <m/prefix/ via <m/"interface"/</tag> 3878: Static device route through an interface to hosts on a directly 3879: connected network. 3880: 3881: <tag><label id="static-route-recursive">route <m/prefix/ recursive <m/ip/</tag> 3882: Static recursive route, its nexthop depends on a route table lookup for 3883: given IP address. 3884: 3885: <tag><label id="static-route-drop">route <m/prefix/ blackhole|unreachable|prohibit</tag> 3886: Special routes specifying to silently drop the packet, return it as 3887: unreachable or return it as administratively prohibited. First two 3888: targets are also known as <cf/drop/ and <cf/reject/. 3889: </descrip> 3890: 3891: Per-route options: 3892: 3893: <descrip> 3894: <tag><label id="static-route-bfd">bfd <m/switch/</tag> 3895: The Static protocol could use BFD protocol for next hop liveness 3896: detection. If enabled, a BFD session to the route next hop is created 3897: and the static route is BFD-controlled -- the static route is announced 3898: only if the next hop liveness is confirmed by BFD. If the BFD session 3899: fails, the static route is removed. Note that this is a bit different 3900: compared to other protocols, which may use BFD as an advisory mechanism 3901: for fast failure detection but ignores it if a BFD session is not even 3902: established. 3903: 3904: This option can be used for static routes with a direct next hop, or 3905: also for for individual next hops in a static multipath route (see 3906: above). Note that BFD protocol also has to be configured, see 3907: <ref id="bfd" name="BFD"> section for details. Default value is no. 3908: 3909: <tag><label id="static-route-filter"><m/filter expression/</tag> 3910: This is a special option that allows filter expressions to be configured 3911: on per-route basis. Can be used multiple times. These expressions are 3912: evaluated when the route is originated, similarly to the import filter 3913: of the static protocol. This is especially useful for configuring route 3914: attributes, e.g., <cf/ospf_metric1 = 100;/ for a route that will be 3915: exported to the OSPF protocol. 3916: </descrip> 3917: 3918: Static routes have no specific attributes. 3919: 3920: Example static config might look like this: 3921: 3922: <code> 3923: protocol static { 3924: table testable; # Connect to a non-default routing table 3925: check link; # Advertise routes only if link is up 3926: route 0.0.0.0/0 via 198.51.100.130; # Default route 3927: route 10.0.0.0/8 multipath # Multipath route 3928: via 198.51.100.10 weight 2 3929: via 198.51.100.20 bfd # BFD-controlled next hop 3930: via 192.0.2.1; 3931: route 203.0.113.0/24 unreachable; # Sink route 3932: route 10.2.0.0/24 via "arc0"; # Secondary network 3933: route 192.168.10.0/24 via 198.51.100.100 { 3934: ospf_metric1 = 20; # Set extended attribute 3935: } 3936: route 192.168.10.0/24 via 198.51.100.100 { 3937: ospf_metric2 = 100; # Set extended attribute 3938: ospf_tag = 2; # Set extended attribute 3939: bfd; # BFD-controlled route 3940: } 3941: } 3942: </code> 3943: 3944: 3945: <chapt>Conclusions 3946: <label id="conclusion"> 3947: 3948: <sect>Future work 3949: <label id="future-work"> 3950: 3951: Although BIRD supports all the commonly used routing protocols, there are 3952: still some features which would surely deserve to be implemented in future 3953: versions of BIRD: 3954: 3955: <itemize> 3956: <item>Opaque LSA's 3957: <item>Route aggregation and flap dampening 3958: <item>Multipath routes 3959: <item>Multicast routing protocols 3960: <item>Ports to other systems 3961: </itemize> 3962: 3963: 3964: <sect>Getting more help 3965: <label id="help"> 3966: 3967: If you use BIRD, you're welcome to join the bird-users mailing list 3968: (<HTMLURL URL="mailto:bird-users@network.cz" name="bird-users@network.cz">) 3969: where you can share your experiences with the other users and consult 3970: your problems with the authors. To subscribe to the list, visit 3971: <HTMLURL URL="http://bird.network.cz/?m_list" name="http://bird.network.cz/?m_list">. 3972: The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">. 3973: 3974: BIRD is a relatively young system and it probably contains some bugs. You can 3975: report any problems to the bird-users list and the authors will be glad to solve 3976: them, but before you do so, please make sure you have read the available 3977: documentation and that you are running the latest version (available at 3978: <HTMLURL URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). 3979: (Of course, a patch which fixes the bug is always welcome as an attachment.) 3980: 3981: If you want to understand what is going inside, Internet standards are a good 3982: and interesting reading. You can get them from 3983: <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a 3984: nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" 3985: name="atrey.karlin.mff.cuni.cz:/pub/rfc">). 3986: 3987: <it/Good luck!/ 3988: 3989: </book> 3990: 3991: