Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 1632f1fe

History | View | Annotate | Download (63 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 will be called routes in the rest of this document) 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 daemons: routed (rip only), GateD<HTMLURL URL="http://www.gated.org/">
66
 (non free), Zebra<HTMLURL URL="http://www.zebra.org"> and MRTD<HTMLURL URL="http://www.zcu.cz/ftp/mirrors/mmrz/mrtd">, but their capabilities are limited and
67
they are relatively hard to configure and maintain.
68

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

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

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

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

    
99
<sect>Installing BIRD
100

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

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

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

    
118
<sect>Running BIRD
119

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

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

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

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

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

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

    
138
<chapt>About routing tables
139

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

    
145
<itemize>
146
	<item>network prefix this route is for (consists of network address and number of bits forming the network part of the address)
147
	<item>preference of this route (taken from preference of
148
	protocol and possibly altered by filters)
149
	<item>IP address of router who 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 more than
158
one entry for a network, but at most one entry for one network and one
159
protocol. The entry with biggest preference is used for routing. If
160
there are more entries with the same preference and they are from the same
161
protocol, protocol decides (typically according to metrics). If not,
162
internal ordering is used to decide. You can
163
get list of route attributes in "Route attributes" section in
164
filters. 
165

    
166
<p>Protocols are connected to routing tables through filters. Routes
167
that come from other routers go to the protocol, it then passes them to
168
filters, if import filter accepts route, it gets to main routing
169
table. It is then broadcasted to all other protocols (filtered through
170
their export filters), which typically send it to other routers.
171

    
172
Filters can alter routes passed between routing tables and
173
protocols.
174

    
175
<chapt>Configuration
176

    
177
<sect>Introduction
178

    
179
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <file>$prefix/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 (parameters) 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 BIRDC to talk to BIRD, your
327
own applications could do that, too -- the format of communication between
328
BIRD and 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 [<m/prefix/|for <m/prefix or IP/] [primary] [table <m/sym/] [all] [stats|count] [filter <m/name/|where <m/condition/] [(import|proto) <m/sym/]</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/proto/ switches ask for printing of entries as
370
	they would be seen by the specified protocol. With <cf/import/, the
371
	export filter of the protocol is skipped.
372

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

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

    
380
	<tag>configure ["<m/config file/"]</tag>
381
	Reload configuration from a given file.
382

    
383
	<tag/down/
384
	Shut BIRD down.
385

    
386
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
387
	Control protocol debugging.
388
</descrip>
389

    
390
<chapt>Filters
391

    
392
<sect>Introduction
393

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

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

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

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

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

    
432
<code>
433
function name ()
434
int local_variable;
435
{
436
	local_variable = 5;
437
}
438

    
439
function with_parameters (int parameter)
440
{
441
	print parameter;
442
}
443
</code>
444

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

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

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

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

    
474
<sect>Data types
475

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

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

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

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

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

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

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

    
507
	<tag/int|ip|prefix|pair|enum set/
508
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
509
	  but you can't modify them. Literals of type <cf>set int</cf> look like <cf>
510
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
511
	  sets. Sets of prefixes are special: you can specify which prefix lengths should match them by
512
	  using <cf>[ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]</cf>. <cf>3.0.0.0/8{5,6}</cf> matches
513
	  prefixes <cf/3.X.X.X/ whose prefix length is 5 to 6. <cf><m>address</m>/<m>num</m>+</cf> is a shorthand for <cf><m>address</m>/{0,<m/num/}</cf>,
514
	  <cf><m>address</m>/<m/num/-</cf> is a shorthand for <cf><m>address</m>/{0,<m/num-1/}</cf>. For example,
515
	  <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{ 15 , 17 } ]</cf> is true, but
516
	  <cf>1.0.0.0/8 &tilde; [ 1.0.0.0/8- ]</cf> is false.
517

    
518
	<tag/enum/
519
	  Enumeration types are fixed in BIRD -- you can't define your own
520
	  variables of such type, but some route attributes are of enumeration
521
	  type. Enumeration types are incompatible with each other.
522

    
523
	<tag/bgppath/
524
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
525

    
526
	<tag/bgpmask/
527
	  BGP masks are patterns used for BGP path matching
528
	  (using <cf>path &tilde; /2 3 5 ?/</cf> syntax). The masks
529
	  resemble wildcard patterns as used by UNIX shells. Autonomous
530
	  system numbers match themselves, <cf/?/ matches any (even empty)
531
	  sequence of arbitrary AS numbers (<cf/*/ hasn't been chosen, because
532
	  <cf>/*</cf> starts a comment). For example:
533
	  <tt>/4 3 2 1/ ~ /? 4 3 ?/</tt> is true, but 
534
	  <tt>/4 3 2 1/ ~ /? 4 5 ?/</tt> is false.
535
	<tag/clist/ 
536
	  Community list is similar to set of pairs,
537
	  except that unlike other sets, it can be modified.
538
	  There exist no literals of this type.
539

    
540
</descrip>
541

    
542
<sect>Operators
543

    
544
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
545
<cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/). 
546
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
547
used on element and set of elements of the same type (returning true if element is contained in the given set), or on IP and prefix (returning true if IP is within the range defined by that prefix), or on
548
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).
549

    
550

    
551
<sect>Control structures
552

    
553
<p>Filters support two control structures: conditions and case switches. 
554

    
555
<p>Syntax of a condition is: <cf>if
556
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
557
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
558
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.
559

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

    
566
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
567

    
568
<code>
569
case arg1 {
570
	2: print "two"; print "I can do more commands without {}";
571
	3 .. 5: print "three to five";
572
	else: print "something else";
573
}
574

    
575
if 1234 = i then printn "."; else { 
576
  print "not 1234"; 
577
  print "You need {} around multiple commands"; 
578
}
579
</code>
580

    
581
<sect>Route attributes
582

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

    
588
<descrip>
589
	<tag><m/prefix/ net</tag>
590
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
591

    
592
	<tag><m/enum/ scope</tag>
593
	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).
594

    
595
	<tag><m/int/ preference</tag>
596
	Preference of the route. (See the chapter about routing tables.)
597

    
598
	<tag><m/ip/ from</tag>
599
	The router which the route has originated from. Read-only.
600
	
601
	<tag><m/ip/ gw</tag>
602
	Next hop packets routed using this route should be forwarded to.
603

    
604
	<tag><m/enum/ source</tag>
605
	what protocol has told me about this route. Possible values: <cf/RTS_DUMMY, RTS_STATIC, RTS_INHERIT, RTS_DEVICE, RTS_STATIC_DEVICE, RTS_REDIRECT, RTS_RIP, RTS_OSPF, RTS_OSPF_EXT, RTS_OSPF_IA, RTS_OSPF_BOUNDARY, RTS_BGP, RTS_PIPE/.
606

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

    
610
	<tag><m/enum/ dest</tag>
611
	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.
612
</descrip>
613

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

    
616
<sect>Other statements
617

    
618
<p>The following statements are available:
619

    
620
<descrip>
621
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
622

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

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

    
627
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
628
	Prints given expressions; useful mainly while debugging
629
	filters. The <cf/printn/ variant does not terminate the line.
630

    
631
	<tag>quitbird</tag>
632
	Terminates BIRD. Useful when debugging the filter interpreter.
633
</descrip>
634

    
635
<chapt>Protocols
636

    
637
<sect>BGP
638

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

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

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

    
658
<p>BIRD supports all requirements of the BGP4 standard as defined in
659
RFC 1771<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1771.txt">
660
including several enhancements from the
661
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-09.txt">.
662
It also supports the community attributes as per
663
RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">,
664
capability negotiation defined in
665
RFC 2842<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2842.txt">.
666
For IPv6, it uses the standard multiprotocol extensions defined in
667
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
668
including changes described in the
669
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
670
and applied to IPv6 according to
671
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
672

    
673
<sect1>Route selection rules
674

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

    
681
<itemize>
682
	<item>Prefer route with the highest Local Preference attribute.
683
	<item>Prefer route with the shortest AS path.
684
	<item>Prefer IGP origin over EGP and EGP over incomplete.
685
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
686
	<item>Prefer internal routes over external ones.
687
	<item>Prefer the route with the lowest value of router ID of the
688
	advertising router.
689
</itemize>
690

    
691
<sect1>Configuration
692

    
693
<p>Each instance of the BGP corresponds to one neighboring router.
694
This allows to set routing policy and all the other parameters differently
695
for each neighbor using the following configuration parameters:
696

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

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

    
710
	<tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
711
	neighbor which is connected at most <m/number/ hops far and to which
712
	we should route via our direct neighbor with address <m/ip/.
713
	Default: switched off.
714

    
715
	<tag>next hop self</tag> Avoid calculation of the Next Hop attribute
716
	and always advertise our own source address (see below) as a next hop.
717
	This needs to be used only
718
	occasionally to circumvent misconfigurations of other routers.
719
	Default: disabled.
720

    
721
	<tag>source address <m/ip/</tag> Define local address we should use
722
	for next hop calculation. Default: the address of the local end
723
	of the interface our neighbor is connected to.
724

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

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

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

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

    
741
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
742
	retrying a failed attempt to connect. Default: 120 seconds.
743

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

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

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

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

    
759
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
760
	Discriminator to be used during route selection when the MED attribute
761
	is missing. Default: infinite.
762

    
763
	<tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference
764
	to be used during route selection when the Local Preference attribute
765
	is missing. Default: 0.
766
</descrip>
767

    
768
<sect1>Attributes
769

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

    
774
<descrip>
775
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
776
	the packet will travel through when forwarded according to the particular route. In case of 
777
	internal BGP it doesn't contain the number of the local AS.
778

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

    
783
	<tag>int <cf/bgp_med/ [IO]</tag> The Multiple Exit Discriminator of the route
784
	is an optional attribute which is often used within the local AS to
785
	reflect interior distances to various boundary routers. See the route selection
786
	rules above for exact semantics.
787

    
788
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
789
	if the route has originated in an interior routing protocol or
790
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
791
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
792
	is unknown.
793

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

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

    
806
<!-- we don't handle aggregators right since they are of a very obscure type
807
	<tag>bgp_aggregator</tag>
808
-->
809
	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
810
	with the route. Each such value is a pair (represented as a <cf/pair/ data
811
	type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
812
	the community and the second one being a per-AS identifier. There are lots
813
	of uses of the community mechanism, but generally they are used to carry
814
	policy information like "don't export to USA peers". As each AS can define
815
	its own routing policy, it also has a complete freedom about which community
816
	attributes it defines and what will their semantics be.
817
</descrip>
818

    
819
<sect1>Example
820

    
821
<p><code>
822
protocol bgp {
823
	local as 65000;				# Use a private AS number
824
	neighbor 62.168.0.130 as 5588;		# Our neighbor...
825
	multihop 20 via 62.168.0.13;		# ... which is connected indirectly
826
	export filter {				# We use non-trivial export rules
827
		if source = RTS_STATIC then {	# Export only static routes
828
		        # Assign our community
829
			bgp_community.add((65000,5678));
830
			# Artificially increase path length
831
			# by advertising local AS number twice
832
			if bgp_path ~ / 65000 / then	  
833
				bgp_path.prepend(65000);  
834
			accept;
835
		}
836
		reject;
837
	};
838
	import all;
839
	source address 62.168.0.1;		# Use a non-standard source address
840
}
841
</code>
842

    
843
<sect>Device
844

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

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

    
853
<p>The only configurable thing is interface scan time:
854

    
855
<p><descrip>
856
	<tag>scan time <m/number/</tag> Time in seconds between two scans
857
	of the network interface list. On systems where we are notified about
858
	interface status changes asynchronously (such as newer versions of
859
	Linux), we need to scan the list only in order to avoid confusion by lost
860
	notification messages, so the default time is set to a large value.
861
</descrip>
862

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

    
866
<p><code>
867
protocol device {
868
	scan time 10;		# Scan the interfaces often
869
}
870
</code>
871

    
872
<sect>Direct
873

    
874
<p>The Direct protocol is a simple generator of device routes for all the
875
directly connected networks according to the list of interfaces provided
876
by the kernel via the Device protocol.
877

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

    
883
<p>The only configurable thing about direct is what interfaces it watches:
884

    
885
<p><descrip>
886
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
887
	protocol will generate device routes for all the interfaces
888
	available. If you want to restrict it to some subset of interfaces
889
	(for example if you're using multiple routing tables for policy
890
	routing and some of the policy domains don't contain all interfaces),
891
	just use this clause.
892
</descrip>
893

    
894
<p>Direct device routes don't contain any specific attributes.
895

    
896
<p>Example config might look like this:
897

    
898
<p><code>
899
protocol direct {
900
	interface "-arc*", "*";		# Exclude the ARCnets
901
}
902
</code>
903

    
904
<sect>Kernel
905

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

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

    
921
<sect1>Configuration
922

    
923
<p><descrip>
924
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
925
	routing tables when it exits (instead of cleaning them up).
926
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
927
	kernel routing table.
928
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
929
	routing tables by other routing daemons or by the system administrator.
930
	This is possible only on systems which support identification of route
931
	authorship.
932
	<tag>kernel table <m/number/</tag> Select which kernel table should
933
	this particular instance of the Kernel protocol work with. Available
934
	only on systems supporting multiple routing tables.
935
</descrip>
936

    
937
<p>The Kernel protocol doesn't define any route attributes.
938
<p>A simple configuration can look this way:
939

    
940
<p><code>
941
protocol kernel {
942
	import all;
943
	export all;
944
}
945
</code>
946

    
947
<p>Or for a system with two routing tables:
948

    
949
<p><code>
950
protocol kernel {		# Primary routing table
951
	learn;			# Learn alien routes from the kernel
952
	persist;		# Don't remove routes on bird shutdown
953
	scan time 10;		# Scan kernel routing table every 10 seconds
954
	import all;
955
	export all;
956
}
957

    
958
protocol kernel {		# Secondary routing table
959
	table auxtable;
960
	kernel table 100;
961
	export all;
962
}
963
</code>
964

    
965
<sect>OSPF
966

    
967
<sect1>Introduction
968

    
969
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
970
protocol. The current IPv4 version (OSPFv2) is defined in RFC 2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt">. It's a link
971
state (a.k.a. shortest path first) protocol -- each router maintains a database
972
describing the autonomous system's topology. Each participating router
973
has an identical copy of the database and all routers run the same algorithm
974
calculating a shortest path tree with themselves as a root.
975
OSPF chooses the least cost path as the best path.
976

    
977
<p>In OSPF, the autonomous system can be split to several areas in order
978
to reduce the amount of resources consumed for exchanging the routing
979
information and to protect the other areas from incorrect routing data.
980
Topology of the area is hidden to the rest of the autonomous system.
981
Unfortunately, multiple OSPF areas are not yet fully supported
982
by this version of BIRD and neither is the IPv6 version (OSPFv3).
983

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

    
990
<p>OSPF quickly detects topological changes in the autonomous system (such
991
as router interface failures) and calculates new loop-free routes after a short
992
period of convergence. Only a minimal ammount of 
993
routing traffic is involved.
994

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

    
1001
<sect1>Configuration
1002

    
1003
<p>In the main part of configuration, there can be multiple definitions of
1004
OSPF area witch different id included. These definitions includes many other
1005
switches and mutliple definitions of interfaces. Definition of interface
1006
may contain many switches and constant definitinons and list of neighbors
1007
on nonbroadcast networks.
1008

    
1009
<code>
1010
protocol ospf &lt;name&gt; {
1011
	rfc1583compat &lt;switch&gt;;
1012
	area &lt;id&gt; {
1013
		stub &lt;switch&gt;;
1014
		tick &lt;num&gt;;
1015
		interface &lt;interface pattern&gt;
1016
		{
1017
			cost &lt;num&gt;;
1018
			hello &lt;num&gt;;
1019
			retransmit &lt;num&gt;;
1020
			priority &lt;num&gt;;
1021
			wait &lt;num&gt;;
1022
			dead count &lt;num&gt;;
1023
			type [broadcast|nonbroadcast|pointopoint];
1024
			authetication [none|simple];
1025
			password "&lt;text&gt;";
1026
			neighbors {
1027
				&lt;ip&gt;;
1028
			};
1029
		};
1030
	};
1031
}
1032
</code>
1033

    
1034
<descrip>
1035
	<tag>rfc1583compat <M>switch</M></tag>
1036
	 This option controls compatibility of routing table
1037
	 calculation with RFC 1583<htmlurl
1038
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1039
	 value is no.
1040
	
1041
	<tag>area <M>id</M></tag>
1042
	 This defines an OSPF area with given area ID (an integer or an IPv4
1043
	 address, similarly to a router ID).
1044
	 The most important area is
1045
	 the backbone (ID 0) to which every other area must be connected.
1046

    
1047
	<tag>stub <M>switch</M></tag>
1048
	 No external routes are flooded into stub areas. Default value is no.
1049

    
1050
	<tag>tick <M>num</M></tag>
1051
	 The routing table calculation is not performed when a single link state
1052
	 change arrives. To lower the CPU utilization, it's processed later
1053
	 at periodical intervals of <m/num/ seconds. The default value is 7.
1054

    
1055
	<tag>interface <M>pattern</M></tag>
1056
	 Defines that the specified interfaces belong to the area being defined.
1057

    
1058
	<tag>cost <M>num</M></tag>
1059
	 Specifies output cost (metric) of an interface. Default value is 10.
1060

    
1061
	<tag>hello <M>num</M></tag>
1062
	 Specifies interval in seconds between sending of Hello messages. Beware, all
1063
	 routers on the same network need to have the same hello interval.
1064
	 Default value is 10.
1065

    
1066
	<tag>retransmit <M>num</M></tag>
1067
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
1068
	 Default value is 5.
1069

    
1070
        <tag>priority <M>num</M></tag>
1071
	 On every multiple access network (e.g., the Ethernet) Designed Router
1072
	 and Backup Designed router are elected. These routers have some
1073
	 special functions in the flooding process. Higher priority increases
1074
	 preferences in this election. Routers with priority 0 are not
1075
	 eligible. Default value is 1.
1076

    
1077
	<tag>wait <M>num</M></tag>
1078
	 After start, router waits for the specified number of seconds between starting
1079
	 election and building adjacency. Default value is 40.
1080
	 
1081
	<tag>dead count <M>num</M></tag>
1082
	 When the router does not receive any messages from a neighbor in
1083
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
1084

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

    
1090
	<tag>type nonbroadcast</tag>
1091
	 On nonbroadcast networks, the packets are sent to each neighbor
1092
	 separately because of lack of multicast capabilities.
1093

    
1094
	<tag>type pointopoint</tag>
1095
	 Point-to-point networks connect just 2 routers together. No election
1096
	 is performed there which reduces the number of messages sent.
1097

    
1098
	<tag>authentication none</tag>
1099
	 No passwords are sent in OSPF packets. This is the default value.
1100

    
1101
	<tag>authentication simple</tag>
1102
	 Every packet carries 8 bytes of password. Received packets
1103
	 lacking this password are ignored. This authentication mechanism is
1104
	 very weak.
1105

    
1106
	<tag>password "<M>text</M>"</tag>
1107
	 An 8-byte password used for authentication.
1108

    
1109
	<tag>neighbors { <m/set/ } </tag>
1110
	 A set of neighbors to which Hello messages on nonbroadcast networks
1111
	 are to be sent.
1112
</descrip>
1113

    
1114
<sect1>Attributes
1115

    
1116
<p>OSPF defines three route attributes. Each internal route has a <cf/metric/
1117
Metric is ranging from 1 to infinity (65535).
1118
External routes use <cf/metric type 1/ or <cf/metric type 2/.
1119
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
1120
<cf/metric of type 2/ is always longer
1121
than any <cf/metric of type 1/ or any <cf/internal metric/.
1122
Each external route can also carry a <cf/tag/ which is a 32-bit
1123
integer which is used when exporting routes to other protocols;
1124
otherwise, it doesn't affect routing inside the OSPF domain at all.
1125

    
1126
<sect1>Example
1127

    
1128
<p>
1129

    
1130
<code>
1131
protocol ospf MyOSPF {
1132
	export filter {
1133
		if source = RTS_BGP then {
1134
			ospf_metric1 = 100;
1135
			accept;
1136
		}
1137
	reject;
1138
	};                                                                      
1139
	area 0.0.0.0 {
1140
		tick 8;
1141
		interface "eth*" {
1142
			cost 11;
1143
			hello 15;
1144
			priority 100;
1145
			retransmit 7;
1146
			authentication simple;
1147
			password "aaa";
1148
		};
1149
		interface "ppp*" {
1150
			cost 100;
1151
		};
1152
	};
1153
	area 120 {
1154
		stub yes;
1155
		interface "-arc0" , "arc*" {
1156
			type nonbroadcast;
1157
			authentication none;
1158
			wait 50;
1159
			dead count 6;
1160
			neighbors {
1161
				192.168.120.1;
1162
				192.168.120.2;
1163
				192.168.120.10;
1164
			};
1165
		};
1166
	};
1167
}
1168
</code>
1169

    
1170
<sect>Pipe
1171

    
1172
<sect1>Introduction
1173

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

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

    
1192
<sect1>Configuration
1193

    
1194
<p><descrip>
1195
	<tag>peer table <m/table/</tag> Define secondary routing table to connect to. The
1196
	primary one is selected by the <cf/table/ keyword.
1197
</descrip>
1198

    
1199
<sect1>Attributes
1200

    
1201
<p>The Pipe protocol doesn't define any route attributes.
1202

    
1203
<sect1>Example
1204

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

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

    
1219
<code>
1220
table as1;				# Define the tables
1221
table as2;
1222

    
1223
protocol kernel kern1 {			# Synchronize them with the kernel
1224
	table as1;
1225
	kernel table 1;
1226
}
1227

    
1228
protocol kernel kern2 {
1229
	table as2;
1230
	kernel table 2;
1231
}
1232

    
1233
protocol bgp bgp1 {			# The outside connections
1234
	table as1;
1235
	local as 1;
1236
	neighbor 192.168.0.1 as 1001;
1237
	export all;
1238
	import all;
1239
}
1240

    
1241
protocol bgp bgp2 {
1242
	table as2;
1243
	local as 2;
1244
	neighbor 10.0.0.1 as 1002;
1245
	export all;
1246
	import all;
1247
}
1248

    
1249
protocol pipe {				# The Pipe
1250
	table as1;
1251
	peer table as2;
1252
	export filter {
1253
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
1254
			if preference>10 then preference = preference-10;
1255
			if source=RTS_BGP then bgp_path.prepend(1);
1256
			accept;
1257
		}
1258
		reject;
1259
	};
1260
	import filter {
1261
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
1262
			if preference>10 then preference = preference-10;
1263
			if source=RTS_BGP then bgp_path.prepend(2);
1264
			accept;
1265
		}
1266
		reject;
1267
	};
1268
}
1269
</code>
1270

    
1271
<sect>RIP
1272

    
1273
<sect1>Introduction
1274

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

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

    
1294
<sect1>Configuration
1295

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

    
1298
<descrip>
1299
	<tag/authentication none|password|md5/ selects authentication method to be used. <cf/none/ means that
1300
	  packets are not authenticated at all, <cf/password/ means that a plaintext password is embedded
1301
	  into each packet, and <cf/md5/ means that packets are authenticated using a md5 cryptographic
1302
	  hash. If you set authentication to not-none, it is a good idea to add <cf>passwords { }</cf>
1303
	  section. Default: none.
1304

    
1305
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
1306
	  be honored. (Always, when sent from a  host on a directly connected
1307
	  network or never.) Routing table updates are honored only from
1308
	  neighbors, that is not configurable. Default: never.
1309
</descrip>
1310

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

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

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

    
1328
	<tag>infinity <M>number</M></tag>
1329
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
1330
	  even slower.
1331

    
1332
	<tag>period <M>number</M>
1333
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
1334
	  number will mean faster convergence but bigger network
1335
	  load. Do not use values lower than 10.
1336

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

    
1340
	<tag>garbage time <M>number</M>
1341
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
1342
</descrip>
1343

    
1344
<sect1>Attributes
1345

    
1346
<p>RIP defines two route attributes:
1347

    
1348
<descrip>
1349
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
1350
	When routes from different RIP instances are available and all of them have the same
1351
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
1352
	When importing a non-RIP route, the metric defaults to 5.
1353

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

    
1359
<sect1>Example
1360

    
1361
<p><code>
1362
protocol rip MyRIP_test {
1363
        debug all;
1364
        port 1520;
1365
        period 10;
1366
        garbage time 60;
1367
        interface "eth0" { metric 3; mode multicast; }
1368
	          "eth1" { metric 2; mode broadcast; };
1369
        honor neighbor;
1370
        authentication none;
1371
        import filter { print "importing"; accept; };
1372
        export filter { print "exporting"; accept; };
1373
}
1374
</code>
1375

    
1376
<sect>Static
1377

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

    
1386
<p>There are three types of static routes: `classical' routes telling to
1387
forward packets to a neighboring router, device routes specifying forwarding
1388
to hosts on a directly connected network and special routes (sink, blackhole
1389
etc.) which specify a special action to be done instead of forwarding the
1390
packet.
1391

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

    
1397
<p>The Static protocol has no configuration options. Instead, the
1398
definition of the protocol contains a list of static routes:
1399

    
1400
<descrip>
1401
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
1402
	a neighboring router.
1403
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
1404
	route through an interface to hosts on a directly connected network.
1405
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
1406
	specifying to drop the packet, return it as unreachable or return
1407
	it as administratively prohibited.
1408
</descrip>
1409

    
1410
<p>Static routes have no specific attributes.
1411

    
1412
<p>Example static config might look like this:
1413

    
1414
<p><code>
1415
protocol static {
1416
	table testable;				# Connect to a non-default routing table
1417
	route 0.0.0.0/0 via 62.168.0.13;	# Default route
1418
	route 62.168.0.0/25 reject;		# Sink route
1419
	route 10.2.0.0/24 via "arc0";		# Secondary network
1420
}
1421
</code>
1422

    
1423
<chapt>Problems
1424

    
1425
<p>BIRD is relatively young system, and probably contains some
1426
bugs. You can report bugs at bird-users mailing list (<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">), but before you do,
1427
please make sure you have read available documentation, make sure are running latest version (available at <HTMLURL
1428
URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). (Of course, patch
1429
which fixes the bug along with bug report is always welcome). If you
1430
want to use BIRD, join mailing list by sending
1431
<tt/subscribe bird-users/ to <HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">. Main home page of bird is <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">. When
1432
trying to understand, what is going on, Internet standards are
1433
relevant reading; you can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
1434

    
1435
<p><it/Good luck!/
1436

    
1437
</book>
1438

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