Statistics
| Branch: | Revision:

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

History | View | Annotate | Download (80.7 KB)

1
<!doctype birddoc system>
2

    
3
<!--
4
	BIRD documentation
5

    
6
This documentation can have 4 forms: sgml (this is master copy), html,
7
ASCII text and dvi/postscript (generated from sgml using
8
sgmltools). You should always edit master copy.
9

    
10
This is a slightly modified linuxdoc dtd.  Anything in <descrip> tags is considered definition of
11
configuration primitives, <cf> is fragment of configuration within normal text, <m> is
12
"meta" information within fragment of configuration - something in config which is not keyword.
13

    
14
    (set-fill-column 100)
15

    
16
    Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
17

    
18
 -->
19

    
20
<book>
21

    
22
<title>BIRD User's Guide
23
<author>
24
Ondrej Filip <it/&lt;feela@network.cz&gt;/,
25
Pavel Machek <it/&lt;pavel@ucw.cz&gt;/,
26
Martin Mares <it/&lt;mj@ucw.cz&gt;/,
27
Ondrej Zajicek <it/&lt;santiago@crfreenet.org&gt;/
28
</author>
29

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

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

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

    
39
<chapt>Introduction
40

    
41
<sect>What is BIRD
42

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

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

    
50
<p><em/Internet Routing/: It's a program (well, a daemon, as you are going to discover in a moment)
51
which works as a dynamic router in an Internet type network (that is, in a network running either
52
the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected
53
networks in order to allow hosts not connected directly to the same local area network to
54
communicate with each other. They also communicate with the other routers in the Internet to discover
55
the topology of the network which allows them to find optimal (in terms of some metric) rules for
56
forwarding of packets (which are called routing tables) and to adapt themselves to the
57
changing conditions such as outages of network links, building of new connections and so on. Most of
58
these routers are costly dedicated devices running obscure firmware which is hard to configure and
59
not open to any changes (on the other hand, their special hardware design allows them to keep up with lots of high-speed network interfaces, better than general-purpose computer does). Fortunately, most operating systems of the UNIX family allow an ordinary 
60
computer to act as a router and forward packets belonging to the other hosts, but only according to
61
a statically configured table.
62

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

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

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

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

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

    
101
<sect>Installing BIRD
102

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

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

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

    
120
<sect>Running BIRD
121

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

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

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

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

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

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

    
140
<chapt>About routing tables
141

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

    
147
<itemize>
148
	<item>network prefix this route is for (network address and prefix length -- the number of bits forming the network part of the address; also known as a netmask)
149
	<item>preference of this route
150
	<item>IP address of router which told us about this route
151
	<item>IP address of router we should forward the packets to
152
	using this route
153
	<item>other attributes common to all routes
154
	<item>dynamic attributes defined by protocols which may or
155
	may not be present (typically protocol metrics)
156
</itemize>
157

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

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

    
176
<chapt>Configuration
177

    
178
<sect>Introduction
179

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

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

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

    
195

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

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

    
207
protocol rip {
208
	export all;
209
	import all;
210
	interface "*";
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 class (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 establish logging to multiple
227
	destinations. Default: log everything to the system log.
228

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

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

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

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

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

    
251
	<tag>router id <m/IPv4 address/</tag> Set BIRD's router ID. It's a world-wide unique identification of your router, usually one of router's IPv4 addresses. Default: in IPv4 version, the lowest IP address of a non-loopback interface. In IPv6 version, this option is mandatory. 
252

    
253
	<tag>listen bgp [address <m/address/] [port <m/port/] [v6only]</tag>
254
	This option allows to specify address and port where BGP
255
	protocol should listen. It is global option as listening
256
	socket is common to all BGP instances. Default is to listen on
257
	all addresses (0.0.0.0) and port 179. In IPv6 mode, option
258
	<cf/v6only/ can be used to specify that BGP socket should
259
	listen to IPv6 connections only. This is needed if you want to
260
	run both bird and bird6 on the same port.
261

    
262
	<tag>table <m/name/</tag> Create a new routing table. The default
263
	routing table is created implicitly, other routing tables have
264
	to be added by this command.
265

    
266
	<tag>eval <m/expr/</tag> Evaluates given filter expression. It
267
	is used by us for testing of filters.
268
</descrip>
269

    
270
<sect>Protocol options
271

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

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

    
282
<descrip>
283
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
284

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

    
288
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
289
	Set protocol debugging options. If asked, each protocol is capable of
290
	writing trace messages about its work to the log (with category
291
	<cf/trace/). You can either request printing of <cf/all/ trace messages
292
	or only of the types selected: <cf/states/ for protocol state changes
293
	(protocol going up, down, starting, stopping etc.),
294
	<cf/routes/ for routes exchanged with the routing table,
295
	<cf/filters/ for details on route filtering,
296
	<cf/interfaces/ for interface change events sent to the protocol,
297
	<cf/events/ for events internal to the protocol and
298
	<cf/packets/ for packets sent and received by the protocol. Default: off.
299

    
300
	<tag>router id <m/IPv4 address/</tag> This option can be used to override global
301
	router id for a given protocol. This option is not yet implemented for OSPF
302
	protocol. Default: uses global router id.
303

    
304
	<tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> 
305
	Specify a filter to be used for filtering routes coming from the protocol to the routing table. <cf/all/ is shorthand for <cf/where true/ and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/.
306

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

    
310
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
311
</descrip>
312

    
313
<p>There are several options that give sense only with certain protocols:
314

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

    
318
	Specifies a set of interfaces on which the protocol is activated with
319
	given interface-specific options. A set of interfaces specified by one
320
	interface option is described using an interface pattern. The
321
	interface pattern consists of a sequence of clauses (separted by
322
	commas), each clause may contain a mask, a prefix, or both of them. An
323
	interface matches the clause if its name matches the mask (if
324
	specified) and its address matches the prefix (if specified). Mask is
325
	specified as shell-like pattern.
326

    
327
	An interface matches the pattern if it matches any of its
328
	clauses. If the clause begins with <cf/-/, matching interfaces are
329
	excluded. Patterns are parsed left-to-right, thus
330
	<cf/interface "eth0", -"eth*", "*";/ means eth0 and all
331
	non-ethernets.
332

    
333
	An interface option can be used more times with different
334
	interfaces-specific options, in that case for given interface
335
	the first matching interface option is used.
336
	
337
	This option is allowed in Direct, OSPF and RIP protocols,
338
	but in OSPF protocol it is used in <cf/area/ subsection.
339

    
340
	Default: none.
341

    
342
	Examples:
343

    
344
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
345
	<cf>type broadcast</cf> option.
346

    
347
	<cf>interface "eth1", "eth4", "eth5" { type pointopoint; };</cf> - start the protocol
348
	on enumerated interfaces with <cf>type pointopoint</cf> option.
349
	
350
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
351
	interfaces that have address from 192.168.0.0/16, but not
352
	from 192.168.1.0/24.
353

    
354
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
355
	interfaces that have address from 192.168.0.0/16, but not
356
	from 192.168.1.0/24.
357

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

    
361
	<tag><label id="dsc-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag>
362
	Specifies a password that can be used by the protocol. Password option can
363
	be used more times to specify more passwords. If more passwords are
364
	specified, it is a protocol-dependent decision which one is really
365
	used. Specifying passwords does not mean that authentication is
366
	enabled, authentication can be enabled by separate, protocol-dependent
367
	<cf/authentication/ option.
368
	
369
	This option is allowed in OSPF and RIP protocols. BGP has also
370
	<cf/password/ option, but it is slightly different and described
371
	separately.
372

    
373
	Default: none.
374
</descrip>
375

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

    
378
<descrip>
379
	<tag>id <M>num</M></tag>
380
	 ID of the password, (0-255). If it's not used, BIRD will choose
381
	 ID based on an order of the password item in the interface. For
382
	 example, second password item in one interface will have default
383
	 ID 2. ID is used by some routing protocols to identify which
384
	 password was used to authenticate protocol packets.
385

    
386
	<tag>generate from "<m/time/"</tag>
387
	 The start time of the usage of the password for packet signing.
388
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
389

    
390
	<tag>generate to "<m/time/"</tag>
391
	 The last time of the usage of the password for packet signing.
392

    
393
	<tag>accept from "<m/time/"</tag>
394
	 The start time of the usage of the password for packet verification.
395

    
396
	<tag>accept to "<m/time/"</tag>
397
	 The last time of the usage of the password for packet verification.
398
</descrip>
399

    
400
<chapt>Remote control
401

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

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

    
417
<p>Here is a brief list of supported functions:
418

    
419
<descrip>
420
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
421
	Dump contents of internal data structures to the debugging output.
422

    
423
	<tag>show status</tag>
424
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
425

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

    
429
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
430
	Show detailed information about OSPF interfaces.
431

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

    
435
	<tag>show ospf state [<m/name/]</tag>
436
	Show detailed information about OSPF areas based on a content of link-state database.
437
	It shows network topology,  aggregated networks and routers from other areas and external routes.
438

    
439
	<tag>show ospf topology [<m/name/]</tag>
440
	Show a topology of OSPF areas based on a content of link-state database.
441
	It is just a stripped-down version of 'show ospf state'.
442

    
443
	<tag>show static [<m/name/]</tag>
444
	Show detailed information about static routes.
445

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

    
449
	<tag>show symbols</tag>
450
	Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
451

    
452
	<tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(export|preexport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
453
	Show contents of a routing table (by default of the main one),
454
	that is routes, their metrics and (in case the <cf/all/ switch is given)
455
	all their attributes.
456

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

    
464
	<p>You can also ask for printing only routes processed and accepted by
465
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
466
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
467
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
468
	that are exported to the specified protocol. With <cf/preexport/, the
469
	export filter of the protocol is skipped.
470

    
471
	<p>You can also select just routes added by a specific protocol.
472
	<cf>protocol <m/p/</cf>.
473

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

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

    
481
	<tag>configure [soft] ["<m/config file/"]</tag>
482
	Reload configuration from a given file. BIRD will smoothly
483
	switch itself to the new configuration, protocols are
484
	reconfigured if possible, restarted otherwise. Changes in
485
	filters usualy lead to restart of affected protocols. If
486
	<cf/soft/ option is used, changes in filters does not cause
487
	BIRD to restart affected protocols, therefore already accepted
488
	routes (according to old filters) would be still propagated,
489
	but new routes would be processed according to the new
490
	filters.
491

    
492
	<tag/down/
493
	Shut BIRD down.
494

    
495
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
496
	Control protocol debugging.
497
</descrip>
498

    
499
<chapt>Filters
500

    
501
<sect>Introduction
502

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

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

    
513
<code>
514
filter not_too_far
515
int var;
516
{
517
	if defined( rip_metric ) then
518
		var = rip_metric;
519
	else {
520
		var = 1;
521
		rip_metric = 1;
522
	}
523
	if rip_metric &gt; 10 then
524
		reject "RIP metric is too big";
525
	else
526
		accept "ok";
527
}
528
</code>
529

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

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

    
541
<code>
542
function name ()
543
int local_variable;
544
{
545
	local_variable = 5;
546
}
547

    
548
function with_parameters (int parameter)
549
{
550
	print parameter;
551
}
552
</code>
553

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

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

    
565
<p>A nice trick to debug filters is to use <cf>show route filter
566
<m/name/</cf> from the command line client. An example session might look
567
like:
568

    
569
<code>
570
pavel@bug:~/bird$ ./birdc -s bird.ctl
571
BIRD 0.0.0 ready.
572
bird> show route
573
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
574
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
575
127.0.0.0/8        dev lo [direct1 23:21] (240)
576
bird> show route ?
577
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
578
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
579
127.0.0.0/8        dev lo [direct1 23:21] (240)
580
bird>
581
</code>
582

    
583
<sect>Data types
584

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

    
588
<descrip>
589
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
590
	  <cf/false/. Boolean is the only type you can use in <cf/if/
591
	  statements.
592

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

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

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

    
605
	<tag/ip/ This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it
606
	  is either an IPv4 or IPv6 address. IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf>
607
	  on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP
608
	  address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
609

    
610
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
611
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
612
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
613
	  operators on prefixes:
614
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
615
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
616

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

    
623
	  Sets of prefixes are special: their literals does not allow ranges, but allows
624
	  prefix patterns that are written as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
625
	  Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> iff 
626
	  the first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are identical and <cf>len1 &lt;= ip1 &lt;= len2</cf>.
627
	  A valid prefix pattern has to satisfy <cf>low &lt;= high</cf>, but <cf/pxlen/ is not constrained by <cf/low/
628
	  or <cf/high/. Obviously, a prefix matches a prefix set literal iff it matches any prefix pattern in the
629
	  prefix set literal.
630

    
631
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
632
	  <cf><m>address</m>/<m/len/{<m/len/,<m/maxlen/}</cf> (where <cf><m>maxlen</m></cf> is 32 for IPv4 and 128 for IPv6), 
633
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
634
	  is a shorthand for <cf><m>address</m>/<m/len/{0,<m/len/}</cf>, that means network prefix <cf><m>address</m>/<m/len/</cf>
635
	  and all its supernets (network prefixes that contain it).
636

    
637
	  For example, <cf>[ 1.0.0.0/8, 2.0.0.0/8+, 3.0.0.0/8-, 4.0.0.0/8{16,24} ]</cf> matches
638
	  prefix <cf>1.0.0.0/8</cf>, all subprefixes of <cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes
639
	  <cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf> matches all prefixes (regardless of
640
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
641
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
642
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
643

    
644
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
645
	  in Bird as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
646
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
647
	  <cf>192.168.0.0/16{24,32}</cf>.
648

    
649
	<tag/enum/
650
	  Enumeration types are fixed sets of possibilities. You can't define your own
651
	  variables of such type, but some route attributes are of enumeration
652
	  type. Enumeration types are incompatible with each other.
653

    
654
	<tag/bgppath/
655
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
656
	  There are several special operators on bgppaths:
657

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

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

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

    
665
          <cf><m/P/.len</cf> returns the length of path <m/P/.
666

    
667
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
668
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
669
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
670
          (for example <cf/bgp_path/).
671

    
672
	<tag/bgpmask/
673
	  BGP masks are patterns used for BGP path matching
674
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
675
	  resemble wildcard patterns as used by UNIX shells. Autonomous
676
	  system numbers match themselves, <cf/*/ matches any (even empty)
677
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
678
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
679
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
680
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
681
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
682
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
683
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
684

    
685
	<tag/clist/ 
686
	  Community list is similar to set of pairs,
687
	  except that unlike other sets, it can be modified.
688
	  There exist no literals of this type.
689
	  There are two special operators on clists:
690

    
691
          <cf>add(<m/C/,<m/P/)</cf> adds pair <m/P/ to clist <m/C/ and returns the result.
692

    
693
          <cf>delete(<m/C/,<m/P/)</cf> deletes pair <m/P/ from clist <m/C/ and returns the result.
694

    
695
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
696
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute
697
          (for example <cf/bgp_community/). Similarly for <cf/delete/.
698

    
699
</descrip>
700

    
701
<sect>Operators
702

    
703
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
704
<cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Logical operations include unary not (<cf/!/), and (<cf/&amp;&amp;/) and or (<cf/&verbar;&verbar;/). 
705
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
706
used on element and set of elements of the same type (returning true if element is contained in the given set), or
707
on two strings (returning true if first string matches a shell-like pattern stored in second string) or on IP and prefix (returning true if IP is within the range defined by that prefix), or on
708
prefix and prefix (returning true if first prefix is more specific than second one) or on bgppath and bgpmask (returning true if the path matches the mask) or on pair and clist (returning true if the community is element of the community list).
709

    
710

    
711
<sect>Control structures
712

    
713
<p>Filters support two control structures: conditions and case switches. 
714

    
715
<p>Syntax of a condition is: <cf>if
716
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
717
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
718
clause may be omitted. If the <cf><m>boolean expression</m></cf> is true, <cf><m>command1</m></cf> is executed, otherwise <cf><m>command2</m></cf> is executed.
719

    
720
<p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else |
721
<m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. The expression after
722
<cf>case</cf> can be of any type which can be on the left side of the &tilde; operator and anything that could
723
be a member of a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping.
724
If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed.
725

    
726
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
727

    
728
<code>
729
case arg1 {
730
	2: print "two"; print "I can do more commands without {}";
731
	3 .. 5: print "three to five";
732
	else: print "something else";
733
}
734

    
735
if 1234 = i then printn "."; else { 
736
  print "not 1234"; 
737
  print "You need {} around multiple commands"; 
738
}
739
</code>
740

    
741
<sect>Route attributes
742

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

    
748
<descrip>
749
	<tag><m/prefix/ net</tag>
750
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
751

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

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

    
758
	<tag><m/ip/ from</tag>
759
	The router which the route has originated from. Read-only.
760
	
761
	<tag><m/ip/ gw</tag>
762
	Next hop packets routed using this route should be forwarded to.
763

    
764
	<tag><m/string/ proto</tag>
765
	The name of the protocol which the route has been imported from. Read-only.
766

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

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

    
773
	<tag><m/enum/ dest</tag>
774
	Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_NETWORK/ for routing to a directly-connected network, <cf/RTD_BLACKHOLE/ for packets to be silently discarded, <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be returned with ICMP host unreachable / ICMP administratively prohibited messages). Read-only.
775
</descrip>
776

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

    
779
<sect>Other statements
780

    
781
<p>The following statements are available:
782

    
783
<descrip>
784
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
785

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

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

    
790
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
791
	Prints given expressions; useful mainly while debugging
792
	filters. The <cf/printn/ variant does not terminate the line.
793

    
794
	<tag>quitbird</tag>
795
	Terminates BIRD. Useful when debugging the filter interpreter.
796
</descrip>
797

    
798
<chapt>Protocols
799

    
800
<sect>BGP
801

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

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

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

    
821
<p>BIRD supports all requirements of the BGP4 standard as defined in
822
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
823
It also supports the community attributes
824
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
825
capability negotiation
826
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
827
MD5 password authentication
828
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
829
route reflectors 
830
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
831
multiprotocol extensions
832
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
833
and 4B AS numbers 
834
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">).
835

    
836

    
837
For IPv6, it uses the standard multiprotocol extensions defined in
838
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
839
including changes described in the
840
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
841
and applied to IPv6 according to
842
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
843

    
844
<sect1>Route selection rules
845

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

    
852
<itemize>
853
	<item>Prefer route with the highest Local Preference attribute.
854
	<item>Prefer route with the shortest AS path.
855
	<item>Prefer IGP origin over EGP and EGP over incomplete.
856
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
857
	<item>Prefer internal routes over external ones.
858
	<item>Prefer the route with the lowest value of router ID of the
859
	advertising router.
860
</itemize>
861

    
862
<sect1>Configuration
863

    
864
<p>Each instance of the BGP corresponds to one neighboring router.
865
This allows to set routing policy and all the other parameters differently
866
for each neighbor using the following configuration parameters:
867

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

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

    
881
	<tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
882
	neighbor which is connected at most <m/number/ hops far and to which
883
	we should route via our direct neighbor with address <m/ip/.
884
	Default: switched off.
885

    
886
	<tag>next hop self</tag> Avoid calculation of the Next Hop attribute
887
	and always advertise our own source address (see below) as a next hop.
888
	This needs to be used only
889
	occasionally to circumvent misconfigurations of other routers.
890
	Default: disabled.
891

    
892
	<tag>source address <m/ip/</tag> Define local address we should use
893
	for next hop calculation. Default: the address of the local end
894
	of the interface our neighbor is connected to.
895

    
896
	<tag>password <m/string/</tag> Use this password for MD5 authentication
897
	of BGP sessions. Default: no authentication. Password has to be set by
898
	external utility (e.g. setkey(8)) on BSD systems.
899

    
900
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
901
        initiating outgoing connections and accepting incoming
902
        connections. In passive mode, outgoing connections are not
903
        initiated. Default: off.
904

    
905
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
906
	a route reflection client. Default: disabled.
907

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

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

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

    
932
	<tag>capabilities <m/switch/</tag> Use capability advertisement
933
	to advertise optional capabilities. This is standard behavior
934
	for newer BGP implementations, but there might be some older
935
	BGP implementations that reject such connection attempts.
936
	When disabled (off), features that request it (4B AS support)
937
	are also disabled. Default: on, with automatic fallback to
938
	off when received capability-related error.
939

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

    
946
	<tag>route limit <m/number/</tag> The maximal number of routes
947
	that may be imported from the protocol. If the route limit is
948
	exceeded, the connection is closed with error. Default: no limit.
949

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

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

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

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

    
966
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
967
	retrying a failed attempt to connect. Default: 120 seconds.
968

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

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

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

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

    
984
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
985
	Discriminator to be used during route selection when the MED attribute
986
	is missing. Default: 0.
987

    
988
	<tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference
989
	to be used during route selection when the Local Preference attribute
990
	is missing. Default: 0.
991
</descrip>
992

    
993
<sect1>Attributes
994

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

    
999
<descrip>
1000
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1001
	the packet will travel through when forwarded according to the particular route. In case of 
1002
	internal BGP it doesn't contain the number of the local AS.
1003

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

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

    
1019
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1020
	if the route has originated in an interior routing protocol or
1021
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1022
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1023
	is unknown.
1024

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

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

    
1037
<!-- we don't handle aggregators right since they are of a very obscure type
1038
	<tag>bgp_aggregator</tag>
1039
-->
1040
	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
1041
	with the route. Each such value is a pair (represented as a <cf/pair/ data
1042
	type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
1043
	the community and the second one being a per-AS identifier. There are lots
1044
	of uses of the community mechanism, but generally they are used to carry
1045
	policy information like "don't export to USA peers". As each AS can define
1046
	its own routing policy, it also has a complete freedom about which community
1047
	attributes it defines and what will their semantics be.
1048
</descrip>
1049

    
1050
<sect1>Example
1051

    
1052
<p><code>
1053
protocol bgp {
1054
	local as 65000;			     # Use a private AS number
1055
	neighbor 62.168.0.130 as 5588;	     # Our neighbor ...
1056
	multihop 20 via 62.168.0.13;	     # ... which is connected indirectly
1057
	export filter {			     # We use non-trivial export rules
1058
		if source = RTS_STATIC then { # Export only static routes
1059
		        # Assign our community
1060
			bgp_community.add((65000,5678));
1061
			# Artificially increase path length
1062
			# by advertising local AS number twice
1063
			if bgp_path ~ [= 65000 =] then	  
1064
				bgp_path.prepend(65000);  
1065
			accept;
1066
		}
1067
		reject;
1068
	};
1069
	import all;
1070
	source address 62.168.0.1;	# Use a non-standard source address
1071
}
1072
</code>
1073

    
1074
<sect>Device
1075

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

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

    
1084
<sect1>Configuration
1085

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

    
1093
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1094
	If a network interface has more than one network address,
1095
	BIRD has to choose one of them as a primary one, because some
1096
	routing protocols (for example OSPFv2) suppose there is only
1097
	one network address per interface. By default, BIRD chooses
1098
	the lexicographically smallest address as the primary one.
1099

    
1100
	This option allows to specify which network address should be
1101
	chosen as a primary one. Network addresses that match
1102
	<m/prefix/ are preferred to non-matching addresses. If more
1103
	<cf/primary/ options are used, the first one has the highest
1104
	preference. If "<m/mask/" is specified, then such
1105
	<cf/primary/ option is relevant only to matching network
1106
	interfaces.
1107

    
1108
	In all cases, an address marked by operating system as
1109
	secondary cannot be chosen as the primary one. 
1110
</descrip>
1111

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

    
1115
<p><code>
1116
protocol device {
1117
	scan time 10;		# Scan the interfaces often
1118
	primary "eth0" 192.168.1.1;
1119
	primary 192.168.0.0/16;
1120
}
1121
</code>
1122

    
1123
<sect>Direct
1124

    
1125
<p>The Direct protocol is a simple generator of device routes for all the
1126
directly connected networks according to the list of interfaces provided
1127
by the kernel via the Device protocol.
1128

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

    
1134
<p>The only configurable thing about direct is what interfaces it watches:
1135

    
1136
<p><descrip>
1137
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
1138
	protocol will generate device routes for all the interfaces
1139
	available. If you want to restrict it to some subset of interfaces
1140
	(for example if you're using multiple routing tables for policy
1141
	routing and some of the policy domains don't contain all interfaces),
1142
	just use this clause.
1143
</descrip>
1144

    
1145
<p>Direct device routes don't contain any specific attributes.
1146

    
1147
<p>Example config might look like this:
1148

    
1149
<p><code>
1150
protocol direct {
1151
	interface "-arc*", "*";		# Exclude the ARCnets
1152
}
1153
</code>
1154

    
1155
<sect>Kernel
1156

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

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

    
1172
<sect1>Configuration
1173

    
1174
<p><descrip>
1175
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1176
	routing tables when it exits (instead of cleaning them up).
1177
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1178
	kernel routing table.
1179
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1180
	routing tables by other routing daemons or by the system administrator.
1181
	This is possible only on systems which support identification of route
1182
	authorship.
1183
	<tag>kernel table <m/number/</tag> Select which kernel table should
1184
	this particular instance of the Kernel protocol work with. Available
1185
	only on systems supporting multiple routing tables.
1186
</descrip>
1187

    
1188
<p>The Kernel protocol doesn't define any route attributes.
1189
<p>A simple configuration can look this way:
1190

    
1191
<p><code>
1192
protocol kernel {
1193
	import all;
1194
	export all;
1195
}
1196
</code>
1197

    
1198
<p>Or for a system with two routing tables:
1199

    
1200
<p><code>
1201
protocol kernel {		# Primary routing table
1202
	learn;			# Learn alien routes from the kernel
1203
	persist;		# Don't remove routes on bird shutdown
1204
	scan time 10;		# Scan kernel routing table every 10 seconds
1205
	import all;
1206
	export all;
1207
}
1208

    
1209
protocol kernel {		# Secondary routing table
1210
	table auxtable;
1211
	kernel table 100;
1212
	export all;
1213
}
1214
</code>
1215

    
1216
<sect>OSPF
1217

    
1218
<sect1>Introduction
1219

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

    
1230
<p>In OSPF, the autonomous system can be split to several areas in order
1231
to reduce the amount of resources consumed for exchanging the routing
1232
information and to protect the other areas from incorrect routing data.
1233
Topology of the area is hidden to the rest of the autonomous system.
1234

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

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

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

    
1252
<sect1>Configuration
1253

    
1254
<p>In the main part of configuration, there can be multiple definitions of
1255
OSPF area witch different id included. These definitions includes many other
1256
switches and multiple definitions of interfaces. Definition of interface
1257
may contain many switches and constant definitions and list of neighbors
1258
on nonbroadcast networks.
1259

    
1260
<code>
1261
protocol ospf &lt;name&gt; {
1262
	rfc1583compat &lt;switch&gt;;
1263
	tick &lt;num&gt;;
1264
	area &lt;id&gt; {
1265
		stub cost &lt;num&gt;;
1266
                networks {
1267
			&lt;prefix&gt;;
1268
			&lt;prefix&gt; hidden;
1269
		}
1270
		stubnet &lt;prefix&gt;;
1271
		stubnet &lt;prefix&gt; {
1272
			hidden &lt;switch&gt;;
1273
			summary &lt;switch&gt;;
1274
			cost &lt;num&gt;;
1275
		}
1276
		interface &lt;interface pattern&gt; {
1277
			cost &lt;num&gt;;
1278
			stub &lt;switch&gt;;
1279
			hello &lt;num&gt;;
1280
			poll &lt;num&gt;;
1281
			retransmit &lt;num&gt;;
1282
			priority &lt;num&gt;;
1283
			wait &lt;num&gt;;
1284
			dead count &lt;num&gt;;
1285
			dead &lt;num&gt;;
1286
			rx buffer [normal|large|&lt;num&gt;];
1287
			type [broadcast|nonbroadcast|pointopoint];
1288
			strict nonbroadcast &lt;switch&gt;;
1289
			authentication [none|simple|cryptographics];
1290
			password "&lt;text&gt;";
1291
			password "&lt;text&gt;" {
1292
				id &lt;num&gt;;
1293
				generate from "&lt;date&gt;";
1294
				generate to "&lt;date&gt;";
1295
				accept from "&lt;date&gt;";
1296
				accept to "&lt;date&gt;";
1297
			};
1298
			neighbors {
1299
				&lt;ip&gt;;
1300
				&lt;ip&gt; eligible;
1301
			};
1302
		};
1303
		virtual link &lt;id&gt;	{
1304
			hello &lt;num&gt;;
1305
			retransmit &lt;num&gt;;
1306
			wait &lt;num&gt;;
1307
			dead count &lt;num&gt;;
1308
			dead &lt;num&gt;;
1309
			authentication [none|simple];
1310
			password "&lt;text&gt;";
1311
		};
1312
	};
1313
}
1314
</code>
1315

    
1316
<descrip>
1317
	<tag>rfc1583compat <M>switch</M></tag>
1318
	 This option controls compatibility of routing table
1319
	 calculation with RFC 1583<htmlurl
1320
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1321
	 value is no.
1322
	
1323
	<tag>area <M>id</M></tag>
1324
	 This defines an OSPF area with given area ID (an integer or an IPv4
1325
	 address, similarly to a router ID).
1326
	 The most important area is
1327
	 the backbone (ID 0) to which every other area must be connected.
1328

    
1329
	<tag>stub cost <M>num</M></tag>
1330
	 No external (except default) routes are flooded into stub areas.
1331
         Setting this value marks area stub with defined cost of default route.
1332
	 Default value is no. (Area is not stub.)
1333

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

    
1340
	<tag>networks { <m/set/ }</tag>
1341
         Definition of area IP ranges. This is used in summary lsa origination.
1342
	 Hidden networks are not propagated into other areas.
1343

    
1344
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
1345
	 Stub networks are networks that are not transit networks
1346
	 between OSPF routers. They are also propagated through an
1347
	 OSPF area as a part of a link state database. By default,
1348
	 BIRD generates a stub network record for each primary network
1349
	 address on each OSPF interface that does not have any OSPF
1350
	 neighbors, and also for each non-primary network address on
1351
	 each OSPF interface. This option allows to alter a set of
1352
	 stub networks propagated by this router. 
1353

    
1354
	 Each instance of this option adds a stub network with given
1355
	 network prefix to the set of propagated stub network, unless
1356
	 option <cf/hidden/ is used. It also suppresses default stub
1357
	 networks for given network prefix. When option
1358
	 <cf/summary/ is used, also default stub networks that are
1359
	 subnetworks of given stub network are suppressed. This might
1360
	 be used, for example, to aggregate generated stub networks.
1361
	 
1362
	<tag>interface <M>pattern</M></tag>
1363
	 Defines that the specified interfaces belong to the area being defined.
1364
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
1365

    
1366
	<tag>virtual link <M>id</M></tag>
1367
	 Virtual link to router with the router id. Virtual link acts as a
1368
         point-to-point interface belonging to backbone. The actual area is
1369
         used as transport area. This item cannot be in the backbone.
1370

    
1371
	<tag>cost <M>num</M></tag>
1372
	 Specifies output cost (metric) of an interface. Default value is 10.
1373

    
1374
	<tag>stub <M>switch</M></tag>
1375
	 If set to interface it does not listen to any packet and does not send
1376
	 any hello. Default value is no.
1377

    
1378
	<tag>hello <M>num</M></tag>
1379
	 Specifies interval in seconds between sending of Hello messages. Beware, all
1380
	 routers on the same network need to have the same hello interval.
1381
	 Default value is 10.
1382

    
1383
	<tag>poll <M>num</M></tag>
1384
	 Specifies interval in seconds between sending of Hello messages for
1385
	 some neighbors on NBMA network. Default value is 20.
1386

    
1387
	<tag>retransmit <M>num</M></tag>
1388
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
1389
	 Default value is 5.
1390

    
1391
        <tag>priority <M>num</M></tag>
1392
	 On every multiple access network (e.g., the Ethernet) Designed Router
1393
	 and Backup Designed router are elected. These routers have some
1394
	 special functions in the flooding process. Higher priority increases
1395
	 preferences in this election. Routers with priority 0 are not
1396
	 eligible. Default value is 1.
1397

    
1398
	<tag>wait <M>num</M></tag>
1399
	 After start, router waits for the specified number of seconds between starting
1400
	 election and building adjacency. Default value is 40.
1401
	 
1402
	<tag>dead count <M>num</M></tag>
1403
	 When the router does not receive any messages from a neighbor in
1404
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
1405

    
1406
	<tag>dead <M>num</M></tag>
1407
	 When the router does not receive any messages from a neighbor in
1408
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
1409
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
1410

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

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

    
1422
	<tag>type pointopoint</tag>
1423
	 Point-to-point networks connect just 2 routers together. No election
1424
	 is performed there which reduces the number of messages sent.
1425

    
1426
	<tag>type nonbroadcast</tag>
1427
	 On nonbroadcast networks, the packets are sent to each neighbor
1428
	 separately because of lack of multicast capabilities.
1429

    
1430
	<tag>strict nonbroadcast <M>switch</M></tag>
1431
	 If set, don't send hello to any undefined neighbor. This switch
1432
	 is ignored on on any non-NBMA network. Default is No.
1433

    
1434
	<tag>authentication none</tag>
1435
	 No passwords are sent in OSPF packets. This is the default value.
1436

    
1437
	<tag>authentication simple</tag>
1438
	 Every packet carries 8 bytes of password. Received packets
1439
	 lacking this password are ignored. This authentication mechanism is
1440
	 very weak.
1441

    
1442
	<tag>authentication cryptographic</tag>
1443
	 16-byte long MD5 digest is appended to every packet. For the digest
1444
         generation 16-byte long passwords are used. Those passwords are 
1445
         not sent via network, so this mechanismus is quite secure.
1446
         Packets can still be read by an attacker.
1447

    
1448
	<tag>password "<M>text</M>"</tag>
1449
	 An 8-byte or 16-byte password used for authentication.
1450
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
1451

    
1452
	<tag>neighbors { <m/set/ } </tag>
1453
	 A set of neighbors to which Hello messages on nonbroadcast networks
1454
	 are to be sent. Some of them could be marked as eligible.
1455

    
1456
</descrip>
1457

    
1458
<sect1>Attributes
1459

    
1460
<p>OSPF defines three route attributes. Each internal route has a <cf/metric/
1461
Metric is ranging from 1 to infinity (65535).
1462
External routes use <cf/metric type 1/ or <cf/metric type 2/.
1463
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
1464
<cf/metric of type 2/ is always longer
1465
than any <cf/metric of type 1/ or any <cf/internal metric/.
1466
If you specify both metrics only metric1 is used.
1467
Each external route can also carry a <cf/tag/ which is a 32-bit
1468
integer which is used when exporting routes to other protocols;
1469
otherwise, it doesn't affect routing inside the OSPF domain at all.
1470
Default is <cf/metric of type 2 = 10000/ and <cf/tag = 0/.
1471

    
1472
<sect1>Example
1473

    
1474
<p>
1475

    
1476
<code>
1477
protocol ospf MyOSPF {
1478
        rfc1583compatibility yes;
1479
        tick 2;
1480
	export filter {
1481
		if source = RTS_BGP then {
1482
			ospf_metric1 = 100;
1483
			accept;
1484
		}
1485
		reject;
1486
	};
1487
	area 0.0.0.0 {
1488
		interface "eth*" {
1489
			cost 11;
1490
			hello 15;
1491
			priority 100;
1492
			retransmit 7;
1493
			authentication simple;
1494
			password "aaa";
1495
		};
1496
		interface "ppp*" {
1497
			cost 100;
1498
			authentication cryptographic;
1499
			password "abc" {
1500
				id 1;
1501
				generate to "22-04-2003 11:00:06";
1502
				accept from "17-01-2001 12:01:05";
1503
			};
1504
			password "def" {
1505
				id 2;
1506
				generate to "22-07-2005 17:03:21";
1507
				accept from "22-02-2001 11:34:06";
1508
			};
1509
		};
1510
		interface "arc0" {
1511
			cost 10;
1512
			stub yes;
1513
		};
1514
		interface "arc1";
1515
	};
1516
	area 120 {
1517
		stub yes;
1518
		networks {
1519
			172.16.1.0/24;
1520
			172.16.2.0/24 hidden;
1521
		}
1522
		interface "-arc0" , "arc*" {
1523
			type nonbroadcast;
1524
			authentication none;
1525
			strict nonbroadcast yes;
1526
			wait 120;
1527
			poll 40;
1528
			dead count 8;
1529
			neighbors {
1530
				192.168.120.1 eligible;
1531
				192.168.120.2;
1532
				192.168.120.10;
1533
			};
1534
		};
1535
	};
1536
}
1537
</code>
1538

    
1539
<sect>Pipe
1540

    
1541
<sect1>Introduction
1542

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

    
1550
<p>The Pipe protocol may work in the opaque mode or in the transparent
1551
mode. In the opaque mode, the Pipe protocol retransmits optimal route
1552
from one table to the other table in a similar way like other
1553
protocols send and receive routes. Retransmitted route will have the
1554
source set to the Pipe protocol, which may limit access to protocol
1555
specific route attributes. The opaque mode is a default mode.
1556

    
1557
<p>In transparent mode, the Pipe protocol retransmits all routes from
1558
one table to the other table, retaining their original source and
1559
attributes.  If import and export filters are set to accept, then both
1560
tables would have the same content. The mode can be set by
1561
<tt/mode/ option.
1562

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

    
1574
<sect1>Configuration
1575

    
1576
<p><descrip>
1577
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
1578
	primary one is selected by the <cf/table/ keyword.
1579

    
1580
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
1581
</descrip>
1582

    
1583
<sect1>Attributes
1584

    
1585
<p>The Pipe protocol doesn't define any route attributes.
1586

    
1587
<sect1>Example
1588

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

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

    
1603
<code>
1604
table as1;				# Define the tables
1605
table as2;
1606

    
1607
protocol kernel kern1 {			# Synchronize them with the kernel
1608
	table as1;
1609
	kernel table 1;
1610
}
1611

    
1612
protocol kernel kern2 {
1613
	table as2;
1614
	kernel table 2;
1615
}
1616

    
1617
protocol bgp bgp1 {			# The outside connections
1618
	table as1;
1619
	local as 1;
1620
	neighbor 192.168.0.1 as 1001;
1621
	export all;
1622
	import all;
1623
}
1624

    
1625
protocol bgp bgp2 {
1626
	table as2;
1627
	local as 2;
1628
	neighbor 10.0.0.1 as 1002;
1629
	export all;
1630
	import all;
1631
}
1632

    
1633
protocol pipe {				# The Pipe
1634
	table as1;
1635
	peer table as2;
1636
	export filter {
1637
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
1638
			if preference>10 then preference = preference-10;
1639
			if source=RTS_BGP then bgp_path.prepend(1);
1640
			accept;
1641
		}
1642
		reject;
1643
	};
1644
	import filter {
1645
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
1646
			if preference>10 then preference = preference-10;
1647
			if source=RTS_BGP then bgp_path.prepend(2);
1648
			accept;
1649
		}
1650
		reject;
1651
	};
1652
}
1653
</code>
1654

    
1655
<sect>RIP
1656

    
1657
<sect1>Introduction
1658

    
1659
<p>The RIP protocol (also sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts (to all its neighbors)
1660
distances to all networks it can reach. When a router hears distance to another network, it increments
1661
it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes
1662
unreachable, routers keep telling each other that its distance is the original distance plus 1 (actually, plus
1663
interface metric, which is usually one). After some time, the distance reaches infinity (that's 15 in
1664
RIP) and all routers know that network is unreachable. RIP tries to minimize situations where
1665
counting to infinity is necessary, because it is slow. Due to infinity being 16, you can't use
1666
RIP on networks where maximal distance is higher than 15 hosts. You can read more about RIP at <HTMLURL
1667
URL="http://www.ietf.org/html.charters/rip-charter.html" name="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4  
1668
(RFC 1723<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1723.txt">)
1669
and IPv6 (RFC 2080<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2080.txt">) versions of RIP are supported by BIRD, historical RIPv1 (RFC 1058<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1058.txt">)is
1670
not currently supported. RIPv4 MD5 authentication (RFC 2082<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2082.txt">) is supported.
1671

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

    
1678
<sect1>Configuration
1679

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

    
1682
<descrip>
1683
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
1684
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
1685
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
1686
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
1687
	  section. Default: none.
1688

    
1689
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
1690
	  be honored. (Always, when sent from a  host on a directly connected
1691
	  network or never.) Routing table updates are honored only from
1692
	  neighbors, that is not configurable. Default: never.
1693
</descrip>
1694

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

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

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

    
1712
	<tag>infinity <M>number</M></tag>
1713
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
1714
	  even slower.
1715

    
1716
	<tag>period <M>number</M>
1717
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
1718
	  number will mean faster convergence but bigger network
1719
	  load. Do not use values lower than 10.
1720

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

    
1724
	<tag>garbage time <M>number</M>
1725
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
1726
</descrip>
1727

    
1728
<sect1>Attributes
1729

    
1730
<p>RIP defines two route attributes:
1731

    
1732
<descrip>
1733
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
1734
	When routes from different RIP instances are available and all of them have the same
1735
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
1736
	When importing a non-RIP route, the metric defaults to 5.
1737

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

    
1743
<sect1>Example
1744

    
1745
<p><code>
1746
protocol rip MyRIP_test {
1747
        debug all;
1748
        port 1520;
1749
        period 10;
1750
        garbage time 60;
1751
        interface "eth0" { metric 3; mode multicast; };
1752
	interface "eth*" { metric 2; mode broadcast; };
1753
        honor neighbor;
1754
        authentication none;
1755
        import filter { print "importing"; accept; };
1756
        export filter { print "exporting"; accept; };
1757
}
1758
</code>
1759

    
1760
<sect>Static
1761

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

    
1770
<p>There are three types of static routes: `classical' routes telling to
1771
forward packets to a neighboring router, device routes specifying forwarding
1772
to hosts on a directly connected network and special routes (sink, blackhole
1773
etc.) which specify a special action to be done instead of forwarding the
1774
packet.
1775

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

    
1781
<p>The Static protocol has no configuration options. Instead, the
1782
definition of the protocol contains a list of static routes:
1783

    
1784
<descrip>
1785
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
1786
	a neighboring router.
1787
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
1788
	route through an interface to hosts on a directly connected network.
1789
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
1790
	specifying to drop the packet, return it as unreachable or return
1791
	it as administratively prohibited.
1792
</descrip>
1793

    
1794
<p>Static routes have no specific attributes.
1795

    
1796
<p>Example static config might look like this:
1797

    
1798
<p><code>
1799
protocol static {
1800
	table testable;			 # Connect to a non-default routing table
1801
	route 0.0.0.0/0 via 62.168.0.13; # Default route
1802
	route 62.168.0.0/25 reject;	 # Sink route
1803
	route 10.2.0.0/24 via "arc0";	 # Secondary network
1804
}
1805
</code>
1806

    
1807
<chapt>Conclusions
1808

    
1809
<sect>Future work
1810

    
1811
<p>Although BIRD supports all the commonly used routing protocols,
1812
there are still some features which would surely deserve to be
1813
implemented in future versions of BIRD:
1814

    
1815
<itemize>
1816
<item>OSPF for IPv6 networks
1817
<item>OSPF NSSA areas and opaque LSA's
1818
<item>Route aggregation and flap dampening
1819
<item>Generation of IPv6 router advertisements
1820
<item>Multipath routes
1821
<item>Multicast routing protocols
1822
<item>Ports to other systems
1823
</itemize>
1824

    
1825
<sect>Getting more help
1826

    
1827
<p>If you use BIRD, you're welcome to join the bird-users mailing list
1828
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
1829
where you can share your experiences with the other users and consult
1830
your problems with the authors. To subscribe to the list, just send a
1831
<tt/subscribe bird-users/ command in a body of a mail to
1832
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
1833
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
1834

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

    
1842
<p>If you want to understand what is going inside, Internet standards are
1843
a good and interesting reading. You can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
1844

    
1845
<p><it/Good luck!/
1846

    
1847
</book>
1848

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