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