Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 4d176e14

History | View | Annotate | Download (72.5 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
</author>
28

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

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

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

    
38
<chapt>Introduction
39

    
40
<sect>What is BIRD
41

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

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

    
49
<p><em/Internet Routing/: It's a program (well, a daemon, as you are going to discover in a moment)
50
which works as a dynamic router in an Internet type network (that is, in a network running either
51
the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected
52
networks in order to allow hosts not connected directly to the same local area network to
53
communicate with each other. They also communicate with the other routers in the Internet to discover
54
the topology of the network which allows them to find optimal (in terms of some metric) rules for
55
forwarding of packets (which are called routing tables) and to adapt themselves to the
56
changing conditions such as outages of network links, building of new connections and so on. Most of
57
these routers are costly dedicated devices running obscure firmware which is hard to configure and
58
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 
59
computer to act as a router and forward packets belonging to the other hosts, but only according to
60
a statically configured table.
61

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

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

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

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

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

    
100
<sect>Installing BIRD
101

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

    
104
<code>
105
        ./configure
106
        make
107
        make install
108
        vi /usr/local/etc/bird.conf
109
	bird
110
</code>
111

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

    
119
<sect>Running BIRD
120

    
121
<p>You can pass several command-line options to bird:
122

    
123
<descrip>
124
	<tag>-c <m/config name/</tag>
125
	use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
126

    
127
	<tag>-d</tag>
128
	enable debug messages and run bird in foreground.
129

    
130
	<tag>-D <m/filename of debug log/</tag>
131
	log debugging information to given file instead of stderr
132

    
133
	<tag>-s <m/name of communication socket/</tag>
134
	use given filename for a  socket for communications with the client, default is <it/prefix/<file>/var/run/bird.ctl</file>.
135
</descrip>
136

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

    
139
<chapt>About routing tables
140

    
141
<p>BIRD has one or more routing tables which may or may not be
142
synchronized with OS kernel and which may or may not be synchronized with
143
each other (see the Pipe protocol). Each routing table contains a list of
144
known routes. Each route consists of:
145

    
146
<itemize>
147
	<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)
148
	<item>preference of this route
149
	<item>IP address of router which told us about this route
150
	<item>IP address of router we should forward the packets to
151
	using this route
152
	<item>other attributes common to all routes
153
	<item>dynamic attributes defined by protocols which may or
154
	may not be present (typically protocol metrics)
155
</itemize>
156

    
157
Routing table maintains multiple entries
158
for a network, but at most one entry for one network and one
159
protocol. The entry with the highest preference is used for routing (we
160
will call such an entry the <it/selected route/). If
161
there are more entries with the same preference and they are from the same
162
protocol, the protocol decides (typically according to metrics). If they aren't,
163
an internal ordering is used to break the tie. You can
164
get the list of route attributes in the Route attributes section.
165

    
166
<p>Each protocol is connected to a routing table through two filters
167
which can accept, reject and modify the routes. An <it/export/
168
filter checks routes passed from the routing table to the protocol,
169
an <it/import/ filter checks routes in the opposite direction.
170
When the routing table gets a route from a protocol, it recalculates
171
the selected route and broadcasts it to all protocols connected to
172
the table. The protocols typically send the update to other routers
173
in the network.
174

    
175
<chapt>Configuration
176

    
177
<sect>Introduction
178

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

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

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

    
194

    
195
<code>
196
protocol kernel {
197
	persist;		# Don't remove routes on BIRD shutdown
198
	scan time 20;		# Scan kernel routing table every 20 seconds
199
	export all;		# Default is export none
200
}
201

    
202
protocol device {
203
	scan time 10;		# Scan interfaces every 10 seconds
204
}
205

    
206
protocol rip {
207
	export all;
208
	import all;
209
}
210
</code>
211

    
212

    
213
<sect>Global options
214

    
215
<p><descrip>
216
	<tag>log "<m/filename/"|syslog|stderr all|{ <m/list of classes/ }</tag> 
217
	Set logging of messages having the given class (either <cf/all/ or <cf/{
218
	error, trace }/ etc.) into selected destination. Classes are:
219
	<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
220
	<cf/debug/ for debugging messages, 
221
	<cf/trace/ when you want to know what happens in the network, 
222
	<cf/remote/ for messages about misbehavior of remote machines, 
223
	<cf/auth/ about authentication failures,
224
	<cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple
225
	destinations. Default: log everything to the system log.
226

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

    
230
	<tag>debug commands <m/number/</tag>
231
	Control logging of client connections (0 for no logging, 1 for
232
	logging of connects and disconnects, 2 and higher for logging of
233
	all client commands). Default: 0.
234

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

    
238
	<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
239
	about functions in the following chapter.
240
 
241
	<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
242
	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
243
	about configuring protocols in their own chapters. You can run more than one instance of
244
	most protocols (like RIP or BGP). By default, no instances are configured.
245

    
246
	<tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag> Define a constant. You can use it later in every place
247
	you could use a simple integer or an IP address.
248

    
249
	<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. 
250

    
251
	<tag>table <m/name/</tag> Create a new routing table. The default
252
	routing table is created implicitly, other routing tables have
253
	to be added by this command.
254

    
255
	<tag>eval <m/expr/</tag> Evaluates given filter expression. It
256
	is used by us for testing of filters.
257
</descrip>
258

    
259
<sect>Protocol options
260

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

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

    
271
<descrip>
272
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
273

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

    
277
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
278
	Set protocol debugging options. If asked, each protocol is capable of
279
	writing trace messages about its work to the log (with category
280
	<cf/trace/). You can either request printing of <cf/all/ trace messages
281
	or only of the types selected: <cf/states/ for protocol state changes
282
	(protocol going up, down, starting, stopping etc.),
283
	<cf/routes/ for routes exchanged with the routing table,
284
	<cf/filters/ for details on route filtering,
285
	<cf/interfaces/ for interface change events sent to the protocol,
286
	<cf/events/ for events internal to the protocol and
287
	<cf/packets/ for packets sent and received by the protocol. Default: off.
288

    
289
	<tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> 
290
	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/.
291

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

    
295
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
296
</descrip>
297

    
298
<p>There are several options that give sense only with certain protocols:
299

    
300
<descrip>
301
	<tag>passwords { password "<m/password/" from <m/time/ to <m/time/ passive <m/time/ id
302
	<m/num/ [...] }</tag> Specifies passwords to be used with this protocol. <cf>Passive <m/time/</cf> is
303
	time from which the password is not used for sending, but it is recognized on reception. <cf/id/ is password ID as needed by
304
	certain protocols. Format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
305

    
306
	<tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [...] } ]</tag> Specifies which
307
	interfaces is this protocol active on and allows you to set options on a
308
	per-interface basis. Mask is specified as in shell-like patterns, thus <cf>interface
309
	"*" { mode broadcast; };</cf> will start the protocol on all interfaces with <cf>mode
310
	broadcast;</cf> option. If the first character of mask is <cf/-/, such interfaces are
311
	excluded. Masks are parsed left-to-right, thus <cf/interface "-eth*", "*";/ means all but
312
	the ethernets. Default: none.
313

    
314
</descrip>
315

    
316
<chapt>Remote control
317

    
318
<p>You can use the command-line client <file>birdc</file> to talk with
319
a running BIRD. Communication is done using a <file/bird.ctl/ UNIX domain
320
socket (unless changed with the <tt/-s/ option given to both the server and
321
the client). The commands can perform simple actions such as enabling/disabling
322
of protocols, telling BIRD to show various information, telling it to
323
show routing table filtered by filter, or asking BIRD to
324
reconfigure. Press <tt/?/ at any time to get online help. Option
325
<tt/-v/ can be passed to the client, to make it dump numeric return
326
codes along with the messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your
327
own applications could do that, too -- the format of communication between
328
BIRD and <file/birdc/ is stable (see the programmer's documentation).
329

    
330
<p>Here is a brief list of supported functions:
331

    
332
<descrip>
333
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
334
	Dump contents of internal data structures to the debugging output.
335

    
336
	<tag>show status</tag>
337
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
338

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

    
342
	<tag>show ospf [interface|neighbors] [<m/name/] ["<m/interface/"]</tag>
343
	Show detailed information about OSPF protocol, possibly giving a verbose list of interfaces and neighbors. The <m/name/ of the protocol instance can be omitted if there exists only a single instance.
344

    
345
	<tag>show static [<m/name/]</tag>
346
	Show detailed information about static routes. The <m/name/ of the protocol instance can be omitted if there exists only a single instance.
347
	
348
	<tag>show interfaces [summary]</tag>
349
	Show the list of interfaces. For each interface, print its type, state, MTU and addresses assigned. 
350

    
351
	<tag>show symbols</tag>
352
	Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
353

    
354
	<tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(import|preimport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
355
	Show contents of a routing table (by default of the main one),
356
	that is routes, their metrics and (in case the <cf/all/ switch is given)
357
	all their attributes.
358

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

    
366
	<p>You can also ask for printing only routes processed and accepted by
367
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
368
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
369
	The <cf/import/ and <cf/preimport/ switches ask for printing of entries
370
        that are imported to the specified protocol. With <cf/preimport/, the
371
	import filter of the protocol is skipped.
372

    
373
	<p>You can also select just routes added by a specific protocol.
374
	<cf>protocol <m/p/</cf>.
375

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

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

    
383
	<tag>configure ["<m/config file/"]</tag>
384
	Reload configuration from a given file.
385

    
386
	<tag/down/
387
	Shut BIRD down.
388

    
389
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
390
	Control protocol debugging.
391
</descrip>
392

    
393
<chapt>Filters
394

    
395
<sect>Introduction
396

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

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

    
407
<code>
408
filter not_too_far
409
int var;
410
{
411
	if defined( rip_metric ) then
412
		var = rip_metric;
413
	else {
414
		var = 1;
415
		rip_metric = 1;
416
	}
417
	if rip_metric &gt; 10 then
418
		reject "RIP metric is too big";
419
	else
420
		accept "ok";
421
}
422
</code>
423

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

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

    
435
<code>
436
function name ()
437
int local_variable;
438
{
439
	local_variable = 5;
440
}
441

    
442
function with_parameters (int parameter)
443
{
444
	print parameter;
445
}
446
</code>
447

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

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

    
459
<p>A nice trick to debug filters is to use <cf>show route filter
460
<m/name/</cf> from the command line client. An example session might look
461
like:
462

    
463
<code>
464
pavel@bug:~/bird$ ./birdc -s bird.ctl
465
BIRD 0.0.0 ready.
466
bird> show route
467
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
468
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
469
127.0.0.0/8        dev lo [direct1 23:21] (240)
470
bird> show route ?
471
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
472
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
473
127.0.0.0/8        dev lo [direct1 23:21] (240)
474
bird>
475
</code>
476

    
477
<sect>Data types
478

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

    
482
<descrip>
483
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
484
	  <cf/false/. Boolean is the only type you can use in <cf/if/
485
	  statements.
486

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

    
490
	<tag/pair/ This is a pair of two short integers. Each component can have values from 0 to
491
	  65535. Literals of this type is written as <cf/(1234,5678)/.
492

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

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

    
503
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
504
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
505
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
506
	  operators on prefixes:
507
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
508
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
509

    
510
	<tag/int|ip|prefix|pair|enum set/
511
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
512
	  but you can't modify them. Literals of type <cf>set int</cf> look like <cf>
513
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
514
	  sets.
515

    
516
	  Sets of prefixes are special: their literals does not allow ranges, but allows
517
	  prefix patterns that are written as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
518
	  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> iff 
519
	  the first <cf>min(len1, len2)</cf> bits of <cf/ip1/> and <cf/ip2/ are identical and <cf>len1 &le; ip1 &le; len2</cf>.
520
	  A valid prefix pattern has to satisfy <cf/low &le; high/, but <cf/pxlen/ is not constrained by <cf/low/
521
	  or <cf/high/. Obviously, a prefix matches a prefix set literal iff it matches any prefix pattern in the
522
	  prefix set literal.
523

    
524
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
525
	  <cf><m>address</m>/<m/len/{<m/len/,<m/maxlen/}</cf> (where <cf><m>maxlen</m></c> is 32 for IPv4 and 128 for IPv6), 
526
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
527
	  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>
528
	  and all its supernets (network prefixes that contain it).
529

    
530
	  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
531
	  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
532
	  <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
533
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
534
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{ 15 , 17 } ]</cf> is true,
535
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
536

    
537
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
538
	  in Bird as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
539
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
540
	  <cf>192.168.0.0/16{24,32}</cf>.
541

    
542
	<tag/enum/
543
	  Enumeration types are fixed sets of possibilities. You can't define your own
544
	  variables of such type, but some route attributes are of enumeration
545
	  type. Enumeration types are incompatible with each other.
546

    
547
	<tag/bgppath/
548
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
549

    
550
	<tag/bgpmask/
551
	  BGP masks are patterns used for BGP path matching
552
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
553
	  resemble wildcard patterns as used by UNIX shells. Autonomous
554
	  system numbers match themselves, <cf/*/ matches any (even empty)
555
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
556
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
557
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
558
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
559
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
560
	<tag/clist/ 
561
	  Community list is similar to set of pairs,
562
	  except that unlike other sets, it can be modified.
563
	  There exist no literals of this type.
564

    
565
</descrip>
566

    
567
<sect>Operators
568

    
569
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
570
<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;/). 
571
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
572
used on element and set of elements of the same type (returning true if element is contained in the given set), or
573
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
574
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 and clist (returning true if the community is element of the community list).
575

    
576

    
577
<sect>Control structures
578

    
579
<p>Filters support two control structures: conditions and case switches. 
580

    
581
<p>Syntax of a condition is: <cf>if
582
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
583
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
584
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.
585

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

    
592
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
593

    
594
<code>
595
case arg1 {
596
	2: print "two"; print "I can do more commands without {}";
597
	3 .. 5: print "three to five";
598
	else: print "something else";
599
}
600

    
601
if 1234 = i then printn "."; else { 
602
  print "not 1234"; 
603
  print "You need {} around multiple commands"; 
604
}
605
</code>
606

    
607
<sect>Route attributes
608

    
609
<p>A filter is implicitly passed a route, and it can access its
610
attributes just like it accesses variables. Attempts to access undefined
611
attribute result in a runtime error; you can check if an attribute is
612
defined by using the <cf>defined( <m>attribute</m> )</cf> operator.
613

    
614
<descrip>
615
	<tag><m/prefix/ net</tag>
616
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
617

    
618
	<tag><m/enum/ scope</tag>
619
	Address scope of the network (<cf/SCOPE_HOST/ for addresses local to this host, <cf/SCOPE_LINK/ for those specific for a physical link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private addresses, <cf/SCOPE_UNIVERSE/ for globally visible addresses).
620

    
621
	<tag><m/int/ preference</tag>
622
	Preference of the route. (See the chapter about routing tables.)
623

    
624
	<tag><m/ip/ from</tag>
625
	The router which the route has originated from. Read-only.
626
	
627
	<tag><m/ip/ gw</tag>
628
	Next hop packets routed using this route should be forwarded to.
629

    
630
	<tag><m/string/ proto</tag>
631
	The name of the protocol which the route has been imported from. Read-only.
632

    
633
	<tag><m/enum/ source</tag>
634
	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_EXT/, <cf/RTS_BGP/, <cf/RTS_PIPE/.
635

    
636
	<tag><m/enum/ cast</tag>
637
	Route type (<cf/RTC_UNICAST/ for normal routes, <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ for broadcast, multicast and anycast routes). Read-only.
638

    
639
	<tag><m/enum/ dest</tag>
640
	Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_NETWORK/ 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.
641
</descrip>
642

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

    
645
<sect>Other statements
646

    
647
<p>The following statements are available:
648

    
649
<descrip>
650
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
651

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

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

    
656
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
657
	Prints given expressions; useful mainly while debugging
658
	filters. The <cf/printn/ variant does not terminate the line.
659

    
660
	<tag>quitbird</tag>
661
	Terminates BIRD. Useful when debugging the filter interpreter.
662
</descrip>
663

    
664
<chapt>Protocols
665

    
666
<sect>BGP
667

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

    
675
<p>BGP works in terms of autonomous systems (often abbreviated as AS). Each
676
AS is a part of the network with common management and common routing policy. It is identified by a unique 16-bit number.
677
Routers within each AS usually communicate with each other using either a interior routing
678
protocol (such as OSPF or RIP) or an interior variant of BGP (called iBGP).
679
Boundary routers at the border of the AS communicate with their peers
680
in the neighboring AS'es via exterior BGP (eBGP).
681

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

    
687
<p>BIRD supports all requirements of the BGP4 standard as defined in
688
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
689
It also supports the community attributes
690
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
691
capability negotiation
692
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
693
MD5 password authentication
694
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
695
route reflectors 
696
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
697
multiprotocol extensions
698
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
699
and 4B AS numbers 
700
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">).
701

    
702

    
703
For IPv6, it uses the standard multiprotocol extensions defined in
704
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
705
including changes described in the
706
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
707
and applied to IPv6 according to
708
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
709

    
710
<sect1>Route selection rules
711

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

    
718
<itemize>
719
	<item>Prefer route with the highest Local Preference attribute.
720
	<item>Prefer route with the shortest AS path.
721
	<item>Prefer IGP origin over EGP and EGP over incomplete.
722
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
723
	<item>Prefer internal routes over external ones.
724
	<item>Prefer the route with the lowest value of router ID of the
725
	advertising router.
726
</itemize>
727

    
728
<sect1>Configuration
729

    
730
<p>Each instance of the BGP corresponds to one neighboring router.
731
This allows to set routing policy and all the other parameters differently
732
for each neighbor using the following configuration parameters:
733

    
734
<descrip>
735
	<tag>local as <m/number/</tag> Define which AS we are part of. (Note that
736
	contrary to other IP routers, BIRD is able to act as a router located
737
	in multiple AS'es simultaneously, but in such cases you need to tweak
738
	the BGP paths manually in the filters to get consistent behavior.)
739
	This parameter is mandatory.
740

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

    
747
	<tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
748
	neighbor which is connected at most <m/number/ hops far and to which
749
	we should route via our direct neighbor with address <m/ip/.
750
	Default: switched off.
751

    
752
	<tag>next hop self</tag> Avoid calculation of the Next Hop attribute
753
	and always advertise our own source address (see below) as a next hop.
754
	This needs to be used only
755
	occasionally to circumvent misconfigurations of other routers.
756
	Default: disabled.
757

    
758
	<tag>source address <m/ip/</tag> Define local address we should use
759
	for next hop calculation. Default: the address of the local end
760
	of the interface our neighbor is connected to.
761

    
762
	<tag>password <m/string/</tag> Use this password for MD5 authentication
763
	of BGP sessions. Default: no authentication.
764

    
765
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
766
	a route reflection client. Default: disabled.
767

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

    
775
	<tag>rs client</tag> Be a route server and treat the neighbor
776
	as a route server client. A route server is used as a
777
	replacement for full mesh EBGP routing in Internet exchange
778
	points in a similar way to route reflectors used in IBGP routing.
779
	Bird does not implement obsoleted RFC 1863, but uses ad-hoc implementation,
780
	which behaves like plain EBGP but reduces modifications to advertised route
781
	attributes to be transparent (for example does not prepend its AS number to
782
	AS PATH attribute and keep MED attribute). Default: disabled.
783

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

    
792
	<tag>capabilities <m/switch/</tag> Use capability advertisement
793
	to advertise optional capabilities. This is standard behavior
794
	for newer BGP implementations, but there might be some older
795
	BGP implementations that reject such connection attempts.
796
	When disabled (off), features that request it (4B AS support)
797
	are also disabled. Default: on, with automatic fallback to
798
	off when received capability-related error.
799

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

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

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

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

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

    
822
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
823
	retrying a failed attempt to connect. Default: 120 seconds.
824

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

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

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

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

    
840
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
841
	Discriminator to be used during route selection when the MED attribute
842
	is missing. Default: 0.
843

    
844
	<tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference
845
	to be used during route selection when the Local Preference attribute
846
	is missing. Default: 0.
847
</descrip>
848

    
849
<sect1>Attributes
850

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

    
855
<descrip>
856
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
857
	the packet will travel through when forwarded according to the particular route. In case of 
858
	internal BGP it doesn't contain the number of the local AS.
859

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

    
864
	<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
865
	is an optional attribute which is used on on external (inter-AS) links to
866
	convey to an adjacent AS the optimal entry point into the local AS.
867
	The received attribute may be also propagated over internal BGP links
868
	(and this is default behavior). The attribute value is zeroed when a route
869
	is exported from a routing table to a BGP instance to ensure that the attribute
870
	received from a neighboring AS is not propagated to other neighboring ASes.
871
	A new value might be set in the export filter of a BGP instance.
872
	See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
873
	for further discussion of BGP MED attribute.
874

    
875
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
876
	if the route has originated in an interior routing protocol or
877
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
878
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
879
	is unknown.
880

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

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

    
893
<!-- we don't handle aggregators right since they are of a very obscure type
894
	<tag>bgp_aggregator</tag>
895
-->
896
	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
897
	with the route. Each such value is a pair (represented as a <cf/pair/ data
898
	type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
899
	the community and the second one being a per-AS identifier. There are lots
900
	of uses of the community mechanism, but generally they are used to carry
901
	policy information like "don't export to USA peers". As each AS can define
902
	its own routing policy, it also has a complete freedom about which community
903
	attributes it defines and what will their semantics be.
904
</descrip>
905

    
906
<sect1>Example
907

    
908
<p><code>
909
protocol bgp {
910
	local as 65000;			     # Use a private AS number
911
	neighbor 62.168.0.130 as 5588;	     # Our neighbor ...
912
	multihop 20 via 62.168.0.13;	     # ... which is connected indirectly
913
	export filter {			     # We use non-trivial export rules
914
		if source = RTS_STATIC then { # Export only static routes
915
		        # Assign our community
916
			bgp_community.add((65000,5678));
917
			# Artificially increase path length
918
			# by advertising local AS number twice
919
			if bgp_path ~ [= 65000 =] then	  
920
				bgp_path.prepend(65000);  
921
			accept;
922
		}
923
		reject;
924
	};
925
	import all;
926
	source address 62.168.0.1;	# Use a non-standard source address
927
}
928
</code>
929

    
930
<sect>Device
931

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

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

    
940
<p>The only configurable thing is interface scan time:
941

    
942
<p><descrip>
943
	<tag>scan time <m/number/</tag> Time in seconds between two scans
944
	of the network interface list. On systems where we are notified about
945
	interface status changes asynchronously (such as newer versions of
946
	Linux), we need to scan the list only in order to avoid confusion by lost
947
	notification messages, so the default time is set to a large value.
948
</descrip>
949

    
950
<p>As the Device protocol doesn't generate any routes, it cannot have
951
any attributes. Example configuration looks really simple:
952

    
953
<p><code>
954
protocol device {
955
	scan time 10;		# Scan the interfaces often
956
}
957
</code>
958

    
959
<sect>Direct
960

    
961
<p>The Direct protocol is a simple generator of device routes for all the
962
directly connected networks according to the list of interfaces provided
963
by the kernel via the Device protocol.
964

    
965
<p>It's highly recommended to include this protocol in your configuration
966
unless you want to use BIRD as a route server or a route reflector, that is
967
on a machine which doesn't forward packets itself and only participates in
968
distribution of routing information.
969

    
970
<p>The only configurable thing about direct is what interfaces it watches:
971

    
972
<p><descrip>
973
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
974
	protocol will generate device routes for all the interfaces
975
	available. If you want to restrict it to some subset of interfaces
976
	(for example if you're using multiple routing tables for policy
977
	routing and some of the policy domains don't contain all interfaces),
978
	just use this clause.
979
</descrip>
980

    
981
<p>Direct device routes don't contain any specific attributes.
982

    
983
<p>Example config might look like this:
984

    
985
<p><code>
986
protocol direct {
987
	interface "-arc*", "*";		# Exclude the ARCnets
988
}
989
</code>
990

    
991
<sect>Kernel
992

    
993
<p>The Kernel protocol is not a real routing protocol. Instead of communicating
994
the with other routers in the network, it performs synchronization of BIRD's routing
995
tables with the OS kernel. Basically, it sends all routing table updates to the kernel
996
and from time to time it scans the kernel tables to see whether some routes have
997
disappeared (for example due to unnoticed up/down transition of an interface)
998
or whether an `alien' route has been added by someone else (depending on the
999
<cf/learn/ switch, such routes are either deleted or accepted to our
1000
table).
1001

    
1002
<p>If your OS supports only a single routing table, you can configure only one
1003
instance of the Kernel protocol. If it supports multiple tables (in order to
1004
allow policy routing; such an OS is for example Linux 2.2), you can run as many instances as you want, but each of
1005
them must be connected to a different BIRD routing table and to a different
1006
kernel table.
1007

    
1008
<sect1>Configuration
1009

    
1010
<p><descrip>
1011
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1012
	routing tables when it exits (instead of cleaning them up).
1013
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1014
	kernel routing table.
1015
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1016
	routing tables by other routing daemons or by the system administrator.
1017
	This is possible only on systems which support identification of route
1018
	authorship.
1019
	<tag>kernel table <m/number/</tag> Select which kernel table should
1020
	this particular instance of the Kernel protocol work with. Available
1021
	only on systems supporting multiple routing tables.
1022
</descrip>
1023

    
1024
<p>The Kernel protocol doesn't define any route attributes.
1025
<p>A simple configuration can look this way:
1026

    
1027
<p><code>
1028
protocol kernel {
1029
	import all;
1030
	export all;
1031
}
1032
</code>
1033

    
1034
<p>Or for a system with two routing tables:
1035

    
1036
<p><code>
1037
protocol kernel {		# Primary routing table
1038
	learn;			# Learn alien routes from the kernel
1039
	persist;		# Don't remove routes on bird shutdown
1040
	scan time 10;		# Scan kernel routing table every 10 seconds
1041
	import all;
1042
	export all;
1043
}
1044

    
1045
protocol kernel {		# Secondary routing table
1046
	table auxtable;
1047
	kernel table 100;
1048
	export all;
1049
}
1050
</code>
1051

    
1052
<sect>OSPF
1053

    
1054
<sect1>Introduction
1055

    
1056
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
1057
protocol. The current IPv4 version (OSPFv2) is defined
1058
in RFC 2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt">. It's a link
1059
state (a.k.a. shortest path first) protocol -- each router maintains a database
1060
describing the autonomous system's topology. Each participating router
1061
has an identical copy of the database and all routers run the same algorithm
1062
calculating a shortest path tree with themselves as a root.
1063
OSPF chooses the least cost path as the best path.
1064
(OSPFv3 - OSPF for IPv6 is not supported yet.)
1065

    
1066
<p>In OSPF, the autonomous system can be split to several areas in order
1067
to reduce the amount of resources consumed for exchanging the routing
1068
information and to protect the other areas from incorrect routing data.
1069
Topology of the area is hidden to the rest of the autonomous system.
1070

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

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

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

    
1088
<sect1>Configuration
1089

    
1090
<p>In the main part of configuration, there can be multiple definitions of
1091
OSPF area witch different id included. These definitions includes many other
1092
switches and multiple definitions of interfaces. Definition of interface
1093
may contain many switches and constant definitions and list of neighbors
1094
on nonbroadcast networks.
1095

    
1096
<code>
1097
protocol ospf &lt;name&gt; {
1098
	rfc1583compat &lt;switch&gt;;
1099
	tick &lt;num&gt;;
1100
	area &lt;id&gt; {
1101
		stub cost &lt;num&gt;;
1102
                networks {
1103
			&lt;prefix&gt;;
1104
			&lt;prefix&gt; hidden;
1105
		}
1106
		interface &lt;interface pattern&gt;
1107
		{
1108
			cost &lt;num&gt;;
1109
			stub &lt;switch&gt;;
1110
			hello &lt;num&gt;;
1111
			poll &lt;num&gt;;
1112
			retransmit &lt;num&gt;;
1113
			priority &lt;num&gt;;
1114
			wait &lt;num&gt;;
1115
			dead count &lt;num&gt;;
1116
			dead &lt;num&gt;;
1117
			rx buffer [normal|large|&lt;num&gt;];
1118
			type [broadcast|nonbroadcast|pointopoint];
1119
			strict nonbroadcast &lt;switch&gt;;
1120
			authentication [none|simple|cryptographics];
1121
			password "&lt;text&gt;";
1122
			password "&lt;text&gt;" {
1123
				id &lt;num&gt;;
1124
				generate from "&lt;date&gt;";
1125
				generate to "&lt;date&gt;";
1126
				accept from "&lt;date&gt;";
1127
				accept to "&lt;date&gt;";
1128
			};
1129
			neighbors {
1130
				&lt;ip&gt;;
1131
				&lt;ip&gt; eligible;
1132
			};
1133
		};
1134
		virtual link &lt;id&gt;
1135
		{
1136
			hello &lt;num&gt;;
1137
			retransmit &lt;num&gt;;
1138
			wait &lt;num&gt;;
1139
			dead count &lt;num&gt;;
1140
			dead &lt;num&gt;;
1141
			authentication [none|simple];
1142
			password "&lt;text&gt;";
1143
		};
1144
	};
1145
}
1146
</code>
1147

    
1148
<descrip>
1149
	<tag>rfc1583compat <M>switch</M></tag>
1150
	 This option controls compatibility of routing table
1151
	 calculation with RFC 1583<htmlurl
1152
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1153
	 value is no.
1154
	
1155
	<tag>area <M>id</M></tag>
1156
	 This defines an OSPF area with given area ID (an integer or an IPv4
1157
	 address, similarly to a router ID).
1158
	 The most important area is
1159
	 the backbone (ID 0) to which every other area must be connected.
1160

    
1161
	<tag>stub cost <M>num</M></tag>
1162
	 No external (except default) routes are flooded into stub areas.
1163
         Setting this value marks area stub with defined cost of default route.
1164
	 Default value is no. (Area is not stub.)
1165

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

    
1172
	<tag>networks { <m/set/ }</tag>
1173
         Definition of area IP ranges. This is used in summary lsa origination.
1174
	 Hidden networks are not propagated into other areas.
1175

    
1176
	<tag>interface <M>pattern</M></tag>
1177
	 Defines that the specified interfaces belong to the area being defined.
1178

    
1179
	<tag>virtual link <M>id</M></tag>
1180
	 Virtual link to router with the router id. Virtual link acts as a
1181
         point-to-point interface belonging to backbone. The actual area is
1182
         used as transport area. This item cannot be in the backbone.
1183

    
1184
	<tag>cost <M>num</M></tag>
1185
	 Specifies output cost (metric) of an interface. Default value is 10.
1186

    
1187
	<tag>stub <M>switch</M></tag>
1188
	 If set to interface it does not listen to any packet and does not send
1189
	 any hello. Default value is no.
1190

    
1191
	<tag>hello <M>num</M></tag>
1192
	 Specifies interval in seconds between sending of Hello messages. Beware, all
1193
	 routers on the same network need to have the same hello interval.
1194
	 Default value is 10.
1195

    
1196
	<tag>poll <M>num</M></tag>
1197
	 Specifies interval in seconds between sending of Hello messages for
1198
	 some neighbors on NBMA network. Default value is 20.
1199

    
1200
	<tag>retransmit <M>num</M></tag>
1201
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
1202
	 Default value is 5.
1203

    
1204
        <tag>priority <M>num</M></tag>
1205
	 On every multiple access network (e.g., the Ethernet) Designed Router
1206
	 and Backup Designed router are elected. These routers have some
1207
	 special functions in the flooding process. Higher priority increases
1208
	 preferences in this election. Routers with priority 0 are not
1209
	 eligible. Default value is 1.
1210

    
1211
	<tag>wait <M>num</M></tag>
1212
	 After start, router waits for the specified number of seconds between starting
1213
	 election and building adjacency. Default value is 40.
1214
	 
1215
	<tag>dead count <M>num</M></tag>
1216
	 When the router does not receive any messages from a neighbor in
1217
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
1218

    
1219
	<tag>dead <M>num</M></tag>
1220
	 When the router does not receive any messages from a neighbor in
1221
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
1222
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
1223

    
1224
	<tag>rx buffer <M>num</M></tag>
1225
	 This sets the size of buffer used for receiving packets. The buffer should
1226
	 be bigger than maximal size of any packets. Value NORMAL (default)
1227
	 means 2*MTU, value LARGE means maximal allowed packet - 65536.
1228

    
1229
	<tag>type broadcast</tag>
1230
	 BIRD detects a type of a connected network automatically, but sometimes it's
1231
	 convenient to force use of a different type manually.
1232
	 On broadcast networks, flooding and Hello messages are sent using multicasts
1233
	 (a single packet for all the neighbors).
1234

    
1235
	<tag>type pointopoint</tag>
1236
	 Point-to-point networks connect just 2 routers together. No election
1237
	 is performed there which reduces the number of messages sent.
1238

    
1239
	<tag>type nonbroadcast</tag>
1240
	 On nonbroadcast networks, the packets are sent to each neighbor
1241
	 separately because of lack of multicast capabilities.
1242

    
1243
	<tag>strict nonbroadcast <M>switch</M></tag>
1244
	 If set, don't send hello to any undefined neighbor. This switch
1245
	 is ignored on on any non-NBMA network. Default is No.
1246

    
1247
	<tag>authentication none</tag>
1248
	 No passwords are sent in OSPF packets. This is the default value.
1249

    
1250
	<tag>authentication simple</tag>
1251
	 Every packet carries 8 bytes of password. Received packets
1252
	 lacking this password are ignored. This authentication mechanism is
1253
	 very weak.
1254

    
1255
	<tag>authentication cryptographic</tag>
1256
	 16-byte long MD5 digest is appended to every packet. For the digest
1257
         generation 16-byte long passwords are used. Those passwords are 
1258
         not sent via network, so this mechanismus is quite secure.
1259
         Packets can still be read by an attacker.
1260

    
1261
	<tag>password "<M>text</M>"</tag>
1262
	 An 8-byte or 16-byte password used for authentication.
1263

    
1264
	<tag>id <M>num</M></tag>
1265
	 ID of the password, (0-255). If it's not used, BIRD will choose
1266
	 ID based on an order of the password item in the interface. For
1267
	 example, second password item in one interface will have default
1268
	 ID 2.  
1269

    
1270
	<tag>generate from <M>date</M></tag>
1271
	 The start time of the usage of the password for packet signing.
1272

    
1273
	<tag>generate to <M>date</M></tag>
1274
	 The last time of the usage of the password for packet signing.
1275

    
1276
	<tag>accept from <M>date</M></tag>
1277
	 The start time of the usage of the password for packet verification.
1278

    
1279
	<tag>accept to <M>date</M></tag>
1280
	 The last time of the usage of the password for packet verification.
1281

    
1282
	<tag>neighbors { <m/set/ } </tag>
1283
	 A set of neighbors to which Hello messages on nonbroadcast networks
1284
	 are to be sent. Some of them could be marked as eligible.
1285

    
1286
</descrip>
1287

    
1288
<sect1>Attributes
1289

    
1290
<p>OSPF defines three route attributes. Each internal route has a <cf/metric/
1291
Metric is ranging from 1 to infinity (65535).
1292
External routes use <cf/metric type 1/ or <cf/metric type 2/.
1293
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
1294
<cf/metric of type 2/ is always longer
1295
than any <cf/metric of type 1/ or any <cf/internal metric/.
1296
If you specify both metrics only metric1 is used.
1297
Each external route can also carry a <cf/tag/ which is a 32-bit
1298
integer which is used when exporting routes to other protocols;
1299
otherwise, it doesn't affect routing inside the OSPF domain at all.
1300
Default is <cf/metric of type 2 = 10000/ and <cf/tag = 0/.
1301

    
1302
<sect1>Example
1303

    
1304
<p>
1305

    
1306
<code>
1307
protocol ospf MyOSPF {
1308
        rfc1583compatibility yes;
1309
        tick 2;
1310
	export filter {
1311
		if source = RTS_BGP then {
1312
			ospf_metric1 = 100;
1313
			accept;
1314
		}
1315
		reject;
1316
	};                                                                      
1317
	area 0.0.0.0 {
1318
		interface "eth*" {
1319
			cost 11;
1320
			hello 15;
1321
			priority 100;
1322
			retransmit 7;
1323
			authentication simple;
1324
			password "aaa";
1325
		};
1326
		interface "ppp*" {
1327
			cost 100;
1328
			authentication cryptographic;
1329
			passwords {
1330
				password "abc" {
1331
					id 1;
1332
					generate to "22-04-2003 11:00:06";
1333
					accept from "17-01-2001 12:01:05";
1334
				};
1335
				password "def" {
1336
					id 2;
1337
					generate to "22-07-2005 17:03:21";
1338
					accept from "22-02-2001 11:34:06";
1339
				};
1340
			};
1341
		};
1342
		interface "arc0" {
1343
			cost 10;
1344
			stub yes;
1345
		};
1346
		interface "arc1";
1347
	};
1348
	area 120 {
1349
		stub yes;
1350
		networks {
1351
			172.16.1.0/24;
1352
			172.16.2.0/24 hidden;
1353
		}
1354
		interface "-arc0" , "arc*" {
1355
			type nonbroadcast;
1356
			authentication none;
1357
			strict nonbroadcast yes;
1358
			wait 120;
1359
			poll 40;
1360
			dead count 8;
1361
			neighbors {
1362
				192.168.120.1 eligible;
1363
				192.168.120.2;
1364
				192.168.120.10;
1365
			};
1366
		};
1367
	};
1368
}
1369
</code>
1370

    
1371
<sect>Pipe
1372

    
1373
<sect1>Introduction
1374

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

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

    
1393
<sect1>Configuration
1394

    
1395
<p><descrip>
1396
	<tag>peer table <m/table/</tag> Define secondary routing table to connect to. The
1397
	primary one is selected by the <cf/table/ keyword.
1398
</descrip>
1399

    
1400
<sect1>Attributes
1401

    
1402
<p>The Pipe protocol doesn't define any route attributes.
1403

    
1404
<sect1>Example
1405

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

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

    
1420
<code>
1421
table as1;				# Define the tables
1422
table as2;
1423

    
1424
protocol kernel kern1 {			# Synchronize them with the kernel
1425
	table as1;
1426
	kernel table 1;
1427
}
1428

    
1429
protocol kernel kern2 {
1430
	table as2;
1431
	kernel table 2;
1432
}
1433

    
1434
protocol bgp bgp1 {			# The outside connections
1435
	table as1;
1436
	local as 1;
1437
	neighbor 192.168.0.1 as 1001;
1438
	export all;
1439
	import all;
1440
}
1441

    
1442
protocol bgp bgp2 {
1443
	table as2;
1444
	local as 2;
1445
	neighbor 10.0.0.1 as 1002;
1446
	export all;
1447
	import all;
1448
}
1449

    
1450
protocol pipe {				# The Pipe
1451
	table as1;
1452
	peer table as2;
1453
	export filter {
1454
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
1455
			if preference>10 then preference = preference-10;
1456
			if source=RTS_BGP then bgp_path.prepend(1);
1457
			accept;
1458
		}
1459
		reject;
1460
	};
1461
	import filter {
1462
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
1463
			if preference>10 then preference = preference-10;
1464
			if source=RTS_BGP then bgp_path.prepend(2);
1465
			accept;
1466
		}
1467
		reject;
1468
	};
1469
}
1470
</code>
1471

    
1472
<sect>RIP
1473

    
1474
<sect1>Introduction
1475

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

    
1489
<p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
1490
convergence, big network load and inability to handle larger networks
1491
makes it pretty much obsolete in IPv4 world. (It is still usable on
1492
very small networks.) It is widely used in IPv6 networks,
1493
because there are no good implementations of OSPFv3.
1494

    
1495
<sect1>Configuration
1496

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

    
1499
<descrip>
1500
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
1501
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
1502
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
1503
	  hash. If you set authentication to not-none, it is a good idea to add <cf>passwords { }</cf>
1504
	  section. Default: none.
1505

    
1506
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
1507
	  be honored. (Always, when sent from a  host on a directly connected
1508
	  network or never.) Routing table updates are honored only from
1509
	  neighbors, that is not configurable. Default: never.
1510
</descrip>
1511

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

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

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

    
1529
	<tag>infinity <M>number</M></tag>
1530
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
1531
	  even slower.
1532

    
1533
	<tag>period <M>number</M>
1534
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
1535
	  number will mean faster convergence but bigger network
1536
	  load. Do not use values lower than 10.
1537

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

    
1541
	<tag>garbage time <M>number</M>
1542
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
1543
</descrip>
1544

    
1545
<sect1>Attributes
1546

    
1547
<p>RIP defines two route attributes:
1548

    
1549
<descrip>
1550
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
1551
	When routes from different RIP instances are available and all of them have the same
1552
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
1553
	When importing a non-RIP route, the metric defaults to 5.
1554

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

    
1560
<sect1>Example
1561

    
1562
<p><code>
1563
protocol rip MyRIP_test {
1564
        debug all;
1565
        port 1520;
1566
        period 10;
1567
        garbage time 60;
1568
        interface "eth0" { metric 3; mode multicast; }
1569
	          "eth1" { metric 2; mode broadcast; };
1570
        honor neighbor;
1571
        authentication none;
1572
        import filter { print "importing"; accept; };
1573
        export filter { print "exporting"; accept; };
1574
}
1575
</code>
1576

    
1577
<sect>Static
1578

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

    
1587
<p>There are three types of static routes: `classical' routes telling to
1588
forward packets to a neighboring router, device routes specifying forwarding
1589
to hosts on a directly connected network and special routes (sink, blackhole
1590
etc.) which specify a special action to be done instead of forwarding the
1591
packet.
1592

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

    
1598
<p>The Static protocol has no configuration options. Instead, the
1599
definition of the protocol contains a list of static routes:
1600

    
1601
<descrip>
1602
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
1603
	a neighboring router.
1604
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
1605
	route through an interface to hosts on a directly connected network.
1606
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
1607
	specifying to drop the packet, return it as unreachable or return
1608
	it as administratively prohibited.
1609
</descrip>
1610

    
1611
<p>Static routes have no specific attributes.
1612

    
1613
<p>Example static config might look like this:
1614

    
1615
<p><code>
1616
protocol static {
1617
	table testable;			 # Connect to a non-default routing table
1618
	route 0.0.0.0/0 via 62.168.0.13; # Default route
1619
	route 62.168.0.0/25 reject;	 # Sink route
1620
	route 10.2.0.0/24 via "arc0";	 # Secondary network
1621
}
1622
</code>
1623

    
1624
<chapt>Conclusions
1625

    
1626
<sect>Future work
1627

    
1628
<p>Although BIRD supports all the commonly used routing protocols,
1629
there are still some features which would surely deserve to be
1630
implemented in future versions of BIRD:
1631

    
1632
<itemize>
1633
<item>OSPF for IPv6 networks
1634
<item>OSPF NSSA areas and opaque LSA's
1635
<item>Route aggregation and flap dampening
1636
<item>Generation of IPv6 router advertisements
1637
<item>Multipath routes
1638
<item>Multicast routing protocols
1639
<item>Ports to other systems
1640
</itemize>
1641

    
1642
<sect>Getting more help
1643

    
1644
<p>If you use BIRD, you're welcome to join the bird-users mailing list
1645
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
1646
where you can share your experiences with the other users and consult
1647
your problems with the authors. To subscribe to the list, just send a
1648
<tt/subscribe bird-users/ command in a body of a mail to
1649
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
1650
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
1651

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

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

    
1662
<p><it/Good luck!/
1663

    
1664
</book>
1665

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