Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 1532a244

History | View | Annotate | Download (49.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
<sect>Pipe
881

    
882
<sect1>Introduction
883

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

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

    
902
<sect1>Configuration
903

    
904
<p><descrip>
905
	<tag>peer table <m/table/</tag> Define secondary routing table to connect to. The
906
	primary one is selected by the <cf/table/ keyword.
907
</descrip>
908

    
909
<sect1>Attributes
910

    
911
<p>The Pipe protocol doesn't define any route attributes.
912

    
913
<sect1>Example
914

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

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

    
929
<code>
930
table as1;				# Define the tables
931
table as2;
932

    
933
protocol kernel kern1 {			# Synchronize them with the kernel
934
	table as1;
935
	kernel table 1;
936
}
937

    
938
protocol kernel kern2 {
939
	table as2;
940
	kernel table 2;
941
}
942

    
943
protocol bgp bgp1 {			# The outside connections
944
	table as1;
945
	local as 1;
946
	neighbor 192.168.0.1 as 1001;
947
	export all;
948
	import all;
949
}
950

    
951
protocol bgp bgp2 {
952
	table as2;
953
	local as 2;
954
	neighbor 10.0.0.1 as 1002;
955
	export all;
956
	import all;
957
}
958

    
959
protocol pipe {				# The Pipe
960
	table as1;
961
	peer table as2;
962
	export filter {
963
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
964
			if preference>10 then preference = preference-10;
965
			if source=RTS_BGP then bgp_path.prepend(1);
966
			accept;
967
		}
968
		reject;
969
	};
970
	import filter {
971
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
972
			if preference>10 then preference = preference-10;
973
			if source=RTS_BGP then bgp_path.prepend(2);
974
			accept;
975
		}
976
		reject;
977
	};
978
}
979
</code>
980

    
981
<sect>RIP
982

    
983
<sect1>Introduction
984

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

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

    
1003
<sect1>Configuration
1004

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

    
1007
<descrip>
1008
	<tag/authentication none|password|md5/ selects authentication method to be used. <cf/none/ means that
1009
	  packets are not authenticated at all, <cf/password/ means that a plaintext password is embedded
1010
	  into each packet, and <cf/md5/ means that packets are authenticated using a md5 cryptographic
1011
	  hash. If you set authentication to not-none, it is a good idea to add <cf>passwords { }</cf>
1012
	  section.
1013

    
1014
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
1015
	  be honored. (Always, when sent from a  host on a directly connected
1016
	  network or never.) Routing table updates are honored only from
1017
	  neighbors, that is not configurable.
1018
</descrip>
1019

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

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

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

    
1037
	<tag>infinity <M>number</M></tag>
1038
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
1039
	  even slower.
1040

    
1041
	<tag>period <M>number</M>
1042
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
1043
	  number will mean faster convergence but bigger network
1044
	  load. Do not use values lower than 10.
1045

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

    
1049
	<tag>garbage time <M>number</M>
1050
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
1051
</descrip>
1052

    
1053
<sect1>Attributes
1054

    
1055
<p>RIP defines two route attributes:
1056

    
1057
<descrip>
1058
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
1059
	When routes from different RIP instances are available and all of them have the same
1060
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
1061

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

    
1067
<sect1>Example
1068

    
1069
<p><code>
1070
protocol rip MyRIP_test {
1071
        debug all;
1072
        port 1520;
1073
        period 10;
1074
        garbage time 60;
1075
        interface "eth0" { metric 3; mode multicast; }
1076
	          "eth1" { metric 2; mode broadcast; };
1077
        honor neighbor;
1078
        authentication none;
1079
        import filter { print "importing"; accept; };
1080
        export filter { print "exporting"; accept; };
1081
}
1082
</code>
1083

    
1084
<sect>Static
1085

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

    
1094
<p>There are three types of static routes: `classical' routes telling to
1095
forward packets to a neighboring router, device routes specifying forwarding
1096
to hosts on a directly connected network and special routes (sink, blackhole
1097
etc.) which specify a special action to be done instead of forwarding the
1098
packet.
1099

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

    
1105
<p>The Static protocol has no configuration options. Instead, the
1106
definition of the protocol contains a list of static routes:
1107

    
1108
<descrip>
1109
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
1110
	a neighboring router.
1111
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
1112
	route through an interface to hosts on a directly connected network.
1113
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
1114
	specifying to drop the packet, return it as unreachable or return
1115
	it as administratively prohibited.
1116
</descrip>
1117

    
1118
<p>Static routes have no specific attributes.
1119

    
1120
<p>Example static config might look like this:
1121

    
1122
<p><code>
1123
protocol static {
1124
	table testable;				# Connect to a non-default routing table
1125
	route 0.0.0.0/0 via 62.168.0.13;	# Default route
1126
	route 62.168.0.0/25 reject;		# Sink route
1127
	route 10.2.0.0/24 via "arc0";		# Secondary network
1128
}
1129
</code>
1130

    
1131
<chapt>Problems
1132

    
1133
<p>BIRD is relatively young system, and probably contains some
1134
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,
1135
please make sure you have read available documentation, make sure are running latest version (available at <HTMLURL
1136
URL="ftp://bird.network.cz/pub/bird" TEXT="bird.network.cz:/pub/bird>). (Of course, patch
1137
which fixes the bug along with bug report is always welcome). If you
1138
want to use BIRD, join mailing list by sending
1139
<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
1140
trying to understand, what is going on, Internet standards are
1141
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">.
1142

    
1143
<p><it/Good luck!/
1144

    
1145
</book>
1146

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