Annotation of embedaddon/bird2/doc/bird.sgml, revision 1.1.1.1
1.1 misho 1: <!doctype birddoc system>
2:
3: <!--
4: BIRD 2.0 documentation
5:
6: This documentation can have 4 forms: sgml (this is master copy), html, ASCII
7: text and dvi/postscript (generated from sgml using sgmltools). You should always
8: edit master copy.
9:
10: This is a slightly modified linuxdoc dtd. Anything in <descrip> tags is
11: considered definition of configuration primitives, <cf> is fragment of
12: configuration within normal text, <m> is "meta" information within fragment of
13: configuration - something in config which is not keyword.
14:
15: (set-fill-column 80)
16:
17: Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
18:
19: -->
20:
21: <book>
22:
23: <title>BIRD 2.0 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: Maria Matejka <it/<mq@jmq.cz>/,
29: Ondrej Zajicek <it/<santiago@crfreenet.org>/
30: </author>
31:
32: <abstract>
33: This document contains user documentation for the BIRD Internet Routing Daemon project.
34: </abstract>
35:
36: <!-- Table of contents -->
37: <toc>
38:
39: <!-- Begin the document -->
40:
41:
42: <chapt>Introduction
43: <label id="intro">
44:
45: <sect>What is BIRD
46: <label id="what-is-bird">
47:
48: <p>The name `BIRD' is actually an acronym standing for `BIRD Internet Routing
49: Daemon'. Let's take a closer look at the meaning of the name:
50:
51: <p><em/BIRD/: Well, we think we have already explained that. It's an acronym
52: standing for `BIRD Internet Routing Daemon', you remember, don't you? :-)
53:
54: <p><em/Internet Routing/: It's a program (well, a daemon, as you are going to
55: discover in a moment) which works as a dynamic router in an Internet type
56: network (that is, in a network running either the IPv4 or the IPv6 protocol).
57: Routers are devices which forward packets between interconnected networks in
58: order to allow hosts not connected directly to the same local area network to
59: communicate with each other. They also communicate with the other routers in the
60: Internet to discover the topology of the network which allows them to find
61: optimal (in terms of some metric) rules for forwarding of packets (which are
62: called routing tables) and to adapt themselves to the changing conditions such
63: as outages of network links, building of new connections and so on. Most of
64: these routers are costly dedicated devices running obscure firmware which is
65: hard to configure and not open to any changes (on the other hand, their special
66: hardware design allows them to keep up with lots of high-speed network
67: interfaces, better than general-purpose computer does). Fortunately, most
68: operating systems of the UNIX family allow an ordinary computer to act as a
69: router and forward packets belonging to the other hosts, but only according to a
70: statically configured table.
71:
72: <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program
73: running on background which does the dynamic part of Internet routing, that is
74: it communicates with the other routers, calculates routing tables and sends them
75: to the OS kernel which does the actual packet forwarding. There already exist
76: other such routing daemons: routed (RIP only), GateD (non-free),
77: <HTMLURL URL="http://www.zebra.org" name="Zebra"> and
78: <HTMLURL URL="http://sourceforge.net/projects/mrt" name="MRTD">,
79: but their capabilities are limited and they are relatively hard to configure
80: and maintain.
81:
82: <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
83: to support all the routing technology used in the today's Internet or planned to
84: be used in near future and to have a clean extensible architecture allowing new
85: routing protocols to be incorporated easily. Among other features, BIRD
86: supports:
87:
88: <itemize>
89: <item>both IPv4 and IPv6 protocols
90: <item>multiple routing tables
91: <item>the Border Gateway Protocol (BGPv4)
92: <item>the Routing Information Protocol (RIPv2, RIPng)
93: <item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
94: <item>the Babel Routing Protocol
95: <item>the Router Advertisements for IPv6 hosts
96: <item>a virtual protocol for exchange of routes between different
97: routing tables on a single host
98: <item>a command-line interface allowing on-line control and inspection
99: of status of the daemon
100: <item>soft reconfiguration (no need to use complex online commands to
101: change the configuration, just edit the configuration file and
102: notify BIRD to re-read it and it will smoothly switch itself to
103: the new configuration, not disturbing routing protocols unless
104: they are affected by the configuration changes)
105: <item>a powerful language for route filtering
106: </itemize>
107:
108: <p>BIRD has been developed at the Faculty of Math and Physics, Charles
109: University, Prague, Czech Republic as a student project. It can be freely
110: distributed under the terms of the GNU General Public License.
111:
112: <p>BIRD has been designed to work on all UNIX-like systems. It has been
113: developed and tested under Linux 2.0 to 2.6, and then ported to FreeBSD, NetBSD
114: and OpenBSD, porting to other systems (even non-UNIX ones) should be relatively
115: easy due to its highly modular architecture.
116:
117: <p>BIRD 1.x supported either IPv4 or IPv6 protocol, but had to be compiled separately
118: for each one. BIRD~2 supports both of them with a possibility of further extension.
119: BIRD~2 supports Linux at least 3.16, FreeBSD 10, NetBSD 7.0, and OpenBSD 5.8.
120: Anyway, it will probably work well also on older systems.
121:
122: <sect>Installing BIRD
123: <label id="install">
124:
125: <p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make)
126: and Perl, installing BIRD should be as easy as:
127:
128: <code>
129: ./configure
130: make
131: make install
132: vi /usr/local/etc/bird.conf
133: bird
134: </code>
135:
136: <p>You can use <tt>./configure --help</tt> to get a list of configure
137: options. The most important ones are: <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: <p>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 to stderr, and run bird in foreground.
153:
154: <tag><label id="argv-debug-file">-D <m/filename of debug log/</tag>
155: enable debug messages to given file.
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: <p>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: <p>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: <p>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: <p>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>Architecture
221: <label id="architecture">
222:
223: <sect>Routing tables
224: <label id="routing-tables">
225:
226: <p>The heart of BIRD is a routing table. BIRD has several independent routing tables;
227: each of them contains routes of exactly one <m/nettype/ (see below). There are two
228: default tables -- <cf/master4/ for IPv4 routes and <cf/master6/ for IPv6 routes.
229: Other tables must be explicitly configured.
230:
231: <p>
232: These routing tables are not kernel forwarding tables. No forwarding is done by
233: BIRD. If you want to forward packets using the routes in BIRD tables, you may
234: use the Kernel protocol (see below) to synchronize them with kernel FIBs.
235:
236: <p>
237: Every nettype defines a (kind of) primary key on routes. Every route source can
238: supply one route for every possible primary key; new route announcement replaces
239: the old route from the same source, keeping other routes intact. BIRD always
240: chooses the best route for each primary key among the known routes and keeps the
241: others as suboptimal. When the best route is retracted, BIRD re-runs the best
242: route selection algorithm to find the current best route.
243:
244: <p>
245: The global best route selection algorithm is (roughly) as follows:
246:
247: <itemize>
248: <item>Preferences of the routes are compared.
249: <item>Source protocol instance preferences are compared.
250: <item>If source protocols are the same (e.g. BGP vs. BGP), the protocol's route selection algorithm is invoked.
251: <item>If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined.
252: </itemize>
253:
254: <p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected
255: route from a list of entries for one network. But if the <cf/sorted/ option is
256: activated, these lists of entries are kept completely sorted (according to
257: preference or some protocol-dependent metric). This is needed for some features
258: of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to
259: accept not just a selected route, but the first route (in the sorted list) that
260: is accepted by filters), but it is incompatible with some other features (e.g.
261: <cf/deterministic med/ option of BGP protocol, which activates a way of choosing
262: selected route that cannot be described using comparison and ordering). Minor
263: advantage is that routes are shown sorted in <cf/show route/, minor disadvantage
264: is that it is slightly more computationally expensive.
265:
266: <sect>Routes and network types
267: <label id="routes">
268:
269: <p>BIRD works with several types of routes. Some of them are typical IP routes,
270: others are better described as forwarding rules. We call them all routes,
271: regardless of this difference.
272:
273: <p>Every route consists of several attributes (read more about them in the
274: <ref id="route-attributes" name="Route attributes"> section); the common for all
275: routes are:
276:
277: <itemize>
278: <item>IP address of router which told us about this route
279: <item>Source protocol instance
280: <item>Route preference
281: <item>Optional attributes defined by protocols
282: </itemize>
283:
284: <p>Other attributes depend on nettypes. Some of them are part of the primary key, these are marked (PK).
285:
286: <sect1>IPv4 and IPv6 routes
287: <label id="ip-routes">
288:
289: <p>The traditional routes. Configuration keywords are <cf/ipv4/ and <cf/ipv6/.
290:
291: <itemize>
292: <item>(PK) Route destination (IP prefix together with its length)
293: <item>Route next hops (see below)
294: </itemize>
295:
296: <sect1>IPv6 source-specific routes
297: <label id="ip-sadr-routes">
298:
299: <p>The IPv6 routes containing both destination and source prefix. They are used
300: for source-specific routing (SSR), also called source-address dependent routing
301: (SADR), see <rfc id="8043">. Currently limited mostly to the Babel protocol.
302: Configuration keyword is <cf/ipv6 sadr/.
303:
304: <itemize>
305: <item>(PK) Route destination (IP prefix together with its length)
306: <item>(PK) Route source (IP prefix together with its length)
307: <item>Route next hops (see below)
308: </itemize>
309:
310: <sect1>VPN IPv4 and IPv6 routes
311: <label id="vpn-routes">
312:
313: <p>Routes for IPv4 and IPv6 with VPN Route Distinguisher (<rfc id="4364">).
314: Configuration keywords are <cf/vpn4/ and <cf/vpn6/.
315:
316: <itemize>
317: <item>(PK) Route destination (IP prefix together with its length)
318: <item>(PK) Route distinguisher (according to <rfc id="4364">)
319: <item>Route next hops
320: </itemize>
321:
322: <sect1>Route Origin Authorization for IPv4 and IPv6
323: <label id="roa-routes">
324:
325: <p>These entries can be used to validate route origination of BGP routes.
326: A ROA entry specifies prefixes which could be originated by an AS number.
327: Their keywords are <cf/roa4/ and <cf/roa6/.
328:
329: <itemize>
330: <item>(PK) IP prefix together with its length
331: <item>(PK) Matching prefix maximal length
332: <item>(PK) AS number
333: </itemize>
334:
335: <sect1>Flowspec for IPv4 and IPv6
336: <label id="flow-routes">
337:
338: <p>Flowspec rules are a form of firewall and traffic flow control rules
339: distributed mostly via BGP. These rules may help the operators stop various
340: network attacks in the beginning before eating up the whole bandwidth.
341: Configuration keywords are <cf/flow4/ and <cf/flow6/.
342:
343: <itemize>
344: <item>(PK) IP prefix together with its length
345: <item>(PK) Flow definition data
346: <item>Flow action (encoded internally as BGP communities according to <rfc id="5575">)
347: </itemize>
348:
349: <sect1>MPLS switching rules
350: <label id="mpls-routes">
351:
352: <p>This nettype is currently a stub before implementing more support of <rfc id="3031">.
353: BIRD currently does not support any label distribution protocol nor any label assignment method.
354: Only the Kernel, Pipe and Static protocols can use MPLS tables.
355: Configuration keyword is <cf/mpls/.
356:
357: <itemize>
358: <item>(PK) MPLS label
359: <item>Route next hops
360: </itemize>
361:
362: <sect1>Route next hops
363: <label id="route-next-hop">
364:
365: <p>This is not a nettype. The route next hop is a complex attribute common for many
366: nettypes as you can see before. Every next hop has its assigned device
367: (either assumed from its IP address or set explicitly). It may have also
368: an IP address and an MPLS stack (one or both independently).
369: Maximal MPLS stack depth is set (in compile time) to 8 labels.
370:
371: <p>Every route (when eligible to have a next hop) can have more than one next hop.
372: In that case, every next hop has also its weight.
373:
374: <sect>Protocols and channels
375: <label id="protocols-concept">
376:
377: <p>BIRD protocol is an abstract class of producers and consumers of the routes.
378: Each protocol may run in multiple instances and bind on one side to route
379: tables via channels, on the other side to specified listen sockets (BGP),
380: interfaces (Babel, OSPF, RIP), APIs (Kernel, Direct), or nothing (Static, Pipe).
381:
382: <p>There are also two protocols that do not have any channels -- BFD and Device.
383: Both of them are kind of service for other protocols.
384:
385: <p>Each protocol is connected to a routing table through a channel. Some protocols
386: support only one channel (OSPF, RIP), some protocols support more channels (BGP, Direct).
387: Each channel has two filters which can accept, reject and modify the routes.
388: An <it/export/ filter is applied to routes passed from the routing table to the protocol,
389: an <it/import/ filter is applied to routes in the opposite direction.
390:
391: <sect>Graceful restart
392: <label id="graceful-restart">
393:
394: <p>When BIRD is started after restart or crash, it repopulates routing tables in
395: an uncoordinated manner, like after clean start. This may be impractical in some
396: cases, because if the forwarding plane (i.e. kernel routing tables) remains
397: intact, then its synchronization with BIRD would temporarily disrupt packet
398: forwarding until protocols converge. Graceful restart is a mechanism that could
399: help with this issue. Generally, it works by starting protocols and letting them
400: repopulate routing tables while deferring route propagation until protocols
401: acknowledge their convergence. Note that graceful restart behavior have to be
402: configured for all relevant protocols and requires protocol-specific support
403: (currently implemented for Kernel and BGP protocols), it is activated for
404: particular boot by option <cf/-R/.
405:
406: <p>Some protocols (e.g. BGP) could be restarted gracefully after both
407: intentional outage and crash, while others (e.g. OSPF) after intentional outage
408: only. For planned graceful restart, BIRD must be shut down by
409: <ref id="cli-graceful-restart" name="graceful restart"> command instead of
410: regular <ref id="cli-down" name="down"> command. In this way routing neighbors
411: are notified about planned graceful restart and routes are kept in kernel table
412: after shutdown.
413:
414:
415: <chapt>Configuration
416: <label id="config">
417:
418: <sect>Introduction
419: <label id="config-intro">
420:
421: <p>BIRD is configured using a text configuration file. Upon startup, BIRD reads
422: <it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option
423: is given). Configuration may be changed at user's request: if you modify the
424: config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new
425: config. Then there's the client which allows you to talk with BIRD in an
426: extensive way.
427:
428: <p>In the config, everything on a line after <cf/#/ or inside <cf>/* */</cf> is
429: a comment, whitespace characters are treated as a single space. If there's a
430: variable number of options, they are grouped using the <cf/{ }/ brackets. Each
431: option is terminated by a <cf/;/. Configuration is case sensitive. There are two
432: ways how to name symbols (like protocol names, filter names, constants etc.).
433: You can either use a simple string starting with a letter (or underscore)
434: followed by any combination of letters, numbers and underscores (e.g. <cf/R123/,
435: <cf/my_filter/, <cf/bgp5/) or you can enclose the name into apostrophes (<cf/'/)
436: and than you can use any combination of numbers, letters, underscores, hyphens,
437: dots and colons (e.g. <cf/'1:strange-name'/, <cf/'-NAME-'/, <cf/'cool::name'/).
438:
439: <p>Here is an example of a simple config file. It enables synchronization of
440: routing tables with OS kernel, learns network interfaces and runs RIP on all
441: network interfaces found.
442:
443: <code>
444: protocol kernel {
445: ipv4 {
446: export all; # Default is export none
447: };
448: persist; # Don't remove routes on BIRD shutdown
449: }
450:
451: protocol device {
452: }
453:
454: protocol rip {
455: ipv4 {
456: import all;
457: export all;
458: };
459: interface "*";
460: }
461: </code>
462:
463:
464: <sect>Global options
465: <label id="global-opts">
466:
467: <p><descrip>
468: <tag><label id="opt-include">include "<m/filename/";</tag>
469: This statement causes inclusion of a new file. The <m/filename/ could
470: also be a wildcard, in that case matching files are included in
471: alphabetic order. The maximal depth is 8. Note that this statement can
472: be used anywhere in the config file, even inside other options, but
473: always on the beginning of line. In the following example, the first
474: semicolon belongs to the <cf/include/, the second to <cf/ipv6 table/.
475: If the <file/tablename.conf/ contains exactly one token (the name of the
476: table), this construction is correct:
477: <code>
478: ipv6 table
479: include "tablename.conf";;
480: </code>
481:
482: <tag><label id="opt-log">log "<m/filename/" [<m/limit/ "<m/backup/"] | syslog [name <m/name/] | stderr all|{ <m/list of classes/ }</tag>
483: Set logging of messages having the given class (either <cf/all/ or <cf>{
484: error|trace [, <m/.../] }</cf> etc.) into selected destination - a file
485: specified as a filename string (with optional log rotation information),
486: syslog (with optional name argument), or the stderr output.
487:
488: Classes are:
489: <cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
490: <cf/debug/ for debugging messages,
491: <cf/trace/ when you want to know what happens in the network,
492: <cf/remote/ for messages about misbehavior of remote machines,
493: <cf/auth/ about authentication failures,
494: <cf/bug/ for internal BIRD bugs.
495:
496: Logging directly to file supports basic log rotation -- there is an
497: optional log file limit and a backup filename, when log file reaches the
498: limit, the current log file is renamed to the backup filename and a new
499: log file is created.
500:
501: You may specify more than one <cf/log/ line to establish logging to
502: multiple destinations. Default: log everything to the system log, or
503: to the debug output if debugging is enabled by <cf/-d//<cf/-D/
504: command-line option.
505:
506: <tag><label id="opt-debug-protocols">debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
507: Set global defaults of protocol debugging options. See <cf/debug/ in the
508: following section. Default: off.
509:
510: <tag><label id="opt-debug-commands">debug commands <m/number/</tag>
511: Control logging of client connections (0 for no logging, 1 for logging
512: of connects and disconnects, 2 and higher for logging of all client
513: commands). Default: 0.
514:
515: <tag><label id="opt-debug-latency">debug latency <m/switch/</tag>
516: Activate tracking of elapsed time for internal events. Recent events
517: could be examined using <cf/dump events/ command. Default: off.
518:
519: <tag><label id="opt-debug-latency-limit">debug latency limit <m/time/</tag>
520: If <cf/debug latency/ is enabled, this option allows to specify a limit
521: for elapsed time. Events exceeding the limit are logged. Default: 1 s.
522:
523: <tag><label id="opt-watchdog-warn">watchdog warning <m/time/</tag>
524: Set time limit for I/O loop cycle. If one iteration took more time to
525: complete, a warning is logged. Default: 5 s.
526:
527: <tag><label id="opt-watchdog-timeout">watchdog timeout <m/time/</tag>
528: Set time limit for I/O loop cycle. If the limit is breached, BIRD is
529: killed by abort signal. The timeout has effective granularity of
530: seconds, zero means disabled. Default: disabled (0).
531:
532: <tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag>
533: Set MRTdump file name. This option must be specified to allow MRTdump
534: feature. Default: no dump file.
535:
536: <tag><label id="opt-mrtdump-protocols">mrtdump protocols all|off|{ states|messages [, <m/.../] }</tag>
537: Set global defaults of MRTdump options. See <cf/mrtdump/ in the
538: following section. Default: off.
539:
540: <tag><label id="opt-filter">filter <m/name local variables/{ <m/commands/ }</tag>
541: Define a filter. You can learn more about filters in the following
542: chapter.
543:
544: <tag><label id="opt-function">function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
545: Define a function. You can learn more about functions in the following chapter.
546:
547: <tag><label id="opt-protocol">protocol rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
548: Define a protocol instance called <cf><m/name/</cf> (or with a name like
549: "rip5" generated automatically if you don't specify any
550: <cf><m/name/</cf>). You can learn more about configuring protocols in
551: their own chapters. When <cf>from <m/name2/</cf> expression is used,
552: initial protocol options are taken from protocol or template
553: <cf><m/name2/</cf> You can run more than one instance of most protocols
554: (like RIP or BGP). By default, no instances are configured.
555:
556: <tag><label id="opt-template">template rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
557: Define a protocol template instance called <m/name/ (or with a name like
558: "bgp1" generated automatically if you don't specify any <m/name/).
559: Protocol templates can be used to group common options when many
560: similarly configured protocol instances are to be defined. Protocol
561: instances (and other templates) can use templates by using <cf/from/
562: expression and the name of the template. At the moment templates (and
563: <cf/from/ expression) are not implemented for OSPF protocol.
564:
565: <tag><label id="opt-define">define <m/constant/ = <m/expression/</tag>
566: Define a constant. You can use it later in every place you could use a
567: value of the same type. Besides, there are some predefined numeric
568: constants based on /etc/iproute2/rt_* files. A list of defined constants
569: can be seen (together with other symbols) using 'show symbols' command.
570:
571: <tag><label id="opt-attribute">attribute <m/type/ <m/name/</tag>
572: Declare a custom route attribute. You can set and get it in filters like
573: any other route attribute. This feature is intended for marking routes
574: in import filters for export filtering purposes instead of locally
575: assigned BGP communities which have to be deleted in export filters.
576:
577: <tag><label id="opt-router-id">router id <m/IPv4 address/</tag>
578: Set BIRD's router ID. It's a world-wide unique identification of your
579: router, usually one of router's IPv4 addresses. Default: the lowest
580: IPv4 address of a non-loopback interface.
581:
582: <tag><label id="opt-router-id-from">router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../]</tag>
583: Set BIRD's router ID based on an IPv4 address of an interface specified by
584: an interface pattern.
585: See <ref id="proto-iface" name="interface"> section for detailed
586: description of interface patterns with extended clauses.
587:
588: <tag><label id="opt-graceful-restart">graceful restart wait <m/number/</tag>
589: During graceful restart recovery, BIRD waits for convergence of routing
590: protocols. This option allows to specify a timeout for the recovery to
591: prevent waiting indefinitely if some protocols cannot converge. Default:
592: 240 seconds.
593:
594: <tag><label id="opt-timeformat">timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
595: This option allows to specify a format of date/time used by BIRD. The
596: first argument specifies for which purpose such format is used.
597: <cf/route/ is a format used in 'show route' command output,
598: <cf/protocol/ is used in 'show protocols' command output, <cf/base/ is
599: used for other commands and <cf/log/ is used in a log file.
600:
601: "<m/format1/" is a format string using <it/strftime(3)/ notation (see
602: <it/man strftime/ for details). It is extended to support sub-second
603: time part with variable precision (up to microseconds) using "%f"
604: conversion code (e.g., "%T.%3f" is hh:mm:ss.sss time). <m/limit/ and
605: "<m/format2/" allow to specify the second format string for times in
606: past deeper than <m/limit/ seconds.
607:
608: There are several shorthands: <cf/iso long/ is a ISO 8601 date/time
609: format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
610: %T"/. Similarly, <cf/iso long ms/ and <cf/iso long us/ are ISO 8601
611: date/time formats with millisecond or microsecond precision.
612: <cf/iso short/ is a variant of ISO 8601 that uses just the time format
613: (hh:mm:ss) for near times (up to 20 hours in the past) and the date
614: format (YYYY-MM-DD) for far times. This is a shorthand for <cf/"%T"
615: 72000 "%F"/. And there are also <cf/iso short ms/ and <cf/iso short us/
616: high-precision variants of that.
617:
618: By default, BIRD uses the <cf/iso short ms/ format for <cf/route/ and
619: <cf/protocol/ times, and the <cf/iso long ms/ format for <cf/base/ and
620: <cf/log/ times.
621:
622: <tag><label id="opt-table"><m/nettype/ table <m/name/ [sorted]</tag>
623: Create a new routing table. The default routing tables <cf/master4/ and
624: <cf/master6/ are created implicitly, other routing tables have to be
625: added by this command. Option <cf/sorted/ can be used to enable sorting
626: of routes, see <ref id="dsc-table-sorted" name="sorted table">
627: description for details.
628:
629: <tag><label id="opt-eval">eval <m/expr/</tag>
630: Evaluates given filter expression. It is used by the developers for testing of filters.
631: </descrip>
632:
633:
634: <sect>Protocol options
635: <label id="protocol-opts">
636:
637: <p>For each protocol instance, you can configure a bunch of options. Some of
638: them (those described in this section) are generic, some are specific to the
639: protocol (see sections talking about the protocols).
640:
641: <p>Several options use a <m/switch/ argument. It can be either <cf/on/,
642: <cf/yes/ or a numeric expression with a non-zero value for the option to be
643: enabled or <cf/off/, <cf/no/ or a numeric expression evaluating to zero to
644: disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means
645: agreement").
646:
647: <descrip>
648: <tag><label id="proto-disabled">disabled <m/switch/</tag>
649: Disables the protocol. You can change the disable/enable status from the
650: command line interface without needing to touch the configuration.
651: Disabled protocols are not activated. Default: protocol is enabled.
652:
653: <tag><label id="proto-debug">debug all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
654: Set protocol debugging options. If asked, each protocol is capable of
655: writing trace messages about its work to the log (with category
656: <cf/trace/). You can either request printing of <cf/all/ trace messages
657: or only of the types selected: <cf/states/ for protocol state changes
658: (protocol going up, down, starting, stopping etc.), <cf/routes/ for
659: routes exchanged with the routing table, <cf/filters/ for details on
660: route filtering, <cf/interfaces/ for interface change events sent to the
661: protocol, <cf/events/ for events internal to the protocol and <cf/packets/
662: for packets sent and received by the protocol. Default: off.
663:
664: <tag><label id="proto-mrtdump">mrtdump all|off|{ states|messages [, <m/.../] }</tag>
665: Set protocol MRTdump flags. MRTdump is a standard binary format for
666: logging information from routing protocols and daemons. These flags
667: control what kind of information is logged from the protocol to the
668: MRTdump file (which must be specified by global <cf/mrtdump/ option, see
669: the previous section). Although these flags are similar to flags of
670: <cf/debug/ option, their meaning is different and protocol-specific. For
671: BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs
672: received BGP messages. Other protocols does not support MRTdump yet.
673:
674: <tag><label id="proto-router-id">router id <m/IPv4 address/</tag>
675: This option can be used to override global router id for a given
676: protocol. Default: uses global router id.
677:
678: <tag><label id="proto-description">description "<m/text/"</tag>
679: This is an optional description of the protocol. It is displayed as a
680: part of the output of 'show protocols all' command.
681:
682: <tag><label id="proto-vrf">vrf "<m/text/"|default</tag>
683: Associate the protocol with specific VRF. The protocol will be
684: restricted to interfaces assigned to the VRF and will use sockets bound
685: to the VRF. A corresponding VRF interface must exist on OS level. For
686: kernel protocol, an appropriate table still must be explicitly selected
687: by <cf/table/ option.
688:
689: By selecting <cf/default/, the protocol is associated with the default
690: VRF; i.e., it will be restricted to interfaces not assigned to any
691: regular VRF. That is different from not specifying <cf/vrf/ at all, in
692: which case the protocol may use any interface regardless of its VRF
693: status.
694:
695: Note that for proper VRF support it is necessary to use Linux kernel
696: version at least 4.14, older versions have limited VRF implementation.
697: Before Linux kernel 5.0, a socket bound to a port in default VRF collide
698: with others in regular VRFs. In BGP, this can be avoided by using
699: <ref id="bgp-strict-bind" name="strict bind"> option.
700:
701: <tag><label id="proto-channel"><m/channel name/ [{<m/channel config/}]</tag>
702: Every channel must be explicitly stated. See the protocol-specific
703: configuration for the list of supported channel names. See the
704: <ref id="channel-opts" name="channel configuration section"> for channel
705: definition.
706: </descrip>
707:
708: <p>There are several options that give sense only with certain protocols:
709:
710: <descrip>
711: <tag><label id="proto-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../] [ { <m/option/; [<m/.../] } ]</tag>
712: Specifies a set of interfaces on which the protocol is activated with
713: given interface-specific options. A set of interfaces specified by one
714: interface option is described using an interface pattern. The interface
715: pattern consists of a sequence of clauses (separated by commas), each
716: clause is a mask specified as a shell-like pattern. Interfaces are
717: matched by their name.
718:
719: An interface matches the pattern if it matches any of its clauses. If
720: the clause begins with <cf/-/, matching interfaces are excluded. Patterns
721: are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/
722: means eth0 and all non-ethernets.
723:
724: Some protocols (namely OSPFv2 and Direct) support extended clauses that
725: may contain a mask, a prefix, or both of them. An interface matches such
726: clause if its name matches the mask (if specified) and its address
727: matches the prefix (if specified). Extended clauses are used when the
728: protocol handles multiple addresses on an interface independently.
729:
730: An interface option can be used more times with different interface-specific
731: options, in that case for given interface the first matching interface
732: option is used.
733:
734: This option is allowed in Babel, BFD, Device, Direct, OSPF, RAdv and RIP
735: protocols. In OSPF protocol it is used in the <cf/area/ subsection.
736:
737: Default: none.
738:
739: Examples:
740:
741: <cf>interface "*" { type broadcast; };</cf> - start the protocol on all
742: interfaces with <cf>type broadcast</cf> option.
743:
744: <cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the
745: protocol on enumerated interfaces with <cf>type ptp</cf> option.
746:
747: <cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
748: on all interfaces that have address from 192.168.0.0/16, but not from
749: 192.168.1.0/24.
750:
751: <cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
752: ethernet interfaces that have address from 192.168.1.0/24.
753:
754: <tag><label id="proto-tx-class">tx class|dscp <m/num/</tag>
755: This option specifies the value of ToS/DS/Class field in IP headers of
756: the outgoing protocol packets. This may affect how the protocol packets
757: are processed by the network relative to the other network traffic. With
758: <cf/class/ keyword, the value (0-255) is used for the whole ToS/Class
759: octet (but two bits reserved for ECN are ignored). With <cf/dscp/
760: keyword, the value (0-63) is used just for the DS field in the octet.
761: Default value is 0xc0 (DSCP 0x30 - CS6).
762:
763: <tag><label id="proto-tx-priority">tx priority <m/num/</tag>
764: This option specifies the local packet priority. This may affect how the
765: protocol packets are processed in the local TX queues. This option is
766: Linux specific. Default value is 7 (highest priority, privileged traffic).
767:
768: <tag><label id="proto-pass">password "<m/password/" [ { <m>password options</m> } ]</tag>
769: Specifies a password that can be used by the protocol as a shared secret
770: key. Password option can be used more times to specify more passwords.
771: If more passwords are specified, it is a protocol-dependent decision
772: which one is really used. Specifying passwords does not mean that
773: authentication is enabled, authentication can be enabled by separate,
774: protocol-dependent <cf/authentication/ option.
775:
776: This option is allowed in BFD, OSPF and RIP protocols. BGP has also
777: <cf/password/ option, but it is slightly different and described
778: separately.
779: Default: none.
780: </descrip>
781:
782: <p>Password option can contain section with some (not necessary all) password sub-options:
783:
784: <descrip>
785: <tag><label id="proto-pass-id">id <M>num</M></tag>
786: ID of the password, (1-255). If it is not used, BIRD will choose ID based
787: on an order of the password item in the interface. For example, second
788: password item in one interface will have default ID 2. ID is used by
789: some routing protocols to identify which password was used to
790: authenticate protocol packets.
791:
792: <tag><label id="proto-pass-gen-from">generate from "<m/time/"</tag>
793: The start time of the usage of the password for packet signing.
794: The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
795:
796: <tag><label id="proto-pass-gen-to">generate to "<m/time/"</tag>
797: The last time of the usage of the password for packet signing.
798:
799: <tag><label id="proto-pass-accept-from">accept from "<m/time/"</tag>
800: The start time of the usage of the password for packet verification.
801:
802: <tag><label id="proto-pass-accept-to">accept to "<m/time/"</tag>
803: The last time of the usage of the password for packet verification.
804:
805: <tag><label id="proto-pass-from">from "<m/time/"</tag>
806: Shorthand for setting both <cf/generate from/ and <cf/accept from/.
807:
808: <tag><label id="proto-pass-to">to "<m/time/"</tag>
809: Shorthand for setting both <cf/generate to/ and <cf/accept to/.
810:
811: <tag><label id="proto-pass-algorithm">algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 )</tag>
812: The message authentication algorithm for the password when cryptographic
813: authentication is enabled. The default value depends on the protocol.
814: For RIP and OSPFv2 it is Keyed-MD5 (for compatibility), for OSPFv3
815: protocol it is HMAC-SHA-256.
816:
817: </descrip>
818:
819:
820: <sect>Channel options
821: <label id="channel-opts">
822:
823: <p>Every channel belongs to a protocol and is configured inside its block. The
824: minimal channel config is empty, then it uses default values. The name of the
825: channel implies its nettype. Channel definitions can be inherited from protocol
826: templates. Multiple definitions of the same channel are forbidden, but channels
827: inherited from templates can be updated by new definitions.
828:
829: <descrip>
830: <tag><label id="proto-table">table <m/name/</tag>
831: Specify a table to which the channel is connected. Default: the first
832: table of given nettype.
833:
834: <tag><label id="proto-preference">preference <m/expr/</tag>
835: Sets the preference of routes generated by the protocol and imported
836: through this channel. Default: protocol dependent.
837:
838: <tag><label id="proto-import">import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/boolean filter expression/</tag>
839: Specify a filter to be used for filtering routes coming from the
840: protocol to the routing table. <cf/all/ is for keeping all routes,
841: <cf/none/ is for dropping all routes. Default: <cf/all/ (except for
842: EBGP).
843:
844: <tag><label id="proto-export">export <m/filter/</tag>
845: This is similar to the <cf>import</cf> keyword, except that it works in
846: the direction from the routing table to the protocol. Default: <cf/none/
847: (except for EBGP).
848:
849: <tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag>
850: Usually, if an import filter rejects a route, the route is forgotten.
851: When this option is active, these routes are kept in the routing table,
852: but they are hidden and not propagated to other protocols. But it is
853: possible to show them using <cf/show route filtered/. Note that this
854: option does not work for the pipe protocol. Default: off.
855:
856: <tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
857: Specify an import route limit (a maximum number of routes imported from
858: the protocol) and optionally the action to be taken when the limit is
859: hit. Warn action just prints warning log message. Block action discards
860: new routes coming from the protocol. Restart and disable actions shut
861: the protocol down like appropriate commands. Disable is the default
862: action if an action is not explicitly specified. Note that limits are
863: reset during protocol reconfigure, reload or restart. Default: <cf/off/.
864:
865: <tag><label id="proto-receive-limit">receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
866: Specify an receive route limit (a maximum number of routes received from
867: the protocol and remembered). It works almost identically to <cf>import
868: limit</cf> option, the only difference is that if <cf/import keep
869: filtered/ option is active, filtered routes are counted towards the
870: limit and blocked routes are forgotten, as the main purpose of the
871: receive limit is to protect routing tables from overflow. Import limit,
872: on the contrary, counts accepted routes only and routes blocked by the
873: limit are handled like filtered routes. Default: <cf/off/.
874:
875: <tag><label id="proto-export-limit">export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
876: Specify an export route limit, works similarly to the <cf>import
877: limit</cf> option, but for the routes exported to the protocol. This
878: option is experimental, there are some problems in details of its
879: behavior -- the number of exported routes can temporarily exceed the
880: limit without triggering it during protocol reload, exported routes
881: counter ignores route blocking and block action also blocks route
882: updates of already accepted routes -- and these details will probably
883: change in the future. Default: <cf/off/.
884: </descrip>
885:
886: <p>This is a trivial example of RIP configured for IPv6 on all interfaces:
887: <code>
888: protocol rip ng {
889: ipv6;
890: interface "*";
891: }
892: </code>
893:
894: <p>This is a non-trivial example.
895: <code>
896: protocol rip ng {
897: ipv6 {
898: table mytable6;
899: import filter { ... };
900: export filter { ... };
901: import limit 50;
902: };
903: interface "*";
904: }
905: </code>
906:
907: <p>And this is even more complicated example using templates.
908: <code>
909: template bgp {
910: local 198.51.100.14 as 65000;
911:
912: ipv4 {
913: table mytable4;
914: import filter { ... };
915: export none;
916: };
917: ipv6 {
918: table mytable6;
919: import filter { ... };
920: export none;
921: };
922: }
923:
924: protocol bgp from {
925: neighbor 198.51.100.130 as 64496;
926:
927: # IPv4 channel is inherited as-is, while IPv6
928: # channel is adjusted by export filter option
929: ipv6 {
930: export filter { ... };
931: };
932: }
933: </code>
934:
935:
936: <chapt>Remote control
937: <label id="remote-control">
938:
939: <p>You can use the command-line client <file>birdc</file> to talk with a running
940: BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless
941: changed with the <tt/-s/ option given to both the server and the client). The
942: commands can perform simple actions such as enabling/disabling of protocols,
943: telling BIRD to show various information, telling it to show routing table
944: filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to
945: get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
946: client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can
947: be passed to the client, to make it dump numeric return codes along with the
948: messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your
949: own applications could do that, too -- the format of communication between BIRD
950: and <file/birdc/ is stable (see the programmer's documentation).
951:
952: <p>There is also lightweight variant of BIRD client called <file/birdcl/, which
953: does not support command line editing and history and has minimal dependencies.
954: This is useful for running BIRD in resource constrained environments, where
955: Readline library (required for regular BIRD client) is not available.
956:
957: <p>Many commands have the <m/name/ of the protocol instance as an argument.
958: This argument can be omitted if there exists only a single instance.
959:
960: <p>Here is a brief list of supported functions:
961:
962: <descrip>
963: <tag><label id="cli-show-status">show status</tag>
964: Show router status, that is BIRD version, uptime and time from last
965: reconfiguration.
966:
967: <tag><label id="cli-show-interfaces">show interfaces [summary]</tag>
968: Show the list of interfaces. For each interface, print its type, state,
969: MTU and addresses assigned.
970:
971: <tag><label id="cli-show-protocols">show protocols [all]</tag>
972: Show list of protocol instances along with tables they are connected to
973: and protocol status, possibly giving verbose information, if <cf/all/ is
974: specified.
975:
976: <!-- TODO: Move these protocol-specific remote control commands to the protocol sections -->
977: <tag><label id="cli-show-ospf-iface">show ospf interface [<m/name/] ["<m/interface/"]</tag>
978: Show detailed information about OSPF interfaces.
979:
980: <tag><label id="cli-show-ospf-neighbors">show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
981: Show a list of OSPF neighbors and a state of adjacency to them.
982:
983: <tag><label id="cli-show-ospf-state">show ospf state [all] [<m/name/]</tag>
984: Show detailed information about OSPF areas based on a content of the
985: link-state database. It shows network topology, stub networks,
986: aggregated networks and routers from other areas and external routes.
987: The command shows information about reachable network nodes, use option
988: <cf/all/ to show information about all network nodes in the link-state
989: database.
990:
991: <tag><label id="cli-show-ospf-topology">show ospf topology [all] [<m/name/]</tag>
992: Show a topology of OSPF areas based on a content of the link-state
993: database. It is just a stripped-down version of 'show ospf state'.
994:
995: <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>
996: Show contents of an OSPF LSA database. Options could be used to filter
997: entries.
998:
999: <tag><label id="cli-show-rip-interfaces">show rip interfaces [<m/name/] ["<m/interface/"]</tag>
1000: Show detailed information about RIP interfaces.
1001:
1002: <tag><label id="cli-show-rip-neighbors">show rip neighbors [<m/name/] ["<m/interface/"]</tag>
1003: Show a list of RIP neighbors and associated state.
1004:
1005: <tag><label id="cli-show-static">show static [<m/name/]</tag>
1006: Show detailed information about static routes.
1007:
1008: <tag><label id="cli-show-bfd-sessions">show bfd sessions [<m/name/]</tag>
1009: Show information about BFD sessions.
1010:
1011: <tag><label id="cli-show-symbols">show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
1012: Show the list of symbols defined in the configuration (names of
1013: protocols, routing tables etc.).
1014:
1015: <tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table (<m/t/ | all)] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [(stats|count)] [<m/options/]</tag>
1016: Show contents of specified routing tables, that is routes, their metrics
1017: and (in case the <cf/all/ switch is given) all their attributes.
1018:
1019: <p>You can specify a <m/prefix/ if you want to print routes for a
1020: specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
1021: the entry which will be used for forwarding of packets to the given
1022: destination. By default, all routes for each network are printed with
1023: the selected one at the top, unless <cf/primary/ is given in which case
1024: only the selected route is shown.
1025:
1026: <p>The <cf/show route/ command can process one or multiple routing
1027: tables. The set of selected tables is determined on three levels: First,
1028: tables can be explicitly selected by <cf/table/ switch, which could be
1029: used multiple times, all tables are specified by <cf/table all/. Second,
1030: tables can be implicitly selected by channels or protocols that are
1031: arguments of several other switches (e.g., <cf/export/, <cf/protocol/).
1032: Last, the set of default tables is used: <cf/master4/, <cf/master6/ and
1033: each first table of any other network type.
1034:
1035: <p>You can also ask for printing only routes processed and accepted by
1036: a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
1037: </cf> or matching a given condition (<cf>where <m/condition/</cf>).
1038:
1039: The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for
1040: printing of routes that are exported to the specified protocol or
1041: channel. With <cf/preexport/, the export filter of the channel is
1042: skipped. With <cf/noexport/, routes rejected by the export filter are
1043: printed instead. Note that routes not exported for other reasons
1044: (e.g. secondary routes or routes imported from that protocol) are not
1045: printed even with <cf/noexport/. These switches also imply that
1046: associated routing tables are selected instead of default ones.
1047:
1048: <p>You can also select just routes added by a specific protocol.
1049: <cf>protocol <m/p/</cf>. This switch also implies that associated
1050: routing tables are selected instead of default ones.
1051:
1052: <p>If BIRD is configured to keep filtered routes (see <cf/import keep
1053: filtered/ option), you can show them instead of routes by using
1054: <cf/filtered/ switch.
1055:
1056: <p>The <cf/stats/ switch requests showing of route statistics (the
1057: number of networks, number of routes before and after filtering). If
1058: you use <cf/count/ instead, only the statistics will be printed.
1059:
1060: <tag><label id="cli-mrt-dump">mrt dump table <m/name/|"<m/pattern/" to "<m/filename/" [filter <m/f/|where <m/c/]</tag>
1061: Dump content of a routing table to a specified file in MRT table dump
1062: format. See <ref id="mrt" name="MRT protocol"> for details.
1063:
1064: <tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
1065: Reload configuration from a given file. BIRD will smoothly switch itself
1066: to the new configuration, protocols are reconfigured if possible,
1067: restarted otherwise. Changes in filters usually lead to restart of
1068: affected protocols.
1069:
1070: If <cf/soft/ option is used, changes in filters does not cause BIRD to
1071: restart affected protocols, therefore already accepted routes (according
1072: to old filters) would be still propagated, but new routes would be
1073: processed according to the new filters.
1074:
1075: If <cf/timeout/ option is used, config timer is activated. The new
1076: configuration could be either confirmed using <cf/configure confirm/
1077: command, or it will be reverted to the old one when the config timer
1078: expires. This is useful for cases when reconfiguration breaks current
1079: routing and a router becomes inaccessible for an administrator. The
1080: config timeout expiration is equivalent to <cf/configure undo/
1081: command. The timeout duration could be specified, default is 300 s.
1082:
1083: <tag><label id="cli-configure-confirm">configure confirm</tag>
1084: Deactivate the config undo timer and therefore confirm the current
1085: configuration.
1086:
1087: <tag><label id="cli-configure-undo">configure undo</tag>
1088: Undo the last configuration change and smoothly switch back to the
1089: previous (stored) configuration. If the last configuration change was
1090: soft, the undo change is also soft. There is only one level of undo, but
1091: in some specific cases when several reconfiguration requests are given
1092: immediately in a row and the intermediate ones are skipped then the undo
1093: also skips them back.
1094:
1095: <tag><label id="cli-configure-check">configure check ["<m/config file/"]</tag>
1096: Read and parse given config file, but do not use it. useful for checking
1097: syntactic and some semantic validity of an config file.
1098:
1099: <tag><label id="cli-enable-disable-restart">enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
1100: Enable, disable or restart a given protocol instance, instances matching
1101: the <cf><m/pattern/</cf> or <cf/all/ instances.
1102:
1103: <tag><label id="cli-reload">reload [in|out] <m/name/|"<m/pattern/"|all</tag>
1104: Reload a given protocol instance, that means re-import routes from the
1105: protocol instance and re-export preferred routes to the instance. If
1106: <cf/in/ or <cf/out/ options are used, the command is restricted to one
1107: direction (re-import or re-export).
1108:
1109: This command is useful if appropriate filters have changed but the
1110: protocol instance was not restarted (or reloaded), therefore it still
1111: propagates the old set of routes. For example when <cf/configure soft/
1112: command was used to change filters.
1113:
1114: Re-export always succeeds, but re-import is protocol-dependent and might
1115: fail (for example, if BGP neighbor does not support route-refresh
1116: extension). In that case, re-export is also skipped. Note that for the
1117: pipe protocol, both directions are always reloaded together (<cf/in/ or
1118: <cf/out/ options are ignored in that case).
1119:
1120: <tag><label id="cli-down">down</tag>
1121: Shut BIRD down.
1122:
1123: <tag><label id="cli-graceful-restart">graceful restart</tag>
1124: Shut BIRD down for graceful restart. See <ref id="graceful-restart"
1125: name="graceful restart"> section for details.
1126:
1127: <tag><label id="cli-debug">debug <m/protocol/|<m/pattern/|all all|off|{ states|routes|filters|events|packets [, <m/.../] }</tag>
1128: Control protocol debugging.
1129:
1130: <tag><label id="cli-dump">dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
1131: Dump contents of internal data structures to the debugging output.
1132:
1133: <tag><label id="cli-echo">echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
1134: Control echoing of log messages to the command-line output.
1135: See <ref id="opt-log" name="log option"> for a list of log classes.
1136:
1137: <tag><label id="cli-eval">eval <m/expr/</tag>
1138: Evaluate given expression.
1139: </descrip>
1140:
1141:
1142: <chapt>Filters
1143: <label id="filters">
1144:
1145: <sect>Introduction
1146: <label id="filters-intro">
1147:
1148: <p>BIRD contains a simple programming language. (No, it can't yet read mail :-).
1149: There are two objects in this language: filters and functions. Filters are
1150: interpreted by BIRD core when a route is being passed between protocols and
1151: routing tables. The filter language contains control structures such as if's and
1152: switches, but it allows no loops. An example of a filter using many features can
1153: be found in <file>filter/test.conf</file>.
1154:
1155: <p>Filter gets the route, looks at its attributes and modifies some of them if
1156: it wishes. At the end, it decides whether to pass the changed route through
1157: (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks like
1158: this:
1159:
1160: <code>
1161: filter not_too_far
1162: int var;
1163: {
1164: if defined( rip_metric ) then
1165: var = rip_metric;
1166: else {
1167: var = 1;
1168: rip_metric = 1;
1169: }
1170: if rip_metric > 10 then
1171: reject "RIP metric is too big";
1172: else
1173: accept "ok";
1174: }
1175: </code>
1176:
1177: <p>As you can see, a filter has a header, a list of local variables, and a body.
1178: The header consists of the <cf/filter/ keyword followed by a (unique) name of
1179: filter. The list of local variables consists of <cf><M>type name</M>;</cf>
1180: pairs where each pair declares one local variable. The body consists of <cf>
1181: { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You
1182: can group several statements to a single compound statement by using braces
1183: (<cf>{ <M>statements</M> }</cf>) which is useful if you want to make a bigger
1184: block of code conditional.
1185:
1186: <p>BIRD supports functions, so that you don't have to repeat the same blocks of
1187: code over and over. Functions can have zero or more parameters and they can have
1188: local variables. Recursion is not allowed. Function definitions look like this:
1189:
1190: <code>
1191: function name ()
1192: int local_variable;
1193: {
1194: local_variable = 5;
1195: }
1196:
1197: function with_parameters (int parameter)
1198: {
1199: print parameter;
1200: }
1201: </code>
1202:
1203: <p>Unlike in C, variables are declared after the <cf/function/ line, but before
1204: the first <cf/{/. You can't declare variables in nested blocks. Functions are
1205: called like in C: <cf>name(); with_parameters(5);</cf>. Function may return
1206: values using the <cf>return <m/[expr]/</cf> command. Returning a value exits
1207: from current function (this is similar to C).
1208:
1209: <p>Filters are defined in a way similar to functions except they can't have
1210: explicit parameters. They get a route table entry as an implicit parameter, it
1211: is also passed automatically to any functions called. The filter must terminate
1212: with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in
1213: filter, the route is rejected.
1214:
1215: <p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf>
1216: from the command line client. An example session might look like:
1217:
1218: <code>
1219: pavel@bug:~/bird$ ./birdc -s bird.ctl
1220: BIRD 0.0.0 ready.
1221: bird> show route
1222: 10.0.0.0/8 dev eth0 [direct1 23:21] (240)
1223: 195.113.30.2/32 dev tunl1 [direct1 23:21] (240)
1224: 127.0.0.0/8 dev lo [direct1 23:21] (240)
1225: bird> show route ?
1226: show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
1227: bird> show route filter { if 127.0.0.5 ˜ net then accept; }
1228: 127.0.0.0/8 dev lo [direct1 23:21] (240)
1229: bird>
1230: </code>
1231:
1232:
1233: <sect>Data types
1234: <label id="data-types">
1235:
1236: <p>Each variable and each value has certain type. Booleans, integers and enums
1237: are incompatible with each other (that is to prevent you from shooting oneself
1238: in the foot).
1239:
1240: <descrip>
1241: <tag><label id="type-bool">bool</tag>
1242: This is a boolean type, it can have only two values, <cf/true/ and
1243: <cf/false/. Boolean is the only type you can use in <cf/if/ statements.
1244:
1245: <tag><label id="type-int">int</tag>
1246: This is a general integer type. It is an unsigned 32bit type; i.e., you
1247: can expect it to store values from 0 to 4294967295. Overflows are not
1248: checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
1249:
1250: <tag><label id="type-pair">pair</tag>
1251: This is a pair of two short integers. Each component can have values
1252: from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/.
1253: The same syntax can also be used to construct a pair from two arbitrary
1254: integer expressions (for example <cf/(1+2,a)/).
1255:
1256: <tag><label id="type-quad">quad</tag>
1257: This is a dotted quad of numbers used to represent router IDs (and
1258: others). Each component can have a value from 0 to 255. Literals of
1259: this type are written like IPv4 addresses.
1260:
1261: <tag><label id="type-string">string</tag>
1262: This is a string of characters. There are no ways to modify strings in
1263: filters. You can pass them between functions, assign them to variables
1264: of type <cf/string/, print such variables, use standard string
1265: comparison operations (e.g. <cf/=, !=, <, >, <=, >=/), but
1266: you can't concatenate two strings. String literals are written as
1267: <cf/"This is a string constant"/. Additionally matching (<cf/˜,
1268: !˜/) operators could be used to match a string value against
1269: a shell pattern (represented also as a string).
1270:
1271: <tag><label id="type-ip">ip</tag>
1272: This type can hold a single IP address. The IPv4 addresses are stored as
1273: IPv4-Mapped IPv6 addresses so one data type for both of them is used.
1274: Whether the address is IPv4 or not may be checked by <cf>.is_ip4</cf>
1275: which returns a <cf/bool/. IP addresses are written in the standard
1276: notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special
1277: operator <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out
1278: all but first <cf><M>num</M></cf> bits from the IP address. So
1279: <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
1280:
1281: <tag><label id="type-prefix">prefix</tag>
1282: This type can hold a network prefix consisting of IP address, prefix
1283: length and several other values. This is the key in route tables.
1284:
1285: Prefixes may be of several types, which can be determined by the special
1286: operator <cf/.type/. The type may be:
1287:
1288: <cf/NET_IP4/ and <cf/NET_IP6/ prefixes hold an IP prefix. The literals
1289: are written as <cf><m/ipaddress//<m/pxlen/</cf>. There are two special
1290: operators on these: <cf/.ip/ which extracts the IP address from the
1291: pair, and <cf/.len/, which separates prefix length from the pair.
1292: So <cf>1.2.0.0/16.len = 16</cf> is true.
1293:
1294: <cf/NET_IP6_SADR/ nettype holds both destination and source IPv6
1295: prefix. The literals are written as <cf><m/ipaddress//<m/pxlen/ from
1296: <m/ipaddress//<m/pxlen/</cf>, where the first part is the destination
1297: prefix and the second art is the source prefix. They support the same
1298: operators as IP prefixes, but just for the destination part.
1299:
1300: <cf/NET_VPN4/ and <cf/NET_VPN6/ prefixes hold an IP prefix with VPN
1301: Route Distinguisher (<rfc id="4364">). They support the same special
1302: operators as IP prefixes, and also <cf/.rd/ which extracts the Route
1303: Distinguisher. Their literals are written
1304: as <cf><m/vpnrd/ <m/ipprefix/</cf>
1305:
1306: <cf/NET_ROA4/ and <cf/NET_ROA6/ prefixes hold an IP prefix range
1307: together with an ASN. They support the same special operators as IP
1308: prefixes, and also <cf/.maxlen/ which extracts maximal prefix length,
1309: and <cf/.asn/ which extracts the ASN.
1310:
1311: <cf/NET_FLOW4/ and <cf/NET_FLOW6/ hold an IP prefix together with a
1312: flowspec rule. Filters currently don't support flowspec parsing.
1313:
1314: <cf/NET_MPLS/ holds a single MPLS label and its handling is currently
1315: not implemented.
1316:
1317: <tag><label id="type-vpnrd">vpnrd</tag>
1318: This is a route distinguisher according to <rfc id="4364">. There are
1319: three kinds of RD's: <cf><m/asn/:<m/32bit int/</cf>, <cf><m/asn4/:<m/16bit int/</cf>
1320: and <cf><m/IPv4 address/:<m/32bit int/</cf>
1321:
1322: <tag><label id="type-ec">ec</tag>
1323: This is a specialized type used to represent BGP extended community
1324: values. It is essentially a 64bit value, literals of this type are
1325: usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where
1326: <cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a
1327: route target / route origin communities), the format and possible values
1328: of <cf/key/ and <cf/value/ are usually integers, but it depends on the
1329: used kind. Similarly to pairs, ECs can be constructed using expressions
1330: for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
1331: <cf/myas/ is an integer variable).
1332:
1333: <tag><label id="type-lc">lc</tag>
1334: This is a specialized type used to represent BGP large community
1335: values. It is essentially a triplet of 32bit values, where the first
1336: value is reserved for the AS number of the issuer, while meaning of
1337: remaining parts is defined by the issuer. Literals of this type are
1338: written as <cf/(123, 456, 789)/, with any integer values. Similarly to
1339: pairs, LCs can be constructed using expressions for its parts, (e.g.
1340: <cf/(myas, 10+20, 3*10)/, where <cf/myas/ is an integer variable).
1341:
1342: <tag><label id="type-set">int|pair|quad|ip|prefix|ec|lc|enum set</tag>
1343: Filters recognize four types of sets. Sets are similar to strings: you
1344: can pass them around but you can't modify them. Literals of type <cf>int
1345: set</cf> look like <cf> [ 1, 2, 5..7 ]</cf>. As you can see, both simple
1346: values and ranges are permitted in sets.
1347:
1348: For pair sets, expressions like <cf/(123,*)/ can be used to denote
1349: ranges (in that case <cf/(123,0)..(123,65535)/). You can also use
1350: <cf/(123,5..100)/ for range <cf/(123,5)..(123,100)/. You can also use
1351: <cf/*/ and <cf/a..b/ expressions in the first part of a pair, note that
1352: such expressions are translated to a set of intervals, which may be
1353: memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20),
1354: (1,4..20), (2,4..20), ... (65535, 4..20)/.
1355:
1356: EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123,
1357: 10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation
1358: (like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range
1359: for ASNs).
1360:
1361: Also LC sets use similar expressions like pair sets. You can use ranges
1362: and wildcards, but if one field uses that, more specific (later) fields
1363: must be wildcards. E.g., <cf/(10, 20..30, *)/ or <cf/(10, 20, 30..40)/
1364: is valid, while <cf/(10, *, 20..30)/ or <cf/(10, 20..30, 40)/ is not
1365: valid.
1366:
1367: You can also use expressions for int, pair, EC and LC set values.
1368: However, it must be possible to evaluate these expressions before daemon
1369: boots. So you can use only constants inside them. E.g.
1370:
1371: <code>
1372: define one=1;
1373: define myas=64500;
1374: int set odds;
1375: pair set ps;
1376: ec set es;
1377:
1378: odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
1379: ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
1380: es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
1381: </code>
1382:
1383: Sets of prefixes are special: their literals does not allow ranges, but
1384: allows prefix patterns that are written
1385: as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
1386: Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix
1387: pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if the
1388: first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are
1389: identical and <cf>len1 <= ip1 <= len2</cf>. A valid prefix pattern
1390: has to satisfy <cf>low <= high</cf>, but <cf/pxlen/ is not
1391: constrained by <cf/low/ or <cf/high/. Obviously, a prefix matches a
1392: prefix set literal if it matches any prefix pattern in the prefix set
1393: literal.
1394:
1395: There are also two shorthands for prefix patterns: <cf><m/address//<m/len/+</cf>
1396: is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf>
1397: (where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means
1398: network prefix <cf><m/address//<m/len/</cf> and all its subnets.
1399: <cf><m/address//<m/len/-</cf> is a shorthand for
1400: <cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix
1401: <cf><m/address//<m/len/</cf> and all its supernets (network prefixes
1402: that contain it).
1403:
1404: 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}
1405: ]</cf> matches prefix <cf>1.0.0.0/8</cf>, all subprefixes of
1406: <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes
1407: <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf>
1408: matches all prefixes (regardless of IP address) whose prefix length is
1409: 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP
1410: address <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 ˜ [ 1.0.0.0/8{15,17} ]</cf>
1411: is true, but <cf>1.0.0.0/16 ˜ [ 1.0.0.0/8- ]</cf> is false.
1412:
1413: Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
1414: in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as
1415: <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
1416: <cf>192.168.0.0/16{24,32}</cf>.
1417:
1418: It is possible to mix IPv4 and IPv6 prefixes/addresses in a prefix/ip set
1419: but its behavior may change between versions without any warning; don't do
1420: it unless you are more than sure what you are doing. (Really, don't do it.)
1421:
1422: <tag><label id="type-enum">enum</tag>
1423: Enumeration types are fixed sets of possibilities. You can't define your
1424: own variables of such type, but some route attributes are of enumeration
1425: type. Enumeration types are incompatible with each other.
1426:
1427: <tag><label id="type-bgppath">bgppath</tag>
1428: BGP path is a list of autonomous system numbers. You can't write
1429: literals of this type. There are several special operators on bgppaths:
1430:
1431: <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/.
1432:
1433: <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/.
1434:
1435: <cf><m/P/.last_nonaggregated</cf> returns the last ASN in the non-aggregated part of the path <m/P/.
1436:
1437: Both <cf/first/ and <cf/last/ return zero if there is no appropriate
1438: ASN, for example if the path contains an AS set element as the first (or
1439: the last) part. If the path ends with an AS set, <cf/last_nonaggregated/
1440: may be used to get last ASN before any AS set.
1441:
1442: <cf><m/P/.len</cf> returns the length of path <m/P/.
1443:
1444: <cf><m/P/.empty</cf> makes the path <m/P/ empty.
1445:
1446: <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
1447: returns the result.
1448:
1449: <cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from
1450: from path <m/P/ and returns the result. <m/A/ may also be an integer
1451: set, in that case the operator deletes all ASNs from path <m/P/ that are
1452: also members of set <m/A/.
1453:
1454: <cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are
1455: not members of integer set <m/A/. I.e., <cf/filter/ do the same as
1456: <cf/delete/ with inverted set <m/A/.
1457:
1458: Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
1459: <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
1460: (for example <cf/bgp_path/). Similarly for <cf/delete/ and <cf/filter/.
1461:
1462: <tag><label id="type-bgpmask">bgpmask</tag>
1463: BGP masks are patterns used for BGP path matching (using <cf>path
1464: ˜ [= 2 3 5 * =]</cf> syntax). The masks resemble wildcard patterns
1465: as used by UNIX shells. Autonomous system numbers match themselves,
1466: <cf/*/ matches any (even empty) sequence of arbitrary AS numbers and
1467: <cf/?/ matches one arbitrary AS number. For example, if <cf>bgp_path</cf>
1468: is 4 3 2 1, then: <tt>bgp_path ˜ [= * 4 3 * =]</tt> is true,
1469: but <tt>bgp_path ˜ [= * 4 5 * =]</tt> is false. BGP mask
1470: expressions can also contain integer expressions enclosed in parenthesis
1471: and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. You can
1472: also use ranges (e.g. <tt>[= * 3..5 2 100..200 * =]</tt>) and sets
1473: (e.g. <tt>[= 1 2 [3, 5, 7] * =]</tt>).
1474:
1475: <tag><label id="type-clist">clist</tag>
1476: Clist is similar to a set, except that unlike other sets, it can be
1477: modified. The type is used for community list (a set of pairs) and for
1478: cluster list (a set of quads). There exist no literals of this type.
1479: There are three special operators on clists:
1480:
1481: <cf><m/C/.len</cf> returns the length of clist <m/C/.
1482:
1483: <cf><m/C/.empty</cf> makes the list <m/C/ empty.
1484:
1485: <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and
1486: returns the result. If item <m/P/ is already in clist <m/C/, it does
1487: nothing. <m/P/ may also be a clist, in that case all its members are
1488: added; i.e., it works as clist union.
1489:
1490: <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) <m/P/ from clist
1491: <m/C/ and returns the result. If clist <m/C/ does not contain item
1492: <m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that
1493: case the operator deletes all items from clist <m/C/ that are also
1494: members of set <m/P/. Moreover, <m/P/ may also be a clist, which works
1495: analogously; i.e., it works as clist difference.
1496:
1497: <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are
1498: not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same
1499: as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which
1500: works analogously; i.e., it works as clist intersection.
1501:
1502: Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1503: <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute (for
1504: example <cf/bgp_community/). Similarly for <cf/delete/ and <cf/filter/.
1505:
1506: <tag><label id="type-eclist">eclist</tag>
1507: Eclist is a data type used for BGP extended community lists. Eclists
1508: are very similar to clists, but they are sets of ECs instead of pairs.
1509: The same operations (like <cf/add/, <cf/delete/ or <cf/˜/ and
1510: <cf/!˜/ membership operators) can be used to modify or test
1511: eclists, with ECs instead of pairs as arguments.
1512:
1513: <tag><label id="type-lclist">lclist</tag>
1514: Lclist is a data type used for BGP large community lists. Like eclists,
1515: lclists are very similar to clists, but they are sets of LCs instead of
1516: pairs. The same operations (like <cf/add/, <cf/delete/ or <cf/˜/
1517: and <cf/!˜/ membership operators) can be used to modify or test
1518: lclists, with LCs instead of pairs as arguments.
1519: </descrip>
1520:
1521:
1522: <sect>Operators
1523: <label id="operators">
1524:
1525: <p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>,
1526: parentheses <cf/(a*(b+c))/, comparison <cf/(a=b, a!=b, a<b, a>=b)/.
1527: Logical operations include unary not (<cf/!/), and (<cf/&&/), and or
1528: (<cf/||/). Special operators include (<cf/˜/,
1529: <cf/!˜/) for "is (not) element of a set" operation - it can be used on
1530: element and set of elements of the same type (returning true if element is
1531: contained in the given set), or on two strings (returning true if first string
1532: matches a shell-like pattern stored in second string) or on IP and prefix
1533: (returning true if IP is within the range defined by that prefix), or on prefix
1534: and prefix (returning true if first prefix is more specific than second one) or
1535: on bgppath and bgpmask (returning true if the path matches the mask) or on
1536: number and bgppath (returning true if the number is in the path) or on bgppath
1537: and int (number) set (returning true if any ASN from the path is in the set) or
1538: on pair/quad and clist (returning true if the pair/quad is element of the
1539: clist) or on clist and pair/quad set (returning true if there is an element of
1540: the clist that is also a member of the pair/quad set).
1541:
1542: <p>There is one operator related to ROA infrastructure - <cf/roa_check()/. It
1543: examines a ROA table and does <rfc id="6483"> route origin validation for a
1544: given network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which
1545: checks the current route (which should be from BGP to have AS_PATH argument) in
1546: the specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA,
1547: ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant
1548: ROAs but none of them match. There is also an extended variant
1549: <cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a
1550: prefix and an ASN as arguments.
1551:
1552:
1553: <sect>Control structures
1554: <label id="control-structures">
1555:
1556: <p>Filters support two control structures: conditions and case switches.
1557:
1558: <p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/commandT/;
1559: else <m/commandF/;</cf> and you can use <cf>{ <m/command1/; <m/command2/;
1560: <M>...</M> }</cf> instead of either command. The <cf>else</cf> clause may be
1561: omitted. If the <cf><m>boolean expression</m></cf> is true, <m/commandT/ is
1562: executed, otherwise <m/commandF/ is executed.
1563:
1564: <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case
1565: <m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [
1566: ... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be
1567: on the left side of the ˜ operator and anything that could be a member of
1568: a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/
1569: grouping. If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements
1570: between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches
1571: neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed.
1572:
1573: <p>Here is example that uses <cf/if/ and <cf/case/ structures:
1574:
1575: <code>
1576: case arg1 {
1577: 2: print "two"; print "I can do more commands without {}";
1578: 3 .. 5: print "three to five";
1579: else: print "something else";
1580: }
1581:
1582: if 1234 = i then printn "."; else {
1583: print "not 1234";
1584: print "You need {} around multiple commands";
1585: }
1586: </code>
1587:
1588:
1589: <sect>Route attributes
1590: <label id="route-attributes">
1591:
1592: <p>A filter is implicitly passed a route, and it can access its attributes just
1593: like it accesses variables. There are common route attributes, protocol-specific
1594: route attributes and custom route attributes. Most common attributes are
1595: mandatory (always defined), while remaining are optional. Attempts to access
1596: undefined attribute result in a runtime error; you can check if an attribute is
1597: defined by using the <cf>defined( <m>attribute</m> )</cf> operator. One notable
1598: exception to this rule are attributes of bgppath and *clist types, where
1599: undefined value is regarded as empty bgppath/*clist for most purposes.
1600:
1601: Attributes can be defined by just setting them in filters. Custom attributes
1602: have to be first declared by <ref id="opt-attribute" name="attribute"> global
1603: option. You can also undefine optional attribute back to non-existence by using
1604: the <cf>unset( <m/attribute/ )</cf> operator.
1605:
1606: Common route attributes are:
1607:
1608: <descrip>
1609: <tag><label id="rta-net"><m/prefix/ net</tag>
1610: The network prefix or anything else the route is talking about. The
1611: primary key of the routing table. Read-only. (See the <ref id="routes"
1612: name="chapter about routes">.)
1613:
1614: <tag><label id="rta-scope"><m/enum/ scope</tag>
1615: The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes
1616: local to this host, <cf/SCOPE_LINK/ for those specific for a physical
1617: link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and
1618: <cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not
1619: interpreted by BIRD and can be used to mark routes in filters. The
1620: default value for new routes is <cf/SCOPE_UNIVERSE/.
1621:
1622: <tag><label id="rta-preference"><m/int/ preference</tag>
1623: Preference of the route. Valid values are 0-65535. (See the chapter
1624: about routing tables.)
1625:
1626: <tag><label id="rta-from"><m/ip/ from</tag>
1627: The router which the route has originated from.
1628:
1629: <tag><label id="rta-gw"><m/ip/ gw</tag>
1630: Next hop packets routed using this route should be forwarded to.
1631:
1632: <tag><label id="rta-proto"><m/string/ proto</tag>
1633: The name of the protocol which the route has been imported from.
1634: Read-only.
1635:
1636: <tag><label id="rta-source"><m/enum/ source</tag>
1637: what protocol has told me about this route. Possible values:
1638: <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/,
1639: <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/,
1640: <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/,
1641: <cf/RTS_PIPE/, <cf/RTS_BABEL/.
1642:
1643: <tag><label id="rta-dest"><m/enum/ dest</tag>
1644: Type of destination the packets should be sent to
1645: (<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1646: <cf/RTD_DEVICE/ for routing to a directly-connected network,
1647: <cf/RTD_MULTIPATH/ for multipath destinations,
1648: <cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1649: <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be
1650: returned with ICMP host unreachable / ICMP administratively prohibited
1651: messages). Can be changed, but only to <cf/RTD_BLACKHOLE/,
1652: <cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/.
1653:
1654: <tag><label id="rta-ifname"><m/string/ ifname</tag>
1655: Name of the outgoing interface. Sink routes (like blackhole, unreachable
1656: or prohibit) and multipath routes have no interface associated with
1657: them, so <cf/ifname/ returns an empty string for such routes. Setting it
1658: would also change route to a direct one (remove gateway).
1659:
1660: <tag><label id="rta-ifindex"><m/int/ ifindex</tag>
1661: Index of the outgoing interface. System wide index of the interface. May
1662: be used for interface matching, however indexes might change on interface
1663: creation/removal. Zero is returned for routes with undefined outgoing
1664: interfaces. Read-only.
1665:
1666: <tag><label id="rta-igp-metric"><m/int/ igp_metric</tag>
1667: The optional attribute that can be used to specify a distance to the
1668: network for routes that do not have a native protocol metric attribute
1669: (like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to
1670: compare internal distances to boundary routers (see below).
1671: </descrip>
1672:
1673: <p>Protocol-specific route attributes are described in the corresponding
1674: protocol sections.
1675:
1676:
1677: <sect>Other statements
1678: <label id="other-statements">
1679:
1680: <p>The following statements are available:
1681:
1682: <descrip>
1683: <tag><label id="assignment"><m/variable/ = <m/expr/</tag>
1684: Set variable (or route attribute) to a given value.
1685:
1686: <tag><label id="filter-accept-reject">accept|reject [ <m/expr/ ]</tag>
1687: Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
1688:
1689: <tag><label id="return">return <m/expr/</tag>
1690: Return <cf><m>expr</m></cf> from the current function, the function ends
1691: at this point.
1692:
1693: <tag><label id="print">print|printn <m/expr/ [<m/, expr.../]</tag>
1694: Prints given expressions; useful mainly while debugging filters. The
1695: <cf/printn/ variant does not terminate the line.
1696:
1697: <tag><label id="quitbird">quitbird</tag>
1698: Terminates BIRD. Useful when debugging the filter interpreter.
1699: </descrip>
1700:
1701:
1702: <chapt>Protocols
1703: <label id="protocols">
1704:
1705: <sect>Babel
1706: <label id="babel">
1707:
1708: <sect1>Introduction
1709: <label id="babel-intro">
1710:
1711: <p>The Babel protocol
1712: (<rfc id="6126">) is a loop-avoiding distance-vector routing protocol that is
1713: robust and efficient both in ordinary wired networks and in wireless mesh
1714: networks. Babel is conceptually very simple in its operation and "just works"
1715: in its default configuration, though some configuration is possible and in some
1716: cases desirable.
1717:
1718: <p>The Babel protocol is dual stack; i.e., it can carry both IPv4 and IPv6
1719: routes over the same IPv6 transport. For sending and receiving Babel packets,
1720: only a link-local IPv6 address is needed.
1721:
1722: <p>BIRD implements an extension for IPv6 source-specific routing (SSR or SADR),
1723: but must be configured accordingly to use it. SADR-enabled Babel router can
1724: interoperate with non-SADR Babel router, but the later would ignore routes
1725: with specific (non-zero) source prefix.
1726:
1727: <sect1>Configuration
1728: <label id="babel-config">
1729:
1730: <p>The Babel protocol support both IPv4 and IPv6 channels; both can be
1731: configured simultaneously. It can also be configured with <ref
1732: id="ip-sadr-routes" name="IPv6 SADR"> channel instead of regular IPv6
1733: channel, in such case SADR support is enabled. Babel supports no global
1734: configuration options apart from those common to all other protocols, but
1735: supports the following per-interface configuration options:
1736:
1737: <code>
1738: protocol babel [<name>] {
1739: ipv4 { <channel config> };
1740: ipv6 [sadr] { <channel config> };
1741: randomize router id <switch>;
1742: interface <interface pattern> {
1743: type <wired|wireless>;
1744: rxcost <number>;
1745: limit <number>;
1746: hello interval <time>;
1747: update interval <time>;
1748: port <number>;
1749: tx class|dscp <number>;
1750: tx priority <number>;
1751: rx buffer <number>;
1752: tx length <number>;
1753: check link <switch>;
1754: next hop ipv4 <address>;
1755: next hop ipv6 <address>;
1756: };
1757: }
1758: </code>
1759:
1760: <descrip>
1761: <tag><label id="babel-channel">ipv4 | ipv6 [sadr] <m/channel config/</tag>
1762: The supported channels are IPv4, IPv6, and IPv6 SADR.
1763:
1764: <tag><label id="babel-random-router-id">randomize router id <m/switch/</tag>
1765: If enabled, Bird will randomize the top 32 bits of its router ID whenever
1766: the protocol instance starts up. If a Babel node restarts, it loses its
1767: sequence number, which can cause its routes to be rejected by peers until
1768: the state is cleared out by other nodes in the network (which can take on
1769: the order of minutes). Enabling this option causes Bird to pick a random
1770: router ID every time it starts up, which avoids this problem at the cost
1771: of not having stable router IDs in the network. Default: no.
1772:
1773: <tag><label id="babel-type">type wired|wireless </tag>
1774: This option specifies the interface type: Wired or wireless. On wired
1775: interfaces a neighbor is considered unreachable after a small number of
1776: Hello packets are lost, as described by <cf/limit/ option. On wireless
1777: interfaces the ETX link quality estimation technique is used to compute
1778: the metrics of routes discovered over this interface. This technique will
1779: gradually degrade the metric of routes when packets are lost rather than
1780: the more binary up/down mechanism of wired type links. Default:
1781: <cf/wired/.
1782:
1783: <tag><label id="babel-rxcost">rxcost <m/num/</tag>
1784: This option specifies the nominal RX cost of the interface. The effective
1785: neighbor costs for route metrics will be computed from this value with a
1786: mechanism determined by the interface <cf/type/. Note that in contrast to
1787: other routing protocols like RIP or OSPF, the <cf/rxcost/ specifies the
1788: cost of RX instead of TX, so it affects primarily neighbors' route
1789: selection and not local route selection. Default: 96 for wired interfaces,
1790: 256 for wireless.
1791:
1792: <tag><label id="babel-limit">limit <m/num/</tag>
1793: BIRD keeps track of received Hello messages from each neighbor to
1794: establish neighbor reachability. For wired type interfaces, this option
1795: specifies how many of last 16 hellos have to be correctly received in
1796: order to neighbor is assumed to be up. The option is ignored on wireless
1797: type interfaces, where gradual cost degradation is used instead of sharp
1798: limit. Default: 12.
1799:
1800: <tag><label id="babel-hello">hello interval <m/time/ s|ms</tag>
1801: Interval at which periodic Hello messages are sent on this interface,
1802: with time units. Default: 4 seconds.
1803:
1804: <tag><label id="babel-update">update interval <m/time/ s|ms</tag>
1805: Interval at which periodic (full) updates are sent, with time
1806: units. Default: 4 times the hello interval.
1807:
1808: <tag><label id="babel-port">port <m/number/</tag>
1809: This option selects an UDP port to operate on. The default is to operate
1810: on port 6696 as specified in the Babel RFC.
1811:
1812: <tag><label id="babel-tx-class">tx class|dscp|priority <m/number/</tag>
1813: These options specify the ToS/DiffServ/Traffic class/Priority of the
1814: outgoing Babel packets. See <ref id="proto-tx-class" name="tx class"> common
1815: option for detailed description.
1816:
1817: <tag><label id="babel-rx-buffer">rx buffer <m/number/</tag>
1818: This option specifies the size of buffers used for packet processing.
1819: The buffer size should be bigger than maximal size of received packets.
1820: The default value is the interface MTU, and the value will be clamped to a
1821: minimum of 512 bytes + IP packet overhead.
1822:
1823: <tag><label id="babel-tx-length">tx length <m/number/</tag>
1824: This option specifies the maximum length of generated Babel packets. To
1825: avoid IP fragmentation, it should not exceed the interface MTU value.
1826: The default value is the interface MTU value, and the value will be
1827: clamped to a minimum of 512 bytes + IP packet overhead.
1828:
1829: <tag><label id="babel-check-link">check link <m/switch/</tag>
1830: If set, the hardware link state (as reported by OS) is taken into
1831: consideration. When the link disappears (e.g. an ethernet cable is
1832: unplugged), neighbors are immediately considered unreachable and all
1833: routes received from them are withdrawn. It is possible that some
1834: hardware drivers or platforms do not implement this feature. Default:
1835: yes.
1836:
1837: <tag><label id="babel-next-hop-ipv4">next hop ipv4 <m/address/</tag>
1838: Set the next hop address advertised for IPv4 routes advertised on this
1839: interface. Default: the preferred IPv4 address of the interface.
1840:
1841: <tag><label id="babel-next-hop-ipv6">next hop ipv6 <m/address/</tag>
1842: Set the next hop address advertised for IPv6 routes advertised on this
1843: interface. If not set, the same link-local address that is used as the
1844: source for Babel packets will be used. In normal operation, it should not
1845: be necessary to set this option.
1846: </descrip>
1847:
1848: <sect1>Attributes
1849: <label id="babel-attr">
1850:
1851: <p>Babel defines just one attribute: the internal babel metric of the route. It
1852: is exposed as the <cf/babel_metric/ attribute and has range from 1 to infinity
1853: (65535).
1854:
1855: <sect1>Example
1856: <label id="babel-exam">
1857:
1858: <p><code>
1859: protocol babel {
1860: interface "eth*" {
1861: type wired;
1862: };
1863: interface "wlan0", "wlan1" {
1864: type wireless;
1865: hello interval 1;
1866: rxcost 512;
1867: };
1868: interface "tap0";
1869:
1870: # This matches the default of babeld: redistribute all addresses
1871: # configured on local interfaces, plus re-distribute all routes received
1872: # from other babel peers.
1873:
1874: ipv4 {
1875: export where (source = RTS_DEVICE) || (source = RTS_BABEL);
1876: };
1877: ipv6 {
1878: export where (source = RTS_DEVICE) || (source = RTS_BABEL);
1879: };
1880: }
1881: </code>
1882:
1883: <sect1>Known issues
1884: <label id="babel-issues">
1885:
1886: <p>When retracting a route, Babel generates an unreachable route for a little
1887: while (according to RFC). The interaction of this behavior with other protocols
1888: is not well tested and strange things may happen.
1889:
1890:
1891: <sect>BFD
1892: <label id="bfd">
1893:
1894: <sect1>Introduction
1895: <label id="bfd-intro">
1896:
1897: <p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
1898: is an independent tool providing liveness and failure detection. Routing
1899: protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
1900: liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
1901: seconds by default in OSPF, could be set down to several seconds). BFD offers
1902: universal, fast and low-overhead mechanism for failure detection, which could be
1903: attached to any routing protocol in an advisory role.
1904:
1905: <p>BFD consists of mostly independent BFD sessions. Each session monitors an
1906: unicast bidirectional path between two BFD-enabled routers. This is done by
1907: periodically sending control packets in both directions. BFD does not handle
1908: neighbor discovery, BFD sessions are created on demand by request of other
1909: protocols (like OSPF or BGP), which supply appropriate information like IP
1910: addresses and associated interfaces. When a session changes its state, these
1911: protocols are notified and act accordingly (e.g. break an OSPF adjacency when
1912: the BFD session went down).
1913:
1914: <p>BIRD implements basic BFD behavior as defined in <rfc id="5880"> (some
1915: advanced features like the echo mode or authentication are not implemented), IP
1916: transport for BFD as defined in <rfc id="5881"> and <rfc id="5883"> and
1917: interaction with client protocols as defined in <rfc id="5882">.
1918:
1919: <p>BFD packets are sent with a dynamic source port number. Linux systems use by
1920: default a bit different dynamic port range than the IANA approved one
1921: (49152-65535). If you experience problems with compatibility, please adjust
1922: <cf>/proc/sys/net/ipv4/ip_local_port_range</cf>.
1923:
1924: <sect1>Configuration
1925: <label id="bfd-config">
1926:
1927: <p>BFD configuration consists mainly of multiple definitions of interfaces.
1928: Most BFD config options are session specific. When a new session is requested
1929: and dynamically created, it is configured from one of these definitions. For
1930: sessions to directly connected neighbors, <cf/interface/ definitions are chosen
1931: based on the interface associated with the session, while <cf/multihop/
1932: definition is used for multihop sessions. If no definition is relevant, the
1933: session is just created with the default configuration. Therefore, an empty BFD
1934: configuration is often sufficient.
1935:
1936: <p>Note that to use BFD for other protocols like OSPF or BGP, these protocols
1937: also have to be configured to request BFD sessions, usually by <cf/bfd/ option.
1938:
1939: <p>A BFD instance not associated with any VRF handles session requests from all
1940: other protocols, even ones associated with a VRF. Such setup would work for
1941: single-hop BFD sessions if <cf/net.ipv4.udp_l3mdev_accept/ sysctl is enabled,
1942: but does not currently work for multihop sessions. Another approach is to
1943: configure multiple BFD instances, one for each VRF (including the default VRF).
1944: Each BFD instance associated with a VRF (regular or default) only handles
1945: session requests from protocols in the same VRF.
1946:
1947: <p>Some of BFD session options require <m/time/ value, which has to be specified
1948: with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds
1949: are allowed as units, practical minimum values are usually in order of tens of
1950: milliseconds.
1951:
1952: <code>
1953: protocol bfd [<name>] {
1954: interface <interface pattern> {
1955: interval <time>;
1956: min rx interval <time>;
1957: min tx interval <time>;
1958: idle tx interval <time>;
1959: multiplier <num>;
1960: passive <switch>;
1961: authentication none;
1962: authentication simple;
1963: authentication [meticulous] keyed md5|sha1;
1964: password "<text>";
1965: password "<text>" {
1966: id <num>;
1967: generate from "<date>";
1968: generate to "<date>";
1969: accept from "<date>";
1970: accept to "<date>";
1971: from "<date>";
1972: to "<date>";
1973: };
1974: };
1975: multihop {
1976: interval <time>;
1977: min rx interval <time>;
1978: min tx interval <time>;
1979: idle tx interval <time>;
1980: multiplier <num>;
1981: passive <switch>;
1982: };
1983: neighbor <ip> [dev "<interface>"] [local <ip>] [multihop <switch>];
1984: }
1985: </code>
1986:
1987: <descrip>
1988: <tag><label id="bfd-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
1989: Interface definitions allow to specify options for sessions associated
1990: with such interfaces and also may contain interface specific options.
1991: See <ref id="proto-iface" name="interface"> common option for a detailed
1992: description of interface patterns. Note that contrary to the behavior of
1993: <cf/interface/ definitions of other protocols, BFD protocol would accept
1994: sessions (in default configuration) even on interfaces not covered by
1995: such definitions.
1996:
1997: <tag><label id="bfd-multihop">multihop { <m/options/ }</tag>
1998: Multihop definitions allow to specify options for multihop BFD sessions,
1999: in the same manner as <cf/interface/ definitions are used for directly
2000: connected sessions. Currently only one such definition (for all multihop
2001: sessions) could be used.
2002:
2003: <tag><label id="bfd-neighbor">neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>
2004: BFD sessions are usually created on demand as requested by other
2005: protocols (like OSPF or BGP). This option allows to explicitly add
2006: a BFD session to the specified neighbor regardless of such requests.
2007:
2008: The session is identified by the IP address of the neighbor, with
2009: optional specification of used interface and local IP. By default
2010: the neighbor must be directly connected, unless the session is
2011: configured as multihop. Note that local IP must be specified for
2012: multihop sessions.
2013: </descrip>
2014:
2015: <p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):
2016:
2017: <descrip>
2018: <tag><label id="bfd-interval">interval <m/time/</tag>
2019: BFD ensures availability of the forwarding path associated with the
2020: session by periodically sending BFD control packets in both
2021: directions. The rate of such packets is controlled by two options,
2022: <cf/min rx interval/ and <cf/min tx interval/ (see below). This option
2023: is just a shorthand to set both of these options together.
2024:
2025: <tag><label id="bfd-min-rx-interval">min rx interval <m/time/</tag>
2026: This option specifies the minimum RX interval, which is announced to the
2027: neighbor and used there to limit the neighbor's rate of generated BFD
2028: control packets. Default: 10 ms.
2029:
2030: <tag><label id="bfd-min-tx-interval">min tx interval <m/time/</tag>
2031: This option specifies the desired TX interval, which controls the rate
2032: of generated BFD control packets (together with <cf/min rx interval/
2033: announced by the neighbor). Note that this value is used only if the BFD
2034: session is up, otherwise the value of <cf/idle tx interval/ is used
2035: instead. Default: 100 ms.
2036:
2037: <tag><label id="bfd-idle-tx-interval">idle tx interval <m/time/</tag>
2038: In order to limit unnecessary traffic in cases where a neighbor is not
2039: available or not running BFD, the rate of generated BFD control packets
2040: is lower when the BFD session is not up. This option specifies the
2041: desired TX interval in such cases instead of <cf/min tx interval/.
2042: Default: 1 s.
2043:
2044: <tag><label id="bfd-multiplier">multiplier <m/num/</tag>
2045: Failure detection time for BFD sessions is based on established rate of
2046: BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this
2047: multiplier, which is essentially (ignoring jitter) a number of missed
2048: packets after which the session is declared down. Note that rates and
2049: multipliers could be different in each direction of a BFD session.
2050: Default: 5.
2051:
2052: <tag><label id="bfd-passive">passive <m/switch/</tag>
2053: Generally, both BFD session endpoints try to establish the session by
2054: sending control packets to the other side. This option allows to enable
2055: passive mode, which means that the router does not send BFD packets
2056: until it has received one from the other side. Default: disabled.
2057:
2058: <tag>authentication none</tag>
2059: No passwords are sent in BFD packets. This is the default value.
2060:
2061: <tag>authentication simple</tag>
2062: Every packet carries 16 bytes of password. Received packets lacking this
2063: password are ignored. This authentication mechanism is very weak.
2064:
2065: <tag>authentication [meticulous] keyed md5|sha1</tag>
2066: An authentication code is appended to each packet. The cryptographic
2067: algorithm is keyed MD5 or keyed SHA-1. Note that the algorithm is common
2068: for all keys (on one interface), in contrast to OSPF or RIP, where it
2069: is a per-key option. Passwords (keys) are not sent open via network.
2070:
2071: The <cf/meticulous/ variant means that cryptographic sequence numbers
2072: are increased for each sent packet, while in the basic variant they are
2073: increased about once per second. Generally, the <cf/meticulous/ variant
2074: offers better resistance to replay attacks but may require more
2075: computation.
2076:
2077: <tag>password "<M>text</M>"</tag>
2078: Specifies a password used for authentication. See <ref id="proto-pass"
2079: name="password"> common option for detailed description. Note that
2080: password option <cf/algorithm/ is not available in BFD protocol. The
2081: algorithm is selected by <cf/authentication/ option for all passwords.
2082:
2083: </descrip>
2084:
2085: <sect1>Example
2086: <label id="bfd-exam">
2087:
2088: <p><code>
2089: protocol bfd {
2090: interface "eth*" {
2091: min rx interval 20 ms;
2092: min tx interval 50 ms;
2093: idle tx interval 300 ms;
2094: };
2095: interface "gre*" {
2096: interval 200 ms;
2097: multiplier 10;
2098: passive;
2099: };
2100: multihop {
2101: interval 200 ms;
2102: multiplier 10;
2103: };
2104:
2105: neighbor 192.168.1.10;
2106: neighbor 192.168.2.2 dev "eth2";
2107: neighbor 192.168.10.1 local 192.168.1.1 multihop;
2108: }
2109: </code>
2110:
2111:
2112: <sect>BGP
2113: <label id="bgp">
2114:
2115: <p>The Border Gateway Protocol is the routing protocol used for backbone level
2116: routing in the today's Internet. Contrary to other protocols, its convergence
2117: does not rely on all routers following the same rules for route selection,
2118: making it possible to implement any routing policy at any router in the network,
2119: the only restriction being that if a router advertises a route, it must accept
2120: and forward packets according to it.
2121:
2122: <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each AS
2123: is a part of the network with common management and common routing policy. It is
2124: identified by a unique 16-bit number (ASN). Routers within each AS usually
2125: exchange AS-internal routing information with each other using an interior
2126: gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of
2127: the AS communicate global (inter-AS) network reachability information with their
2128: neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute
2129: received information to other routers in the AS via interior BGP (iBGP).
2130:
2131: <p>Each BGP router sends to its neighbors updates of the parts of its routing
2132: table it wishes to export along with complete path information (a list of AS'es
2133: the packet will travel through if it uses the particular route) in order to
2134: avoid routing loops.
2135:
2136: <sect1>Supported standards
2137: <label id="bgp-standards">
2138:
2139: <p>
2140: <itemize>
2141: <item> <rfc id="4271"> - Border Gateway Protocol 4 (BGP)
2142: <item> <rfc id="1997"> - BGP Communities Attribute
2143: <item> <rfc id="2385"> - Protection of BGP Sessions via TCP MD5 Signature
2144: <item> <rfc id="2545"> - Use of BGP Multiprotocol Extensions for IPv6
2145: <item> <rfc id="2918"> - Route Refresh Capability
2146: <item> <rfc id="3107"> - Carrying Label Information in BGP
2147: <item> <rfc id="4360"> - BGP Extended Communities Attribute
2148: <item> <rfc id="4364"> - BGP/MPLS IPv4 Virtual Private Networks
2149: <item> <rfc id="4456"> - BGP Route Reflection
2150: <item> <rfc id="4486"> - Subcodes for BGP Cease Notification Message
2151: <item> <rfc id="4659"> - BGP/MPLS IPv6 Virtual Private Networks
2152: <item> <rfc id="4724"> - Graceful Restart Mechanism for BGP
2153: <item> <rfc id="4760"> - Multiprotocol extensions for BGP
2154: <item> <rfc id="4798"> - Connecting IPv6 Islands over IPv4 MPLS
2155: <item> <rfc id="5065"> - AS confederations for BGP
2156: <item> <rfc id="5082"> - Generalized TTL Security Mechanism
2157: <item> <rfc id="5492"> - Capabilities Advertisement with BGP
2158: <item> <rfc id="5549"> - Advertising IPv4 NLRI with an IPv6 Next Hop
2159: <item> <rfc id="5575"> - Dissemination of Flow Specification Rules
2160: <item> <rfc id="5668"> - 4-Octet AS Specific BGP Extended Community
2161: <item> <rfc id="6286"> - AS-Wide Unique BGP Identifier
2162: <item> <rfc id="6608"> - Subcodes for BGP Finite State Machine Error
2163: <item> <rfc id="6793"> - BGP Support for 4-Octet AS Numbers
2164: <item> <rfc id="7311"> - Accumulated IGP Metric Attribute for BGP
2165: <item> <rfc id="7313"> - Enhanced Route Refresh Capability for BGP
2166: <item> <rfc id="7606"> - Revised Error Handling for BGP UPDATE Messages
2167: <item> <rfc id="7911"> - Advertisement of Multiple Paths in BGP
2168: <item> <rfc id="7947"> - Internet Exchange BGP Route Server
2169: <item> <rfc id="8092"> - BGP Large Communities Attribute
2170: <item> <rfc id="8203"> - BGP Administrative Shutdown Communication
2171: <item> <rfc id="8212"> - Default EBGP Route Propagation Behavior without Policies
2172: </itemize>
2173:
2174: <sect1>Route selection rules
2175: <label id="bgp-route-select-rules">
2176:
2177: <p>BGP doesn't have any simple metric, so the rules for selection of an optimal
2178: route among multiple BGP routes with the same preference are a bit more complex
2179: and they are implemented according to the following algorithm. It starts the
2180: first rule, if there are more "best" routes, then it uses the second rule to
2181: choose among them and so on.
2182:
2183: <itemize>
2184: <item>Prefer route with the highest Local Preference attribute.
2185: <item>Prefer route with the shortest AS path.
2186: <item>Prefer IGP origin over EGP and EGP origin over incomplete.
2187: <item>Prefer the lowest value of the Multiple Exit Discriminator.
2188: <item>Prefer routes received via eBGP over ones received via iBGP.
2189: <item>Prefer routes with lower internal distance to a boundary router.
2190: <item>Prefer the route with the lowest value of router ID of the
2191: advertising router.
2192: </itemize>
2193:
2194: <sect1>IGP routing table
2195: <label id="bgp-igp-routing-table">
2196:
2197: <p>BGP is mainly concerned with global network reachability and with routes to
2198: other autonomous systems. When such routes are redistributed to routers in the
2199: AS via BGP, they contain IP addresses of a boundary routers (in route attribute
2200: NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to
2201: determine immediate next hops for routes and to know their internal distances to
2202: boundary routers for the purpose of BGP route selection. In BIRD, there is
2203: usually one routing table used for both IGP routes and BGP routes.
2204:
2205: <sect1>Protocol configuration
2206: <label id="bgp-proto-config">
2207:
2208: <p>Each instance of the BGP corresponds to one neighboring router. This allows
2209: to set routing policy and all the other parameters differently for each neighbor
2210: using the following configuration parameters:
2211:
2212: <descrip>
2213: <tag><label id="bgp-local">local [<m/ip/] [port <m/number/] [as <m/number/]</tag>
2214: Define which AS we are part of. (Note that contrary to other IP routers,
2215: BIRD is able to act as a router located in multiple AS'es simultaneously,
2216: but in such cases you need to tweak the BGP paths manually in the filters
2217: to get consistent behavior.) Optional <cf/ip/ argument specifies a source
2218: address, equivalent to the <cf/source address/ option (see below).
2219: Optional <cf/port/ argument specifies the local BGP port instead of
2220: standard port 179. The parameter may be used multiple times with
2221: different sub-options (e.g., both <cf/local 10.0.0.1 as 65000;/ and
2222: <cf/local 10.0.0.1; local as 65000;/ are valid). This parameter is
2223: mandatory.
2224:
2225: <tag><label id="bgp-neighbor">neighbor [<m/ip/ | range <m/prefix/] [port <m/number/] [as <m/number/] [internal|external]</tag>
2226: Define neighboring router this instance will be talking to and what AS
2227: it is located in. In case the neighbor is in the same AS as we are, we
2228: automatically switch to IBGP. Alternatively, it is possible to specify
2229: just <cf/internal/ or <cf/external/ instead of AS number, in that case
2230: either local AS number, or any external AS number is accepted.
2231: Optionally, the remote port may also be specified. Like <cf/local/
2232: parameter, this parameter may also be used multiple times with different
2233: sub-options. This parameter is mandatory.
2234:
2235: It is possible to specify network prefix (with <cf/range/ keyword)
2236: instead of explicit neighbor IP address. This enables dynamic BGP
2237: behavior, where the BGP instance listens on BGP port, but new BGP
2238: instances are spawned for incoming BGP connections (if source address
2239: matches the network prefix). It is possible to mix regular BGP instances
2240: with dynamic BGP instances and have multiple dynamic BGP instances with
2241: different ranges.
2242:
2243: <tag><label id="bgp-iface">interface <m/string/</tag>
2244: Define interface we should use for link-local BGP IPv6 sessions.
2245: Interface can also be specified as a part of <cf/neighbor address/
2246: (e.g., <cf/neighbor fe80::1234%eth0 as 65000;/). The option may also be
2247: used for non link-local sessions when it is necessary to explicitly
2248: specify an interface, but only for direct (not multihop) sessions.
2249:
2250: <tag><label id="bgp-direct">direct</tag>
2251: Specify that the neighbor is directly connected. The IP address of the
2252: neighbor must be from a directly reachable IP range (i.e. associated
2253: with one of your router's interfaces), otherwise the BGP session
2254: wouldn't start but it would wait for such interface to appear. The
2255: alternative is the <cf/multihop/ option. Default: enabled for eBGP.
2256:
2257: <tag><label id="bgp-multihop">multihop [<m/number/]</tag>
2258: Configure multihop BGP session to a neighbor that isn't directly
2259: connected. Accurately, this option should be used if the configured
2260: neighbor IP address does not match with any local network subnets. Such
2261: IP address have to be reachable through system routing table. The
2262: alternative is the <cf/direct/ option. For multihop BGP it is
2263: recommended to explicitly configure the source address to have it
2264: stable. Optional <cf/number/ argument can be used to specify the number
2265: of hops (used for TTL). Note that the number of networks (edges) in a
2266: path is counted; i.e., if two BGP speakers are separated by one router,
2267: the number of hops is 2. Default: enabled for iBGP.
2268:
2269: <tag><label id="bgp-source-address">source address <m/ip/</tag>
2270: Define local address we should use as a source address for the BGP
2271: session. Default: the address of the local end of the interface our
2272: neighbor is connected to.
2273:
2274: <tag><label id="bgp-dynamic-name">dynamic name "<m/text/"</tag>
2275: Define common prefix of names used for new BGP instances spawned when
2276: dynamic BGP behavior is active. Actual names also contain numeric
2277: index to distinguish individual instances. Default: "dynbgp".
2278:
2279: <tag><label id="bgp-dynamic-name-digits">dynamic name digits <m/number/</tag>
2280: Define minimum number of digits for index in names of spawned dynamic
2281: BGP instances. E.g., if set to 2, then the first name would be
2282: "dynbgp01". Default: 0.
2283:
2284: <tag><label id="bgp-strict-bind">strict bind <m/switch/</tag>
2285: Specify whether BGP listening socket should be bound to a specific local
2286: address (the same as the <cf/source address/) and associated interface,
2287: or to all addresses. Binding to a specific address could be useful in
2288: cases like running multiple BIRD instances on a machine, each using its
2289: IP address. Note that listening sockets bound to a specific address and
2290: to all addresses collide, therefore either all BGP protocols (of the
2291: same address family and using the same local port) should have set
2292: <cf/strict bind/, or none of them. Default: disabled.
2293:
2294: <tag><label id="bgp-check-link">check link <M>switch</M></tag>
2295: BGP could use hardware link state into consideration. If enabled,
2296: BIRD tracks the link state of the associated interface and when link
2297: disappears (e.g. an ethernet cable is unplugged), the BGP session is
2298: immediately shut down. Note that this option cannot be used with
2299: multihop BGP. Default: enabled for direct BGP, disabled otherwise.
2300:
2301: <tag><label id="bgp-bfd">bfd <M>switch</M>|graceful</tag>
2302: BGP could use BFD protocol as an advisory mechanism for neighbor
2303: liveness and failure detection. If enabled, BIRD setups a BFD session
2304: for the BGP neighbor and tracks its liveness by it. This has an
2305: advantage of an order of magnitude lower detection times in case of
2306: failure. When a neighbor failure is detected, the BGP session is
2307: restarted. Optionally, it can be configured (by <cf/graceful/ argument)
2308: to trigger graceful restart instead of regular restart. Note that BFD
2309: protocol also has to be configured, see <ref id="bfd" name="BFD">
2310: section for details. Default: disabled.
2311:
2312: <tag><label id="bgp-ttl-security">ttl security <m/switch/</tag>
2313: Use GTSM (<rfc id="5082"> - the generalized TTL security mechanism). GTSM
2314: protects against spoofed packets by ignoring received packets with a
2315: smaller than expected TTL. To work properly, GTSM have to be enabled on
2316: both sides of a BGP session. If both <cf/ttl security/ and
2317: <cf/multihop/ options are enabled, <cf/multihop/ option should specify
2318: proper hop value to compute expected TTL. Kernel support required:
2319: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only.
2320: Note that full (ICMP protection, for example) <rfc id="5082"> support is
2321: provided by Linux only. Default: disabled.
2322:
2323: <tag><label id="bgp-password">password <m/string/</tag>
2324: Use this password for MD5 authentication of BGP sessions (<rfc id="2385">). When
2325: used on BSD systems, see also <cf/setkey/ option below. Default: no
2326: authentication.
2327:
2328: <tag><label id="bgp-setkey">setkey <m/switch/</tag>
2329: On BSD systems, keys for TCP MD5 authentication are stored in the global
2330: SA/SP database, which can be accessed by external utilities (e.g.
2331: setkey(8)). BIRD configures security associations in the SA/SP database
2332: automatically based on <cf/password/ options (see above), this option
2333: allows to disable automatic updates by BIRD when manual configuration by
2334: external utilities is preferred. Note that automatic SA/SP database
2335: updates are currently implemented only for FreeBSD. Passwords have to be
2336: set manually by an external utility on NetBSD and OpenBSD. Default:
2337: enabled (ignored on non-FreeBSD).
2338:
2339: <tag><label id="bgp-passive">passive <m/switch/</tag>
2340: Standard BGP behavior is both initiating outgoing connections and
2341: accepting incoming connections. In passive mode, outgoing connections
2342: are not initiated. Default: off.
2343:
2344: <tag><label id="bgp-confederation">confederation <m/number/</tag>
2345: BGP confederations (<rfc id="5065">) are collections of autonomous
2346: systems that act as one entity to external systems, represented by one
2347: confederation identifier (instead of AS numbers). This option allows to
2348: enable BGP confederation behavior and to specify the local confederation
2349: identifier. When BGP confederations are used, all BGP speakers that are
2350: members of the BGP confederation should have the same confederation
2351: identifier configured. Default: 0 (no confederation).
2352:
2353: <tag><label id="bgp-confederation-member">confederation member <m/switch/</tag>
2354: When BGP confederations are used, this option allows to specify whether
2355: the BGP neighbor is a member of the same confederation as the local BGP
2356: speaker. The option is unnecessary (and ignored) for IBGP sessions, as
2357: the same AS number implies the same confederation. Default: no.
2358:
2359: <tag><label id="bgp-rr-client">rr client</tag>
2360: Be a route reflector and treat the neighbor as a route reflection
2361: client. Default: disabled.
2362:
2363: <tag><label id="bgp-rr-cluster-id">rr cluster id <m/IPv4 address/</tag>
2364: Route reflectors use cluster id to avoid route reflection loops. When
2365: there is one route reflector in a cluster it usually uses its router id
2366: as a cluster id, but when there are more route reflectors in a cluster,
2367: these need to be configured (using this option) to use a common cluster
2368: id. Clients in a cluster need not know their cluster id and this option
2369: is not allowed for them. Default: the same as router id.
2370:
2371: <tag><label id="bgp-rs-client">rs client</tag>
2372: Be a route server and treat the neighbor as a route server client.
2373: A route server is used as a replacement for full mesh EBGP routing in
2374: Internet exchange points in a similar way to route reflectors used in
2375: IBGP routing. BIRD does not implement obsoleted <rfc id="1863">, but
2376: uses ad-hoc implementation, which behaves like plain EBGP but reduces
2377: modifications to advertised route attributes to be transparent (for
2378: example does not prepend its AS number to AS PATH attribute and
2379: keeps MED attribute). Default: disabled.
2380:
2381: <tag><label id="bgp-allow-local-pref">allow bgp_local_pref <m/switch/</tag>
2382: A standard BGP implementation do not send the Local Preference attribute
2383: to eBGP neighbors and ignore this attribute if received from eBGP
2384: neighbors, as per <rfc id="4271">. When this option is enabled on an
2385: eBGP session, this attribute will be sent to and accepted from the peer,
2386: which is useful for example if you have a setup like in <rfc id="7938">.
2387: The option does not affect iBGP sessions. Default: off.
2388:
2389: <tag><label id="bgp-allow-local-as">allow local as [<m/number/]</tag>
2390: BGP prevents routing loops by rejecting received routes with the local
2391: AS number in the AS path. This option allows to loose or disable the
2392: check. Optional <cf/number/ argument can be used to specify the maximum
2393: number of local ASNs in the AS path that is allowed for received
2394: routes. When the option is used without the argument, the check is
2395: completely disabled and you should ensure loop-free behavior by some
2396: other means. Default: 0 (no local AS number allowed).
2397:
2398: <tag><label id="bgp-enable-route-refresh">enable route refresh <m/switch/</tag>
2399: After the initial route exchange, BGP protocol uses incremental updates
2400: to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker
2401: changes its import filter, or if there is suspicion of inconsistency) it
2402: is necessary to do a new complete route exchange. BGP protocol extension
2403: Route Refresh (<rfc id="2918">) allows BGP speaker to request
2404: re-advertisement of all routes from its neighbor. BGP protocol
2405: extension Enhanced Route Refresh (<rfc id="7313">) specifies explicit
2406: begin and end for such exchanges, therefore the receiver can remove
2407: stale routes that were not advertised during the exchange. This option
2408: specifies whether BIRD advertises these capabilities and supports
2409: related procedures. Note that even when disabled, BIRD can send route
2410: refresh requests. Default: on.
2411:
2412: <tag><label id="bgp-graceful-restart">graceful restart <m/switch/|aware</tag>
2413: When a BGP speaker restarts or crashes, neighbors will discard all
2414: received paths from the speaker, which disrupts packet forwarding even
2415: when the forwarding plane of the speaker remains intact. <rfc id="4724">
2416: specifies an optional graceful restart mechanism to alleviate this
2417: issue. This option controls the mechanism. It has three states:
2418: Disabled, when no support is provided. Aware, when the graceful restart
2419: support is announced and the support for restarting neighbors is
2420: provided, but no local graceful restart is allowed (i.e. receiving-only
2421: role). Enabled, when the full graceful restart support is provided
2422: (i.e. both restarting and receiving role). Restarting role could be also
2423: configured per-channel. Note that proper support for local graceful
2424: restart requires also configuration of other protocols. Default: aware.
2425:
2426: <tag><label id="bgp-graceful-restart-time">graceful restart time <m/number/</tag>
2427: The restart time is announced in the BGP graceful restart capability
2428: and specifies how long the neighbor would wait for the BGP session to
2429: re-establish after a restart before deleting stale routes. Default:
2430: 120 seconds.
2431:
2432: <tag><label id="bgp-long-lived-graceful-restart">long lived graceful restart <m/switch/|aware</tag>
2433: The long-lived graceful restart is an extension of the traditional
2434: <ref id="bgp-graceful-restart" name="BGP graceful restart">, where stale
2435: routes are kept even after the <ref id="bgp-graceful-restart-time"
2436: name="restart time"> expires for additional long-lived stale time, but
2437: they are marked with the LLGR_STALE community, depreferenced, and
2438: withdrawn from routers not supporting LLGR. Like traditional BGP
2439: graceful restart, it has three states: disabled, aware (receiving-only),
2440: and enabled. Note that long-lived graceful restart requires at least
2441: aware level of traditional BGP graceful restart. Default: aware, unless
2442: graceful restart is disabled.
2443:
2444: <tag><label id="bgp-long-lived-stale-time">long lived stale time <m/number/</tag>
2445: The long-lived stale time is announced in the BGP long-lived graceful
2446: restart capability and specifies how long the neighbor would keep stale
2447: routes depreferenced during long-lived graceful restart until either the
2448: session is re-stablished and synchronized or the stale time expires and
2449: routes are removed. Default: 3600 seconds.
2450:
2451: <tag><label id="bgp-interpret-communities">interpret communities <m/switch/</tag>
2452: <rfc id="1997"> demands that BGP speaker should process well-known
2453: communities like no-export (65535, 65281) or no-advertise (65535,
2454: 65282). For example, received route carrying a no-adverise community
2455: should not be advertised to any of its neighbors. If this option is
2456: enabled (which is by default), BIRD has such behavior automatically (it
2457: is evaluated when a route is exported to the BGP protocol just before
2458: the export filter). Otherwise, this integrated processing of
2459: well-known communities is disabled. In that case, similar behavior can
2460: be implemented in the export filter. Default: on.
2461:
2462: <tag><label id="bgp-enable-as4">enable as4 <m/switch/</tag>
2463: BGP protocol was designed to use 2B AS numbers and was extended later to
2464: allow 4B AS number. BIRD supports 4B AS extension, but by disabling this
2465: option it can be persuaded not to advertise it and to maintain old-style
2466: sessions with its neighbors. This might be useful for circumventing bugs
2467: in neighbor's implementation of 4B AS extension. Even when disabled
2468: (off), BIRD behaves internally as AS4-aware BGP router. Default: on.
2469:
2470: <tag><label id="bgp-enable-extended-messages">enable extended messages <m/switch/</tag>
2471: The BGP protocol uses maximum message length of 4096 bytes. This option
2472: provides an extension to allow extended messages with length up
2473: to 65535 bytes. Default: off.
2474:
2475: <tag><label id="bgp-capabilities">capabilities <m/switch/</tag>
2476: Use capability advertisement to advertise optional capabilities. This is
2477: standard behavior for newer BGP implementations, but there might be some
2478: older BGP implementations that reject such connection attempts. When
2479: disabled (off), features that request it (4B AS support) are also
2480: disabled. Default: on, with automatic fallback to off when received
2481: capability-related error.
2482:
2483: <tag><label id="bgp-advertise-ipv4">advertise ipv4 <m/switch/</tag>
2484: Advertise IPv4 multiprotocol capability. This is not a correct behavior
2485: according to the strict interpretation of <rfc id="4760">, but it is
2486: widespread and required by some BGP implementations (Cisco and Quagga).
2487: This option is relevant to IPv4 mode with enabled capability
2488: advertisement only. Default: on.
2489:
2490: <tag><label id="bgp-disable-after-error">disable after error <m/switch/</tag>
2491: When an error is encountered (either locally or by the other side),
2492: disable the instance automatically and wait for an administrator to fix
2493: the problem manually. Default: off.
2494:
2495: <tag><label id="bgp-disable-after-cease">disable after cease <m/switch/|<m/set-of-flags/</tag>
2496: When a Cease notification is received, disable the instance
2497: automatically and wait for an administrator to fix the problem manually.
2498: When used with <m/switch/ argument, it means handle every Cease subtype
2499: with the exception of <cf/connection collision/. Default: off.
2500:
2501: The <m/set-of-flags/ allows to narrow down relevant Cease subtypes. The
2502: syntax is <cf>{<m/flag/ [, <m/.../] }</cf>, where flags are: <cf/cease/,
2503: <cf/prefix limit hit/, <cf/administrative shutdown/,
2504: <cf/peer deconfigured/, <cf/administrative reset/,
2505: <cf/connection rejected/, <cf/configuration change/,
2506: <cf/connection collision/, <cf/out of resources/.
2507:
2508: <tag><label id="bgp-hold-time">hold time <m/number/</tag>
2509: Time in seconds to wait for a Keepalive message from the other side
2510: before considering the connection stale. Default: depends on agreement
2511: with the neighboring router, we prefer 240 seconds if the other side is
2512: willing to accept it.
2513:
2514: <tag><label id="bgp-startup-hold-time">startup hold time <m/number/</tag>
2515: Value of the hold timer used before the routers have a chance to exchange
2516: open messages and agree on the real value. Default: 240 seconds.
2517:
2518: <tag><label id="bgp-keepalive-time">keepalive time <m/number/</tag>
2519: Delay in seconds between sending of two consecutive Keepalive messages.
2520: Default: One third of the hold time.
2521:
2522: <tag><label id="bgp-connect-delay-time">connect delay time <m/number/</tag>
2523: Delay in seconds between protocol startup and the first attempt to
2524: connect. Default: 5 seconds.
2525:
2526: <tag><label id="bgp-connect-retry-time">connect retry time <m/number/</tag>
2527: Time in seconds to wait before retrying a failed attempt to connect.
2528: Default: 120 seconds.
2529:
2530: <tag><label id="bgp-error-wait-time">error wait time <m/number/,<m/number/</tag>
2531: Minimum and maximum delay in seconds between a protocol failure (either
2532: local or reported by the peer) and automatic restart. Doesn't apply
2533: when <cf/disable after error/ is configured. If consecutive errors
2534: happen, the delay is increased exponentially until it reaches the
2535: maximum. Default: 60, 300.
2536:
2537: <tag><label id="bgp-error-forget-time">error forget time <m/number/</tag>
2538: Maximum time in seconds between two protocol failures to treat them as a
2539: error sequence which makes <cf/error wait time/ increase exponentially.
2540: Default: 300 seconds.
2541:
2542: <tag><label id="bgp-path-metric">path metric <m/switch/</tag>
2543: Enable comparison of path lengths when deciding which BGP route is the
2544: best one. Default: on.
2545:
2546: <tag><label id="bgp-med-metric">med metric <m/switch/</tag>
2547: Enable comparison of MED attributes (during best route selection) even
2548: between routes received from different ASes. This may be useful if all
2549: MED attributes contain some consistent metric, perhaps enforced in
2550: import filters of AS boundary routers. If this option is disabled, MED
2551: attributes are compared only if routes are received from the same AS
2552: (which is the standard behavior). Default: off.
2553:
2554: <tag><label id="bgp-deterministic-med">deterministic med <m/switch/</tag>
2555: BGP route selection algorithm is often viewed as a comparison between
2556: individual routes (e.g. if a new route appears and is better than the
2557: current best one, it is chosen as the new best one). But the proper
2558: route selection, as specified by <rfc id="4271">, cannot be fully
2559: implemented in that way. The problem is mainly in handling the MED
2560: attribute. BIRD, by default, uses an simplification based on individual
2561: route comparison, which in some cases may lead to temporally dependent
2562: behavior (i.e. the selection is dependent on the order in which routes
2563: appeared). This option enables a different (and slower) algorithm
2564: implementing proper <rfc id="4271"> route selection, which is
2565: deterministic. Alternative way how to get deterministic behavior is to
2566: use <cf/med metric/ option. This option is incompatible with <ref
2567: id="dsc-table-sorted" name="sorted tables">. Default: off.
2568:
2569: <tag><label id="bgp-igp-metric">igp metric <m/switch/</tag>
2570: Enable comparison of internal distances to boundary routers during best
2571: route selection. Default: on.
2572:
2573: <tag><label id="bgp-prefer-older">prefer older <m/switch/</tag>
2574: Standard route selection algorithm breaks ties by comparing router IDs.
2575: This changes the behavior to prefer older routes (when both are external
2576: and from different peer). For details, see <rfc id="5004">. Default: off.
2577:
2578: <tag><label id="bgp-default-med">default bgp_med <m/number/</tag>
2579: Value of the Multiple Exit Discriminator to be used during route
2580: selection when the MED attribute is missing. Default: 0.
2581:
2582: <tag><label id="bgp-default-local-pref">default bgp_local_pref <m/number/</tag>
2583: A default value for the Local Preference attribute. It is used when
2584: a new Local Preference attribute is attached to a route by the BGP
2585: protocol itself (for example, if a route is received through eBGP and
2586: therefore does not have such attribute). Default: 100 (0 in pre-1.2.0
2587: versions of BIRD).
2588: </descrip>
2589:
2590: <sect1>Channel configuration
2591: <label id="bgp-channel-config">
2592:
2593: <p>BGP supports several AFIs and SAFIs over one connection. Every AFI/SAFI
2594: announced to the peer corresponds to one channel. The table of supported AFI/SAFIs
2595: together with their appropriate channels follows.
2596:
2597: <table loc="h">
2598: <tabular ca="l|l|l|r|r">
2599: <bf/Channel name/ | <bf/Table nettype/ | <bf/IGP table allowed/ | <bf/AFI/ | <bf/SAFI/
2600: @<hline>
2601: <cf/ipv4/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 1
2602: @ <cf/ipv6/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 1
2603: @ <cf/ipv4 multicast/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 2
2604: @ <cf/ipv6 multicast/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 2
2605: @ <cf/ipv4 mpls/ | <cf/ipv4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 4
2606: @ <cf/ipv6 mpls/ | <cf/ipv6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 4
2607: @ <cf/vpn4 mpls/ | <cf/vpn4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 128
2608: @ <cf/vpn6 mpls/ | <cf/vpn6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 128
2609: @ <cf/vpn4 multicast/ | <cf/vpn4/ | <cf/ipv4/ and <cf/ipv6/ | 1 | 129
2610: @ <cf/vpn6 multicast/ | <cf/vpn6/ | <cf/ipv4/ and <cf/ipv6/ | 2 | 129
2611: @ <cf/flow4/ | <cf/flow4/ | --- | 1 | 133
2612: @ <cf/flow6/ | <cf/flow6/ | --- | 2 | 133
2613: </tabular>
2614: </table>
2615:
2616: <p>Due to <rfc id="8212">, external BGP protocol requires explicit configuration
2617: of import and export policies (in contrast to other protocols, where default
2618: policies of <cf/import all/ and <cf/export none/ are used in absence of explicit
2619: configuration). Note that blanket policies like <cf/all/ or <cf/none/ can still
2620: be used in explicit configuration.
2621:
2622: <p>BGP channels have additional config options (together with the common ones):
2623:
2624: <descrip>
2625: <tag><label id="bgp-mandatory">mandatory <m/switch/</tag>
2626: When local and neighbor sets of configured AFI/SAFI pairs differ,
2627: capability negotiation ensures that a common subset is used. For
2628: mandatory channels their associated AFI/SAFI must be negotiated
2629: (i.e., also announced by the neighbor), otherwise BGP session
2630: negotiation fails with <it/'Required capability missing'/ error.
2631: Regardless, at least one AFI/SAFI must be negotiated in order to BGP
2632: session be successfully established. Default: off.
2633:
2634: <tag><label id="bgp-next-hop-keep">next hop keep <m/switch/|ibgp|ebgp</tag>
2635: Do not modify the Next Hop attribute and advertise the current one
2636: unchanged even in cases where our own local address should be used
2637: instead. This is necessary when the BGP speaker does not forward network
2638: traffic (route servers and some route reflectors) and also can be useful
2639: in some other cases (e.g. multihop EBGP sessions). Can be enabled for
2640: all routes, or just for routes received from IBGP / EBGP neighbors.
2641: Default: disabled for regular BGP, enabled for route servers,
2642: <cf/ibgp/ for route reflectors.
2643:
2644: <tag><label id="bgp-next-hop-self">next hop self <m/switch/|ibgp|ebgp</tag>
2645: Always advertise our own local address as a next hop, even in cases
2646: where the current Next Hop attribute should be used unchanged. This is
2647: sometimes used for routes propagated from EBGP to IBGP when IGP routing
2648: does not cover inter-AS links, therefore IP addreses of EBGP neighbors
2649: are not resolvable through IGP. Can be enabled for all routes, or just
2650: for routes received from IBGP / EBGP neighbors. Default: disabled.
2651:
2652: <tag><label id="bgp-next-hop-address">next hop address <m/ip/</tag>
2653: Specify which address to use when our own local address should be
2654: announced in the Next Hop attribute. Default: the source address of the
2655: BGP session (if acceptable), or the preferred address of an associated
2656: interface.
2657:
2658: <tag><label id="bgp-missing-lladdr">missing lladdr self|drop|ignore</tag>
2659: Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6
2660: address, but sometimes it has to contain both global and link-local IPv6
2661: addresses. This option specifies what to do if BIRD have to send both
2662: addresses but does not know link-local address. This situation might
2663: happen when routes from other protocols are exported to BGP, or when
2664: improper updates are received from BGP peers. <cf/self/ means that BIRD
2665: advertises its own local address instead. <cf/drop/ means that BIRD
2666: skips that prefixes and logs error. <cf/ignore/ means that BIRD ignores
2667: the problem and sends just the global address (and therefore forms
2668: improper BGP update). Default: <cf/self/, unless BIRD is configured as a
2669: route server (option <cf/rs client/), in that case default is <cf/ignore/,
2670: because route servers usually do not forward packets themselves.
2671:
2672: <tag><label id="bgp-gateway">gateway direct|recursive</tag>
2673: For received routes, their <cf/gw/ (immediate next hop) attribute is
2674: computed from received <cf/bgp_next_hop/ attribute. This option
2675: specifies how it is computed. Direct mode means that the IP address from
2676: <cf/bgp_next_hop/ is used if it is directly reachable, otherwise the
2677: neighbor IP address is used. Recursive mode means that the gateway is
2678: computed by an IGP routing table lookup for the IP address from
2679: <cf/bgp_next_hop/. Note that there is just one level of indirection in
2680: recursive mode - the route obtained by the lookup must not be recursive
2681: itself, to prevent mutually recursive routes.
2682:
2683: Recursive mode is the behavior specified by the BGP
2684: standard. Direct mode is simpler, does not require any routes in a
2685: routing table, and was used in older versions of BIRD, but does not
2686: handle well nontrivial iBGP setups and multihop. Recursive mode is
2687: incompatible with <ref id="dsc-table-sorted" name="sorted tables">. Default:
2688: <cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions.
2689:
2690: <tag><label id="bgp-igp-table">igp table <m/name/</tag>
2691: Specifies a table that is used as an IGP routing table. The type of this
2692: table must be as allowed in the table above. This option is allowed once
2693: for every allowed table type. Default: the same as the main table
2694: the channel is connected to (if eligible).
2695:
2696: <tag><label id="bgp-import-table">import table <m/switch/</tag>
2697: A BGP import table contains all received routes from given BGP neighbor,
2698: before application of import filters. It is also called <em/Adj-RIB-In/
2699: in BGP terminology. BIRD BGP by default operates without import tables,
2700: in which case received routes are just processed by import filters,
2701: accepted ones are stored in the master table, and the rest is forgotten.
2702: Enabling <cf/import table/ allows to store unprocessed routes, which can
2703: be examined later by <cf/show route/, and can be used to reconfigure
2704: import filters without full route refresh. Default: off.
2705:
2706: <tag><label id="bgp-export-table">export table <m/switch/</tag>
2707: A BGP export table contains all routes sent to given BGP neighbor, after
2708: application of export filters. It is also called <em/Adj-RIB-Out/ in BGP
2709: terminology. BIRD BGP by default operates without export tables, in
2710: which case routes from master table are just processed by export filters
2711: and then announced by BGP. Enabling <cf/export table/ allows to store
2712: routes after export filter processing, so they can be examined later by
2713: <cf/show route/, and can be used to eliminate unnecessary updates or
2714: withdraws. Default: off.
2715:
2716: <tag><label id="bgp-secondary">secondary <m/switch/</tag>
2717: Usually, if an export filter rejects a selected route, no other route is
2718: propagated for that network. This option allows to try the next route in
2719: order until one that is accepted is found or all routes for that network
2720: are rejected. This can be used for route servers that need to propagate
2721: different tables to each client but do not want to have these tables
2722: explicitly (to conserve memory). This option requires that the connected
2723: routing table is <ref id="dsc-table-sorted" name="sorted">. Default: off.
2724:
2725: <tag><label id="bgp-extended-next-hop">extended next hop <m/switch/</tag>
2726: BGP expects that announced next hops have the same address family as
2727: associated network prefixes. This option provides an extension to use
2728: IPv4 next hops with IPv6 prefixes and vice versa. For IPv4 / VPNv4
2729: channels, the behavior is controlled by the Extended Next Hop Encoding
2730: capability, as described in <rfc id="5549">. For IPv6 / VPNv6 channels,
2731: just IPv4-mapped IPv6 addresses are used, as described in
2732: <rfc id="4798"> and <rfc id="4659">. Default: off.
2733:
2734: <tag><label id="bgp-add-paths">add paths <m/switch/|rx|tx</tag>
2735: Standard BGP can propagate only one path (route) per destination network
2736: (usually the selected one). This option controls the add-path protocol
2737: extension, which allows to advertise any number of paths to a
2738: destination. Note that to be active, add-path has to be enabled on both
2739: sides of the BGP session, but it could be enabled separately for RX and
2740: TX direction. When active, all available routes accepted by the export
2741: filter are advertised to the neighbor. Default: off.
2742:
2743: <tag><label id="bgp-aigp">aigp <m/switch/|originate</tag>
2744: The BGP protocol does not use a common metric like other routing
2745: protocols, instead it uses a set of criteria for route selection
2746: consisting both overall AS path length and a distance to the nearest AS
2747: boundary router. Assuming that metrics of different autonomous systems
2748: are incomparable, once a route is propagated from an AS to a next one,
2749: the distance in the old AS does not matter.
2750:
2751: The AIGP extension (<rfc id="7311">) allows to propagate accumulated
2752: IGP metric (in the AIGP attribute) through both IBGP and EBGP links,
2753: computing total distance through multiple autonomous systems (assuming
2754: they use comparable IGP metric). The total AIGP metric is compared in
2755: the route selection process just after Local Preference comparison (and
2756: before AS path length comparison).
2757:
2758: This option controls whether AIGP attribute propagation is allowed on
2759: the session. Optionally, it can be set to <cf/originate/, which not only
2760: allows AIGP attribute propagation, but also new AIGP attributes are
2761: automatically attached to non-BGP routes with valid IGP metric (e.g.
2762: <cf/ospf_metric1/) as they are exported to the BGP session. Default:
2763: enabled for IBGP (and intra-confederation EBGP), disabled for regular
2764: EBGP.
2765:
2766: <tag><label id="bgp-cost">cost <m/number/</tag>
2767: When BGP <ref id="bgp-gateway" name="gateway mode"> is <cf/recursive/
2768: (mainly multihop IBGP sessions), then the distance to BGP next hop is
2769: based on underlying IGP metric. This option specifies the distance to
2770: BGP next hop for BGP sessions in direct gateway mode (mainly direct
2771: EBGP sessions).
2772:
2773: <tag><label id="bgp-graceful-restart-c">graceful restart <m/switch/</tag>
2774: Although BGP graceful restart is configured mainly by protocol-wide
2775: <ref id="bgp-graceful-restart" name="options">, it is possible to
2776: configure restarting role per AFI/SAFI pair by this channel option.
2777: The option is ignored if graceful restart is disabled by protocol-wide
2778: option. Default: off in aware mode, on in full mode.
2779:
2780: <tag><label id="bgp-long-lived-graceful-restart-c">long lived graceful restart <m/switch/</tag>
2781: BGP long-lived graceful restart is configured mainly by protocol-wide
2782: <ref id="bgp-long-lived-graceful-restart" name="options">, but the
2783: restarting role can be set per AFI/SAFI pair by this channel option.
2784: The option is ignored if long-lived graceful restart is disabled by
2785: protocol-wide option. Default: off in aware mode, on in full mode.
2786:
2787: <tag><label id="bgp-long-lived-stale-time-c">long lived stale time <m/number/</tag>
2788: Like previous graceful restart channel options, this option allows to
2789: set <ref id="bgp-long-lived-stale-time" name="long lived stale time">
2790: per AFI/SAFI pair instead of per protocol. Default: set by protocol-wide
2791: option.
2792: </descrip>
2793:
2794: <sect1>Attributes
2795: <label id="bgp-attr">
2796:
2797: <p>BGP defines several route attributes. Some of them (those marked with
2798: `<tt/I/' in the table below) are available on internal BGP connections only,
2799: some of them (marked with `<tt/O/') are optional.
2800:
2801: <descrip>
2802: <tag><label id="rta-bgp-path">bgppath bgp_path</tag>
2803: Sequence of AS numbers describing the AS path the packet will travel
2804: through when forwarded according to the particular route. In case of
2805: internal BGP it doesn't contain the number of the local AS.
2806:
2807: <tag><label id="rta-bgp-local-pref">int bgp_local_pref [I]</tag>
2808: Local preference value used for selection among multiple BGP routes (see
2809: the selection rules above). It's used as an additional metric which is
2810: propagated through the whole local AS.
2811:
2812: <tag><label id="rta-bgp-med">int bgp_med [O]</tag>
2813: The Multiple Exit Discriminator of the route is an optional attribute
2814: which is used on external (inter-AS) links to convey to an adjacent AS
2815: the optimal entry point into the local AS. The received attribute is
2816: also propagated over internal BGP links. The attribute value is zeroed
2817: when a route is exported to an external BGP instance to ensure that the
2818: attribute received from a neighboring AS is not propagated to other
2819: neighboring ASes. A new value might be set in the export filter of an
2820: external BGP instance. See <rfc id="4451"> for further discussion of
2821: BGP MED attribute.
2822:
2823: <tag><label id="rta-bgp-origin">enum bgp_origin</tag>
2824: Origin of the route: either <cf/ORIGIN_IGP/ if the route has originated
2825: in an interior routing protocol or <cf/ORIGIN_EGP/ if it's been imported
2826: from the <tt>EGP</tt> protocol (nowadays it seems to be obsolete) or
2827: <cf/ORIGIN_INCOMPLETE/ if the origin is unknown.
2828:
2829: <tag><label id="rta-bgp-next-hop">ip bgp_next_hop</tag>
2830: Next hop to be used for forwarding of packets to this destination. On
2831: internal BGP connections, it's an address of the originating router if
2832: it's inside the local AS or a boundary router the packet will leave the
2833: AS through if it's an exterior route, so each BGP speaker within the AS
2834: has a chance to use the shortest interior path possible to this point.
2835:
2836: <tag><label id="rta-bgp-atomic-aggr">void bgp_atomic_aggr [O]</tag>
2837: This is an optional attribute which carries no value, but the sole
2838: presence of which indicates that the route has been aggregated from
2839: multiple routes by some router on the path from the originator.
2840:
2841: <tag><label id="rta-bgp-aggregator">void bgp_aggregator [O]</tag>
2842: This is an optional attribute specifying AS number and IP address of the
2843: BGP router that created the route by aggregating multiple BGP routes.
2844: Currently, the attribute is not accessible from filters.
2845:
2846: <tag><label id="rta-bgp-community">clist bgp_community [O]</tag>
2847: List of community values associated with the route. Each such value is a
2848: pair (represented as a <cf/pair/ data type inside the filters) of 16-bit
2849: integers, the first of them containing the number of the AS which
2850: defines the community and the second one being a per-AS identifier.
2851: There are lots of uses of the community mechanism, but generally they
2852: are used to carry policy information like "don't export to USA peers".
2853: As each AS can define its own routing policy, it also has a complete
2854: freedom about which community attributes it defines and what will their
2855: semantics be.
2856:
2857: <tag><label id="rta-bgp-ext-community">eclist bgp_ext_community [O]</tag>
2858: List of extended community values associated with the route. Extended
2859: communities have similar usage as plain communities, but they have an
2860: extended range (to allow 4B ASNs) and a nontrivial structure with a type
2861: field. Individual community values are represented using an <cf/ec/ data
2862: type inside the filters.
2863:
2864: <tag><label id="rta-bgp-large-community">lclist bgp_large_community [O]</tag>
2865: List of large community values associated with the route. Large BGP
2866: communities is another variant of communities, but contrary to extended
2867: communities they behave very much the same way as regular communities,
2868: just larger -- they are uniform untyped triplets of 32bit numbers.
2869: Individual community values are represented using an <cf/lc/ data type
2870: inside the filters.
2871:
2872: <tag><label id="rta-bgp-originator-id">quad bgp_originator_id [I, O]</tag>
2873: This attribute is created by the route reflector when reflecting the
2874: route and contains the router ID of the originator of the route in the
2875: local AS.
2876:
2877: <tag><label id="rta-bgp-cluster-list">clist bgp_cluster_list [I, O]</tag>
2878: This attribute contains a list of cluster IDs of route reflectors. Each
2879: route reflector prepends its cluster ID when reflecting the route.
2880:
2881: <tag><label id="rta-bgp-aigp">void bgp_aigp [O]</tag>
2882: This attribute contains accumulated IGP metric, which is a total
2883: distance to the destination through multiple autonomous systems.
2884: Currently, the attribute is not accessible from filters.
2885: </descrip>
2886:
2887: <sect1>Example
2888: <label id="bgp-exam">
2889:
2890: <p><code>
2891: protocol bgp {
2892: local 198.51.100.14 as 65000; # Use a private AS number
2893: neighbor 198.51.100.130 as 64496; # Our neighbor ...
2894: multihop; # ... which is connected indirectly
2895: ipv4 {
2896: export filter { # We use non-trivial export rules
2897: if source = RTS_STATIC then { # Export only static routes
2898: # Assign our community
2899: bgp_community.add((65000,64501));
2900: # Artificially increase path length
2901: # by advertising local AS number twice
2902: if bgp_path ~ [= 65000 =] then
2903: bgp_path.prepend(65000);
2904: accept;
2905: }
2906: reject;
2907: };
2908: import all;
2909: next hop self; # advertise this router as next hop
2910: igp table myigptable4; # IGP table for routes with IPv4 nexthops
2911: igp table myigptable6; # IGP table for routes with IPv6 nexthops
2912: };
2913: ipv6 {
2914: export filter mylargefilter; # We use a named filter
2915: import all;
2916: missing lladdr self;
2917: igp table myigptable4; # IGP table for routes with IPv4 nexthops
2918: igp table myigptable6; # IGP table for routes with IPv6 nexthops
2919: };
2920: ipv4 multicast {
2921: import all;
2922: export filter someotherfilter;
2923: table mymulticasttable4; # Another IPv4 table, dedicated for multicast
2924: igp table myigptable4;
2925: };
2926: }
2927: </code>
2928:
2929:
2930: <sect>Device
2931: <label id="device">
2932:
2933: <p>The Device protocol is not a real routing protocol. It doesn't generate any
2934: routes and it only serves as a module for getting information about network
2935: interfaces from the kernel. This protocol supports no channel.
2936:
2937: <p>Except for very unusual circumstances, you probably should include this
2938: protocol in the configuration since almost all other protocols require network
2939: interfaces to be defined for them to work with.
2940:
2941: <sect1>Configuration
2942: <label id="device-config">
2943:
2944: <p><descrip>
2945: <tag><label id="device-scan-time">scan time <m/number/</tag>
2946: Time in seconds between two scans of the network interface list. On
2947: systems where we are notified about interface status changes
2948: asynchronously (such as newer versions of Linux), we need to scan the
2949: list only in order to avoid confusion by lost notification messages,
2950: so the default time is set to a large value.
2951:
2952: <tag><label id="device-iface">interface <m/pattern/ [, <m/.../]</tag>
2953: By default, the Device protocol handles all interfaces without any
2954: configuration. Interface definitions allow to specify optional
2955: parameters for specific interfaces. See <ref id="proto-iface"
2956: name="interface"> common option for detailed description. Currently only
2957: one interface option is available:
2958:
2959: <tag><label id="device-preferred">preferred <m/ip/</tag>
2960: If a network interface has more than one IP address, BIRD chooses one of
2961: them as a preferred one. Preferred IP address is used as source address
2962: for packets or announced next hop by routing protocols. Precisely, BIRD
2963: chooses one preferred IPv4 address, one preferred IPv6 address and one
2964: preferred link-local IPv6 address. By default, BIRD chooses the first
2965: found IP address as the preferred one.
2966:
2967: This option allows to specify which IP address should be preferred. May
2968: be used multiple times for different address classes (IPv4, IPv6, IPv6
2969: link-local). In all cases, an address marked by operating system as
2970: secondary cannot be chosen as the primary one.
2971: </descrip>
2972:
2973: <p>As the Device protocol doesn't generate any routes, it cannot have
2974: any attributes. Example configuration looks like this:
2975:
2976: <p><code>
2977: protocol device {
2978: scan time 10; # Scan the interfaces often
2979: interface "eth0" {
2980: preferred 192.168.1.1;
2981: preferred 2001:db8:1:10::1;
2982: };
2983: }
2984: </code>
2985:
2986:
2987: <sect>Direct
2988: <label id="direct">
2989:
2990: <p>The Direct protocol is a simple generator of device routes for all the
2991: directly connected networks according to the list of interfaces provided by the
2992: kernel via the Device protocol. The Direct protocol supports both IPv4 and IPv6
2993: channels; both can be configured simultaneously. It can also be configured with
2994: <ref id="ip-sadr-routes" name="IPv6 SADR"> channel instead of regular IPv6
2995: channel in order to be used together with SADR-enabled Babel protocol.
2996:
2997: <p>The question is whether it is a good idea to have such device routes in BIRD
2998: routing table. OS kernel usually handles device routes for directly connected
2999: networks by itself so we don't need (and don't want) to export these routes to
3000: the kernel protocol. OSPF protocol creates device routes for its interfaces
3001: itself and BGP protocol is usually used for exporting aggregate routes. But the
3002: Direct protocol is necessary for distance-vector protocols like RIP or Babel to
3003: announce local networks.
3004:
3005: <p>There are just few configuration options for the Direct protocol:
3006:
3007: <p><descrip>
3008: <tag><label id="direct-iface">interface <m/pattern/ [, <m/.../]</tag>
3009: By default, the Direct protocol will generate device routes for all the
3010: interfaces available. If you want to restrict it to some subset of
3011: interfaces or addresses (e.g. if you're using multiple routing tables
3012: for policy routing and some of the policy domains don't contain all
3013: interfaces), just use this clause. See <ref id="proto-iface" name="interface">
3014: common option for detailed description. The Direct protocol uses
3015: extended interface clauses.
3016:
3017: <tag><label id="direct-check-link">check link <m/switch/</tag>
3018: If enabled, a hardware link state (reported by OS) is taken into
3019: consideration. Routes for directly connected networks are generated only
3020: if link up is reported and they are withdrawn when link disappears
3021: (e.g., an ethernet cable is unplugged). Default value is no.
3022: </descrip>
3023:
3024: <p>Direct device routes don't contain any specific attributes.
3025:
3026: <p>Example config might look like this:
3027:
3028: <p><code>
3029: protocol direct {
3030: ipv4;
3031: ipv6;
3032: interface "-arc*", "*"; # Exclude the ARCnets
3033: }
3034: </code>
3035:
3036:
3037: <sect>Kernel
3038: <label id="krt">
3039:
3040: <p>The Kernel protocol is not a real routing protocol. Instead of communicating
3041: with other routers in the network, it performs synchronization of BIRD's routing
3042: tables with the OS kernel. Basically, it sends all routing table updates to the
3043: kernel and from time to time it scans the kernel tables to see whether some
3044: routes have disappeared (for example due to unnoticed up/down transition of an
3045: interface) or whether an `alien' route has been added by someone else (depending
3046: on the <cf/learn/ switch, such routes are either ignored or accepted to our
3047: table).
3048:
3049: <p>Note that routes created by OS kernel itself, namely direct routes
3050: representing IP subnets of associated interfaces, are not imported even with
3051: <cf/learn/ enabled. You can use <ref id="direct" name="Direct protocol"> to
3052: generate these direct routes.
3053:
3054: <p>If your OS supports only a single routing table, you can configure only one
3055: instance of the Kernel protocol. If it supports multiple tables (in order to
3056: allow policy routing; such an OS is for example Linux), you can run as many
3057: instances as you want, but each of them must be connected to a different BIRD
3058: routing table and to a different kernel table.
3059:
3060: <p>Because the kernel protocol is partially integrated with the connected
3061: routing table, there are two limitations - it is not possible to connect more
3062: kernel protocols to the same routing table and changing route destination
3063: (gateway) in an export filter of a kernel protocol does not work. Both
3064: limitations can be overcome using another routing table and the pipe protocol.
3065:
3066: <p>The Kernel protocol supports both IPv4 and IPv6 channels; only one channel
3067: can be configured in each protocol instance. On Linux, it also supports <ref
3068: id="ip-sadr-routes" name="IPv6 SADR"> and <ref id="mpls-routes" name="MPLS">
3069: channels.
3070:
3071: <sect1>Configuration
3072: <label id="krt-config">
3073:
3074: <p><descrip>
3075: <tag><label id="krt-persist">persist <m/switch/</tag>
3076: Tell BIRD to leave all its routes in the routing tables when it exits
3077: (instead of cleaning them up).
3078:
3079: <tag><label id="krt-scan-time">scan time <m/number/</tag>
3080: Time in seconds between two consecutive scans of the kernel routing
3081: table.
3082:
3083: <tag><label id="krt-learn">learn <m/switch/</tag>
3084: Enable learning of routes added to the kernel routing tables by other
3085: routing daemons or by the system administrator. This is possible only on
3086: systems which support identification of route authorship.
3087:
3088: <tag><label id="krt-kernel-table">kernel table <m/number/</tag>
3089: Select which kernel table should this particular instance of the Kernel
3090: protocol work with. Available only on systems supporting multiple
3091: routing tables.
3092:
3093: <tag><label id="krt-metric">metric <m/number/</tag> (Linux)
3094: Use specified value as a kernel metric (priority) for all routes sent to
3095: the kernel. When multiple routes for the same network are in the kernel
3096: routing table, the Linux kernel chooses one with lower metric. Also,
3097: routes with different metrics do not clash with each other, therefore
3098: using dedicated metric value is a reliable way to avoid overwriting
3099: routes from other sources (e.g. kernel device routes). Metric 0 has a
3100: special meaning of undefined metric, in which either OS default is used,
3101: or per-route metric can be set using <cf/krt_metric/ attribute. Default:
3102: 32.
3103:
3104: <tag><label id="krt-graceful-restart">graceful restart <m/switch/</tag>
3105: Participate in graceful restart recovery. If this option is enabled and
3106: a graceful restart recovery is active, the Kernel protocol will defer
3107: synchronization of routing tables until the end of the recovery. Note
3108: that import of kernel routes to BIRD is not affected.
3109:
3110: <tag><label id="krt-merge-paths">merge paths <M>switch</M> [limit <M>number</M>]</tag>
3111: Usually, only best routes are exported to the kernel protocol. With path
3112: merging enabled, both best routes and equivalent non-best routes are
3113: merged during export to generate one ECMP (equal-cost multipath) route
3114: for each network. This is useful e.g. for BGP multipath. Note that best
3115: routes are still pivotal for route export (responsible for most
3116: properties of resulting ECMP routes), while exported non-best routes are
3117: responsible just for additional multipath next hops. This option also
3118: allows to specify a limit on maximal number of nexthops in one route. By
3119: default, multipath merging is disabled. If enabled, default value of the
3120: limit is 16.
3121: </descrip>
3122:
3123: <sect1>Attributes
3124: <label id="krt-attr">
3125:
3126: <p>The Kernel protocol defines several attributes. These attributes are
3127: translated to appropriate system (and OS-specific) route attributes. We support
3128: these attributes:
3129:
3130: <descrip>
3131: <tag><label id="rta-krt-source">int krt_source</tag>
3132: The original source of the imported kernel route. The value is
3133: system-dependent. On Linux, it is a value of the protocol field of the
3134: route. See /etc/iproute2/rt_protos for common values. On BSD, it is
3135: based on STATIC and PROTOx flags. The attribute is read-only.
3136:
3137: <tag><label id="rta-krt-metric">int krt_metric</tag> (Linux)
3138: The kernel metric of the route. When multiple same routes are in a
3139: kernel routing table, the Linux kernel chooses one with lower metric.
3140: Note that preferred way to set kernel metric is to use protocol option
3141: <cf/metric/, unless per-route metric values are needed.
3142:
3143: <tag><label id="rta-krt-prefsrc">ip krt_prefsrc</tag> (Linux)
3144: The preferred source address. Used in source address selection for
3145: outgoing packets. Has to be one of the IP addresses of the router.
3146:
3147: <tag><label id="rta-krt-realm">int krt_realm</tag> (Linux)
3148: The realm of the route. Can be used for traffic classification.
3149:
3150: <tag><label id="rta-krt-scope">int krt_scope</tag> (Linux IPv4)
3151: The scope of the route. Valid values are 0-254, although Linux kernel
3152: may reject some values depending on route type and nexthop. It is
3153: supposed to represent `indirectness' of the route, where nexthops of
3154: routes are resolved through routes with a higher scope, but in current
3155: kernels anything below <it/link/ (253) is treated as <it/global/ (0).
3156: When not present, global scope is implied for all routes except device
3157: routes, where link scope is used by default.
3158: </descrip>
3159:
3160: <p>In Linux, there is also a plenty of obscure route attributes mostly focused
3161: on tuning TCP performance of local connections. BIRD supports most of these
3162: attributes, see Linux or iproute2 documentation for their meaning. Attributes
3163: <cf/krt_lock_*/ and <cf/krt_feature_*/ have type bool, others have type int.
3164: Supported attributes are:
3165:
3166: <cf/krt_mtu/, <cf/krt_lock_mtu/, <cf/krt_window/, <cf/krt_lock_window/,
3167: <cf/krt_rtt/, <cf/krt_lock_rtt/, <cf/krt_rttvar/, <cf/krt_lock_rttvar/,
3168: <cf/krt_sstresh/, <cf/krt_lock_sstresh/, <cf/krt_cwnd/, <cf/krt_lock_cwnd/,
3169: <cf/krt_advmss/, <cf/krt_lock_advmss/, <cf/krt_reordering/, <cf/krt_lock_reordering/,
3170: <cf/krt_hoplimit/, <cf/krt_lock_hoplimit/, <cf/krt_rto_min/, <cf/krt_lock_rto_min/,
3171: <cf/krt_initcwnd/, <cf/krt_initrwnd/, <cf/krt_quickack/,
3172: <cf/krt_feature_ecn/, <cf/krt_feature_allfrag/
3173:
3174: <sect1>Example
3175: <label id="krt-exam">
3176:
3177: <p>A simple configuration can look this way:
3178:
3179: <p><code>
3180: protocol kernel {
3181: export all;
3182: }
3183: </code>
3184:
3185: <p>Or for a system with two routing tables:
3186:
3187: <p><code>
3188: protocol kernel { # Primary routing table
3189: learn; # Learn alien routes from the kernel
3190: persist; # Don't remove routes on bird shutdown
3191: scan time 10; # Scan kernel routing table every 10 seconds
3192: ipv4 {
3193: import all;
3194: export all;
3195: };
3196: }
3197:
3198: protocol kernel { # Secondary routing table
3199: kernel table 100;
3200: ipv4 {
3201: table auxtable;
3202: export all;
3203: };
3204: }
3205: </code>
3206:
3207:
3208: <sect>MRT
3209: <label id="mrt">
3210:
3211: <sect1>Introduction
3212: <label id="mrt-intro">
3213:
3214: <p>The MRT protocol is a component responsible for handling the Multi-Threaded
3215: Routing Toolkit (MRT) routing information export format, which is mainly used
3216: for collecting and analyzing of routing information from BGP routers. The MRT
3217: protocol can be configured to do periodic dumps of routing tables, created MRT
3218: files can be analyzed later by other tools. Independent MRT table dumps can also
3219: be requested from BIRD client. There is also a feature to save incoming BGP
3220: messages in MRT files, but it is controlled by <ref id="proto-mrtdump"
3221: name="mrtdump"> options independently of MRT protocol, although that might
3222: change in the future.
3223:
3224: BIRD implements the main MRT format specification as defined in <rfc id="6396">
3225: and the ADD_PATH extension (<rfc id="8050">).
3226:
3227: <sect1>Configuration
3228: <label id="mrt-config">
3229:
3230: <p>MRT configuration consists of several statements describing routing table
3231: dumps. Multiple independent periodic dumps can be done as multiple MRT protocol
3232: instances. The MRT protocol does not use channels. There are two mandatory
3233: statements: <cf/filename/ and <cf/period/.
3234:
3235: The behavior can be modified by following configuration parameters:
3236:
3237: <descrip>
3238: <tag><label id="mrt-table">table <m/name/ | "<m/pattern/"</tag>
3239: Specify a routing table (or a set of routing tables described by a
3240: wildcard pattern) that are to be dumped by the MRT protocol instance.
3241: Default: the master table.
3242:
3243: <tag><label id="mrt-filter">filter { <m/filter commands/ }</tag>
3244: The MRT protocol allows to specify a filter that is applied to routes as
3245: they are dumped. Rejected routes are ignored and not saved to the MRT
3246: dump file. Default: no filter.
3247:
3248: <tag><label id="mrt-where">where <m/filter expression/</tag>
3249: An alternative way to specify a filter for the MRT protocol.
3250:
3251: <tag><label id="mrt-filename">filename "<m/filename/"</tag>
3252: Specify a filename for MRT dump files. The filename may contain time
3253: format sequences with <it/strftime(3)/ notation (see <it/man strftime/
3254: for details), there is also a sequence "%N" that is expanded to the name
3255: of dumped table. Therefore, each periodic dump of each table can be
3256: saved to a different file. Mandatory, see example below.
3257:
3258: <tag><label id="mrt-period">period <m/number/</tag>
3259: Specify the time interval (in seconds) between periodic dumps.
3260: Mandatory.
3261:
3262: <tag><label id="mrt-always-add-path">always add path <m/switch/</tag>
3263: The MRT format uses special records (specified in <rfc id="8050">) for
3264: routes received using BGP ADD_PATH extension to keep Path ID, while
3265: other routes use regular records. This has advantage of better
3266: compatibility with tools that do not know special records, but it loses
3267: information about which route is the best route. When this option is
3268: enabled, both ADD_PATH and non-ADD_PATH routes are stored in ADD_PATH
3269: records and order of routes for network is preserved. Default: disabled.
3270: </descrip>
3271:
3272: <sect1>Example
3273: <label id="mrt-exam">
3274:
3275: <p><code>
3276: protocol mrt {
3277: table "tab*";
3278: where source = RTS_BGP;
3279: filename "/var/log/bird/%N_%F_%T.mrt";
3280: period 300;
3281: }
3282: </code>
3283:
3284:
3285: <sect>OSPF
3286: <label id="ospf">
3287:
3288: <sect1>Introduction
3289: <label id="ospf-intro">
3290:
3291: <p>Open Shortest Path First (OSPF) is a quite complex interior gateway
3292: protocol. The current IPv4 version (OSPFv2) is defined in <rfc id="2328"> and
3293: the current IPv6 version (OSPFv3) is defined in <rfc id="5340"> It's a link
3294: state (a.k.a. shortest path first) protocol -- each router maintains a database
3295: describing the autonomous system's topology. Each participating router has an
3296: identical copy of the database and all routers run the same algorithm
3297: calculating a shortest path tree with themselves as a root. OSPF chooses the
3298: least cost path as the best path.
3299:
3300: <p>In OSPF, the autonomous system can be split to several areas in order to
3301: reduce the amount of resources consumed for exchanging the routing information
3302: and to protect the other areas from incorrect routing data. Topology of the area
3303: is hidden to the rest of the autonomous system.
3304:
3305: <p>Another very important feature of OSPF is that it can keep routing information
3306: from other protocols (like Static or BGP) in its link state database as external
3307: routes. Each external route can be tagged by the advertising router, making it
3308: possible to pass additional information between routers on the boundary of the
3309: autonomous system.
3310:
3311: <p>OSPF quickly detects topological changes in the autonomous system (such as
3312: router interface failures) and calculates new loop-free routes after a short
3313: period of convergence. Only a minimal amount of routing traffic is involved.
3314:
3315: <p>Each router participating in OSPF routing periodically sends Hello messages
3316: to all its interfaces. This allows neighbors to be discovered dynamically. Then
3317: the neighbors exchange theirs parts of the link state database and keep it
3318: identical by flooding updates. The flooding process is reliable and ensures that
3319: each router detects all changes.
3320:
3321: <sect1>Configuration
3322: <label id="ospf-config">
3323:
3324: <p>First, the desired OSPF version can be specified by using <cf/ospf v2/ or
3325: <cf/ospf v3/ as a protocol type. By default, OSPFv2 is used. In the main part of
3326: configuration, there can be multiple definitions of OSPF areas, each with a
3327: different id. These definitions includes many other switches and multiple
3328: definitions of interfaces. Definition of interface may contain many switches and
3329: constant definitions and list of neighbors on nonbroadcast networks.
3330:
3331: <p>OSPFv2 needs one IPv4 channel. OSPFv3 needs either one IPv6 channel, or one
3332: IPv4 channel (<rfc id="5838">). Therefore, it is possible to use OSPFv3 for both
3333: IPv4 and Pv6 routing, but it is necessary to have two protocol instances anyway.
3334: If no channel is configured, appropriate channel is defined with default
3335: parameters.
3336:
3337: <code>
3338: protocol ospf [v2|v3] <name> {
3339: rfc1583compat <switch>;
3340: rfc5838 <switch>;
3341: instance id <num>;
3342: stub router <switch>;
3343: tick <num>;
3344: ecmp <switch> [limit <num>];
3345: merge external <switch>;
3346: graceful restart <switch>|aware;
3347: graceful restart time <num>;
3348: area <id> {
3349: stub;
3350: nssa;
3351: summary <switch>;
3352: default nssa <switch>;
3353: default cost <num>;
3354: default cost2 <num>;
3355: translator <switch>;
3356: translator stability <num>;
3357:
3358: networks {
3359: <prefix>;
3360: <prefix> hidden;
3361: }
3362: external {
3363: <prefix>;
3364: <prefix> hidden;
3365: <prefix> tag <num>;
3366: }
3367: stubnet <prefix>;
3368: stubnet <prefix> {
3369: hidden <switch>;
3370: summary <switch>;
3371: cost <num>;
3372: }
3373: interface <interface pattern> [instance <num>] {
3374: cost <num>;
3375: stub <switch>;
3376: hello <num>;
3377: poll <num>;
3378: retransmit <num>;
3379: priority <num>;
3380: wait <num>;
3381: dead count <num>;
3382: dead <num>;
3383: secondary <switch>;
3384: rx buffer [normal|large|<num>];
3385: tx length <num>;
3386: type [broadcast|bcast|pointopoint|ptp|
3387: nonbroadcast|nbma|pointomultipoint|ptmp];
3388: link lsa suppression <switch>;
3389: strict nonbroadcast <switch>;
3390: real broadcast <switch>;
3391: ptp netmask <switch>;
3392: check link <switch>;
3393: bfd <switch>;
3394: ecmp weight <num>;
3395: ttl security [<switch>; | tx only]
3396: tx class|dscp <num>;
3397: tx priority <num>;
3398: authentication none|simple|cryptographic;
3399: password "<text>";
3400: password "<text>" {
3401: id <num>;
3402: generate from "<date>";
3403: generate to "<date>";
3404: accept from "<date>";
3405: accept to "<date>";
3406: from "<date>";
3407: to "<date>";
3408: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
3409: };
3410: neighbors {
3411: <ip>;
3412: <ip> eligible;
3413: };
3414: };
3415: virtual link <id> [instance <num>] {
3416: hello <num>;
3417: retransmit <num>;
3418: wait <num>;
3419: dead count <num>;
3420: dead <num>;
3421: authentication none|simple|cryptographic;
3422: password "<text>";
3423: password "<text>" {
3424: id <num>;
3425: generate from "<date>";
3426: generate to "<date>";
3427: accept from "<date>";
3428: accept to "<date>";
3429: from "<date>";
3430: to "<date>";
3431: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
3432: };
3433: };
3434: };
3435: }
3436: </code>
3437:
3438: <descrip>
3439: <tag><label id="ospf-rfc1583compat">rfc1583compat <M>switch</M></tag>
3440: This option controls compatibility of routing table calculation with
3441: <rfc id="1583">. Default value is no.
3442:
3443: <tag><label id="ospf-rfc5838">rfc5838 <m/switch/</tag>
3444: Basic OSPFv3 is limited to IPv6 unicast routing. The <rfc id="5838">
3445: extension defines support for more address families (IPv4, IPv6, both
3446: unicast and multicast). The extension is enabled by default, but can be
3447: disabled if necessary, as it restricts the range of available instance
3448: IDs. Default value is yes.
3449:
3450: <tag><label id="ospf-instance-id">instance id <m/num/</tag>
3451: When multiple OSPF protocol instances are active on the same links, they
3452: should use different instance IDs to distinguish their packets. Although
3453: it could be done on per-interface basis, it is often preferred to set
3454: one instance ID to whole OSPF domain/topology (e.g., when multiple
3455: instances are used to represent separate logical topologies on the same
3456: physical network). This option specifies the instance ID for all
3457: interfaces of the OSPF instance, but can be overridden by
3458: <cf/interface/ option. Default value is 0 unless OSPFv3-AF extended
3459: address families are used, see <rfc id="5838"> for that case.
3460:
3461: <tag><label id="ospf-stub-router">stub router <M>switch</M></tag>
3462: This option configures the router to be a stub router, i.e., a router
3463: that participates in the OSPF topology but does not allow transit
3464: traffic. In OSPFv2, this is implemented by advertising maximum metric
3465: for outgoing links. In OSPFv3, the stub router behavior is announced by
3466: clearing the R-bit in the router LSA. See <rfc id="6987"> for details.
3467: Default value is no.
3468:
3469: <tag><label id="ospf-tick">tick <M>num</M></tag>
3470: The routing table calculation and clean-up of areas' databases is not
3471: performed when a single link state change arrives. To lower the CPU
3472: utilization, it's processed later at periodical intervals of <m/num/
3473: seconds. The default value is 1.
3474:
3475: <tag><label id="ospf-ecmp">ecmp <M>switch</M> [limit <M>number</M>]</tag>
3476: This option specifies whether OSPF is allowed to generate ECMP
3477: (equal-cost multipath) routes. Such routes are used when there are
3478: several directions to the destination, each with the same (computed)
3479: cost. This option also allows to specify a limit on maximum number of
3480: nexthops in one route. By default, ECMP is enabled if supported by
3481: Kernel. Default value of the limit is 16.
3482:
3483: <tag><label id="ospf-merge-external">merge external <M>switch</M></tag>
3484: This option specifies whether OSPF should merge external routes from
3485: different routers/LSAs for the same destination. When enabled together
3486: with <cf/ecmp/, equal-cost external routes will be combined to multipath
3487: routes in the same way as regular routes. When disabled, external routes
3488: from different LSAs are treated as separate even if they represents the
3489: same destination. Default value is no.
3490:
3491: <tag><label id="ospf-graceful-restart">graceful restart <m/switch/|aware</tag>
3492: When an OSPF instance is restarted, neighbors break adjacencies and
3493: recalculate their routing tables, which disrupts packet forwarding even
3494: when the forwarding plane of the restarting router remains intact.
3495: <rfc id="3623"> specifies a graceful restart mechanism to alleviate this
3496: issue. For OSPF graceful restart, restarting router originates
3497: Grace-LSAs, announcing intent to do graceful restart. Neighbors
3498: receiving these LSAs enter helper mode, in which they ignore breakdown
3499: of adjacencies, behave as if nothing is happening and keep old routes.
3500: When adjacencies are reestablished, the restarting router flushes
3501: Grace-LSAs and graceful restart is ended.
3502:
3503: This option controls the graceful restart mechanism. It has three
3504: states: Disabled, when no support is provided. Aware, when graceful
3505: restart helper mode is supported, but no local graceful restart is
3506: allowed (i.e. helper-only role). Enabled, when the full graceful restart
3507: support is provided (i.e. both restarting and helper role). Note that
3508: proper support for local graceful restart requires also configuration of
3509: other protocols. Default: aware.
3510:
3511: <tag><label id="ospf-graceful-restart-time">graceful restart time <m/num/</tag>
3512: The restart time is announced in the Grace-LSA and specifies how long
3513: neighbors should wait for proper end of the graceful restart before
3514: exiting helper mode prematurely. Default: 120 seconds.
3515:
3516: <tag><label id="ospf-area">area <M>id</M></tag>
3517: This defines an OSPF area with given area ID (an integer or an IPv4
3518: address, similarly to a router ID). The most important area is the
3519: backbone (ID 0) to which every other area must be connected.
3520:
3521: <tag><label id="ospf-stub">stub</tag>
3522: This option configures the area to be a stub area. External routes are
3523: not flooded into stub areas. Also summary LSAs can be limited in stub
3524: areas (see option <cf/summary/). By default, the area is not a stub
3525: area.
3526:
3527: <tag><label id="ospf-nssa">nssa</tag>
3528: This option configures the area to be a NSSA (Not-So-Stubby Area). NSSA
3529: is a variant of a stub area which allows a limited way of external route
3530: propagation. Global external routes are not propagated into a NSSA, but
3531: an external route can be imported into NSSA as a (area-wide) NSSA-LSA
3532: (and possibly translated and/or aggregated on area boundary). By
3533: default, the area is not NSSA.
3534:
3535: <tag><label id="ospf-summary">summary <M>switch</M></tag>
3536: This option controls propagation of summary LSAs into stub or NSSA
3537: areas. If enabled, summary LSAs are propagated as usual, otherwise just
3538: the default summary route (0.0.0.0/0) is propagated (this is sometimes
3539: called totally stubby area). If a stub area has more area boundary
3540: routers, propagating summary LSAs could lead to more efficient routing
3541: at the cost of larger link state database. Default value is no.
3542:
3543: <tag><label id="ospf-default-nssa">default nssa <M>switch</M></tag>
3544: When <cf/summary/ option is enabled, default summary route is no longer
3545: propagated to the NSSA. In that case, this option allows to originate
3546: default route as NSSA-LSA to the NSSA. Default value is no.
3547:
3548: <tag><label id="ospf-default-cost">default cost <M>num</M></tag>
3549: This option controls the cost of a default route propagated to stub and
3550: NSSA areas. Default value is 1000.
3551:
3552: <tag><label id="ospf-default-cost2">default cost2 <M>num</M></tag>
3553: When a default route is originated as NSSA-LSA, its cost can use either
3554: type 1 or type 2 metric. This option allows to specify the cost of a
3555: default route in type 2 metric. By default, type 1 metric (option
3556: <cf/default cost/) is used.
3557:
3558: <tag><label id="ospf-translator">translator <M>switch</M></tag>
3559: This option controls translation of NSSA-LSAs into external LSAs. By
3560: default, one translator per NSSA is automatically elected from area
3561: boundary routers. If enabled, this area boundary router would
3562: unconditionally translate all NSSA-LSAs regardless of translator
3563: election. Default value is no.
3564:
3565: <tag><label id="ospf-translator-stability">translator stability <M>num</M></tag>
3566: This option controls the translator stability interval (in seconds).
3567: When the new translator is elected, the old one keeps translating until
3568: the interval is over. Default value is 40.
3569:
3570: <tag><label id="ospf-networks">networks { <m/set/ }</tag>
3571: Definition of area IP ranges. This is used in summary LSA origination.
3572: Hidden networks are not propagated into other areas.
3573:
3574: <tag><label id="ospf-external">external { <m/set/ }</tag>
3575: Definition of external area IP ranges for NSSAs. This is used for
3576: NSSA-LSA translation. Hidden networks are not translated into external
3577: LSAs. Networks can have configured route tag.
3578:
3579: <tag><label id="ospf-stubnet">stubnet <m/prefix/ { <m/options/ }</tag>
3580: Stub networks are networks that are not transit networks between OSPF
3581: routers. They are also propagated through an OSPF area as a part of a
3582: link state database. By default, BIRD generates a stub network record
3583: for each primary network address on each OSPF interface that does not
3584: have any OSPF neighbors, and also for each non-primary network address
3585: on each OSPF interface. This option allows to alter a set of stub
3586: networks propagated by this router.
3587:
3588: Each instance of this option adds a stub network with given network
3589: prefix to the set of propagated stub network, unless option <cf/hidden/
3590: is used. It also suppresses default stub networks for given network
3591: prefix. When option <cf/summary/ is used, also default stub networks
3592: that are subnetworks of given stub network are suppressed. This might be
3593: used, for example, to aggregate generated stub networks.
3594:
3595: <tag><label id="ospf-iface">interface <M>pattern</M> [instance <m/num/]</tag>
3596: Defines that the specified interfaces belong to the area being defined.
3597: See <ref id="proto-iface" name="interface"> common option for detailed
3598: description. In OSPFv2, extended interface clauses are used, because
3599: each network prefix is handled as a separate virtual interface.
3600:
3601: You can specify alternative instance ID for the interface definition,
3602: therefore it is possible to have several instances of that interface
3603: with different options or even in different areas. For OSPFv2, instance
3604: ID support is an extension (<rfc id="6549">) and is supposed to be set
3605: per-protocol. For OSPFv3, it is an integral feature.
3606:
3607: <tag><label id="ospf-virtual-link">virtual link <M>id</M> [instance <m/num/]</tag>
3608: Virtual link to router with the router id. Virtual link acts as a
3609: point-to-point interface belonging to backbone. The actual area is used
3610: as a transport area. This item cannot be in the backbone. Like with
3611: <cf/interface/ option, you could also use several virtual links to one
3612: destination with different instance IDs.
3613:
3614: <tag><label id="ospf-cost">cost <M>num</M></tag>
3615: Specifies output cost (metric) of an interface. Default value is 10.
3616:
3617: <tag><label id="ospf-stub-iface">stub <M>switch</M></tag>
3618: If set to interface it does not listen to any packet and does not send
3619: any hello. Default value is no.
3620:
3621: <tag><label id="ospf-hello">hello <M>num</M></tag>
3622: Specifies interval in seconds between sending of Hello messages. Beware,
3623: all routers on the same network need to have the same hello interval.
3624: Default value is 10.
3625:
3626: <tag><label id="ospf-poll">poll <M>num</M></tag>
3627: Specifies interval in seconds between sending of Hello messages for some
3628: neighbors on NBMA network. Default value is 20.
3629:
3630: <tag><label id="ospf-retransmit">retransmit <M>num</M></tag>
3631: Specifies interval in seconds between retransmissions of unacknowledged
3632: updates. Default value is 5.
3633:
3634: <tag><label id="ospf-transmit-delay">transmit delay <M>num</M></tag>
3635: Specifies estimated transmission delay of link state updates send over
3636: the interface. The value is added to LSA age of LSAs propagated through
3637: it. Default value is 1.
3638:
3639: <tag><label id="ospf-priority">priority <M>num</M></tag>
3640: On every multiple access network (e.g., the Ethernet) Designated Router
3641: and Backup Designated router are elected. These routers have some special
3642: functions in the flooding process. Higher priority increases preferences
3643: in this election. Routers with priority 0 are not eligible. Default
3644: value is 1.
3645:
3646: <tag><label id="ospf-wait">wait <M>num</M></tag>
3647: After start, router waits for the specified number of seconds between
3648: starting election and building adjacency. Default value is 4*<m/hello/.
3649:
3650: <tag><label id="ospf-dead-count">dead count <M>num</M></tag>
3651: When the router does not receive any messages from a neighbor in
3652: <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
3653:
3654: <tag><label id="ospf-dead">dead <M>num</M></tag>
3655: When the router does not receive any messages from a neighbor in
3656: <m/dead/ seconds, it will consider the neighbor down. If both directives
3657: <cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precedence.
3658:
3659: <tag><label id="ospf-rx-buffer">rx buffer <M>num</M></tag>
3660: This option allows to specify the size of buffers used for packet
3661: processing. The buffer size should be bigger than maximal size of any
3662: packets. By default, buffers are dynamically resized as needed, but a
3663: fixed value could be specified. Value <cf/large/ means maximal allowed
3664: packet size - 65535.
3665:
3666: <tag><label id="ospf-tx-length">tx length <M>num</M></tag>
3667: Transmitted OSPF messages that contain large amount of information are
3668: segmented to separate OSPF packets to avoid IP fragmentation. This
3669: option specifies the soft ceiling for the length of generated OSPF
3670: packets. Default value is the MTU of the network interface. Note that
3671: larger OSPF packets may still be generated if underlying OSPF messages
3672: cannot be splitted (e.g. when one large LSA is propagated).
3673:
3674: <tag><label id="ospf-type-bcast">type broadcast|bcast</tag>
3675: BIRD detects a type of a connected network automatically, but sometimes
3676: it's convenient to force use of a different type manually. On broadcast
3677: networks (like ethernet), flooding and Hello messages are sent using
3678: multicasts (a single packet for all the neighbors). A designated router
3679: is elected and it is responsible for synchronizing the link-state
3680: databases and originating network LSAs. This network type cannot be used
3681: on physically NBMA networks and on unnumbered networks (networks without
3682: proper IP prefix).
3683:
3684: <tag><label id="ospf-type-ptp">type pointopoint|ptp</tag>
3685: Point-to-point networks connect just 2 routers together. No election is
3686: performed and no network LSA is originated, which makes it simpler and
3687: faster to establish. This network type is useful not only for physically
3688: PtP ifaces (like PPP or tunnels), but also for broadcast networks used
3689: as PtP links. This network type cannot be used on physically NBMA
3690: networks.
3691:
3692: <tag><label id="ospf-type-nbma">type nonbroadcast|nbma</tag>
3693: On NBMA networks, the packets are sent to each neighbor separately
3694: because of lack of multicast capabilities. Like on broadcast networks,
3695: a designated router is elected, which plays a central role in propagation
3696: of LSAs. This network type cannot be used on unnumbered networks.
3697:
3698: <tag><label id="ospf-type-ptmp">type pointomultipoint|ptmp</tag>
3699: This is another network type designed to handle NBMA networks. In this
3700: case the NBMA network is treated as a collection of PtP links. This is
3701: useful if not every pair of routers on the NBMA network has direct
3702: communication, or if the NBMA network is used as an (possibly
3703: unnumbered) PtP link.
3704:
3705: <tag><label id="ospf-link-lsa-suppression">link lsa suppression <m/switch/</tag>
3706: In OSPFv3, link LSAs are generated for each link, announcing link-local
3707: IPv6 address of the router to its local neighbors. These are useless on
3708: PtP or PtMP networks and this option allows to suppress the link LSA
3709: origination for such interfaces. The option is ignored on other than PtP
3710: or PtMP interfaces. Default value is no.
3711:
3712: <tag><label id="ospf-strict-nonbroadcast">strict nonbroadcast <m/switch/</tag>
3713: If set, don't send hello to any undefined neighbor. This switch is
3714: ignored on other than NBMA or PtMP interfaces. Default value is no.
3715:
3716: <tag><label id="ospf-real-broadcast">real broadcast <m/switch/</tag>
3717: In <cf/type broadcast/ or <cf/type ptp/ network configuration, OSPF
3718: packets are sent as IP multicast packets. This option changes the
3719: behavior to using old-fashioned IP broadcast packets. This may be useful
3720: as a workaround if IP multicast for some reason does not work or does
3721: not work reliably. This is a non-standard option and probably is not
3722: interoperable with other OSPF implementations. Default value is no.
3723:
3724: <tag><label id="ospf-ptp-netmask">ptp netmask <m/switch/</tag>
3725: In <cf/type ptp/ network configurations, OSPFv2 implementations should
3726: ignore received netmask field in hello packets and should send hello
3727: packets with zero netmask field on unnumbered PtP links. But some OSPFv2
3728: implementations perform netmask checking even for PtP links. This option
3729: specifies whether real netmask will be used in hello packets on <cf/type
3730: ptp/ interfaces. You should ignore this option unless you meet some
3731: compatibility problems related to this issue. Default value is no for
3732: unnumbered PtP links, yes otherwise.
3733:
3734: <tag><label id="ospf-check-link">check link <M>switch</M></tag>
3735: If set, a hardware link state (reported by OS) is taken into consideration.
3736: When a link disappears (e.g. an ethernet cable is unplugged), neighbors
3737: are immediately considered unreachable and only the address of the iface
3738: (instead of whole network prefix) is propagated. It is possible that
3739: some hardware drivers or platforms do not implement this feature.
3740: Default value is yes.
3741:
3742: <tag><label id="ospf-bfd">bfd <M>switch</M></tag>
3743: OSPF could use BFD protocol as an advisory mechanism for neighbor
3744: liveness and failure detection. If enabled, BIRD setups a BFD session
3745: for each OSPF neighbor and tracks its liveness by it. This has an
3746: advantage of an order of magnitude lower detection times in case of
3747: failure. Note that BFD protocol also has to be configured, see
3748: <ref id="bfd" name="BFD"> section for details. Default value is no.
3749:
3750: <tag><label id="ospf-ttl-security">ttl security [<m/switch/ | tx only]</tag>
3751: TTL security is a feature that protects routing protocols from remote
3752: spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
3753: destined to neighbors. Because TTL is decremented when packets are
3754: forwarded, it is non-trivial to spoof packets with TTL 255 from remote
3755: locations. Note that this option would interfere with OSPF virtual
3756: links.
3757:
3758: If this option is enabled, the router will send OSPF packets with TTL
3759: 255 and drop received packets with TTL less than 255. If this option si
3760: set to <cf/tx only/, TTL 255 is used for sent packets, but is not
3761: checked for received packets. Default value is no.
3762:
3763: <tag><label id="ospf-tx-class">tx class|dscp|priority <m/num/</tag>
3764: These options specify the ToS/DiffServ/Traffic class/Priority of the
3765: outgoing OSPF packets. See <ref id="proto-tx-class" name="tx class"> common
3766: option for detailed description.
3767:
3768: <tag><label id="ospf-ecmp-weight">ecmp weight <M>num</M></tag>
3769: When ECMP (multipath) routes are allowed, this value specifies a
3770: relative weight used for nexthops going through the iface. Allowed
3771: values are 1-256. Default value is 1.
3772:
3773: <tag><label id="ospf-auth-none">authentication none</tag>
3774: No passwords are sent in OSPF packets. This is the default value.
3775:
3776: <tag><label id="ospf-auth-simple">authentication simple</tag>
3777: Every packet carries 8 bytes of password. Received packets lacking this
3778: password are ignored. This authentication mechanism is very weak.
3779: This option is not available in OSPFv3.
3780:
3781: <tag><label id="ospf-auth-cryptographic">authentication cryptographic</tag>
3782: An authentication code is appended to every packet. The specific
3783: cryptographic algorithm is selected by option <cf/algorithm/ for each
3784: key. The default cryptographic algorithm for OSPFv2 keys is Keyed-MD5
3785: and for OSPFv3 keys is HMAC-SHA-256. Passwords are not sent open via
3786: network, so this mechanism is quite secure. Packets can still be read by
3787: an attacker.
3788:
3789: <tag><label id="ospf-pass">password "<M>text</M>"</tag>
3790: Specifies a password used for authentication. See
3791: <ref id="proto-pass" name="password"> common option for detailed
3792: description.
3793:
3794: <tag><label id="ospf-neighbors">neighbors { <m/set/ } </tag>
3795: A set of neighbors to which Hello messages on NBMA or PtMP networks are
3796: to be sent. For NBMA networks, some of them could be marked as eligible.
3797: In OSPFv3, link-local addresses should be used, using global ones is
3798: possible, but it is nonstandard and might be problematic. And definitely,
3799: link-local and global addresses should not be mixed.
3800: </descrip>
3801:
3802: <sect1>Attributes
3803: <label id="ospf-attr">
3804:
3805: <p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
3806:
3807: <p>Metric is ranging from 1 to infinity (65535). External routes use
3808: <cf/metric type 1/ or <cf/metric type 2/. A <cf/metric of type 1/ is comparable
3809: with internal <cf/metric/, a <cf/metric of type 2/ is always longer than any
3810: <cf/metric of type 1/ or any <cf/internal metric/. <cf/Internal metric/ or
3811: <cf/metric of type 1/ is stored in attribute <cf/ospf_metric1/, <cf/metric type
3812: 2/ is stored in attribute <cf/ospf_metric2/.
3813:
3814: When both metrics are specified then <cf/metric of type 2/ is used. This is
3815: relevant e.g. when a type 2 external route is propagated from one OSPF domain to
3816: another and <cf/ospf_metric1/ is an internal distance to the original ASBR,
3817: while <cf/ospf_metric2/ stores the type 2 metric. Note that in such cases if
3818: <cf/ospf_metric1/ is non-zero then <cf/ospf_metric2/ is increased by one to
3819: ensure monotonicity of metric, as internal distance is reset to zero when an
3820: external route is announced.
3821:
3822: <p>Each external route can also carry attribute <cf/ospf_tag/ which is a 32-bit
3823: integer which is used when exporting routes to other protocols; otherwise, it
3824: doesn't affect routing inside the OSPF domain at all. The fourth attribute
3825: <cf/ospf_router_id/ is a router ID of the router advertising that route /
3826: network. This attribute is read-only. Default is <cf/ospf_metric2 = 10000/ and
3827: <cf/ospf_tag = 0/.
3828:
3829: <sect1>Example
3830: <label id="ospf-exam">
3831:
3832: <p><code>
3833: protocol ospf MyOSPF {
3834: ipv4 {
3835: export filter {
3836: if source = RTS_BGP then {
3837: ospf_metric1 = 100;
3838: accept;
3839: }
3840: reject;
3841: };
3842: };
3843: area 0.0.0.0 {
3844: interface "eth*" {
3845: cost 11;
3846: hello 15;
3847: priority 100;
3848: retransmit 7;
3849: authentication simple;
3850: password "aaa";
3851: };
3852: interface "ppp*" {
3853: cost 100;
3854: authentication cryptographic;
3855: password "abc" {
3856: id 1;
3857: generate to "22-04-2003 11:00:06";
3858: accept from "17-01-2001 12:01:05";
3859: algorithm hmac sha384;
3860: };
3861: password "def" {
3862: id 2;
3863: generate to "22-07-2005 17:03:21";
3864: accept from "22-02-2001 11:34:06";
3865: algorithm hmac sha512;
3866: };
3867: };
3868: interface "arc0" {
3869: cost 10;
3870: stub yes;
3871: };
3872: interface "arc1";
3873: };
3874: area 120 {
3875: stub yes;
3876: networks {
3877: 172.16.1.0/24;
3878: 172.16.2.0/24 hidden;
3879: }
3880: interface "-arc0" , "arc*" {
3881: type nonbroadcast;
3882: authentication none;
3883: strict nonbroadcast yes;
3884: wait 120;
3885: poll 40;
3886: dead count 8;
3887: neighbors {
3888: 192.168.120.1 eligible;
3889: 192.168.120.2;
3890: 192.168.120.10;
3891: };
3892: };
3893: };
3894: }
3895: </code>
3896:
3897: <sect>Perf
3898: <label id="perf">
3899:
3900: <sect1>Introduction
3901: <label id="perf-intro">
3902:
3903: <p>The Perf protocol is a generator of fake routes together with a time measurement
3904: framework. Its purpose is to check BIRD performance and to benchmark filters.
3905:
3906: <p>Import mode of this protocol runs in several steps. In each step, it generates 2^x routes,
3907: imports them into the appropriate table and withdraws them. The exponent x is configurable.
3908: It runs the benchmark several times for the same x, then it increases x by one
3909: until it gets too high, then it stops.
3910:
3911: <p>Export mode of this protocol repeats route refresh from table and measures how long it takes.
3912:
3913: <p>Output data is logged on info level. There is a Perl script <cf>proto/perf/parse.pl</cf>
3914: which may be handy to parse the data and draw some plots.
3915:
3916: <p>Implementation of this protocol is experimental. Use with caution and do not keep
3917: any instance of Perf in production configs for long time. The config interface is also unstable
3918: and may change in future versions without warning.
3919:
3920: <sect1>Configuration
3921: <label id="perf-config">
3922:
3923: <p><descrip>
3924: <tag><label id="perf-mode">mode import|export</tag>
3925: Set perf mode. Default: import
3926:
3927: <tag><label id="perf-repeat">repeat <m/number/</tag>
3928: Run this amount of iterations of the benchmark for every amount step. Default: 4
3929:
3930: <tag><label id="perf-from">exp from <m/number/</tag>
3931: Begin benchmarking on this exponent for number of generated routes in one step.
3932: Default: 10
3933:
3934: <tag><label id="perf-to">exp to <m/number/</tag>
3935: Stop benchmarking on this exponent. Default: 20
3936:
3937: <tag><label id="perf-threshold-min">threshold min <m/time/</tag>
3938: If a run for the given exponent took less than this time for route import,
3939: increase the exponent immediately. Default: 1 ms
3940:
3941: <tag><label id="perf-threshold-max">threshold max <m/time/</tag>
3942: If every run for the given exponent took at least this time for route import,
3943: stop benchmarking. Default: 500 ms
3944: </descrip>
3945:
3946: <sect>Pipe
3947: <label id="pipe">
3948:
3949: <sect1>Introduction
3950: <label id="pipe-intro">
3951:
3952: <p>The Pipe protocol serves as a link between two routing tables, allowing
3953: routes to be passed from a table declared as primary (i.e., the one the pipe is
3954: connected to using the <cf/table/ configuration keyword) to the secondary one
3955: (declared using <cf/peer table/) and vice versa, depending on what's allowed by
3956: the filters. Export filters control export of routes from the primary table to
3957: the secondary one, import filters control the opposite direction. Both tables
3958: must be of the same nettype.
3959:
3960: <p>The Pipe protocol retransmits all routes from one table to the other table,
3961: retaining their original source and attributes. If import and export filters
3962: are set to accept, then both tables would have the same content.
3963:
3964: <p>The primary use of multiple routing tables and the Pipe protocol is for
3965: policy routing, where handling of a single packet doesn't depend only on its
3966: destination address, but also on its source address, source interface, protocol
3967: type and other similar parameters. In many systems (Linux being a good example),
3968: the kernel allows to enforce routing policies by defining routing rules which
3969: choose one of several routing tables to be used for a packet according to its
3970: parameters. Setting of these rules is outside the scope of BIRD's work (on
3971: Linux, you can use the <tt/ip/ command), but you can create several routing
3972: tables in BIRD, connect them to the kernel ones, use filters to control which
3973: routes appear in which tables and also you can employ the Pipe protocol for
3974: exporting a selected subset of one table to another one.
3975:
3976: <sect1>Configuration
3977: <label id="pipe-config">
3978:
3979: <p>Essentially, the Pipe protocol is just a channel connected to a table on both
3980: sides. Therefore, the configuration block for <cf/protocol pipe/ shall directly
3981: include standard channel config options; see the example below.
3982:
3983: <p><descrip>
3984: <tag><label id="pipe-peer-table">peer table <m/table/</tag>
3985: Defines secondary routing table to connect to. The primary one is
3986: selected by the <cf/table/ keyword.
3987: </descrip>
3988:
3989: <sect1>Attributes
3990: <label id="pipe-attr">
3991:
3992: <p>The Pipe protocol doesn't define any route attributes.
3993:
3994: <sect1>Example
3995: <label id="pipe-exam">
3996:
3997: <p>Let's consider a router which serves as a boundary router of two different
3998: autonomous systems, each of them connected to a subset of interfaces of the
3999: router, having its own exterior connectivity and wishing to use the other AS as
4000: a backup connectivity in case of outage of its own exterior line.
4001:
4002: <p>Probably the simplest solution to this situation is to use two routing tables
4003: (we'll call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that
4004: packets having arrived from interfaces belonging to the first AS will be routed
4005: according to <cf/as1/ and similarly for the second AS. Thus we have split our
4006: router to two logical routers, each one acting on its own routing table, having
4007: its own routing protocols on its own interfaces. In order to use the other AS's
4008: routes for backup purposes, we can pass the routes between the tables through a
4009: Pipe protocol while decreasing their preferences and correcting their BGP paths
4010: to reflect the AS boundary crossing.
4011:
4012: <code>
4013: ipv4 table as1; # Define the tables
4014: ipv4 table as2;
4015:
4016: protocol kernel kern1 { # Synchronize them with the kernel
4017: ipv4 { table as1; export all; };
4018: kernel table 1;
4019: }
4020:
4021: protocol kernel kern2 {
4022: ipv4 { table as2; export all; };
4023: kernel table 2;
4024: }
4025:
4026: protocol bgp bgp1 { # The outside connections
4027: ipv4 { table as1; import all; export all; };
4028: local as 1;
4029: neighbor 192.168.0.1 as 1001;
4030: }
4031:
4032: protocol bgp bgp2 {
4033: ipv4 { table as2; import all; export all; };
4034: local as 2;
4035: neighbor 10.0.0.1 as 1002;
4036: }
4037:
4038: protocol pipe { # The Pipe
4039: table as1;
4040: peer table as2;
4041: export filter {
4042: if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks
4043: if preference>10 then preference = preference-10;
4044: if source=RTS_BGP then bgp_path.prepend(1);
4045: accept;
4046: }
4047: reject;
4048: };
4049: import filter {
4050: if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks
4051: if preference>10 then preference = preference-10;
4052: if source=RTS_BGP then bgp_path.prepend(2);
4053: accept;
4054: }
4055: reject;
4056: };
4057: }
4058: </code>
4059:
4060:
4061: <sect>RAdv
4062: <label id="radv">
4063:
4064: <sect1>Introduction
4065: <label id="radv-intro">
4066:
4067: <p>The RAdv protocol is an implementation of Router Advertisements, which are
4068: used in the IPv6 stateless autoconfiguration. IPv6 routers send (in irregular
4069: time intervals or as an answer to a request) advertisement packets to connected
4070: networks. These packets contain basic information about a local network (e.g. a
4071: list of network prefixes), which allows network hosts to autoconfigure network
4072: addresses and choose a default route. BIRD implements router behavior as defined
4073: in <rfc id="4861">, router preferences and specific routes (<rfc id="4191">),
4074: and DNS extensions (<rfc id="6106">).
4075:
4076: <p>The RAdv protocols supports just IPv6 channel.
4077:
4078: <sect1>Configuration
4079: <label id="radv-config">
4080:
4081: <p>There are several classes of definitions in RAdv configuration -- interface
4082: definitions, prefix definitions and DNS definitions:
4083:
4084: <descrip>
4085: <tag><label id="radv-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
4086: Interface definitions specify a set of interfaces on which the
4087: protocol is activated and contain interface specific options.
4088: See <ref id="proto-iface" name="interface"> common options for
4089: detailed description.
4090:
4091: <tag><label id="radv-prefix">prefix <m/prefix/ { <m/options/ }</tag>
4092: Prefix definitions allow to modify a list of advertised prefixes. By
4093: default, the advertised prefixes are the same as the network prefixes
4094: assigned to the interface. For each network prefix, the matching prefix
4095: definition is found and its options are used. If no matching prefix
4096: definition is found, the prefix is used with default options.
4097:
4098: Prefix definitions can be either global or interface-specific. The
4099: second ones are part of interface options. The prefix definition
4100: matching is done in the first-match style, when interface-specific
4101: definitions are processed before global definitions. As expected, the
4102: prefix definition is matching if the network prefix is a subnet of the
4103: prefix in prefix definition.
4104:
4105: <tag><label id="radv-rdnss">rdnss { <m/options/ }</tag>
4106: RDNSS definitions allow to specify a list of advertised recursive DNS
4107: servers together with their options. As options are seldom necessary,
4108: there is also a short variant <cf>rdnss <m/address/</cf> that just
4109: specifies one DNS server. Multiple definitions are cumulative. RDNSS
4110: definitions may also be interface-specific when used inside interface
4111: options. By default, interface uses both global and interface-specific
4112: options, but that can be changed by <cf/rdnss local/ option.
4113:
4114: <tag><label id="radv-dnssl">dnssl { <m/options/ }</tag>
4115: DNSSL definitions allow to specify a list of advertised DNS search
4116: domains together with their options. Like <cf/rdnss/ above, multiple
4117: definitions are cumulative, they can be used also as interface-specific
4118: options and there is a short variant <cf>dnssl <m/domain/</cf> that just
4119: specifies one DNS search domain.
4120:
4121: <tag><label id="radv-trigger">trigger <m/prefix/</tag>
4122: RAdv protocol could be configured to change its behavior based on
4123: availability of routes. When this option is used, the protocol waits in
4124: suppressed state until a <it/trigger route/ (for the specified network)
4125: is exported to the protocol, the protocol also returns to suppressed
4126: state if the <it/trigger route/ disappears. Note that route export
4127: depends on specified export filter, as usual. This option could be used,
4128: e.g., for handling failover in multihoming scenarios.
4129:
4130: During suppressed state, router advertisements are generated, but with
4131: some fields zeroed. Exact behavior depends on which fields are zeroed,
4132: this can be configured by <cf/sensitive/ option for appropriate
4133: fields. By default, just <cf/default lifetime/ (also called <cf/router
4134: lifetime/) is zeroed, which means hosts cannot use the router as a
4135: default router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
4136: also be configured as <cf/sensitive/ for a prefix, which would cause
4137: autoconfigured IPs to be deprecated or even removed.
4138:
4139: <tag><label id="radv-propagate-routes">propagate routes <m/switch/</tag>
4140: This option controls propagation of more specific routes, as defined in
4141: <rfc id="4191">. If enabled, all routes exported to the RAdv protocol,
4142: with the exception of the trigger prefix, are added to advertisments as
4143: additional options. The lifetime and preference of advertised routes can
4144: be set individually by <cf/ra_lifetime/ and <cf/ra_preference/ route
4145: attributes, or per interface by <cf/route lifetime/ and
4146: <cf/route preference/ options. Default: disabled.
4147:
4148: Note that the RFC discourages from sending more than 17 routes and
4149: recommends the routes to be configured manually.
4150: </descrip>
4151:
4152: <p>Interface specific options:
4153:
4154: <descrip>
4155: <tag><label id="radv-iface-max-ra-interval">max ra interval <m/expr/</tag>
4156: Unsolicited router advertisements are sent in irregular time intervals.
4157: This option specifies the maximum length of these intervals, in seconds.
4158: Valid values are 4-1800. Default: 600
4159:
4160: <tag><label id="radv-iface-min-ra-interval">min ra interval <m/expr/</tag>
4161: This option specifies the minimum length of that intervals, in seconds.
4162: Must be at least 3 and at most 3/4 * <cf/max ra interval/. Default:
4163: about 1/3 * <cf/max ra interval/.
4164:
4165: <tag><label id="radv-iface-min-delay">min delay <m/expr/</tag>
4166: The minimum delay between two consecutive router advertisements, in
4167: seconds. Default: 3
4168:
4169: <tag><label id="radv-solicited-ra-unicast">solicited ra unicast <m/switch/</tag>
4170: Solicited router advertisements are usually sent to all-nodes multicast
4171: group like unsolicited ones, but the router can be configured to send
4172: them as unicast directly to soliciting nodes instead. This is especially
4173: useful on wireless networks (see <rfc id="7772">). Default: no
4174:
4175: <tag><label id="radv-iface-managed">managed <m/switch/</tag>
4176: This option specifies whether hosts should use DHCPv6 for IP address
4177: configuration. Default: no
4178:
4179: <tag><label id="radv-iface-other-config">other config <m/switch/</tag>
4180: This option specifies whether hosts should use DHCPv6 to receive other
4181: configuration information. Default: no
4182:
4183: <tag><label id="radv-iface-link-mtu">link mtu <m/expr/</tag>
4184: This option specifies which value of MTU should be used by hosts. 0
4185: means unspecified. Default: 0
4186:
4187: <tag><label id="radv-iface-reachable-time">reachable time <m/expr/</tag>
4188: This option specifies the time (in milliseconds) how long hosts should
4189: assume a neighbor is reachable (from the last confirmation). Maximum is
4190: 3600000, 0 means unspecified. Default 0.
4191:
4192: <tag><label id="radv-iface-retrans-timer">retrans timer <m/expr/</tag>
4193: This option specifies the time (in milliseconds) how long hosts should
4194: wait before retransmitting Neighbor Solicitation messages. 0 means
4195: unspecified. Default 0.
4196:
4197: <tag><label id="radv-iface-current-hop-limit">current hop limit <m/expr/</tag>
4198: This option specifies which value of Hop Limit should be used by
4199: hosts. Valid values are 0-255, 0 means unspecified. Default: 64
4200:
4201: <tag><label id="radv-iface-default-lifetime">default lifetime <m/expr/ [sensitive <m/switch/]</tag>
4202: This option specifies the time (in seconds) how long (since the receipt
4203: of RA) hosts may use the router as a default router. 0 means do not use
4204: as a default router. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
4205: Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes.
4206:
4207: <tag><label id="radv-iface-default-preference">default preference low|medium|high</tag>
4208: This option specifies the Default Router Preference value to advertise
4209: to hosts. Default: medium.
4210:
4211: <tag><label id="radv-iface-route-lifetime">route lifetime <m/expr/ [sensitive <m/switch/]</tag>
4212: This option specifies the default value of advertised lifetime for
4213: specific routes; i.e., the time (in seconds) for how long (since the
4214: receipt of RA) hosts should consider these routes valid. A special value
4215: 0xffffffff represents infinity. The lifetime can be overriden on a per
4216: route basis by the <ref id="rta-ra-lifetime" name="ra_lifetime"> route
4217: attribute. Default: 3 * <cf/max ra interval/, <cf/sensitive/ no.
4218:
4219: For the <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
4220: If <cf/sensitive/ is enabled, even the routes with the <cf/ra_lifetime/
4221: attribute become sensitive to the trigger.
4222:
4223: <tag><label id="radv-iface-route-preference">route preference low|medium|high</tag>
4224: This option specifies the default value of advertised route preference
4225: for specific routes. The value can be overriden on a per route basis by
4226: the <ref id="rta-ra-preference" name="ra_preference"> route attribute.
4227: Default: medium.
4228:
4229: <tag><label id="radv-prefix-linger-time">prefix linger time <m/expr/</tag>
4230: When a prefix or a route disappears, it is advertised for some time with
4231: zero lifetime, to inform clients it is no longer valid. This option
4232: specifies the time (in seconds) for how long prefixes are advertised
4233: that way. Default: 3 * <cf/max ra interval/.
4234:
4235: <tag><label id="radv-route-linger-time">route linger time <m/expr/</tag>
4236: When a prefix or a route disappears, it is advertised for some time with
4237: zero lifetime, to inform clients it is no longer valid. This option
4238: specifies the time (in seconds) for how long routes are advertised
4239: that way. Default: 3 * <cf/max ra interval/.
4240:
4241: <tag><label id="radv-iface-rdnss-local">rdnss local <m/switch/</tag>
4242: Use only local (interface-specific) RDNSS definitions for this
4243: interface. Otherwise, both global and local definitions are used. Could
4244: also be used to disable RDNSS for given interface if no local definitons
4245: are specified. Default: no.
4246:
4247: <tag><label id="radv-iface-dnssl-local">dnssl local <m/switch/</tag>
4248: Use only local DNSSL definitions for this interface. See <cf/rdnss local/
4249: option above. Default: no.
4250: </descrip>
4251:
4252: <p>Prefix specific options
4253:
4254: <descrip>
4255: <tag><label id="radv-prefix-skip">skip <m/switch/</tag>
4256: This option allows to specify that given prefix should not be
4257: advertised. This is useful for making exceptions from a default policy
4258: of advertising all prefixes. Note that for withdrawing an already
4259: advertised prefix it is more useful to advertise it with zero valid
4260: lifetime. Default: no
4261:
4262: <tag><label id="radv-prefix-onlink">onlink <m/switch/</tag>
4263: This option specifies whether hosts may use the advertised prefix for
4264: onlink determination. Default: yes
4265:
4266: <tag><label id="radv-prefix-autonomous">autonomous <m/switch/</tag>
4267: This option specifies whether hosts may use the advertised prefix for
4268: stateless autoconfiguration. Default: yes
4269:
4270: <tag><label id="radv-prefix-valid-lifetime">valid lifetime <m/expr/ [sensitive <m/switch/]</tag>
4271: This option specifies the time (in seconds) how long (after the
4272: receipt of RA) the prefix information is valid, i.e., autoconfigured
4273: IP addresses can be assigned and hosts with that IP addresses are
4274: considered directly reachable. 0 means the prefix is no longer
4275: valid. For <cf/sensitive/ option, see <ref id="radv-trigger" name="trigger">.
4276: Default: 86400 (1 day), <cf/sensitive/ no.
4277:
4278: <tag><label id="radv-prefix-preferred-lifetime">preferred lifetime <m/expr/ [sensitive <m/switch/]</tag>
4279: This option specifies the time (in seconds) how long (after the
4280: receipt of RA) IP addresses generated from the prefix using stateless
4281: autoconfiguration remain preferred. For <cf/sensitive/ option,
4282: see <ref id="radv-trigger" name="trigger">. Default: 14400 (4 hours),
4283: <cf/sensitive/ no.
4284: </descrip>
4285:
4286: <p>RDNSS specific options:
4287:
4288: <descrip>
4289: <tag><label id="radv-rdnss-ns">ns <m/address/</tag>
4290: This option specifies one recursive DNS server. Can be used multiple
4291: times for multiple servers. It is mandatory to have at least one
4292: <cf/ns/ option in <cf/rdnss/ definition.
4293:
4294: <tag><label id="radv-rdnss-lifetime">lifetime [mult] <m/expr/</tag>
4295: This option specifies the time how long the RDNSS information may be
4296: used by clients after the receipt of RA. It is expressed either in
4297: seconds or (when <cf/mult/ is used) in multiples of <cf/max ra
4298: interval/. Note that RDNSS information is also invalidated when
4299: <cf/default lifetime/ expires. 0 means these addresses are no longer
4300: valid DNS servers. Default: 3 * <cf/max ra interval/.
4301: </descrip>
4302:
4303: <p>DNSSL specific options:
4304:
4305: <descrip>
4306: <tag><label id="radv-dnssl-domain">domain <m/address/</tag>
4307: This option specifies one DNS search domain. Can be used multiple times
4308: for multiple domains. It is mandatory to have at least one <cf/domain/
4309: option in <cf/dnssl/ definition.
4310:
4311: <tag><label id="radv-dnssl-lifetime">lifetime [mult] <m/expr/</tag>
4312: This option specifies the time how long the DNSSL information may be
4313: used by clients after the receipt of RA. Details are the same as for
4314: RDNSS <cf/lifetime/ option above. Default: 3 * <cf/max ra interval/.
4315: </descrip>
4316:
4317: <sect1>Attributes
4318: <label id="radv-attr">
4319:
4320: <p>RAdv defines two route attributes:
4321:
4322: <descrip>
4323: <tag><label id="rta-ra-preference">enum ra_preference</tag>
4324: The preference of the route. The value can be <it/RA_PREF_LOW/,
4325: <it/RA_PREF_MEDIUM/ or <it/RA_PREF_HIGH/. If the attribute is not set,
4326: the <ref id="radv-iface-route-preference" name="route preference">
4327: option is used.
4328:
4329: <tag><label id="rta-ra-lifetime">int ra_lifetime</tag>
4330: The advertised lifetime of the route, in seconds. The special value of
4331: 0xffffffff represents infinity. If the attribute is not set, the
4332: <ref id="radv-iface-route-lifetime" name="route lifetime">
4333: option is used.
4334: </descrip>
4335:
4336: <sect1>Example
4337: <label id="radv-exam">
4338:
4339: <p><code>
4340: ipv6 table radv_routes; # Manually configured routes go here
4341:
4342: protocol static {
4343: ipv6 { table radv_routes; };
4344:
4345: route 2001:0DB8:4000::/48 unreachable;
4346: route 2001:0DB8:4010::/48 unreachable;
4347:
4348: route 2001:0DB8:4020::/48 unreachable {
4349: ra_preference = RA_PREF_HIGH;
4350: ra_lifetime = 3600;
4351: };
4352: }
4353:
4354: protocol radv {
4355: propagate routes yes; # Propagate the routes from the radv_routes table
4356: ipv6 { table radv_routes; export all; };
4357:
4358: interface "eth2" {
4359: max ra interval 5; # Fast failover with more routers
4360: managed yes; # Using DHCPv6 on eth2
4361: prefix ::/0 {
4362: autonomous off; # So do not autoconfigure any IP
4363: };
4364: };
4365:
4366: interface "eth*"; # No need for any other options
4367:
4368: prefix 2001:0DB8:1234::/48 {
4369: preferred lifetime 0; # Deprecated address range
4370: };
4371:
4372: prefix 2001:0DB8:2000::/48 {
4373: autonomous off; # Do not autoconfigure
4374: };
4375:
4376: rdnss 2001:0DB8:1234::10; # Short form of RDNSS
4377:
4378: rdnss {
4379: lifetime mult 10;
4380: ns 2001:0DB8:1234::11;
4381: ns 2001:0DB8:1234::12;
4382: };
4383:
4384: dnssl {
4385: lifetime 3600;
4386: domain "abc.com";
4387: domain "xyz.com";
4388: };
4389: }
4390: </code>
4391:
4392:
4393: <sect>RIP
4394: <label id="rip">
4395:
4396: <sect1>Introduction
4397: <label id="rip-intro">
4398:
4399: <p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol,
4400: where each router broadcasts (to all its neighbors) distances to all networks it
4401: can reach. When a router hears distance to another network, it increments it and
4402: broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some
4403: network goes unreachable, routers keep telling each other that its distance is
4404: the original distance plus 1 (actually, plus interface metric, which is usually
4405: one). After some time, the distance reaches infinity (that's 15 in RIP) and all
4406: routers know that network is unreachable. RIP tries to minimize situations where
4407: counting to infinity is necessary, because it is slow. Due to infinity being 16,
4408: you can't use RIP on networks where maximal distance is higher than 15
4409: hosts.
4410:
4411: <p>BIRD supports RIPv1 (<rfc id="1058">), RIPv2 (<rfc id="2453">), RIPng (<rfc
4412: id="2080">), and RIP cryptographic authentication (<rfc id="4822">).
4413:
4414: <p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
4415: convergence, big network load and inability to handle larger networks makes it
4416: pretty much obsolete. It is still usable on very small networks.
4417:
4418: <sect1>Configuration
4419: <label id="rip-config">
4420:
4421: <p>RIP configuration consists mainly of common protocol options and interface
4422: definitions, most RIP options are interface specific. RIPng (RIP for IPv6)
4423: protocol instance can be configured by using <cf/rip ng/ instead of just
4424: <cf/rip/ as a protocol type.
4425:
4426: <p>RIP needs one IPv4 channel. RIPng needs one IPv6 channel. If no channel is
4427: configured, appropriate channel is defined with default parameters.
4428:
4429: <code>
4430: protocol rip [ng] [<name>] {
4431: infinity <number>;
4432: ecmp <switch> [limit <number>];
4433: interface <interface pattern> {
4434: metric <number>;
4435: mode multicast|broadcast;
4436: passive <switch>;
4437: address <ip>;
4438: port <number>;
4439: version 1|2;
4440: split horizon <switch>;
4441: poison reverse <switch>;
4442: check zero <switch>;
4443: update time <number>;
4444: timeout time <number>;
4445: garbage time <number>;
4446: ecmp weight <number>;
4447: ttl security <switch>; | tx only;
4448: tx class|dscp <number>;
4449: tx priority <number>;
4450: rx buffer <number>;
4451: tx length <number>;
4452: check link <switch>;
4453: authentication none|plaintext|cryptographic;
4454: password "<text>";
4455: password "<text>" {
4456: id <num>;
4457: generate from "<date>";
4458: generate to "<date>";
4459: accept from "<date>";
4460: accept to "<date>";
4461: from "<date>";
4462: to "<date>";
4463: algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 );
4464: };
4465: };
4466: }
4467: </code>
4468:
4469: <descrip>
4470: <tag><label id="rip-infinity">infinity <M>number</M></tag>
4471: Selects the distance of infinity. Bigger values will make
4472: protocol convergence even slower. The default value is 16.
4473:
4474: <tag><label id="rip-ecmp">ecmp <M>switch</M> [limit <M>number</M>]</tag>
4475: This option specifies whether RIP is allowed to generate ECMP
4476: (equal-cost multipath) routes. Such routes are used when there are
4477: several directions to the destination, each with the same (computed)
4478: cost. This option also allows to specify a limit on maximum number of
4479: nexthops in one route. By default, ECMP is enabled if supported by
4480: Kernel. Default value of the limit is 16.
4481:
4482: <tag><label id="rip-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
4483: Interface definitions specify a set of interfaces on which the
4484: protocol is activated and contain interface specific options.
4485: See <ref id="proto-iface" name="interface"> common options for
4486: detailed description.
4487: </descrip>
4488:
4489: <p>Interface specific options:
4490:
4491: <descrip>
4492: <tag><label id="rip-iface-metric">metric <m/num/</tag>
4493: This option specifies the metric of the interface. When a route is
4494: received from the interface, its metric is increased by this value
4495: before further processing. Valid values are 1-255, but values higher
4496: than infinity has no further meaning. Default: 1.
4497:
4498: <tag><label id="rip-iface-mode">mode multicast|broadcast</tag>
4499: This option selects the mode for RIP to use on the interface. The
4500: default is multicast mode for RIPv2 and broadcast mode for RIPv1.
4501: RIPng always uses the multicast mode.
4502:
4503: <tag><label id="rip-iface-passive">passive <m/switch/</tag>
4504: Passive interfaces receive routing updates but do not transmit any
4505: messages. Default: no.
4506:
4507: <tag><label id="rip-iface-address">address <m/ip/</tag>
4508: This option specifies a destination address used for multicast or
4509: broadcast messages, the default is the official RIP (224.0.0.9) or RIPng
4510: (ff02::9) multicast address, or an appropriate broadcast address in the
4511: broadcast mode.
4512:
4513: <tag><label id="rip-iface-port">port <m/number/</tag>
4514: This option selects an UDP port to operate on, the default is the
4515: official RIP (520) or RIPng (521) port.
4516:
4517: <tag><label id="rip-iface-version">version 1|2</tag>
4518: This option selects the version of RIP used on the interface. For RIPv1,
4519: automatic subnet aggregation is not implemented, only classful network
4520: routes and host routes are propagated. Note that BIRD allows RIPv1 to be
4521: configured with features that are defined for RIPv2 only, like
4522: authentication or using multicast sockets. The default is RIPv2 for IPv4
4523: RIP, the option is not supported for RIPng, as no further versions are
4524: defined.
4525:
4526: <tag><label id="rip-iface-version-only">version only <m/switch/</tag>
4527: Regardless of RIP version configured for the interface, BIRD accepts
4528: incoming packets of any RIP version. This option restrict accepted
4529: packets to the configured version. Default: no.
4530:
4531: <tag><label id="rip-iface-split-horizon">split horizon <m/switch/</tag>
4532: Split horizon is a scheme for preventing routing loops. When split
4533: horizon is active, routes are not regularly propagated back to the
4534: interface from which they were received. They are either not propagated
4535: back at all (plain split horizon) or propagated back with an infinity
4536: metric (split horizon with poisoned reverse). Therefore, other routers
4537: on the interface will not consider the router as a part of an
4538: independent path to the destination of the route. Default: yes.
4539:
4540: <tag><label id="rip-iface-poison-reverse">poison reverse <m/switch/</tag>
4541: When split horizon is active, this option specifies whether the poisoned
4542: reverse variant (propagating routes back with an infinity metric) is
4543: used. The poisoned reverse has some advantages in faster convergence,
4544: but uses more network traffic. Default: yes.
4545:
4546: <tag><label id="rip-iface-check-zero">check zero <m/switch/</tag>
4547: Received RIPv1 packets with non-zero values in reserved fields should
4548: be discarded. This option specifies whether the check is performed or
4549: such packets are just processed as usual. Default: yes.
4550:
4551: <tag><label id="rip-iface-update-time">update time <m/number/</tag>
4552: Specifies the number of seconds between periodic updates. A lower number
4553: will mean faster convergence but bigger network load. Default: 30.
4554:
4555: <tag><label id="rip-iface-timeout-time">timeout time <m/number/</tag>
4556: Specifies the time interval (in seconds) between the last received route
4557: announcement and the route expiration. After that, the network is
4558: considered unreachable, but still is propagated with infinity distance.
4559: Default: 180.
4560:
4561: <tag><label id="rip-iface-garbage-time">garbage time <m/number/</tag>
4562: Specifies the time interval (in seconds) between the route expiration
4563: and the removal of the unreachable network entry. The garbage interval,
4564: when a route with infinity metric is propagated, is used for both
4565: internal (after expiration) and external (after withdrawal) routes.
4566: Default: 120.
4567:
4568: <tag><label id="rip-iface-ecmp-weight">ecmp weight <m/number/</tag>
4569: When ECMP (multipath) routes are allowed, this value specifies a
4570: relative weight used for nexthops going through the iface. Valid
4571: values are 1-256. Default value is 1.
4572:
4573: <tag><label id="rip-iface-auth">authentication none|plaintext|cryptographic</tag>
4574: Selects authentication method to be used. <cf/none/ means that packets
4575: are not authenticated at all, <cf/plaintext/ means that a plaintext
4576: password is embedded into each packet, and <cf/cryptographic/ means that
4577: packets are authenticated using some cryptographic hash function
4578: selected by option <cf/algorithm/ for each key. The default
4579: cryptographic algorithm for RIP keys is Keyed-MD5. If you set
4580: authentication to not-none, it is a good idea to add <cf>password</cf>
4581: section. Default: none.
4582:
4583: <tag><label id="rip-iface-pass">password "<m/text/"</tag>
4584: Specifies a password used for authentication. See <ref id="proto-pass"
4585: name="password"> common option for detailed description.
4586:
4587: <tag><label id="rip-iface-ttl-security">ttl security [<m/switch/ | tx only]</tag>
4588: TTL security is a feature that protects routing protocols from remote
4589: spoofed packets by using TTL 255 instead of TTL 1 for protocol packets
4590: destined to neighbors. Because TTL is decremented when packets are
4591: forwarded, it is non-trivial to spoof packets with TTL 255 from remote
4592: locations.
4593:
4594: If this option is enabled, the router will send RIP packets with TTL 255
4595: and drop received packets with TTL less than 255. If this option si set
4596: to <cf/tx only/, TTL 255 is used for sent packets, but is not checked
4597: for received packets. Such setting does not offer protection, but offers
4598: compatibility with neighbors regardless of whether they use ttl
4599: security.
4600:
4601: For RIPng, TTL security is a standard behavior (required by <rfc
4602: id="2080">) and therefore default value is yes. For IPv4 RIP, default
4603: value is no.
4604:
4605: <tag><label id="rip-iface-tx-class">tx class|dscp|priority <m/number/</tag>
4606: These options specify the ToS/DiffServ/Traffic class/Priority of the
4607: outgoing RIP packets. See <ref id="proto-tx-class" name="tx class"> common
4608: option for detailed description.
4609:
4610: <tag><label id="rip-iface-rx-buffer">rx buffer <m/number/</tag>
4611: This option specifies the size of buffers used for packet processing.
4612: The buffer size should be bigger than maximal size of received packets.
4613: The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
4614:
4615: <tag><label id="rip-iface-tx-length">tx length <m/number/</tag>
4616: This option specifies the maximum length of generated RIP packets. To
4617: avoid IP fragmentation, it should not exceed the interface MTU value.
4618: The default value is 532 for IPv4 RIP and interface MTU value for RIPng.
4619:
4620: <tag><label id="rip-iface-check-link">check link <m/switch/</tag>
4621: If set, the hardware link state (as reported by OS) is taken into
4622: consideration. When the link disappears (e.g. an ethernet cable is
4623: unplugged), neighbors are immediately considered unreachable and all
4624: routes received from them are withdrawn. It is possible that some
4625: hardware drivers or platforms do not implement this feature.
4626: Default: yes.
4627: </descrip>
4628:
4629: <sect1>Attributes
4630: <label id="rip-attr">
4631:
4632: <p>RIP defines two route attributes:
4633:
4634: <descrip>
4635: <tag><label id="rta-rip-metric">int rip_metric</tag>
4636: RIP metric of the route (ranging from 0 to <cf/infinity/). When routes
4637: from different RIP instances are available and all of them have the same
4638: preference, BIRD prefers the route with lowest <cf/rip_metric/. When a
4639: non-RIP route is exported to RIP, the default metric is 1.
4640:
4641: <tag><label id="rta-rip-tag">int rip_tag</tag>
4642: RIP route tag: a 16-bit number which can be used to carry additional
4643: information with the route (for example, an originating AS number in
4644: case of external routes). When a non-RIP route is exported to RIP, the
4645: default tag is 0.
4646: </descrip>
4647:
4648: <sect1>Example
4649: <label id="rip-exam">
4650:
4651: <p><code>
4652: protocol rip {
4653: ipv4 {
4654: import all;
4655: export all;
4656: };
4657: interface "eth*" {
4658: metric 2;
4659: port 1520;
4660: mode multicast;
4661: update time 12;
4662: timeout time 60;
4663: authentication cryptographic;
4664: password "secret" { algorithm hmac sha256; };
4665: };
4666: }
4667: </code>
4668:
4669:
4670: <sect>RPKI
4671: <label id="rpki">
4672:
4673: <sect1>Introduction
4674:
4675: <p>The Resource Public Key Infrastructure (RPKI) is mechanism for origin
4676: validation of BGP routes (RFC 6480). BIRD supports only so-called RPKI-based
4677: origin validation. There is implemented RPKI to Router (RPKI-RTR) protocol (RFC
4678: 6810). It uses some of the RPKI data to allow a router to verify that the
4679: autonomous system announcing an IP address prefix is in fact authorized to do
4680: so. This is not crypto checked so can be violated. But it should prevent the
4681: vast majority of accidental hijackings on the Internet today, e.g. the famous
4682: Pakastani accidental announcement of YouTube's address space.
4683:
4684: <p>The RPKI-RTR protocol receives and maintains a set of ROAs from a cache
4685: server (also called validator). You can validate routes (RFC 6483) using
4686: function <cf/roa_check()/ in filter and set it as import filter at the BGP
4687: protocol. BIRD should re-validate all of affected routes after RPKI update by
4688: RFC 6811, but we don't support it yet! You can use a BIRD's client command
4689: <cf>reload in <m/bgp_protocol_name/</cf> for manual call of revalidation of all
4690: routes.
4691:
4692: <sect1>Supported transports
4693: <p>
4694: <itemize>
4695: <item>Unprotected transport over TCP uses a port 323. The cache server
4696: and BIRD router should be on the same trusted and controlled network
4697: for security reasons.
4698: <item>SSHv2 encrypted transport connection uses the normal SSH port
4699: 22.
4700: </itemize>
4701:
4702: <sect1>Configuration
4703:
4704: <p>We currently support just one cache server per protocol. However you can
4705: define more RPKI protocols generally.
4706:
4707: <code>
4708: protocol rpki [<name>] {
4709: roa4 { table <tab>; };
4710: roa6 { table <tab>; };
4711: remote <ip> | "<domain>" [port <num>];
4712: port <num>;
4713: refresh [keep] <num>;
4714: retry [keep] <num>;
4715: expire [keep] <num>;
4716: transport tcp;
4717: transport ssh {
4718: bird private key "</path/to/id_rsa>";
4719: remote public key "</path/to/known_host>";
4720: user "<name>";
4721: };
4722: }
4723: </code>
4724:
4725: <p>Alse note that you have to specify the ROA channel. If you want to import
4726: only IPv4 prefixes you have to specify only roa4 channel. Similarly with IPv6
4727: prefixes only. If you want to fetch both IPv4 and even IPv6 ROAs you have to
4728: specify both channels.
4729:
4730: <sect2>RPKI protocol options
4731: <p>
4732: <descrip>
4733: <tag>remote <m/ip/ | "<m/hostname/" [port <m/num/]</tag> Specifies
4734: a destination address of the cache server. Can be specified by an IP
4735: address or by full domain name string. Only one cache can be specified
4736: per protocol. This option is required.
4737:
4738: <tag>port <m/num/</tag> Specifies the port number. The default port
4739: number is 323 for transport without any encryption and 22 for transport
4740: with SSH encryption.
4741:
4742: <tag>refresh [keep] <m/num/</tag> Time period in seconds. Tells how
4743: long to wait before next attempting to poll the cache using a Serial
4744: Query or a Reset Query packet. Must be lower than 86400 seconds (one
4745: day). Too low value can caused a false positive detection of
4746: network connection problems. A keyword <cf/keep/ suppresses updating
4747: this value by a cache server.
4748: Default: 3600 seconds
4749:
4750: <tag>retry [keep] <m/num/</tag> Time period in seconds between a failed
4751: Serial/Reset Query and a next attempt. Maximum allowed value is 7200
4752: seconds (two hours). Too low value can caused a false positive
4753: detection of network connection problems. A keyword <cf/keep/
4754: suppresses updating this value by a cache server.
4755: Default: 600 seconds
4756:
4757: <tag>expire [keep] <m/num/</tag> Time period in seconds. Received
4758: records are deleted if the client was unable to successfully refresh
4759: data for this time period. Must be in range from 600 seconds (ten
4760: minutes) to 172800 seconds (two days). A keyword <cf/keep/
4761: suppresses updating this value by a cache server.
4762: Default: 7200 seconds
4763:
4764: <tag>transport tcp</tag> Unprotected transport over TCP. It's a default
4765: transport. Should be used only on secure private networks.
4766: Default: tcp
4767:
4768: <tag>transport ssh { <m/SSH transport options.../ }</tag> It enables a
4769: SSHv2 transport encryption. Cannot be combined with a TCP transport.
4770: Default: off
4771: </descrip>
4772:
4773: <sect3>SSH transport options
4774: <p>
4775: <descrip>
4776: <tag>bird private key "<m>/path/to/id_rsa</m>"</tag>
4777: A path to the BIRD's private SSH key for authentication.
4778: It can be a <cf><m>id_rsa</m></cf> file.
4779:
4780: <tag>remote public key "<m>/path/to/known_host</m>"</tag>
4781: A path to the cache's public SSH key for verification identity
4782: of the cache server. It could be a path to <cf><m>known_host</m></cf> file.
4783:
4784: <tag>user "<m/name/"</tag>
4785: A SSH user name for authentication. This option is a required.
4786: </descrip>
4787:
4788: <sect1>Examples
4789: <sect2>BGP origin validation
4790: <p>Policy: Don't import <cf/ROA_INVALID/ routes.
4791: <code>
4792: roa4 table r4;
4793: roa6 table r6;
4794:
4795: protocol rpki {
4796: debug all;
4797:
4798: roa4 { table r4; };
4799: roa6 { table r6; };
4800:
4801: # Please, do not use rpki-validator.realmv6.org in production
4802: remote "rpki-validator.realmv6.org" port 8282;
4803:
4804: retry keep 5;
4805: refresh keep 30;
4806: expire 600;
4807: }
4808:
4809: filter peer_in_v4 {
4810: if (roa_check(r4, net, bgp_path.last) = ROA_INVALID) then
4811: {
4812: print "Ignore RPKI invalid ", net, " for ASN ", bgp_path.last;
4813: reject;
4814: }
4815: accept;
4816: }
4817:
4818: protocol bgp {
4819: debug all;
4820: local as 65000;
4821: neighbor 192.168.2.1 as 65001;
4822: ipv4 {
4823: import filter peer_in_v4;
4824: export none;
4825: };
4826: }
4827: </code>
4828:
4829: <sect2>SSHv2 transport encryption
4830: <p>
4831: <code>
4832: roa4 table r4;
4833: roa6 table r6;
4834:
4835: protocol rpki {
4836: debug all;
4837:
4838: roa4 { table r4; };
4839: roa6 { table r6; };
4840:
4841: remote 127.0.0.1 port 2345;
4842: transport ssh {
4843: bird private key "/home/birdgeek/.ssh/id_rsa";
4844: remote public key "/home/birdgeek/.ssh/known_hosts";
4845: user "birdgeek";
4846: };
4847:
4848: # Default interval values
4849: }
4850: </code>
4851:
4852:
4853: <sect>Static
4854: <label id="static">
4855:
4856: <p>The Static protocol doesn't communicate with other routers in the network,
4857: but instead it allows you to define routes manually. This is often used for
4858: specifying how to forward packets to parts of the network which don't use
4859: dynamic routing at all and also for defining sink routes (i.e., those telling to
4860: return packets as undeliverable if they are in your IP block, you don't have any
4861: specific destination for them and you don't want to send them out through the
4862: default route to prevent routing loops).
4863:
4864: <p>There are three classes of definitions in Static protocol configuration --
4865: global options, static route definitions, and per-route options. Usually, the
4866: definition of the protocol contains mainly a list of static routes.
4867: Static routes have no specific attributes.
4868:
4869: <p>Global options:
4870:
4871: <descrip>
4872: <tag><label id="static-check-link">check link <m/switch/</tag>
4873: If set, hardware link states of network interfaces are taken into
4874: consideration. When link disappears (e.g. ethernet cable is unplugged),
4875: static routes directing to that interface are removed. It is possible
4876: that some hardware drivers or platforms do not implement this feature.
4877: Default: off.
4878:
4879: <tag><label id="static-igp-table">igp table <m/name/</tag>
4880: Specifies a table that is used for route table lookups of recursive
4881: routes. Default: the same table as the protocol is connected to.
4882: </descrip>
4883:
4884: <p>Route definitions (each may also contain a block of per-route options):
4885:
4886: <sect1>Regular routes; MPLS switching rules
4887:
4888: <p>There exist several types of routes; keep in mind that <m/prefix/ syntax is
4889: <ref id="type-prefix" name="dependent on network type">.
4890:
4891: <descrip>
4892: <tag>route <m/prefix/ via <m/ip/|<m/"interface"/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag>
4893: Next hop routes may bear one or more <ref id="route-next-hop" name="next hops">.
4894: Every next hop is preceded by <cf/via/ and configured as shown.
4895:
4896: <tag>route <m/prefix/ recursive <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag>
4897: Recursive nexthop resolves the given IP in the configured IGP table and
4898: uses that route's next hop. The MPLS stacks are concatenated; on top is
4899: the IGP's nexthop stack and on bottom is this route's stack.
4900:
4901: <tag>route <m/prefix/ blackhole|unreachable|prohibit</tag>
4902: Special routes specifying to silently drop the packet, return it as
4903: unreachable or return it as administratively prohibited. First two
4904: targets are also known as <cf/drop/ and <cf/reject/.
4905: </descrip>
4906:
4907: <p>When the particular destination is not available (the interface is down or
4908: the next hop of the route is not a neighbor at the moment), Static just
4909: uninstalls the route from the table it is connected to and adds it again as soon
4910: as the destination becomes adjacent again.
4911:
4912: <sect1>Route Origin Authorization
4913:
4914: <p>The ROA config is just <cf>route <m/prefix/ max <m/int/ as <m/int/</cf> with no nexthop.
4915:
4916: <sect1>Flowspec
4917: <label id="flowspec-network-type">
4918:
4919: <p>The flow specification are rules for routers and firewalls for filtering
4920: purpose. It is described by <rfc id="5575">. There are 3 types of arguments:
4921: <m/inet4/ or <m/inet6/ prefixes, bitmasks matching expressions and numbers
4922: matching expressions.
4923:
4924: Bitmasks matching is written using <m/value/<cf>/</cf><m/mask/ or
4925: <cf/!/<m/value/<cf>/</cf><m/mask/ pairs. It means that <cf/(/<m/data/ <cf/&/
4926: <m/mask/<cf/)/ is or is not equal to <m/value/.
4927:
4928: Numbers matching is a matching sequence of numbers and ranges separeted by a
4929: commas (<cf/,/) (e.g. <cf/10,20,30/). Ranges can be written using double dots
4930: <cf/../ notation (e.g. <cf/80..90,120..124/). An alternative notation are
4931: sequence of one or more pairs of relational operators and values separated by
4932: logical operators <cf/&&/ or <cf/||/. Allowed relational operators are <cf/=/,
4933: <cf/!=/, <cf/</, <cf/<=/, <cf/>/, <cf/>=/, <cf/true/ and <cf/false/.
4934:
4935: <sect2>IPv4 Flowspec
4936:
4937: <p><descrip>
4938: <tag><label id="flow-dst">dst <m/inet4/</tag>
4939: Set a matching destination prefix (e.g. <cf>dst 192.168.0.0/16</cf>).
4940: Only this option is mandatory in IPv4 Flowspec.
4941:
4942: <tag><label id="flow-src">src <m/inet4/</tag>
4943: Set a matching source prefix (e.g. <cf>src 10.0.0.0/8</cf>).
4944:
4945: <tag><label id="flow-proto">proto <m/numbers-match/</tag>
4946: Set a matching IP protocol numbers (e.g. <cf/proto 6/).
4947:
4948: <tag><label id="flow-port">port <m/numbers-match/</tag>
4949: Set a matching source or destination TCP/UDP port numbers (e.g.
4950: <cf>port 1..1023,1194,3306</cf>).
4951:
4952: <tag><label id="flow-dport">dport <m/numbers-match/</tag>
4953: Set a mating destination port numbers (e.g. <cf>dport 49151</cf>).
4954:
4955: <tag><label id="flow-sport">sport <m/numbers-match/</tag>
4956: Set a matching source port numbers (e.g. <cf>sport = 0</cf>).
4957:
4958: <tag><label id="flow-icmp-type">icmp type <m/numbers-match/</tag>
4959: Set a matching type field number of an ICMP packet (e.g. <cf>icmp type
4960: 3</cf>)
4961:
4962: <tag><label id="flow-icmp-code">icmp code <m/numbers-match/</tag>
4963: Set a matching code field number of an ICMP packet (e.g. <cf>icmp code
4964: 1</cf>)
4965:
4966: <tag><label id="flow-tcp-flags">tcp flags <m/bitmask-match/</tag>
4967: Set a matching bitmask for TCP header flags (aka control bits) (e.g.
4968: <cf>tcp flags 0x03/0x0f;</cf>). The maximum length of mask is 12 bits
4969: (0xfff).
4970:
4971: <tag><label id="flow-length">length <m/numbers-match/</tag>
4972: Set a matching packet length (e.g. <cf>length > 1500;</cf>)
4973:
4974: <tag><label id="flow-dscp">dscp <m/numbers-match/</tag>
4975: Set a matching DiffServ Code Point number (e.g. <cf>length > 1500;</cf>).
4976:
4977: <tag><label id="flow-fragment">fragment <m/fragmentation-type/</tag>
4978: Set a matching type of packet fragmentation. Allowed fragmentation
4979: types are <cf/dont_fragment/, <cf/is_fragment/, <cf/first_fragment/,
4980: <cf/last_fragment/ (e.g. <cf>fragment is_fragment &&
4981: !dont_fragment</cf>).
4982: </descrip>
4983:
4984: <p><code>
4985: protocol static {
4986: flow4;
4987:
4988: route flow4 {
4989: dst 10.0.0.0/8;
4990: port > 24 && < 30 || 40..50,60..70,80 && >= 90;
4991: tcp flags 0x03/0x0f;
4992: length > 1024;
4993: dscp = 63;
4994: fragment dont_fragment, is_fragment || !first_fragment;
4995: };
4996: }
4997: </code>
4998:
4999: <sect2>Differences for IPv6 Flowspec
5000:
5001: <p>Flowspec IPv6 are same as Flowspec IPv4 with a few exceptions.
5002: <itemize>
5003: <item>Prefixes <m/inet6/ can be specified not only with prefix length,
5004: but with prefix <cf/offset/ <m/num/ too (e.g.
5005: <cf>::1234:5678:9800:0000/101 offset 64</cf>). Offset means to don't
5006: care of <m/num/ first bits.
5007: <item>IPv6 Flowspec hasn't mandatory any flowspec component.
5008: <item>In IPv6 packets, there is a matching the last next header value
5009: for a matching IP protocol number (e.g. <cf>next header 6</cf>).
5010: <item>It is not possible to set <cf>dont_fragment</cf> as a type of
5011: packet fragmentation.
5012: </itemize>
5013:
5014: <p><descrip>
5015: <tag><label id="flow6-dst">dst <m/inet6/ [offset <m/num/]</tag>
5016: Set a matching destination IPv6 prefix (e.g. <cf>dst
5017: ::1c77:3769:27ad:a11a/128 offset 64</cf>).
5018:
5019: <tag><label id="flow6-src">src <m/inet6/ [offset <m/num/]</tag>
5020: Set a matching source IPv6 prefix (e.g. <cf>src fe80::/64</cf>).
5021:
5022: <tag><label id="flow6-next-header">next header <m/numbers-match/</tag>
5023: Set a matching IP protocol numbers (e.g. <cf>next header != 6</cf>).
5024:
5025: <tag><label id="flow6-label">label <m/bitmask-match/</tag>
5026: Set a 20-bit bitmask for matching Flow Label field in IPv6 packets
5027: (e.g. <cf>label 0x8e5/0x8e5</cf>).
5028: </descrip>
5029:
5030: <p><code>
5031: protocol static {
5032: flow6 { table myflow6; };
5033:
5034: route flow6 {
5035: dst fec0:1122:3344:5566:7788:99aa:bbcc:ddee/128;
5036: src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63;
5037: next header = 23;
5038: sport > 24 && < 30 || = 40 || 50,60,70..80;
5039: dport = 50;
5040: tcp flags 0x03/0x0f, !0/0xff || 0x33/0x33;
5041: fragment !is_fragment || !first_fragment;
5042: label 0xaaaa/0xaaaa && 0x33/0x33;
5043: };
5044: }
5045: </code>
5046:
5047: <sect1>Per-route options
5048: <p>
5049: <descrip>
5050: <tag><label id="static-route-bfd">bfd <m/switch/</tag>
5051: The Static protocol could use BFD protocol for next hop liveness
5052: detection. If enabled, a BFD session to the route next hop is created
5053: and the static route is BFD-controlled -- the static route is announced
5054: only if the next hop liveness is confirmed by BFD. If the BFD session
5055: fails, the static route is removed. Note that this is a bit different
5056: compared to other protocols, which may use BFD as an advisory mechanism
5057: for fast failure detection but ignores it if a BFD session is not even
5058: established.
5059:
5060: This option can be used for static routes with a direct next hop, or
5061: also for for individual next hops in a static multipath route (see
5062: above). Note that BFD protocol also has to be configured, see
5063: <ref id="bfd" name="BFD"> section for details. Default value is no.
5064:
5065: <tag><label id="static-route-filter"><m/filter expression/</tag>
5066: This is a special option that allows filter expressions to be configured
5067: on per-route basis. Can be used multiple times. These expressions are
5068: evaluated when the route is originated, similarly to the import filter
5069: of the static protocol. This is especially useful for configuring route
5070: attributes, e.g., <cf/ospf_metric1 = 100;/ for a route that will be
5071: exported to the OSPF protocol.
5072: </descrip>
5073:
5074: <sect1>Example static config
5075:
5076: <p><code>
5077: protocol static {
5078: ipv4 { table testable; }; # Connect to a non-default routing table
5079: check link; # Advertise routes only if link is up
5080: route 0.0.0.0/0 via 198.51.100.130; # Default route
5081: route 10.0.0.0/8 # Multipath route
5082: via 198.51.100.10 weight 2
5083: via 198.51.100.20 bfd # BFD-controlled next hop
5084: via 192.0.2.1;
5085: route 203.0.113.0/24 unreachable; # Sink route
5086: route 10.2.0.0/24 via "arc0"; # Secondary network
5087: route 192.168.10.0/24 via 198.51.100.100 {
5088: ospf_metric1 = 20; # Set extended attribute
5089: }
5090: route 192.168.10.0/24 via 198.51.100.100 {
5091: ospf_metric2 = 100; # Set extended attribute
5092: ospf_tag = 2; # Set extended attribute
5093: bfd; # BFD-controlled route
5094: }
5095: }
5096: </code>
5097:
5098:
5099: <chapt>Conclusions
5100: <label id="conclusion">
5101:
5102: <sect>Future work
5103: <label id="future-work">
5104:
5105: <p>Although BIRD supports all the commonly used routing protocols, there are
5106: still some features which would surely deserve to be implemented in future
5107: versions of BIRD:
5108:
5109: <itemize>
5110: <item>Opaque LSA's
5111: <item>Route aggregation and flap dampening
5112: <item>Multicast routing protocols
5113: <item>Ports to other systems
5114: </itemize>
5115:
5116:
5117: <sect>Getting more help
5118: <label id="help">
5119:
5120: <p>If you use BIRD, you're welcome to join the bird-users mailing list
5121: (<HTMLURL URL="mailto:bird-users@network.cz" name="bird-users@network.cz">)
5122: where you can share your experiences with the other users and consult
5123: your problems with the authors. To subscribe to the list, visit
5124: <HTMLURL URL="http://bird.network.cz/?m_list" name="http://bird.network.cz/?m_list">.
5125: The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
5126:
5127: <p>BIRD is a relatively young system and it probably contains some bugs. You can
5128: report any problems to the bird-users list and the authors will be glad to solve
5129: them, but before you do so, please make sure you have read the available
5130: documentation and that you are running the latest version (available at
5131: <HTMLURL URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">).
5132: (Of course, a patch which fixes the bug is always welcome as an attachment.)
5133:
5134: <p>If you want to understand what is going inside, Internet standards are a good
5135: and interesting reading. You can get them from
5136: <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a
5137: nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc"
5138: name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
5139:
5140: <p><it/Good luck!/
5141:
5142: </book>
5143:
5144: <!--
5145: LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
5146: LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
5147: LocalWords: router's eval expr num birdc ctl UNIX if's enums bool int ip GCC
5148: LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
5149: LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
5150: LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC
5151: LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU
5152: LocalWords: uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc
5153: LocalWords: compat multicasts nonbroadcast pointopoint loopback sym stats
5154: LocalWords: Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt
5155: LocalWords: proto wildcard Ondrej Filip
5156: -->
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to bird.sgml CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird2 / doc