Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 508d9360

History | View | Annotate | Download (133 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>the Router Advertisements for IPv6 hosts
83
	<item>a virtual protocol for exchange of routes between different routing tables on a single host
84
	<item>a command-line interface allowing on-line control and inspection
85
		of status of the daemon
86
	<item>soft reconfiguration (no need to use complex online commands
87
		to change the configuration, just edit the configuration file
88
		and notify BIRD to re-read it and it will smoothly switch itself
89
		to the new configuration, not disturbing routing protocols
90
		unless they are affected by the configuration changes)
91
	<item>a powerful language for route filtering
92
</itemize>
93

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

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

    
104
<p>BIRD supports either IPv4 or IPv6 protocol, but have to be compiled
105
separately for each one. Therefore, a dualstack router would run two
106
instances of BIRD (one for IPv4 and one for IPv6), with completely
107
separate setups (configuration files, tools ...).
108

    
109
<sect>Installing BIRD
110

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

    
113
<code>
114
        ./configure
115
        make
116
        make install
117
        vi /usr/local/etc/bird.conf
118
	bird
119
</code>
120

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

    
128
<sect>Running BIRD
129

    
130
<p>You can pass several command-line options to bird:
131

    
132
<descrip>
133
	<tag>-c <m/config name/</tag>
134
	use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
135

    
136
	<tag>-d</tag>
137
	enable debug messages and run bird in foreground.
138

    
139
	<tag>-D <m/filename of debug log/</tag>
140
	log debugging information to given file instead of stderr.
141

    
142
	<tag>-p</tag>
143
	just parse the config file and exit. Return value is zero if the config file is valid,
144
	nonzero if there are some errors.
145

    
146
	<tag>-s <m/name of communication socket/</tag>
147
	use given filename for a  socket for communications with the client, default is <it/prefix/<file>/var/run/bird.ctl</file>.
148

    
149
	<tag>-u <m/user/</tag>
150
	drop privileges and use that user ID, see the next section for details.
151

    
152
	<tag>-g <m/group/</tag>
153
	use that group ID, see the next section for details.
154
</descrip>
155

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

    
158
<sect>Privileges
159

    
160
<p>BIRD, as a routing daemon, uses several privileged operations (like
161
setting routing table and using raw sockets). Traditionally, BIRD is
162
executed and runs with root privileges, which may be prone to security
163
problems. The recommended way is to use a privilege restriction
164
(options <cf/-u/, <cf/-g/). In that case BIRD is executed with root
165
privileges, but it changes its user and group ID to an unprivileged
166
ones, while using Linux capabilities to retain just required
167
privileges (capabilities CAP_NET_*). Note that the control socket is
168
created before the privileges are dropped, but the config file is read
169
after that. The privilege restriction is not implemented in BSD port
170
of BIRD.
171

    
172
<p>A nonprivileged user (as an argument to <cf/-u/ options) may be the
173
user <cf/nobody/, but it is suggested to use a new dedicated user
174
account (like <cf/bird/). The similar considerations apply for
175
the group option, but there is one more condition -- the users
176
in the same group can use <file/birdc/ to control BIRD.
177

    
178
<p>Finally, there is a possibility to use external tools to run BIRD in
179
an environment with restricted privileges. This may need some
180
configuration, but it is generally easy -- BIRD needs just the
181
standard library, privileges to read the config file and create the
182
control socket and the CAP_NET_* capabilities.
183

    
184
<chapt>About routing tables
185

    
186
<p>BIRD has one or more routing tables which may or may not be
187
synchronized with OS kernel and which may or may not be synchronized with
188
each other (see the Pipe protocol). Each routing table contains a list of
189
known routes. Each route consists of:
190

    
191
<itemize>
192
	<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)
193
	<item>preference of this route
194
	<item>IP address of router which told us about this route
195
	<item>IP address of router we should forward the packets to
196
	using this route
197
	<item>other attributes common to all routes
198
	<item>dynamic attributes defined by protocols which may or
199
	may not be present (typically protocol metrics)
200
</itemize>
201

    
202
Routing table maintains multiple entries
203
for a network, but at most one entry for one network and one
204
protocol. The entry with the highest preference is used for routing (we
205
will call such an entry the <it/selected route/). If
206
there are more entries with the same preference and they are from the same
207
protocol, the protocol decides (typically according to metrics). If they aren't,
208
an internal ordering is used to break the tie. You can
209
get the list of route attributes in the Route attributes section.
210

    
211
<p>Each protocol is connected to a routing table through two filters
212
which can accept, reject and modify the routes. An <it/export/
213
filter checks routes passed from the routing table to the protocol,
214
an <it/import/ filter checks routes in the opposite direction.
215
When the routing table gets a route from a protocol, it recalculates
216
the selected route and broadcasts it to all protocols connected to
217
the table. The protocols typically send the update to other routers
218
in the network. Note that although most protocols are interested 
219
in receiving just selected routes, some protocols (e.g. the <cf/Pipe/
220
protocol) receive and process all entries in routing tables (accepted
221
by filters).
222

    
223
<p><label id="dsc-sorted">Usually, a routing table just chooses a
224
selected route from a list of entries for one network. But if the
225
<cf/sorted/ option is activated, these lists of entries are kept
226
completely sorted (according to preference or some protocol-dependent
227
metric).
228

    
229
This is needed for some features of some protocols
230
(e.g. <cf/secondary/ option of BGP protocol, which allows to accept
231
not just a selected route, but the first route (in the sorted list)
232
that is accepted by filters), but it is incompatible with some other
233
features (e.g. <cf/deterministic med/ option of BGP protocol, which
234
activates a way of choosing selected route that cannot be described
235
using comparison and ordering). Minor advantage is that routes are
236
shown sorted in <cf/show route/, minor disadvantage is that it is
237
slightly more computationally expensive.
238

    
239

    
240
<chapt>Configuration
241

    
242
<sect>Introduction
243

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

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

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

    
259

    
260
<code>
261
protocol kernel {
262
	persist;		# Don't remove routes on BIRD shutdown
263
	scan time 20;		# Scan kernel routing table every 20 seconds
264
	export all;		# Default is export none
265
}
266

    
267
protocol device {
268
	scan time 10;		# Scan interfaces every 10 seconds
269
}
270

    
271
protocol rip {
272
	export all;
273
	import all;
274
	interface "*";
275
}
276
</code>
277

    
278

    
279
<sect>Global options
280

    
281
<p><descrip>
282
	<tag>include "<m/filename/"</tag> 
283
	This statement causes inclusion of a new file. The maximal depth is set to 5.
284

    
285
	<tag><label id="dsc-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag> 
286
	Set logging of messages having the given class (either <cf/all/ or <cf/{
287
	error, trace }/ etc.) into selected destination (a file specified as a filename string,
288
	syslog with optional name argument, or the stderr output). Classes are:
289
	<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
290
	<cf/debug/ for debugging messages, 
291
	<cf/trace/ when you want to know what happens in the network, 
292
	<cf/remote/ for messages about misbehavior of remote machines, 
293
	<cf/auth/ about authentication failures,
294
	<cf/bug/ for internal BIRD bugs. You may specify more than one <cf/log/ line to establish logging to multiple
295
	destinations. Default: log everything to the system log.
296

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

    
300
	<tag>debug commands <m/number/</tag>
301
	Control logging of client connections (0 for no logging, 1 for
302
	logging of connects and disconnects, 2 and higher for logging of
303
	all client commands). Default: 0.
304

    
305
	<tag>mrtdump "<m/filename/"</tag>
306
	Set MRTdump file name. This option must be specified to allow MRTdump feature.
307
	Default: no dump file.
308

    
309
	<tag>mrtdump protocols all|off|{ states, messages }</tag>
310
	Set global defaults of MRTdump options. See <cf/mrtdump/ in the following section.
311
	Default: off.
312

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

    
316
	<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
317
	about functions in the following chapter.
318
 
319
	<tag>protocol rip|ospf|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
320
	Define a protocol instance called <cf><m/name/</cf> (or with a name like "rip5" generated
321
	automatically if you don't specify any <cf><m/name/</cf>). You can learn more about
322
	configuring protocols in their own chapters. When <cf>from <m/name2/</cf> expression is
323
	used, initial protocol options are taken from protocol or template <cf><m/name2/</cf>
324
	You can run more than one instance of most protocols (like RIP or BGP). By default, no
325
	instances are configured.
326

    
327
	<tag>template rip|bgp|... [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
328
	Define a protocol template instance called <cf><m/name/</cf> (or with a name like "bgp1"
329
	generated automatically if you don't specify any <cf><m/name/</cf>). Protocol templates can
330
	be used to group common options when many similarly configured protocol instances are to be
331
	defined. Protocol instances (and other templates) can use templates by using <cf/from/
332
	expression and the name of the template. At the moment templates (and <cf/from/ expression)
333
	are not implemented for OSPF protocol.
334

    
335
	<tag>define <m/constant/ = (<m/expression/)|<m/number/|<m/IP address/</tag>
336
	Define a constant. You can use it later in every place you could use a simple integer or an IP address.
337
	Besides, there are some predefined numeric constants based on /etc/iproute2/rt_* files.
338
	A list of defined constants can be seen (together with other symbols) using 'show symbols' command.
339

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

    
347
	<tag>router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, ...]</tag>
348
	Set BIRD's router ID based on an IP address of an interface
349
	specified by an interface pattern. The option is applicable
350
	for IPv4 version only. See <ref id="dsc-iface" name="interface">
351
	section for detailed description of interface patterns.
352

    
353
	<tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
354
	This option allows to specify address and port where BGP
355
	protocol should listen. It is global option as listening
356
	socket is common to all BGP instances. Default is to listen on
357
	all addresses (0.0.0.0) and port 179. In IPv6 mode, option
358
	<cf/dual/ can be used to specify that BGP socket should accept
359
	both IPv4 and IPv6 connections (but even in that case, BIRD
360
	would accept IPv6 routes only). Such behavior was default in
361
	older versions of BIRD.
362

    
363
	<tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
364
	This option allows to specify a format of date/time used by
365
	BIRD.  The first argument specifies for which purpose such
366
	format is used. <cf/route/ is a format used in 'show route'
367
	command output, <cf/protocol/ is used in 'show protocols'
368
	command output, <cf/base/ is used for other commands and
369
	<cf/log/ is used in a log file.
370

    
371
	"<m/format1/" is a format string using <it/strftime(3)/
372
	notation (see <it/man strftime/ for details). <m/limit> and
373
	"<m/format2/" allow to specify the second format string for
374
	times in past deeper than <m/limit/ seconds. There are two
375
	shorthands: <cf/iso long/ is a ISO 8601 date/time format
376
	(YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
377
	%T"/. <cf/iso short/ is a variant of ISO 8601 that uses just
378
	the time format (hh:mm:ss) for near times (up to 20 hours in
379
	the past) and the date format (YYYY-MM-DD) for far times. This
380
	is a shorthand for <cf/"%T" 72000 "%F"/.
381

    
382
	By default, BIRD uses an short, ad-hoc format for <cf/route/
383
	and <cf/protocol/ times, and a <cf/iso long/ similar format
384
	(DD-MM-YYYY hh:mm:ss) for <cf/base/ and <cf/log/. These
385
	defaults are here for a compatibility with older versions
386
	and might change in the future.
387

    
388
	<tag>table <m/name/ [sorted]</tag>
389
	Create a new routing table. The default routing table is
390
	created implicitly, other routing tables have to be added by
391
	this command. Option <cf/sorted/ can be used to enable
392
	sorting of routes, see <ref id="dsc-sorted" name="sorted table">
393
	description for details.
394

    
395
	<tag>roa table <m/name/ [ { roa table options ... } ]</tag>
396
	Create a new ROA (Route Origin Authorization) table. ROA
397
	tables can be used to validate route origination of BGP
398
	routes. A ROA table contains ROA entries, each consist of a
399
	network prefix, a max prefix length and an AS number. A ROA
400
	entry specifies prefixes which could be originated by that AS
401
	number. ROA tables could be filled with data from RPKI (RFC
402
	6480) or from public databases like Whois. ROA tables are 
403
	examined by <cf/roa_check()/ operator in filters.
404

    
405
	Currently, there is just one option,
406
	<cf>roa <m/prefix/ max <m/num/ as <m/num/</cf>, which
407
	can be used to populate the ROA table with static ROA
408
	entries. The option may be used multiple times. Other entries
409
	can be added dynamically by <cf/add roa/ command.
410

    
411
	<tag>eval <m/expr/</tag> Evaluates given filter expression. It
412
	is used by us for testing of filters.
413
</descrip>
414

    
415
<sect>Protocol options
416

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

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

    
427
<descrip>
428
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
429

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

    
433
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
434
	Set protocol debugging options. If asked, each protocol is capable of
435
	writing trace messages about its work to the log (with category
436
	<cf/trace/). You can either request printing of <cf/all/ trace messages
437
	or only of the types selected: <cf/states/ for protocol state changes
438
	(protocol going up, down, starting, stopping etc.),
439
	<cf/routes/ for routes exchanged with the routing table,
440
	<cf/filters/ for details on route filtering,
441
	<cf/interfaces/ for interface change events sent to the protocol,
442
	<cf/events/ for events internal to the protocol and
443
	<cf/packets/ for packets sent and received by the protocol. Default: off.
444

    
445
	<tag>mrtdump all|off|{ states, messages }</tag>
446

    
447
	Set protocol MRTdump flags. MRTdump is a standard binary
448
	format for logging information from routing protocols and
449
	daemons.  These flags control what kind of information is
450
	logged from the protocol to the MRTdump file (which must be
451
	specified by global <cf/mrtdump/ option, see the previous
452
	section). Although these flags are similar to flags of
453
	<cf/debug/ option, their meaning is different and
454
	protocol-specific. For BGP protocol, <cf/states/ logs BGP
455
	state changes and <cf/messages/ logs received BGP messages.
456
	Other protocols does not support MRTdump yet.
457

    
458
	<tag>router id <m/IPv4 address/</tag> This option can be used
459
	to override global router id for a given protocol. Default:
460
	uses global router id.
461

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

    
468
	<tag>export <m/filter/</tag>
469
	This is similar to the <cf>import</cf> keyword, except that it
470
	works in the direction from the routing table to the protocol.
471
	Default: <cf/none/.
472

    
473
	<tag>import keep filtered <m/switch/</tag>
474
	Usually, if an import filter rejects a route, the route is
475
	forgotten. When this option is active, these routes are
476
	kept in the routing table, but they are hidden and not
477
	propagated to other protocols. But it is possible to show them
478
	using <cf/show route filtered/. Note that this option does not
479
	work for the pipe protocol. Default: off.
480

    
481
	<tag>import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
482
	Specify an import route limit (a maximum number of routes
483
	imported from the protocol) and optionally the action to be
484
	taken when the limit is hit. Warn action just prints warning
485
	log message. Block action discards new routes coming from the
486
	protocol. Restart and disable actions shut the protocol down
487
	like appropriate commands. Disable is the default action if an
488
	action is not explicitly specified. Note that limits are reset
489
	during protocol reconfigure, reload or restart. Default: <cf/off/.
490

    
491
	<tag>receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
492
	Specify an receive route limit (a maximum number of routes
493
	received from the protocol and remembered). It works almost
494
	identically to <cf>import limit</cf> option, the only
495
	difference is that if <cf/import keep filtered/ option is
496
	active, filtered routes are counted towards the limit and
497
	blocked routes are forgotten, as the main purpose of the
498
	receive limit is to protect routing tables from
499
	overflow. Import limit, on the contrary, counts accepted
500
	routes only and routes blocked by the limit are handled like
501
	filtered routes. Default: <cf/off/.
502

    
503
	<tag>export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
504
	Specify an export route limit, works similarly to
505
	the <cf>import limit</cf> option, but for the routes exported
506
	to the protocol. This option is experimental, there are some
507
	problems in details of its behavior -- the number of exported
508
	routes can temporarily exceed the limit without triggering it
509
	during protocol reload, exported routes counter ignores route
510
	blocking and block action also blocks route updates of already
511
	accepted routes -- and these details will probably change in
512
	the future. Default: <cf/off/.
513

    
514
	<tag>description "<m/text/"</tag> This is an optional
515
	description of the protocol. It is displayed as a part of the
516
	output of 'show route all' command.
517

    
518
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
519
</descrip>
520

    
521
<p>There are several options that give sense only with certain protocols:
522

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

    
526
	Specifies a set of interfaces on which the protocol is activated with
527
	given interface-specific options. A set of interfaces specified by one
528
	interface option is described using an interface pattern. The
529
	interface pattern consists of a sequence of clauses (separated by
530
	commas), each clause may contain a mask, a prefix, or both of them. An
531
	interface matches the clause if its name matches the mask (if
532
	specified) and its address matches the prefix (if specified). Mask is
533
	specified as shell-like pattern. For IPv6, the prefix part of a clause
534
	is generally ignored and interfaces are matched just by their name.
535

    
536
	An interface matches the pattern if it matches any of its
537
	clauses. If the clause begins with <cf/-/, matching interfaces are
538
	excluded. Patterns are parsed left-to-right, thus
539
	<cf/interface "eth0", -"eth*", "*";/ means eth0 and all
540
	non-ethernets.
541

    
542
	An interface option can be used more times with different
543
	interfaces-specific options, in that case for given interface
544
	the first matching interface option is used.
545
	
546
	This option is allowed in Direct, OSPF, RIP and RAdv protocols,
547
	but in OSPF protocol it is used in <cf/area/ subsection.
548

    
549
	Default: none.
550

    
551
	Examples:
552

    
553
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
554
	<cf>type broadcast</cf> option.
555

    
556
	<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the protocol
557
	on enumerated interfaces with <cf>type ptp</cf> option.
558
	
559
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
560
	interfaces that have address from 192.168.0.0/16, but not
561
	from 192.168.1.0/24.
562

    
563
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
564
	interfaces that have address from 192.168.0.0/16, but not
565
	from 192.168.1.0/24.
566

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

    
570
	<tag><label id="dsc-prio">tx class|dscp <m/num/</tag>
571
        This option specifies the value of ToS/DS/Class field in IP
572
        headers of the outgoing protocol packets. This may affect how the
573
        protocol packets are processed by the network relative to the
574
        other network traffic. With <cf/class/ keyword, the value
575
        (0-255) is used for the whole ToS/Class octet (but two bits
576
        reserved for ECN are ignored). With <cf/dscp/ keyword, the
577
        value (0-63) is used just for the DS field in the
578
        octet. Default value is 0xc0 (DSCP 0x30 - CS6).
579

    
580
	<tag>tx priority <m/num/</tag>
581
        This option specifies the local packet priority. This may
582
        affect how the protocol packets are processed in the local TX
583
        queues. This option is Linux specific. Default value is 7
584
        (highest priority, privileged traffic).
585

    
586
	<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>
587
	Specifies a password that can be used by the protocol. Password option can
588
	be used more times to specify more passwords. If more passwords are
589
	specified, it is a protocol-dependent decision which one is really
590
	used. Specifying passwords does not mean that authentication is
591
	enabled, authentication can be enabled by separate, protocol-dependent
592
	<cf/authentication/ option.
593
	
594
	This option is allowed in OSPF and RIP protocols. BGP has also
595
	<cf/password/ option, but it is slightly different and described
596
	separately.
597

    
598
	Default: none.
599
</descrip>
600

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

    
603
<descrip>
604
	<tag>id <M>num</M></tag>
605
	 ID of the password, (0-255). If it's not used, BIRD will choose
606
	 ID based on an order of the password item in the interface. For
607
	 example, second password item in one interface will have default
608
	 ID 2. ID is used by some routing protocols to identify which
609
	 password was used to authenticate protocol packets.
610

    
611
	<tag>generate from "<m/time/"</tag>
612
	 The start time of the usage of the password for packet signing.
613
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
614

    
615
	<tag>generate to "<m/time/"</tag>
616
	 The last time of the usage of the password for packet signing.
617

    
618
	<tag>accept from "<m/time/"</tag>
619
	 The start time of the usage of the password for packet verification.
620

    
621
	<tag>accept to "<m/time/"</tag>
622
	 The last time of the usage of the password for packet verification.
623
</descrip>
624

    
625
<chapt>Remote control
626

    
627
<p>You can use the command-line client <file>birdc</file> to talk with
628
a running BIRD. Communication is done using a <file/bird.ctl/ UNIX
629
domain socket (unless changed with the <tt/-s/ option given to both
630
the server and the client). The commands can perform simple actions
631
such as enabling/disabling of protocols, telling BIRD to show various
632
information, telling it to show routing table filtered by filter, or
633
asking BIRD to reconfigure. Press <tt/?/ at any time to get online
634
help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
635
client, which allows just read-only commands (<cf/show .../). Option
636
<tt/-v/ can be passed to the client, to make it dump numeric return
637
codes along with the messages. You do not necessarily need to use
638
<file/birdc/ to talk to BIRD, your own applications could do that, too
639
-- the format of communication between BIRD and <file/birdc/ is stable
640
(see the programmer's documentation).
641

    
642
<p>There is also lightweight variant of BIRD client called
643
<file/birdcl/, which does not support command line editing and history
644
and has minimal dependencies. This is useful for running BIRD in
645
resource constrained environments, where Readline library (required
646
for regular BIRD client) is not available.
647

    
648
<p>Many commands have the <m/name/ of the protocol instance as an argument.
649
This argument can be omitted if there exists only a single instance.
650

    
651
<p>Here is a brief list of supported functions:
652

    
653
<descrip>
654
	<tag>show status</tag>
655
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
656

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

    
660
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
661
	Show detailed information about OSPF interfaces.
662

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

    
666
	<tag>show ospf state [all] [<m/name/]</tag>
667
	Show detailed information about OSPF areas based on a content
668
	of the link-state database. It shows network topology, stub
669
	networks, aggregated networks and routers from other areas and
670
	external routes. The command shows information about reachable
671
	network nodes, use option <cf/all/ to show information about
672
	all network nodes in the link-state database.
673

    
674
	<tag>show ospf topology [all] [<m/name/]</tag>
675
	Show a topology of OSPF areas based on a content of the
676
	link-state database.  It is just a stripped-down version of
677
	'show ospf state'.
678

    
679
	<tag>show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag>
680
	Show contents of an OSPF LSA database. Options could be used to filter entries.
681

    
682
	<tag>show static [<m/name/]</tag>
683
	Show detailed information about static routes.
684

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

    
688
	<tag>show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
689
	Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
690

    
691
	<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>
692
	Show contents of a routing table (by default of the main one or
693
        the table attached to a respective protocol),
694
	that is routes, their metrics and (in case the <cf/all/ switch is given)
695
	all their attributes.
696

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

    
704
	<p>You can also ask for printing only routes processed and accepted by
705
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
706
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
707
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
708
	that are exported to the specified protocol. With <cf/preexport/, the
709
	export filter of the protocol is skipped.
710

    
711
	<p>You can also select just routes added by a specific protocol.
712
	<cf>protocol <m/p/</cf>.
713

    
714
	<p>If BIRD is configured to keep filtered routes (see <cf/import keep filtered/
715
	option), you can show them instead of routes by using <cf/filtered/ switch.
716

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

    
721
	<tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
722
	Show contents of a ROA table (by default of the first one).
723
	You can specify a <m/prefix/ to print ROA entries for a
724
	specific network. If you use <cf>for <m/prefix/</cf>, you'll
725
	get all entries relevant for route validation of the network
726
	prefix; i.e., ROA entries whose prefixes cover the network
727
	prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA entries
728
	covered by the network prefix. You could also use <cf/as/ option
729
	to show just entries for given AS.
730

    
731
	<tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
732
	Add a new ROA entry to a ROA table. Such entry is called
733
	<it/dynamic/ compared to <it/static/ entries specified in the
734
	config file. These dynamic entries survive reconfiguration.
735

    
736
	<tag>delete roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
737
	Delete the specified ROA entry from a ROA table. Only dynamic
738
	ROA entries (i.e., the ones added by <cf/add roa/ command) can
739
	be deleted.
740

    
741
	<tag>flush roa [table <m/t/>]</tag>
742
	Remove all dynamic ROA entries from a ROA table.
743

    
744
	<tag>configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
745
	Reload configuration from a given file. BIRD will smoothly
746
	switch itself to the new configuration, protocols are
747
	reconfigured if possible, restarted otherwise. Changes in
748
	filters usually lead to restart of affected protocols.
749

    
750
	If <cf/soft/ option is used, changes in filters does not cause
751
	BIRD to restart affected protocols, therefore already accepted
752
	routes (according to old filters) would be still propagated,
753
	but new routes would be processed according to the new
754
	filters.
755

    
756
	If <cf/timeout/ option is used, config timer is activated. The
757
	new configuration could be either confirmed using
758
	<cf/configure confirm/ command, or it will be reverted to the
759
	old one when the config timer expires. This is useful for cases
760
	when reconfiguration breaks current routing and a router becames
761
	inaccessible for an administrator. The config timeout expiration is
762
	equivalent to <cf/configure undo/ command. The timeout duration
763
	could be specified, default is 300 s.
764

    
765
	<tag>configure confirm</tag>
766
	Deactivate the config undo timer and therefore confirm the current
767
	configuration.
768

    
769
	<tag>configure undo</tag>
770
	Undo the last configuration change and smoothly switch back to
771
	the previous (stored) configuration. If the last configuration
772
	change was soft, the undo change is also soft. There is only
773
	one level of undo, but in some specific cases when several
774
	reconfiguration requests are given immediately in a row and
775
	the intermediate ones are skipped then the undo also skips them back.
776

    
777
	<tag>configure check ["<m/config file/"]</tag>
778
	Read and parse given config file, but do not use it. useful
779
	for checking syntactic and some semantic validity of an config
780
	file.
781

    
782
	<tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
783
	Enable, disable or restart a given protocol instance,
784
	instances matching the <cf><m/pattern/</cf> or
785
	<cf/all/ instances.
786

    
787
	<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
788
	
789
	Reload a given protocol instance, that means re-import routes
790
	from the protocol instance and re-export preferred routes to
791
	the instance. If <cf/in/ or <cf/out/ options are used, the
792
	command is restricted to one direction (re-import or
793
	re-export).
794

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

    
800
	Re-export always succeeds, but re-import is protocol-dependent
801
	and might fail (for example, if BGP neighbor does not support
802
	route-refresh extension). In that case, re-export is also
803
	skipped. Note that for the pipe protocol, both directions are
804
	always reloaded together (<cf/in/ or <cf/out/ options are
805
	ignored in that case).
806

    
807
	<tag/down/
808
	Shut BIRD down.
809

    
810
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
811
	Control protocol debugging.
812

    
813
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
814
	Dump contents of internal data structures to the debugging output.
815

    
816
	<tag>echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
817
	Control echoing of log messages to the command-line output.
818
	See <ref id="dsc-log" name="log option"> for a list of log classes.
819

    
820
	<tag>eval <m/expr/</tag>
821
	Evaluate given expression.
822

    
823
</descrip>
824

    
825
<chapt>Filters
826

    
827
<sect>Introduction
828

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

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

    
839
<code>
840
filter not_too_far
841
int var;
842
{
843
	if defined( rip_metric ) then
844
		var = rip_metric;
845
	else {
846
		var = 1;
847
		rip_metric = 1;
848
	}
849
	if rip_metric &gt; 10 then
850
		reject "RIP metric is too big";
851
	else
852
		accept "ok";
853
}
854
</code>
855

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

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

    
867
<code>
868
function name ()
869
int local_variable;
870
{
871
	local_variable = 5;
872
}
873

    
874
function with_parameters (int parameter)
875
{
876
	print parameter;
877
}
878
</code>
879

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

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

    
891
<p>A nice trick to debug filters is to use <cf>show route filter
892
<m/name/</cf> from the command line client. An example session might look
893
like:
894

    
895
<code>
896
pavel@bug:~/bird$ ./birdc -s bird.ctl
897
BIRD 0.0.0 ready.
898
bird> show route
899
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
900
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
901
127.0.0.0/8        dev lo [direct1 23:21] (240)
902
bird> show route ?
903
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
904
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
905
127.0.0.0/8        dev lo [direct1 23:21] (240)
906
bird>
907
</code>
908

    
909
<sect>Data types
910

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

    
914
<descrip>
915
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
916
	  <cf/false/. Boolean is the only type you can use in <cf/if/
917
	  statements.
918

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

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

    
926
	<tag/quad/ This is a dotted quad of numbers used to represent
927
	  router IDs (and others).  Each component can have a value
928
	  from 0 to 255. Literals of this type are written like IPv4
929
	  addresses.
930

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

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

    
941
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
942
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
943
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
944
	  operators on prefixes:
945
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
946
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
947

    
948
	<tag/ec/ This is a specialized type used to represent BGP
949
	  extended community values. It is essentially a 64bit value,
950
	  literals of this type are usually written as <cf>(<m/kind/,
951
	  <m/key/, <m/value/)</cf>, where <cf/kind/ is a kind of
952
	  extended community (e.g. <cf/rt/ / <cf/ro/ for a route
953
	  target / route origin communities), the format and possible
954
	  values of <cf/key/ and <cf/value/ are usually integers, but
955
	  it depends on the used kind. Similarly to pairs, ECs can be
956
	  constructed using expressions for <cf/key/ and
957
	  <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
958
	  <cf/myas/ is an integer variable).
959
 
960
	<tag/int|pair|quad|ip|prefix|ec|enum set/
961
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
962
	  but you can't modify them. Literals of type <cf>int set</cf> look like <cf>
963
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
964
	  sets.
965

    
966
	  For pair sets, expressions like <cf/(123,*)/ can be used to denote ranges (in
967
	  that case <cf/(123,0)..(123,65535)/). You can also use <cf/(123,5..100)/ for range
968
	  <cf/(123,5)..(123,100)/. You can also use <cf/*/ and <cf/a..b/ expressions
969
	  in the first part of a pair, note that such expressions are translated to a set
970
	  of intervals, which may be memory intensive. E.g. <cf/(*,4..20)/ is translated to
971
	  <cf/(0,4..20), (1,4..20), (2,4..20), ... (65535, 4..20)/.
972

    
973
	  EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123, 10..20)/ 
974
	  or <cf/(ro, 123, *)/. Expressions requiring the translation (like  <cf/(rt, *, 3)/)
975
	  are not allowed (as they usually have 4B range for ASNs).
976

    
977
	  You can also use expressions for int, pair and EC set values. However it must
978
	  be possible to evaluate these expressions before daemon boots. So you can use
979
	  only constants inside them. E.g.
980
	<code>
981
	 define one=1;
982
	 define myas=64500;
983
	 int set odds;
984
	 pair set ps;
985
	 ec set es;
986

    
987
	 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
988
	 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
989
	 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
990
	</code>
991

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

    
1000
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
1001
	  <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), 
1002
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
1003
	  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>
1004
	  and all its supernets (network prefixes that contain it).
1005

    
1006
	  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
1007
	  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
1008
	  <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
1009
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
1010
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
1011
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
1012

    
1013
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
1014
	  in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
1015
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
1016
	  <cf>192.168.0.0/16{24,32}</cf>.
1017

    
1018
	<tag/enum/
1019
	  Enumeration types are fixed sets of possibilities. You can't define your own
1020
	  variables of such type, but some route attributes are of enumeration
1021
	  type. Enumeration types are incompatible with each other.
1022

    
1023
	<tag/bgppath/
1024
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
1025
	  There are several special operators on bgppaths:
1026

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

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

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

    
1034
          <cf><m/P/.len</cf> returns the length of path <m/P/.
1035

    
1036
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
1037
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
1038
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
1039
          (for example <cf/bgp_path/).
1040

    
1041
	<tag/bgpmask/
1042
	  BGP masks are patterns used for BGP path matching
1043
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
1044
	  resemble wildcard patterns as used by UNIX shells. Autonomous
1045
	  system numbers match themselves, <cf/*/ matches any (even empty)
1046
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
1047
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
1048
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
1049
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
1050
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
1051
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
1052
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
1053

    
1054
	<tag/clist/
1055
	  Clist is similar to a set, except that unlike other sets, it
1056
	  can be modified. The type is used for community list (a set
1057
	  of pairs) and for cluster list (a set of quads). There exist
1058
	  no literals of this type. There are three special operators on
1059
	  clists:
1060

    
1061
          <cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist
1062
	  <m/C/ and returns the result.  If item <m/P/ is already in
1063
	  clist <m/C/, it does nothing. <m/P/ may also be a clist,
1064
	  in that case all its members are added; i.e., it works as clist union.
1065

    
1066
          <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad)
1067
	  <m/P/ from clist <m/C/ and returns the result.  If clist
1068
	  <m/C/ does not contain item <m/P/, it does nothing.
1069
	  <m/P/ may also be a pair (or quad) set, in that case the
1070
	  operator deletes all items from clist <m/C/ that are also
1071
	  members of set <m/P/. Moreover, <m/P/ may also be a clist,
1072
	  which works analogously; i.e., it works as clist difference.
1073

    
1074
          <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist
1075
	  <m/C/ that are not members of pair (or quad) set <m/P/.
1076
	  I.e., <cf/filter/ do the same as <cf/delete/ with inverted
1077
	  set <m/P/. <m/P/ may also be a clist, which works analogously;
1078
	  i.e., it works as clist intersection.
1079

    
1080
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1081
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route
1082
          attribute (for example <cf/bgp_community/). Similarly for
1083
          <cf/delete/ and <cf/filter/.
1084

    
1085
	<tag/eclist/
1086
	  Eclist is a data type used for BGP extended community lists.
1087
	  Eclists are very similar to clists, but they are sets of ECs
1088
	  instead of pairs. The same operations (like <cf/add/,
1089
	  <cf/delete/, or <cf/&tilde;/ membership operator) can be
1090
	  used to modify or test eclists, with ECs instead of pairs as
1091
	  arguments.
1092
</descrip>
1093

    
1094
<sect>Operators
1095

    
1096
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
1097
<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;/). 
1098
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
1099
used on element and set of elements of the same type (returning true if element is contained in the given set), or
1100
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
1101
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 number and bgppath (returning true if the number is in the path) or on bgppath and int (number) set (returning true if any ASN from the path is in the set) or on pair/quad and clist (returning true if the pair/quad is element of the clist) or on clist and pair/quad set (returning true if there is an element of the clist that is also a member of the pair/quad set).
1102

    
1103
<p>There is one operator related to ROA infrastructure -
1104
<cf/roa_check()/. It examines a ROA table and does RFC 6483 route
1105
origin validation for a given network prefix. The basic usage
1106
is <cf>roa_check(<m/table/)</cf>, which checks current route (which
1107
should be from BGP to have AS_PATH argument) in the specified ROA
1108
table and returns ROA_UNKNOWN if there is no relevant ROA, ROA_VALID
1109
if there is a matching ROA, or ROA_INVALID if there are some relevant
1110
ROAs but none of them match. There is also an extended variant
1111
<cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to
1112
specify a prefix and an ASN as arguments.
1113

    
1114

    
1115
<sect>Control structures
1116

    
1117
<p>Filters support two control structures: conditions and case switches. 
1118

    
1119
<p>Syntax of a condition is: <cf>if
1120
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
1121
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
1122
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.
1123

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

    
1130
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
1131

    
1132
<code>
1133
case arg1 {
1134
	2: print "two"; print "I can do more commands without {}";
1135
	3 .. 5: print "three to five";
1136
	else: print "something else";
1137
}
1138

    
1139
if 1234 = i then printn "."; else { 
1140
  print "not 1234"; 
1141
  print "You need {} around multiple commands"; 
1142
}
1143
</code>
1144

    
1145
<sect>Route attributes
1146

    
1147
<p>A filter is implicitly passed a route, and it can access its
1148
attributes just like it accesses variables. Attempts to access undefined
1149
attribute result in a runtime error; you can check if an attribute is
1150
defined by using the <cf>defined( <m>attribute</m> )</cf> operator.
1151
One notable exception to this rule are attributes of clist type, where
1152
undefined value is regarded as empty clist for most purposes.
1153

    
1154
<descrip>
1155
	<tag><m/prefix/ net</tag>
1156
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
1157

    
1158
	<tag><m/enum/ scope</tag>
1159
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for
1160
	routes local to this host, <cf/SCOPE_LINK/ for those specific
1161
	for a physical link, <cf/SCOPE_SITE/ and
1162
	<cf/SCOPE_ORGANIZATION/ for private routes and
1163
	<cf/SCOPE_UNIVERSE/ for globally visible routes. This
1164
	attribute is not interpreted by BIRD and can be used to mark
1165
	routes in filters. The default value for new routes is
1166
	<cf/SCOPE_UNIVERSE/.
1167

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

    
1171
	<tag><m/ip/ from</tag>
1172
	The router which the route has originated from. Read-only.
1173
	
1174
	<tag><m/ip/ gw</tag>
1175
	Next hop packets routed using this route should be forwarded to.
1176

    
1177
	<tag><m/string/ proto</tag>
1178
	The name of the protocol which the route has been imported from. Read-only.
1179

    
1180
	<tag><m/enum/ source</tag>
1181
	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_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/, <cf/RTS_PIPE/.
1182

    
1183
	<tag><m/enum/ cast</tag>
1184

    
1185
	Route type (Currently <cf/RTC_UNICAST/ for normal routes,
1186
	<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will
1187
	be used in the future for broadcast, multicast and anycast
1188
	routes). Read-only.
1189

    
1190
	<tag><m/enum/ dest</tag>
1191
	Type of destination the packets should be sent to
1192
	(<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1193
	<cf/RTD_DEVICE/ for routing to a directly-connected network,
1194
	<cf/RTD_MULTIPATH/ for multipath destinations,
1195
	<cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1196
	<cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that
1197
	should be returned with ICMP host unreachable / ICMP
1198
	administratively prohibited messages). Can be changed, but
1199
	only to <cf/RTD_BLACKHOLE/, <cf/RTD_UNREACHABLE/ or
1200
	<cf/RTD_PROHIBIT/.
1201

    
1202
	<tag><m/int/ igp_metric</tag>
1203
	The optional attribute that can be used to specify a distance
1204
	to the network for routes that do not have a native protocol
1205
	metric attribute (like <cf/ospf_metric1/ for OSPF routes). It
1206
	is used mainly by BGP to compare internal distances to boundary
1207
	routers (see below). It is also used when the route is exported
1208
	to OSPF as a default value for OSPF type 1 metric.
1209
</descrip>
1210

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

    
1213
<sect>Other statements
1214

    
1215
<p>The following statements are available:
1216

    
1217
<descrip>
1218
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
1219

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

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

    
1224
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
1225
	Prints given expressions; useful mainly while debugging
1226
	filters. The <cf/printn/ variant does not terminate the line.
1227

    
1228
	<tag>quitbird</tag>
1229
	Terminates BIRD. Useful when debugging the filter interpreter.
1230
</descrip>
1231

    
1232
<chapt>Protocols
1233

    
1234
<sect>BGP
1235

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

    
1243
<p>BGP works in terms of autonomous systems (often abbreviated as
1244
AS). Each AS is a part of the network with common management and
1245
common routing policy. It is identified by a unique 16-bit number
1246
(ASN).  Routers within each AS usually exchange AS-internal routing
1247
information with each other using an interior gateway protocol (IGP,
1248
such as OSPF or RIP). Boundary routers at the border of
1249
the AS communicate global (inter-AS) network reachability information with
1250
their neighbors in the neighboring AS'es via exterior BGP (eBGP) and
1251
redistribute received information to other routers in the AS via
1252
interior BGP (iBGP).
1253

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

    
1259
<p>BIRD supports all requirements of the BGP4 standard as defined in
1260
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
1261
It also supports the community attributes
1262
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
1263
capability negotiation
1264
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
1265
MD5 password authentication
1266
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
1267
extended communities
1268
(RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">),
1269
route reflectors 
1270
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
1271
multiprotocol extensions
1272
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
1273
4B AS numbers 
1274
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">),
1275
and 4B AS numbers in extended communities
1276
(RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">).
1277

    
1278

    
1279
For IPv6, it uses the standard multiprotocol extensions defined in
1280
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
1281
including changes described in the
1282
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
1283
and applied to IPv6 according to
1284
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
1285

    
1286
<sect1>Route selection rules
1287

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

    
1294
<itemize>
1295
	<item>Prefer route with the highest Local Preference attribute.
1296
	<item>Prefer route with the shortest AS path.
1297
	<item>Prefer IGP origin over EGP and EGP origin over incomplete.
1298
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
1299
	<item>Prefer routes received via eBGP over ones received via iBGP.
1300
	<item>Prefer routes with lower internal distance to a boundary router.
1301
	<item>Prefer the route with the lowest value of router ID of the
1302
	advertising router.
1303
</itemize>
1304

    
1305
<sect1>IGP routing table
1306

    
1307
<p>BGP is mainly concerned with global network reachability and with
1308
routes to other autonomous systems. When such routes are redistributed
1309
to routers in the AS via BGP, they contain IP addresses of a boundary
1310
routers (in route attribute NEXT_HOP). BGP depends on existing IGP
1311
routing table with AS-internal routes to determine immediate next hops
1312
for routes and to know their internal distances to boundary routers
1313
for the purpose of BGP route selection. In BIRD, there is usually
1314
one routing table used for both IGP routes and BGP routes.
1315

    
1316
<sect1>Configuration
1317

    
1318
<p>Each instance of the BGP corresponds to one neighboring router.
1319
This allows to set routing policy and all the other parameters differently
1320
for each neighbor using the following configuration parameters:
1321

    
1322
<descrip>
1323
	<tag>local [<m/ip/] as <m/number/</tag> Define which AS we
1324
	are part of. (Note that contrary to other IP routers, BIRD is
1325
	able to act as a router located in multiple AS'es
1326
	simultaneously, but in such cases you need to tweak the BGP
1327
	paths manually in the filters to get consistent behavior.)
1328
	Optional <cf/ip/ argument specifies a source address,
1329
	equivalent to the <cf/source address/ option (see below).
1330
	This parameter is mandatory.
1331

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

    
1338
	<tag>multihop [<m/number/]</tag> Configure multihop BGP
1339
	session to a neighbor that isn't directly connected.
1340
	Accurately, this option should be used if the configured
1341
	neighbor IP address does not match with any local network
1342
	subnets. Such IP address have to be reachable through system
1343
	routing table. For multihop BGP it is recommended to
1344
	explicitly configure <cf/source address/ to have it
1345
	stable. Optional <cf/number/ argument can be used to specify
1346
	the number of hops (used for TTL). Note that the number of
1347
	networks (edges) in a path is counted, i.e. if two BGP
1348
	speakers are separated by one router, the number of hops is
1349
	2. Default: switched off.
1350

    
1351
	<tag>source address <m/ip/</tag> Define local address we
1352
	should use for next hop calculation and as a source address
1353
	for the BGP session. Default: the address of the local
1354
	end of the interface our neighbor is connected to.
1355

    
1356
	<tag>next hop self</tag> Avoid calculation of the Next Hop
1357
	attribute and always advertise our own source address as a
1358
	next hop.  This needs to be used only occasionally to
1359
	circumvent misconfigurations of other routers.  Default:
1360
	disabled.
1361

    
1362
	<tag>next hop keep</tag> Forward the received Next Hop
1363
	attribute even in situations where the local address should be
1364
	used instead, like when the route is sent to an interface with
1365
	a different subnet. Default: disabled.
1366

    
1367
	<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
1368
	in BGP-IPv6 sometimes contains just the global IPv6 address,
1369
	but sometimes it has to contain both global and link-local
1370
	IPv6 addresses. This option specifies what to do if BIRD have
1371
	to send both addresses but does not know link-local address.
1372
	This situation might happen when routes from other protocols
1373
	are exported to BGP, or when improper updates are received
1374
	from BGP peers.  <cf/self/ means that BIRD advertises its own
1375
	local address instead. <cf/drop/ means that BIRD skips that
1376
	prefixes and logs error. <cf/ignore/ means that BIRD ignores
1377
	the problem and sends just the global address (and therefore
1378
	forms improper BGP update). Default: <cf/self/, unless BIRD
1379
	is configured as a route server (option <cf/rs client/), in
1380
	that case default is <cf/ignore/, because route servers usually
1381
	do not forward packets themselves.
1382

    
1383
	<tag>gateway direct|recursive</tag>For received routes, their
1384
	<cf/gw/ (immediate next hop) attribute is computed from
1385
	received <cf/bgp_next_hop/ attribute. This option specifies
1386
	how it is computed. Direct mode means that the IP address from
1387
	<cf/bgp_next_hop/ is used if it is directly reachable,
1388
	otherwise the neighbor IP address is used. Recursive mode
1389
	means that the gateway is computed by an IGP routing table
1390
	lookup for the IP address from <cf/bgp_next_hop/. Recursive
1391
	mode is the behavior specified by the BGP standard. Direct
1392
	mode is simpler, does not require any routes in a routing
1393
	table, and was used in older versions of BIRD, but does not
1394
	handle well nontrivial iBGP setups and multihop.  Recursive
1395
	mode is incompatible with <ref id="dsc-sorted" name="sorted
1396
	tables">. Default: <cf/direct/ for singlehop eBGP,
1397
	<cf/recursive/ otherwise.
1398

    
1399
	<tag>igp table <m/name/</tag> Specifies a table that is used
1400
	as an IGP routing table. Default: the same as the table BGP is
1401
	connected to.
1402
	
1403
	<tag>ttl security <m/switch/</tag> Use GTSM (RFC 5082 - the
1404
	generalized TTL security mechanism). GTSM protects against
1405
	spoofed packets by ignoring received packets with a smaller
1406
	than expected TTL. To work properly, GTSM have to be enabled
1407
	on both sides of a BGP session. If both <cf/ttl security/ and
1408
	<cf/multihop/ options are enabled, <cf/multihop/ option should
1409
	specify proper hop value to compute expected TTL. Kernel
1410
	support required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD:
1411
	since long ago, IPv4 only. Note that full (ICMP protection,
1412
	for example) RFC 5082 support is provided by Linux
1413
	only. Default: disabled.
1414
	
1415
	<tag>password <m/string/</tag> Use this password for MD5 authentication
1416
	of BGP sessions. Default: no authentication. Password has to be set by
1417
	external utility (e.g. setkey(8)) on BSD systems.
1418

    
1419
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
1420
        initiating outgoing connections and accepting incoming
1421
        connections. In passive mode, outgoing connections are not
1422
        initiated. Default: off.
1423

    
1424
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
1425
	a route reflection client. Default: disabled.
1426

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

    
1434
	<tag>rs client</tag> Be a route server and treat the neighbor
1435
	as a route server client. A route server is used as a
1436
	replacement for full mesh EBGP routing in Internet exchange
1437
	points in a similar way to route reflectors used in IBGP routing.
1438
	BIRD does not implement obsoleted RFC 1863, but uses ad-hoc implementation,
1439
	which behaves like plain EBGP but reduces modifications to advertised route
1440
	attributes to be transparent (for example does not prepend its AS number to
1441
	AS PATH attribute and keeps MED attribute). Default: disabled.
1442

    
1443
	<tag>secondary <m/switch/</tag> Usually, if an import filter
1444
	rejects a selected route, no other route is propagated for
1445
	that network. This option allows to try the next route in
1446
	order until one that is accepted is found or all routes for
1447
	that network are rejected. This can be used for route servers
1448
	that need to propagate different tables to each client but do
1449
	not want to have these tables explicitly (to conserve memory).
1450
	This option requires that the connected routing table is
1451
	<ref id="dsc-sorted" name="sorted">. Default: off.
1452

    
1453
	<tag>enable route refresh <m/switch/</tag> When BGP speaker
1454
	changes its import filter, it has to re-examine all routes
1455
	received from its neighbor against the new filter. As these
1456
	routes might not be available, there is a BGP protocol
1457
	extension Route Refresh (specified in RFC 2918) that allows
1458
	BGP speaker to request re-advertisement of all routes from its
1459
	neighbor. This option specifies whether BIRD advertises this
1460
	capability and accepts such requests. Even when disabled, BIRD
1461
	can send route refresh requests. Default: on.
1462

    
1463
	<tag>interpret communities <m/switch/</tag> RFC 1997 demands
1464
	that BGP speaker should process well-known communities like
1465
	no-export (65535, 65281) or no-advertise (65535, 65282). For
1466
	example, received route carrying a no-adverise community
1467
	should not be advertised to any of its neighbors. If this
1468
	option is enabled (which is by default), BIRD has such
1469
	behavior automatically (it is evaluated when a route is
1470
	exported to the BGP protocol just before the export filter).
1471
	Otherwise, this integrated processing of well-known
1472
	communities is disabled. In that case, similar behavior can be
1473
	implemented in the export filter.  Default: on.
1474

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

    
1483
	<tag>capabilities <m/switch/</tag> Use capability advertisement
1484
	to advertise optional capabilities. This is standard behavior
1485
	for newer BGP implementations, but there might be some older
1486
	BGP implementations that reject such connection attempts.
1487
	When disabled (off), features that request it (4B AS support)
1488
	are also disabled. Default: on, with automatic fallback to
1489
	off when received capability-related error.
1490

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

    
1497
	<tag>route limit <m/number/</tag> The maximal number of routes
1498
	that may be imported from the protocol. If the route limit is
1499
	exceeded, the connection is closed with error. Limit is currently implemented as
1500
	<cf/import limit number exceed restart/. Default: no limit.
1501

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

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

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

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

    
1518
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
1519
	retrying a failed attempt to connect. Default: 120 seconds.
1520

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

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

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

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

    
1536
	<tag>med metric <m/switch/</tag> Enable comparison of MED
1537
	attributes (during best route selection) even between routes
1538
	received from different ASes.  This may be useful if all MED
1539
	attributes contain some consistent metric, perhaps enforced in
1540
	import filters of AS boundary routers. If this option is
1541
	disabled, MED attributes are compared only if routes are
1542
	received from the same AS (which is the standard behavior).
1543
	Default: off.
1544

    
1545
	<tag>deterministic med <m/switch/</tag> BGP route selection
1546
	algorithm is often viewed as a comparison between individual
1547
	routes (e.g. if a new route appears and is better than the
1548
	current best one, it is chosen as the new best one). But the
1549
	proper route selection, as specified by RFC 4271, cannot be
1550
	fully implemented in that way. The problem is mainly in
1551
	handling the MED attribute. BIRD, by default, uses an
1552
	simplification based on individual route comparison, which in
1553
	some cases may lead to temporally dependent behavior (i.e. the
1554
	selection is dependent on the order in which routes appeared).
1555
	This option enables a different (and slower) algorithm
1556
	implementing proper RFC 4271 route selection, which is
1557
	deterministic. Alternative way how to get deterministic
1558
	behavior is to use <cf/med metric/ option. This option is
1559
	incompatible with <ref id="dsc-sorted" name="sorted tables">.
1560
	Default: off.
1561

    
1562
	<tag>igp metric <m/switch/</tag> Enable comparison of internal
1563
 	distances to boundary routers during best route selection. Default: on.
1564

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

    
1570
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
1571
	Discriminator to be used during route selection when the MED attribute
1572
	is missing. Default: 0.
1573

    
1574
	<tag>default bgp_local_pref <m/number/</tag> A default value
1575
	for the Local Preference attribute. It is used when a new
1576
	Local Preference attribute is attached to a route by the BGP
1577
	protocol itself (for example, if a route is received through
1578
	eBGP and therefore does not have such attribute). Default: 100
1579
	(0 in pre-1.2.0 versions of BIRD).
1580
</descrip>
1581

    
1582
<sect1>Attributes
1583

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

    
1588
<descrip>
1589
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1590
	the packet will travel through when forwarded according to the particular route.
1591
	In case of internal BGP it doesn't contain the number of the local AS.
1592

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

    
1597
	<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
1598
	is an optional attribute which is used on external (inter-AS) links to
1599
	convey to an adjacent AS the optimal entry point into the local AS.
1600
	The received attribute is also propagated over internal BGP links.
1601
	The attribute value is zeroed when a route is exported to an external BGP
1602
	instance to ensure that the attribute received from a neighboring AS is
1603
	not propagated to other neighboring ASes. A new value might be set in
1604
	the export filter of an external BGP instance.
1605
	See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
1606
	for further discussion of BGP MED attribute.
1607

    
1608
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1609
	if the route has originated in an interior routing protocol or
1610
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1611
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1612
	is unknown.
1613

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

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

    
1626
<!-- we don't handle aggregators right since they are of a very obscure type
1627
	<tag>bgp_aggregator</tag>
1628
-->
1629
	<tag>clist <cf/bgp_community/ [O]</tag> List of community values associated
1630
	with the route. Each such value is a pair (represented as a <cf/pair/ data
1631
	type inside the filters) of 16-bit integers, the first of them containing the number of the AS which defines
1632
	the community and the second one being a per-AS identifier. There are lots
1633
	of uses of the community mechanism, but generally they are used to carry
1634
	policy information like "don't export to USA peers". As each AS can define
1635
	its own routing policy, it also has a complete freedom about which community
1636
	attributes it defines and what will their semantics be.
1637

    
1638
	<tag>eclist <cf/bgp_ext_community/ [O]</tag> List of extended community
1639
	values associated with the route. Extended communities have similar usage
1640
	as plain communities, but they have an extended range (to allow 4B ASNs)
1641
	and a nontrivial structure with a type field. Individual community values are
1642
	represented using an <cf/ec/ data type inside the filters.
1643

    
1644
	<tag>quad <cf/bgp_originator_id/ [I, O]</tag> This attribute is created by the
1645
	route reflector when reflecting the route and contains the router ID of the
1646
	originator of the route in the local AS.
1647

    
1648
	<tag>clist <cf/bgp_cluster_list/ [I, O]</tag> This attribute contains a list
1649
	of cluster IDs of route reflectors. Each route reflector prepends its
1650
	cluster ID when reflecting the route.
1651
</descrip>
1652

    
1653
<sect1>Example
1654

    
1655
<p><code>
1656
protocol bgp {
1657
	local as 65000;			     # Use a private AS number
1658
	neighbor 198.51.100.130 as 64496;    # Our neighbor ...
1659
	multihop;			     # ... which is connected indirectly
1660
	export filter {			     # We use non-trivial export rules
1661
		if source = RTS_STATIC then { # Export only static routes
1662
		        # Assign our community
1663
			bgp_community.add((65000,64501));
1664
			# Artificially increase path length
1665
			# by advertising local AS number twice
1666
			if bgp_path ~ [= 65000 =] then
1667
				bgp_path.prepend(65000);
1668
			accept;
1669
		}
1670
		reject;
1671
	};
1672
	import all;
1673
	source address 198.51.100.14;	# Use a non-standard source address
1674
}
1675
</code>
1676

    
1677
<sect>Device
1678

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

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

    
1687
<sect1>Configuration
1688

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

    
1696
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1697
	If a network interface has more than one network address, BIRD
1698
	has to choose one of them as a primary one. By default, BIRD
1699
	chooses the lexicographically smallest address as the primary
1700
	one.
1701

    
1702
	This option allows to specify which network address should be
1703
	chosen as a primary one. Network addresses that match
1704
	<m/prefix/ are preferred to non-matching addresses. If more
1705
	<cf/primary/ options are used, the first one has the highest
1706
	preference. If "<m/mask/" is specified, then such
1707
	<cf/primary/ option is relevant only to matching network
1708
	interfaces.
1709

    
1710
	In all cases, an address marked by operating system as
1711
	secondary cannot be chosen as the primary one. 
1712
</descrip>
1713

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

    
1717
<p><code>
1718
protocol device {
1719
	scan time 10;		# Scan the interfaces often
1720
	primary "eth0" 192.168.1.1;
1721
	primary 192.168.0.0/16;
1722
}
1723
</code>
1724

    
1725
<sect>Direct
1726

    
1727
<p>The Direct protocol is a simple generator of device routes for all the
1728
directly connected networks according to the list of interfaces provided
1729
by the kernel via the Device protocol.
1730

    
1731
<p>The question is whether it is a good idea to have such device
1732
routes in BIRD routing table. OS kernel usually handles device routes
1733
for directly connected networks by itself so we don't need (and don't
1734
want) to export these routes to the kernel protocol. OSPF protocol
1735
creates device routes for its interfaces itself and BGP protocol is
1736
usually used for exporting aggregate routes. Although there are some
1737
use cases that use the direct protocol (like abusing eBGP as an IGP
1738
routing protocol), in most cases it is not needed to have these device
1739
routes in BIRD routing table and to use the direct protocol.
1740

    
1741
<p>There is one notable case when you definitely want to use the
1742
direct protocol -- running BIRD on BSD systems. Having high priority
1743
device routes for directly connected networks from the direct protocol
1744
protects kernel device routes from being overwritten or removed by IGP
1745
routes during some transient network conditions, because a lower
1746
priority IGP route for the same network is not exported to the kernel
1747
routing table. This is an issue on BSD systems only, as on Linux
1748
systems BIRD cannot change non-BIRD route in the kernel routing table.
1749

    
1750
<p>The only configurable thing about direct is what interfaces it watches:
1751

    
1752
<p><descrip>
1753
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
1754
	protocol will generate device routes for all the interfaces
1755
	available. If you want to restrict it to some subset of interfaces
1756
	(for example if you're using multiple routing tables for policy
1757
	routing and some of the policy domains don't contain all interfaces),
1758
	just use this clause.
1759
</descrip>
1760

    
1761
<p>Direct device routes don't contain any specific attributes.
1762

    
1763
<p>Example config might look like this:
1764

    
1765
<p><code>
1766
protocol direct {
1767
	interface "-arc*", "*";		# Exclude the ARCnets
1768
}
1769
</code>
1770

    
1771
<sect>Kernel
1772

    
1773
<p>The Kernel protocol is not a real routing protocol. Instead of communicating
1774
with other routers in the network, it performs synchronization of BIRD's routing
1775
tables with the OS kernel. Basically, it sends all routing table updates to the kernel
1776
and from time to time it scans the kernel tables to see whether some routes have
1777
disappeared (for example due to unnoticed up/down transition of an interface)
1778
or whether an `alien' route has been added by someone else (depending on the
1779
<cf/learn/ switch, such routes are either ignored or accepted to our
1780
table).
1781

    
1782
<p>Unfortunately, there is one thing that makes the routing table
1783
synchronization a bit more complicated. In the kernel routing table
1784
there are also device routes for directly connected networks. These
1785
routes are usually managed by OS itself (as a part of IP address
1786
configuration) and we don't want to touch that.  They are completely
1787
ignored during the scan of the kernel tables and also the export of
1788
device routes from BIRD tables to kernel routing tables is restricted
1789
to prevent accidental interference. This restriction can be disabled using
1790
<cf/device routes/ switch.
1791

    
1792
<p>If your OS supports only a single routing table, you can configure
1793
only one instance of the Kernel protocol. If it supports multiple
1794
tables (in order to allow policy routing; such an OS is for example
1795
Linux), you can run as many instances as you want, but each of them
1796
must be connected to a different BIRD routing table and to a different
1797
kernel table.
1798

    
1799
<p>Because the kernel protocol is partially integrated with the
1800
connected routing table, there are two limitations - it is not
1801
possible to connect more kernel protocols to the same routing table
1802
and changing route destination/gateway in an export
1803
filter of a kernel protocol does not work. Both limitations can be
1804
overcome using another routing table and the pipe protocol.
1805

    
1806
<sect1>Configuration
1807

    
1808
<p><descrip>
1809
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1810
	routing tables when it exits (instead of cleaning them up).
1811
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1812
	kernel routing table.
1813
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1814
	routing tables by other routing daemons or by the system administrator.
1815
	This is possible only on systems which support identification of route
1816
	authorship.
1817

    
1818
	<tag>device routes <m/switch/</tag> Enable export of device
1819
	routes to the kernel routing table. By default, such routes
1820
	are rejected (with the exception of explicitly configured
1821
	device routes from the static protocol) regardless of the
1822
	export filter to protect device routes in kernel routing table
1823
	(managed by OS itself) from accidental overwriting or erasing.
1824

    
1825
	<tag>kernel table <m/number/</tag> Select which kernel table should
1826
	this particular instance of the Kernel protocol work with. Available
1827
	only on systems supporting multiple routing tables.
1828
</descrip>
1829

    
1830
<sect1>Attributes
1831

    
1832
<p>The Kernel protocol defines several attributes. These attributes
1833
are translated to appropriate system (and OS-specific) route attributes.
1834
We support these attributes:
1835

    
1836
<descrip>
1837
	<tag>int <cf/krt_source/</tag> The original source of the imported
1838
	kernel route.  The value is system-dependent. On Linux, it is
1839
	a value of the protocol field of the route. See
1840
	/etc/iproute2/rt_protos for common values.  On BSD, it is
1841
	based on STATIC and PROTOx flags. The attribute is read-only.
1842

    
1843
	<tag>int <cf/krt_metric/</tag> The kernel metric of
1844
	the route.  When multiple same routes are in a kernel routing
1845
	table, the Linux kernel chooses one with lower metric.
1846

    
1847
	<tag>ip <cf/krt_prefsrc/</tag> (Linux) The preferred source address.
1848
 	Used in source address selection for outgoing packets. Have to
1849
 	be one of IP addresses of the router.
1850

    
1851
	<tag>int <cf/krt_realm/</tag> (Linux) The realm of the route. Can be
1852
	used for traffic classification.
1853
</descrip>
1854

    
1855
<sect1>Example
1856

    
1857
<p>A simple configuration can look this way:
1858

    
1859
<p><code>
1860
protocol kernel {
1861
	export all;
1862
}
1863
</code>
1864

    
1865
<p>Or for a system with two routing tables:
1866

    
1867
<p><code>
1868
protocol kernel {		# Primary routing table
1869
	learn;			# Learn alien routes from the kernel
1870
	persist;		# Don't remove routes on bird shutdown
1871
	scan time 10;		# Scan kernel routing table every 10 seconds
1872
	import all;
1873
	export all;
1874
}
1875

    
1876
protocol kernel {		# Secondary routing table
1877
	table auxtable;
1878
	kernel table 100;
1879
	export all;
1880
}
1881
</code>
1882

    
1883
<sect>OSPF
1884

    
1885
<sect1>Introduction
1886

    
1887
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
1888
protocol. The current IPv4 version (OSPFv2) is defined in RFC
1889
2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> and
1890
the current IPv6 version (OSPFv3) is defined in RFC 5340<htmlurl
1891
url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt">  It's a link state
1892
(a.k.a. shortest path first) protocol -- each router maintains a
1893
database describing the autonomous system's topology. Each participating
1894
router has an identical copy of the database and all routers run the
1895
same algorithm calculating a shortest path tree with themselves as a
1896
root. OSPF chooses the least cost path as the best path.
1897

    
1898
<p>In OSPF, the autonomous system can be split to several areas in order
1899
to reduce the amount of resources consumed for exchanging the routing
1900
information and to protect the other areas from incorrect routing data.
1901
Topology of the area is hidden to the rest of the autonomous system.
1902

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

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

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

    
1920
<sect1>Configuration
1921

    
1922
<p>In the main part of configuration, there can be multiple definitions of
1923
OSPF areas, each with a different id. These definitions includes many other
1924
switches and multiple definitions of interfaces. Definition of interface
1925
may contain many switches and constant definitions and list of neighbors
1926
on nonbroadcast networks.
1927

    
1928
<code>
1929
protocol ospf &lt;name&gt; {
1930
	rfc1583compat &lt;switch&gt;;
1931
	stub router &lt;switch&gt;;
1932
	tick &lt;num&gt;;
1933
	ecmp &lt;switch&gt; [limit &lt;num&gt;];
1934
	area &lt;id&gt; {
1935
		stub;
1936
		nssa;
1937
		summary &lt;switch&gt;;
1938
		default nssa &lt;switch&gt;;
1939
		default cost &lt;num&gt;;
1940
		default cost2 &lt;num&gt;;
1941
		translator &lt;switch&gt;;
1942
		translator stability &lt;num&gt;;
1943

    
1944
                networks {
1945
			&lt;prefix&gt;;
1946
			&lt;prefix&gt; hidden;
1947
		}
1948
                external {
1949
			&lt;prefix&gt;;
1950
			&lt;prefix&gt; hidden;
1951
			&lt;prefix&gt; tag &lt;num&gt;;
1952
		}
1953
		stubnet &lt;prefix&gt;;
1954
		stubnet &lt;prefix&gt; {
1955
			hidden &lt;switch&gt;;
1956
			summary &lt;switch&gt;;
1957
			cost &lt;num&gt;;
1958
		}
1959
		interface &lt;interface pattern&gt; [instance &lt;num&gt;] {
1960
			cost &lt;num&gt;;
1961
			stub &lt;switch&gt;;
1962
			hello &lt;num&gt;;
1963
			poll &lt;num&gt;;
1964
			retransmit &lt;num&gt;;
1965
			priority &lt;num&gt;;
1966
			wait &lt;num&gt;;
1967
			dead count &lt;num&gt;;
1968
			dead &lt;num&gt;;
1969
			rx buffer [normal|large|&lt;num&gt;];
1970
			type [broadcast|bcast|pointopoint|ptp|
1971
				nonbroadcast|nbma|pointomultipoint|ptmp];
1972
			strict nonbroadcast &lt;switch&gt;;
1973
			real broadcast &lt;switch&gt;;
1974
			ptp netmask &lt;switch&gt;;
1975
			check link &lt;switch&gt;;
1976
			ecmp weight &lt;num&gt;;
1977
			ttl security [&lt;switch&gt;; | tx only]
1978
			tx class|dscp &lt;num&gt;;
1979
			tx priority &lt;num&gt;;
1980
			authentication [none|simple|cryptographic];
1981
			password "&lt;text&gt;";
1982
			password "&lt;text&gt;" {
1983
				id &lt;num&gt;;
1984
				generate from "&lt;date&gt;";
1985
				generate to "&lt;date&gt;";
1986
				accept from "&lt;date&gt;";
1987
				accept to "&lt;date&gt;";
1988
			};
1989
			neighbors {
1990
				&lt;ip&gt;;
1991
				&lt;ip&gt; eligible;
1992
			};
1993
		};
1994
		virtual link &lt;id&gt; [instance &lt;num&gt;] {
1995
			hello &lt;num&gt;;
1996
			retransmit &lt;num&gt;;
1997
			wait &lt;num&gt;;
1998
			dead count &lt;num&gt;;
1999
			dead &lt;num&gt;;
2000
			authentication [none|simple|cryptographic];
2001
			password "&lt;text&gt;";
2002
		};
2003
	};
2004
}
2005
</code>
2006

    
2007
<descrip>
2008
	<tag>rfc1583compat <M>switch</M></tag>
2009
	 This option controls compatibility of routing table
2010
	 calculation with RFC 1583<htmlurl
2011
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
2012
	 value is no.
2013

    
2014
	<tag>stub router <M>switch</M></tag>
2015
	 This option configures the router to be a stub router, i.e.,
2016
	 a router that participates in the OSPF topology but does not
2017
	 allow transit traffic. In OSPFv2, this is implemented by
2018
	 advertising maximum metric for outgoing links, as suggested
2019
	 by RFC 3137<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3137.txt">.
2020
	 In OSPFv3, the stub router behavior is announced by clearing
2021
	 the R-bit in the router LSA. Default value is no.
2022

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

    
2029
	<tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
2030
	 This option specifies whether OSPF is allowed to generate
2031
	 ECMP (equal-cost multipath) routes. Such routes are used when
2032
	 there are several directions to the destination, each with
2033
	 the same (computed) cost. This option also allows to specify
2034
	 a limit on maximal number of nexthops in one route. By
2035
	 default, ECMP is disabled.  If enabled, default value of the
2036
	 limit is 16.
2037

    
2038
	<tag>area <M>id</M></tag>
2039
	 This defines an OSPF area with given area ID (an integer or an IPv4
2040
	 address, similarly to a router ID). The most important area is
2041
	 the backbone (ID 0) to which every other area must be connected.
2042

    
2043
	<tag>stub</tag>
2044
	 This option configures the area to be a stub area. External
2045
	 routes are not flooded into stub areas. Also summary LSAs can be
2046
	 limited in stub areas (see option <cf/summary/).
2047
	 By default, the area is not a stub area.
2048

    
2049
	<tag>nssa</tag>
2050
	 This option configures the area to be a NSSA (Not-So-Stubby
2051
	 Area). NSSA is a variant of a stub area which allows a
2052
	 limited way of external route propagation. Global external
2053
	 routes are not propagated into a NSSA, but an external route
2054
	 can be imported into NSSA as a (area-wide) NSSA-LSA (and
2055
	 possibly translated and/or aggregated on area boundary).
2056
	 By default, the area is not NSSA.
2057

    
2058
	<tag>summary <M>switch</M></tag>
2059
	 This option controls propagation of summary LSAs into stub or
2060
	 NSSA areas. If enabled, summary LSAs are propagated as usual,
2061
	 otherwise just the default summary route (0.0.0.0/0) is
2062
	 propagated (this is sometimes called totally stubby area). If
2063
	 a stub area has more area boundary routers, propagating
2064
	 summary LSAs could lead to more efficient routing at the cost
2065
	 of larger link state database. Default value is no.
2066

    
2067
	<tag>default nssa <M>switch</M></tag>
2068
 	 When <cf/summary/ option is enabled, default summary route is
2069
	 no longer propagated to the NSSA. In that case, this option
2070
	 allows to originate default route as NSSA-LSA to the NSSA.
2071
	 Default value is no.
2072

    
2073
	<tag>default cost <M>num</M></tag>
2074
	 This option controls the cost of a default route propagated to
2075
	 stub and NSSA areas. Default value is 1000.
2076

    
2077
	<tag>default cost2 <M>num</M></tag>
2078
	 When a default route is originated as NSSA-LSA, its cost
2079
	 can use either type 1 or type 2 metric. This option allows
2080
	 to specify the cost of a default route in type 2 metric.
2081
	 By default, type 1 metric (option <cf/default cost/) is used.
2082

    
2083
	<tag>translator <M>switch</M></tag>
2084
	 This option controls translation of NSSA-LSAs into external
2085
	 LSAs. By default, one translator per NSSA is automatically
2086
	 elected from area boundary routers. If enabled, this area
2087
	 boundary router would unconditionally translate all NSSA-LSAs
2088
	 regardless of translator election. Default value is no.
2089

    
2090
	<tag>translator stability <M>num</M></tag>
2091
	 This option controls the translator stability interval (in
2092
	 seconds). When the new translator is elected, the old one
2093
	 keeps translating until the interval is over. Default value
2094
	 is 40.
2095

    
2096
	<tag>networks { <m/set/ }</tag>
2097
         Definition of area IP ranges. This is used in summary LSA origination.
2098
	 Hidden networks are not propagated into other areas.
2099

    
2100
	<tag>external { <m/set/ }</tag>
2101
         Definition of external area IP ranges for NSSAs. This is used
2102
	 for NSSA-LSA translation. Hidden networks are not translated
2103
	 into external LSAs. Networks can have configured route tag.
2104

    
2105
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
2106
	 Stub networks are networks that are not transit networks
2107
	 between OSPF routers. They are also propagated through an
2108
	 OSPF area as a part of a link state database. By default,
2109
	 BIRD generates a stub network record for each primary network
2110
	 address on each OSPF interface that does not have any OSPF
2111
	 neighbors, and also for each non-primary network address on
2112
	 each OSPF interface. This option allows to alter a set of
2113
	 stub networks propagated by this router. 
2114

    
2115
	 Each instance of this option adds a stub network with given
2116
	 network prefix to the set of propagated stub network, unless
2117
	 option <cf/hidden/ is used. It also suppresses default stub
2118
	 networks for given network prefix. When option
2119
	 <cf/summary/ is used, also default stub networks that are
2120
	 subnetworks of given stub network are suppressed. This might
2121
	 be used, for example, to aggregate generated stub networks.
2122
	 
2123
	<tag>interface <M>pattern</M> [instance <m/num/]</tag>
2124
	 Defines that the specified interfaces belong to the area being defined.
2125
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
2126
	 In OSPFv3, you can specify instance ID for that interface
2127
	 description, so it is possible to have several instances of
2128
	 that interface with different options or even in different areas.
2129

    
2130
	<tag>virtual link <M>id</M> [instance <m/num/]</tag>
2131
	 Virtual link to router with the router id. Virtual link acts
2132
         as a point-to-point interface belonging to backbone. The
2133
         actual area is used as transport area. This item cannot be in
2134
         the backbone. In OSPFv3, you could also use several virtual
2135
         links to one destination with different instance IDs.
2136

    
2137
	<tag>cost <M>num</M></tag>
2138
	 Specifies output cost (metric) of an interface. Default value is 10.
2139

    
2140
	<tag>stub <M>switch</M></tag>
2141
	 If set to interface it does not listen to any packet and does not send
2142
	 any hello. Default value is no.
2143

    
2144
	<tag>hello <M>num</M></tag>
2145
	 Specifies interval in seconds between sending of Hello messages. Beware, all
2146
	 routers on the same network need to have the same hello interval.
2147
	 Default value is 10.
2148

    
2149
	<tag>poll <M>num</M></tag>
2150
	 Specifies interval in seconds between sending of Hello messages for
2151
	 some neighbors on NBMA network. Default value is 20.
2152

    
2153
	<tag>retransmit <M>num</M></tag>
2154
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
2155
	 Default value is 5.
2156

    
2157
        <tag>priority <M>num</M></tag>
2158
	 On every multiple access network (e.g., the Ethernet) Designed Router
2159
	 and Backup Designed router are elected. These routers have some
2160
	 special functions in the flooding process. Higher priority increases
2161
	 preferences in this election. Routers with priority 0 are not
2162
	 eligible. Default value is 1.
2163

    
2164
	<tag>wait <M>num</M></tag>
2165
	 After start, router waits for the specified number of seconds between starting
2166
	 election and building adjacency. Default value is 40.
2167
	 
2168
	<tag>dead count <M>num</M></tag>
2169
	 When the router does not receive any messages from a neighbor in
2170
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
2171

    
2172
	<tag>dead <M>num</M></tag>
2173
	 When the router does not receive any messages from a neighbor in
2174
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
2175
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
2176

    
2177
	<tag>rx buffer <M>num</M></tag>
2178
	 This sets the size of buffer used for receiving packets. The buffer should
2179
	 be bigger than maximal size of any packets. Value NORMAL (default)
2180
	 means 2*MTU, value LARGE means maximal allowed packet - 65535.
2181

    
2182
	<tag>type broadcast|bcast</tag>
2183
	 BIRD detects a type of a connected network automatically, but
2184
	 sometimes it's convenient to force use of a different type
2185
	 manually. On broadcast networks (like ethernet), flooding
2186
	 and Hello messages are sent using multicasts (a single packet
2187
	 for all the neighbors). A designated router is elected and it
2188
	 is responsible for synchronizing the link-state databases and
2189
	 originating network LSAs. This network type cannot be used on
2190
	 physically NBMA networks and on unnumbered networks (networks
2191
	 without proper IP prefix).
2192

    
2193
	<tag>type pointopoint|ptp</tag>
2194
	 Point-to-point networks connect just 2 routers together. No
2195
	 election is performed and no network LSA is originated, which
2196
	 makes it simpler and faster to establish. This network type
2197
	 is useful not only for physically PtP ifaces (like PPP or
2198
	 tunnels), but also for broadcast networks used as PtP links.
2199
	 This network type cannot be used on physically NBMA networks.
2200

    
2201
	<tag>type nonbroadcast|nbma</tag>
2202
	 On NBMA networks, the packets are sent to each neighbor
2203
	 separately because of lack of multicast capabilities.
2204
	 Like on broadcast networks, a designated router is elected,
2205
	 which plays a central role in propagation of LSAs.
2206
	 This network type cannot be used on unnumbered networks.
2207

    
2208
	<tag>type pointomultipoint|ptmp</tag>
2209
	 This is another network type designed to handle NBMA
2210
	 networks. In this case the NBMA network is treated as a
2211
	 collection of PtP links. This is useful if not every pair of
2212
	 routers on the NBMA network has direct communication, or if
2213
	 the NBMA network is used as an (possibly unnumbered) PtP
2214
	 link.
2215

    
2216
	<tag>strict nonbroadcast <M>switch</M></tag>
2217
	 If set, don't send hello to any undefined neighbor. This switch
2218
	 is ignored on other than NBMA or PtMP networks. Default value is no.
2219

    
2220
	<tag>real broadcast <m/switch/</tag>
2221
	 In <cf/type broadcast/ or <cf/type ptp/ network
2222
	 configuration, OSPF packets are sent as IP multicast
2223
	 packets. This option changes the behavior to using
2224
	 old-fashioned IP broadcast packets. This may be useful as a
2225
	 workaround if IP multicast for some reason does not work or
2226
	 does not work reliably. This is a non-standard option and
2227
	 probably is not interoperable with other OSPF
2228
	 implementations. Default value is no.
2229

    
2230
	<tag>ptp netmask <m/switch/</tag>
2231
	 In <cf/type ptp/ network configurations, OSPFv2
2232
	 implementations should ignore received netmask field in hello
2233
	 packets and should send hello packets with zero netmask field
2234
	 on unnumbered PtP links. But some OSPFv2 implementations
2235
	 perform netmask checking even for PtP links. This option
2236
	 specifies whether real netmask will be used in hello packets
2237
	 on <cf/type ptp/ interfaces. You should ignore this option
2238
	 unless you meet some compatibility problems related to this
2239
	 issue. Default value is no for unnumbered PtP links, yes
2240
	 otherwise.
2241

    
2242
	<tag>check link <M>switch</M></tag>
2243
	 If set, a hardware link state (reported by OS) is taken into
2244
	 consideration. When a link disappears (e.g. an ethernet cable is
2245
	 unplugged), neighbors are immediately considered unreachable
2246
	 and only the address of the iface (instead of whole network
2247
	 prefix) is propagated. It is possible that some hardware
2248
	 drivers or platforms do not implement this feature. Default value is no.
2249

    
2250
	<tag>ttl security [<m/switch/ | tx only]</tag>
2251
	 TTL security is a feature that protects routing protocols
2252
	 from remote spoofed packets by using TTL 255 instead of TTL 1
2253
	 for protocol packets destined to neighbors. Because TTL is
2254
	 decremented when packets are forwarded, it is non-trivial to
2255
	 spoof packets with TTL 255 from remote locations. Note that
2256
	 this option would interfere with OSPF virtual links.
2257

    
2258
	 If this option is enabled, the router will send OSPF packets
2259
	 with TTL 255 and drop received packets with TTL less than
2260
	 255. If this option si set to <cf/tx only/, TTL 255 is used
2261
	 for sent packets, but is not checked for received
2262
	 packets. Default value is no.
2263

    
2264
	<tag>tx class|dscp|priority <m/num/</tag>
2265
         These options specify the ToS/DiffServ/Traffic class/Priority
2266
         of the outgoing OSPF packets. See <ref id="dsc-prio" name="tx
2267
         class"> common option for detailed description.
2268

    
2269
	<tag>ecmp weight <M>num</M></tag>
2270
	 When ECMP (multipath) routes are allowed, this value specifies
2271
	 a relative weight used for nexthops going through the iface.
2272
	 Allowed values are 1-256. Default value is 1.
2273

    
2274
	<tag>authentication none</tag>
2275
	 No passwords are sent in OSPF packets. This is the default value.
2276

    
2277
	<tag>authentication simple</tag>
2278
	 Every packet carries 8 bytes of password. Received packets
2279
	 lacking this password are ignored. This authentication mechanism is
2280
	 very weak.
2281

    
2282
	<tag>authentication cryptographic</tag>
2283
	 16-byte long MD5 digest is appended to every packet. For the digest
2284
         generation 16-byte long passwords are used. Those passwords are 
2285
         not sent via network, so this mechanism is quite secure.
2286
         Packets can still be read by an attacker.
2287

    
2288
	<tag>password "<M>text</M>"</tag>
2289
	 An 8-byte or 16-byte password used for authentication.
2290
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
2291

    
2292
	<tag>neighbors { <m/set/ } </tag>
2293
	 A set of neighbors to which Hello messages on NBMA or PtMP
2294
	 networks are to be sent. For NBMA networks, some of them
2295
	 could be marked as eligible. In OSPFv3, link-local addresses
2296
	 should be used, using global ones is possible, but it is
2297
	 nonstandard and might be problematic. And definitely,
2298
	 link-local and global addresses should not be mixed.
2299

    
2300
</descrip>
2301

    
2302
<sect1>Attributes
2303

    
2304
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
2305
Metric is ranging from 1 to infinity (65535).
2306
External routes use <cf/metric type 1/ or <cf/metric type 2/.
2307
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
2308
<cf/metric of type 2/ is always longer
2309
than any <cf/metric of type 1/ or any <cf/internal metric/.
2310
<cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute
2311
<cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/.
2312
If you specify both metrics only metric1 is used.
2313

    
2314
Each external route can also carry attribute <cf/ospf_tag/ which is a
2315
32-bit integer which is used when exporting routes to other protocols;
2316
otherwise, it doesn't affect routing inside the OSPF domain at all.
2317
The fourth attribute <cf/ospf_router_id/ is a router ID of the router
2318
advertising that route/network. This attribute is read-only. Default
2319
is <cf/ospf_metric2 = 10000/ and <cf/ospf_tag = 0/.
2320

    
2321
<sect1>Example
2322

    
2323
<p>
2324

    
2325
<code>
2326
protocol ospf MyOSPF {
2327
        rfc1583compat yes;
2328
        tick 2;
2329
	export filter {
2330
		if source = RTS_BGP then {
2331
			ospf_metric1 = 100;
2332
			accept;
2333
		}
2334
		reject;
2335
	};
2336
	area 0.0.0.0 {
2337
		interface "eth*" {
2338
			cost 11;
2339
			hello 15;
2340
			priority 100;
2341
			retransmit 7;
2342
			authentication simple;
2343
			password "aaa";
2344
		};
2345
		interface "ppp*" {
2346
			cost 100;
2347
			authentication cryptographic;
2348
			password "abc" {
2349
				id 1;
2350
				generate to "22-04-2003 11:00:06";
2351
				accept from "17-01-2001 12:01:05";
2352
			};
2353
			password "def" {
2354
				id 2;
2355
				generate to "22-07-2005 17:03:21";
2356
				accept from "22-02-2001 11:34:06";
2357
			};
2358
		};
2359
		interface "arc0" {
2360
			cost 10;
2361
			stub yes;
2362
		};
2363
		interface "arc1";
2364
	};
2365
	area 120 {
2366
		stub yes;
2367
		networks {
2368
			172.16.1.0/24;
2369
			172.16.2.0/24 hidden;
2370
		}
2371
		interface "-arc0" , "arc*" {
2372
			type nonbroadcast;
2373
			authentication none;
2374
			strict nonbroadcast yes;
2375
			wait 120;
2376
			poll 40;
2377
			dead count 8;
2378
			neighbors {
2379
				192.168.120.1 eligible;
2380
				192.168.120.2;
2381
				192.168.120.10;
2382
			};
2383
		};
2384
	};
2385
}
2386
</code>
2387

    
2388
<sect>Pipe
2389

    
2390
<sect1>Introduction
2391

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

    
2399
<p>The Pipe protocol may work in the transparent mode mode or in the opaque mode.
2400
In the transparent mode, the Pipe protocol retransmits all routes from
2401
one table to the other table, retaining their original source and
2402
attributes.  If import and export filters are set to accept, then both
2403
tables would have the same content. The transparent mode is the default mode.
2404

    
2405
<p>In the opaque mode, the Pipe protocol retransmits optimal route
2406
from one table to the other table in a similar way like other
2407
protocols send and receive routes. Retransmitted route will have the
2408
source set to the Pipe protocol, which may limit access to protocol
2409
specific route attributes. This mode is mainly for compatibility, it
2410
is not suggested for new configs. The mode can be changed by
2411
<tt/mode/ option.
2412

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

    
2424
<sect1>Configuration
2425

    
2426
<p><descrip>
2427
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
2428
	primary one is selected by the <cf/table/ keyword.
2429

    
2430
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
2431
</descrip>
2432

    
2433
<sect1>Attributes
2434

    
2435
<p>The Pipe protocol doesn't define any route attributes.
2436

    
2437
<sect1>Example
2438

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

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

    
2453
<code>
2454
table as1;				# Define the tables
2455
table as2;
2456

    
2457
protocol kernel kern1 {			# Synchronize them with the kernel
2458
	table as1;
2459
	kernel table 1;
2460
}
2461

    
2462
protocol kernel kern2 {
2463
	table as2;
2464
	kernel table 2;
2465
}
2466

    
2467
protocol bgp bgp1 {			# The outside connections
2468
	table as1;
2469
	local as 1;
2470
	neighbor 192.168.0.1 as 1001;
2471
	export all;
2472
	import all;
2473
}
2474

    
2475
protocol bgp bgp2 {
2476
	table as2;
2477
	local as 2;
2478
	neighbor 10.0.0.1 as 1002;
2479
	export all;
2480
	import all;
2481
}
2482

    
2483
protocol pipe {				# The Pipe
2484
	table as1;
2485
	peer table as2;
2486
	export filter {
2487
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
2488
			if preference>10 then preference = preference-10;
2489
			if source=RTS_BGP then bgp_path.prepend(1);
2490
			accept;
2491
		}
2492
		reject;
2493
	};
2494
	import filter {
2495
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
2496
			if preference>10 then preference = preference-10;
2497
			if source=RTS_BGP then bgp_path.prepend(2);
2498
			accept;
2499
		}
2500
		reject;
2501
	};
2502
}
2503
</code>
2504

    
2505
<sect>RAdv
2506

    
2507
<sect1>Introduction
2508

    
2509
<p>The RAdv protocol is an implementation of Router Advertisements,
2510
which are used in the IPv6 stateless autoconfiguration. IPv6 routers
2511
send (in irregular time intervals or as an answer to a request)
2512
advertisement packets to connected networks. These packets contain
2513
basic information about a local network (e.g. a list of network
2514
prefixes), which allows network hosts to autoconfigure network
2515
addresses and choose a default route. BIRD implements router behavior
2516
as defined in
2517
RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">
2518
and also the DNS extensions from
2519
RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">.
2520

    
2521
<sect1>Configuration
2522

    
2523
<p>There are several classes of definitions in RAdv configuration --
2524
interface definitions, prefix definitions and DNS definitions:
2525

    
2526
<descrip>
2527
	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag>
2528
	Interface definitions specify a set of interfaces on which the
2529
	protocol is activated and contain interface specific options.
2530
	See <ref id="dsc-iface" name="interface"> common options for
2531
	detailed description.
2532

    
2533
	<tag>prefix <m/prefix/ { <m/options/ }</tag>
2534
	Prefix definitions allow to modify a list of advertised
2535
	prefixes. By default, the advertised prefixes are the same as
2536
	the network prefixes assigned to the interface. For each
2537
	network prefix, the matching prefix definition is found and
2538
	its options are used. If no matching prefix definition is
2539
	found, the prefix is used with default options.
2540

    
2541
	Prefix definitions can be either global or interface-specific.
2542
	The second ones are part of interface options. The prefix
2543
	definition matching is done in the first-match style, when
2544
	interface-specific definitions are processed before global
2545
	definitions. As expected, the prefix definition is matching if
2546
	the network prefix is a subnet of the prefix in prefix
2547
	definition.
2548

    
2549
	<tag>rdnss { <m/options/ }</tag>
2550
	RDNSS definitions allow to specify a list of advertised
2551
	recursive DNS servers together with their options. As options
2552
	are seldom necessary, there is also a short variant <cf>rdnss
2553
	<m/address/</cf> that just specifies one DNS server. Multiple
2554
	definitions are cumulative. RDNSS definitions may also be
2555
	interface-specific when used inside interface options. By
2556
	default, interface uses both global and interface-specific
2557
	options, but that can be changed by <cf/rdnss local/ option.
2558

    
2559
	<tag>dnssl { <m/options/ }</tag>
2560
	DNSSL definitions allow to specify a list of advertised DNS
2561
	search domains together with their options. Like <cf/rdnss/
2562
	above, multiple definitions are cumulative, they can be used
2563
	also as interface-specific options and there is a short
2564
	variant <cf>dnssl <m/domain/</cf> that just specifies one DNS
2565
        search domain.
2566

    
2567
	<label id="dsc-trigger"> <tag>trigger <m/prefix/</tag>
2568
	RAdv protocol could be configured to change its behavior based
2569
	on availability of routes. When this option is used, the
2570
	protocol waits in suppressed state until a <it/trigger route/
2571
	(for the specified network) is exported to the protocol, the
2572
	protocol also returnsd to suppressed state if the
2573
	<it/trigger route/ disappears. Note that route export depends
2574
	on specified export filter, as usual. This option could be
2575
	used, e.g., for handling failover in multihoming scenarios.
2576

    
2577
	During suppressed state, router advertisements are generated,
2578
	but with some fields zeroed. Exact behavior depends on which
2579
	fields are zeroed, this can be configured by
2580
	<cf/sensitive/ option for appropriate fields. By default, just
2581
	<cf/default lifetime/ (also called <cf/router lifetime/) is
2582
	zeroed, which means hosts cannot use the router as a default
2583
	router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
2584
	also be configured as <cf/sensitive/ for a prefix, which would
2585
	cause autoconfigured IPs to be deprecated or even removed.
2586
</descrip>
2587

    
2588
<p>Interface specific options:
2589

    
2590
<descrip>
2591
	<tag>max ra interval <m/expr/</tag>
2592
	Unsolicited router advertisements are sent in irregular time
2593
	intervals. This option specifies the maximum length of these
2594
	intervals, in seconds. Valid values are 4-1800. Default: 600
2595

    
2596
	<tag>min ra interval <m/expr/</tag>
2597
	This option specifies the minimum length of that intervals, in
2598
	seconds. Must be at least 3 and at most 3/4 * <cf/max ra interval/.
2599
	Default: about 1/3 * <cf/max ra interval/.
2600

    
2601
	<tag>min delay <m/expr/</tag>
2602
	The minimum delay between two consecutive router advertisements,
2603
	in seconds. Default: 3
2604

    
2605
	<tag>managed <m/switch/</tag>
2606
	This option specifies whether hosts should use DHCPv6 for
2607
	IP address configuration. Default: no
2608

    
2609
	<tag>other config <m/switch/</tag>
2610
	This option specifies whether hosts should use DHCPv6 to
2611
	receive other configuration information. Default: no
2612

    
2613
	<tag>link mtu <m/expr/</tag>
2614
	This option specifies which value of MTU should be used by
2615
	hosts. 0 means unspecified. Default: 0
2616

    
2617
	<tag>reachable time <m/expr/</tag>
2618
	This option specifies the time (in milliseconds) how long
2619
	hosts should assume a neighbor is reachable (from the last
2620
	confirmation). Maximum is 3600000, 0 means unspecified.
2621
	Default 0.
2622

    
2623
	<tag>retrans timer <m/expr/</tag>
2624
	This option specifies the time (in milliseconds) how long
2625
	hosts should wait before retransmitting Neighbor Solicitation
2626
	messages. 0 means unspecified. Default 0.
2627

    
2628
	<tag>current hop limit <m/expr/</tag>
2629
	This option specifies which value of Hop Limit should be used
2630
	by hosts. Valid values are 0-255, 0 means unspecified. Default: 64
2631

    
2632
	<tag>default lifetime <m/expr/ [sensitive <m/switch/]</tag>
2633
	This option specifies the time (in seconds) how long (after
2634
	the receipt of RA) hosts may use the router as a default
2635
	router. 0 means do not use as a default router. For
2636
	<cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
2637
	Default: 3 * <cf/max ra interval/, <cf/sensitive/ yes.
2638

    
2639
	<tag>rdnss local <m/switch/</tag>
2640
	Use only local (interface-specific) RDNSS definitions for this
2641
	interface. Otherwise, both global and local definitions are
2642
	used. Could also be used to disable RDNSS for given interface
2643
	if no local definitons are specified. Default: no.
2644

    
2645
	<tag>dnssl local <m/switch/</tag>
2646
	Use only local DNSSL definitions for this interface. See
2647
	<cf/rdnss local/ option above. Default: no.
2648
</descrip>
2649

    
2650

    
2651
<p>Prefix specific options:
2652

    
2653
<descrip>
2654
	<tag>skip <m/switch/</tag>
2655
	This option allows to specify that given prefix should not be
2656
	advertised. This is useful for making exceptions from a
2657
	default policy of advertising all prefixes. Note that for
2658
	withdrawing an already advertised prefix it is more useful to
2659
	advertise it with zero valid lifetime. Default: no
2660

    
2661
	<tag>onlink <m/switch/</tag>
2662
	This option specifies whether hosts may use the advertised
2663
	prefix for onlink determination. Default: yes
2664

    
2665
	<tag>autonomous <m/switch/</tag>
2666
	This option specifies whether hosts may use the advertised
2667
	prefix for stateless autoconfiguration. Default: yes
2668

    
2669
	<tag>valid lifetime <m/expr/ [sensitive <m/switch/]</tag>
2670
	This option specifies the time (in seconds) how long (after
2671
	the receipt of RA) the prefix information is valid, i.e.,
2672
	autoconfigured IP addresses can be assigned and hosts with
2673
	that IP addresses are considered directly reachable. 0 means
2674
	the prefix is no longer valid. For <cf/sensitive/ option, see
2675
	<ref id="dsc-trigger" name="trigger">. Default: 86400 (1 day), <cf/sensitive/ no.
2676

    
2677
	<tag>preferred lifetime <m/expr/ [sensitive <m/switch/]</tag>
2678
	This option specifies the time (in seconds) how long (after
2679
	the receipt of RA) IP addresses generated from the prefix
2680
	using stateless autoconfiguration remain preferred. For
2681
	<cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
2682
	Default: 14400 (4 hours), <cf/sensitive/ no.
2683
</descrip>
2684

    
2685

    
2686
<p>RDNSS specific options:
2687

    
2688
<descrip>
2689
	<tag>ns <m/address/</tag>
2690
	This option specifies one recursive DNS server. Can be used
2691
	multiple times for multiple servers. It is mandatory to have
2692
	at least one <cf/ns/ option in <cf/rdnss/ definition.
2693

    
2694
	<tag>lifetime [mult] <m/expr/</tag>
2695
	This option specifies the time how long the RDNSS information
2696
        may be used by clients after the receipt of RA. It is
2697
        expressed either in seconds or (when <cf/mult/ is used) in
2698
        multiples of <cf/max ra interval/. Note that RDNSS information
2699
        is also invalidated when <cf/default lifetime/ expires. 0
2700
        means these addresses are no longer valid DNS servers.
2701
	Default: 3 * <cf/max ra interval/.
2702
</descrip>
2703

    
2704

    
2705
<p>DNSSL specific options:
2706

    
2707
<descrip>
2708
	<tag>domain <m/address/</tag>
2709
	This option specifies one DNS search domain. Can be used
2710
	multiple times for multiple domains. It is mandatory to have
2711
	at least one <cf/domain/ option in <cf/dnssl/ definition.
2712

    
2713
	<tag>lifetime [mult] <m/expr/</tag>
2714
	This option specifies the time how long the DNSSL information
2715
        may be used by clients after the receipt of RA. Details are
2716
	the same as for RDNSS <cf/lifetime/ option above.
2717
	Default: 3 * <cf/max ra interval/.
2718
</descrip>
2719

    
2720

    
2721
<sect1>Example
2722

    
2723
<p><code>
2724
protocol radv {
2725
	interface "eth2" {
2726
		max ra interval 5;	# Fast failover with more routers
2727
		managed yes;		# Using DHCPv6 on eth2
2728
		prefix ::/0 {
2729
			autonomous off;	# So do not autoconfigure any IP
2730
		};
2731
	};
2732

    
2733
	interface "eth*";		# No need for any other options
2734

    
2735
	prefix 2001:0DB8:1234::/48 {
2736
		preferred lifetime 0;	# Deprecated address range
2737
	};
2738

    
2739
	prefix 2001:0DB8:2000::/48 {
2740
		autonomous off;		# Do not autoconfigure
2741
	};
2742

    
2743
	rdnss 2001:0DB8:1234::10;	# Short form of RDNSS
2744

    
2745
	rdnss {
2746
		lifetime mult 10;
2747
		ns 2001:0DB8:1234::11;
2748
		ns 2001:0DB8:1234::12;
2749
	};
2750

    
2751
	dnssl {
2752
		lifetime 3600;
2753
		domain "abc.com";
2754
		domain "xyz.com";
2755
	};
2756
}
2757
</code>
2758

    
2759
<sect>RIP
2760

    
2761
<sect1>Introduction
2762

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

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

    
2780
<sect1>Configuration
2781

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

    
2784
<descrip>
2785
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
2786
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
2787
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
2788
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
2789
	  section. Default: none.
2790

    
2791
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
2792
	  be honored. (Always, when sent from a  host on a directly connected
2793
	  network or never.) Routing table updates are honored only from
2794
	  neighbors, that is not configurable. Default: never.
2795
</descrip>
2796

    
2797
<p>There are some options that can be specified per-interface:
2798

    
2799
<descrip>
2800
	<tag>metric <m/num/</tag>
2801
	  This option specifies the metric of the interface. Valid
2802

    
2803
	<tag>mode multicast|broadcast|quiet|nolisten|version1</tag>
2804
	  This option selects the mode for RIP to work in. If nothing is
2805
	  specified, RIP runs in multicast mode. <cf/version1/ is
2806
	  currently equivalent to <cf/broadcast/, and it makes RIP talk
2807
	  to a broadcast address even through multicast mode is
2808
	  possible. <cf/quiet/ option means that RIP will not transmit
2809
	  any periodic messages to this interface and <cf/nolisten/
2810
	  means that RIP will send to this interface butnot listen to it.
2811

    
2812
	<tag>ttl security [<m/switch/ | tx only]</tag>
2813
	 TTL security is a feature that protects routing protocols
2814
	 from remote spoofed packets by using TTL 255 instead of TTL 1
2815
	 for protocol packets destined to neighbors. Because TTL is
2816
	 decremented when packets are forwarded, it is non-trivial to
2817
	 spoof packets with TTL 255 from remote locations.
2818

    
2819
	 If this option is enabled, the router will send RIP packets
2820
	 with TTL 255 and drop received packets with TTL less than
2821
	 255. If this option si set to <cf/tx only/, TTL 255 is used
2822
	 for sent packets, but is not checked for received
2823
	 packets. Such setting does not offer protection, but offers
2824
	 compatibility with neighbors regardless of whether they use
2825
	 ttl security.
2826

    
2827
	 Note that for RIPng, TTL security is a standard behavior
2828
	 (required by RFC 2080), but BIRD uses <cf/tx only/ by
2829
	 default, for compatibility with older versions. For IPv4 RIP,
2830
	 default value is no.
2831

    
2832
	<tag>tx class|dscp|priority <m/num/</tag>
2833
          These options specify the ToS/DiffServ/Traffic class/Priority
2834
          of the outgoing RIP packets. See <ref id="dsc-prio" name="tx
2835
          class"> common option for detailed description.
2836
</descrip>
2837

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

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

    
2847
	<tag>infinity <M>number</M></tag>
2848
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
2849
	  even slower.
2850

    
2851
	<tag>period <M>number</M>
2852
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
2853
	  number will mean faster convergence but bigger network
2854
	  load. Do not use values lower than 12.
2855

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

    
2859
	<tag>garbage time <M>number</M>
2860
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
2861
</descrip>
2862

    
2863
<sect1>Attributes
2864

    
2865
<p>RIP defines two route attributes:
2866

    
2867
<descrip>
2868
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
2869
	When routes from different RIP instances are available and all of them have the same
2870
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
2871
	When importing a non-RIP route, the metric defaults to 5.
2872

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

    
2878
<sect1>Example
2879

    
2880
<p><code>
2881
protocol rip MyRIP_test {
2882
        debug all;
2883
        port 1520;
2884
        period 12;
2885
        garbage time 60;
2886
        interface "eth0" { metric 3; mode multicast; };
2887
	interface "eth*" { metric 2; mode broadcast; };
2888
        honor neighbor;
2889
        authentication none;
2890
        import filter { print "importing"; accept; };
2891
        export filter { print "exporting"; accept; };
2892
}
2893
</code>
2894

    
2895
<sect>Static
2896

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

    
2905
<p>There are five types of static routes: `classical' routes telling
2906
to forward packets to a neighboring router, multipath routes
2907
specifying several (possibly weighted) neighboring routers, device
2908
routes specifying forwarding to hosts on a directly connected network,
2909
recursive routes computing their nexthops by doing route table lookups
2910
for a given IP and special routes (sink, blackhole etc.) which specify
2911
a special action to be done instead of forwarding the packet.
2912

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

    
2918
<p>The Static protocol does not have many configuration options. The
2919
definition of the protocol contains mainly a list of static routes:
2920

    
2921
<descrip>
2922
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
2923
	a neighboring router.
2924
	<tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
2925
	Static multipath route. Contains several nexthops (gateways), possibly
2926
 	with their weights.
2927
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
2928
	route through an interface to hosts on a directly connected network.
2929
	<tag>route <m/prefix/ recursive <m/ip/</tag> Static recursive route,
2930
	its nexthop depends on a route table lookup for given IP address.
2931
	<tag>route <m/prefix/ blackhole|unreachable|prohibit</tag> Special routes
2932
	specifying to silently drop the packet, return it as unreachable or return
2933
	it as administratively prohibited. First two targets are also known
2934
	as <cf/drop/ and <cf/reject/.
2935

    
2936
	<tag>check link <m/switch/</tag>
2937
	If set, hardware link states of network interfaces are taken
2938
	into consideration.  When link disappears (e.g. ethernet cable
2939
	is unplugged), static routes directing to that interface are
2940
	removed. It is possible that some hardware drivers or
2941
	platforms do not implement this feature. Default: off.
2942

    
2943
	<tag>igp table <m/name/</tag> Specifies a table that is used
2944
	for route table lookups of recursive routes. Default: the
2945
	same table as the protocol is connected to.
2946
</descrip>
2947

    
2948
<p>Static routes have no specific attributes.
2949

    
2950
<p>Example static config might look like this:
2951

    
2952
<p><code>
2953
protocol static {
2954
	table testable;			 # Connect to a non-default routing table
2955
	route 0.0.0.0/0 via 198.51.100.130; # Default route
2956
	route 10.0.0.0/8 multipath	 # Multipath route
2957
		via 198.51.100.10 weight 2
2958
		via 198.51.100.20
2959
		via 192.0.2.1;
2960
	route 203.0.113.0/24 unreachable; # Sink route
2961
	route 10.2.0.0/24 via "arc0";	 # Secondary network
2962
}
2963
</code>
2964

    
2965
<chapt>Conclusions
2966

    
2967
<sect>Future work
2968

    
2969
<p>Although BIRD supports all the commonly used routing protocols,
2970
there are still some features which would surely deserve to be
2971
implemented in future versions of BIRD:
2972

    
2973
<itemize>
2974
<item>Opaque LSA's
2975
<item>Route aggregation and flap dampening
2976
<item>Multipath routes
2977
<item>Multicast routing protocols
2978
<item>Ports to other systems
2979
</itemize>
2980

    
2981
<sect>Getting more help
2982

    
2983
<p>If you use BIRD, you're welcome to join the bird-users mailing list
2984
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
2985
where you can share your experiences with the other users and consult
2986
your problems with the authors. To subscribe to the list, just send a
2987
<tt/subscribe bird-users/ command in a body of a mail to
2988
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
2989
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
2990

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

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

    
3001
<p><it/Good luck!/
3002

    
3003
</book>
3004

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