Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ f623ab98

History | View | Annotate | Download (129 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>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/bool/</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-pass">password "<m/password/" [ { id <m/num/; generate from <m/time/; generate to <m/time/; accept from <m/time/; accept to <m/time/; } ]</tag>
571
	Specifies a password that can be used by the protocol. Password option can
572
	be used more times to specify more passwords. If more passwords are
573
	specified, it is a protocol-dependent decision which one is really
574
	used. Specifying passwords does not mean that authentication is
575
	enabled, authentication can be enabled by separate, protocol-dependent
576
	<cf/authentication/ option.
577
	
578
	This option is allowed in OSPF and RIP protocols. BGP has also
579
	<cf/password/ option, but it is slightly different and described
580
	separately.
581

    
582
	Default: none.
583
</descrip>
584

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

    
587
<descrip>
588
	<tag>id <M>num</M></tag>
589
	 ID of the password, (0-255). If it's not used, BIRD will choose
590
	 ID based on an order of the password item in the interface. For
591
	 example, second password item in one interface will have default
592
	 ID 2. ID is used by some routing protocols to identify which
593
	 password was used to authenticate protocol packets.
594

    
595
	<tag>generate from "<m/time/"</tag>
596
	 The start time of the usage of the password for packet signing.
597
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
598

    
599
	<tag>generate to "<m/time/"</tag>
600
	 The last time of the usage of the password for packet signing.
601

    
602
	<tag>accept from "<m/time/"</tag>
603
	 The start time of the usage of the password for packet verification.
604

    
605
	<tag>accept to "<m/time/"</tag>
606
	 The last time of the usage of the password for packet verification.
607
</descrip>
608

    
609
<chapt>Remote control
610

    
611
<p>You can use the command-line client <file>birdc</file> to talk with
612
a running BIRD. Communication is done using a <file/bird.ctl/ UNIX
613
domain socket (unless changed with the <tt/-s/ option given to both
614
the server and the client). The commands can perform simple actions
615
such as enabling/disabling of protocols, telling BIRD to show various
616
information, telling it to show routing table filtered by filter, or
617
asking BIRD to reconfigure. Press <tt/?/ at any time to get online
618
help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
619
client, which allows just read-only commands (<cf/show .../). Option
620
<tt/-v/ can be passed to the client, to make it dump numeric return
621
codes along with the messages. You do not necessarily need to use
622
<file/birdc/ to talk to BIRD, your own applications could do that, too
623
-- the format of communication between BIRD and <file/birdc/ is stable
624
(see the programmer's documentation).
625

    
626
<p>There is also lightweight variant of BIRD client called
627
<file/birdcl/, which does not support command line editing and history
628
and has minimal dependencies. This is useful for running BIRD in
629
resource constrained environments, where Readline library (required
630
for regular BIRD client) is not available.
631

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

    
635
<p>Here is a brief list of supported functions:
636

    
637
<descrip>
638
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
639
	Dump contents of internal data structures to the debugging output.
640

    
641
	<tag>show status</tag>
642
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
643

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

    
647
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
648
	Show detailed information about OSPF interfaces.
649

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

    
653
	<tag>show ospf state [all] [<m/name/]</tag>
654
	Show detailed information about OSPF areas based on a content
655
	of the link-state database. It shows network topology, stub
656
	networks, aggregated networks and routers from other areas and
657
	external routes. The command shows information about reachable
658
	network nodes, use option <cf/all/ to show information about
659
	all network nodes in the link-state database.
660

    
661
	<tag>show ospf topology [all] [<m/name/]</tag>
662
	Show a topology of OSPF areas based on a content of the
663
	link-state database.  It is just a stripped-down version of
664
	'show ospf state'.
665

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

    
669
	<tag>show static [<m/name/]</tag>
670
	Show detailed information about static routes.
671

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

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

    
678
	<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>
679
	Show contents of a routing table (by default of the main one or
680
        the table attached to a respective protocol),
681
	that is routes, their metrics and (in case the <cf/all/ switch is given)
682
	all their attributes.
683

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

    
691
	<p>You can also ask for printing only routes processed and accepted by
692
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
693
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
694
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
695
	that are exported to the specified protocol. With <cf/preexport/, the
696
	export filter of the protocol is skipped.
697

    
698
	<p>You can also select just routes added by a specific protocol.
699
	<cf>protocol <m/p/</cf>.
700

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

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

    
708
	<tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
709
	Show contents of a ROA table (by default of the first one).
710
	You can specify a <m/prefix/ to print ROA entries for a
711
	specific network. If you use <cf>for <m/prefix/</cf>, you'll
712
	get all entries relevant for route validation of the network
713
	prefix; i.e., ROA entries whose prefixes cover the network
714
	prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA entries
715
	covered by the network prefix. You could also use <cf/as/ option
716
	to show just entries for given AS.
717

    
718
	<tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
719
	Add a new ROA entry to a ROA table. Such entry is called
720
	<it/dynamic/ compared to <it/static/ entries specified in the
721
	config file. These dynamic entries survive reconfiguration.
722

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

    
728
	<tag>flush roa [table <m/t/>]</tag>
729
	Remove all dynamic ROA entries from a ROA table.
730

    
731
	<tag>configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
732
	Reload configuration from a given file. BIRD will smoothly
733
	switch itself to the new configuration, protocols are
734
	reconfigured if possible, restarted otherwise. Changes in
735
	filters usually lead to restart of affected protocols.
736

    
737
	If <cf/soft/ option is used, changes in filters does not cause
738
	BIRD to restart affected protocols, therefore already accepted
739
	routes (according to old filters) would be still propagated,
740
	but new routes would be processed according to the new
741
	filters.
742

    
743
	If <cf/timeout/ option is used, config timer is activated. The
744
	new configuration could be either confirmed using
745
	<cf/configure confirm/ command, or it will be reverted to the
746
	old one when the config timer expires. This is useful for cases
747
	when reconfiguration breaks current routing and a router becames
748
	inaccessible for an administrator. The config timeout expiration is
749
	equivalent to <cf/configure undo/ command. The timeout duration
750
	could be specified, default is 300 s.
751

    
752
	<tag>configure confirm</tag>
753
	Deactivate the config undo timer and therefore confirm the current
754
	configuration.
755

    
756
	<tag>configure undo</tag>
757
	Undo the last configuration change and smoothly switch back to
758
	the previous (stored) configuration. If the last configuration
759
	change was soft, the undo change is also soft. There is only
760
	one level of undo, but in some specific cases when several
761
	reconfiguration requests are given immediately in a row and
762
	the intermediate ones are skipped then the undo also skips them back.
763

    
764
	<tag>configure check ["<m/config file/"]</tag>
765
	Read and parse given config file, but do not use it. useful
766
	for checking syntactic and some semantic validity of an config
767
	file.
768

    
769
	<tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
770
	Enable, disable or restart a given protocol instance,
771
	instances matching the <cf><m/pattern/</cf> or
772
	<cf/all/ instances.
773

    
774
	<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
775
	
776
	Reload a given protocol instance, that means re-import routes
777
	from the protocol instance and re-export preferred routes to
778
	the instance. If <cf/in/ or <cf/out/ options are used, the
779
	command is restricted to one direction (re-import or
780
	re-export).
781

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

    
787
	Re-export always succeeds, but re-import is protocol-dependent
788
	and might fail (for example, if BGP neighbor does not support
789
	route-refresh extension). In that case, re-export is also
790
	skipped. Note that for the pipe protocol, both directions are
791
	always reloaded together (<cf/in/ or <cf/out/ options are
792
	ignored in that case).
793

    
794
	<tag/down/
795
	Shut BIRD down.
796

    
797
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
798
	Control protocol debugging.
799
</descrip>
800

    
801
<chapt>Filters
802

    
803
<sect>Introduction
804

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

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

    
815
<code>
816
filter not_too_far
817
int var;
818
{
819
	if defined( rip_metric ) then
820
		var = rip_metric;
821
	else {
822
		var = 1;
823
		rip_metric = 1;
824
	}
825
	if rip_metric &gt; 10 then
826
		reject "RIP metric is too big";
827
	else
828
		accept "ok";
829
}
830
</code>
831

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

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

    
843
<code>
844
function name ()
845
int local_variable;
846
{
847
	local_variable = 5;
848
}
849

    
850
function with_parameters (int parameter)
851
{
852
	print parameter;
853
}
854
</code>
855

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

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

    
867
<p>A nice trick to debug filters is to use <cf>show route filter
868
<m/name/</cf> from the command line client. An example session might look
869
like:
870

    
871
<code>
872
pavel@bug:~/bird$ ./birdc -s bird.ctl
873
BIRD 0.0.0 ready.
874
bird> show route
875
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
876
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
877
127.0.0.0/8        dev lo [direct1 23:21] (240)
878
bird> show route ?
879
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
880
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
881
127.0.0.0/8        dev lo [direct1 23:21] (240)
882
bird>
883
</code>
884

    
885
<sect>Data types
886

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

    
890
<descrip>
891
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
892
	  <cf/false/. Boolean is the only type you can use in <cf/if/
893
	  statements.
894

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

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

    
902
	<tag/quad/ This is a dotted quad of numbers used to represent
903
	  router IDs (and others).  Each component can have a value
904
	  from 0 to 255. Literals of this type are written like IPv4
905
	  addresses.
906

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

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

    
917
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
918
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
919
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
920
	  operators on prefixes:
921
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
922
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
923

    
924
	<tag/ec/ This is a specialized type used to represent BGP
925
	  extended community values. It is essentially a 64bit value,
926
	  literals of this type are usually written as <cf>(<m/kind/,
927
	  <m/key/, <m/value/)</cf>, where <cf/kind/ is a kind of
928
	  extended community (e.g. <cf/rt/ / <cf/ro/ for a route
929
	  target / route origin communities), the format and possible
930
	  values of <cf/key/ and <cf/value/ are usually integers, but
931
	  it depends on the used kind. Similarly to pairs, ECs can be
932
	  constructed using expressions for <cf/key/ and
933
	  <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
934
	  <cf/myas/ is an integer variable).
935
 
936
	<tag/int|pair|quad|ip|prefix|ec|enum set/
937
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
938
	  but you can't modify them. Literals of type <cf>int set</cf> look like <cf>
939
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
940
	  sets.
941

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

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

    
953
	  You can also use expressions for int, pair and EC set values. However it must
954
	  be possible to evaluate these expressions before daemon boots. So you can use
955
	  only constants inside them. E.g.
956
	<code>
957
	 define one=1;
958
	 define myas=64500;
959
	 int set odds;
960
	 pair set ps;
961
	 ec set es;
962

    
963
	 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
964
	 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
965
	 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
966
	</code>
967

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

    
976
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
977
	  <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), 
978
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
979
	  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>
980
	  and all its supernets (network prefixes that contain it).
981

    
982
	  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
983
	  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
984
	  <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
985
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
986
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
987
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
988

    
989
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
990
	  in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
991
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
992
	  <cf>192.168.0.0/16{24,32}</cf>.
993

    
994
	<tag/enum/
995
	  Enumeration types are fixed sets of possibilities. You can't define your own
996
	  variables of such type, but some route attributes are of enumeration
997
	  type. Enumeration types are incompatible with each other.
998

    
999
	<tag/bgppath/
1000
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
1001
	  There are several special operators on bgppaths:
1002

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

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

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

    
1010
          <cf><m/P/.len</cf> returns the length of path <m/P/.
1011

    
1012
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
1013
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
1014
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
1015
          (for example <cf/bgp_path/).
1016

    
1017
	<tag/bgpmask/
1018
	  BGP masks are patterns used for BGP path matching
1019
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
1020
	  resemble wildcard patterns as used by UNIX shells. Autonomous
1021
	  system numbers match themselves, <cf/*/ matches any (even empty)
1022
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
1023
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
1024
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
1025
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
1026
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
1027
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
1028
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
1029

    
1030
	<tag/clist/
1031
	  Clist is similar to a set, except that unlike other sets, it
1032
	  can be modified. The type is used for community list (a set
1033
	  of pairs) and for cluster list (a set of quads). There exist
1034
	  no literals of this type. There are three special operators on
1035
	  clists:
1036

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

    
1042
          <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad)
1043
	  <m/P/ from clist <m/C/ and returns the result.  If clist
1044
	  <m/C/ does not contain item <m/P/, it does nothing.
1045
	  <m/P/ may also be a pair (or quad) set, in that case the
1046
	  operator deletes all items from clist <m/C/ that are also
1047
	  members of set <m/P/. Moreover, <m/P/ may also be a clist,
1048
	  which works analogously; i.e., it works as clist difference.
1049

    
1050
          <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist
1051
	  <m/C/ that are not members of pair (or quad) set <m/P/.
1052
	  I.e., <cf/filter/ do the same as <cf/delete/ with inverted
1053
	  set <m/P/. <m/P/ may also be a clist, which works analogously;
1054
	  i.e., it works as clist intersection.
1055

    
1056
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1057
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route
1058
          attribute (for example <cf/bgp_community/). Similarly for
1059
          <cf/delete/ and <cf/filter/.
1060

    
1061
	<tag/eclist/
1062
	  Eclist is a data type used for BGP extended community lists.
1063
	  Eclists are very similar to clists, but they are sets of ECs
1064
	  instead of pairs. The same operations (like <cf/add/,
1065
	  <cf/delete/, or <cf/&tilde;/ membership operator) can be
1066
	  used to modify or test eclists, with ECs instead of pairs as
1067
	  arguments.
1068
</descrip>
1069

    
1070
<sect>Operators
1071

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

    
1079
<p>There is one operator related to ROA infrastructure -
1080
<cf/roa_check()/. It examines a ROA table and does RFC 6483 route
1081
origin validation for a given network prefix. The basic usage
1082
is <cf>roa_check(<m/table/)</cf>, which checks current route (which
1083
should be from BGP to have AS_PATH argument) in the specified ROA
1084
table and returns ROA_UNKNOWN if there is no relevant ROA, ROA_VALID
1085
if there is a matching ROA, or ROA_INVALID if there are some relevant
1086
ROAs but none of them match. There is also an extended variant
1087
<cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to
1088
specify a prefix and an ASN as arguments.
1089

    
1090

    
1091
<sect>Control structures
1092

    
1093
<p>Filters support two control structures: conditions and case switches. 
1094

    
1095
<p>Syntax of a condition is: <cf>if
1096
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
1097
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
1098
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.
1099

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

    
1106
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
1107

    
1108
<code>
1109
case arg1 {
1110
	2: print "two"; print "I can do more commands without {}";
1111
	3 .. 5: print "three to five";
1112
	else: print "something else";
1113
}
1114

    
1115
if 1234 = i then printn "."; else { 
1116
  print "not 1234"; 
1117
  print "You need {} around multiple commands"; 
1118
}
1119
</code>
1120

    
1121
<sect>Route attributes
1122

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

    
1130
<descrip>
1131
	<tag><m/prefix/ net</tag>
1132
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
1133

    
1134
	<tag><m/enum/ scope</tag>
1135
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for
1136
	routes local to this host, <cf/SCOPE_LINK/ for those specific
1137
	for a physical link, <cf/SCOPE_SITE/ and
1138
	<cf/SCOPE_ORGANIZATION/ for private routes and
1139
	<cf/SCOPE_UNIVERSE/ for globally visible routes. This
1140
	attribute is not interpreted by BIRD and can be used to mark
1141
	routes in filters. The default value for new routes is
1142
	<cf/SCOPE_UNIVERSE/.
1143

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

    
1147
	<tag><m/ip/ from</tag>
1148
	The router which the route has originated from. Read-only.
1149
	
1150
	<tag><m/ip/ gw</tag>
1151
	Next hop packets routed using this route should be forwarded to.
1152

    
1153
	<tag><m/string/ proto</tag>
1154
	The name of the protocol which the route has been imported from. Read-only.
1155

    
1156
	<tag><m/enum/ source</tag>
1157
	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/.
1158

    
1159
	<tag><m/enum/ cast</tag>
1160

    
1161
	Route type (Currently <cf/RTC_UNICAST/ for normal routes,
1162
	<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will
1163
	be used in the future for broadcast, multicast and anycast
1164
	routes). Read-only.
1165

    
1166
	<tag><m/enum/ dest</tag>
1167
	Type of destination the packets should be sent to
1168
	(<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1169
	<cf/RTD_DEVICE/ for routing to a directly-connected network,
1170
	<cf/RTD_MULTIPATH/ for multipath destinations,
1171
	<cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1172
	<cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that
1173
	should be returned with ICMP host unreachable / ICMP
1174
	administratively prohibited messages). Can be changed, but
1175
	only to <cf/RTD_BLACKHOLE/, <cf/RTD_UNREACHABLE/ or
1176
	<cf/RTD_PROHIBIT/.
1177

    
1178
	<tag><m/int/ igp_metric</tag>
1179
	The optional attribute that can be used to specify a distance
1180
	to the network for routes that do not have a native protocol
1181
	metric attribute (like <cf/ospf_metric1/ for OSPF routes). It
1182
	is used mainly by BGP to compare internal distances to boundary
1183
	routers (see below). It is also used when the route is exported
1184
	to OSPF as a default value for OSPF type 1 metric.
1185
</descrip>
1186

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

    
1189
<sect>Other statements
1190

    
1191
<p>The following statements are available:
1192

    
1193
<descrip>
1194
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
1195

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

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

    
1200
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
1201
	Prints given expressions; useful mainly while debugging
1202
	filters. The <cf/printn/ variant does not terminate the line.
1203

    
1204
	<tag>quitbird</tag>
1205
	Terminates BIRD. Useful when debugging the filter interpreter.
1206
</descrip>
1207

    
1208
<chapt>Protocols
1209

    
1210
<sect>BGP
1211

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

    
1219
<p>BGP works in terms of autonomous systems (often abbreviated as
1220
AS). Each AS is a part of the network with common management and
1221
common routing policy. It is identified by a unique 16-bit number
1222
(ASN).  Routers within each AS usually exchange AS-internal routing
1223
information with each other using an interior gateway protocol (IGP,
1224
such as OSPF or RIP). Boundary routers at the border of
1225
the AS communicate global (inter-AS) network reachability information with
1226
their neighbors in the neighboring AS'es via exterior BGP (eBGP) and
1227
redistribute received information to other routers in the AS via
1228
interior BGP (iBGP).
1229

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

    
1235
<p>BIRD supports all requirements of the BGP4 standard as defined in
1236
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
1237
It also supports the community attributes
1238
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
1239
capability negotiation
1240
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
1241
MD5 password authentication
1242
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
1243
extended communities
1244
(RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">),
1245
route reflectors 
1246
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
1247
multiprotocol extensions
1248
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
1249
4B AS numbers 
1250
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">),
1251
and 4B AS numbers in extended communities
1252
(RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">).
1253

    
1254

    
1255
For IPv6, it uses the standard multiprotocol extensions defined in
1256
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
1257
including changes described in the
1258
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
1259
and applied to IPv6 according to
1260
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
1261

    
1262
<sect1>Route selection rules
1263

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

    
1270
<itemize>
1271
	<item>Prefer route with the highest Local Preference attribute.
1272
	<item>Prefer route with the shortest AS path.
1273
	<item>Prefer IGP origin over EGP and EGP origin over incomplete.
1274
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
1275
	<item>Prefer routes received via eBGP over ones received via iBGP.
1276
	<item>Prefer routes with lower internal distance to a boundary router.
1277
	<item>Prefer the route with the lowest value of router ID of the
1278
	advertising router.
1279
</itemize>
1280

    
1281
<sect1>IGP routing table
1282

    
1283
<p>BGP is mainly concerned with global network reachability and with
1284
routes to other autonomous systems. When such routes are redistributed
1285
to routers in the AS via BGP, they contain IP addresses of a boundary
1286
routers (in route attribute NEXT_HOP). BGP depends on existing IGP
1287
routing table with AS-internal routes to determine immediate next hops
1288
for routes and to know their internal distances to boundary routers
1289
for the purpose of BGP route selection. In BIRD, there is usually
1290
one routing table used for both IGP routes and BGP routes.
1291

    
1292
<sect1>Configuration
1293

    
1294
<p>Each instance of the BGP corresponds to one neighboring router.
1295
This allows to set routing policy and all the other parameters differently
1296
for each neighbor using the following configuration parameters:
1297

    
1298
<descrip>
1299
	<tag>local [<m/ip/] as <m/number/</tag> Define which AS we
1300
	are part of. (Note that contrary to other IP routers, BIRD is
1301
	able to act as a router located in multiple AS'es
1302
	simultaneously, but in such cases you need to tweak the BGP
1303
	paths manually in the filters to get consistent behavior.)
1304
	Optional <cf/ip/ argument specifies a source address,
1305
	equivalent to the <cf/source address/ option (see below).
1306
	This parameter is mandatory.
1307

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

    
1314
	<tag>multihop [<m/number/]</tag> Configure multihop BGP
1315
	session to a neighbor that isn't directly connected.
1316
	Accurately, this option should be used if the configured
1317
	neighbor IP address does not match with any local network
1318
	subnets. Such IP address have to be reachable through system
1319
	routing table. For multihop BGP it is recommended to
1320
	explicitly configure <cf/source address/ to have it
1321
	stable. Optional <cf/number/ argument can be used to specify
1322
	the number of hops (used for TTL). Note that the number of
1323
	networks (edges) in a path is counted, i.e. if two BGP
1324
	speakers are separated by one router, the number of hops is
1325
	2. Default: switched off.
1326

    
1327
	<tag>source address <m/ip/</tag> Define local address we
1328
	should use for next hop calculation and as a source address
1329
	for the BGP session. Default: the address of the local
1330
	end of the interface our neighbor is connected to.
1331

    
1332
	<tag>next hop self</tag> Avoid calculation of the Next Hop
1333
	attribute and always advertise our own source address as a
1334
	next hop.  This needs to be used only occasionally to
1335
	circumvent misconfigurations of other routers.  Default:
1336
	disabled.
1337

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

    
1343
	<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
1344
	in BGP-IPv6 sometimes contains just the global IPv6 address,
1345
	but sometimes it has to contain both global and link-local
1346
	IPv6 addresses. This option specifies what to do if BIRD have
1347
	to send both addresses but does not know link-local address.
1348
	This situation might happen when routes from other protocols
1349
	are exported to BGP, or when improper updates are received
1350
	from BGP peers.  <cf/self/ means that BIRD advertises its own
1351
	local address instead. <cf/drop/ means that BIRD skips that
1352
	prefixes and logs error. <cf/ignore/ means that BIRD ignores
1353
	the problem and sends just the global address (and therefore
1354
	forms improper BGP update). Default: <cf/self/, unless BIRD
1355
	is configured as a route server (option <cf/rs client/), in
1356
	that case default is <cf/ignore/, because route servers usually
1357
	do not forward packets themselves.
1358

    
1359
	<tag>gateway direct|recursive</tag>For received routes, their
1360
	<cf/gw/ (immediate next hop) attribute is computed from
1361
	received <cf/bgp_next_hop/ attribute. This option specifies
1362
	how it is computed. Direct mode means that the IP address from
1363
	<cf/bgp_next_hop/ is used if it is directly reachable,
1364
	otherwise the neighbor IP address is used. Recursive mode
1365
	means that the gateway is computed by an IGP routing table
1366
	lookup for the IP address from <cf/bgp_next_hop/. Recursive
1367
	mode is the behavior specified by the BGP standard. Direct
1368
	mode is simpler, does not require any routes in a routing
1369
	table, and was used in older versions of BIRD, but does not
1370
	handle well nontrivial iBGP setups and multihop.  Recursive
1371
	mode is incompatible with <ref id="dsc-sorted" name="sorted
1372
	tables">. Default: <cf/direct/ for singlehop eBGP,
1373
	<cf/recursive/ otherwise.
1374

    
1375
	<tag>igp table <m/name/</tag> Specifies a table that is used
1376
	as an IGP routing table. Default: the same as the table BGP is
1377
	connected to.
1378
	
1379
	<tag>ttl security <m/switch/</tag> Use GTSM (RFC 5082 - the
1380
	generalized TTL security mechanism). GTSM protects against
1381
	spoofed packets by ignoring received packets with a smaller
1382
	than expected TTL. To work properly, GTSM have to be enabled
1383
	on both sides of a BGP session. If both <cf/ttl security/ and
1384
	<cf/multihop/ options are enabled, <cf/multihop/ option should
1385
	specify proper hop value to compute expected TTL. Kernel
1386
	support required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD:
1387
	since long ago, IPv4 only. Note that full (ICMP protection,
1388
	for example) RFC 5082 support is provided by Linux
1389
	only. Default: disabled.
1390
	
1391
	<tag>password <m/string/</tag> Use this password for MD5 authentication
1392
	of BGP sessions. Default: no authentication. Password has to be set by
1393
	external utility (e.g. setkey(8)) on BSD systems.
1394

    
1395
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
1396
        initiating outgoing connections and accepting incoming
1397
        connections. In passive mode, outgoing connections are not
1398
        initiated. Default: off.
1399

    
1400
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
1401
	a route reflection client. Default: disabled.
1402

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

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

    
1419
	<tag>secondary <m/switch/</tag> Usually, if an import filter
1420
	rejects a selected route, no other route is propagated for
1421
	that network. This option allows to try the next route in
1422
	order until one that is accepted is found or all routes for
1423
	that network are rejected. This can be used for route servers
1424
	that need to propagate different tables to each client but do
1425
	not want to have these tables explicitly (to conserve memory).
1426
	This option requires that the connected routing table is
1427
	<ref id="dsc-sorted" name="sorted">. Default: off.
1428

    
1429
	<tag>enable route refresh <m/switch/</tag> When BGP speaker
1430
	changes its import filter, it has to re-examine all routes
1431
	received from its neighbor against the new filter. As these
1432
	routes might not be available, there is a BGP protocol
1433
	extension Route Refresh (specified in RFC 2918) that allows
1434
	BGP speaker to request re-advertisement of all routes from its
1435
	neighbor. This option specifies whether BIRD advertises this
1436
	capability and accepts such requests. Even when disabled, BIRD
1437
	can send route refresh requests. Default: on.
1438

    
1439
	<tag>interpret communities <m/switch/</tag> RFC 1997 demands
1440
	that BGP speaker should process well-known communities like
1441
	no-export (65535, 65281) or no-advertise (65535, 65282). For
1442
	example, received route carrying a no-adverise community
1443
	should not be advertised to any of its neighbors. If this
1444
	option is enabled (which is by default), BIRD has such
1445
	behavior automatically (it is evaluated when a route is
1446
	exported to the BGP protocol just before the export filter).
1447
	Otherwise, this integrated processing of well-known
1448
	communities is disabled. In that case, similar behavior can be
1449
	implemented in the export filter.  Default: on.
1450

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

    
1459
	<tag>capabilities <m/switch/</tag> Use capability advertisement
1460
	to advertise optional capabilities. This is standard behavior
1461
	for newer BGP implementations, but there might be some older
1462
	BGP implementations that reject such connection attempts.
1463
	When disabled (off), features that request it (4B AS support)
1464
	are also disabled. Default: on, with automatic fallback to
1465
	off when received capability-related error.
1466

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

    
1473
	<tag>route limit <m/number/</tag> The maximal number of routes
1474
	that may be imported from the protocol. If the route limit is
1475
	exceeded, the connection is closed with error. Limit is currently implemented as
1476
	<cf/import limit number exceed restart/. Default: no limit.
1477

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

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

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

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

    
1494
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
1495
	retrying a failed attempt to connect. Default: 120 seconds.
1496

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

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

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

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

    
1512
	<tag>med metric <m/switch/</tag> Enable comparison of MED
1513
	attributes (during best route selection) even between routes
1514
	received from different ASes.  This may be useful if all MED
1515
	attributes contain some consistent metric, perhaps enforced in
1516
	import filters of AS boundary routers. If this option is
1517
	disabled, MED attributes are compared only if routes are
1518
	received from the same AS (which is the standard behavior).
1519
	Default: off.
1520

    
1521
	<tag>deterministic med <m/switch/</tag> BGP route selection
1522
	algorithm is often viewed as a comparison between individual
1523
	routes (e.g. if a new route appears and is better than the
1524
	current best one, it is chosen as the new best one). But the
1525
	proper route selection, as specified by RFC 4271, cannot be
1526
	fully implemented in that way. The problem is mainly in
1527
	handling the MED attribute. BIRD, by default, uses an
1528
	simplification based on individual route comparison, which in
1529
	some cases may lead to temporally dependent behavior (i.e. the
1530
	selection is dependent on the order in which routes appeared).
1531
	This option enables a different (and slower) algorithm
1532
	implementing proper RFC 4271 route selection, which is
1533
	deterministic. Alternative way how to get deterministic
1534
	behavior is to use <cf/med metric/ option. This option is
1535
	incompatible with <ref id="dsc-sorted" name="sorted tables">.
1536
	Default: off.
1537

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

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

    
1546
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
1547
	Discriminator to be used during route selection when the MED attribute
1548
	is missing. Default: 0.
1549

    
1550
	<tag>default bgp_local_pref <m/number/</tag> A default value
1551
	for the Local Preference attribute. It is used when a new
1552
	Local Preference attribute is attached to a route by the BGP
1553
	protocol itself (for example, if a route is received through
1554
	eBGP and therefore does not have such attribute). Default: 100
1555
	(0 in pre-1.2.0 versions of BIRD).
1556
</descrip>
1557

    
1558
<sect1>Attributes
1559

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

    
1564
<descrip>
1565
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1566
	the packet will travel through when forwarded according to the particular route.
1567
	In case of internal BGP it doesn't contain the number of the local AS.
1568

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

    
1573
	<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
1574
	is an optional attribute which is used on external (inter-AS) links to
1575
	convey to an adjacent AS the optimal entry point into the local AS.
1576
	The received attribute is also propagated over internal BGP links.
1577
	The attribute value is zeroed when a route is exported to an external BGP
1578
	instance to ensure that the attribute received from a neighboring AS is
1579
	not propagated to other neighboring ASes. A new value might be set in
1580
	the export filter of an external BGP instance.
1581
	See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
1582
	for further discussion of BGP MED attribute.
1583

    
1584
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1585
	if the route has originated in an interior routing protocol or
1586
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1587
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1588
	is unknown.
1589

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

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

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

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

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

    
1624
	<tag>clist <cf/bgp_cluster_list/ [I, O]</tag> This attribute contains a list
1625
	of cluster IDs of route reflectors. Each route reflector prepends its
1626
	cluster ID when reflecting the route.
1627
</descrip>
1628

    
1629
<sect1>Example
1630

    
1631
<p><code>
1632
protocol bgp {
1633
	local as 65000;			     # Use a private AS number
1634
	neighbor 198.51.100.130 as 64496;    # Our neighbor ...
1635
	multihop;			     # ... which is connected indirectly
1636
	export filter {			     # We use non-trivial export rules
1637
		if source = RTS_STATIC then { # Export only static routes
1638
		        # Assign our community
1639
			bgp_community.add((65000,64501));
1640
			# Artificially increase path length
1641
			# by advertising local AS number twice
1642
			if bgp_path ~ [= 65000 =] then
1643
				bgp_path.prepend(65000);
1644
			accept;
1645
		}
1646
		reject;
1647
	};
1648
	import all;
1649
	source address 198.51.100.14;	# Use a non-standard source address
1650
}
1651
</code>
1652

    
1653
<sect>Device
1654

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

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

    
1663
<sect1>Configuration
1664

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

    
1672
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1673
	If a network interface has more than one network address, BIRD
1674
	has to choose one of them as a primary one. By default, BIRD
1675
	chooses the lexicographically smallest address as the primary
1676
	one.
1677

    
1678
	This option allows to specify which network address should be
1679
	chosen as a primary one. Network addresses that match
1680
	<m/prefix/ are preferred to non-matching addresses. If more
1681
	<cf/primary/ options are used, the first one has the highest
1682
	preference. If "<m/mask/" is specified, then such
1683
	<cf/primary/ option is relevant only to matching network
1684
	interfaces.
1685

    
1686
	In all cases, an address marked by operating system as
1687
	secondary cannot be chosen as the primary one. 
1688
</descrip>
1689

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

    
1693
<p><code>
1694
protocol device {
1695
	scan time 10;		# Scan the interfaces often
1696
	primary "eth0" 192.168.1.1;
1697
	primary 192.168.0.0/16;
1698
}
1699
</code>
1700

    
1701
<sect>Direct
1702

    
1703
<p>The Direct protocol is a simple generator of device routes for all the
1704
directly connected networks according to the list of interfaces provided
1705
by the kernel via the Device protocol.
1706

    
1707
<p>The question is whether it is a good idea to have such device
1708
routes in BIRD routing table. OS kernel usually handles device routes
1709
for directly connected networks by itself so we don't need (and don't
1710
want) to export these routes to the kernel protocol. OSPF protocol
1711
creates device routes for its interfaces itself and BGP protocol is
1712
usually used for exporting aggregate routes. Although there are some
1713
use cases that use the direct protocol (like abusing eBGP as an IGP
1714
routing protocol), in most cases it is not needed to have these device
1715
routes in BIRD routing table and to use the direct protocol.
1716

    
1717
<p>There is one notable case when you definitely want to use the
1718
direct protocol -- running BIRD on BSD systems. Having high priority
1719
device routes for directly connected networks from the direct protocol
1720
protects kernel device routes from being overwritten or removed by IGP
1721
routes during some transient network conditions, because a lower
1722
priority IGP route for the same network is not exported to the kernel
1723
routing table. This is an issue on BSD systems only, as on Linux
1724
systems BIRD cannot change non-BIRD route in the kernel routing table.
1725

    
1726
<p>The only configurable thing about direct is what interfaces it watches:
1727

    
1728
<p><descrip>
1729
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
1730
	protocol will generate device routes for all the interfaces
1731
	available. If you want to restrict it to some subset of interfaces
1732
	(for example if you're using multiple routing tables for policy
1733
	routing and some of the policy domains don't contain all interfaces),
1734
	just use this clause.
1735
</descrip>
1736

    
1737
<p>Direct device routes don't contain any specific attributes.
1738

    
1739
<p>Example config might look like this:
1740

    
1741
<p><code>
1742
protocol direct {
1743
	interface "-arc*", "*";		# Exclude the ARCnets
1744
}
1745
</code>
1746

    
1747
<sect>Kernel
1748

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

    
1758
<p>Unfortunately, there is one thing that makes the routing table
1759
synchronization a bit more complicated. In the kernel routing table
1760
there are also device routes for directly connected networks. These
1761
routes are usually managed by OS itself (as a part of IP address
1762
configuration) and we don't want to touch that.  They are completely
1763
ignored during the scan of the kernel tables and also the export of
1764
device routes from BIRD tables to kernel routing tables is restricted
1765
to prevent accidental interference. This restriction can be disabled using
1766
<cf/device routes/ switch.
1767

    
1768
<p>If your OS supports only a single routing table, you can configure
1769
only one instance of the Kernel protocol. If it supports multiple
1770
tables (in order to allow policy routing; such an OS is for example
1771
Linux), you can run as many instances as you want, but each of them
1772
must be connected to a different BIRD routing table and to a different
1773
kernel table.
1774

    
1775
<p>Because the kernel protocol is partially integrated with the
1776
connected routing table, there are two limitations - it is not
1777
possible to connect more kernel protocols to the same routing table
1778
and changing route destination/gateway in an export
1779
filter of a kernel protocol does not work. Both limitations can be
1780
overcome using another routing table and the pipe protocol.
1781

    
1782
<sect1>Configuration
1783

    
1784
<p><descrip>
1785
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1786
	routing tables when it exits (instead of cleaning them up).
1787
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1788
	kernel routing table.
1789
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1790
	routing tables by other routing daemons or by the system administrator.
1791
	This is possible only on systems which support identification of route
1792
	authorship.
1793

    
1794
	<tag>device routes <m/switch/</tag> Enable export of device
1795
	routes to the kernel routing table. By default, such routes
1796
	are rejected (with the exception of explicitly configured
1797
	device routes from the static protocol) regardless of the
1798
	export filter to protect device routes in kernel routing table
1799
	(managed by OS itself) from accidental overwriting or erasing.
1800

    
1801
	<tag>kernel table <m/number/</tag> Select which kernel table should
1802
	this particular instance of the Kernel protocol work with. Available
1803
	only on systems supporting multiple routing tables.
1804
</descrip>
1805

    
1806
<sect1>Attributes
1807

    
1808
<p>The Kernel protocol defines several attributes. These attributes
1809
are translated to appropriate system (and OS-specific) route attributes.
1810
We support these attributes:
1811

    
1812
<descrip>
1813
	<tag>int <cf/krt_source/</tag> The original source of the imported
1814
	kernel route.  The value is system-dependent. On Linux, it is
1815
	a value of the protocol field of the route. See
1816
	/etc/iproute2/rt_protos for common values.  On BSD, it is
1817
	based on STATIC and PROTOx flags. The attribute is read-only.
1818

    
1819
	<tag>int <cf/krt_metric/</tag> The kernel metric of
1820
	the route.  When multiple same routes are in a kernel routing
1821
	table, the Linux kernel chooses one with lower metric.
1822

    
1823
	<tag>ip <cf/krt_prefsrc/</tag> (Linux) The preferred source address.
1824
 	Used in source address selection for outgoing packets. Have to
1825
 	be one of IP addresses of the router.
1826

    
1827
	<tag>int <cf/krt_realm/</tag> (Linux) The realm of the route. Can be
1828
	used for traffic classification.
1829
</descrip>
1830

    
1831
<sect1>Example
1832

    
1833
<p>A simple configuration can look this way:
1834

    
1835
<p><code>
1836
protocol kernel {
1837
	export all;
1838
}
1839
</code>
1840

    
1841
<p>Or for a system with two routing tables:
1842

    
1843
<p><code>
1844
protocol kernel {		# Primary routing table
1845
	learn;			# Learn alien routes from the kernel
1846
	persist;		# Don't remove routes on bird shutdown
1847
	scan time 10;		# Scan kernel routing table every 10 seconds
1848
	import all;
1849
	export all;
1850
}
1851

    
1852
protocol kernel {		# Secondary routing table
1853
	table auxtable;
1854
	kernel table 100;
1855
	export all;
1856
}
1857
</code>
1858

    
1859
<sect>OSPF
1860

    
1861
<sect1>Introduction
1862

    
1863
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
1864
protocol. The current IPv4 version (OSPFv2) is defined in RFC
1865
2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> and
1866
the current IPv6 version (OSPFv3) is defined in RFC 5340<htmlurl
1867
url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt">  It's a link state
1868
(a.k.a. shortest path first) protocol -- each router maintains a
1869
database describing the autonomous system's topology. Each participating
1870
router has an identical copy of the database and all routers run the
1871
same algorithm calculating a shortest path tree with themselves as a
1872
root. OSPF chooses the least cost path as the best path.
1873

    
1874
<p>In OSPF, the autonomous system can be split to several areas in order
1875
to reduce the amount of resources consumed for exchanging the routing
1876
information and to protect the other areas from incorrect routing data.
1877
Topology of the area is hidden to the rest of the autonomous system.
1878

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

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

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

    
1896
<sect1>Configuration
1897

    
1898
<p>In the main part of configuration, there can be multiple definitions of
1899
OSPF areas, each with a different id. These definitions includes many other
1900
switches and multiple definitions of interfaces. Definition of interface
1901
may contain many switches and constant definitions and list of neighbors
1902
on nonbroadcast networks.
1903

    
1904
<code>
1905
protocol ospf &lt;name&gt; {
1906
	rfc1583compat &lt;switch&gt;;
1907
	stub router &lt;switch&gt;;
1908
	tick &lt;num&gt;;
1909
	ecmp &lt;switch&gt; [limit &lt;num&gt;];
1910
	area &lt;id&gt; {
1911
		stub;
1912
		nssa;
1913
		summary &lt;switch&gt;;
1914
		default nssa &lt;switch&gt;;
1915
		default cost &lt;num&gt;;
1916
		default cost2 &lt;num&gt;;
1917
		translator &lt;switch&gt;;
1918
		translator stability &lt;num&gt;;
1919

    
1920
                networks {
1921
			&lt;prefix&gt;;
1922
			&lt;prefix&gt; hidden;
1923
		}
1924
                external {
1925
			&lt;prefix&gt;;
1926
			&lt;prefix&gt; hidden;
1927
			&lt;prefix&gt; tag &lt;num&gt;;
1928
		}
1929
		stubnet &lt;prefix&gt;;
1930
		stubnet &lt;prefix&gt; {
1931
			hidden &lt;switch&gt;;
1932
			summary &lt;switch&gt;;
1933
			cost &lt;num&gt;;
1934
		}
1935
		interface &lt;interface pattern&gt; [instance &lt;num&gt;] {
1936
			cost &lt;num&gt;;
1937
			stub &lt;switch&gt;;
1938
			hello &lt;num&gt;;
1939
			poll &lt;num&gt;;
1940
			retransmit &lt;num&gt;;
1941
			priority &lt;num&gt;;
1942
			wait &lt;num&gt;;
1943
			dead count &lt;num&gt;;
1944
			dead &lt;num&gt;;
1945
			rx buffer [normal|large|&lt;num&gt;];
1946
			type [broadcast|bcast|pointopoint|ptp|
1947
				nonbroadcast|nbma|pointomultipoint|ptmp];
1948
			strict nonbroadcast &lt;switch&gt;;
1949
			real broadcast &lt;switch&gt;;
1950
			ptp netmask &lt;switch&gt;;
1951
			check link &lt;switch&gt;;
1952
			ecmp weight &lt;num&gt;;
1953
			authentication [none|simple|cryptographic];
1954
			password "&lt;text&gt;";
1955
			password "&lt;text&gt;" {
1956
				id &lt;num&gt;;
1957
				generate from "&lt;date&gt;";
1958
				generate to "&lt;date&gt;";
1959
				accept from "&lt;date&gt;";
1960
				accept to "&lt;date&gt;";
1961
			};
1962
			neighbors {
1963
				&lt;ip&gt;;
1964
				&lt;ip&gt; eligible;
1965
			};
1966
		};
1967
		virtual link &lt;id&gt; [instance &lt;num&gt;] {
1968
			hello &lt;num&gt;;
1969
			retransmit &lt;num&gt;;
1970
			wait &lt;num&gt;;
1971
			dead count &lt;num&gt;;
1972
			dead &lt;num&gt;;
1973
			authentication [none|simple|cryptographic];
1974
			password "&lt;text&gt;";
1975
		};
1976
	};
1977
}
1978
</code>
1979

    
1980
<descrip>
1981
	<tag>rfc1583compat <M>switch</M></tag>
1982
	 This option controls compatibility of routing table
1983
	 calculation with RFC 1583<htmlurl
1984
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1985
	 value is no.
1986

    
1987
	<tag>stub router <M>switch</M></tag>
1988
	 This option configures the router to be a stub router, i.e.,
1989
	 a router that participates in the OSPF topology but does not
1990
	 allow transit traffic. In OSPFv2, this is implemented by
1991
	 advertising maximum metric for outgoing links, as suggested
1992
	 by RFC 3137<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3137.txt">.
1993
	 In OSPFv3, the stub router behavior is announced by clearing
1994
	 the R-bit in the router LSA. Default value is no.
1995

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

    
2002
	<tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
2003
	 This option specifies whether OSPF is allowed to generate
2004
	 ECMP (equal-cost multipath) routes. Such routes are used when
2005
	 there are several directions to the destination, each with
2006
	 the same (computed) cost. This option also allows to specify
2007
	 a limit on maximal number of nexthops in one route. By
2008
	 default, ECMP is disabled.  If enabled, default value of the
2009
	 limit is 16.
2010

    
2011
	<tag>area <M>id</M></tag>
2012
	 This defines an OSPF area with given area ID (an integer or an IPv4
2013
	 address, similarly to a router ID). The most important area is
2014
	 the backbone (ID 0) to which every other area must be connected.
2015

    
2016
	<tag>stub</tag>
2017
	 This option configures the area to be a stub area. External
2018
	 routes are not flooded into stub areas. Also summary LSAs can be
2019
	 limited in stub areas (see option <cf/summary/).
2020
	 By default, the area is not a stub area.
2021

    
2022
	<tag>nssa</tag>
2023
	 This option configures the area to be a NSSA (Not-So-Stubby
2024
	 Area). NSSA is a variant of a stub area which allows a
2025
	 limited way of external route propagation. Global external
2026
	 routes are not propagated into a NSSA, but an external route
2027
	 can be imported into NSSA as a (area-wide) NSSA-LSA (and
2028
	 possibly translated and/or aggregated on area boundary).
2029
	 By default, the area is not NSSA.
2030

    
2031
	<tag>summary <M>switch</M></tag>
2032
	 This option controls propagation of summary LSAs into stub or
2033
	 NSSA areas. If enabled, summary LSAs are propagated as usual,
2034
	 otherwise just the default summary route (0.0.0.0/0) is
2035
	 propagated (this is sometimes called totally stubby area). If
2036
	 a stub area has more area boundary routers, propagating
2037
	 summary LSAs could lead to more efficient routing at the cost
2038
	 of larger link state database. Default value is no.
2039

    
2040
	<tag>default nssa <M>switch</M></tag>
2041
 	 When <cf/summary/ option is enabled, default summary route is
2042
	 no longer propagated to the NSSA. In that case, this option
2043
	 allows to originate default route as NSSA-LSA to the NSSA.
2044
	 Default value is no.
2045

    
2046
	<tag>default cost <M>num</M></tag>
2047
	 This option controls the cost of a default route propagated to
2048
	 stub and NSSA areas. Default value is 1000.
2049

    
2050
	<tag>default cost2 <M>num</M></tag>
2051
	 When a default route is originated as NSSA-LSA, its cost
2052
	 can use either type 1 or type 2 metric. This option allows
2053
	 to specify the cost of a default route in type 2 metric.
2054
	 By default, type 1 metric (option <cf/default cost/) is used.
2055

    
2056
	<tag>translator <M>switch</M></tag>
2057
	 This option controls translation of NSSA-LSAs into external
2058
	 LSAs. By default, one translator per NSSA is automatically
2059
	 elected from area boundary routers. If enabled, this area
2060
	 boundary router would unconditionally translate all NSSA-LSAs
2061
	 regardless of translator election. Default value is no.
2062

    
2063
	<tag>translator stability <M>num</M></tag>
2064
	 This option controls the translator stability interval (in
2065
	 seconds). When the new translator is elected, the old one
2066
	 keeps translating until the interval is over. Default value
2067
	 is 40.
2068

    
2069
	<tag>networks { <m/set/ }</tag>
2070
         Definition of area IP ranges. This is used in summary LSA origination.
2071
	 Hidden networks are not propagated into other areas.
2072

    
2073
	<tag>external { <m/set/ }</tag>
2074
         Definition of external area IP ranges for NSSAs. This is used
2075
	 for NSSA-LSA translation. Hidden networks are not translated
2076
	 into external LSAs. Networks can have configured route tag.
2077

    
2078
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
2079
	 Stub networks are networks that are not transit networks
2080
	 between OSPF routers. They are also propagated through an
2081
	 OSPF area as a part of a link state database. By default,
2082
	 BIRD generates a stub network record for each primary network
2083
	 address on each OSPF interface that does not have any OSPF
2084
	 neighbors, and also for each non-primary network address on
2085
	 each OSPF interface. This option allows to alter a set of
2086
	 stub networks propagated by this router. 
2087

    
2088
	 Each instance of this option adds a stub network with given
2089
	 network prefix to the set of propagated stub network, unless
2090
	 option <cf/hidden/ is used. It also suppresses default stub
2091
	 networks for given network prefix. When option
2092
	 <cf/summary/ is used, also default stub networks that are
2093
	 subnetworks of given stub network are suppressed. This might
2094
	 be used, for example, to aggregate generated stub networks.
2095
	 
2096
	<tag>interface <M>pattern</M> [instance <m/num/]</tag>
2097
	 Defines that the specified interfaces belong to the area being defined.
2098
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
2099
	 In OSPFv3, you can specify instance ID for that interface
2100
	 description, so it is possible to have several instances of
2101
	 that interface with different options or even in different areas.
2102

    
2103
	<tag>virtual link <M>id</M> [instance <m/num/]</tag>
2104
	 Virtual link to router with the router id. Virtual link acts
2105
         as a point-to-point interface belonging to backbone. The
2106
         actual area is used as transport area. This item cannot be in
2107
         the backbone. In OSPFv3, you could also use several virtual
2108
         links to one destination with different instance IDs.
2109

    
2110
	<tag>cost <M>num</M></tag>
2111
	 Specifies output cost (metric) of an interface. Default value is 10.
2112

    
2113
	<tag>stub <M>switch</M></tag>
2114
	 If set to interface it does not listen to any packet and does not send
2115
	 any hello. Default value is no.
2116

    
2117
	<tag>hello <M>num</M></tag>
2118
	 Specifies interval in seconds between sending of Hello messages. Beware, all
2119
	 routers on the same network need to have the same hello interval.
2120
	 Default value is 10.
2121

    
2122
	<tag>poll <M>num</M></tag>
2123
	 Specifies interval in seconds between sending of Hello messages for
2124
	 some neighbors on NBMA network. Default value is 20.
2125

    
2126
	<tag>retransmit <M>num</M></tag>
2127
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
2128
	 Default value is 5.
2129

    
2130
        <tag>priority <M>num</M></tag>
2131
	 On every multiple access network (e.g., the Ethernet) Designed Router
2132
	 and Backup Designed router are elected. These routers have some
2133
	 special functions in the flooding process. Higher priority increases
2134
	 preferences in this election. Routers with priority 0 are not
2135
	 eligible. Default value is 1.
2136

    
2137
	<tag>wait <M>num</M></tag>
2138
	 After start, router waits for the specified number of seconds between starting
2139
	 election and building adjacency. Default value is 40.
2140
	 
2141
	<tag>dead count <M>num</M></tag>
2142
	 When the router does not receive any messages from a neighbor in
2143
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
2144

    
2145
	<tag>dead <M>num</M></tag>
2146
	 When the router does not receive any messages from a neighbor in
2147
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
2148
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
2149

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

    
2155
	<tag>type broadcast|bcast</tag>
2156
	 BIRD detects a type of a connected network automatically, but
2157
	 sometimes it's convenient to force use of a different type
2158
	 manually. On broadcast networks (like ethernet), flooding
2159
	 and Hello messages are sent using multicasts (a single packet
2160
	 for all the neighbors). A designated router is elected and it
2161
	 is responsible for synchronizing the link-state databases and
2162
	 originating network LSAs. This network type cannot be used on
2163
	 physically NBMA networks and on unnumbered networks (networks
2164
	 without proper IP prefix).
2165

    
2166
	<tag>type pointopoint|ptp</tag>
2167
	 Point-to-point networks connect just 2 routers together. No
2168
	 election is performed and no network LSA is originated, which
2169
	 makes it simpler and faster to establish. This network type
2170
	 is useful not only for physically PtP ifaces (like PPP or
2171
	 tunnels), but also for broadcast networks used as PtP links.
2172
	 This network type cannot be used on physically NBMA networks.
2173

    
2174
	<tag>type nonbroadcast|nbma</tag>
2175
	 On NBMA networks, the packets are sent to each neighbor
2176
	 separately because of lack of multicast capabilities.
2177
	 Like on broadcast networks, a designated router is elected,
2178
	 which plays a central role in propagation of LSAs.
2179
	 This network type cannot be used on unnumbered networks.
2180

    
2181
	<tag>type pointomultipoint|ptmp</tag>
2182
	 This is another network type designed to handle NBMA
2183
	 networks. In this case the NBMA network is treated as a
2184
	 collection of PtP links. This is useful if not every pair of
2185
	 routers on the NBMA network has direct communication, or if
2186
	 the NBMA network is used as an (possibly unnumbered) PtP
2187
	 link.
2188

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

    
2193
	<tag>real broadcast <m/switch/</tag>
2194
	 In <cf/type broadcast/ or <cf/type ptp/ network
2195
	 configuration, OSPF packets are sent as IP multicast
2196
	 packets. This option changes the behavior to using
2197
	 old-fashioned IP broadcast packets. This may be useful as a
2198
	 workaround if IP multicast for some reason does not work or
2199
	 does not work reliably. This is a non-standard option and
2200
	 probably is not interoperable with other OSPF
2201
	 implementations. Default value is no.
2202

    
2203
	<tag>ptp netmask <m/switch/</tag>
2204
	 In <cf/type ptp/ network configurations, OSPFv2
2205
	 implementations should ignore received netmask field in hello
2206
	 packets and should send hello packets with zero netmask field
2207
	 on unnumbered PtP links. But some OSPFv2 implementations
2208
	 perform netmask checking even for PtP links. This option
2209
	 specifies whether real netmask will be used in hello packets
2210
	 on <cf/type ptp/ interfaces. You should ignore this option
2211
	 unless you meet some compatibility problems related to this
2212
	 issue. Default value is no for unnumbered PtP links, yes
2213
	 otherwise.
2214

    
2215
	<tag>check link <M>switch</M></tag>
2216
	 If set, a hardware link state (reported by OS) is taken into
2217
	 consideration. When a link disappears (e.g. an ethernet cable is
2218
	 unplugged), neighbors are immediately considered unreachable
2219
	 and only the address of the iface (instead of whole network
2220
	 prefix) is propagated. It is possible that some hardware
2221
	 drivers or platforms do not implement this feature. Default value is no.
2222

    
2223
	<tag>ecmp weight <M>num</M></tag>
2224
	 When ECMP (multipath) routes are allowed, this value specifies
2225
	 a relative weight used for nexthops going through the iface.
2226
	 Allowed values are 1-256. Default value is 1.
2227

    
2228
	<tag>authentication none</tag>
2229
	 No passwords are sent in OSPF packets. This is the default value.
2230

    
2231
	<tag>authentication simple</tag>
2232
	 Every packet carries 8 bytes of password. Received packets
2233
	 lacking this password are ignored. This authentication mechanism is
2234
	 very weak.
2235

    
2236
	<tag>authentication cryptographic</tag>
2237
	 16-byte long MD5 digest is appended to every packet. For the digest
2238
         generation 16-byte long passwords are used. Those passwords are 
2239
         not sent via network, so this mechanism is quite secure.
2240
         Packets can still be read by an attacker.
2241

    
2242
	<tag>password "<M>text</M>"</tag>
2243
	 An 8-byte or 16-byte password used for authentication.
2244
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
2245

    
2246
	<tag>neighbors { <m/set/ } </tag>
2247
	 A set of neighbors to which Hello messages on NBMA or PtMP
2248
	 networks are to be sent. For NBMA networks, some of them
2249
	 could be marked as eligible. In OSPFv3, link-local addresses
2250
	 should be used, using global ones is possible, but it is
2251
	 nonstandard and might be problematic. And definitely,
2252
	 link-local and global addresses should not be mixed.
2253

    
2254
</descrip>
2255

    
2256
<sect1>Attributes
2257

    
2258
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
2259
Metric is ranging from 1 to infinity (65535).
2260
External routes use <cf/metric type 1/ or <cf/metric type 2/.
2261
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
2262
<cf/metric of type 2/ is always longer
2263
than any <cf/metric of type 1/ or any <cf/internal metric/.
2264
<cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute
2265
<cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/.
2266
If you specify both metrics only metric1 is used.
2267

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

    
2275
<sect1>Example
2276

    
2277
<p>
2278

    
2279
<code>
2280
protocol ospf MyOSPF {
2281
        rfc1583compat yes;
2282
        tick 2;
2283
	export filter {
2284
		if source = RTS_BGP then {
2285
			ospf_metric1 = 100;
2286
			accept;
2287
		}
2288
		reject;
2289
	};
2290
	area 0.0.0.0 {
2291
		interface "eth*" {
2292
			cost 11;
2293
			hello 15;
2294
			priority 100;
2295
			retransmit 7;
2296
			authentication simple;
2297
			password "aaa";
2298
		};
2299
		interface "ppp*" {
2300
			cost 100;
2301
			authentication cryptographic;
2302
			password "abc" {
2303
				id 1;
2304
				generate to "22-04-2003 11:00:06";
2305
				accept from "17-01-2001 12:01:05";
2306
			};
2307
			password "def" {
2308
				id 2;
2309
				generate to "22-07-2005 17:03:21";
2310
				accept from "22-02-2001 11:34:06";
2311
			};
2312
		};
2313
		interface "arc0" {
2314
			cost 10;
2315
			stub yes;
2316
		};
2317
		interface "arc1";
2318
	};
2319
	area 120 {
2320
		stub yes;
2321
		networks {
2322
			172.16.1.0/24;
2323
			172.16.2.0/24 hidden;
2324
		}
2325
		interface "-arc0" , "arc*" {
2326
			type nonbroadcast;
2327
			authentication none;
2328
			strict nonbroadcast yes;
2329
			wait 120;
2330
			poll 40;
2331
			dead count 8;
2332
			neighbors {
2333
				192.168.120.1 eligible;
2334
				192.168.120.2;
2335
				192.168.120.10;
2336
			};
2337
		};
2338
	};
2339
}
2340
</code>
2341

    
2342
<sect>Pipe
2343

    
2344
<sect1>Introduction
2345

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

    
2353
<p>The Pipe protocol may work in the transparent mode mode or in the opaque mode.
2354
In the transparent mode, the Pipe protocol retransmits all routes from
2355
one table to the other table, retaining their original source and
2356
attributes.  If import and export filters are set to accept, then both
2357
tables would have the same content. The transparent mode is the default mode.
2358

    
2359
<p>In the opaque mode, the Pipe protocol retransmits optimal route
2360
from one table to the other table in a similar way like other
2361
protocols send and receive routes. Retransmitted route will have the
2362
source set to the Pipe protocol, which may limit access to protocol
2363
specific route attributes. This mode is mainly for compatibility, it
2364
is not suggested for new configs. The mode can be changed by
2365
<tt/mode/ option.
2366

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

    
2378
<sect1>Configuration
2379

    
2380
<p><descrip>
2381
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
2382
	primary one is selected by the <cf/table/ keyword.
2383

    
2384
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
2385
</descrip>
2386

    
2387
<sect1>Attributes
2388

    
2389
<p>The Pipe protocol doesn't define any route attributes.
2390

    
2391
<sect1>Example
2392

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

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

    
2407
<code>
2408
table as1;				# Define the tables
2409
table as2;
2410

    
2411
protocol kernel kern1 {			# Synchronize them with the kernel
2412
	table as1;
2413
	kernel table 1;
2414
}
2415

    
2416
protocol kernel kern2 {
2417
	table as2;
2418
	kernel table 2;
2419
}
2420

    
2421
protocol bgp bgp1 {			# The outside connections
2422
	table as1;
2423
	local as 1;
2424
	neighbor 192.168.0.1 as 1001;
2425
	export all;
2426
	import all;
2427
}
2428

    
2429
protocol bgp bgp2 {
2430
	table as2;
2431
	local as 2;
2432
	neighbor 10.0.0.1 as 1002;
2433
	export all;
2434
	import all;
2435
}
2436

    
2437
protocol pipe {				# The Pipe
2438
	table as1;
2439
	peer table as2;
2440
	export filter {
2441
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
2442
			if preference>10 then preference = preference-10;
2443
			if source=RTS_BGP then bgp_path.prepend(1);
2444
			accept;
2445
		}
2446
		reject;
2447
	};
2448
	import filter {
2449
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
2450
			if preference>10 then preference = preference-10;
2451
			if source=RTS_BGP then bgp_path.prepend(2);
2452
			accept;
2453
		}
2454
		reject;
2455
	};
2456
}
2457
</code>
2458

    
2459
<sect>RAdv
2460

    
2461
<sect1>Introduction
2462

    
2463
<p>The RAdv protocol is an implementation of Router Advertisements,
2464
which are used in the IPv6 stateless autoconfiguration. IPv6 routers
2465
send (in irregular time intervals or as an answer to a request)
2466
advertisement packets to connected networks. These packets contain
2467
basic information about a local network (e.g. a list of network
2468
prefixes), which allows network hosts to autoconfigure network
2469
addresses and choose a default route. BIRD implements router behavior
2470
as defined in
2471
RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">
2472
and also the DNS extensions from
2473
RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">.
2474

    
2475
<sect1>Configuration
2476

    
2477
<p>There are several classes of definitions in RAdv configuration --
2478
interface definitions, prefix definitions and DNS definitions:
2479

    
2480
<descrip>
2481
	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag>
2482
	Interface definitions specify a set of interfaces on which the
2483
	protocol is activated and contain interface specific options.
2484
	See <ref id="dsc-iface" name="interface"> common options for
2485
	detailed description.
2486

    
2487
	<tag>prefix <m/prefix/ { <m/options/ }</tag>
2488
	Prefix definitions allow to modify a list of advertised
2489
	prefixes. By default, the advertised prefixes are the same as
2490
	the network prefixes assigned to the interface. For each
2491
	network prefix, the matching prefix definition is found and
2492
	its options are used. If no matching prefix definition is
2493
	found, the prefix is used with default options.
2494

    
2495
	Prefix definitions can be either global or interface-specific.
2496
	The second ones are part of interface options. The prefix
2497
	definition matching is done in the first-match style, when
2498
	interface-specific definitions are processed before global
2499
	definitions. As expected, the prefix definition is matching if
2500
	the network prefix is a subnet of the prefix in prefix
2501
	definition.
2502

    
2503
	<tag>rdnss { <m/options/ }</tag>
2504
	RDNSS definitions allow to specify a list of advertised
2505
	recursive DNS servers together with their options. As options
2506
	are seldom necessary, there is also a short variant <cf>rdnss
2507
	<m/address/</cf> that just specifies one DNS server. Multiple
2508
	definitions are cumulative. RDNSS definitions may also be
2509
	interface-specific when used inside interface options. By
2510
	default, interface uses both global and interface-specific
2511
	options, but that can be changed by <cf/rdnss local/ option.
2512

    
2513
	<tag>dnssl { <m/options/ }</tag>
2514
	DNSSL definitions allow to specify a list of advertised DNS
2515
	search domains together with their options. Like <cf/rdnss/
2516
	above, multiple definitions are cumulative, they can be used
2517
	also as interface-specific options and there is a short
2518
	variant <cf>dnssl <m/domain/</cf> that just specifies one DNS
2519
        search domain.
2520

    
2521
	<label id="dsc-trigger"> <tag>trigger <m/prefix/</tag>
2522
	RAdv protocol could be configured to change its behavior based
2523
	on availability of routes. When this option is used, the
2524
	protocol waits in suppressed state until a <it/trigger route/
2525
	(for the specified network) is exported to the protocol, the
2526
	protocol also returnsd to suppressed state if the
2527
	<it/trigger route/ disappears. Note that route export depends
2528
	on specified export filter, as usual. This option could be
2529
	used, e.g., for handling failover in multihoming scenarios.
2530

    
2531
	During suppressed state, router advertisements are generated,
2532
	but with some fields zeroed. Exact behavior depends on which
2533
	fields are zeroed, this can be configured by
2534
	<cf/sensitive/ option for appropriate fields. By default, just
2535
	<cf/default lifetime/ (also called <cf/router lifetime/) is
2536
	zeroed, which means hosts cannot use the router as a default
2537
	router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
2538
	also be configured as <cf/sensitive/ for a prefix, which would
2539
	cause autoconfigured IPs to be deprecated or even removed.
2540
</descrip>
2541

    
2542
<p>Interface specific options:
2543

    
2544
<descrip>
2545
	<tag>max ra interval <m/expr/</tag>
2546
	Unsolicited router advertisements are sent in irregular time
2547
	intervals. This option specifies the maximum length of these
2548
	intervals, in seconds. Valid values are 4-1800. Default: 600
2549

    
2550
	<tag>min ra interval <m/expr/</tag>
2551
	This option specifies the minimum length of that intervals, in
2552
	seconds. Must be at least 3 and at most 3/4 * <cf/max ra interval/.
2553
	Default: about 1/3 * <cf/max ra interval/.
2554

    
2555
	<tag>min delay <m/expr/</tag>
2556
	The minimum delay between two consecutive router advertisements,
2557
	in seconds. Default: 3
2558

    
2559
	<tag>managed <m/switch/</tag>
2560
	This option specifies whether hosts should use DHCPv6 for
2561
	IP address configuration. Default: no
2562

    
2563
	<tag>other config <m/switch/</tag>
2564
	This option specifies whether hosts should use DHCPv6 to
2565
	receive other configuration information. Default: no
2566

    
2567
	<tag>link mtu <m/expr/</tag>
2568
	This option specifies which value of MTU should be used by
2569
	hosts. 0 means unspecified. Default: 0
2570

    
2571
	<tag>reachable time <m/expr/</tag>
2572
	This option specifies the time (in milliseconds) how long
2573
	hosts should assume a neighbor is reachable (from the last
2574
	confirmation). Maximum is 3600000, 0 means unspecified.
2575
	Default 0.
2576

    
2577
	<tag>retrans timer <m/expr/</tag>
2578
	This option specifies the time (in milliseconds) how long
2579
	hosts should wait before retransmitting Neighbor Solicitation
2580
	messages. 0 means unspecified. Default 0.
2581

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

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

    
2593
	<tag>rdnss local <m/switch/</tag>
2594
	Use only local (interface-specific) RDNSS definitions for this
2595
	interface. Otherwise, both global and local definitions are
2596
	used. Could also be used to disable RDNSS for given interface
2597
	if no local definitons are specified. Default: no.
2598

    
2599
	<tag>dnssl local <m/switch/</tag>
2600
	Use only local DNSSL definitions for this interface. See
2601
	<cf/rdnss local/ option above. Default: no.
2602
</descrip>
2603

    
2604

    
2605
<p>Prefix specific options:
2606

    
2607
<descrip>
2608
	<tag>skip <m/switch/</tag>
2609
	This option allows to specify that given prefix should not be
2610
	advertised. This is useful for making exceptions from a
2611
	default policy of advertising all prefixes. Note that for
2612
	withdrawing an already advertised prefix it is more useful to
2613
	advertise it with zero valid lifetime. Default: no
2614

    
2615
	<tag>onlink <m/switch/</tag>
2616
	This option specifies whether hosts may use the advertised
2617
	prefix for onlink determination. Default: yes
2618

    
2619
	<tag>autonomous <m/switch/</tag>
2620
	This option specifies whether hosts may use the advertised
2621
	prefix for stateless autoconfiguration. Default: yes
2622

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

    
2631
	<tag>preferred lifetime <m/expr/ [sensitive <m/switch/]</tag>
2632
	This option specifies the time (in seconds) how long (after
2633
	the receipt of RA) IP addresses generated from the prefix
2634
	using stateless autoconfiguration remain preferred. For
2635
	<cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
2636
	Default: 14400 (4 hours), <cf/sensitive/ no.
2637
</descrip>
2638

    
2639

    
2640
<p>RDNSS specific options:
2641

    
2642
<descrip>
2643
	<tag>ns <m/address/</tag>
2644
	This option specifies one recursive DNS server. Can be used
2645
	multiple times for multiple servers. It is mandatory to have
2646
	at least one <cf/ns/ option in <cf/rdnss/ definition.
2647

    
2648
	<tag>lifetime [mult] <m/expr/</tag>
2649
	This option specifies the time how long the RDNSS information
2650
        may be used by clients after the receipt of RA. It is
2651
        expressed either in seconds or (when <cf/mult/ is used) in
2652
        multiples of <cf/max ra interval/. Note that RDNSS information
2653
        is also invalidated when <cf/default lifetime/ expires. 0
2654
        means these addresses are no longer valid DNS servers.
2655
	Default: 3 * <cf/max ra interval/.
2656
</descrip>
2657

    
2658

    
2659
<p>DNSSL specific options:
2660

    
2661
<descrip>
2662
	<tag>domain <m/address/</tag>
2663
	This option specifies one DNS search domain. Can be used
2664
	multiple times for multiple domains. It is mandatory to have
2665
	at least one <cf/domain/ option in <cf/dnssl/ definition.
2666

    
2667
	<tag>lifetime [mult] <m/expr/</tag>
2668
	This option specifies the time how long the DNSSL information
2669
        may be used by clients after the receipt of RA. Details are
2670
	the same as for RDNSS <cf/lifetime/ option above.
2671
	Default: 3 * <cf/max ra interval/.
2672
</descrip>
2673

    
2674

    
2675
<sect1>Example
2676

    
2677
<p><code>
2678
protocol radv {
2679
	interface "eth2" {
2680
		max ra interval 5;	# Fast failover with more routers
2681
		managed yes;		# Using DHCPv6 on eth2
2682
		prefix ::/0 {
2683
			autonomous off;	# So do not autoconfigure any IP
2684
		};
2685
	};
2686

    
2687
	interface "eth*";		# No need for any other options
2688

    
2689
	prefix 2001:0DB8:1234::/48 {
2690
		preferred lifetime 0;	# Deprecated address range
2691
	};
2692

    
2693
	prefix 2001:0DB8:2000::/48 {
2694
		autonomous off;		# Do not autoconfigure
2695
	};
2696

    
2697
	rdnss 2001:0DB8:1234::10;	# Short form of RDNSS
2698

    
2699
	rdnss {
2700
		lifetime mult 10;
2701
		ns 2001:0DB8:1234::11;
2702
		ns 2001:0DB8:1234::12;
2703
	};
2704

    
2705
	dnssl {
2706
		lifetime 3600;
2707
		domain "abc.com";
2708
		domain "xyz.com";
2709
	};
2710
}
2711
</code>
2712

    
2713
<sect>RIP
2714

    
2715
<sect1>Introduction
2716

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

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

    
2734
<sect1>Configuration
2735

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

    
2738
<descrip>
2739
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
2740
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
2741
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
2742
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
2743
	  section. Default: none.
2744

    
2745
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
2746
	  be honored. (Always, when sent from a  host on a directly connected
2747
	  network or never.) Routing table updates are honored only from
2748
	  neighbors, that is not configurable. Default: never.
2749
</descrip>
2750

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

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

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

    
2768
	<tag>infinity <M>number</M></tag>
2769
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
2770
	  even slower.
2771

    
2772
	<tag>period <M>number</M>
2773
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
2774
	  number will mean faster convergence but bigger network
2775
	  load. Do not use values lower than 12.
2776

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

    
2780
	<tag>garbage time <M>number</M>
2781
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
2782
</descrip>
2783

    
2784
<sect1>Attributes
2785

    
2786
<p>RIP defines two route attributes:
2787

    
2788
<descrip>
2789
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
2790
	When routes from different RIP instances are available and all of them have the same
2791
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
2792
	When importing a non-RIP route, the metric defaults to 5.
2793

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

    
2799
<sect1>Example
2800

    
2801
<p><code>
2802
protocol rip MyRIP_test {
2803
        debug all;
2804
        port 1520;
2805
        period 12;
2806
        garbage time 60;
2807
        interface "eth0" { metric 3; mode multicast; };
2808
	interface "eth*" { metric 2; mode broadcast; };
2809
        honor neighbor;
2810
        authentication none;
2811
        import filter { print "importing"; accept; };
2812
        export filter { print "exporting"; accept; };
2813
}
2814
</code>
2815

    
2816
<sect>Static
2817

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

    
2826
<p>There are five types of static routes: `classical' routes telling
2827
to forward packets to a neighboring router, multipath routes
2828
specifying several (possibly weighted) neighboring routers, device
2829
routes specifying forwarding to hosts on a directly connected network,
2830
recursive routes computing their nexthops by doing route table lookups
2831
for a given IP and special routes (sink, blackhole etc.) which specify
2832
a special action to be done instead of forwarding the packet.
2833

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

    
2839
<p>The Static protocol does not have many configuration options. The
2840
definition of the protocol contains mainly a list of static routes:
2841

    
2842
<descrip>
2843
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
2844
	a neighboring router.
2845
	<tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
2846
	Static multipath route. Contains several nexthops (gateways), possibly
2847
 	with their weights.
2848
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
2849
	route through an interface to hosts on a directly connected network.
2850
	<tag>route <m/prefix/ recursive <m/ip/</tag> Static recursive route,
2851
	its nexthop depends on a route table lookup for given IP address.
2852
	<tag>route <m/prefix/ blackhole|unreachable|prohibit</tag> Special routes
2853
	specifying to silently drop the packet, return it as unreachable or return
2854
	it as administratively prohibited. First two targets are also known
2855
	as <cf/drop/ and <cf/reject/.
2856

    
2857
	<tag>check link <m/switch/</tag>
2858
	If set, hardware link states of network interfaces are taken
2859
	into consideration.  When link disappears (e.g. ethernet cable
2860
	is unplugged), static routes directing to that interface are
2861
	removed. It is possible that some hardware drivers or
2862
	platforms do not implement this feature. Default: off.
2863

    
2864
	<tag>igp table <m/name/</tag> Specifies a table that is used
2865
	for route table lookups of recursive routes. Default: the
2866
	same table as the protocol is connected to.
2867
</descrip>
2868

    
2869
<p>Static routes have no specific attributes.
2870

    
2871
<p>Example static config might look like this:
2872

    
2873
<p><code>
2874
protocol static {
2875
	table testable;			 # Connect to a non-default routing table
2876
	route 0.0.0.0/0 via 198.51.100.130; # Default route
2877
	route 10.0.0.0/8 multipath	 # Multipath route
2878
		via 198.51.100.10 weight 2
2879
		via 198.51.100.20
2880
		via 192.0.2.1;
2881
	route 203.0.113.0/24 unreachable; # Sink route
2882
	route 10.2.0.0/24 via "arc0";	 # Secondary network
2883
}
2884
</code>
2885

    
2886
<chapt>Conclusions
2887

    
2888
<sect>Future work
2889

    
2890
<p>Although BIRD supports all the commonly used routing protocols,
2891
there are still some features which would surely deserve to be
2892
implemented in future versions of BIRD:
2893

    
2894
<itemize>
2895
<item>Opaque LSA's
2896
<item>Route aggregation and flap dampening
2897
<item>Multipath routes
2898
<item>Multicast routing protocols
2899
<item>Ports to other systems
2900
</itemize>
2901

    
2902
<sect>Getting more help
2903

    
2904
<p>If you use BIRD, you're welcome to join the bird-users mailing list
2905
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
2906
where you can share your experiences with the other users and consult
2907
your problems with the authors. To subscribe to the list, just send a
2908
<tt/subscribe bird-users/ command in a body of a mail to
2909
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
2910
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
2911

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

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

    
2922
<p><it/Good luck!/
2923

    
2924
</book>
2925

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