Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ acc93efd

History | View | Annotate | Download (103 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
</descrip>
149

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

    
152
<chapt>About routing tables
153

    
154
<p>BIRD has one or more routing tables which may or may not be
155
synchronized with OS kernel and which may or may not be synchronized with
156
each other (see the Pipe protocol). Each routing table contains a list of
157
known routes. Each route consists of:
158

    
159
<itemize>
160
	<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)
161
	<item>preference of this route
162
	<item>IP address of router which told us about this route
163
	<item>IP address of router we should forward the packets to
164
	using this route
165
	<item>other attributes common to all routes
166
	<item>dynamic attributes defined by protocols which may or
167
	may not be present (typically protocol metrics)
168
</itemize>
169

    
170
Routing table maintains multiple entries
171
for a network, but at most one entry for one network and one
172
protocol. The entry with the highest preference is used for routing (we
173
will call such an entry the <it/selected route/). If
174
there are more entries with the same preference and they are from the same
175
protocol, the protocol decides (typically according to metrics). If they aren't,
176
an internal ordering is used to break the tie. You can
177
get the list of route attributes in the Route attributes section.
178

    
179
<p>Each protocol is connected to a routing table through two filters
180
which can accept, reject and modify the routes. An <it/export/
181
filter checks routes passed from the routing table to the protocol,
182
an <it/import/ filter checks routes in the opposite direction.
183
When the routing table gets a route from a protocol, it recalculates
184
the selected route and broadcasts it to all protocols connected to
185
the table. The protocols typically send the update to other routers
186
in the network.
187

    
188
<chapt>Configuration
189

    
190
<sect>Introduction
191

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

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

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

    
207

    
208
<code>
209
protocol kernel {
210
	persist;		# Don't remove routes on BIRD shutdown
211
	scan time 20;		# Scan kernel routing table every 20 seconds
212
	export all;		# Default is export none
213
}
214

    
215
protocol device {
216
	scan time 10;		# Scan interfaces every 10 seconds
217
}
218

    
219
protocol rip {
220
	export all;
221
	import all;
222
	interface "*";
223
}
224
</code>
225

    
226

    
227
<sect>Global options
228

    
229
<p><descrip>
230
	<tag>log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag> 
231
	Set logging of messages having the given class (either <cf/all/ or <cf/{
232
	error, trace }/ etc.) into selected destination (a file specified as a filename string,
233
	syslog with optional name argument, or the stderr output). Classes are:
234
	<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
235
	<cf/debug/ for debugging messages, 
236
	<cf/trace/ when you want to know what happens in the network, 
237
	<cf/remote/ for messages about misbehavior of remote machines, 
238
	<cf/auth/ about authentication failures,
239
	<cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple
240
	destinations. Default: log everything to the system log.
241

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

    
245
	<tag>debug commands <m/number/</tag>
246
	Control logging of client connections (0 for no logging, 1 for
247
	logging of connects and disconnects, 2 and higher for logging of
248
	all client commands). Default: 0.
249

    
250
	<tag>mrtdump "<m/filename/"</tag>
251
	Set MRTdump file name. This option must be specified to allow MRTdump feature.
252
	Default: no dump file.
253

    
254
	<tag>mrtdump protocols all|off|{ states, messages }</tag>
255
	Set global defaults of MRTdump options. See <cf/mrtdump/ in the following section.
256
	Default: off.
257

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

    
261
	<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
262
	about functions in the following chapter.
263
 
264
	<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
265
	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
266
	about configuring protocols in their own chapters. You can run more than one instance of
267
	most protocols (like RIP or BGP). By default, no instances are configured.
268

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

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

    
276
	<tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
277
	This option allows to specify address and port where BGP
278
	protocol should listen. It is global option as listening
279
	socket is common to all BGP instances. Default is to listen on
280
	all addresses (0.0.0.0) and port 179. In IPv6 mode, option
281
	<cf/dual/ can be used to specify that BGP socket should accept
282
	both IPv4 and IPv6 connections (but even in that case, BIRD
283
	would accept IPv6 routes only). Such behavior was default in
284
	older versions of BIRD.
285

    
286
	<tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
287
	This option allows to specify a format of date/time used by
288
	BIRD.  The first argument specifies for which purpose such
289
	format is used. <cf/route/ is a format used in 'show route'
290
	command output, <cf/protocol/ is used in 'show protocols'
291
	command output, <cf/base/ is used for other commands and
292
	<cf/log/ is used in a log file.
293

    
294
	"<m/format1/" is a format string using <it/strftime(3)/
295
	notation (see <it/man strftime/ for details). <m/limit> and
296
	"<m/format2/" allow to specify the second format string for
297
	times in past deeper than <m/limit/ seconds. There are two
298
	shorthands: <cf/iso long/ is a ISO 8601 date/time format
299
	(YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
300
	%T"/. <cf/iso short/ is a variant of ISO 8601 that uses just
301
	the time format (hh:mm:ss) for near times (up to 20 hours in
302
	the past) and the date format (YYYY-MM-DD) for far times. This
303
	is a shorthand for <cf/"%T" 72000 "%F"/.
304

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

    
311
	<tag>table <m/name/</tag> Create a new routing table. The default
312
	routing table is created implicitly, other routing tables have
313
	to be added by this command.
314

    
315
	<tag>eval <m/expr/</tag> Evaluates given filter expression. It
316
	is used by us for testing of filters.
317
</descrip>
318

    
319
<sect>Protocol options
320

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

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

    
331
<descrip>
332
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
333

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

    
337
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
338
	Set protocol debugging options. If asked, each protocol is capable of
339
	writing trace messages about its work to the log (with category
340
	<cf/trace/). You can either request printing of <cf/all/ trace messages
341
	or only of the types selected: <cf/states/ for protocol state changes
342
	(protocol going up, down, starting, stopping etc.),
343
	<cf/routes/ for routes exchanged with the routing table,
344
	<cf/filters/ for details on route filtering,
345
	<cf/interfaces/ for interface change events sent to the protocol,
346
	<cf/events/ for events internal to the protocol and
347
	<cf/packets/ for packets sent and received by the protocol. Default: off.
348

    
349
	<tag>mrtdump all|off|{ states, messages }</tag>
350

    
351
	Set protocol MRTdump flags. MRTdump is a standard binary
352
	format for logging information from routing protocols and
353
	daemons.  These flags control what kind of information is
354
	logged from the protocol to the MRTdump file (which must be
355
	specified by global <cf/mrtdump/ option, see the previous
356
	section). Although these flags are similar to flags of
357
	<cf/debug/ option, their meaning is different and
358
	protocol-specific. For BGP protocol, <cf/states/ logs BGP
359
	state changes and <cf/messages/ logs received BGP messages.
360
	Other protocols does not support MRTdump yet.
361

    
362
	<tag>router id <m/IPv4 address/</tag> This option can be used
363
	to override global router id for a given protocol. Default:
364
	uses global router id.
365

    
366
	<tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> 
367
	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/.
368

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

    
372
	<tag>description "<m/text/"</tag> This is an optional
373
	description of the protocol. It is displayed as a part of the
374
	output of 'show route all' command.
375

    
376
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
377
</descrip>
378

    
379
<p>There are several options that give sense only with certain protocols:
380

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

    
384
	Specifies a set of interfaces on which the protocol is activated with
385
	given interface-specific options. A set of interfaces specified by one
386
	interface option is described using an interface pattern. The
387
	interface pattern consists of a sequence of clauses (separated by
388
	commas), each clause may contain a mask, a prefix, or both of them. An
389
	interface matches the clause if its name matches the mask (if
390
	specified) and its address matches the prefix (if specified). Mask is
391
	specified as shell-like pattern. For IPv6, the prefix part of a clause
392
	is generally ignored and interfaces are matched just by their name.
393

    
394
	An interface matches the pattern if it matches any of its
395
	clauses. If the clause begins with <cf/-/, matching interfaces are
396
	excluded. Patterns are parsed left-to-right, thus
397
	<cf/interface "eth0", -"eth*", "*";/ means eth0 and all
398
	non-ethernets.
399

    
400
	An interface option can be used more times with different
401
	interfaces-specific options, in that case for given interface
402
	the first matching interface option is used.
403
	
404
	This option is allowed in Direct, OSPF, RIP and RAdv protocols,
405
	but in OSPF protocol it is used in <cf/area/ subsection.
406

    
407
	Default: none.
408

    
409
	Examples:
410

    
411
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
412
	<cf>type broadcast</cf> option.
413

    
414
	<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the protocol
415
	on enumerated interfaces with <cf>type ptp</cf> option.
416
	
417
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
418
	interfaces that have address from 192.168.0.0/16, but not
419
	from 192.168.1.0/24.
420

    
421
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
422
	interfaces that have address from 192.168.0.0/16, but not
423
	from 192.168.1.0/24.
424

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

    
428
	<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>
429
	Specifies a password that can be used by the protocol. Password option can
430
	be used more times to specify more passwords. If more passwords are
431
	specified, it is a protocol-dependent decision which one is really
432
	used. Specifying passwords does not mean that authentication is
433
	enabled, authentication can be enabled by separate, protocol-dependent
434
	<cf/authentication/ option.
435
	
436
	This option is allowed in OSPF and RIP protocols. BGP has also
437
	<cf/password/ option, but it is slightly different and described
438
	separately.
439

    
440
	Default: none.
441
</descrip>
442

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

    
445
<descrip>
446
	<tag>id <M>num</M></tag>
447
	 ID of the password, (0-255). If it's not used, BIRD will choose
448
	 ID based on an order of the password item in the interface. For
449
	 example, second password item in one interface will have default
450
	 ID 2. ID is used by some routing protocols to identify which
451
	 password was used to authenticate protocol packets.
452

    
453
	<tag>generate from "<m/time/"</tag>
454
	 The start time of the usage of the password for packet signing.
455
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
456

    
457
	<tag>generate to "<m/time/"</tag>
458
	 The last time of the usage of the password for packet signing.
459

    
460
	<tag>accept from "<m/time/"</tag>
461
	 The start time of the usage of the password for packet verification.
462

    
463
	<tag>accept to "<m/time/"</tag>
464
	 The last time of the usage of the password for packet verification.
465
</descrip>
466

    
467
<chapt>Remote control
468

    
469
<p>You can use the command-line client <file>birdc</file> to talk with
470
a running BIRD. Communication is done using a <file/bird.ctl/ UNIX
471
domain socket (unless changed with the <tt/-s/ option given to both
472
the server and the client). The commands can perform simple actions
473
such as enabling/disabling of protocols, telling BIRD to show various
474
information, telling it to show routing table filtered by filter, or
475
asking BIRD to reconfigure. Press <tt/?/ at any time to get online
476
help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
477
client, which allows just read-only commands (<cf/show .../). Option
478
<tt/-v/ can be passed to the client, to make it dump numeric return
479
codes along with the messages. You do not necessarily need to use
480
<file/birdc/ to talk to BIRD, your own applications could do that, too
481
-- the format of communication between BIRD and <file/birdc/ is stable
482
(see the programmer's documentation).
483

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

    
487
<p>Here is a brief list of supported functions:
488

    
489
<descrip>
490
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
491
	Dump contents of internal data structures to the debugging output.
492

    
493
	<tag>show status</tag>
494
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
495

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

    
499
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
500
	Show detailed information about OSPF interfaces.
501

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

    
505
	<tag>show ospf state [all] [<m/name/]</tag>
506
	Show detailed information about OSPF areas based on a content
507
	of the link-state database. It shows network topology, stub
508
	networks, aggregated networks and routers from other areas and
509
	external routes. The command shows information about reachable
510
	network nodes, use option <cf/all/ to show information about
511
	all network nodes in the link-state database.
512

    
513
	<tag>show ospf topology [all] [<m/name/]</tag>
514
	Show a topology of OSPF areas based on a content of the
515
	link-state database.  It is just a stripped-down version of
516
	'show ospf state'.
517

    
518
	<tag>show static [<m/name/]</tag>
519
	Show detailed information about static routes.
520

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

    
524
	<tag>show symbols</tag>
525
	Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
526

    
527
	<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>
528
	Show contents of a routing table (by default of the main one),
529
	that is routes, their metrics and (in case the <cf/all/ switch is given)
530
	all their attributes.
531

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

    
539
	<p>You can also ask for printing only routes processed and accepted by
540
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
541
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
542
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
543
	that are exported to the specified protocol. With <cf/preexport/, the
544
	export filter of the protocol is skipped.
545

    
546
	<p>You can also select just routes added by a specific protocol.
547
	<cf>protocol <m/p/</cf>.
548

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

    
553
	<tag>configure [soft] ["<m/config file/"]</tag>
554
	Reload configuration from a given file. BIRD will smoothly
555
	switch itself to the new configuration, protocols are
556
	reconfigured if possible, restarted otherwise. Changes in
557
	filters usually lead to restart of affected protocols. If
558
	<cf/soft/ option is used, changes in filters does not cause
559
	BIRD to restart affected protocols, therefore already accepted
560
	routes (according to old filters) would be still propagated,
561
	but new routes would be processed according to the new
562
	filters.
563

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

    
567
	<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
568
	
569
	Reload a given protocol instance, that means re-import routes
570
	from the protocol instance and re-export preferred routes to
571
	the instance. If <cf/in/ or <cf/out/ options are used, the
572
	command is restricted to one direction (re-import or
573
	re-export).
574

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

    
580
	Re-export always succeeds, but re-import is protocol-dependent
581
	and might fail (for example, if BGP neighbor does not support
582
	route-refresh extension). In that case, re-export is also
583
	skipped. Note that for the pipe protocol, both directions are
584
	always reloaded together (<cf/in/ or <cf/out/ options are
585
	ignored in that case).
586

    
587
	<tag/down/
588
	Shut BIRD down.
589

    
590
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
591
	Control protocol debugging.
592
</descrip>
593

    
594
<chapt>Filters
595

    
596
<sect>Introduction
597

    
598
<p>BIRD contains a simple programming language. (No, it can't yet read mail :-). There are
599
two objects in this language: filters and functions. Filters are interpreted by BIRD core when a route is
600
being passed between protocols and routing tables. The filter language contains control structures such
601
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>. 
602

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

    
608
<code>
609
filter not_too_far
610
int var;
611
{
612
	if defined( rip_metric ) then
613
		var = rip_metric;
614
	else {
615
		var = 1;
616
		rip_metric = 1;
617
	}
618
	if rip_metric &gt; 10 then
619
		reject "RIP metric is too big";
620
	else
621
		accept "ok";
622
}
623
</code>
624

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

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

    
636
<code>
637
function name ()
638
int local_variable;
639
{
640
	local_variable = 5;
641
}
642

    
643
function with_parameters (int parameter)
644
{
645
	print parameter;
646
}
647
</code>
648

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

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

    
660
<p>A nice trick to debug filters is to use <cf>show route filter
661
<m/name/</cf> from the command line client. An example session might look
662
like:
663

    
664
<code>
665
pavel@bug:~/bird$ ./birdc -s bird.ctl
666
BIRD 0.0.0 ready.
667
bird> show route
668
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
669
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
670
127.0.0.0/8        dev lo [direct1 23:21] (240)
671
bird> show route ?
672
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
673
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
674
127.0.0.0/8        dev lo [direct1 23:21] (240)
675
bird>
676
</code>
677

    
678
<sect>Data types
679

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

    
683
<descrip>
684
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
685
	  <cf/false/. Boolean is the only type you can use in <cf/if/
686
	  statements.
687

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

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

    
695
	<tag/quad/ This is a dotted quad of numbers used to represent
696
	  router IDs (and others).  Each component can have a value
697
	  from 0 to 255. Literals of this type are written like IPv4
698
	  addresses.
699

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

    
705
	<tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it
706
	  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>
707
	  on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP
708
	  address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
709

    
710
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
711
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
712
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
713
	  operators on prefixes:
714
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
715
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
716

    
717
	<tag/int|pair|quad|ip|prefix|enum set/
718
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
719
	  but you can't modify them. Literals of type <cf>int set</cf> look like <cf>
720
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
721
	  sets.
722
	  For pair sets, expressions like <cf/(123,*)/ can be used to denote ranges (in
723
	  that case <cf/(123,0)..(123,65535)/). You can also use <cf/(123,5..100)/ for range
724
	  <cf/(123,5)..(123,100)/. You can also use <cf/(*,123)/ which is translated as
725
	  <cf/(0,123) , (1,123) , (2,123) , ... , (65535, 123)/
726
	  You can also use expressions for both, pair sets and int sets. However it must
727
	  be possible to evaluate these expressions before daemon boots. So you can use
728
	  only constants inside them. E.g.
729
	<code>
730
	 define one=1;
731
	 int set odds;
732
	 pair set ps;
733

    
734
	 odds = [ one, (2+1), (6-one), (2*2*2-1), 9, 11 ]; 
735
	 ps = [ (1,(one+one)), (3,4)..(4,8), (5,*), (6,3..6) ];
736
	</code>
737

    
738
	  Sets of prefixes are special: their literals does not allow ranges, but allows
739
	  prefix patterns that are written as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
740
	  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 
741
	  the first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are identical and <cf>len1 &lt;= ip1 &lt;= len2</cf>.
742
	  A valid prefix pattern has to satisfy <cf>low &lt;= high</cf>, but <cf/pxlen/ is not constrained by <cf/low/
743
	  or <cf/high/. Obviously, a prefix matches a prefix set literal if it matches any prefix pattern in the
744
	  prefix set literal.
745

    
746
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
747
	  <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), 
748
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
749
	  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>
750
	  and all its supernets (network prefixes that contain it).
751

    
752
	  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
753
	  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
754
	  <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
755
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
756
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
757
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
758

    
759
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
760
	  in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
761
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
762
	  <cf>192.168.0.0/16{24,32}</cf>.
763

    
764
	<tag/enum/
765
	  Enumeration types are fixed sets of possibilities. You can't define your own
766
	  variables of such type, but some route attributes are of enumeration
767
	  type. Enumeration types are incompatible with each other.
768

    
769
	<tag/bgppath/
770
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
771
	  There are several special operators on bgppaths:
772

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

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

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

    
780
          <cf><m/P/.len</cf> returns the length of path <m/P/.
781

    
782
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
783
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
784
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
785
          (for example <cf/bgp_path/).
786

    
787
	<tag/bgpmask/
788
	  BGP masks are patterns used for BGP path matching
789
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
790
	  resemble wildcard patterns as used by UNIX shells. Autonomous
791
	  system numbers match themselves, <cf/*/ matches any (even empty)
792
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
793
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
794
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
795
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
796
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
797
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
798
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
799

    
800
	<tag/clist/
801
	  Clist is similar to a set, except that unlike other sets, it
802
	  can be modified. The type is used for community list (a set
803
	  of pairs) and for cluster list (a set of quads). There exist
804
	  no literals of this type. There are two special operators on
805
	  clists:
806

    
807
          <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist
808
	  <m/C/ and returns the result.  If item <m/P/ is already in
809
	  clist <m/C/, it does nothing.
810

    
811
          <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad)
812
	  <m/P/ from clist <m/C/ and returns the result.  If clist
813
	  <m/C/ does not contain item <m/P/, it does nothing.
814
	  <m/P/ may also be a pair (or quad) set, in that case the
815
	  operator deletes all items from clist <m/C/ that are also
816
	  members of set <m/P/.
817

    
818
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
819
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute
820
          (for example <cf/bgp_community/). Similarly for <cf/delete/.
821

    
822
</descrip>
823

    
824
<sect>Operators
825

    
826
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
827
<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;/). 
828
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
829
used on element and set of elements of the same type (returning true if element is contained in the given set), or
830
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
831
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).
832

    
833

    
834
<sect>Control structures
835

    
836
<p>Filters support two control structures: conditions and case switches. 
837

    
838
<p>Syntax of a condition is: <cf>if
839
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
840
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
841
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.
842

    
843
<p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else: |
844
<m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. The expression after
845
<cf>case</cf> can be of any type which can be on the left side of the &tilde; operator and anything that could
846
be a member of a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping.
847
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.
848

    
849
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
850

    
851
<code>
852
case arg1 {
853
	2: print "two"; print "I can do more commands without {}";
854
	3 .. 5: print "three to five";
855
	else: print "something else";
856
}
857

    
858
if 1234 = i then printn "."; else { 
859
  print "not 1234"; 
860
  print "You need {} around multiple commands"; 
861
}
862
</code>
863

    
864
<sect>Route attributes
865

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

    
873
<descrip>
874
	<tag><m/prefix/ net</tag>
875
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
876

    
877
	<tag><m/enum/ scope</tag>
878
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for
879
	routes local to this host, <cf/SCOPE_LINK/ for those specific
880
	for a physical link, <cf/SCOPE_SITE/ and
881
	<cf/SCOPE_ORGANIZATION/ for private routes and
882
	<cf/SCOPE_UNIVERSE/ for globally visible routes. This
883
	attribute is not interpreted by BIRD and can be used to mark
884
	routes in filters. The default value for new routes is
885
	<cf/SCOPE_UNIVERSE/.
886

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

    
890
	<tag><m/ip/ from</tag>
891
	The router which the route has originated from. Read-only.
892
	
893
	<tag><m/ip/ gw</tag>
894
	Next hop packets routed using this route should be forwarded to.
895

    
896
	<tag><m/string/ proto</tag>
897
	The name of the protocol which the route has been imported from. Read-only.
898

    
899
	<tag><m/enum/ source</tag>
900
	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/.
901

    
902
	<tag><m/enum/ cast</tag>
903

    
904
	Route type (Currently <cf/RTC_UNICAST/ for normal routes,
905
	<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will
906
	be used in the future for broadcast, multicast and anycast
907
	routes). Read-only.
908

    
909
	<tag><m/enum/ dest</tag>
910
	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.
911

    
912
	<tag><m/int/ igp_metric</tag>
913
	The optional attribute that can be used to specify a distance
914
	to the network for routes that do not have a native protocol
915
	metric attribute (like <cf/ospf_metric1/ for OSPF routes). It
916
	is used mainly by BGP to compare internal distances to boundary
917
	routers (see below). It is also used when the route is exported
918
	to OSPF as a default value for OSPF type 1 metric.
919
</descrip>
920

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

    
923
<sect>Other statements
924

    
925
<p>The following statements are available:
926

    
927
<descrip>
928
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
929

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

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

    
934
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
935
	Prints given expressions; useful mainly while debugging
936
	filters. The <cf/printn/ variant does not terminate the line.
937

    
938
	<tag>quitbird</tag>
939
	Terminates BIRD. Useful when debugging the filter interpreter.
940
</descrip>
941

    
942
<chapt>Protocols
943

    
944
<sect>BGP
945

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

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

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

    
969
<p>BIRD supports all requirements of the BGP4 standard as defined in
970
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
971
It also supports the community attributes
972
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
973
capability negotiation
974
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
975
MD5 password authentication
976
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
977
route reflectors 
978
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
979
multiprotocol extensions
980
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
981
and 4B AS numbers 
982
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">).
983

    
984

    
985
For IPv6, it uses the standard multiprotocol extensions defined in
986
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
987
including changes described in the
988
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
989
and applied to IPv6 according to
990
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
991

    
992
<sect1>Route selection rules
993

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

    
1000
<itemize>
1001
	<item>Prefer route with the highest Local Preference attribute.
1002
	<item>Prefer route with the shortest AS path.
1003
	<item>Prefer IGP origin over EGP and EGP origin over incomplete.
1004
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
1005
	<item>Prefer routes received via eBGP over ones received via iBGP.
1006
	<item>Prefer routes with lower internal distance to a boundary router.
1007
	<item>Prefer the route with the lowest value of router ID of the
1008
	advertising router.
1009
</itemize>
1010

    
1011
<sect1>IGP routing table
1012

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

    
1022
<sect1>Configuration
1023

    
1024
<p>Each instance of the BGP corresponds to one neighboring router.
1025
This allows to set routing policy and all the other parameters differently
1026
for each neighbor using the following configuration parameters:
1027

    
1028
<descrip>
1029
	<tag>local [<m/ip/] as <m/number/</tag> Define which AS we
1030
	are part of. (Note that contrary to other IP routers, BIRD is
1031
	able to act as a router located in multiple AS'es
1032
	simultaneously, but in such cases you need to tweak the BGP
1033
	paths manually in the filters to get consistent behavior.)
1034
	Optional <cf/ip/ argument specifies a source address,
1035
	equivalent to the <cf/source address/ option (see below).
1036
	This parameter is mandatory.
1037

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

    
1044
	<tag>multihop [<m/number/]</tag> Configure multihop BGP
1045
	session to a neighbor that isn't directly connected.
1046
	Accurately, this option should be used if the configured
1047
	neighbor IP address does not match with any local network
1048
	subnets. Such IP address have to be reachable through system
1049
	routing table. For multihop BGP it is recommended to
1050
	explicitly configure <cf/source address/ to have it
1051
	stable. Optional <cf/number/ argument can be used to limit TTL
1052
	(the number of hops).
1053
	Default: switched off.
1054

    
1055
	<tag>source address <m/ip/</tag> Define local address we
1056
	should use for next hop calculation and as a source address
1057
	for the BGP session. Default: the address of the local
1058
	end of the interface our neighbor is connected to.
1059

    
1060
	<tag>next hop self</tag> Avoid calculation of the Next Hop
1061
	attribute and always advertise our own source address as a
1062
	next hop.  This needs to be used only occasionally to
1063
	circumvent misconfigurations of other routers.  Default:
1064
	disabled.
1065

    
1066
	<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
1067
	in BGP-IPv6 sometimes contains just the global IPv6 address,
1068
	but sometimes it has to contain both global and link-local
1069
	IPv6 addresses. This option specifies what to do if BIRD have
1070
	to send both addresses but does not know link-local address.
1071
	This situation might happen when routes from other protocols
1072
	are exported to BGP, or when improper updates are received
1073
	from BGP peers.  <cf/self/ means that BIRD advertises its own
1074
	local address instead. <cf/drop/ means that BIRD skips that
1075
	prefixes and logs error. <cf/ignore/ means that BIRD ignores
1076
	the problem and sends just the global address (and therefore
1077
	forms improper BGP update). Default: <cf/self/, unless BIRD
1078
	is configured as a route server (option <cf/rs client/), in
1079
	that case default is <cf/ignore/, because route servers usually
1080
	do not forward packets themselves.
1081

    
1082
	<tag>gateway direct|recursive</tag>For received routes, their
1083
	<cf/gw/ (immediate next hop) attribute is computed from
1084
	received <cf/bgp_next_hop/ attribute. This option specifies
1085
	how it is computed. Direct mode means that the IP address from
1086
	<cf/bgp_next_hop/ is used if it is directly reachable,
1087
	otherwise the neighbor IP address is used. Recursive mode
1088
	means that the gateway is computed by an IGP routing table
1089
	lookup for the IP address from <cf/bgp_next_hop/. Recursive
1090
	mode is the behavior specified by the BGP standard. Direct
1091
	mode is simpler, does not require any routes in a routing
1092
	table, and was used in older versions of BIRD, but does not
1093
	handle well nontrivial iBGP setups and multihop. Default:
1094
	<cf/direct/ for singlehop eBGP, <cf/recursive/ otherwise.
1095

    
1096
	<tag>igp table <m/name/</tag> Specifies a table that is used
1097
	as an IGP routing table. Default: the same as the table BGP is
1098
	connected to.
1099
	
1100
	<tag>password <m/string/</tag> Use this password for MD5 authentication
1101
	of BGP sessions. Default: no authentication. Password has to be set by
1102
	external utility (e.g. setkey(8)) on BSD systems.
1103

    
1104
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
1105
        initiating outgoing connections and accepting incoming
1106
        connections. In passive mode, outgoing connections are not
1107
        initiated. Default: off.
1108

    
1109
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
1110
	a route reflection client. Default: disabled.
1111

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

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

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

    
1138
	<tag>interpret communities <m/switch/</tag> RFC 1997 demands
1139
	that BGP speaker should process well-known communities like
1140
	no-export (65535, 65281) or no-advertise (65535, 65282). For
1141
	example, received route carrying a no-adverise community
1142
	should not be advertised to any of its neighbors. If this
1143
	option is enabled (which is by default), BIRD has such
1144
	behavior automatically (it is evaluated when a route is
1145
	exported to the BGP protocol just before the export filter).
1146
	Otherwise, this integrated processing of well-known
1147
	communities is disabled. In that case, similar behavior can be
1148
	implemented in the export filter.  Default: on.
1149

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

    
1158
	<tag>capabilities <m/switch/</tag> Use capability advertisement
1159
	to advertise optional capabilities. This is standard behavior
1160
	for newer BGP implementations, but there might be some older
1161
	BGP implementations that reject such connection attempts.
1162
	When disabled (off), features that request it (4B AS support)
1163
	are also disabled. Default: on, with automatic fallback to
1164
	off when received capability-related error.
1165

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

    
1172
	<tag>route limit <m/number/</tag> The maximal number of routes
1173
	that may be imported from the protocol. If the route limit is
1174
	exceeded, the connection is closed with error. Default: no limit.
1175

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

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

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

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

    
1192
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
1193
	retrying a failed attempt to connect. Default: 120 seconds.
1194

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

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

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

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

    
1210
	<tag>med metric <m/switch/</tag> Enable comparison of MED
1211
	attributes (during best route selection) even between routes
1212
	received from different ASes.  This may be useful if all MED
1213
	attributes contain some consistent metric, perhaps enforced in
1214
	import filters of AS boundary routers. If this option is
1215
	disabled, MED attributes are compared only if routes are
1216
	received from the same AS (which is the standard behavior).
1217
	Default: off.
1218

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

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

    
1227
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
1228
	Discriminator to be used during route selection when the MED attribute
1229
	is missing. Default: 0.
1230

    
1231
	<tag>default bgp_local_pref <m/number/</tag> A default value
1232
	for the Local Preference attribute. It is used when a new
1233
	Local Preference attribute is attached to a route by the BGP
1234
	protocol itself (for example, if a route is received through
1235
	eBGP and therefore does not have such attribute). Default: 100
1236
	(0 in pre-1.2.0 versions of BIRD).
1237
</descrip>
1238

    
1239
<sect1>Attributes
1240

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

    
1245
<descrip>
1246
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1247
	the packet will travel through when forwarded according to the particular route.
1248
	In case of internal BGP it doesn't contain the number of the local AS.
1249

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

    
1254
	<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
1255
	is an optional attribute which is used on external (inter-AS) links to
1256
	convey to an adjacent AS the optimal entry point into the local AS.
1257
	The received attribute is also propagated over internal BGP links.
1258
	The attribute value is zeroed when a route is exported to an external BGP
1259
	instance to ensure that the attribute received from a neighboring AS is
1260
	not propagated to other neighboring ASes. A new value might be set in
1261
	the export filter of an external BGP instance.
1262
	See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
1263
	for further discussion of BGP MED attribute.
1264

    
1265
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1266
	if the route has originated in an interior routing protocol or
1267
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1268
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1269
	is unknown.
1270

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

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

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

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

    
1299
	<tag>clist <cf/bgp_cluster_list/ [I, O]</tag> This attribute contains a list
1300
	of cluster IDs of route reflectors. Each route reflector prepends its
1301
	cluster ID when reflecting the route.
1302
</descrip>
1303

    
1304
<sect1>Example
1305

    
1306
<p><code>
1307
protocol bgp {
1308
	local as 65000;			     # Use a private AS number
1309
	neighbor 62.168.0.130 as 5588;	     # Our neighbor ...
1310
	multihop;			     # ... which is connected indirectly
1311
	export filter {			     # We use non-trivial export rules
1312
		if source = RTS_STATIC then { # Export only static routes
1313
		        # Assign our community
1314
			bgp_community.add((65000,5678));
1315
			# Artificially increase path length
1316
			# by advertising local AS number twice
1317
			if bgp_path ~ [= 65000 =] then	  
1318
				bgp_path.prepend(65000);  
1319
			accept;
1320
		}
1321
		reject;
1322
	};
1323
	import all;
1324
	source address 62.168.0.1;	# Use a non-standard source address
1325
}
1326
</code>
1327

    
1328
<sect>Device
1329

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

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

    
1338
<sect1>Configuration
1339

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

    
1347
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1348
	If a network interface has more than one network address, BIRD
1349
	has to choose one of them as a primary one. By default, BIRD
1350
	chooses the lexicographically smallest address as the primary
1351
	one.
1352

    
1353
	This option allows to specify which network address should be
1354
	chosen as a primary one. Network addresses that match
1355
	<m/prefix/ are preferred to non-matching addresses. If more
1356
	<cf/primary/ options are used, the first one has the highest
1357
	preference. If "<m/mask/" is specified, then such
1358
	<cf/primary/ option is relevant only to matching network
1359
	interfaces.
1360

    
1361
	In all cases, an address marked by operating system as
1362
	secondary cannot be chosen as the primary one. 
1363
</descrip>
1364

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

    
1368
<p><code>
1369
protocol device {
1370
	scan time 10;		# Scan the interfaces often
1371
	primary "eth0" 192.168.1.1;
1372
	primary 192.168.0.0/16;
1373
}
1374
</code>
1375

    
1376
<sect>Direct
1377

    
1378
<p>The Direct protocol is a simple generator of device routes for all the
1379
directly connected networks according to the list of interfaces provided
1380
by the kernel via the Device protocol.
1381

    
1382
<p>The question is whether it is a good idea to have such device
1383
routes in BIRD routing table. OS kernel usually handles device routes
1384
for directly connected networks by itself so we don't need (and don't
1385
want) to export these routes to the kernel protocol. OSPF protocol
1386
creates device routes for its interfaces itself and BGP protocol is
1387
usually used for exporting aggregate routes. Although there are some
1388
use cases that use the direct protocol (like abusing eBGP as an IGP
1389
routing protocol), in most cases it is not needed to have these device
1390
routes in BIRD routing table and to use the direct protocol.
1391

    
1392
<p>The only configurable thing about direct is what interfaces it watches:
1393

    
1394
<p><descrip>
1395
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
1396
	protocol will generate device routes for all the interfaces
1397
	available. If you want to restrict it to some subset of interfaces
1398
	(for example if you're using multiple routing tables for policy
1399
	routing and some of the policy domains don't contain all interfaces),
1400
	just use this clause.
1401
</descrip>
1402

    
1403
<p>Direct device routes don't contain any specific attributes.
1404

    
1405
<p>Example config might look like this:
1406

    
1407
<p><code>
1408
protocol direct {
1409
	interface "-arc*", "*";		# Exclude the ARCnets
1410
}
1411
</code>
1412

    
1413
<sect>Kernel
1414

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

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

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

    
1441
<p>Because the kernel protocol is partially integrated with the
1442
connected routing table, there are two limitations - it is not
1443
possible to connect more kernel protocols to the same routing table
1444
and changing route attributes (even the kernel ones) in an export
1445
filter of a kernel protocol does not work. Both limitations can be
1446
overcome using another routing table and the pipe protocol.
1447

    
1448
<sect1>Configuration
1449

    
1450
<p><descrip>
1451
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1452
	routing tables when it exits (instead of cleaning them up).
1453
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1454
	kernel routing table.
1455
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1456
	routing tables by other routing daemons or by the system administrator.
1457
	This is possible only on systems which support identification of route
1458
	authorship.
1459

    
1460
	<tag>device routes <m/switch/</tag> Enable export of device
1461
	routes to the kernel routing table. By default, such routes
1462
	are rejected (with the exception of explicitly configured
1463
	device routes from the static protocol) regardless of the
1464
	export filter to protect device routes in kernel routing table
1465
	(managed by OS itself) from accidental overwriting or erasing.
1466

    
1467
	<tag>kernel table <m/number/</tag> Select which kernel table should
1468
	this particular instance of the Kernel protocol work with. Available
1469
	only on systems supporting multiple routing tables.
1470
</descrip>
1471

    
1472
<sect1>Attributes
1473

    
1474
<p>The Kernel protocol defines several attributes. These attributes
1475
are translated to appropriate system (and OS-specific) route attributes.
1476
We support these attributes:
1477

    
1478
<descrip>
1479
	<tag>ip <cf/krt_prefsrc/</tag> (Linux) The preferred source address.
1480
 	Used in source address selection for outgoing packets. Have to
1481
 	be one of IP addresses of the router.
1482

    
1483
	<tag>int <cf/krt_realm/</tag> (Linux) The realm of the route. Can be
1484
	used for traffic classification.
1485
</descrip>
1486

    
1487
<sect1>Example
1488

    
1489
<p>A simple configuration can look this way:
1490

    
1491
<p><code>
1492
protocol kernel {
1493
	export all;
1494
}
1495
</code>
1496

    
1497
<p>Or for a system with two routing tables:
1498

    
1499
<p><code>
1500
protocol kernel {		# Primary routing table
1501
	learn;			# Learn alien routes from the kernel
1502
	persist;		# Don't remove routes on bird shutdown
1503
	scan time 10;		# Scan kernel routing table every 10 seconds
1504
	import all;
1505
	export all;
1506
}
1507

    
1508
protocol kernel {		# Secondary routing table
1509
	table auxtable;
1510
	kernel table 100;
1511
	export all;
1512
}
1513
</code>
1514

    
1515
<sect>OSPF
1516

    
1517
<sect1>Introduction
1518

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

    
1530
<p>In OSPF, the autonomous system can be split to several areas in order
1531
to reduce the amount of resources consumed for exchanging the routing
1532
information and to protect the other areas from incorrect routing data.
1533
Topology of the area is hidden to the rest of the autonomous system.
1534

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

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

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

    
1552
<sect1>Configuration
1553

    
1554
<p>In the main part of configuration, there can be multiple definitions of
1555
OSPF areas, each with a different id. These definitions includes many other
1556
switches and multiple definitions of interfaces. Definition of interface
1557
may contain many switches and constant definitions and list of neighbors
1558
on nonbroadcast networks.
1559

    
1560
<code>
1561
protocol ospf &lt;name&gt; {
1562
	rfc1583compat &lt;switch&gt;;
1563
	tick &lt;num&gt;;
1564
	ecmp &lt;switch&gt; [limit &lt;num&gt;];
1565
	area &lt;id&gt; {
1566
		stub cost &lt;num&gt;;
1567
                networks {
1568
			&lt;prefix&gt;;
1569
			&lt;prefix&gt; hidden;
1570
		}
1571
		stubnet &lt;prefix&gt;;
1572
		stubnet &lt;prefix&gt; {
1573
			hidden &lt;switch&gt;;
1574
			summary &lt;switch&gt;;
1575
			cost &lt;num&gt;;
1576
		}
1577
		interface &lt;interface pattern&gt; {
1578
			cost &lt;num&gt;;
1579
			stub &lt;switch&gt;;
1580
			hello &lt;num&gt;;
1581
			poll &lt;num&gt;;
1582
			retransmit &lt;num&gt;;
1583
			priority &lt;num&gt;;
1584
			wait &lt;num&gt;;
1585
			dead count &lt;num&gt;;
1586
			dead &lt;num&gt;;
1587
			rx buffer [normal|large|&lt;num&gt;];
1588
			type [broadcast|bcast|pointopoint|ptp|
1589
				nonbroadcast|nbma|pointomultipoint|ptmp];
1590
			strict nonbroadcast &lt;switch&gt;;
1591
			check link &lt;switch&gt;;
1592
			ecmp weight &lt;num&gt;;
1593
			authentication [none|simple|cryptographic];
1594
			password "&lt;text&gt;";
1595
			password "&lt;text&gt;" {
1596
				id &lt;num&gt;;
1597
				generate from "&lt;date&gt;";
1598
				generate to "&lt;date&gt;";
1599
				accept from "&lt;date&gt;";
1600
				accept to "&lt;date&gt;";
1601
			};
1602
			neighbors {
1603
				&lt;ip&gt;;
1604
				&lt;ip&gt; eligible;
1605
			};
1606
		};
1607
		virtual link &lt;id&gt;	{
1608
			hello &lt;num&gt;;
1609
			retransmit &lt;num&gt;;
1610
			wait &lt;num&gt;;
1611
			dead count &lt;num&gt;;
1612
			dead &lt;num&gt;;
1613
			authentication [none|simple|cryptographic];
1614
			password "&lt;text&gt;";
1615
		};
1616
	};
1617
}
1618
</code>
1619

    
1620
<descrip>
1621
	<tag>rfc1583compat <M>switch</M></tag>
1622
	 This option controls compatibility of routing table
1623
	 calculation with RFC 1583<htmlurl
1624
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1625
	 value is no.
1626

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

    
1633
	<tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
1634
	 This option specifies whether OSPF is allowed to generate
1635
	 ECMP (equal-cost multipath) routes. Such routes are used when
1636
	 there are several directions to the destination, each with
1637
	 the same (computed) cost. This option also allows to specify
1638
	 a limit on maximal number of nexthops in one route. By
1639
	 default, ECMP is disabled.  If enabled, default value of the
1640
	 limit is 16.
1641

    
1642
	<tag>area <M>id</M></tag>
1643
	 This defines an OSPF area with given area ID (an integer or an IPv4
1644
	 address, similarly to a router ID). The most important area is
1645
	 the backbone (ID 0) to which every other area must be connected.
1646

    
1647
	<tag>stub cost <M>num</M></tag>
1648
	 No external (except default) routes are flooded into stub areas.
1649
         Setting this value marks area stub with defined cost of default route.
1650
	 Default value is no. (Area is not stub.)
1651

    
1652
	<tag>networks { <m/set/ }</tag>
1653
         Definition of area IP ranges. This is used in summary LSA origination.
1654
	 Hidden networks are not propagated into other areas.
1655

    
1656
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
1657
	 Stub networks are networks that are not transit networks
1658
	 between OSPF routers. They are also propagated through an
1659
	 OSPF area as a part of a link state database. By default,
1660
	 BIRD generates a stub network record for each primary network
1661
	 address on each OSPF interface that does not have any OSPF
1662
	 neighbors, and also for each non-primary network address on
1663
	 each OSPF interface. This option allows to alter a set of
1664
	 stub networks propagated by this router. 
1665

    
1666
	 Each instance of this option adds a stub network with given
1667
	 network prefix to the set of propagated stub network, unless
1668
	 option <cf/hidden/ is used. It also suppresses default stub
1669
	 networks for given network prefix. When option
1670
	 <cf/summary/ is used, also default stub networks that are
1671
	 subnetworks of given stub network are suppressed. This might
1672
	 be used, for example, to aggregate generated stub networks.
1673
	 
1674
	<tag>interface <M>pattern</M></tag>
1675
	 Defines that the specified interfaces belong to the area being defined.
1676
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
1677

    
1678
	<tag>virtual link <M>id</M></tag>
1679
	 Virtual link to router with the router id. Virtual link acts as a
1680
         point-to-point interface belonging to backbone. The actual area is
1681
         used as transport area. This item cannot be in the backbone.
1682

    
1683
	<tag>cost <M>num</M></tag>
1684
	 Specifies output cost (metric) of an interface. Default value is 10.
1685

    
1686
	<tag>stub <M>switch</M></tag>
1687
	 If set to interface it does not listen to any packet and does not send
1688
	 any hello. Default value is no.
1689

    
1690
	<tag>hello <M>num</M></tag>
1691
	 Specifies interval in seconds between sending of Hello messages. Beware, all
1692
	 routers on the same network need to have the same hello interval.
1693
	 Default value is 10.
1694

    
1695
	<tag>poll <M>num</M></tag>
1696
	 Specifies interval in seconds between sending of Hello messages for
1697
	 some neighbors on NBMA network. Default value is 20.
1698

    
1699
	<tag>retransmit <M>num</M></tag>
1700
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
1701
	 Default value is 5.
1702

    
1703
        <tag>priority <M>num</M></tag>
1704
	 On every multiple access network (e.g., the Ethernet) Designed Router
1705
	 and Backup Designed router are elected. These routers have some
1706
	 special functions in the flooding process. Higher priority increases
1707
	 preferences in this election. Routers with priority 0 are not
1708
	 eligible. Default value is 1.
1709

    
1710
	<tag>wait <M>num</M></tag>
1711
	 After start, router waits for the specified number of seconds between starting
1712
	 election and building adjacency. Default value is 40.
1713
	 
1714
	<tag>dead count <M>num</M></tag>
1715
	 When the router does not receive any messages from a neighbor in
1716
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
1717

    
1718
	<tag>dead <M>num</M></tag>
1719
	 When the router does not receive any messages from a neighbor in
1720
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
1721
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
1722

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

    
1728
	<tag>type broadcast|bcast</tag>
1729
	 BIRD detects a type of a connected network automatically, but
1730
	 sometimes it's convenient to force use of a different type
1731
	 manually. On broadcast networks (like ethernet), flooding
1732
	 and Hello messages are sent using multicasts (a single packet
1733
	 for all the neighbors). A designated router is elected and it
1734
	 is responsible for synchronizing the link-state databases and
1735
	 originating network LSAs. This network type cannot be used on
1736
	 physically NBMA networks and on unnumbered networks (networks
1737
	 without proper IP prefix).
1738

    
1739
	<tag>type pointopoint|ptp</tag>
1740
	 Point-to-point networks connect just 2 routers together. No
1741
	 election is performed and no network LSA is originated, which
1742
	 makes it simpler and faster to establish. This network type
1743
	 is useful not only for physically PtP ifaces (like PPP or
1744
	 tunnels), but also for broadcast networks used as PtP links.
1745
	 This network type cannot be used on physically NBMA networks.
1746

    
1747
	<tag>type nonbroadcast|nbma</tag>
1748
	 On NBMA networks, the packets are sent to each neighbor
1749
	 separately because of lack of multicast capabilities.
1750
	 Like on broadcast networks, a designated router is elected,
1751
	 which plays a central role in propagation of LSAs.
1752
	 This network type cannot be used on unnumbered networks.
1753

    
1754
	<tag>type pointomultipoint|ptmp</tag>
1755
	 This is another network type designed to handle NBMA
1756
	 networks. In this case the NBMA network is treated as a
1757
	 collection of PtP links. This is useful if not every pair of
1758
	 routers on the NBMA network has direct communication, or if
1759
	 the NBMA network is used as an (possibly unnumbered) PtP
1760
	 link.
1761

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

    
1766
	<tag>check link <M>switch</M></tag>
1767
	 If set, a hardware link state (reported by OS) is taken into
1768
	 consideration. When a link disappears (e.g. an ethernet cable is
1769
	 unplugged), neighbors are immediately considered unreachable
1770
	 and only the address of the iface (instead of whole network
1771
	 prefix) is propagated. It is possible that some hardware
1772
	 drivers or platforms do not implement this feature. Default value is no.
1773

    
1774
	<tag>ecmp weight <M>num</M></tag>
1775
	 When ECMP (multipath) routes are allowed, this value specifies
1776
	 a relative weight used for nexthops going through the iface.
1777
	 Allowed values are 1-256. Default value is 1.
1778

    
1779
	<tag>authentication none</tag>
1780
	 No passwords are sent in OSPF packets. This is the default value.
1781

    
1782
	<tag>authentication simple</tag>
1783
	 Every packet carries 8 bytes of password. Received packets
1784
	 lacking this password are ignored. This authentication mechanism is
1785
	 very weak.
1786

    
1787
	<tag>authentication cryptographic</tag>
1788
	 16-byte long MD5 digest is appended to every packet. For the digest
1789
         generation 16-byte long passwords are used. Those passwords are 
1790
         not sent via network, so this mechanism is quite secure.
1791
         Packets can still be read by an attacker.
1792

    
1793
	<tag>password "<M>text</M>"</tag>
1794
	 An 8-byte or 16-byte password used for authentication.
1795
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
1796

    
1797
	<tag>neighbors { <m/set/ } </tag>
1798
	 A set of neighbors to which Hello messages on NBMA or PtMP
1799
	 networks are to be sent. For NBMA networks, some of them
1800
	 could be marked as eligible.
1801

    
1802
</descrip>
1803

    
1804
<sect1>Attributes
1805

    
1806
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
1807
Metric is ranging from 1 to infinity (65535).
1808
External routes use <cf/metric type 1/ or <cf/metric type 2/.
1809
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
1810
<cf/metric of type 2/ is always longer
1811
than any <cf/metric of type 1/ or any <cf/internal metric/.
1812
<cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute
1813
<cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/.
1814
If you specify both metrics only metric1 is used.
1815

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

    
1823
<sect1>Example
1824

    
1825
<p>
1826

    
1827
<code>
1828
protocol ospf MyOSPF {
1829
        rfc1583compat yes;
1830
        tick 2;
1831
	export filter {
1832
		if source = RTS_BGP then {
1833
			ospf_metric1 = 100;
1834
			accept;
1835
		}
1836
		reject;
1837
	};
1838
	area 0.0.0.0 {
1839
		interface "eth*" {
1840
			cost 11;
1841
			hello 15;
1842
			priority 100;
1843
			retransmit 7;
1844
			authentication simple;
1845
			password "aaa";
1846
		};
1847
		interface "ppp*" {
1848
			cost 100;
1849
			authentication cryptographic;
1850
			password "abc" {
1851
				id 1;
1852
				generate to "22-04-2003 11:00:06";
1853
				accept from "17-01-2001 12:01:05";
1854
			};
1855
			password "def" {
1856
				id 2;
1857
				generate to "22-07-2005 17:03:21";
1858
				accept from "22-02-2001 11:34:06";
1859
			};
1860
		};
1861
		interface "arc0" {
1862
			cost 10;
1863
			stub yes;
1864
		};
1865
		interface "arc1";
1866
	};
1867
	area 120 {
1868
		stub yes;
1869
		networks {
1870
			172.16.1.0/24;
1871
			172.16.2.0/24 hidden;
1872
		}
1873
		interface "-arc0" , "arc*" {
1874
			type nonbroadcast;
1875
			authentication none;
1876
			strict nonbroadcast yes;
1877
			wait 120;
1878
			poll 40;
1879
			dead count 8;
1880
			neighbors {
1881
				192.168.120.1 eligible;
1882
				192.168.120.2;
1883
				192.168.120.10;
1884
			};
1885
		};
1886
	};
1887
}
1888
</code>
1889

    
1890
<sect>Pipe
1891

    
1892
<sect1>Introduction
1893

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

    
1901
<p>The Pipe protocol may work in the opaque mode or in the transparent
1902
mode. In the opaque mode, the Pipe protocol retransmits optimal route
1903
from one table to the other table in a similar way like other
1904
protocols send and receive routes. Retransmitted route will have the
1905
source set to the Pipe protocol, which may limit access to protocol
1906
specific route attributes. The opaque mode is a default mode.
1907

    
1908
<p>In transparent mode, the Pipe protocol retransmits all routes from
1909
one table to the other table, retaining their original source and
1910
attributes.  If import and export filters are set to accept, then both
1911
tables would have the same content. The mode can be set by
1912
<tt/mode/ option.
1913

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

    
1925
<sect1>Configuration
1926

    
1927
<p><descrip>
1928
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
1929
	primary one is selected by the <cf/table/ keyword.
1930

    
1931
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
1932
</descrip>
1933

    
1934
<sect1>Attributes
1935

    
1936
<p>The Pipe protocol doesn't define any route attributes.
1937

    
1938
<sect1>Example
1939

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

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

    
1954
<code>
1955
table as1;				# Define the tables
1956
table as2;
1957

    
1958
protocol kernel kern1 {			# Synchronize them with the kernel
1959
	table as1;
1960
	kernel table 1;
1961
}
1962

    
1963
protocol kernel kern2 {
1964
	table as2;
1965
	kernel table 2;
1966
}
1967

    
1968
protocol bgp bgp1 {			# The outside connections
1969
	table as1;
1970
	local as 1;
1971
	neighbor 192.168.0.1 as 1001;
1972
	export all;
1973
	import all;
1974
}
1975

    
1976
protocol bgp bgp2 {
1977
	table as2;
1978
	local as 2;
1979
	neighbor 10.0.0.1 as 1002;
1980
	export all;
1981
	import all;
1982
}
1983

    
1984
protocol pipe {				# The Pipe
1985
	table as1;
1986
	peer table as2;
1987
	export filter {
1988
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
1989
			if preference>10 then preference = preference-10;
1990
			if source=RTS_BGP then bgp_path.prepend(1);
1991
			accept;
1992
		}
1993
		reject;
1994
	};
1995
	import filter {
1996
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
1997
			if preference>10 then preference = preference-10;
1998
			if source=RTS_BGP then bgp_path.prepend(2);
1999
			accept;
2000
		}
2001
		reject;
2002
	};
2003
}
2004
</code>
2005

    
2006
<sect>RAdv
2007

    
2008
<sect1>Introduction
2009

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

    
2019
<sect1>Configuration
2020

    
2021
<p>There are two classes of definitions in RAdv configuration --
2022
interface definitions and prefix definitions:
2023

    
2024
<descrip>
2025
	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag> 
2026
	Interface definitions specify a set of interfaces on which the
2027
	protocol is activated and contain interface specific options.
2028
	See <ref id="dsc-iface" name="interface"> common options for
2029
	detailed description.
2030

    
2031
	<tag>prefix <m/prefix/ { <m/options/ }</tag> 
2032
	Prefix definitions allows to modify a list of advertised
2033
	prefixes. By default, the advertised prefixes are the same as
2034
	the network prefixes assigned to the interface. For each
2035
	network prefix, the matching prefix definition is found and
2036
	its options are used. If no matching prefix definition is
2037
	found, the prefix is used with default options.
2038

    
2039
	Prefix definitions can be either global or interface-specific.
2040
	The second ones are part of interface options. The prefix
2041
	definition matching is done in the first-match style, when
2042
	interface-specific definitions are processed before global
2043
	definitions. As expected, the prefix definition is matching if
2044
	the network prefix is a subnet of the prefix in prefix
2045
	definition.
2046
</descrip>
2047

    
2048
<p>Interface specific options:
2049

    
2050
<descrip>
2051
	<tag>max ra interval <m/expr/</tag>
2052
	Unsolicited router advertisements are sent in irregular time
2053
	intervals. This option specifies the maximum length of these
2054
	intervals, in seconds. Valid values are 4-1800. Default: 600
2055

    
2056
	<tag>min ra interval <m/expr/</tag>
2057
	This option specifies the minimum length of that intervals, in
2058
	seconds. Must be at least 3 and at most 3/4 * max ra interval.
2059
	Default: about 1/3 * max ra interval.
2060

    
2061
	<tag>min delay <m/expr/</tag>
2062
	The minimum delay between two consecutive router advertisements,
2063
	in seconds. Default: 3
2064

    
2065
	<tag>managed <m/switch/</tag>
2066
	This option specifies whether hosts should use DHCPv6 for
2067
	IP address configuration. Default: no
2068

    
2069
	<tag>other config <m/switch/</tag>
2070
	This option specifies whether hosts should use DHCPv6 to
2071
	receive other configuration information. Default: no
2072

    
2073
	<tag>link mtu <m/expr/</tag>
2074
	This option specifies which value of MTU should be used by
2075
	hosts. 0 means unspecified. Default: 0
2076

    
2077
	<tag>reachable time <m/expr/</tag>
2078
	This option specifies the time (in milliseconds) how long
2079
	hosts should assume a neighbor is reachable (from the last
2080
	confirmation). Maximum is 3600000, 0 means unspecified.
2081
	Default 0.
2082

    
2083
	<tag>retrans timer <m/expr/</tag>
2084
	This option specifies the time (in milliseconds) how long
2085
	hosts should wait before retransmitting Neighbor Solicitation
2086
	messages. 0 means unspecified. Default 0.
2087

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

    
2092
	<tag>default lifetime <m/expr/</tag>
2093
	This option specifies the time (in seconds) how long (after
2094
	the receipt of RA) hosts may use the router as a default
2095
	router. 0 means do not use as a default router. Default: 3 *
2096
	max ra interval.
2097
</descrip>
2098

    
2099

    
2100
<p>Prefix specific options:
2101

    
2102
<descrip>
2103
	<tag>onlink <m/switch/</tag>
2104
	This option specifies whether hosts may use the advertised
2105
	prefix for onlink determination. Default: yes
2106

    
2107
	<tag>autonomous <m/switch/</tag>
2108
	This option specifies whether hosts may use the advertised
2109
	prefix for stateless autoconfiguration. Default: yes
2110

    
2111
	<tag>valid lifetime <m/expr/</tag>
2112
	This option specifies the time (in seconds) how long (after
2113
	the receipt of RA) the prefix information is valid, i.e.,
2114
	autoconfigured IP addresses can be assigned and hosts with
2115
	that IP addresses are considered directly reachable. 0 means
2116
	the prefix is no longer valid. Default: 86400 (1 day)
2117

    
2118
	<tag>preferred lifetime <m/expr/</tag>
2119
	This option specifies the time (in seconds) how long (after
2120
	the receipt of RA) IP addresses generated from the prefix
2121
	using stateless autoconfiguration remain preferred. Default:
2122
	14400 (4 hours)
2123
</descrip>
2124

    
2125
<sect1>Example
2126

    
2127
<p><code>
2128
protocol radv {
2129
	interface "eth2" {
2130
		max ra interval 5;	# Fast failover with more routers
2131
		managed yes;		# Using DHCPv6 on eth2
2132
		prefix ::/0 {
2133
			autonomous off;	# So do not autoconfigure any IP
2134
		};
2135
	};
2136

    
2137
	interface "eth*";		# No need for any other options
2138

    
2139
	prefix 2001:0DB8:1234::/48 {
2140
		preferred lifetime 0;	# Deprecated address range
2141
	};
2142

    
2143
	prefix 2001:0DB8:2000::/48 {
2144
		autonomous off;		# Do not autoconfigure
2145
	};
2146
}
2147
</code>
2148

    
2149
<sect>RIP
2150

    
2151
<sect1>Introduction
2152

    
2153
<p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors)
2154
distances to all networks it can reach. When a router hears distance to another network, it increments
2155
it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes
2156
unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus
2157
interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in
2158
RIP) and all routers know that network is unreachable. RIP tries to minimize situations where
2159
counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use
2160
RIP on networks where maximal distance is higher than 15 hosts. You can read more about RIP at <HTMLURL
2161
URL="http://www.ietf.org/html.charters/rip-charter.html" name="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4  
2162
(RFC 1723<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt">)
2163
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
2164
not currently supported. RIPv4 MD5 authentication (RFC 2082<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt">) is supported.
2165

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

    
2170
<sect1>Configuration
2171

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

    
2174
<descrip>
2175
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
2176
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
2177
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
2178
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
2179
	  section. Default: none.
2180

    
2181
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
2182
	  be honored. (Always, when sent from a  host on a directly connected
2183
	  network or never.) Routing table updates are honored only from
2184
	  neighbors, that is not configurable. Default: never.
2185
</descrip>
2186

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

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

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

    
2204
	<tag>infinity <M>number</M></tag>
2205
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
2206
	  even slower.
2207

    
2208
	<tag>period <M>number</M>
2209
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
2210
	  number will mean faster convergence but bigger network
2211
	  load. Do not use values lower than 10.
2212

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

    
2216
	<tag>garbage time <M>number</M>
2217
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
2218
</descrip>
2219

    
2220
<sect1>Attributes
2221

    
2222
<p>RIP defines two route attributes:
2223

    
2224
<descrip>
2225
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
2226
	When routes from different RIP instances are available and all of them have the same
2227
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
2228
	When importing a non-RIP route, the metric defaults to 5.
2229

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

    
2235
<sect1>Example
2236

    
2237
<p><code>
2238
protocol rip MyRIP_test {
2239
        debug all;
2240
        port 1520;
2241
        period 10;
2242
        garbage time 60;
2243
        interface "eth0" { metric 3; mode multicast; };
2244
	interface "eth*" { metric 2; mode broadcast; };
2245
        honor neighbor;
2246
        authentication none;
2247
        import filter { print "importing"; accept; };
2248
        export filter { print "exporting"; accept; };
2249
}
2250
</code>
2251

    
2252
<sect>Static
2253

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

    
2262
<p>There are three types of static routes: `classical' routes telling to
2263
forward packets to a neighboring router, device routes specifying forwarding
2264
to hosts on a directly connected network and special routes (sink, blackhole
2265
etc.) which specify a special action to be done instead of forwarding the
2266
packet.
2267

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

    
2273
<p>The Static protocol does not have many configuration options. The
2274
definition of the protocol contains mainly a list of static routes:
2275

    
2276
<descrip>
2277
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
2278
	a neighboring router.
2279
	<tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
2280
	Static multipath route. Contains several nexthops (gateways), possibly
2281
 	with their weights.
2282
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
2283
	route through an interface to hosts on a directly connected network.
2284
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
2285
	specifying to drop the packet, return it as unreachable or return
2286
	it as administratively prohibited.
2287

    
2288
	<tag>check link <M>switch</M></tag>
2289
	The only option of the static protocol. If set, hardware link
2290
	states of network interfaces are taken into consideration.
2291
	When link disappears (e.g. ethernet cable is unplugged),
2292
	static routes directing to that interface are removed. It is
2293
	possible that some hardware drivers or platforms do not
2294
	implement this feature. Default: off.
2295
</descrip>
2296

    
2297
<p>Static routes have no specific attributes.
2298

    
2299
<p>Example static config might look like this:
2300

    
2301
<p><code>
2302
protocol static {
2303
	table testable;			 # Connect to a non-default routing table
2304
	route 0.0.0.0/0 via 62.168.0.13; # Default route
2305
	route 10.0.0.0/8 multipath	 # Multipath route
2306
		via 62.168.0.14 weight 2
2307
		via 62.168.1.10
2308
		via 62.168.1.11;
2309
	route 62.168.0.0/25 reject;	 # Sink route
2310
	route 10.2.0.0/24 via "arc0";	 # Secondary network
2311
}
2312
</code>
2313

    
2314
<chapt>Conclusions
2315

    
2316
<sect>Future work
2317

    
2318
<p>Although BIRD supports all the commonly used routing protocols,
2319
there are still some features which would surely deserve to be
2320
implemented in future versions of BIRD:
2321

    
2322
<itemize>
2323
<item>OSPF NSSA areas and opaque LSA's
2324
<item>Route aggregation and flap dampening
2325
<item>Generation of IPv6 router advertisements
2326
<item>Multipath routes
2327
<item>Multicast routing protocols
2328
<item>Ports to other systems
2329
</itemize>
2330

    
2331
<sect>Getting more help
2332

    
2333
<p>If you use BIRD, you're welcome to join the bird-users mailing list
2334
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
2335
where you can share your experiences with the other users and consult
2336
your problems with the authors. To subscribe to the list, just send a
2337
<tt/subscribe bird-users/ command in a body of a mail to
2338
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
2339
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
2340

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

    
2348
<p>If you want to understand what is going inside, Internet standards are
2349
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">).
2350

    
2351
<p><it/Good luck!/
2352

    
2353
</book>
2354

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