Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 0c69604c

History | View | Annotate | Download (55.8 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 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="FIXME">, 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 networkk 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
<!-- fixme: add default values to all places? Where do I learn them? --> 
180

    
181
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads <file>$prefix/bird.conf</file> (unless the
182
<tt/-c/ command line option is given). Configuration may be changed on user's request: if you modify
183
config file and then signal BIRD with SIGHUP, it will adjust to the new
184
config. Then there's the client,
185
which allows you to talk with BIRD in an extensive way. (Of course you can tell BIRD to reconfigure from BIRDC, you can also tell it to shut down, dump various info etc.).
186

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

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

    
196

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

    
204
protocol device {
205
	scan time 10;		# Scan interfaces every 10 seconds
206
}
207

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

    
214

    
215
<sect>Global options
216

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

    
229
	<!--fixme: mj says explain-->
230
				  
231
	<tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag>
232
	Set global default of protocol debugging options.
233

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

    
237
	<tag>function <m/name (parameters) local variables/ { <m/commands/ }</tag> Define a function. You can learn more
238
	about functions in the following chapter.
239
 
240
	<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
241
	instance called <cf><m/name/</cf> (or with a name like "rip5" generated automatically, if you don't specify <cf><m/name/</cf>). You can learn more
242
	about configuring protocols in their own chapters. You can run more than one instance of
243
	most protocols (like RIP or BGP).
244

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

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

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

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

    
258
<sect>Protocol options
259

    
260
<p>Each routing protocol has its own set of options (see the corresponding sections). These options are common to all protocols:
261

    
262
<descrip>
263
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol.
264

    
265
	<tag>disabled</tag> Disables the protocol. You can change the disable/enable status from the command
266
	line interface without needing to touch the configuration. Disabled protocol is not activated.
267

    
268
	<tag>debug <m/setting/</tag> Similar to global <cf/debug/ setting, except that it only
269
	affects one protocol. Only messages in selected debugging categories will be written to the
270
	logs.
271

    
272
	<tag>import { <m/filter commands/ } | <m/name/ | all | none</tag> Specify a filter to be used for filtering routes comming from protocol tothe routing table. Default: <cf/all/. <cf/all/ is shorthand for <cf/{ accept; }/ and <cf/none/ is shorthand for <cf/{ reject; }/.
273

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

    
277
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
278
</descrip>
279

    
280
<p>There are several options that give sense only with certain protocols:
281

    
282
<descrip>
283
	<tag>passwords { password "<m/password/" from <m/time/ to <m/time/ passive <m/time/ id
284
	<m/num/ [...] }</tag> Specifies passwords to be used with this protocol. <cf>Passive <m/time/</cf> is
285
	time from which the password is not used for sending, but it is recognized on reception. <cf/id/ is password id, as needed by
286
	certain protocols.
287

    
288
	<tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [ ... ] } ]</tag> Specifies which
289
	interfaces this protocol is active on, and allows you to set options on
290
	per-interface basis. Mask is specified in shell-like patterns, thus <cf>interface
291
	"*" { mode broadcast; };</cf> will start the protocol on all interfaces with <cf>mode
292
	broadcast;</cf> option. If first character of mask is <cf/-/, such interfaces are
293
	excluded. Masks are parsed left-to-right, thus <cf/interface "-eth*", "*";/ means all but
294
	the ethernets.
295
						  
296
</descrip>
297

    
298
<sect>Client
299

    
300
<p>You can use the command-line client <file>birdc</file> to talk with
301
a running BIRD. Communication is done using <file/bird.ctl/ unix domain
302
socket (unless changed with the <tt/-s/ option given to both the server and
303
the client). The client can do simple actions such as enabling/disabling
304
protocols, telling BIRD to show various information, telling it to
305
show routing table filtered by any filter, or telling bird to
306
reconfigure. Press <tt/?/ at any time to get online help. Option
307
<tt/-v/ can be passed to the client, telling it to dump numeric return
308
codes. You do not necessarily need to use BIRDC to talk to BIRD, your
309
own application could do that, too -- format of communication between
310
BIRD and BIRDC is stable (see programmer's documentation).
311

    
312

    
313
<chapt>Filters
314

    
315
<sect>Introduction
316

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

    
323
<p>Filter gets the route, looks at its attributes and
324
modifies some of them if it wishes. At the end, it decides whether to
325
pass the changed route through (using <cf/accept/) or whether to <cf/reject/ given route. A simple filter looks
326
like this:
327

    
328
<code>
329
filter not_too_far
330
int var;
331
{
332
	if defined( rip_metric ) then
333
		var = rip_metric;
334
	else {
335
		var = 1;
336
		rip_metric = 1;
337
	}
338
	if rip_metric &gt; 10 then
339
		reject "RIP metric is too big";
340
	else
341
		accept "ok";
342
}
343
</code>
344

    
345
<p>As you can see, a filter has a header, a list of local variables, and a body. The header consists of
346
the <cf/filter/ keyword, followed by a (unique) name of filter. List of local variables consists of
347
pairs <cf><M>type name</M>;</cf>, where each pair defines one local variable. Body consists of
348
<cf> { <M>statements</M> }</cf>. Each <m/statement/ is terminated by <cf/;/. You can group
349
several statements into one by using braces (<cf>{ <M>statements</M> }</cf>), that is useful if
350
you want to make bigger block of code conditional.
351

    
352
<p>BIRD supports functions, so that you don't have to repeat same blocks of code over and
353
over. Functions can have zero or more parameters and they can have local variables. Recursion is not allowed. They
354
look like this:
355

    
356
<code>
357
function name ()
358
int local_variable;
359
{
360
	local_variable = 5;
361
}
362

    
363
function with_parameters (int parameter)
364
{
365
	print parameter;
366
}
367
</code>
368

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

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

    
380
<p>A nice trick to debug filters is to use <cf>show route filter
381
<m/name/</cf> from the command line client. An example session might look
382
like:
383

    
384
<code>
385
pavel@bug:~/bird$ ./birdc -s bird.ctl
386
BIRD 0.0.0 ready.
387
bird> show route
388
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
389
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
390
127.0.0.0/8        dev lo [direct1 23:21] (240)
391
bird> show route ?
392
show route [<prefix>] [table <t>] [filter <f>] [all] [primary] [(import|protocol) <p>]...
393
bird> show route filter { if 127.0.0.5 ~ net then accept; }
394
127.0.0.0/8        dev lo [direct1 23:21] (240)
395
bird>
396
</code>
397

    
398
<sect>Data types
399

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

    
403
<descrip>
404
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
405
	  <cf/false/. Boolean is not compatible with integer and is the only type you can use in if
406
	  statements.
407

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

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

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

    
419
	<tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it
420
	  is either an IPv4 or IPv6 address. IPv4 addresses are written (as you would expect) as
421
	  <cf/1.2.3.4/. You can apply special operator <cf>.mask(<M>num</M>)</cf>
422
	  on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from ip
423
	  address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. <!-- FIXME: IPv6? -->
424

    
425
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
426
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
427
	  <cf><m>ipaddress</m>/<m>netmask</m></cf> There are two special
428
	  operators on prefix:
429
	  <cf/.ip/, which separates ip address from the pair, and <cf/.len/, which separates prefix
430
	  len from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
431

    
432
	<tag/int|ip|prefix|pair|enum set/
433
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
434
	  but you can't modify them. Literals of type <cf>set int</cf> look like <cf>
435
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
436
	  sets. Sets of prefixes are special: you can specify which prefix lengths should match them by
437
	  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
438
	  prefixes <cf/3.X.X.X/, whose prefix length is 5 to 6. <cf>3.0.0.0/8+</cf> is shorthand for <cf>3.0.0.0/{0,8}</cf>,
439
	  <cf>3.0.0.0/8-</cf> is shorthand for <cf>3.0.0.0/{0,7}</cf>. For example,
440
	  <cf>1.2.0.0/16 ~ [ 1.0.0.0/8{ 15 , 17 } ]</cf> is true, but
441
	  <cf>1.0.0.0/8 ~ [ 1.0.0.0/8- ]</cf> is false. <!-- fixme: use variables instead of examples -->
442

    
443
	<tag/enum/
444
	  Enumeration types are fixed in BIRD - you can't define your own
445
	  variables of enumeration type, but some route attributes are of enumeration
446
	  type. Enumeration types are incompatible with each other.
447

    
448
	<tag/bgppath/
449
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
450

    
451
	<tag/bgpmask/ 
452
	  BGP mask is a mask used for matching BGP paths
453
	  (using <cf>path &tilde; /2 3 5 ?/</cf> syntax). Matching is
454
	  done using shell-like patterns: <cf/?/ means
455
	  "any number of any autonomous systems". Pattern for single
456
	  unknown autonomous system is not supported. (We
457
	  did not want to use * because then it becomes too easy to
458
	  write <cf>/*</cf> which is start of comment.) For example,
459
	  <tt>/4 3 2 1/ ~ /? 4 3 ?/</tt> is true, but 
460
	  <tt>/4 3 2 1/ ~ /? 4 5 ?/</tt> is false. <!-- fixme: formulate better -->
461

    
462
	<tag/clist/ 
463
	  Community list is similar to set of pairs,
464
	  except that unlike other sets, it can be modified.
465
	  There exist no literals of this type.
466

    
467
</descrip>
468

    
469
<sect>Operators
470

    
471
<!-- FIXME: Make it table -->
472

    
473
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
474
<cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Special operators include <cf/&tilde;/ for "in" operation. In operation can be
475
used on element and set of that elements, or on ip and prefix, or on
476
prefix and prefix or on bgppath and bgpmask or on pair and clist. Its result
477
is true if element is in given set or if ip address is inside given prefix. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/).
478

    
479
<sect>Control structures
480

    
481
<p>Filters support two control structures: conditions and case switches. 
482

    
483
<!-- fixme: say explicitly what if and case does -->
484

    
485
<p>Syntax of condition is <cf>if
486
<M>boolean expression</M> then <M>command</M>; else <M>command</M>;</cf> and you can use <cf>{
487
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of one or both commands. <cf>else</cf>
488
clause may be omitted.
489

    
490
<p><cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else |
491
<m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. Expression after
492
<cf>case</cf> can be of any type that can be on the left side of the &tilde; operator, and anything that could
493
be a member of a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping
494
and break is implicit before each case. If argument
495
matches neither of <cf/:/ clauses, <cf/else:/ clause is used.
496

    
497
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
498

    
499
<code>
500
case arg1 {
501
	2: print "two"; print "I can do more commands without {}";
502
	3 .. 5: print "three to five";
503
	else: print "something else";
504
}
505

    
506
if 1234 = i then printn "."; else { 
507
  print "not 1234"; 
508
  print "You need {} around multiple commands"; 
509
}
510
</code>
511

    
512
<sect>Route attributes
513

    
514
<p>An filter is implicitly passed route, and it can access its
515
attributes just like it accesses variables. Attempt to access undefined
516
attribute result in a runtime error; you can check if an attribute is
517
defined using the <cf>defined( <m>attribute</m> )</cf> operator.
518

    
519
<!-- fixme: say which are read-only -->
520

    
521
<descrip>
522
	<tag><m/prefix/ net</tag>
523
	Network the route is talking about. (See the section about routing tables.)
524

    
525
	<tag><m/enum/ scope</tag>
526
	Address scope of the network (<cf/SCOPE_HOST/ for addresses local to this host, <cf/SCOPE_LINK for those specific for a physical link, ... <!-- FIXME -->)
527

    
528
	<tag><m/int/ preference</tag>
529
	Preference of the route. (See section about routing tables.)
530

    
531
	<tag><m/ip/ from</tag>
532
	The router which the route has originated from.
533
	
534
	<tag><m/ip/ gw</tag>
535
	Next hop packets routed using this route should be forwarded to.
536

    
537
	<tag><m/enum/ source</tag>
538
	what protocol has told me about this route. Possible values: <cf/RTS_RIP/ or <cf/RTS_OSPF_EXT/ <!-- fixme -->.
539

    
540
	<tag><m/enum/ cast</tag>
541
	Route type (<cf/RTC_UNICAST/ for normal routes, ... <!-- FIXME -->)
542

    
543
	<tag><m/enum/ dest</tag>
544
	Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, ...)
545
</descrip>
546

    
547
<p>There also exist some protocol-specific attributes, which are described in protocol sections.
548

    
549
<sect>Statements
550

    
551
<p>The following statements are available:
552

    
553
<descrip>
554
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
555

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

    
558
	<tag>return <m/expr/</tag> Return <cf><m>expr</m></cf> from function, the function ends at this point.
559

    
560
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
561
	Prints given expressions; useful mainly while debugging
562
	filters. The <cf/printn/ variant does not terminate the line.
563

    
564
	<tag>quitbird</tag>
565
	Terminates BIRD. Useful when debugging filter interpreter.
566
</descrip>
567

    
568
<chapt>Protocols
569

    
570
<sect>BGP
571

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

    
579
<p>BGP works in terms of autonomous systems (often abbreviated as AS). Each
580
AS is a part of the network with common management and common routing policy.
581
Routers within each AS usually communicate using either a interior routing
582
protocol (such as OSPF or RIP) or an interior variant of BGP (called iBGP).
583
Boundary routers at the border of the AS communicate with their peers
584
in the neighboring AS'es via exterior BGP (eBGP).
585

    
586
<p>Each BGP router sends to its neighbors updates of the parts of its
587
routing table it wishes to export, along with complete path information
588
(a list of AS'es the packet will travel through if it uses that particular
589
route) in order to avoid routing loops.
590

    
591
<p>BIRD supports all requirements of the BGP4 standard as defined in
592
RFC 1771<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1771.txt">
593
including several enhancements from the
594
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-09.txt">.
595
It also supports the community attributes as per
596
RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">,
597
capability negotiation defined in
598
RFC 2842<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2842.txt">,
599
For IPv6, it uses the standard multiprotocol extensions defined in
600
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
601
including changes described in the
602
latest draft <htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
603
and applied to IPv6 according to
604
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
605

    
606
<sect1>Route selection rules
607

    
608
<p>BGP doesn't have any simple metric, so the rules for selection of an optimal
609
route among multiple BGP routes with the same preference are a bit more complex
610
and are implemented according to the following algorithm. First it uses the first
611
rule, if there are more "best" routes, then it uses the second rule to choose
612
among them and so on.
613

    
614
<itemize>
615
	<item>Prefer route with the highest local preference attribute.
616
	<item>Prefer route with the shortest AS path.
617
	<item>Prefer IGP origin over EGP and EGP over incomplete.
618
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
619
	<item>Prefer internal routes over external routes.
620
	<item>Prefer route with the lowest value of router ID of the
621
	advertising router.
622
</itemize>
623

    
624
<sect1>Configuration
625

    
626
<p>Each instance of the BGP corresponds to one neighboring router.
627
This allows to set routing policy and all other parameters differently
628
for each neighbor using the following protocol parameters:
629

    
630
<descrip>
631
	<tag>local as <m/number/</tag> Define which AS we are part of. (Note that
632
	contrary to other IP routers, BIRD is able to act as a router located
633
	in multiple AS'es simultaneously, but in such cases you need to tweak
634
	the BGP paths manually in the filters to get consistent behavior.)
635
	This parameter is mandatory.
636
	<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router
637
	this instance will be talking to and what AS it's located in. Unless
638
	you use the <cf/multihop/ clause, it must be directly connected to one
639
	of your router's interfaces. In case the neighbor is in the same AS
640
	as we are, we automatically switch to iBGP. This parameter is mandatory.
641
	<tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
642
	neighbor which is connected at most <m/number/ hops far and to which
643
	we should route via our direct neighbor with address <m/ip/.
644
	Default: switched off.
645
	<tag>next hop self</tag> Avoid calculation of the Next Hop attribute
646
	and always advertise our own source address (see below) as a next hop.
647
	This needs to be used only
648
	occasionally to circumvent misconfigurations of other routers.
649
	Default: disabled.
650
	<tag>source address <m/ip/</tag> Define local address we should use
651
	for next hop calculation. Default: the address of the local end
652
	of the interface our neighbor is connected to.
653
	<tag>disable after error <m/switch/</tag> When an error is encountered (either
654
	locally or by the other side), disable the instance automatically
655
	and wait for an administrator to solve the problem manually. Default: off.
656
	<tag>hold time <m/number/</tag> Time in seconds to wait for a keepalive
657
	message from the other side before considering the connection stale.
658
	Default: depends on agreement with the neighboring router, we prefer
659
	240 seconds if the other side is willing to accept it.
660
	<tag>startup hold time <m/number/</tag> Value of the hold timer used
661
	before the routers have a chance to exchange OPEN messages and agree
662
	on the real value. Default: 240 seconds.
663
	<tag>keepalive time <m/number/</tag> Delay in seconds between sending
664
	of two consecutive keepalive messages. Default: One third of the hold time.
665
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
666
	retrying a failed connect attempt. Default: 120 seconds.
667
	<tag>start delay time <m/number/</tag> Delay in seconds between protocol
668
	startup and first attempt to connect. Default: 5 seconds.
669
	<tag>error wait time <m/number/, <m/number/</tag> Minimum and maximum delay in seconds between protocol
670
	failure (either local or reported by the peer) and automatic startup.
671
	Doesn't apply when <cf/disable after error/ is configured. If consecutive
672
	errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300.
673
	<tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol
674
	failures to treat them as a error sequence which makes the <cf/error wait time/
675
	increase exponentially. Default: 300 seconds.
676
	<tag>path metric <m/switch/</tag> Enable comparison of path lengths
677
	when deciding which BGP route is the best one. Default: on.
678
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
679
	Discriminator to be used during route selection when the MED attribute
680
	is missing. Default: infinite.
681
	<tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference
682
	to be used during route selection when the Local Preference attribute
683
	is missing. Default: 0.
684
</descrip>
685

    
686
<sect1>Attributes
687

    
688
<p>BGP defines several route attributes. Some of them (those marked with `I' in the
689
table below) are available on internal BGP connections only, some of them (marked
690
with `O') are optional.
691

    
692
<descrip>
693
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
694
	the packet will travel through when forwarded according to this route. On
695
	internal BGP connections it doesn't contain the number of the local AS.
696
	<tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for
697
	selection among multiple BGP routes (see the selection rules above). It's
698
	used as an additional metric which is propagated through the whole local AS.
699
	<tag>int <cf/bgp_med/ [IO]</tag> The Multiple Exit Discriminator of the route
700
	is an optional attribute which is often used within the local AS to
701
	reflect interior distances to various boundary routers. See the route selection
702
	rules above for exact semantics.
703
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/,
704
	if the route has originated in interior routing protocol of an AS or
705
	<cf/ORIGIN_EGP/, if it's been imported from the <tt>EGP</tt> protocol
706
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/, if the origin
707
	is unknown.
708
	<tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets
709
	to this destination. On internal BGP connections, it's an address of the
710
	originating router if it's inside the local AS or a boundary router the
711
	packet will leave the AS through if it's an exterior route, so each BGP
712
	speaker within the AS has a chance to use the shortest interior path
713
	possible to this point.
714
	<tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute
715
	which carries no value, but which sole presence indicates that the route
716
	has been aggregated from multiple routes by some AS on the path from
717
	the originator.
718
<!-- we don't handle aggregators right since they are of a very obscure type
719
	<tag>bgp_aggregator</tag>
720
-->
721
	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
722
	with the route. Each such value is a pair (represented as a <cf/pair/ data
723
	type inside the filters) of 16-bit integers, the first of them containing a number of the AS which defines
724
	the community and the second one is a per-AS identifier. There are lots
725
	of uses of the community mechanism, but generally they are used to carry
726
	policy information like "don't export to USA peers". As each AS can define
727
	its own routing policy, it also has a complete freedom about which community
728
	attributes it defines and what their semantics will be.
729
</descrip>
730

    
731
<sect1>Example
732

    
733
<p><code>
734
protocol bgp {
735
	local as 65000;				# Use a private AS number
736
	neighbor 62.168.0.130 as 5588;		# Our neighbor
737
	multihop 20 via 62.168.0.13;		# Which is connected indirectly
738
	export filter {				# We use non-trivial export rules
739
		if source = RTS_STATIC then {	# Export only static routes
740
		        # Assign our community
741
			bgp_community.add((65000,5678));
742
			# Artificially increase path length
743
			# by prepending local AS number twice
744
			if bgp_path ~ / 65000 / then	  
745
				bgp_path.prepend(65000);  
746
			accept;
747
		}
748
		reject;
749
	};
750
	import all;
751
	source address 62.168.0.1;		# Use non-standard source address
752
}
753
</code>
754

    
755
<sect>Device
756

    
757
<p>The Device protocol is not a real routing protocol as it doesn't generate
758
any routes and only serves as a module for getting information about network
759
interfaces from the kernel.
760

    
761
<p>Except for very unusual circumstances, you probably should include
762
this protocol in the configuration since almost all other protocol
763
require network interfaces to be defined in order to work.
764

    
765
<p>The only configurable thing is interface scan time:
766

    
767
<p><descrip>
768
	<tag>scan time <m/number/</tag> Time in seconds between two scans
769
	of the network interface list. On systems where we are notified about
770
	interface status changes asynchronously (such as newer versions of
771
	Linux), we need to scan the list only to avoid confusion by lost
772
	notifications, so the default time is set to a large value.
773
</descrip>
774

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

    
778
<p><code>
779
protocol device {
780
	scan time 10;		# Scan the interfaces often
781
}
782
</code>
783

    
784
<sect>Direct
785

    
786
<p>The Direct protocol is a simple generator of device routes for all the
787
directly connected networks according to the list of interfaces provided
788
by the kernel via the Device protocol.
789

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

    
795
<p>Only configurable thing about direct is what interfaces it watches:
796

    
797
<p><descrip>
798
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
799
	protocol will generate device routes for all the interfaces
800
	available. If you want to restrict it to some subset of interfaces
801
	(for example if you're using multiple routing tables for policy
802
	routing and some of the policy domains don't contain all interfaces),
803
	just use this clause.
804
</descrip>
805

    
806
<p>Direct device routes don't contain any specific attributes.
807

    
808
<p>Example config might look like this:
809

    
810
<p><code>
811
protocol direct {
812
	interface "-arc*", "*";		# Exclude the ARCnets
813
}
814
</code>
815

    
816
<sect>Kernel
817

    
818
<p>The Kernel protocol is not a real routing protocol. Instead of communicating
819
with other routers in the network, it performs synchronization of BIRD's routing
820
tables with OS kernel. Basically, it sends all routing table updates to the kernel
821
and from time to time it scans the kernel tables to see whether some routes have
822
disappeared (for example due to unnoticed up/down transition of an interface)
823
or whether an `alien' route has been added by someone else (depending on the
824
<cf/learn/ switch, such routes are either deleted or we accept them to our
825
table).
826

    
827
<p>If your OS supports only a single routing table, you can configure only one
828
instance of the Kernel protocol. If it supports multiple tables (in order to
829
allow policy routing), you can run as many instances as you want, but each of
830
them must be connected to a different BIRD routing table and to a different
831
kernel table.
832

    
833
<sect1>Configuration
834

    
835
<p><descrip>
836
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
837
	routing tables when it exits (instead of cleaning them up).
838
	<tag>scan time <m/number/</tag> Time in seconds between two scans of the
839
	kernel routing table.
840
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
841
	routing tables by other routing daemons or by the system administrator.
842
	This is possible only on systems which support identification of route
843
	authorship.
844
	<tag>kernel table <m/number/</tag> Select which kernel table should
845
	this particular instance of the Kernel protocol work with. Available
846
	only on systems supporting multiple routing tables.
847
</descrip>
848

    
849
<p>A simple configuration can look this way:
850

    
851
<p><code>
852
protocol kernel {
853
	import all;
854
	export all;
855
}
856
</code>
857

    
858
<p>Or for a system with two routing tables:
859

    
860
<p><code>
861
protocol kernel {		# Primary routing table
862
	learn;			# Learn alien routes from the kernel
863
	persist;		# Don't remove routes on bird shutdown
864
	scan time 10;		# Scan kernel routing table every 10 seconds
865
	import all;
866
	export all;
867
}
868

    
869
protocol kernel {		# Secondary routing table
870
	table auxtable;
871
	kernel table 100;
872
	export all;
873
}
874
</code>
875

    
876
<p>The Kernel protocol doesn't define any route attributes.
877

    
878
<sect>OSPF
879

    
880
<sect1>Introduction
881

    
882
<p>Open Shortest Path First (OSPF) is quite complex interior gateway
883
protocol.  Today's version for IPv4 is 2 and it's defined in RFC 2328<htmlurl
884
url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt">. It's based on
885
link-state of SPF technology. Each router maintains a database
886
describing the Autonomous System's topology. Each participating router has
887
has an identical database and all routers run the exact same algorithm
888
calculatin shortest path tree with themselves as roots, in parallel.
889
OSPF chooses the least cost path as the best path. In OSPF, the
890
Autonomous System can be splitted into more areas. Topology
891
of such area is hidden to the rest of the Autonomous System. This enables
892
a reduction in routing traffic as well as protection other areas from bad
893
routing data. Unfortunatelly multiple OSPF areas are not fully supported
894
in this version of BIRD. Another very important feature of OSPF is that
895
it can keep routing information from other protocols (like static or BGP)
896
in it's link-state database as external routes. Each external route can
897
be tagged by the advertising router, enabling the passing of additional
898
information between routers on the boundary of the Autonomous System.
899

    
900
<p>OSPF quickly detects topological changes in the Autonomous System (such
901
as router interface failures) and calculates new loop-free routes after a
902
period of convergence. This period of convergence is short and involves
903
a minimum of routing traffic.
904

    
905
<p>Each router joined in OSPF periodically sends hello messages out
906
all its interfaces. This allows neighbors to be discovered dynamically.
907
Then the neighbors exchange theirs parts of database. And keep it
908
identical flooding updates. Flooding proces is reliable and ensures
909
that each routes detects the change.
910

    
911
<sect1>Configuration
912

    
913
<p>
914

    
915
<code>
916
protocol ospf <name> {
917
	rfc1583compat bool;
918
	area <id> {
919
		stub <bool>;
920
		tick <num>;
921
		interface <interface>
922
		{
923
			cost <num>;
924
			hello <num>;
925
			retransmit <num>;
926
			priority <num>;
927
			wait <num>;
928
			dead count <num>;
929
			type [broadcast|nonbroadcast|pointopoint];
930
			authetication [none|simple];
931
			password "<text>";
932
			neighbors {
933
				<ip>;
934
			};
935
		};
936
	};
937
}
938
</code>
939

    
940
<descrip>
941
	<tag>rfc1583compat <M>bool</M></tag>
942
	 This option can disable or enable compatibility of routing table
943
	 calculation with RFC 1583<htmlurl
944
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
945
	 value is no.
946
	
947
	<tag>area <M>id</M></tag>
948
	 This specifies area id of configured OSPF area. It can be written
949
	 as a number or as an IPv4 number. The most important area is
950
	 the backbone (area id 0) to which every other area must be connected.
951

    
952
	<tag>stub <M>bool</M></tag>
953
	 No external routes are flooded into stub area. Default value is no.
954

    
955
	<tag>tick <M>num</M></tag>
956
	 The routing table calculation is not processed when any single
957
	 change comes. To lower the CPU utilization it's processed late
958
	 in periodical interval. The default value is 7.
959

    
960
	<tag>interface <M>interface</M></tag>
961
	 This mean that specified interface (or interface pattern) belongs
962
	 to actual area.
963

    
964
	<tag>cost <M>num</M></tag>
965
	 Specifies output cost of interface. Default value is 10.
966

    
967
	<tag>hello <M>num</M></tag>
968
	 Specifies interval between sending hello messages. Beware, all
969
	 router on the same network has to have the same hello interval.
970
	 Default value is 10.
971

    
972
	<tag>retransmit <M>num</M></tag>
973
	 Specifies interval between retransmiting unacknoledged update.
974
	 Default value is 5.
975

    
976
        <tag>priority <M>num</M></tag>
977
	 On every multiple access network (like e.g ethernet) Designed
978
	 and Backup Designed router is elected. These routers have some
979
	 special functions in flooding process. Higher priority rices
980
	 preferences in elections. Routers with priority 0 are not
981
	 eligible. Default value is 1.
982

    
983
	<tag>wait <M>num</M></tag>
984
	 After start, router waits specified interval between starting
985
	 election and building adjacency. Default value is 40.
986
	 
987
	<tag>dead count <M>num</M></tag>
988
	 When router does not receive any message from neighbor in
989
	 <dead count>*<hello> seconds, it will declare neighbor down.
990

    
991
	<tag>type <M>broadcast</M><tag>
992
	 BIRD detects a type of connected network. However, sometimes is
993
	 necessary to change it. On broadcast networks are flooding
994
	 and hello messages sent using multicasting. (Single
995
	 packet to all neighbors.)
996

    
997
	<tag>type <M>nonbroadcast</M></tag>
998
	 On nonbroadcast network are packets sent to each neighbor
999
	 separately because of lack of multicast messages.
1000

    
1001
	<tag>type <M>pointopoint</M></tag>
1002
	 Pointopoint network connects just 2 routers together. No election
1003
	 is provided there, this reduces a number of sent messages.
1004

    
1005
	<tag>authetication <M>none</M></tag>
1006
	 No passwords are sent in OSPF's packets. This is default value.
1007

    
1008
	<tag>authetication <M>simple</M></tag>
1009
	 In every packet is sent an 8 bytes long password. Received packets
1010
	 without this password are ignored. This autentication mechanism is
1011
	 very weak.
1012

    
1013
	<tag>password <M>text</M></tag>
1014
	 An 8 bytes long password used for authentication.
1015

    
1016
	<tag>neighbors</tag>
1017
	 A set of neighbors to which hello messages on nonbroadcast networks
1018
	 are sent.
1019
</descrip>
1020

    
1021
<sect1>Attributes
1022

    
1023
<p>OSPF defines 3 route attributes. Each internal route has a metric. External
1024
routes uses metric type 1 or metric type 2. Metric type one is comparable
1025
with internal metric. Metric type 2 is always longer then metric type 1
1026
or internal metric. Each external route can also carry a tag. Tag is
1027
32 bits long number and it's used for exporting routes to other protocols
1028
in link-state it has no funtion.
1029

    
1030
<sect1>Example
1031

    
1032
<p>
1033

    
1034
<code>
1035
protocol ospf MyOSPF {
1036
	area 0.0.0.0 {
1037
		tick 8;
1038
		interface "eth*" {
1039
			cost 11;
1040
			hello 15;
1041
			priority 100;
1042
			retransmit 7;
1043
			authentication simple;
1044
			password "aaa";
1045
		};
1046
		interface "ppp*" {
1047
			cost 100;
1048
		};
1049
	};
1050
	area 120 {
1051
		stub yes;
1052
		interface "-arc0" , "arc*" {
1053
			type nonbroadcast;
1054
			authentication none;
1055
			wait 50;
1056
			dead count 6;
1057
			neighbors {
1058
				192.168.120.1;
1059
				192.168.120.2;
1060
				192.168.120.10;
1061
			};
1062
		};
1063
	};
1064
}
1065
</code>
1066

    
1067
<sect>Pipe
1068

    
1069
<sect1>Introduction
1070

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

    
1078
<p>The primary use of multiple routing tables and the pipe protocol is for policy routing,
1079
where handling of a single packet doesn't depend only on its destination address, but also
1080
on its source address, source interface, protocol type and other similar parameters.
1081
In many systems (Linux 2.2 being a good example) the kernel allows to enforce routing policies
1082
by defining routing rules which choose one of several routing tables to be used for a packet
1083
according to its parameters. Setting of these rules is outside the scope of BIRD's work
1084
(you can use the <tt/ip/ command), but you can create several routing tables in BIRD,
1085
connect them to the kernel ones, use filters to control which routes appear in which tables
1086
and also you can employ the Pipe protocol to export a selected subset of one table in
1087
another one.
1088

    
1089
<sect1>Configuration
1090

    
1091
<p><descrip>
1092
	<tag>peer table <m/table/</tag> Define secondary routing table to connect to. The
1093
	primary one is selected by the <cf/table/ keyword.
1094
</descrip>
1095

    
1096
<sect1>Attributes
1097

    
1098
<p>The Pipe protocol doesn't define any route attributes.
1099

    
1100
<sect1>Example
1101

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

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

    
1116
<code>
1117
table as1;				# Define the tables
1118
table as2;
1119

    
1120
protocol kernel kern1 {			# Synchronize them with the kernel
1121
	table as1;
1122
	kernel table 1;
1123
}
1124

    
1125
protocol kernel kern2 {
1126
	table as2;
1127
	kernel table 2;
1128
}
1129

    
1130
protocol bgp bgp1 {			# The outside connections
1131
	table as1;
1132
	local as 1;
1133
	neighbor 192.168.0.1 as 1001;
1134
	export all;
1135
	import all;
1136
}
1137

    
1138
protocol bgp bgp2 {
1139
	table as2;
1140
	local as 2;
1141
	neighbor 10.0.0.1 as 1002;
1142
	export all;
1143
	import all;
1144
}
1145

    
1146
protocol pipe {				# The Pipe
1147
	table as1;
1148
	peer table as2;
1149
	export filter {
1150
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
1151
			if preference>10 then preference = preference-10;
1152
			if source=RTS_BGP then bgp_path.prepend(1);
1153
			accept;
1154
		}
1155
		reject;
1156
	};
1157
	import filter {
1158
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
1159
			if preference>10 then preference = preference-10;
1160
			if source=RTS_BGP then bgp_path.prepend(2);
1161
			accept;
1162
		}
1163
		reject;
1164
	};
1165
}
1166
</code>
1167

    
1168
<sect>RIP
1169

    
1170
<sect1>Introduction
1171

    
1172
<p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors)
1173
distances to all networks it can reach. When a router hears distance to another network, it increments
1174
it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes
1175
unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus
1176
interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in
1177
RIP) and all routers know that network is unreachable. RIP tries to minimize situations where
1178
counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use
1179
RIP on networks where maximal distance is higher than 15 hosts. You can read more about rip at <HTMLURL
1180
URL="http://www.ietf.org/html.charters/rip-charter.html" TEXT="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4
1181
and IPv6 versions of RIP are supported by BIRD, historical RIPv1 is
1182
currently not fully supported.
1183

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

    
1190
<sect1>Configuration
1191

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

    
1194
<descrip>
1195
	<tag/authentication none|password|md5/ selects authentication method to be used. <cf/none/ means that
1196
	  packets are not authenticated at all, <cf/password/ means that a plaintext password is embedded
1197
	  into each packet, and <cf/md5/ means that packets are authenticated using a md5 cryptographic
1198
	  hash. If you set authentication to not-none, it is a good idea to add <cf>passwords { }</cf>
1199
	  section.
1200

    
1201
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
1202
	  be honored. (Always, when sent from a  host on a directly connected
1203
	  network or never.) Routing table updates are honored only from
1204
	  neighbors, that is not configurable.
1205
</descrip>
1206

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

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

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

    
1224
	<tag>infinity <M>number</M></tag>
1225
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
1226
	  even slower.
1227

    
1228
	<tag>period <M>number</M>
1229
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
1230
	  number will mean faster convergence but bigger network
1231
	  load. Do not use values lower than 10.
1232

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

    
1236
	<tag>garbage time <M>number</M>
1237
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
1238
</descrip>
1239

    
1240
<sect1>Attributes
1241

    
1242
<p>RIP defines two route attributes:
1243

    
1244
<descrip>
1245
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
1246
	When routes from different RIP instances are available and all of them have the same
1247
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
1248

    
1249
	<tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used
1250
	to carry additional information with the route (for example, an originating AS number
1251
	in case of external routes).
1252
</descrip>
1253

    
1254
<sect1>Example
1255

    
1256
<p><code>
1257
protocol rip MyRIP_test {
1258
        debug all;
1259
        port 1520;
1260
        period 10;
1261
        garbage time 60;
1262
        interface "eth0" { metric 3; mode multicast; }
1263
	          "eth1" { metric 2; mode broadcast; };
1264
        honor neighbor;
1265
        authentication none;
1266
        import filter { print "importing"; accept; };
1267
        export filter { print "exporting"; accept; };
1268
}
1269
</code>
1270

    
1271
<sect>Static
1272

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

    
1281
<p>There are three types of static routes: `classical' routes telling to
1282
forward packets to a neighboring router, device routes specifying forwarding
1283
to hosts on a directly connected network and special routes (sink, blackhole
1284
etc.) which specify a special action to be done instead of forwarding the
1285
packet.
1286

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

    
1292
<p>The Static protocol has no configuration options. Instead, the
1293
definition of the protocol contains a list of static routes:
1294

    
1295
<descrip>
1296
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
1297
	a neighboring router.
1298
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
1299
	route through an interface to hosts on a directly connected network.
1300
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
1301
	specifying to drop the packet, return it as unreachable or return
1302
	it as administratively prohibited.
1303
</descrip>
1304

    
1305
<p>Static routes have no specific attributes.
1306

    
1307
<p>Example static config might look like this:
1308

    
1309
<p><code>
1310
protocol static {
1311
	table testable;				# Connect to a non-default routing table
1312
	route 0.0.0.0/0 via 62.168.0.13;	# Default route
1313
	route 62.168.0.0/25 reject;		# Sink route
1314
	route 10.2.0.0/24 via "arc0";		# Secondary network
1315
}
1316
</code>
1317

    
1318
<chapt>Problems
1319

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

    
1330
<p><it/Good luck!/
1331

    
1332
</book>
1333

    
1334
<!--
1335
LocalWords:  GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
1336
LocalWords:  linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps
1337
LocalWords:  router's eval expr num birdc ctl unix if's enums bool int ip GCC
1338
LocalWords:  len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth
1339
LocalWords:  RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek
1340
LocalWords:  EGP misconfigurations keepalive pref aggr aggregator BIRD's
1341
LocalWords:  OS'es AS's multicast nolisten misconfigured UID blackhole
1342
LocalWords:  uninstalls ethernets IP
1343
 -->