Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 4116db18

History | View | Annotate | Download (110 KB)

1
<!doctype birddoc system>
2

    
3
<!--
4
	BIRD documentation
5

    
6
This documentation can have 4 forms: sgml (this is master copy), html,
7
ASCII text and dvi/postscript (generated from sgml using
8
sgmltools). You should always edit master copy.
9

    
10
This is a slightly modified linuxdoc dtd.  Anything in <descrip> tags is considered definition of
11
configuration primitives, <cf> is fragment of configuration within normal text, <m> is
12
"meta" information within fragment of configuration - something in config which is not keyword.
13

    
14
    (set-fill-column 100)
15

    
16
    Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
17

    
18
 -->
19

    
20
<book>
21

    
22
<title>BIRD User's Guide
23
<author>
24
Ondrej Filip <it/&lt;feela@network.cz&gt;/,
25
Pavel Machek <it/&lt;pavel@ucw.cz&gt;/,
26
Martin Mares <it/&lt;mj@ucw.cz&gt;/,
27
Ondrej Zajicek <it/&lt;santiago@crfreenet.org&gt;/
28
</author>
29

    
30
<abstract>
31
This document contains user documentation for the BIRD Internet Routing Daemon project.
32
</abstract>
33

    
34
<!-- Table of contents -->
35
<toc>
36

    
37
<!-- Begin the document -->
38

    
39
<chapt>Introduction
40

    
41
<sect>What is BIRD
42

    
43
<p><label id="intro">
44
The name `BIRD' is actually an acronym standing for `BIRD Internet Routing Daemon'.
45
Let's take a closer look at the meaning of the name:
46

    
47
<p><em/BIRD/: Well, we think we have already explained that. It's an acronym standing
48
for `BIRD Internet Routing Daemon', you remember, don't you? :-)
49

    
50
<p><em/Internet Routing/: It's a program (well, a daemon, as you are going to discover in a moment)
51
which works as a dynamic router in an Internet type network (that is, in a network running either
52
the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected
53
networks in order to allow hosts not connected directly to the same local area network to
54
communicate with each other. They also communicate with the other routers in the Internet to discover
55
the topology of the network which allows them to find optimal (in terms of some metric) rules for
56
forwarding of packets (which are called routing tables) and to adapt themselves to the
57
changing conditions such as outages of network links, building of new connections and so on. Most of
58
these routers are costly dedicated devices running obscure firmware which is hard to configure and
59
not open to any changes (on the other hand, their special hardware design allows them to keep up with lots of high-speed network interfaces, better than general-purpose computer does). Fortunately, most operating systems of the UNIX family allow an ordinary 
60
computer to act as a router and forward packets belonging to the other hosts, but only according to
61
a statically configured table.
62

    
63
<p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on
64
background which does the dynamic part of Internet routing, that is it communicates
65
with the other routers, calculates routing tables and sends them to the OS kernel
66
which does the actual packet forwarding. There already exist other such routing
67
daemons: routed (RIP only), GateD (non-free), Zebra<HTMLURL URL="http://www.zebra.org">
68
and MRTD<HTMLURL URL="http://sourceforge.net/projects/mrt">, but their capabilities are
69
limited and they are relatively hard to configure and maintain.
70

    
71
<p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
72
to support all the routing technology used in the today's Internet or planned to be
73
used in near future and to have a clean extensible architecture allowing new routing
74
protocols to be incorporated easily. Among other features, BIRD supports:
75

    
76
<itemize>
77
	<item>both IPv4 and IPv6 protocols
78
	<item>multiple routing tables
79
	<item>the Border Gateway Protocol (BGPv4)
80
	<item>the Routing Information Protocol (RIPv2)
81
	<item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
82
	<item>the Router Advertisements for IPv6 hosts
83
	<item>a virtual protocol for exchange of routes between different routing tables on a single host
84
	<item>a command-line interface allowing on-line control and inspection
85
		of status of the daemon
86
	<item>soft reconfiguration (no need to use complex online commands
87
		to change the configuration, just edit the configuration file
88
		and notify BIRD to re-read it and it will smoothly switch itself
89
		to the new configuration, not disturbing routing protocols
90
		unless they are affected by the configuration changes)
91
	<item>a powerful language for route filtering
92
</itemize>
93

    
94
<p>BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague,
95
Czech Republic as a student project. It can be freely distributed under the terms of the GNU General
96
Public License.
97

    
98
<p>BIRD has been designed to work on all UNIX-like systems. It has
99
been developed and tested under Linux 2.0 to 2.6, and then ported to
100
FreeBSD, NetBSD and OpenBSD, porting to other systems (even non-UNIX
101
ones) should be relatively easy due to its highly modular
102
architecture.
103

    
104
<p>BIRD supports either IPv4 or IPv6 protocol, but have to be compiled
105
separately for each one. Therefore, a dualstack router would run two
106
instances of BIRD (one for IPv4 and one for IPv6), with completely
107
separate setups (configuration files, tools ...).
108

    
109
<sect>Installing BIRD
110

    
111
<p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make) and Perl, installing BIRD should be as easy as:
112

    
113
<code>
114
        ./configure
115
        make
116
        make install
117
        vi /usr/local/etc/bird.conf
118
	bird
119
</code>
120

    
121
<p>You can use <tt>./configure --help</tt> to get a list of configure
122
options. The most important ones are:
123
<tt/--enable-ipv6/ which enables building of an IPv6 version of BIRD,
124
<tt/--with-protocols=/ to produce a slightly smaller BIRD executable by configuring out routing protocols you don't use, and
125
<tt/--prefix=/ to install BIRD to a place different from.
126
<file>/usr/local</file>.
127

    
128
<sect>Running BIRD
129

    
130
<p>You can pass several command-line options to bird:
131

    
132
<descrip>
133
	<tag>-c <m/config name/</tag>
134
	use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
135

    
136
	<tag>-d</tag>
137
	enable debug messages and run bird in foreground.
138

    
139
	<tag>-D <m/filename of debug log/</tag>
140
	log debugging information to given file instead of stderr.
141

    
142
	<tag>-p</tag>
143
	just parse the config file and exit. Return value is zero if the config file is valid,
144
	nonzero if there are some errors.
145

    
146
	<tag>-s <m/name of communication socket/</tag>
147
	use given filename for a  socket for communications with the client, default is <it/prefix/<file>/var/run/bird.ctl</file>.
148

    
149
	<tag>-u <m/user/</tag>
150
	drop privileges and use that user ID, see the next section for details.
151

    
152
	<tag>-g <m/group/</tag>
153
	use that group ID, see the next section for details.
154
</descrip>
155

    
156
<p>BIRD writes messages about its work to log files or syslog (according to config).
157

    
158
<sect>Privileges
159

    
160
<p>BIRD, as a routing daemon, uses several privileged operations (like
161
setting routing table and using raw sockets). Traditionally, BIRD is
162
executed and runs with root privileges, which may be prone to security
163
problems. The recommended way is to use a privilege restriction
164
(options <cf/-u/, <cf/-g/). In that case BIRD is executed with root
165
privileges, but it changes its user and group ID to an unprivileged
166
ones, while using Linux capabilities to retain just required
167
privileges (capabilities CAP_NET_*). Note that the control socket is
168
created before the privileges are dropped, but the config file is read
169
after that. The privilege restriction is not implemented in BSD port
170
of BIRD.
171

    
172
<p>A nonprivileged user (as an argument to <cf/-u/ options) may be the
173
user <cf/nobody/, but it is suggested to use a new dedicated user
174
account (like <cf/bird/). The similar considerations apply for
175
the group option, but there is one more condition -- the users
176
in the same group can use <file/birdc/ to control BIRD.
177

    
178
<p>Finally, there is a possibility to use external tools to run BIRD in
179
an environment with restricted privileges. This may need some
180
configuration, but it is generally easy -- BIRD needs just the
181
standard library, privileges to read the config file and create the
182
control socket and the CAP_NET_* capabilities.
183

    
184
<chapt>About routing tables
185

    
186
<p>BIRD has one or more routing tables which may or may not be
187
synchronized with OS kernel and which may or may not be synchronized with
188
each other (see the Pipe protocol). Each routing table contains a list of
189
known routes. Each route consists of:
190

    
191
<itemize>
192
	<item>network prefix this route is for (network address and prefix length -- the number of bits forming the network part of the address; also known as a netmask)
193
	<item>preference of this route
194
	<item>IP address of router which told us about this route
195
	<item>IP address of router we should forward the packets to
196
	using this route
197
	<item>other attributes common to all routes
198
	<item>dynamic attributes defined by protocols which may or
199
	may not be present (typically protocol metrics)
200
</itemize>
201

    
202
Routing table maintains multiple entries
203
for a network, but at most one entry for one network and one
204
protocol. The entry with the highest preference is used for routing (we
205
will call such an entry the <it/selected route/). If
206
there are more entries with the same preference and they are from the same
207
protocol, the protocol decides (typically according to metrics). If they aren't,
208
an internal ordering is used to break the tie. You can
209
get the list of route attributes in the Route attributes section.
210

    
211
<p>Each protocol is connected to a routing table through two filters
212
which can accept, reject and modify the routes. An <it/export/
213
filter checks routes passed from the routing table to the protocol,
214
an <it/import/ filter checks routes in the opposite direction.
215
When the routing table gets a route from a protocol, it recalculates
216
the selected route and broadcasts it to all protocols connected to
217
the table. The protocols typically send the update to other routers
218
in the network.
219

    
220
<chapt>Configuration
221

    
222
<sect>Introduction
223

    
224
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <it/prefix/<file>/etc/bird.conf</file> (unless the
225
<tt/-c/ command line option is given). Configuration may be changed at user's request: if you modify
226
the config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new
227
config. Then there's the client
228
which allows you to talk with BIRD in an extensive way.
229

    
230
<p>In the config, everything on a line after <cf/#/ or inside <cf>/*
231
*/</cf> is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using
232
the <cf/{ }/ brackets. Each option is terminated by a <cf/;/. Configuration
233
is case sensitive.
234

    
235
<p>Here is an example of a simple config file. It enables
236
synchronization of routing tables with OS kernel, scans for 
237
new network interfaces every 10 seconds and runs RIP on all network interfaces found.
238

    
239

    
240
<code>
241
protocol kernel {
242
	persist;		# Don't remove routes on BIRD shutdown
243
	scan time 20;		# Scan kernel routing table every 20 seconds
244
	export all;		# Default is export none
245
}
246

    
247
protocol device {
248
	scan time 10;		# Scan interfaces every 10 seconds
249
}
250

    
251
protocol rip {
252
	export all;
253
	import all;
254
	interface "*";
255
}
256
</code>
257

    
258

    
259
<sect>Global options
260

    
261
<p><descrip>
262
	<tag>include "<m/filename/"</tag> 
263
	This statement causes inclusion of a new file. The maximal depth is set to 5.
264

    
265
	<tag>log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag> 
266
	Set logging of messages having the given class (either <cf/all/ or <cf/{
267
	error, trace }/ etc.) into selected destination (a file specified as a filename string,
268
	syslog with optional name argument, or the stderr output). Classes are:
269
	<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
270
	<cf/debug/ for debugging messages, 
271
	<cf/trace/ when you want to know what happens in the network, 
272
	<cf/remote/ for messages about misbehavior of remote machines, 
273
	<cf/auth/ about authentication failures,
274
	<cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple
275
	destinations. Default: log everything to the system log.
276

    
277
	<tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
278
	Set global defaults of protocol debugging options. See <cf/debug/ in the following section. Default: off.
279

    
280
	<tag>debug commands <m/number/</tag>
281
	Control logging of client connections (0 for no logging, 1 for
282
	logging of connects and disconnects, 2 and higher for logging of
283
	all client commands). Default: 0.
284

    
285
	<tag>mrtdump "<m/filename/"</tag>
286
	Set MRTdump file name. This option must be specified to allow MRTdump feature.
287
	Default: no dump file.
288

    
289
	<tag>mrtdump protocols all|off|{ states, messages }</tag>
290
	Set global defaults of MRTdump options. See <cf/mrtdump/ in the following section.
291
	Default: off.
292

    
293
	<tag>filter <m/name local variables/{ <m/commands/ }</tag> Define a filter. You can learn more about filters
294
	in the following chapter. 
295

    
296
	<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
297
	about functions in the following chapter.
298
 
299
	<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
300
	instance called <cf><m/name/</cf> (or with a name like "rip5" generated automatically if you don't specify any <cf><m/name/</cf>). You can learn more
301
	about configuring protocols in their own chapters. You can run more than one instance of
302
	most protocols (like RIP or BGP). By default, no instances are configured.
303

    
304
	<tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag>
305
	Define a constant. You can use it later in every place you could use a simple integer or an IP address.
306
	Besides, there are some predefined numeric constants based on /etc/iproute2/rt_* files.
307
	A list of defined constants can be seen (together with other symbols) using 'show symbols' command.
308

    
309
	<tag>router id <m/IPv4 address/</tag> Set BIRD's router ID. It's a world-wide unique identification of your router, usually one of router's IPv4 addresses. Default: in IPv4 version, the lowest IP address of a non-loopback interface. In IPv6 version, this option is mandatory. 
310

    
311
	<tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
312
	This option allows to specify address and port where BGP
313
	protocol should listen. It is global option as listening
314
	socket is common to all BGP instances. Default is to listen on
315
	all addresses (0.0.0.0) and port 179. In IPv6 mode, option
316
	<cf/dual/ can be used to specify that BGP socket should accept
317
	both IPv4 and IPv6 connections (but even in that case, BIRD
318
	would accept IPv6 routes only). Such behavior was default in
319
	older versions of BIRD.
320

    
321
	<tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
322
	This option allows to specify a format of date/time used by
323
	BIRD.  The first argument specifies for which purpose such
324
	format is used. <cf/route/ is a format used in 'show route'
325
	command output, <cf/protocol/ is used in 'show protocols'
326
	command output, <cf/base/ is used for other commands and
327
	<cf/log/ is used in a log file.
328

    
329
	"<m/format1/" is a format string using <it/strftime(3)/
330
	notation (see <it/man strftime/ for details). <m/limit> and
331
	"<m/format2/" allow to specify the second format string for
332
	times in past deeper than <m/limit/ seconds. There are two
333
	shorthands: <cf/iso long/ is a ISO 8601 date/time format
334
	(YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
335
	%T"/. <cf/iso short/ is a variant of ISO 8601 that uses just
336
	the time format (hh:mm:ss) for near times (up to 20 hours in
337
	the past) and the date format (YYYY-MM-DD) for far times. This
338
	is a shorthand for <cf/"%T" 72000 "%F"/.
339

    
340
	By default, BIRD uses an short, ad-hoc format for <cf/route/
341
	and <cf/protocol/ times, and a <cf/iso long/ similar format
342
	(DD-MM-YYYY hh:mm:ss) for <cf/base/ and <cf/log/. These
343
	defaults are here for a compatibility with older versions
344
	and might change in the future.
345

    
346
	<tag>table <m/name/</tag> Create a new routing table. The default
347
	routing table is created implicitly, other routing tables have
348
	to be added by this command.
349

    
350
	<tag>eval <m/expr/</tag> Evaluates given filter expression. It
351
	is used by us for testing of filters.
352
</descrip>
353

    
354
<sect>Protocol options
355

    
356
<p>For each protocol instance, you can configure a bunch of options.
357
Some of them (those described in this section) are generic, some are
358
specific to the protocol (see sections talking about the protocols).
359

    
360
<p>Several options use a <cf><m/switch/</cf> argument. It can be either
361
<cf/on/, <cf/yes/ or a numeric expression with a non-zero value for the
362
option to be enabled or <cf/off/, <cf/no/ or a numeric expression evaluating
363
to zero to disable it. An empty <cf><m/switch/</cf> is equivalent to <cf/on/
364
("silence means agreement").
365

    
366
<descrip>
367
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
368

    
369
	<tag>disabled <m/switch/</tag> Disables the protocol. You can change the disable/enable status from the command
370
	line interface without needing to touch the configuration. Disabled protocols are not activated. Default: protocol is enabled.
371

    
372
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
373
	Set protocol debugging options. If asked, each protocol is capable of
374
	writing trace messages about its work to the log (with category
375
	<cf/trace/). You can either request printing of <cf/all/ trace messages
376
	or only of the types selected: <cf/states/ for protocol state changes
377
	(protocol going up, down, starting, stopping etc.),
378
	<cf/routes/ for routes exchanged with the routing table,
379
	<cf/filters/ for details on route filtering,
380
	<cf/interfaces/ for interface change events sent to the protocol,
381
	<cf/events/ for events internal to the protocol and
382
	<cf/packets/ for packets sent and received by the protocol. Default: off.
383

    
384
	<tag>mrtdump all|off|{ states, messages }</tag>
385

    
386
	Set protocol MRTdump flags. MRTdump is a standard binary
387
	format for logging information from routing protocols and
388
	daemons.  These flags control what kind of information is
389
	logged from the protocol to the MRTdump file (which must be
390
	specified by global <cf/mrtdump/ option, see the previous
391
	section). Although these flags are similar to flags of
392
	<cf/debug/ option, their meaning is different and
393
	protocol-specific. For BGP protocol, <cf/states/ logs BGP
394
	state changes and <cf/messages/ logs received BGP messages.
395
	Other protocols does not support MRTdump yet.
396

    
397
	<tag>router id <m/IPv4 address/</tag> This option can be used
398
	to override global router id for a given protocol. Default:
399
	uses global router id.
400

    
401
	<tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> 
402
	Specify a filter to be used for filtering routes coming from the protocol to the routing table. <cf/all/ is shorthand for <cf/where true/ and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/.
403

    
404
	<tag>export <m/filter/</tag> This is similar to the <cf>import</cf> keyword, except that it
405
	works in the direction from the routing table to the protocol. Default: <cf/none/.
406

    
407
	<tag>description "<m/text/"</tag> This is an optional
408
	description of the protocol. It is displayed as a part of the
409
	output of 'show route all' command.
410

    
411
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
412
</descrip>
413

    
414
<p>There are several options that give sense only with certain protocols:
415

    
416
<descrip>
417
	<tag><label id="dsc-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...] [ { <m/option/ ; [...] } ]</tag>
418

    
419
	Specifies a set of interfaces on which the protocol is activated with
420
	given interface-specific options. A set of interfaces specified by one
421
	interface option is described using an interface pattern. The
422
	interface pattern consists of a sequence of clauses (separated by
423
	commas), each clause may contain a mask, a prefix, or both of them. An
424
	interface matches the clause if its name matches the mask (if
425
	specified) and its address matches the prefix (if specified). Mask is
426
	specified as shell-like pattern. For IPv6, the prefix part of a clause
427
	is generally ignored and interfaces are matched just by their name.
428

    
429
	An interface matches the pattern if it matches any of its
430
	clauses. If the clause begins with <cf/-/, matching interfaces are
431
	excluded. Patterns are parsed left-to-right, thus
432
	<cf/interface "eth0", -"eth*", "*";/ means eth0 and all
433
	non-ethernets.
434

    
435
	An interface option can be used more times with different
436
	interfaces-specific options, in that case for given interface
437
	the first matching interface option is used.
438
	
439
	This option is allowed in Direct, OSPF, RIP and RAdv protocols,
440
	but in OSPF protocol it is used in <cf/area/ subsection.
441

    
442
	Default: none.
443

    
444
	Examples:
445

    
446
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
447
	<cf>type broadcast</cf> option.
448

    
449
	<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the protocol
450
	on enumerated interfaces with <cf>type ptp</cf> option.
451
	
452
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
453
	interfaces that have address from 192.168.0.0/16, but not
454
	from 192.168.1.0/24.
455

    
456
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
457
	interfaces that have address from 192.168.0.0/16, but not
458
	from 192.168.1.0/24.
459

    
460
	<cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
461
	ethernet interfaces that have address from 192.168.1.0/24.
462

    
463
	<tag><label id="dsc-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag>
464
	Specifies a password that can be used by the protocol. Password option can
465
	be used more times to specify more passwords. If more passwords are
466
	specified, it is a protocol-dependent decision which one is really
467
	used. Specifying passwords does not mean that authentication is
468
	enabled, authentication can be enabled by separate, protocol-dependent
469
	<cf/authentication/ option.
470
	
471
	This option is allowed in OSPF and RIP protocols. BGP has also
472
	<cf/password/ option, but it is slightly different and described
473
	separately.
474

    
475
	Default: none.
476
</descrip>
477

    
478
<p>Password option can contain section with some (not necessary all) password sub-options:
479

    
480
<descrip>
481
	<tag>id <M>num</M></tag>
482
	 ID of the password, (0-255). If it's not used, BIRD will choose
483
	 ID based on an order of the password item in the interface. For
484
	 example, second password item in one interface will have default
485
	 ID 2. ID is used by some routing protocols to identify which
486
	 password was used to authenticate protocol packets.
487

    
488
	<tag>generate from "<m/time/"</tag>
489
	 The start time of the usage of the password for packet signing.
490
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
491

    
492
	<tag>generate to "<m/time/"</tag>
493
	 The last time of the usage of the password for packet signing.
494

    
495
	<tag>accept from "<m/time/"</tag>
496
	 The start time of the usage of the password for packet verification.
497

    
498
	<tag>accept to "<m/time/"</tag>
499
	 The last time of the usage of the password for packet verification.
500
</descrip>
501

    
502
<chapt>Remote control
503

    
504
<p>You can use the command-line client <file>birdc</file> to talk with
505
a running BIRD. Communication is done using a <file/bird.ctl/ UNIX
506
domain socket (unless changed with the <tt/-s/ option given to both
507
the server and the client). The commands can perform simple actions
508
such as enabling/disabling of protocols, telling BIRD to show various
509
information, telling it to show routing table filtered by filter, or
510
asking BIRD to reconfigure. Press <tt/?/ at any time to get online
511
help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
512
client, which allows just read-only commands (<cf/show .../). Option
513
<tt/-v/ can be passed to the client, to make it dump numeric return
514
codes along with the messages. You do not necessarily need to use
515
<file/birdc/ to talk to BIRD, your own applications could do that, too
516
-- the format of communication between BIRD and <file/birdc/ is stable
517
(see the programmer's documentation).
518

    
519
Many commands have the <m/name/ of the protocol instance as an argument.
520
This argument can be omitted if there exists only a single instance.
521

    
522
<p>Here is a brief list of supported functions:
523

    
524
<descrip>
525
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
526
	Dump contents of internal data structures to the debugging output.
527

    
528
	<tag>show status</tag>
529
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
530

    
531
	<tag>show protocols [all]</tag>
532
	Show list of protocol instances along with tables they are connected to and protocol status, possibly giving verbose information, if <cf/all/ is specified.
533

    
534
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
535
	Show detailed information about OSPF interfaces.
536

    
537
	<tag>show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
538
	Show a list of OSPF neighbors and a state of adjacency to them.
539

    
540
	<tag>show ospf state [all] [<m/name/]</tag>
541
	Show detailed information about OSPF areas based on a content
542
	of the link-state database. It shows network topology, stub
543
	networks, aggregated networks and routers from other areas and
544
	external routes. The command shows information about reachable
545
	network nodes, use option <cf/all/ to show information about
546
	all network nodes in the link-state database.
547

    
548
	<tag>show ospf topology [all] [<m/name/]</tag>
549
	Show a topology of OSPF areas based on a content of the
550
	link-state database.  It is just a stripped-down version of
551
	'show ospf state'.
552

    
553
	<tag>show static [<m/name/]</tag>
554
	Show detailed information about static routes.
555

    
556
	<tag>show interfaces [summary]</tag>
557
	Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned. 
558

    
559
	<tag>show symbols</tag>
560
	Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
561

    
562
	<tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
563
	Show contents of a routing table (by default of the main one),
564
	that is routes, their metrics and (in case the <cf/all/ switch is given)
565
	all their attributes.
566

    
567
	<p>You can specify a <m/prefix/ if you want to print routes for a
568
	specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
569
	the entry which will be used for forwarding of packets to the given
570
	destination. By default, all routes for each network are printed with
571
	the selected one at the top, unless <cf/primary/ is given in which case
572
	only the selected route is shown.
573

    
574
	<p>You can also ask for printing only routes processed and accepted by
575
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
576
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
577
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
578
	that are exported to the specified protocol. With <cf/preexport/, the
579
	export filter of the protocol is skipped.
580

    
581
	<p>You can also select just routes added by a specific protocol.
582
	<cf>protocol <m/p/</cf>.
583

    
584
	<p>The <cf/stats/ switch requests showing of route statistics (the
585
	number of networks, number of routes before and after filtering). If
586
	you use <cf/count/ instead, only the statistics will be printed.
587

    
588
	<tag>configure [soft] ["<m/config file/"]</tag>
589
	Reload configuration from a given file. BIRD will smoothly
590
	switch itself to the new configuration, protocols are
591
	reconfigured if possible, restarted otherwise. Changes in
592
	filters usually lead to restart of affected protocols. If
593
	<cf/soft/ option is used, changes in filters does not cause
594
	BIRD to restart affected protocols, therefore already accepted
595
	routes (according to old filters) would be still propagated,
596
	but new routes would be processed according to the new
597
	filters.
598

    
599
	<tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
600
	Enable, disable or restart a given protocol instance, instances matching the <cf><m/pattern/</cf> or <cf/all/ instances.
601

    
602
	<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
603
	
604
	Reload a given protocol instance, that means re-import routes
605
	from the protocol instance and re-export preferred routes to
606
	the instance. If <cf/in/ or <cf/out/ options are used, the
607
	command is restricted to one direction (re-import or
608
	re-export).
609

    
610
	This command is useful if appropriate filters have changed but
611
	the protocol instance was not restarted (or reloaded),
612
	therefore it still propagates the old set of routes. For example
613
	when <cf/configure soft/ command was used to change filters.
614

    
615
	Re-export always succeeds, but re-import is protocol-dependent
616
	and might fail (for example, if BGP neighbor does not support
617
	route-refresh extension). In that case, re-export is also
618
	skipped. Note that for the pipe protocol, both directions are
619
	always reloaded together (<cf/in/ or <cf/out/ options are
620
	ignored in that case).
621

    
622
	<tag/down/
623
	Shut BIRD down.
624

    
625
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
626
	Control protocol debugging.
627
</descrip>
628

    
629
<chapt>Filters
630

    
631
<sect>Introduction
632

    
633
<p>BIRD contains a simple programming language. (No, it can't yet read mail :-). There are
634
two objects in this language: filters and functions. Filters are interpreted by BIRD core when a route is
635
being passed between protocols and routing tables. The filter language contains control structures such
636
as if's and switches, but it allows no loops. An example of a filter using many features can be found in <file>filter/test.conf</file>. 
637

    
638
<p>Filter gets the route, looks at its attributes and
639
modifies some of them if it wishes. At the end, it decides whether to
640
pass the changed route through (using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks
641
like this:
642

    
643
<code>
644
filter not_too_far
645
int var;
646
{
647
	if defined( rip_metric ) then
648
		var = rip_metric;
649
	else {
650
		var = 1;
651
		rip_metric = 1;
652
	}
653
	if rip_metric &gt; 10 then
654
		reject "RIP metric is too big";
655
	else
656
		accept "ok";
657
}
658
</code>
659

    
660
<p>As you can see, a filter has a header, a list of local variables, and a body. The header consists of
661
the <cf/filter/ keyword followed by a (unique) name of filter. The list of local variables consists of
662
<cf><M>type name</M>;</cf> pairs where each pair defines one local variable. The body consists of
663
<cf> { <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You can group
664
several statements to a single compound statement by using braces (<cf>{ <M>statements</M> }</cf>) which is useful if
665
you want to make a bigger block of code conditional.
666

    
667
<p>BIRD supports functions, so that you don't have to repeat the same blocks of code over and
668
over. Functions can have zero or more parameters and they can have local variables. Recursion is not allowed. Function definitions
669
look like this:
670

    
671
<code>
672
function name ()
673
int local_variable;
674
{
675
	local_variable = 5;
676
}
677

    
678
function with_parameters (int parameter)
679
{
680
	print parameter;
681
}
682
</code>
683

    
684
<p>Unlike in C, variables are declared after the <cf/function/ line, but before the first <cf/{/. You can't declare
685
variables in nested blocks. Functions are called like in C: <cf>name();
686
with_parameters(5);</cf>. Function may return values using the <cf>return <m/[expr]/</cf>
687
command. Returning a value exits from current function (this is similar to C).
688

    
689
<p>Filters are declared in a way similar to functions except they can't have explicit
690
parameters. They get a route table entry as an implicit parameter, it is also passed automatically 
691
to any functions called. The filter must terminate with either
692
<cf/accept/ or <cf/reject/ statement. If there's a runtime error in filter, the route
693
is rejected. 
694

    
695
<p>A nice trick to debug filters is to use <cf>show route filter
696
<m/name/</cf> from the command line client. An example session might look
697
like:
698

    
699
<code>
700
pavel@bug:~/bird$ ./birdc -s bird.ctl
701
BIRD 0.0.0 ready.
702
bird> show route
703
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
704
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
705
127.0.0.0/8        dev lo [direct1 23:21] (240)
706
bird> show route ?
707
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
708
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
709
127.0.0.0/8        dev lo [direct1 23:21] (240)
710
bird>
711
</code>
712

    
713
<sect>Data types
714

    
715
<p>Each variable and each value has certain type. Booleans, integers and enums are
716
incompatible with each other (that is to prevent you from shooting in the foot).
717

    
718
<descrip>
719
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
720
	  <cf/false/. Boolean is the only type you can use in <cf/if/
721
	  statements.
722

    
723
	<tag/int/ This is a general integer type, you can expect it to store signed values from -2000000000
724
	  to +2000000000. Overflows are not checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
725

    
726
	<tag/pair/ This is a pair of two short integers. Each component can have values from 0 to
727
	  65535. Literals of this type are written as <cf/(1234,5678)/. The same syntax can also be
728
	  used to construct a pair from two arbitrary integer expressions (for example <cf/(1+2,a)/).
729

    
730
	<tag/quad/ This is a dotted quad of numbers used to represent
731
	  router IDs (and others).  Each component can have a value
732
	  from 0 to 255. Literals of this type are written like IPv4
733
	  addresses.
734

    
735
	<tag/string/ This is a string of characters. There are no ways to modify strings in
736
	  filters. You can pass them between functions, assign them to variables of type <cf/string/, print
737
	  such variables, but you can't concatenate two strings. String literals
738
	  are written as <cf/"This is a string constant"/.
739

    
740
	<tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it
741
	  is either an IPv4 or IPv6 address. IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf>
742
	  on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP
743
	  address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
744

    
745
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
746
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
747
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
748
	  operators on prefixes:
749
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
750
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
751

    
752
	<tag/ec/ This is a specialized type used to represent BGP
753
	  extended community values. It is essentially a 64bit value,
754
	  literals of this type are usually written as <cf>(<m/kind/,
755
	  <m/key/, <m/value/)</cf>, where <cf/kind/ is a kind of
756
	  extended community (e.g. <cf/rt/ / <cf/ro/ for a route
757
	  target / route origin communities), the format and possible
758
	  values of <cf/key/ and <cf/value/ are usually integers, but
759
	  it depends on the used kind. Similarly to pairs, ECs can be
760
	  constructed using expressions for <cf/key/ and
761
	  <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
762
	  <cf/myas/ is an integer variable).
763
 
764
	<tag/int|pair|quad|ip|prefix|ec|enum set/
765
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
766
	  but you can't modify them. Literals of type <cf>int set</cf> look like <cf>
767
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
768
	  sets.
769

    
770
	  For pair sets, expressions like <cf/(123,*)/ can be used to denote ranges (in
771
	  that case <cf/(123,0)..(123,65535)/). You can also use <cf/(123,5..100)/ for range
772
	  <cf/(123,5)..(123,100)/. You can also use <cf/*/ and <cf/a..b/ expressions
773
	  in the first part of a pair, note that such expressions are translated to a set
774
	  of intervals, which may be memory intensive. E.g. <cf/(*,4..20)/ is translated to
775
	  <cf/(0,4..20), (1,4..20), (2,4..20), ... (65535, 4..20)/.
776

    
777
	  EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123, 10..20)/ 
778
	  or <cf/(ro, 123, *)/. Expressions requiring the translation (like  <cf/(rt, *, 3)/)
779
	  are not allowed (as they usually have 4B range for ASNs).
780

    
781
	  You can also use expressions for int, pair and EC set values. However it must
782
	  be possible to evaluate these expressions before daemon boots. So you can use
783
	  only constants inside them. E.g.
784
	<code>
785
	 define one=1;
786
	 define myas=64500;
787
	 int set odds;
788
	 pair set ps;
789
	 ec set es;
790

    
791
	 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
792
	 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
793
	 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
794
	</code>
795

    
796
	  Sets of prefixes are special: their literals does not allow ranges, but allows
797
	  prefix patterns that are written as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
798
	  Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if 
799
	  the first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are identical and <cf>len1 &lt;= ip1 &lt;= len2</cf>.
800
	  A valid prefix pattern has to satisfy <cf>low &lt;= high</cf>, but <cf/pxlen/ is not constrained by <cf/low/
801
	  or <cf/high/. Obviously, a prefix matches a prefix set literal if it matches any prefix pattern in the
802
	  prefix set literal.
803

    
804
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
805
	  <cf><m>address</m>/<m/len/{<m/len/,<m/maxlen/}</cf> (where <cf><m>maxlen</m></cf> is 32 for IPv4 and 128 for IPv6), 
806
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
807
	  is a shorthand for <cf><m>address</m>/<m/len/{0,<m/len/}</cf>, that means network prefix <cf><m>address</m>/<m/len/</cf>
808
	  and all its supernets (network prefixes that contain it).
809

    
810
	  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} ]</cf> matches
811
	  prefix <cf>1.0.0.0/8</cf>, all subprefixes of <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes
812
	  <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf> matches all prefixes (regardless of
813
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
814
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
815
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
816

    
817
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
818
	  in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
819
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
820
	  <cf>192.168.0.0/16{24,32}</cf>.
821

    
822
	<tag/enum/
823
	  Enumeration types are fixed sets of possibilities. You can't define your own
824
	  variables of such type, but some route attributes are of enumeration
825
	  type. Enumeration types are incompatible with each other.
826

    
827
	<tag/bgppath/
828
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
829
	  There are several special operators on bgppaths:
830

    
831
	  <cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/.
832

    
833
          <cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/.
834

    
835
	  Both <cf/first/ and <cf/last/ return zero if there is no appropriate ASN,
836
          for example if the path contains an AS set element as the first (or the last) part.
837

    
838
          <cf><m/P/.len</cf> returns the length of path <m/P/.
839

    
840
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
841
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
842
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
843
          (for example <cf/bgp_path/).
844

    
845
	<tag/bgpmask/
846
	  BGP masks are patterns used for BGP path matching
847
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
848
	  resemble wildcard patterns as used by UNIX shells. Autonomous
849
	  system numbers match themselves, <cf/*/ matches any (even empty)
850
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
851
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
852
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
853
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
854
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
855
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
856
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
857

    
858
	<tag/clist/
859
	  Clist is similar to a set, except that unlike other sets, it
860
	  can be modified. The type is used for community list (a set
861
	  of pairs) and for cluster list (a set of quads). There exist
862
	  no literals of this type. There are three special operators on
863
	  clists:
864

    
865
          <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist
866
	  <m/C/ and returns the result.  If item <m/P/ is already in
867
	  clist <m/C/, it does nothing.
868

    
869
          <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad)
870
	  <m/P/ from clist <m/C/ and returns the result.  If clist
871
	  <m/C/ does not contain item <m/P/, it does nothing.
872
	  <m/P/ may also be a pair (or quad) set, in that case the
873
	  operator deletes all items from clist <m/C/ that are also
874
	  members of set <m/P/.
875

    
876
          <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist
877
	  <m/C/ that are not members of pair (or quad) set <m/P/.
878
	  I.e., <cf/filter/ do the same as <cf/delete/ with inverted
879
	  set <m/P/.
880

    
881
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
882
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route
883
          attribute (for example <cf/bgp_community/). Similarly for
884
          <cf/delete/ and <cf/filter/.
885

    
886
	<tag/eclist/
887
	  Eclist is a data type used for BGP extended community lists.
888
	  Eclists are very similar to clists, but they are sets of ECs
889
	  instead of pairs. The same operations (like <cf/add/,
890
	  <cf/delete/, or <cf/&tilde;/ membership operator) can be
891
	  used to modify or test eclists, with ECs instead of pairs as
892
	  arguments.
893
</descrip>
894

    
895
<sect>Operators
896

    
897
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
898
<cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Logical operations include unary not (<cf/!/), and (<cf/&amp;&amp;/) and or (<cf/&verbar;&verbar;/). 
899
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
900
used on element and set of elements of the same type (returning true if element is contained in the given set), or
901
on two strings (returning true if first string matches a shell-like pattern stored in second string) or on IP and prefix (returning true if IP is within the range defined by that prefix), or on
902
prefix and prefix (returning true if first prefix is more specific than second one) or on bgppath and bgpmask (returning true if the path matches the mask) or on pair/quad and clist (returning true if the pair/quad is element of the clist) or on clist and pair/quad set (returning true if there is an element of the clist that is also a member of the pair/quad set).
903

    
904

    
905
<sect>Control structures
906

    
907
<p>Filters support two control structures: conditions and case switches. 
908

    
909
<p>Syntax of a condition is: <cf>if
910
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
911
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
912
clause may be omitted. If the <cf><m>boolean expression</m></cf> is true, <cf><m>command1</m></cf> is executed, otherwise <cf><m>command2</m></cf> is executed.
913

    
914
<p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else: |
915
<m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. The expression after
916
<cf>case</cf> can be of any type which can be on the left side of the &tilde; operator and anything that could
917
be a member of a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping.
918
If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed.
919

    
920
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
921

    
922
<code>
923
case arg1 {
924
	2: print "two"; print "I can do more commands without {}";
925
	3 .. 5: print "three to five";
926
	else: print "something else";
927
}
928

    
929
if 1234 = i then printn "."; else { 
930
  print "not 1234"; 
931
  print "You need {} around multiple commands"; 
932
}
933
</code>
934

    
935
<sect>Route attributes
936

    
937
<p>A filter is implicitly passed a route, and it can access its
938
attributes just like it accesses variables. Attempts to access undefined
939
attribute result in a runtime error; you can check if an attribute is
940
defined by using the <cf>defined( <m>attribute</m> )</cf> operator.
941
One notable exception to this rule are attributes of clist type, where
942
undefined value is regarded as empty clist for most purposes.
943

    
944
<descrip>
945
	<tag><m/prefix/ net</tag>
946
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
947

    
948
	<tag><m/enum/ scope</tag>
949
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for
950
	routes local to this host, <cf/SCOPE_LINK/ for those specific
951
	for a physical link, <cf/SCOPE_SITE/ and
952
	<cf/SCOPE_ORGANIZATION/ for private routes and
953
	<cf/SCOPE_UNIVERSE/ for globally visible routes. This
954
	attribute is not interpreted by BIRD and can be used to mark
955
	routes in filters. The default value for new routes is
956
	<cf/SCOPE_UNIVERSE/.
957

    
958
	<tag><m/int/ preference</tag>
959
	Preference of the route. Valid values are 0-65535. (See the chapter about routing tables.)
960

    
961
	<tag><m/ip/ from</tag>
962
	The router which the route has originated from. Read-only.
963
	
964
	<tag><m/ip/ gw</tag>
965
	Next hop packets routed using this route should be forwarded to.
966

    
967
	<tag><m/string/ proto</tag>
968
	The name of the protocol which the route has been imported from. Read-only.
969

    
970
	<tag><m/enum/ source</tag>
971
	what protocol has told me about this route. Possible values: <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/, <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/, <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, <cf/RTS_PIPE/.
972

    
973
	<tag><m/enum/ cast</tag>
974

    
975
	Route type (Currently <cf/RTC_UNICAST/ for normal routes,
976
	<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will
977
	be used in the future for broadcast, multicast and anycast
978
	routes). Read-only.
979

    
980
	<tag><m/enum/ dest</tag>
981
	Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_DEVICE/ for routing to a directly-connected network, <cf/RTD_BLACKHOLE/ for packets to be silently discarded, <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be returned with ICMP host unreachable / ICMP administratively prohibited messages). Read-only.
982

    
983
	<tag><m/int/ igp_metric</tag>
984
	The optional attribute that can be used to specify a distance
985
	to the network for routes that do not have a native protocol
986
	metric attribute (like <cf/ospf_metric1/ for OSPF routes). It
987
	is used mainly by BGP to compare internal distances to boundary
988
	routers (see below). It is also used when the route is exported
989
	to OSPF as a default value for OSPF type 1 metric.
990
</descrip>
991

    
992
<p>There also exist some protocol-specific attributes which are described in the corresponding protocol sections.
993

    
994
<sect>Other statements
995

    
996
<p>The following statements are available:
997

    
998
<descrip>
999
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
1000

    
1001
	<tag>accept|reject [ <m/expr/ ]</tag> Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
1002

    
1003
	<tag>return <m/expr/</tag> Return <cf><m>expr</m></cf> from the current function, the function ends at this point.
1004

    
1005
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
1006
	Prints given expressions; useful mainly while debugging
1007
	filters. The <cf/printn/ variant does not terminate the line.
1008

    
1009
	<tag>quitbird</tag>
1010
	Terminates BIRD. Useful when debugging the filter interpreter.
1011
</descrip>
1012

    
1013
<chapt>Protocols
1014

    
1015
<sect>BGP
1016

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

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

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

    
1040
<p>BIRD supports all requirements of the BGP4 standard as defined in
1041
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
1042
It also supports the community attributes
1043
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
1044
capability negotiation
1045
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
1046
MD5 password authentication
1047
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
1048
extended communities
1049
(RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">),
1050
route reflectors 
1051
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
1052
multiprotocol extensions
1053
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
1054
4B AS numbers 
1055
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">),
1056
and 4B AS numbers in extended communities
1057
(RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">).
1058

    
1059

    
1060
For IPv6, it uses the standard multiprotocol extensions defined in
1061
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
1062
including changes described in the
1063
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
1064
and applied to IPv6 according to
1065
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
1066

    
1067
<sect1>Route selection rules
1068

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

    
1075
<itemize>
1076
	<item>Prefer route with the highest Local Preference attribute.
1077
	<item>Prefer route with the shortest AS path.
1078
	<item>Prefer IGP origin over EGP and EGP origin over incomplete.
1079
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
1080
	<item>Prefer routes received via eBGP over ones received via iBGP.
1081
	<item>Prefer routes with lower internal distance to a boundary router.
1082
	<item>Prefer the route with the lowest value of router ID of the
1083
	advertising router.
1084
</itemize>
1085

    
1086
<sect1>IGP routing table
1087

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

    
1097
<sect1>Configuration
1098

    
1099
<p>Each instance of the BGP corresponds to one neighboring router.
1100
This allows to set routing policy and all the other parameters differently
1101
for each neighbor using the following configuration parameters:
1102

    
1103
<descrip>
1104
	<tag>local [<m/ip/] as <m/number/</tag> Define which AS we
1105
	are part of. (Note that contrary to other IP routers, BIRD is
1106
	able to act as a router located in multiple AS'es
1107
	simultaneously, but in such cases you need to tweak the BGP
1108
	paths manually in the filters to get consistent behavior.)
1109
	Optional <cf/ip/ argument specifies a source address,
1110
	equivalent to the <cf/source address/ option (see below).
1111
	This parameter is mandatory.
1112

    
1113
	<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router
1114
	this instance will be talking to and what AS it's located in. Unless
1115
	you use the <cf/multihop/ clause, it must be directly connected to one
1116
	of your router's interfaces. In case the neighbor is in the same AS
1117
	as we are, we automatically switch to iBGP. This parameter is mandatory.
1118

    
1119
	<tag>multihop [<m/number/]</tag> Configure multihop BGP
1120
	session to a neighbor that isn't directly connected.
1121
	Accurately, this option should be used if the configured
1122
	neighbor IP address does not match with any local network
1123
	subnets. Such IP address have to be reachable through system
1124
	routing table. For multihop BGP it is recommended to
1125
	explicitly configure <cf/source address/ to have it
1126
	stable. Optional <cf/number/ argument can be used to specify
1127
	the number of hops (used for TTL). Note that the number of
1128
	networks (edges) in a path is counted, i.e. if two BGP
1129
	speakers are separated by one router, the number of hops is
1130
	2. Default: switched off.
1131

    
1132
	<tag>source address <m/ip/</tag> Define local address we
1133
	should use for next hop calculation and as a source address
1134
	for the BGP session. Default: the address of the local
1135
	end of the interface our neighbor is connected to.
1136

    
1137
	<tag>next hop self</tag> Avoid calculation of the Next Hop
1138
	attribute and always advertise our own source address as a
1139
	next hop.  This needs to be used only occasionally to
1140
	circumvent misconfigurations of other routers.  Default:
1141
	disabled.
1142

    
1143
	<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
1144
	in BGP-IPv6 sometimes contains just the global IPv6 address,
1145
	but sometimes it has to contain both global and link-local
1146
	IPv6 addresses. This option specifies what to do if BIRD have
1147
	to send both addresses but does not know link-local address.
1148
	This situation might happen when routes from other protocols
1149
	are exported to BGP, or when improper updates are received
1150
	from BGP peers.  <cf/self/ means that BIRD advertises its own
1151
	local address instead. <cf/drop/ means that BIRD skips that
1152
	prefixes and logs error. <cf/ignore/ means that BIRD ignores
1153
	the problem and sends just the global address (and therefore
1154
	forms improper BGP update). Default: <cf/self/, unless BIRD
1155
	is configured as a route server (option <cf/rs client/), in
1156
	that case default is <cf/ignore/, because route servers usually
1157
	do not forward packets themselves.
1158

    
1159
	<tag>gateway direct|recursive</tag>For received routes, their
1160
	<cf/gw/ (immediate next hop) attribute is computed from
1161
	received <cf/bgp_next_hop/ attribute. This option specifies
1162
	how it is computed. Direct mode means that the IP address from
1163
	<cf/bgp_next_hop/ is used if it is directly reachable,
1164
	otherwise the neighbor IP address is used. Recursive mode
1165
	means that the gateway is computed by an IGP routing table
1166
	lookup for the IP address from <cf/bgp_next_hop/. Recursive
1167
	mode is the behavior specified by the BGP standard. Direct
1168
	mode is simpler, does not require any routes in a routing
1169
	table, and was used in older versions of BIRD, but does not
1170
	handle well nontrivial iBGP setups and multihop. Default:
1171
	<cf/direct/ for singlehop eBGP, <cf/recursive/ otherwise.
1172

    
1173
	<tag>igp table <m/name/</tag> Specifies a table that is used
1174
	as an IGP routing table. Default: the same as the table BGP is
1175
	connected to.
1176
	
1177
	<tag>ttl security <m/switch/</tag> Use GTSM (RFC 5082 - the
1178
	generalized TTL security mechanism). GTSM protects against
1179
	spoofed packets by ignoring received packets with a smaller
1180
	than expected TTL. To work properly, GTSM have to be enabled
1181
	on both sides of a BGP session. If both <cf/ttl security/ and
1182
	<cf/multihop/ options are enabled, <cf/multihop/ option should
1183
	specify proper hop value to compute expected TTL. Kernel
1184
	support required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD:
1185
	since long ago, IPv4 only. Note that full (ICMP protection,
1186
	for example) RFC 5082 support is provided by Linux
1187
	only. Default: disabled.
1188
	
1189
	<tag>password <m/string/</tag> Use this password for MD5 authentication
1190
	of BGP sessions. Default: no authentication. Password has to be set by
1191
	external utility (e.g. setkey(8)) on BSD systems.
1192

    
1193
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
1194
        initiating outgoing connections and accepting incoming
1195
        connections. In passive mode, outgoing connections are not
1196
        initiated. Default: off.
1197

    
1198
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
1199
	a route reflection client. Default: disabled.
1200

    
1201
	<tag>rr cluster id <m/IPv4 address/</tag> Route reflectors use cluster id
1202
	to avoid route reflection loops. When there is one route reflector in a cluster
1203
	it usually uses its router id as a cluster id, but when there are more route
1204
	reflectors in a cluster, these need to be configured (using this option) to
1205
	use a common cluster id. Clients in a cluster need not know their cluster
1206
	id and this option is not allowed for them. Default: the same as router id.
1207

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

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

    
1227
	<tag>interpret communities <m/switch/</tag> RFC 1997 demands
1228
	that BGP speaker should process well-known communities like
1229
	no-export (65535, 65281) or no-advertise (65535, 65282). For
1230
	example, received route carrying a no-adverise community
1231
	should not be advertised to any of its neighbors. If this
1232
	option is enabled (which is by default), BIRD has such
1233
	behavior automatically (it is evaluated when a route is
1234
	exported to the BGP protocol just before the export filter).
1235
	Otherwise, this integrated processing of well-known
1236
	communities is disabled. In that case, similar behavior can be
1237
	implemented in the export filter.  Default: on.
1238

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

    
1247
	<tag>capabilities <m/switch/</tag> Use capability advertisement
1248
	to advertise optional capabilities. This is standard behavior
1249
	for newer BGP implementations, but there might be some older
1250
	BGP implementations that reject such connection attempts.
1251
	When disabled (off), features that request it (4B AS support)
1252
	are also disabled. Default: on, with automatic fallback to
1253
	off when received capability-related error.
1254

    
1255
	<tag>advertise ipv4 <m/switch/</tag> Advertise IPv4 multiprotocol capability.
1256
	This is not a correct behavior according to the strict interpretation
1257
	of RFC 4760, but it is widespread and required by some BGP
1258
	implementations (Cisco and Quagga). This option is relevant
1259
	to IPv4 mode with enabled capability advertisement only. Default: on.
1260

    
1261
	<tag>route limit <m/number/</tag> The maximal number of routes
1262
	that may be imported from the protocol. If the route limit is
1263
	exceeded, the connection is closed with error. Default: no limit.
1264

    
1265
	<tag>disable after error <m/switch/</tag> When an error is encountered (either
1266
	locally or by the other side), disable the instance automatically
1267
	and wait for an administrator to fix the problem manually. Default: off.
1268

    
1269
	<tag>hold time <m/number/</tag> Time in seconds to wait for a Keepalive
1270
	message from the other side before considering the connection stale.
1271
	Default: depends on agreement with the neighboring router, we prefer
1272
	240 seconds if the other side is willing to accept it.
1273

    
1274
	<tag>startup hold time <m/number/</tag> Value of the hold timer used
1275
	before the routers have a chance to exchange open messages and agree
1276
	on the real value. Default: 240 seconds.
1277

    
1278
	<tag>keepalive time <m/number/</tag> Delay in seconds between sending
1279
	of two consecutive Keepalive messages. Default: One third of the hold time.
1280

    
1281
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
1282
	retrying a failed attempt to connect. Default: 120 seconds.
1283

    
1284
	<tag>start delay time <m/number/</tag> Delay in seconds between protocol
1285
	startup and the first attempt to connect. Default: 5 seconds.
1286

    
1287
	<tag>error wait time <m/number/,<m/number/</tag> Minimum and maximum delay in seconds between a protocol
1288
	failure (either local or reported by the peer) and automatic restart.
1289
	Doesn't apply when <cf/disable after error/ is configured. If consecutive
1290
	errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300.
1291

    
1292
	<tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol
1293
	failures to treat them as a error sequence which makes the <cf/error wait time/
1294
	increase exponentially. Default: 300 seconds.
1295

    
1296
	<tag>path metric <m/switch/</tag> Enable comparison of path lengths
1297
	when deciding which BGP route is the best one. Default: on.
1298

    
1299
	<tag>med metric <m/switch/</tag> Enable comparison of MED
1300
	attributes (during best route selection) even between routes
1301
	received from different ASes.  This may be useful if all MED
1302
	attributes contain some consistent metric, perhaps enforced in
1303
	import filters of AS boundary routers. If this option is
1304
	disabled, MED attributes are compared only if routes are
1305
	received from the same AS (which is the standard behavior).
1306
	Default: off.
1307

    
1308
	<tag>igp metric <m/switch/</tag> Enable comparison of internal
1309
 	distances to boundary routers during best route selection. Default: on.
1310

    
1311
	<tag>prefer older <m/switch/</tag> Standard route selection algorithm
1312
	breaks ties by comparing router IDs. This changes the behavior
1313
	to prefer older routes (when both are external and from different
1314
	peer). For details, see RFC 5004. Default: off.
1315

    
1316
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
1317
	Discriminator to be used during route selection when the MED attribute
1318
	is missing. Default: 0.
1319

    
1320
	<tag>default bgp_local_pref <m/number/</tag> A default value
1321
	for the Local Preference attribute. It is used when a new
1322
	Local Preference attribute is attached to a route by the BGP
1323
	protocol itself (for example, if a route is received through
1324
	eBGP and therefore does not have such attribute). Default: 100
1325
	(0 in pre-1.2.0 versions of BIRD).
1326
</descrip>
1327

    
1328
<sect1>Attributes
1329

    
1330
<p>BGP defines several route attributes. Some of them (those marked with `<tt/I/' in the
1331
table below) are available on internal BGP connections only, some of them (marked
1332
with `<tt/O/') are optional.
1333

    
1334
<descrip>
1335
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1336
	the packet will travel through when forwarded according to the particular route.
1337
	In case of internal BGP it doesn't contain the number of the local AS.
1338

    
1339
	<tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for
1340
	selection among multiple BGP routes (see the selection rules above). It's
1341
	used as an additional metric which is propagated through the whole local AS.
1342

    
1343
	<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
1344
	is an optional attribute which is used on external (inter-AS) links to
1345
	convey to an adjacent AS the optimal entry point into the local AS.
1346
	The received attribute is also propagated over internal BGP links.
1347
	The attribute value is zeroed when a route is exported to an external BGP
1348
	instance to ensure that the attribute received from a neighboring AS is
1349
	not propagated to other neighboring ASes. A new value might be set in
1350
	the export filter of an external BGP instance.
1351
	See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
1352
	for further discussion of BGP MED attribute.
1353

    
1354
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1355
	if the route has originated in an interior routing protocol or
1356
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1357
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1358
	is unknown.
1359

    
1360
	<tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets
1361
	to this destination. On internal BGP connections, it's an address of the
1362
	originating router if it's inside the local AS or a boundary router the
1363
	packet will leave the AS through if it's an exterior route, so each BGP
1364
	speaker within the AS has a chance to use the shortest interior path
1365
	possible to this point.
1366

    
1367
	<tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute
1368
	which carries no value, but the sole presence of which indicates that the route
1369
	has been aggregated from multiple routes by some router on the path from
1370
	the originator.
1371

    
1372
<!-- we don't handle aggregators right since they are of a very obscure type
1373
	<tag>bgp_aggregator</tag>
1374
-->
1375
	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
1376
	with the route. Each such value is a pair (represented as a <cf/pair/ data
1377
	type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
1378
	the community and the second one being a per-AS identifier. There are lots
1379
	of uses of the community mechanism, but generally they are used to carry
1380
	policy information like "don't export to USA peers". As each AS can define
1381
	its own routing policy, it also has a complete freedom about which community
1382
	attributes it defines and what will their semantics be.
1383

    
1384
	<tag>eclist <cf/bgp_ext_community/ [O]</tag> List of extended community
1385
	values associated with the route. Extended communities have similar usage
1386
	as plain communities, but they have an extended range (to allow 4B ASNs)
1387
	and a nontrivial structure with a type field. Individual community values are
1388
	represented using an <cf/ec/ data type inside the filters.
1389

    
1390
	<tag>quad <cf/bgp_originator_id/ [I, O]</tag> This attribute is created by the
1391
	route reflector when reflecting the route and contains the router ID of the
1392
	originator of the route in the local AS.
1393

    
1394
	<tag>clist <cf/bgp_cluster_list/ [I, O]</tag> This attribute contains a list
1395
	of cluster IDs of route reflectors. Each route reflector prepends its
1396
	cluster ID when reflecting the route.
1397
</descrip>
1398

    
1399
<sect1>Example
1400

    
1401
<p><code>
1402
protocol bgp {
1403
	local as 65000;			     # Use a private AS number
1404
	neighbor 62.168.0.130 as 5588;	     # Our neighbor ...
1405
	multihop;			     # ... which is connected indirectly
1406
	export filter {			     # We use non-trivial export rules
1407
		if source = RTS_STATIC then { # Export only static routes
1408
		        # Assign our community
1409
			bgp_community.add((65000,5678));
1410
			# Artificially increase path length
1411
			# by advertising local AS number twice
1412
			if bgp_path ~ [= 65000 =] then	  
1413
				bgp_path.prepend(65000);  
1414
			accept;
1415
		}
1416
		reject;
1417
	};
1418
	import all;
1419
	source address 62.168.0.1;	# Use a non-standard source address
1420
}
1421
</code>
1422

    
1423
<sect>Device
1424

    
1425
<p>The Device protocol is not a real routing protocol.  It doesn't generate
1426
any routes and it only serves as a module for getting information about network
1427
interfaces from the kernel.
1428

    
1429
<p>Except for very unusual circumstances, you probably should include
1430
this protocol in the configuration since almost all other protocols
1431
require network interfaces to be defined for them to work with.
1432

    
1433
<sect1>Configuration
1434

    
1435
<p><descrip>
1436
	<tag>scan time <m/number/</tag> Time in seconds between two scans
1437
	of the network interface list. On systems where we are notified about
1438
	interface status changes asynchronously (such as newer versions of
1439
	Linux), we need to scan the list only in order to avoid confusion by lost
1440
	notification messages, so the default time is set to a large value.
1441

    
1442
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1443
	If a network interface has more than one network address, BIRD
1444
	has to choose one of them as a primary one. By default, BIRD
1445
	chooses the lexicographically smallest address as the primary
1446
	one.
1447

    
1448
	This option allows to specify which network address should be
1449
	chosen as a primary one. Network addresses that match
1450
	<m/prefix/ are preferred to non-matching addresses. If more
1451
	<cf/primary/ options are used, the first one has the highest
1452
	preference. If "<m/mask/" is specified, then such
1453
	<cf/primary/ option is relevant only to matching network
1454
	interfaces.
1455

    
1456
	In all cases, an address marked by operating system as
1457
	secondary cannot be chosen as the primary one. 
1458
</descrip>
1459

    
1460
<p>As the Device protocol doesn't generate any routes, it cannot have
1461
any attributes. Example configuration looks like this:
1462

    
1463
<p><code>
1464
protocol device {
1465
	scan time 10;		# Scan the interfaces often
1466
	primary "eth0" 192.168.1.1;
1467
	primary 192.168.0.0/16;
1468
}
1469
</code>
1470

    
1471
<sect>Direct
1472

    
1473
<p>The Direct protocol is a simple generator of device routes for all the
1474
directly connected networks according to the list of interfaces provided
1475
by the kernel via the Device protocol.
1476

    
1477
<p>The question is whether it is a good idea to have such device
1478
routes in BIRD routing table. OS kernel usually handles device routes
1479
for directly connected networks by itself so we don't need (and don't
1480
want) to export these routes to the kernel protocol. OSPF protocol
1481
creates device routes for its interfaces itself and BGP protocol is
1482
usually used for exporting aggregate routes. Although there are some
1483
use cases that use the direct protocol (like abusing eBGP as an IGP
1484
routing protocol), in most cases it is not needed to have these device
1485
routes in BIRD routing table and to use the direct protocol.
1486

    
1487
<p>The only configurable thing about direct is what interfaces it watches:
1488

    
1489
<p><descrip>
1490
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
1491
	protocol will generate device routes for all the interfaces
1492
	available. If you want to restrict it to some subset of interfaces
1493
	(for example if you're using multiple routing tables for policy
1494
	routing and some of the policy domains don't contain all interfaces),
1495
	just use this clause.
1496
</descrip>
1497

    
1498
<p>Direct device routes don't contain any specific attributes.
1499

    
1500
<p>Example config might look like this:
1501

    
1502
<p><code>
1503
protocol direct {
1504
	interface "-arc*", "*";		# Exclude the ARCnets
1505
}
1506
</code>
1507

    
1508
<sect>Kernel
1509

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

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

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

    
1536
<p>Because the kernel protocol is partially integrated with the
1537
connected routing table, there are two limitations - it is not
1538
possible to connect more kernel protocols to the same routing table
1539
and changing route attributes (even the kernel ones) in an export
1540
filter of a kernel protocol does not work. Both limitations can be
1541
overcome using another routing table and the pipe protocol.
1542

    
1543
<sect1>Configuration
1544

    
1545
<p><descrip>
1546
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1547
	routing tables when it exits (instead of cleaning them up).
1548
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1549
	kernel routing table.
1550
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1551
	routing tables by other routing daemons or by the system administrator.
1552
	This is possible only on systems which support identification of route
1553
	authorship.
1554

    
1555
	<tag>device routes <m/switch/</tag> Enable export of device
1556
	routes to the kernel routing table. By default, such routes
1557
	are rejected (with the exception of explicitly configured
1558
	device routes from the static protocol) regardless of the
1559
	export filter to protect device routes in kernel routing table
1560
	(managed by OS itself) from accidental overwriting or erasing.
1561

    
1562
	<tag>kernel table <m/number/</tag> Select which kernel table should
1563
	this particular instance of the Kernel protocol work with. Available
1564
	only on systems supporting multiple routing tables.
1565
</descrip>
1566

    
1567
<sect1>Attributes
1568

    
1569
<p>The Kernel protocol defines several attributes. These attributes
1570
are translated to appropriate system (and OS-specific) route attributes.
1571
We support these attributes:
1572

    
1573
<descrip>
1574
	<tag>ip <cf/krt_prefsrc/</tag> (Linux) The preferred source address.
1575
 	Used in source address selection for outgoing packets. Have to
1576
 	be one of IP addresses of the router.
1577

    
1578
	<tag>int <cf/krt_realm/</tag> (Linux) The realm of the route. Can be
1579
	used for traffic classification.
1580
</descrip>
1581

    
1582
<sect1>Example
1583

    
1584
<p>A simple configuration can look this way:
1585

    
1586
<p><code>
1587
protocol kernel {
1588
	export all;
1589
}
1590
</code>
1591

    
1592
<p>Or for a system with two routing tables:
1593

    
1594
<p><code>
1595
protocol kernel {		# Primary routing table
1596
	learn;			# Learn alien routes from the kernel
1597
	persist;		# Don't remove routes on bird shutdown
1598
	scan time 10;		# Scan kernel routing table every 10 seconds
1599
	import all;
1600
	export all;
1601
}
1602

    
1603
protocol kernel {		# Secondary routing table
1604
	table auxtable;
1605
	kernel table 100;
1606
	export all;
1607
}
1608
</code>
1609

    
1610
<sect>OSPF
1611

    
1612
<sect1>Introduction
1613

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

    
1625
<p>In OSPF, the autonomous system can be split to several areas in order
1626
to reduce the amount of resources consumed for exchanging the routing
1627
information and to protect the other areas from incorrect routing data.
1628
Topology of the area is hidden to the rest of the autonomous system.
1629

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

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

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

    
1647
<sect1>Configuration
1648

    
1649
<p>In the main part of configuration, there can be multiple definitions of
1650
OSPF areas, each with a different id. These definitions includes many other
1651
switches and multiple definitions of interfaces. Definition of interface
1652
may contain many switches and constant definitions and list of neighbors
1653
on nonbroadcast networks.
1654

    
1655
<code>
1656
protocol ospf &lt;name&gt; {
1657
	rfc1583compat &lt;switch&gt;;
1658
	tick &lt;num&gt;;
1659
	ecmp &lt;switch&gt; [limit &lt;num&gt;];
1660
	area &lt;id&gt; {
1661
		stub;
1662
		nssa;
1663
		summary &lt;switch&gt;;
1664
		default nssa &lt;switch&gt;;
1665
		default cost &lt;num&gt;;
1666
		default cost2 &lt;num&gt;;
1667
		translator &lt;switch&gt;;
1668
		translator stability &lt;num&gt;;
1669

    
1670
                networks {
1671
			&lt;prefix&gt;;
1672
			&lt;prefix&gt; hidden;
1673
		}
1674
                external {
1675
			&lt;prefix&gt;;
1676
			&lt;prefix&gt; hidden;
1677
			&lt;prefix&gt; tag &lt;num&gt;;
1678
		}
1679
		stubnet &lt;prefix&gt;;
1680
		stubnet &lt;prefix&gt; {
1681
			hidden &lt;switch&gt;;
1682
			summary &lt;switch&gt;;
1683
			cost &lt;num&gt;;
1684
		}
1685
		interface &lt;interface pattern&gt; {
1686
			cost &lt;num&gt;;
1687
			stub &lt;switch&gt;;
1688
			hello &lt;num&gt;;
1689
			poll &lt;num&gt;;
1690
			retransmit &lt;num&gt;;
1691
			priority &lt;num&gt;;
1692
			wait &lt;num&gt;;
1693
			dead count &lt;num&gt;;
1694
			dead &lt;num&gt;;
1695
			rx buffer [normal|large|&lt;num&gt;];
1696
			type [broadcast|bcast|pointopoint|ptp|
1697
				nonbroadcast|nbma|pointomultipoint|ptmp];
1698
			strict nonbroadcast &lt;switch&gt;;
1699
			check link &lt;switch&gt;;
1700
			ecmp weight &lt;num&gt;;
1701
			authentication [none|simple|cryptographic];
1702
			password "&lt;text&gt;";
1703
			password "&lt;text&gt;" {
1704
				id &lt;num&gt;;
1705
				generate from "&lt;date&gt;";
1706
				generate to "&lt;date&gt;";
1707
				accept from "&lt;date&gt;";
1708
				accept to "&lt;date&gt;";
1709
			};
1710
			neighbors {
1711
				&lt;ip&gt;;
1712
				&lt;ip&gt; eligible;
1713
			};
1714
		};
1715
		virtual link &lt;id&gt;	{
1716
			hello &lt;num&gt;;
1717
			retransmit &lt;num&gt;;
1718
			wait &lt;num&gt;;
1719
			dead count &lt;num&gt;;
1720
			dead &lt;num&gt;;
1721
			authentication [none|simple|cryptographic];
1722
			password "&lt;text&gt;";
1723
		};
1724
	};
1725
}
1726
</code>
1727

    
1728
<descrip>
1729
	<tag>rfc1583compat <M>switch</M></tag>
1730
	 This option controls compatibility of routing table
1731
	 calculation with RFC 1583<htmlurl
1732
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1733
	 value is no.
1734

    
1735
	<tag>tick <M>num</M></tag>
1736
	 The routing table calculation and clean-up of areas' databases
1737
         is not performed when a single link state
1738
	 change arrives. To lower the CPU utilization, it's processed later
1739
	 at periodical intervals of <m/num/ seconds. The default value is 1.
1740

    
1741
	<tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
1742
	 This option specifies whether OSPF is allowed to generate
1743
	 ECMP (equal-cost multipath) routes. Such routes are used when
1744
	 there are several directions to the destination, each with
1745
	 the same (computed) cost. This option also allows to specify
1746
	 a limit on maximal number of nexthops in one route. By
1747
	 default, ECMP is disabled.  If enabled, default value of the
1748
	 limit is 16.
1749

    
1750
	<tag>area <M>id</M></tag>
1751
	 This defines an OSPF area with given area ID (an integer or an IPv4
1752
	 address, similarly to a router ID). The most important area is
1753
	 the backbone (ID 0) to which every other area must be connected.
1754

    
1755
	<tag>stub</tag>
1756
	 This option configures the area to be a stub area. External
1757
	 routes are not flooded into stub areas. Also summary LSAs can be
1758
	 limited in stub areas (see option <cf/summary/).
1759
	 By default, the area is not a stub area.
1760

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

    
1770
	<tag>summary <M>switch</M></tag>
1771
	 This option controls propagation of summary LSAs into stub or
1772
	 NSSA areas. If enabled, summary LSAs are propagated as usual,
1773
	 otherwise just the default summary route (0.0.0.0/0) is
1774
	 propagated (this is sometimes called totally stubby area). If
1775
	 a stub area has more area boundary routers, propagating
1776
	 summary LSAs could lead to more efficient routing at the cost
1777
	 of larger link state database. Default value is no.
1778

    
1779
	<tag>default nssa <M>switch</M></tag>
1780
 	 When <cf/summary/ option is enabled, default summary route is
1781
	 no longer propagated to the NSSA. In that case, this option
1782
	 allows to originate default route as NSSA-LSA to the NSSA.
1783
	 Default value is no.
1784

    
1785
	<tag>default cost <M>num</M></tag>
1786
	 This option controls the cost of a default route propagated to
1787
	 stub and NSSA areas. Default value is 1000.
1788

    
1789
	<tag>default cost2 <M>num</M></tag>
1790
	 When a default route is originated as NSSA-LSA, its cost
1791
	 can use either type 1 or type 2 metric. This option allows
1792
	 to specify the cost of a default route in type 2 metric.
1793
	 By default, type 1 metric (option <cf/default cost/) is used.
1794

    
1795
	<tag>translator <M>switch</M></tag>
1796
	 This option controls translation of NSSA-LSAs into external
1797
	 LSAs. By default, one translator per NSSA is automatically
1798
	 elected from area boundary routers. If enabled, this area
1799
	 boundary router would unconditionally translate all NSSA-LSAs
1800
	 regardless of translator election. Default value is no.
1801

    
1802
	<tag>translator stability <M>num</M></tag>
1803
	 This option controls the translator stability interval (in
1804
	 seconds). When the new translator is elected, the old one
1805
	 keeps translating until the interval is over. Default value
1806
	 is 40.
1807

    
1808
	<tag>networks { <m/set/ }</tag>
1809
         Definition of area IP ranges. This is used in summary LSA origination.
1810
	 Hidden networks are not propagated into other areas.
1811

    
1812
	<tag>external { <m/set/ }</tag>
1813
         Definition of external area IP ranges for NSSAs. This is used
1814
	 for NSSA-LSA translation. Hidden networks are not translated
1815
	 into external LSAs. Networks can have configured route tag.
1816

    
1817
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
1818
	 Stub networks are networks that are not transit networks
1819
	 between OSPF routers. They are also propagated through an
1820
	 OSPF area as a part of a link state database. By default,
1821
	 BIRD generates a stub network record for each primary network
1822
	 address on each OSPF interface that does not have any OSPF
1823
	 neighbors, and also for each non-primary network address on
1824
	 each OSPF interface. This option allows to alter a set of
1825
	 stub networks propagated by this router. 
1826

    
1827
	 Each instance of this option adds a stub network with given
1828
	 network prefix to the set of propagated stub network, unless
1829
	 option <cf/hidden/ is used. It also suppresses default stub
1830
	 networks for given network prefix. When option
1831
	 <cf/summary/ is used, also default stub networks that are
1832
	 subnetworks of given stub network are suppressed. This might
1833
	 be used, for example, to aggregate generated stub networks.
1834
	 
1835
	<tag>interface <M>pattern</M></tag>
1836
	 Defines that the specified interfaces belong to the area being defined.
1837
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
1838

    
1839
	<tag>virtual link <M>id</M></tag>
1840
	 Virtual link to router with the router id. Virtual link acts as a
1841
         point-to-point interface belonging to backbone. The actual area is
1842
         used as transport area. This item cannot be in the backbone.
1843

    
1844
	<tag>cost <M>num</M></tag>
1845
	 Specifies output cost (metric) of an interface. Default value is 10.
1846

    
1847
	<tag>stub <M>switch</M></tag>
1848
	 If set to interface it does not listen to any packet and does not send
1849
	 any hello. Default value is no.
1850

    
1851
	<tag>hello <M>num</M></tag>
1852
	 Specifies interval in seconds between sending of Hello messages. Beware, all
1853
	 routers on the same network need to have the same hello interval.
1854
	 Default value is 10.
1855

    
1856
	<tag>poll <M>num</M></tag>
1857
	 Specifies interval in seconds between sending of Hello messages for
1858
	 some neighbors on NBMA network. Default value is 20.
1859

    
1860
	<tag>retransmit <M>num</M></tag>
1861
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
1862
	 Default value is 5.
1863

    
1864
        <tag>priority <M>num</M></tag>
1865
	 On every multiple access network (e.g., the Ethernet) Designed Router
1866
	 and Backup Designed router are elected. These routers have some
1867
	 special functions in the flooding process. Higher priority increases
1868
	 preferences in this election. Routers with priority 0 are not
1869
	 eligible. Default value is 1.
1870

    
1871
	<tag>wait <M>num</M></tag>
1872
	 After start, router waits for the specified number of seconds between starting
1873
	 election and building adjacency. Default value is 40.
1874
	 
1875
	<tag>dead count <M>num</M></tag>
1876
	 When the router does not receive any messages from a neighbor in
1877
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
1878

    
1879
	<tag>dead <M>num</M></tag>
1880
	 When the router does not receive any messages from a neighbor in
1881
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
1882
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
1883

    
1884
	<tag>rx buffer <M>num</M></tag>
1885
	 This sets the size of buffer used for receiving packets. The buffer should
1886
	 be bigger than maximal size of any packets. Value NORMAL (default)
1887
	 means 2*MTU, value LARGE means maximal allowed packet - 65535.
1888

    
1889
	<tag>type broadcast|bcast</tag>
1890
	 BIRD detects a type of a connected network automatically, but
1891
	 sometimes it's convenient to force use of a different type
1892
	 manually. On broadcast networks (like ethernet), flooding
1893
	 and Hello messages are sent using multicasts (a single packet
1894
	 for all the neighbors). A designated router is elected and it
1895
	 is responsible for synchronizing the link-state databases and
1896
	 originating network LSAs. This network type cannot be used on
1897
	 physically NBMA networks and on unnumbered networks (networks
1898
	 without proper IP prefix).
1899

    
1900
	<tag>type pointopoint|ptp</tag>
1901
	 Point-to-point networks connect just 2 routers together. No
1902
	 election is performed and no network LSA is originated, which
1903
	 makes it simpler and faster to establish. This network type
1904
	 is useful not only for physically PtP ifaces (like PPP or
1905
	 tunnels), but also for broadcast networks used as PtP links.
1906
	 This network type cannot be used on physically NBMA networks.
1907

    
1908
	<tag>type nonbroadcast|nbma</tag>
1909
	 On NBMA networks, the packets are sent to each neighbor
1910
	 separately because of lack of multicast capabilities.
1911
	 Like on broadcast networks, a designated router is elected,
1912
	 which plays a central role in propagation of LSAs.
1913
	 This network type cannot be used on unnumbered networks.
1914

    
1915
	<tag>type pointomultipoint|ptmp</tag>
1916
	 This is another network type designed to handle NBMA
1917
	 networks. In this case the NBMA network is treated as a
1918
	 collection of PtP links. This is useful if not every pair of
1919
	 routers on the NBMA network has direct communication, or if
1920
	 the NBMA network is used as an (possibly unnumbered) PtP
1921
	 link.
1922

    
1923
	<tag>strict nonbroadcast <M>switch</M></tag>
1924
	 If set, don't send hello to any undefined neighbor. This switch
1925
	 is ignored on other than NBMA or PtMP networks. Default value is no.
1926

    
1927
	<tag>check link <M>switch</M></tag>
1928
	 If set, a hardware link state (reported by OS) is taken into
1929
	 consideration. When a link disappears (e.g. an ethernet cable is
1930
	 unplugged), neighbors are immediately considered unreachable
1931
	 and only the address of the iface (instead of whole network
1932
	 prefix) is propagated. It is possible that some hardware
1933
	 drivers or platforms do not implement this feature. Default value is no.
1934

    
1935
	<tag>ecmp weight <M>num</M></tag>
1936
	 When ECMP (multipath) routes are allowed, this value specifies
1937
	 a relative weight used for nexthops going through the iface.
1938
	 Allowed values are 1-256. Default value is 1.
1939

    
1940
	<tag>authentication none</tag>
1941
	 No passwords are sent in OSPF packets. This is the default value.
1942

    
1943
	<tag>authentication simple</tag>
1944
	 Every packet carries 8 bytes of password. Received packets
1945
	 lacking this password are ignored. This authentication mechanism is
1946
	 very weak.
1947

    
1948
	<tag>authentication cryptographic</tag>
1949
	 16-byte long MD5 digest is appended to every packet. For the digest
1950
         generation 16-byte long passwords are used. Those passwords are 
1951
         not sent via network, so this mechanism is quite secure.
1952
         Packets can still be read by an attacker.
1953

    
1954
	<tag>password "<M>text</M>"</tag>
1955
	 An 8-byte or 16-byte password used for authentication.
1956
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
1957

    
1958
	<tag>neighbors { <m/set/ } </tag>
1959
	 A set of neighbors to which Hello messages on NBMA or PtMP
1960
	 networks are to be sent. For NBMA networks, some of them
1961
	 could be marked as eligible.
1962

    
1963
</descrip>
1964

    
1965
<sect1>Attributes
1966

    
1967
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
1968
Metric is ranging from 1 to infinity (65535).
1969
External routes use <cf/metric type 1/ or <cf/metric type 2/.
1970
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
1971
<cf/metric of type 2/ is always longer
1972
than any <cf/metric of type 1/ or any <cf/internal metric/.
1973
<cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute
1974
<cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/.
1975
If you specify both metrics only metric1 is used.
1976

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

    
1984
<sect1>Example
1985

    
1986
<p>
1987

    
1988
<code>
1989
protocol ospf MyOSPF {
1990
        rfc1583compat yes;
1991
        tick 2;
1992
	export filter {
1993
		if source = RTS_BGP then {
1994
			ospf_metric1 = 100;
1995
			accept;
1996
		}
1997
		reject;
1998
	};
1999
	area 0.0.0.0 {
2000
		interface "eth*" {
2001
			cost 11;
2002
			hello 15;
2003
			priority 100;
2004
			retransmit 7;
2005
			authentication simple;
2006
			password "aaa";
2007
		};
2008
		interface "ppp*" {
2009
			cost 100;
2010
			authentication cryptographic;
2011
			password "abc" {
2012
				id 1;
2013
				generate to "22-04-2003 11:00:06";
2014
				accept from "17-01-2001 12:01:05";
2015
			};
2016
			password "def" {
2017
				id 2;
2018
				generate to "22-07-2005 17:03:21";
2019
				accept from "22-02-2001 11:34:06";
2020
			};
2021
		};
2022
		interface "arc0" {
2023
			cost 10;
2024
			stub yes;
2025
		};
2026
		interface "arc1";
2027
	};
2028
	area 120 {
2029
		stub yes;
2030
		networks {
2031
			172.16.1.0/24;
2032
			172.16.2.0/24 hidden;
2033
		}
2034
		interface "-arc0" , "arc*" {
2035
			type nonbroadcast;
2036
			authentication none;
2037
			strict nonbroadcast yes;
2038
			wait 120;
2039
			poll 40;
2040
			dead count 8;
2041
			neighbors {
2042
				192.168.120.1 eligible;
2043
				192.168.120.2;
2044
				192.168.120.10;
2045
			};
2046
		};
2047
	};
2048
}
2049
</code>
2050

    
2051
<sect>Pipe
2052

    
2053
<sect1>Introduction
2054

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

    
2062
<p>The Pipe protocol may work in the opaque mode or in the transparent
2063
mode. In the opaque mode, the Pipe protocol retransmits optimal route
2064
from one table to the other table in a similar way like other
2065
protocols send and receive routes. Retransmitted route will have the
2066
source set to the Pipe protocol, which may limit access to protocol
2067
specific route attributes. The opaque mode is a default mode.
2068

    
2069
<p>In transparent mode, the Pipe protocol retransmits all routes from
2070
one table to the other table, retaining their original source and
2071
attributes.  If import and export filters are set to accept, then both
2072
tables would have the same content. The mode can be set by
2073
<tt/mode/ option.
2074

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

    
2086
<sect1>Configuration
2087

    
2088
<p><descrip>
2089
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
2090
	primary one is selected by the <cf/table/ keyword.
2091

    
2092
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
2093
</descrip>
2094

    
2095
<sect1>Attributes
2096

    
2097
<p>The Pipe protocol doesn't define any route attributes.
2098

    
2099
<sect1>Example
2100

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

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

    
2115
<code>
2116
table as1;				# Define the tables
2117
table as2;
2118

    
2119
protocol kernel kern1 {			# Synchronize them with the kernel
2120
	table as1;
2121
	kernel table 1;
2122
}
2123

    
2124
protocol kernel kern2 {
2125
	table as2;
2126
	kernel table 2;
2127
}
2128

    
2129
protocol bgp bgp1 {			# The outside connections
2130
	table as1;
2131
	local as 1;
2132
	neighbor 192.168.0.1 as 1001;
2133
	export all;
2134
	import all;
2135
}
2136

    
2137
protocol bgp bgp2 {
2138
	table as2;
2139
	local as 2;
2140
	neighbor 10.0.0.1 as 1002;
2141
	export all;
2142
	import all;
2143
}
2144

    
2145
protocol pipe {				# The Pipe
2146
	table as1;
2147
	peer table as2;
2148
	export filter {
2149
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
2150
			if preference>10 then preference = preference-10;
2151
			if source=RTS_BGP then bgp_path.prepend(1);
2152
			accept;
2153
		}
2154
		reject;
2155
	};
2156
	import filter {
2157
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
2158
			if preference>10 then preference = preference-10;
2159
			if source=RTS_BGP then bgp_path.prepend(2);
2160
			accept;
2161
		}
2162
		reject;
2163
	};
2164
}
2165
</code>
2166

    
2167
<sect>RAdv
2168

    
2169
<sect1>Introduction
2170

    
2171
<p>The RAdv protocol is an implementation of Router Advertisements,
2172
which are used in the IPv6 stateless autoconfiguration. IPv6 routers
2173
send (in irregular time intervals or as an answer to a request)
2174
advertisement packets to connected networks. These packets contain
2175
basic information about a local network (e.g. a list of network
2176
prefixes), which allows network hosts to autoconfigure network
2177
addresses and choose a default route. BIRD implements router behavior
2178
as defined in RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">.
2179

    
2180
<sect1>Configuration
2181

    
2182
<p>There are two classes of definitions in RAdv configuration --
2183
interface definitions and prefix definitions:
2184

    
2185
<descrip>
2186
	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag> 
2187
	Interface definitions specify a set of interfaces on which the
2188
	protocol is activated and contain interface specific options.
2189
	See <ref id="dsc-iface" name="interface"> common options for
2190
	detailed description.
2191

    
2192
	<tag>prefix <m/prefix/ { <m/options/ }</tag> 
2193
	Prefix definitions allows to modify a list of advertised
2194
	prefixes. By default, the advertised prefixes are the same as
2195
	the network prefixes assigned to the interface. For each
2196
	network prefix, the matching prefix definition is found and
2197
	its options are used. If no matching prefix definition is
2198
	found, the prefix is used with default options.
2199

    
2200
	Prefix definitions can be either global or interface-specific.
2201
	The second ones are part of interface options. The prefix
2202
	definition matching is done in the first-match style, when
2203
	interface-specific definitions are processed before global
2204
	definitions. As expected, the prefix definition is matching if
2205
	the network prefix is a subnet of the prefix in prefix
2206
	definition.
2207
</descrip>
2208

    
2209
<p>Interface specific options:
2210

    
2211
<descrip>
2212
	<tag>max ra interval <m/expr/</tag>
2213
	Unsolicited router advertisements are sent in irregular time
2214
	intervals. This option specifies the maximum length of these
2215
	intervals, in seconds. Valid values are 4-1800. Default: 600
2216

    
2217
	<tag>min ra interval <m/expr/</tag>
2218
	This option specifies the minimum length of that intervals, in
2219
	seconds. Must be at least 3 and at most 3/4 * max ra interval.
2220
	Default: about 1/3 * max ra interval.
2221

    
2222
	<tag>min delay <m/expr/</tag>
2223
	The minimum delay between two consecutive router advertisements,
2224
	in seconds. Default: 3
2225

    
2226
	<tag>managed <m/switch/</tag>
2227
	This option specifies whether hosts should use DHCPv6 for
2228
	IP address configuration. Default: no
2229

    
2230
	<tag>other config <m/switch/</tag>
2231
	This option specifies whether hosts should use DHCPv6 to
2232
	receive other configuration information. Default: no
2233

    
2234
	<tag>link mtu <m/expr/</tag>
2235
	This option specifies which value of MTU should be used by
2236
	hosts. 0 means unspecified. Default: 0
2237

    
2238
	<tag>reachable time <m/expr/</tag>
2239
	This option specifies the time (in milliseconds) how long
2240
	hosts should assume a neighbor is reachable (from the last
2241
	confirmation). Maximum is 3600000, 0 means unspecified.
2242
	Default 0.
2243

    
2244
	<tag>retrans timer <m/expr/</tag>
2245
	This option specifies the time (in milliseconds) how long
2246
	hosts should wait before retransmitting Neighbor Solicitation
2247
	messages. 0 means unspecified. Default 0.
2248

    
2249
	<tag>current hop limit <m/expr/</tag>
2250
	This option specifies which value of Hop Limit should be used
2251
	by hosts. Valid values are 0-255, 0 means unspecified. Default: 64
2252

    
2253
	<tag>default lifetime <m/expr/</tag>
2254
	This option specifies the time (in seconds) how long (after
2255
	the receipt of RA) hosts may use the router as a default
2256
	router. 0 means do not use as a default router. Default: 3 *
2257
	max ra interval.
2258
</descrip>
2259

    
2260

    
2261
<p>Prefix specific options:
2262

    
2263
<descrip>
2264
	<tag>onlink <m/switch/</tag>
2265
	This option specifies whether hosts may use the advertised
2266
	prefix for onlink determination. Default: yes
2267

    
2268
	<tag>autonomous <m/switch/</tag>
2269
	This option specifies whether hosts may use the advertised
2270
	prefix for stateless autoconfiguration. Default: yes
2271

    
2272
	<tag>valid lifetime <m/expr/</tag>
2273
	This option specifies the time (in seconds) how long (after
2274
	the receipt of RA) the prefix information is valid, i.e.,
2275
	autoconfigured IP addresses can be assigned and hosts with
2276
	that IP addresses are considered directly reachable. 0 means
2277
	the prefix is no longer valid. Default: 86400 (1 day)
2278

    
2279
	<tag>preferred lifetime <m/expr/</tag>
2280
	This option specifies the time (in seconds) how long (after
2281
	the receipt of RA) IP addresses generated from the prefix
2282
	using stateless autoconfiguration remain preferred. Default:
2283
	14400 (4 hours)
2284
</descrip>
2285

    
2286
<sect1>Example
2287

    
2288
<p><code>
2289
protocol radv {
2290
	interface "eth2" {
2291
		max ra interval 5;	# Fast failover with more routers
2292
		managed yes;		# Using DHCPv6 on eth2
2293
		prefix ::/0 {
2294
			autonomous off;	# So do not autoconfigure any IP
2295
		};
2296
	};
2297

    
2298
	interface "eth*";		# No need for any other options
2299

    
2300
	prefix 2001:0DB8:1234::/48 {
2301
		preferred lifetime 0;	# Deprecated address range
2302
	};
2303

    
2304
	prefix 2001:0DB8:2000::/48 {
2305
		autonomous off;		# Do not autoconfigure
2306
	};
2307
}
2308
</code>
2309

    
2310
<sect>RIP
2311

    
2312
<sect1>Introduction
2313

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

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

    
2331
<sect1>Configuration
2332

    
2333
<p>In addition to options common for all to other protocols, RIP supports the following ones:
2334

    
2335
<descrip>
2336
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
2337
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
2338
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
2339
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
2340
	  section. Default: none.
2341

    
2342
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
2343
	  be honored. (Always, when sent from a  host on a directly connected
2344
	  network or never.) Routing table updates are honored only from
2345
	  neighbors, that is not configurable. Default: never.
2346
</descrip>
2347

    
2348
<p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with
2349
default one.  Second is <cf>mode multicast|broadcast|quiet|nolisten|version1</cf>, it selects mode for
2350
rip to work in. If nothing is specified, rip runs in multicast mode. <cf>version1</cf> is
2351
currently equivalent to <cf>broadcast</cf>, and it makes RIP talk to a broadcast address even
2352
through multicast mode is possible. <cf>quiet</cf> option means that RIP will not transmit
2353
any periodic messages to this interface and <cf>nolisten</cf> means that RIP will send to this
2354
interface but not listen to it.
2355

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

    
2360
<descrip>
2361
	<tag>port <M>number</M></tag>
2362
	  selects IP port to operate on, default 520. (This is useful when testing BIRD, if you
2363
	  set this to an address &gt;1024, you will not need to run bird with UID==0).
2364

    
2365
	<tag>infinity <M>number</M></tag>
2366
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
2367
	  even slower.
2368

    
2369
	<tag>period <M>number</M>
2370
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
2371
	  number will mean faster convergence but bigger network
2372
	  load. Do not use values lower than 10.
2373

    
2374
	<tag>timeout time <M>number</M>
2375
	  </tag>specifies how old route has to be to be considered unreachable. Default is 4*<cf/period/.
2376

    
2377
	<tag>garbage time <M>number</M>
2378
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
2379
</descrip>
2380

    
2381
<sect1>Attributes
2382

    
2383
<p>RIP defines two route attributes:
2384

    
2385
<descrip>
2386
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
2387
	When routes from different RIP instances are available and all of them have the same
2388
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
2389
	When importing a non-RIP route, the metric defaults to 5.
2390

    
2391
	<tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used
2392
	to carry additional information with the route (for example, an originating AS number
2393
	in case of external routes). When importing a non-RIP route, the tag defaults to 0.
2394
</descrip>
2395

    
2396
<sect1>Example
2397

    
2398
<p><code>
2399
protocol rip MyRIP_test {
2400
        debug all;
2401
        port 1520;
2402
        period 10;
2403
        garbage time 60;
2404
        interface "eth0" { metric 3; mode multicast; };
2405
	interface "eth*" { metric 2; mode broadcast; };
2406
        honor neighbor;
2407
        authentication none;
2408
        import filter { print "importing"; accept; };
2409
        export filter { print "exporting"; accept; };
2410
}
2411
</code>
2412

    
2413
<sect>Static
2414

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

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

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

    
2436
<p>The Static protocol does not have many configuration options. The
2437
definition of the protocol contains mainly a list of static routes:
2438

    
2439
<descrip>
2440
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
2441
	a neighboring router.
2442
	<tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
2443
	Static multipath route. Contains several nexthops (gateways), possibly
2444
 	with their weights.
2445
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
2446
	route through an interface to hosts on a directly connected network.
2447
	<tag>route <m/prefix/ recursive <m/ip/</tag> Static recursive route,
2448
	its nexthop depends on a route table lookup for given IP address.
2449
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
2450
	specifying to drop the packet, return it as unreachable or return
2451
	it as administratively prohibited.
2452

    
2453
	<tag>check link <m/switch/</tag>
2454
	If set, hardware link states of network interfaces are taken
2455
	into consideration.  When link disappears (e.g. ethernet cable
2456
	is unplugged), static routes directing to that interface are
2457
	removed. It is possible that some hardware drivers or
2458
	platforms do not implement this feature. Default: off.
2459

    
2460
	<tag>igp table <m/name/</tag> Specifies a table that is used
2461
	for route table lookups of recursive routes. Default: the
2462
	same table as the protocol is connected to.
2463
</descrip>
2464

    
2465
<p>Static routes have no specific attributes.
2466

    
2467
<p>Example static config might look like this:
2468

    
2469
<p><code>
2470
protocol static {
2471
	table testable;			 # Connect to a non-default routing table
2472
	route 0.0.0.0/0 via 62.168.0.13; # Default route
2473
	route 10.0.0.0/8 multipath	 # Multipath route
2474
		via 62.168.0.14 weight 2
2475
		via 62.168.1.10
2476
		via 62.168.1.11;
2477
	route 62.168.0.0/25 reject;	 # Sink route
2478
	route 10.2.0.0/24 via "arc0";	 # Secondary network
2479
}
2480
</code>
2481

    
2482
<chapt>Conclusions
2483

    
2484
<sect>Future work
2485

    
2486
<p>Although BIRD supports all the commonly used routing protocols,
2487
there are still some features which would surely deserve to be
2488
implemented in future versions of BIRD:
2489

    
2490
<itemize>
2491
<item>Opaque LSA's
2492
<item>Route aggregation and flap dampening
2493
<item>Multipath routes
2494
<item>Multicast routing protocols
2495
<item>Ports to other systems
2496
</itemize>
2497

    
2498
<sect>Getting more help
2499

    
2500
<p>If you use BIRD, you're welcome to join the bird-users mailing list
2501
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
2502
where you can share your experiences with the other users and consult
2503
your problems with the authors. To subscribe to the list, just send a
2504
<tt/subscribe bird-users/ command in a body of a mail to
2505
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
2506
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
2507

    
2508
<p>BIRD is a relatively young system and it probably contains some
2509
bugs. You can report any problems to the bird-users list and the authors
2510
will be glad to solve them, but before you do so,
2511
please make sure you have read the available documentation and that you are running the latest version (available at <HTMLURL
2512
URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). (Of course, a patch
2513
which fixes the bug is always welcome as an attachment.)
2514

    
2515
<p>If you want to understand what is going inside, Internet standards are
2516
a good and interesting reading. You can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
2517

    
2518
<p><it/Good luck!/
2519

    
2520
</book>
2521

    
2522
<!--
2523
LocalWords:  GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
2524
LocalWords:  linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
2525
LocalWords:  router's eval expr num birdc ctl UNIX if's enums bool int ip GCC
2526
LocalWords:  len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
2527
LocalWords:  RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
2528
LocalWords:  EGP misconfigurations keepalive pref aggr aggregator BIRD's RTC
2529
LocalWords:  OS'es AS's multicast nolisten misconfigured UID blackhole MRTD MTU
2530
LocalWords:  uninstalls ethernets IP binutils ANYCAST anycast dest RTD ICMP rfc
2531
LocalWords:  compat multicasts nonbroadcast pointopoint loopback sym stats
2532
LocalWords:  Perl SIGHUP dd mm yy HH MM SS EXT IA UNICAST multihop Discriminator txt
2533
LocalWords:  proto wildcard Ondrej Filip
2534
-->