Statistics
| Branch: | Revision:

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

History | View | Annotate | Download (84.5 KB)

1
<!doctype birddoc system>
2

    
3
<!--
4
	BIRD documentation
5

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

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

    
14
    (set-fill-column 100)
15

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

    
18
 -->
19

    
20
<book>
21

    
22
<title>BIRD User's Guide
23
<author>
24
Ondrej Filip <it/&lt;feela@network.cz&gt;/,
25
Pavel Machek <it/&lt;pavel@ucw.cz&gt;/,
26
Martin Mares <it/&lt;mj@ucw.cz&gt;/,
27
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, OSPFv3)
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>-p</tag>
135
	just parse the config file and exit. Return value is zero if the config file is valid,
136
	nonzero if there are some errors.
137

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

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

    
144
<chapt>About routing tables
145

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

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

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

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

    
180
<chapt>Configuration
181

    
182
<sect>Introduction
183

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

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

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

    
199

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

    
207
protocol device {
208
	scan time 10;		# Scan interfaces every 10 seconds
209
}
210

    
211
protocol rip {
212
	export all;
213
	import all;
214
	interface "*";
215
}
216
</code>
217

    
218

    
219
<sect>Global options
220

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

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

    
236
	<tag>debug commands <m/number/</tag>
237
	Control logging of client connections (0 for no logging, 1 for
238
	logging of connects and disconnects, 2 and higher for logging of
239
	all client commands). Default: 0.
240

    
241
	<tag>mrtdump "<m/filename/"</tag>
242
	Set MRTdump file name. This option must be specified to allow MRTdump feature.
243
	Default: no dump file.
244

    
245
	<tag>mrtdump protocols all|off|{ states, messages }</tag>
246
	Set global defaults of MRTdump options. See <cf/mrtdump/ in the following section.
247
	Default: off.
248

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

    
252
	<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
253
	about functions in the following chapter.
254
 
255
	<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
256
	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
257
	about configuring protocols in their own chapters. You can run more than one instance of
258
	most protocols (like RIP or BGP). By default, no instances are configured.
259

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

    
263
	<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. 
264

    
265
	<tag>listen bgp [address <m/address/] [port <m/port/] [v6only]</tag>
266
	This option allows to specify address and port where BGP
267
	protocol should listen. It is global option as listening
268
	socket is common to all BGP instances. Default is to listen on
269
	all addresses (0.0.0.0) and port 179. In IPv6 mode, option
270
	<cf/v6only/ can be used to specify that BGP socket should
271
	listen to IPv6 connections only. This is needed if you want to
272
	run both bird and bird6 on the same port.
273

    
274
	<tag>table <m/name/</tag> Create a new routing table. The default
275
	routing table is created implicitly, other routing tables have
276
	to be added by this command.
277

    
278
	<tag>eval <m/expr/</tag> Evaluates given filter expression. It
279
	is used by us for testing of filters.
280
</descrip>
281

    
282
<sect>Protocol options
283

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

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

    
294
<descrip>
295
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
296

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

    
300
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
301
	Set protocol debugging options. If asked, each protocol is capable of
302
	writing trace messages about its work to the log (with category
303
	<cf/trace/). You can either request printing of <cf/all/ trace messages
304
	or only of the types selected: <cf/states/ for protocol state changes
305
	(protocol going up, down, starting, stopping etc.),
306
	<cf/routes/ for routes exchanged with the routing table,
307
	<cf/filters/ for details on route filtering,
308
	<cf/interfaces/ for interface change events sent to the protocol,
309
	<cf/events/ for events internal to the protocol and
310
	<cf/packets/ for packets sent and received by the protocol. Default: off.
311

    
312
	<tag>mrtdump all|off|{ states, messages }</tag>
313

    
314
	Set protocol MRTdump flags. MRTdump is a standard binary
315
	format for logging information from routing protocols and
316
	daemons.  These flags control what kind of information is
317
	logged from the protocol to the MRTdump file (which must be
318
	specified by global <cf/mrtdump/ option, see the previous
319
	section). Although these flags are similar to flags of
320
	<cf/debug/ option, their meaning is different and
321
	protocol-specific. For BGP protocol, <cf/states/ logs BGP
322
	state changes and <cf/messages/ logs received BGP messages.
323
	Other protocols does not support MRTdump yet.
324

    
325
	<tag>router id <m/IPv4 address/</tag> This option can be used
326
	to override global router id for a given protocol. Default:
327
	uses global router id.
328

    
329
	<tag>import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag> 
330
	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/.
331

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

    
335
	<tag>description "<m/text/"</tag> This is an optional
336
	description of the protocol. It is displayed as a part of the
337
	output of 'show route all' command.
338

    
339
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
340
</descrip>
341

    
342
<p>There are several options that give sense only with certain protocols:
343

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

    
347
	Specifies a set of interfaces on which the protocol is activated with
348
	given interface-specific options. A set of interfaces specified by one
349
	interface option is described using an interface pattern. The
350
	interface pattern consists of a sequence of clauses (separated by
351
	commas), each clause may contain a mask, a prefix, or both of them. An
352
	interface matches the clause if its name matches the mask (if
353
	specified) and its address matches the prefix (if specified). Mask is
354
	specified as shell-like pattern.
355

    
356
	An interface matches the pattern if it matches any of its
357
	clauses. If the clause begins with <cf/-/, matching interfaces are
358
	excluded. Patterns are parsed left-to-right, thus
359
	<cf/interface "eth0", -"eth*", "*";/ means eth0 and all
360
	non-ethernets.
361

    
362
	An interface option can be used more times with different
363
	interfaces-specific options, in that case for given interface
364
	the first matching interface option is used.
365
	
366
	This option is allowed in Direct, OSPF and RIP protocols,
367
	but in OSPF protocol it is used in <cf/area/ subsection.
368

    
369
	Default: none.
370

    
371
	Examples:
372

    
373
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
374
	<cf>type broadcast</cf> option.
375

    
376
	<cf>interface "eth1", "eth4", "eth5" { type pointopoint; };</cf> - start the protocol
377
	on enumerated interfaces with <cf>type pointopoint</cf> option.
378
	
379
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
380
	interfaces that have address from 192.168.0.0/16, but not
381
	from 192.168.1.0/24.
382

    
383
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
384
	interfaces that have address from 192.168.0.0/16, but not
385
	from 192.168.1.0/24.
386

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

    
390
	<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>
391
	Specifies a password that can be used by the protocol. Password option can
392
	be used more times to specify more passwords. If more passwords are
393
	specified, it is a protocol-dependent decision which one is really
394
	used. Specifying passwords does not mean that authentication is
395
	enabled, authentication can be enabled by separate, protocol-dependent
396
	<cf/authentication/ option.
397
	
398
	This option is allowed in OSPF and RIP protocols. BGP has also
399
	<cf/password/ option, but it is slightly different and described
400
	separately.
401

    
402
	Default: none.
403
</descrip>
404

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

    
407
<descrip>
408
	<tag>id <M>num</M></tag>
409
	 ID of the password, (0-255). If it's not used, BIRD will choose
410
	 ID based on an order of the password item in the interface. For
411
	 example, second password item in one interface will have default
412
	 ID 2. ID is used by some routing protocols to identify which
413
	 password was used to authenticate protocol packets.
414

    
415
	<tag>generate from "<m/time/"</tag>
416
	 The start time of the usage of the password for packet signing.
417
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
418

    
419
	<tag>generate to "<m/time/"</tag>
420
	 The last time of the usage of the password for packet signing.
421

    
422
	<tag>accept from "<m/time/"</tag>
423
	 The start time of the usage of the password for packet verification.
424

    
425
	<tag>accept to "<m/time/"</tag>
426
	 The last time of the usage of the password for packet verification.
427
</descrip>
428

    
429
<chapt>Remote control
430

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

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

    
446
<p>Here is a brief list of supported functions:
447

    
448
<descrip>
449
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
450
	Dump contents of internal data structures to the debugging output.
451

    
452
	<tag>show status</tag>
453
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
454

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

    
458
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
459
	Show detailed information about OSPF interfaces.
460

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

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

    
468
	<tag>show ospf topology [<m/name/]</tag>
469
	Show a topology of OSPF areas based on a content of link-state database.
470
	It is just a stripped-down version of 'show ospf state'.
471

    
472
	<tag>show static [<m/name/]</tag>
473
	Show detailed information about static routes.
474

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

    
478
	<tag>show symbols</tag>
479
	Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
480

    
481
	<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>
482
	Show contents of a routing table (by default of the main one),
483
	that is routes, their metrics and (in case the <cf/all/ switch is given)
484
	all their attributes.
485

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

    
493
	<p>You can also ask for printing only routes processed and accepted by
494
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
495
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
496
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
497
	that are exported to the specified protocol. With <cf/preexport/, the
498
	export filter of the protocol is skipped.
499

    
500
	<p>You can also select just routes added by a specific protocol.
501
	<cf>protocol <m/p/</cf>.
502

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

    
507
	<tag>configure [soft] ["<m/config file/"]</tag>
508
	Reload configuration from a given file. BIRD will smoothly
509
	switch itself to the new configuration, protocols are
510
	reconfigured if possible, restarted otherwise. Changes in
511
	filters usually lead to restart of affected protocols. If
512
	<cf/soft/ option is used, changes in filters does not cause
513
	BIRD to restart affected protocols, therefore already accepted
514
	routes (according to old filters) would be still propagated,
515
	but new routes would be processed according to the new
516
	filters.
517

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

    
521
	<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
522
	
523
	Reload a given protocol instance, that means re-import routes
524
	from the protocol instance and re-export preferred routes to
525
	the instance. If <cf/in/ or <cf/out/ options are used, the
526
	command is restricted to one direction (re-import or
527
	re-export).
528

    
529
	This command is useful if appropriate filters have changed but
530
	the protocol instance was not restarted (or reloaded),
531
	therefore it still propagates the old set of routes. For example
532
	when <cf/configure soft/ command was used to change filters.
533

    
534
	Re-export always succeeds, but re-import is protocol-dependent
535
	and might fail (for example, if BGP neighbor does not support
536
	route-refresh extension). In that case, re-export is also
537
	skipped. Note that for the pipe protocol, both directions are
538
	always reloaded together (<cf/in/ or <cf/out/ options are
539
	ignored in that case).
540

    
541
	<tag/down/
542
	Shut BIRD down.
543

    
544
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
545
	Control protocol debugging.
546
</descrip>
547

    
548
<chapt>Filters
549

    
550
<sect>Introduction
551

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

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

    
562
<code>
563
filter not_too_far
564
int var;
565
{
566
	if defined( rip_metric ) then
567
		var = rip_metric;
568
	else {
569
		var = 1;
570
		rip_metric = 1;
571
	}
572
	if rip_metric &gt; 10 then
573
		reject "RIP metric is too big";
574
	else
575
		accept "ok";
576
}
577
</code>
578

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

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

    
590
<code>
591
function name ()
592
int local_variable;
593
{
594
	local_variable = 5;
595
}
596

    
597
function with_parameters (int parameter)
598
{
599
	print parameter;
600
}
601
</code>
602

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

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

    
614
<p>A nice trick to debug filters is to use <cf>show route filter
615
<m/name/</cf> from the command line client. An example session might look
616
like:
617

    
618
<code>
619
pavel@bug:~/bird$ ./birdc -s bird.ctl
620
BIRD 0.0.0 ready.
621
bird> show route
622
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
623
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
624
127.0.0.0/8        dev lo [direct1 23:21] (240)
625
bird> show route ?
626
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
627
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
628
127.0.0.0/8        dev lo [direct1 23:21] (240)
629
bird>
630
</code>
631

    
632
<sect>Data types
633

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

    
637
<descrip>
638
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
639
	  <cf/false/. Boolean is the only type you can use in <cf/if/
640
	  statements.
641

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

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

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

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

    
659
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
660
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
661
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
662
	  operators on prefixes:
663
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
664
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
665

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

    
672
	  Sets of prefixes are special: their literals does not allow ranges, but allows
673
	  prefix patterns that are written as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
674
	  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 
675
	  the first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are identical and <cf>len1 &lt;= ip1 &lt;= len2</cf>.
676
	  A valid prefix pattern has to satisfy <cf>low &lt;= high</cf>, but <cf/pxlen/ is not constrained by <cf/low/
677
	  or <cf/high/. Obviously, a prefix matches a prefix set literal iff it matches any prefix pattern in the
678
	  prefix set literal.
679

    
680
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
681
	  <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), 
682
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
683
	  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>
684
	  and all its supernets (network prefixes that contain it).
685

    
686
	  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
687
	  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
688
	  <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
689
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
690
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
691
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
692

    
693
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
694
	  in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
695
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
696
	  <cf>192.168.0.0/16{24,32}</cf>.
697

    
698
	<tag/enum/
699
	  Enumeration types are fixed sets of possibilities. You can't define your own
700
	  variables of such type, but some route attributes are of enumeration
701
	  type. Enumeration types are incompatible with each other.
702

    
703
	<tag/bgppath/
704
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
705
	  There are several special operators on bgppaths:
706

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

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

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

    
714
          <cf><m/P/.len</cf> returns the length of path <m/P/.
715

    
716
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
717
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
718
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
719
          (for example <cf/bgp_path/).
720

    
721
	<tag/bgpmask/
722
	  BGP masks are patterns used for BGP path matching
723
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
724
	  resemble wildcard patterns as used by UNIX shells. Autonomous
725
	  system numbers match themselves, <cf/*/ matches any (even empty)
726
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
727
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
728
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
729
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
730
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
731
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
732
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
733

    
734
	<tag/clist/ 
735
	  Community list is similar to set of pairs,
736
	  except that unlike other sets, it can be modified.
737
	  There exist no literals of this type.
738
	  There are two special operators on clists:
739

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

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

    
744
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
745
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute
746
          (for example <cf/bgp_community/). Similarly for <cf/delete/.
747

    
748
</descrip>
749

    
750
<sect>Operators
751

    
752
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
753
<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;/). 
754
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
755
used on element and set of elements of the same type (returning true if element is contained in the given set), or
756
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
757
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).
758

    
759

    
760
<sect>Control structures
761

    
762
<p>Filters support two control structures: conditions and case switches. 
763

    
764
<p>Syntax of a condition is: <cf>if
765
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
766
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
767
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.
768

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

    
775
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
776

    
777
<code>
778
case arg1 {
779
	2: print "two"; print "I can do more commands without {}";
780
	3 .. 5: print "three to five";
781
	else: print "something else";
782
}
783

    
784
if 1234 = i then printn "."; else { 
785
  print "not 1234"; 
786
  print "You need {} around multiple commands"; 
787
}
788
</code>
789

    
790
<sect>Route attributes
791

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

    
797
<descrip>
798
	<tag><m/prefix/ net</tag>
799
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
800

    
801
	<tag><m/enum/ scope</tag>
802
	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).
803

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

    
807
	<tag><m/ip/ from</tag>
808
	The router which the route has originated from. Read-only.
809
	
810
	<tag><m/ip/ gw</tag>
811
	Next hop packets routed using this route should be forwarded to.
812

    
813
	<tag><m/string/ proto</tag>
814
	The name of the protocol which the route has been imported from. Read-only.
815

    
816
	<tag><m/enum/ source</tag>
817
	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/.
818

    
819
	<tag><m/enum/ cast</tag>
820
	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.
821

    
822
	<tag><m/enum/ dest</tag>
823
	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.
824
</descrip>
825

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

    
828
<sect>Other statements
829

    
830
<p>The following statements are available:
831

    
832
<descrip>
833
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
834

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

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

    
839
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
840
	Prints given expressions; useful mainly while debugging
841
	filters. The <cf/printn/ variant does not terminate the line.
842

    
843
	<tag>quitbird</tag>
844
	Terminates BIRD. Useful when debugging the filter interpreter.
845
</descrip>
846

    
847
<chapt>Protocols
848

    
849
<sect>BGP
850

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

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

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

    
870
<p>BIRD supports all requirements of the BGP4 standard as defined in
871
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
872
It also supports the community attributes
873
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
874
capability negotiation
875
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
876
MD5 password authentication
877
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
878
route reflectors 
879
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
880
multiprotocol extensions
881
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
882
and 4B AS numbers 
883
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">).
884

    
885

    
886
For IPv6, it uses the standard multiprotocol extensions defined in
887
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
888
including changes described in the
889
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
890
and applied to IPv6 according to
891
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
892

    
893
<sect1>Route selection rules
894

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

    
901
<itemize>
902
	<item>Prefer route with the highest Local Preference attribute.
903
	<item>Prefer route with the shortest AS path.
904
	<item>Prefer IGP origin over EGP and EGP over incomplete.
905
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
906
	<item>Prefer internal routes over external ones.
907
	<item>Prefer the route with the lowest value of router ID of the
908
	advertising router.
909
</itemize>
910

    
911
<sect1>Configuration
912

    
913
<p>Each instance of the BGP corresponds to one neighboring router.
914
This allows to set routing policy and all the other parameters differently
915
for each neighbor using the following configuration parameters:
916

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

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

    
930
	<tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a
931
	neighbor which is connected at most <m/number/ hops far and to which
932
	we should route via our direct neighbor with address <m/ip/.
933
	Default: switched off.
934

    
935
	<tag>next hop self</tag> Avoid calculation of the Next Hop
936
	attribute and always advertise our own source address (see
937
	below) as a next hop.  This needs to be used only occasionally
938
	to circumvent misconfigurations of other routers.
939
	Default: disabled.
940

    
941
	<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
942
	in BGP-IPv6 sometimes contains just the global IPv6 address,
943
	but sometimes it has to contain both global and link-local
944
	IPv6 addresses. This option specifies what to do if BIRD have
945
	to send both addresses but does not know link-local address.
946
	This situation might happen when routes from other protocols
947
	are exported to BGP, or when improper updates are received
948
	from BGP peers.  <cf/self/ means that BIRD advertises its own
949
	local address instead. <cf/drop/ means that BIRD skips that
950
	prefixes and logs error. <cf/ignore/ means that BIRD ignores
951
	the problem and sends just the global address (and therefore
952
	forms improper BGP update). Default: <cf/self/, unless BIRD
953
	is configured as a route server (option <cf/rs client/), in
954
	that case default is <cf/drop/, because route servers usually
955
	does not forward packets ifselves.
956
	
957
	<tag>source address <m/ip/</tag> Define local address we should use
958
	for next hop calculation. Default: the address of the local end
959
	of the interface our neighbor is connected to.
960

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

    
965
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
966
        initiating outgoing connections and accepting incoming
967
        connections. In passive mode, outgoing connections are not
968
        initiated. Default: off.
969

    
970
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
971
	a route reflection client. Default: disabled.
972

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

    
980
	<tag>rs client</tag> Be a route server and treat the neighbor
981
	as a route server client. A route server is used as a
982
	replacement for full mesh EBGP routing in Internet exchange
983
	points in a similar way to route reflectors used in IBGP routing.
984
	BIRD does not implement obsoleted RFC 1863, but uses ad-hoc implementation,
985
	which behaves like plain EBGP but reduces modifications to advertised route
986
	attributes to be transparent (for example does not prepend its AS number to
987
	AS PATH attribute and keep MED attribute). Default: disabled.
988

    
989
	<tag>enable route refresh <m/switch/</tag> When BGP speaker
990
	changes its import filter, it has to re-examine all routes
991
	received from its neighbor against the new filter. As these
992
	routes might not be available, there is a BGP protocol
993
	extension Route Refresh (specified in RFC 2918) that allows
994
	BGP speaker to request re-advertisement of all routes from its
995
	neighbor. This option specifies whether BIRD advertises this
996
	capability and accepts such requests. Even when disabled, BIRD
997
	can send route refresh requests. Default: on.
998

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

    
1007
	<tag>capabilities <m/switch/</tag> Use capability advertisement
1008
	to advertise optional capabilities. This is standard behavior
1009
	for newer BGP implementations, but there might be some older
1010
	BGP implementations that reject such connection attempts.
1011
	When disabled (off), features that request it (4B AS support)
1012
	are also disabled. Default: on, with automatic fallback to
1013
	off when received capability-related error.
1014

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

    
1021
	<tag>route limit <m/number/</tag> The maximal number of routes
1022
	that may be imported from the protocol. If the route limit is
1023
	exceeded, the connection is closed with error. Default: no limit.
1024

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

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

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

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

    
1041
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
1042
	retrying a failed attempt to connect. Default: 120 seconds.
1043

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

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

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

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

    
1059
	<tag>prefer older <m/switch/</tag> Standard route selection algorithm
1060
	breaks ties by comparing router IDs. This changes the behavior
1061
	to prefer older routes (when both are external and from different
1062
	peer). For details, see RFC 5004. Default: off.
1063

    
1064
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
1065
	Discriminator to be used during route selection when the MED attribute
1066
	is missing. Default: 0.
1067

    
1068
	<tag>default bgp_local_pref <m/number/</tag> A default value
1069
	for the Local Preference attribute. It is used when a new
1070
	Local Preference attribute is attached to a route by the BGP
1071
	protocol itself (for example, if a route is received through
1072
	eBGP and therefore does not have such attribute). Default: 100
1073
	(0 in pre-1.2.0 versions of BIRD).
1074
</descrip>
1075

    
1076
<sect1>Attributes
1077

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

    
1082
<descrip>
1083
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1084
	the packet will travel through when forwarded according to the particular route. In case of 
1085
	internal BGP it doesn't contain the number of the local AS.
1086

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

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

    
1102
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1103
	if the route has originated in an interior routing protocol or
1104
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1105
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1106
	is unknown.
1107

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

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

    
1120
<!-- we don't handle aggregators right since they are of a very obscure type
1121
	<tag>bgp_aggregator</tag>
1122
-->
1123
	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
1124
	with the route. Each such value is a pair (represented as a <cf/pair/ data
1125
	type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
1126
	the community and the second one being a per-AS identifier. There are lots
1127
	of uses of the community mechanism, but generally they are used to carry
1128
	policy information like "don't export to USA peers". As each AS can define
1129
	its own routing policy, it also has a complete freedom about which community
1130
	attributes it defines and what will their semantics be.
1131
</descrip>
1132

    
1133
<sect1>Example
1134

    
1135
<p><code>
1136
protocol bgp {
1137
	local as 65000;			     # Use a private AS number
1138
	neighbor 62.168.0.130 as 5588;	     # Our neighbor ...
1139
	multihop 20 via 62.168.0.13;	     # ... which is connected indirectly
1140
	export filter {			     # We use non-trivial export rules
1141
		if source = RTS_STATIC then { # Export only static routes
1142
		        # Assign our community
1143
			bgp_community.add((65000,5678));
1144
			# Artificially increase path length
1145
			# by advertising local AS number twice
1146
			if bgp_path ~ [= 65000 =] then	  
1147
				bgp_path.prepend(65000);  
1148
			accept;
1149
		}
1150
		reject;
1151
	};
1152
	import all;
1153
	source address 62.168.0.1;	# Use a non-standard source address
1154
}
1155
</code>
1156

    
1157
<sect>Device
1158

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

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

    
1167
<sect1>Configuration
1168

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

    
1176
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1177
	If a network interface has more than one network address,
1178
	BIRD has to choose one of them as a primary one, because some
1179
	routing protocols (for example OSPFv2) suppose there is only
1180
	one network address per interface. By default, BIRD chooses
1181
	the lexicographically smallest address as the primary one.
1182

    
1183
	This option allows to specify which network address should be
1184
	chosen as a primary one. Network addresses that match
1185
	<m/prefix/ are preferred to non-matching addresses. If more
1186
	<cf/primary/ options are used, the first one has the highest
1187
	preference. If "<m/mask/" is specified, then such
1188
	<cf/primary/ option is relevant only to matching network
1189
	interfaces.
1190

    
1191
	In all cases, an address marked by operating system as
1192
	secondary cannot be chosen as the primary one. 
1193
</descrip>
1194

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

    
1198
<p><code>
1199
protocol device {
1200
	scan time 10;		# Scan the interfaces often
1201
	primary "eth0" 192.168.1.1;
1202
	primary 192.168.0.0/16;
1203
}
1204
</code>
1205

    
1206
<sect>Direct
1207

    
1208
<p>The Direct protocol is a simple generator of device routes for all the
1209
directly connected networks according to the list of interfaces provided
1210
by the kernel via the Device protocol.
1211

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

    
1217
<p>The only configurable thing about direct is what interfaces it watches:
1218

    
1219
<p><descrip>
1220
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
1221
	protocol will generate device routes for all the interfaces
1222
	available. If you want to restrict it to some subset of interfaces
1223
	(for example if you're using multiple routing tables for policy
1224
	routing and some of the policy domains don't contain all interfaces),
1225
	just use this clause.
1226
</descrip>
1227

    
1228
<p>Direct device routes don't contain any specific attributes.
1229

    
1230
<p>Example config might look like this:
1231

    
1232
<p><code>
1233
protocol direct {
1234
	interface "-arc*", "*";		# Exclude the ARCnets
1235
}
1236
</code>
1237

    
1238
<sect>Kernel
1239

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

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

    
1255
<sect1>Configuration
1256

    
1257
<p><descrip>
1258
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1259
	routing tables when it exits (instead of cleaning them up).
1260
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1261
	kernel routing table.
1262
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1263
	routing tables by other routing daemons or by the system administrator.
1264
	This is possible only on systems which support identification of route
1265
	authorship.
1266
	<tag>kernel table <m/number/</tag> Select which kernel table should
1267
	this particular instance of the Kernel protocol work with. Available
1268
	only on systems supporting multiple routing tables.
1269
</descrip>
1270

    
1271
<p>The Kernel protocol doesn't define any route attributes.
1272
<p>A simple configuration can look this way:
1273

    
1274
<p><code>
1275
protocol kernel {
1276
	import all;
1277
	export all;
1278
}
1279
</code>
1280

    
1281
<p>Or for a system with two routing tables:
1282

    
1283
<p><code>
1284
protocol kernel {		# Primary routing table
1285
	learn;			# Learn alien routes from the kernel
1286
	persist;		# Don't remove routes on bird shutdown
1287
	scan time 10;		# Scan kernel routing table every 10 seconds
1288
	import all;
1289
	export all;
1290
}
1291

    
1292
protocol kernel {		# Secondary routing table
1293
	table auxtable;
1294
	kernel table 100;
1295
	export all;
1296
}
1297
</code>
1298

    
1299
<sect>OSPF
1300

    
1301
<sect1>Introduction
1302

    
1303
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
1304
protocol. The current IPv4 version (OSPFv2) is defined in RFC
1305
2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> and
1306
the current IPv6 version (OSPFv3) is defined in RFC 5340<htmlurl
1307
url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt">  It's a link state
1308
(a.k.a. shortest path first) protocol -- each router maintains a
1309
database describing the autonomous system's topology. Each participating
1310
router has an identical copy of the database and all routers run the
1311
same algorithm calculating a shortest path tree with themselves as a
1312
root. OSPF chooses the least cost path as the best path.
1313

    
1314
<p>In OSPF, the autonomous system can be split to several areas in order
1315
to reduce the amount of resources consumed for exchanging the routing
1316
information and to protect the other areas from incorrect routing data.
1317
Topology of the area is hidden to the rest of the autonomous system.
1318

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

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

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

    
1336
<sect1>Configuration
1337

    
1338
<p>In the main part of configuration, there can be multiple definitions of
1339
OSPF area witch different id included. These definitions includes many other
1340
switches and multiple definitions of interfaces. Definition of interface
1341
may contain many switches and constant definitions and list of neighbors
1342
on nonbroadcast networks.
1343

    
1344
<code>
1345
protocol ospf &lt;name&gt; {
1346
	rfc1583compat &lt;switch&gt;;
1347
	tick &lt;num&gt;;
1348
	area &lt;id&gt; {
1349
		stub cost &lt;num&gt;;
1350
                networks {
1351
			&lt;prefix&gt;;
1352
			&lt;prefix&gt; hidden;
1353
		}
1354
		stubnet &lt;prefix&gt;;
1355
		stubnet &lt;prefix&gt; {
1356
			hidden &lt;switch&gt;;
1357
			summary &lt;switch&gt;;
1358
			cost &lt;num&gt;;
1359
		}
1360
		interface &lt;interface pattern&gt; {
1361
			cost &lt;num&gt;;
1362
			stub &lt;switch&gt;;
1363
			hello &lt;num&gt;;
1364
			poll &lt;num&gt;;
1365
			retransmit &lt;num&gt;;
1366
			priority &lt;num&gt;;
1367
			wait &lt;num&gt;;
1368
			dead count &lt;num&gt;;
1369
			dead &lt;num&gt;;
1370
			rx buffer [normal|large|&lt;num&gt;];
1371
			type [broadcast|nonbroadcast|pointopoint];
1372
			strict nonbroadcast &lt;switch&gt;;
1373
			authentication [none|simple|cryptographics];
1374
			password "&lt;text&gt;";
1375
			password "&lt;text&gt;" {
1376
				id &lt;num&gt;;
1377
				generate from "&lt;date&gt;";
1378
				generate to "&lt;date&gt;";
1379
				accept from "&lt;date&gt;";
1380
				accept to "&lt;date&gt;";
1381
			};
1382
			neighbors {
1383
				&lt;ip&gt;;
1384
				&lt;ip&gt; eligible;
1385
			};
1386
		};
1387
		virtual link &lt;id&gt;	{
1388
			hello &lt;num&gt;;
1389
			retransmit &lt;num&gt;;
1390
			wait &lt;num&gt;;
1391
			dead count &lt;num&gt;;
1392
			dead &lt;num&gt;;
1393
			authentication [none|simple];
1394
			password "&lt;text&gt;";
1395
		};
1396
	};
1397
}
1398
</code>
1399

    
1400
<descrip>
1401
	<tag>rfc1583compat <M>switch</M></tag>
1402
	 This option controls compatibility of routing table
1403
	 calculation with RFC 1583<htmlurl
1404
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1405
	 value is no.
1406
	
1407
	<tag>area <M>id</M></tag>
1408
	 This defines an OSPF area with given area ID (an integer or an IPv4
1409
	 address, similarly to a router ID).
1410
	 The most important area is
1411
	 the backbone (ID 0) to which every other area must be connected.
1412

    
1413
	<tag>stub cost <M>num</M></tag>
1414
	 No external (except default) routes are flooded into stub areas.
1415
         Setting this value marks area stub with defined cost of default route.
1416
	 Default value is no. (Area is not stub.)
1417

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

    
1424
	<tag>networks { <m/set/ }</tag>
1425
         Definition of area IP ranges. This is used in summary LSA origination.
1426
	 Hidden networks are not propagated into other areas.
1427

    
1428
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
1429
	 Stub networks are networks that are not transit networks
1430
	 between OSPF routers. They are also propagated through an
1431
	 OSPF area as a part of a link state database. By default,
1432
	 BIRD generates a stub network record for each primary network
1433
	 address on each OSPF interface that does not have any OSPF
1434
	 neighbors, and also for each non-primary network address on
1435
	 each OSPF interface. This option allows to alter a set of
1436
	 stub networks propagated by this router. 
1437

    
1438
	 Each instance of this option adds a stub network with given
1439
	 network prefix to the set of propagated stub network, unless
1440
	 option <cf/hidden/ is used. It also suppresses default stub
1441
	 networks for given network prefix. When option
1442
	 <cf/summary/ is used, also default stub networks that are
1443
	 subnetworks of given stub network are suppressed. This might
1444
	 be used, for example, to aggregate generated stub networks.
1445
	 
1446
	<tag>interface <M>pattern</M></tag>
1447
	 Defines that the specified interfaces belong to the area being defined.
1448
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
1449

    
1450
	<tag>virtual link <M>id</M></tag>
1451
	 Virtual link to router with the router id. Virtual link acts as a
1452
         point-to-point interface belonging to backbone. The actual area is
1453
         used as transport area. This item cannot be in the backbone.
1454

    
1455
	<tag>cost <M>num</M></tag>
1456
	 Specifies output cost (metric) of an interface. Default value is 10.
1457

    
1458
	<tag>stub <M>switch</M></tag>
1459
	 If set to interface it does not listen to any packet and does not send
1460
	 any hello. Default value is no.
1461

    
1462
	<tag>hello <M>num</M></tag>
1463
	 Specifies interval in seconds between sending of Hello messages. Beware, all
1464
	 routers on the same network need to have the same hello interval.
1465
	 Default value is 10.
1466

    
1467
	<tag>poll <M>num</M></tag>
1468
	 Specifies interval in seconds between sending of Hello messages for
1469
	 some neighbors on NBMA network. Default value is 20.
1470

    
1471
	<tag>retransmit <M>num</M></tag>
1472
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
1473
	 Default value is 5.
1474

    
1475
        <tag>priority <M>num</M></tag>
1476
	 On every multiple access network (e.g., the Ethernet) Designed Router
1477
	 and Backup Designed router are elected. These routers have some
1478
	 special functions in the flooding process. Higher priority increases
1479
	 preferences in this election. Routers with priority 0 are not
1480
	 eligible. Default value is 1.
1481

    
1482
	<tag>wait <M>num</M></tag>
1483
	 After start, router waits for the specified number of seconds between starting
1484
	 election and building adjacency. Default value is 40.
1485
	 
1486
	<tag>dead count <M>num</M></tag>
1487
	 When the router does not receive any messages from a neighbor in
1488
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
1489

    
1490
	<tag>dead <M>num</M></tag>
1491
	 When the router does not receive any messages from a neighbor in
1492
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
1493
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
1494

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

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

    
1506
	<tag>type pointopoint</tag>
1507
	 Point-to-point networks connect just 2 routers together. No election
1508
	 is performed there which reduces the number of messages sent.
1509

    
1510
	<tag>type nonbroadcast</tag>
1511
	 On nonbroadcast networks, the packets are sent to each neighbor
1512
	 separately because of lack of multicast capabilities.
1513

    
1514
	<tag>strict nonbroadcast <M>switch</M></tag>
1515
	 If set, don't send hello to any undefined neighbor. This switch
1516
	 is ignored on on any non-NBMA network. Default is No.
1517

    
1518
	<tag>authentication none</tag>
1519
	 No passwords are sent in OSPF packets. This is the default value.
1520

    
1521
	<tag>authentication simple</tag>
1522
	 Every packet carries 8 bytes of password. Received packets
1523
	 lacking this password are ignored. This authentication mechanism is
1524
	 very weak.
1525

    
1526
	<tag>authentication cryptographic</tag>
1527
	 16-byte long MD5 digest is appended to every packet. For the digest
1528
         generation 16-byte long passwords are used. Those passwords are 
1529
         not sent via network, so this mechanism is quite secure.
1530
         Packets can still be read by an attacker.
1531

    
1532
	<tag>password "<M>text</M>"</tag>
1533
	 An 8-byte or 16-byte password used for authentication.
1534
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
1535

    
1536
	<tag>neighbors { <m/set/ } </tag>
1537
	 A set of neighbors to which Hello messages on nonbroadcast networks
1538
	 are to be sent. Some of them could be marked as eligible.
1539

    
1540
</descrip>
1541

    
1542
<sect1>Attributes
1543

    
1544
<p>OSPF defines three route attributes. Each internal route has a <cf/metric/
1545
Metric is ranging from 1 to infinity (65535).
1546
External routes use <cf/metric type 1/ or <cf/metric type 2/.
1547
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
1548
<cf/metric of type 2/ is always longer
1549
than any <cf/metric of type 1/ or any <cf/internal metric/.
1550
If you specify both metrics only metric1 is used.
1551
Each external route can also carry a <cf/tag/ which is a 32-bit
1552
integer which is used when exporting routes to other protocols;
1553
otherwise, it doesn't affect routing inside the OSPF domain at all.
1554
Default is <cf/metric of type 2 = 10000/ and <cf/tag = 0/.
1555

    
1556
<sect1>Example
1557

    
1558
<p>
1559

    
1560
<code>
1561
protocol ospf MyOSPF {
1562
        rfc1583compat yes;
1563
        tick 2;
1564
	export filter {
1565
		if source = RTS_BGP then {
1566
			ospf_metric1 = 100;
1567
			accept;
1568
		}
1569
		reject;
1570
	};
1571
	area 0.0.0.0 {
1572
		interface "eth*" {
1573
			cost 11;
1574
			hello 15;
1575
			priority 100;
1576
			retransmit 7;
1577
			authentication simple;
1578
			password "aaa";
1579
		};
1580
		interface "ppp*" {
1581
			cost 100;
1582
			authentication cryptographic;
1583
			password "abc" {
1584
				id 1;
1585
				generate to "22-04-2003 11:00:06";
1586
				accept from "17-01-2001 12:01:05";
1587
			};
1588
			password "def" {
1589
				id 2;
1590
				generate to "22-07-2005 17:03:21";
1591
				accept from "22-02-2001 11:34:06";
1592
			};
1593
		};
1594
		interface "arc0" {
1595
			cost 10;
1596
			stub yes;
1597
		};
1598
		interface "arc1";
1599
	};
1600
	area 120 {
1601
		stub yes;
1602
		networks {
1603
			172.16.1.0/24;
1604
			172.16.2.0/24 hidden;
1605
		}
1606
		interface "-arc0" , "arc*" {
1607
			type nonbroadcast;
1608
			authentication none;
1609
			strict nonbroadcast yes;
1610
			wait 120;
1611
			poll 40;
1612
			dead count 8;
1613
			neighbors {
1614
				192.168.120.1 eligible;
1615
				192.168.120.2;
1616
				192.168.120.10;
1617
			};
1618
		};
1619
	};
1620
}
1621
</code>
1622

    
1623
<sect>Pipe
1624

    
1625
<sect1>Introduction
1626

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

    
1634
<p>The Pipe protocol may work in the opaque mode or in the transparent
1635
mode. In the opaque mode, the Pipe protocol retransmits optimal route
1636
from one table to the other table in a similar way like other
1637
protocols send and receive routes. Retransmitted route will have the
1638
source set to the Pipe protocol, which may limit access to protocol
1639
specific route attributes. The opaque mode is a default mode.
1640

    
1641
<p>In transparent mode, the Pipe protocol retransmits all routes from
1642
one table to the other table, retaining their original source and
1643
attributes.  If import and export filters are set to accept, then both
1644
tables would have the same content. The mode can be set by
1645
<tt/mode/ option.
1646

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

    
1658
<sect1>Configuration
1659

    
1660
<p><descrip>
1661
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
1662
	primary one is selected by the <cf/table/ keyword.
1663

    
1664
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
1665
</descrip>
1666

    
1667
<sect1>Attributes
1668

    
1669
<p>The Pipe protocol doesn't define any route attributes.
1670

    
1671
<sect1>Example
1672

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

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

    
1687
<code>
1688
table as1;				# Define the tables
1689
table as2;
1690

    
1691
protocol kernel kern1 {			# Synchronize them with the kernel
1692
	table as1;
1693
	kernel table 1;
1694
}
1695

    
1696
protocol kernel kern2 {
1697
	table as2;
1698
	kernel table 2;
1699
}
1700

    
1701
protocol bgp bgp1 {			# The outside connections
1702
	table as1;
1703
	local as 1;
1704
	neighbor 192.168.0.1 as 1001;
1705
	export all;
1706
	import all;
1707
}
1708

    
1709
protocol bgp bgp2 {
1710
	table as2;
1711
	local as 2;
1712
	neighbor 10.0.0.1 as 1002;
1713
	export all;
1714
	import all;
1715
}
1716

    
1717
protocol pipe {				# The Pipe
1718
	table as1;
1719
	peer table as2;
1720
	export filter {
1721
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
1722
			if preference>10 then preference = preference-10;
1723
			if source=RTS_BGP then bgp_path.prepend(1);
1724
			accept;
1725
		}
1726
		reject;
1727
	};
1728
	import filter {
1729
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
1730
			if preference>10 then preference = preference-10;
1731
			if source=RTS_BGP then bgp_path.prepend(2);
1732
			accept;
1733
		}
1734
		reject;
1735
	};
1736
}
1737
</code>
1738

    
1739
<sect>RIP
1740

    
1741
<sect1>Introduction
1742

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

    
1756
<p>RIP is a very simple protocol, and it has a lot of shortcomings. Slow
1757
convergence, big network load and inability to handle larger networks
1758
makes it pretty much obsolete. (It is still usable on very small networks.)
1759

    
1760
<sect1>Configuration
1761

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

    
1764
<descrip>
1765
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
1766
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
1767
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
1768
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
1769
	  section. Default: none.
1770

    
1771
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
1772
	  be honored. (Always, when sent from a  host on a directly connected
1773
	  network or never.) Routing table updates are honored only from
1774
	  neighbors, that is not configurable. Default: never.
1775
</descrip>
1776

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

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

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

    
1794
	<tag>infinity <M>number</M></tag>
1795
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
1796
	  even slower.
1797

    
1798
	<tag>period <M>number</M>
1799
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
1800
	  number will mean faster convergence but bigger network
1801
	  load. Do not use values lower than 10.
1802

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

    
1806
	<tag>garbage time <M>number</M>
1807
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
1808
</descrip>
1809

    
1810
<sect1>Attributes
1811

    
1812
<p>RIP defines two route attributes:
1813

    
1814
<descrip>
1815
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
1816
	When routes from different RIP instances are available and all of them have the same
1817
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
1818
	When importing a non-RIP route, the metric defaults to 5.
1819

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

    
1825
<sect1>Example
1826

    
1827
<p><code>
1828
protocol rip MyRIP_test {
1829
        debug all;
1830
        port 1520;
1831
        period 10;
1832
        garbage time 60;
1833
        interface "eth0" { metric 3; mode multicast; };
1834
	interface "eth*" { metric 2; mode broadcast; };
1835
        honor neighbor;
1836
        authentication none;
1837
        import filter { print "importing"; accept; };
1838
        export filter { print "exporting"; accept; };
1839
}
1840
</code>
1841

    
1842
<sect>Static
1843

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

    
1852
<p>There are three types of static routes: `classical' routes telling to
1853
forward packets to a neighboring router, device routes specifying forwarding
1854
to hosts on a directly connected network and special routes (sink, blackhole
1855
etc.) which specify a special action to be done instead of forwarding the
1856
packet.
1857

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

    
1863
<p>The Static protocol has no configuration options. Instead, the
1864
definition of the protocol contains a list of static routes:
1865

    
1866
<descrip>
1867
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
1868
	a neighboring router.
1869
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
1870
	route through an interface to hosts on a directly connected network.
1871
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
1872
	specifying to drop the packet, return it as unreachable or return
1873
	it as administratively prohibited.
1874
</descrip>
1875

    
1876
<p>Static routes have no specific attributes.
1877

    
1878
<p>Example static config might look like this:
1879

    
1880
<p><code>
1881
protocol static {
1882
	table testable;			 # Connect to a non-default routing table
1883
	route 0.0.0.0/0 via 62.168.0.13; # Default route
1884
	route 62.168.0.0/25 reject;	 # Sink route
1885
	route 10.2.0.0/24 via "arc0";	 # Secondary network
1886
}
1887
</code>
1888

    
1889
<chapt>Conclusions
1890

    
1891
<sect>Future work
1892

    
1893
<p>Although BIRD supports all the commonly used routing protocols,
1894
there are still some features which would surely deserve to be
1895
implemented in future versions of BIRD:
1896

    
1897
<itemize>
1898
<item>OSPF NSSA areas and opaque LSA's
1899
<item>Route aggregation and flap dampening
1900
<item>Generation of IPv6 router advertisements
1901
<item>Multipath routes
1902
<item>Multicast routing protocols
1903
<item>Ports to other systems
1904
</itemize>
1905

    
1906
<sect>Getting more help
1907

    
1908
<p>If you use BIRD, you're welcome to join the bird-users mailing list
1909
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
1910
where you can share your experiences with the other users and consult
1911
your problems with the authors. To subscribe to the list, just send a
1912
<tt/subscribe bird-users/ command in a body of a mail to
1913
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
1914
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
1915

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

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

    
1926
<p><it/Good luck!/
1927

    
1928
</book>
1929

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