Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 48e5f32d

History | View | Annotate | Download (145 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>-P <m/name of PID file/</tag>
150
	create a PID file with given filename</file>.
151

    
152
	<tag>-u <m/user/</tag>
153
	drop privileges and use that user ID, see the next section for details.
154

    
155
	<tag>-g <m/group/</tag>
156
	use that group ID, see the next section for details.
157

    
158
	<tag>-f</tag>
159
	run bird in foreground.
160
</descrip>
161

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

    
164
<sect>Privileges
165

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

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

    
184
<p>Finally, there is a possibility to use external tools to run BIRD in
185
an environment with restricted privileges. This may need some
186
configuration, but it is generally easy -- BIRD needs just the
187
standard library, privileges to read the config file and create the
188
control socket and the CAP_NET_* capabilities.
189

    
190
<chapt>About routing tables
191

    
192
<p>BIRD has one or more routing tables which may or may not be
193
synchronized with OS kernel and which may or may not be synchronized with
194
each other (see the Pipe protocol). Each routing table contains a list of
195
known routes. Each route consists of:
196

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

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

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

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

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

    
245

    
246
<chapt>Configuration
247

    
248
<sect>Introduction
249

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

    
256
<p>In the config, everything on a line after <cf/#/ or inside <cf>/*
257
*/</cf> is a comment, whitespace characters are treated as a single space. If there's a variable number of options, they are grouped using
258
the <cf/{ }/ brackets. Each option is terminated by a <cf/;/. Configuration
259
is case sensitive. There are two ways how to name symbols (like protocol names, filter names, constats etc.). You can either use
260
a simple string starting with a letter followed by any combination of letters and numbers (e.g. "R123", "myfilter", "bgp5") or you
261
can enclose the name into apostrophes (<cf/'/) and than you can use any combination of numbers, letters. hyphens, dots and colons
262
(e.g. "'1:strange-name'", "'-NAME-'", "'cool::name'").
263

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

    
268

    
269
<code>
270
protocol kernel {
271
	persist;		# Don't remove routes on BIRD shutdown
272
	scan time 20;		# Scan kernel routing table every 20 seconds
273
	export all;		# Default is export none
274
}
275

    
276
protocol device {
277
	scan time 10;		# Scan interfaces every 10 seconds
278
}
279

    
280
protocol rip {
281
	export all;
282
	import all;
283
	interface "*";
284
}
285
</code>
286

    
287

    
288
<sect>Global options
289

    
290
<p><descrip>
291
	<tag>include "<m/filename/"</tag> 
292
	This statement causes inclusion of a new file. The maximal depth is set to 5.
293

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

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

    
309
	<tag>debug commands <m/number/</tag>
310
	Control logging of client connections (0 for no logging, 1 for
311
	logging of connects and disconnects, 2 and higher for logging of
312
	all client commands). Default: 0.
313

    
314
	<tag>mrtdump "<m/filename/"</tag>
315
	Set MRTdump file name. This option must be specified to allow MRTdump feature.
316
	Default: no dump file.
317

    
318
	<tag>mrtdump protocols all|off|{ states, messages }</tag>
319
	Set global defaults of MRTdump options. See <cf/mrtdump/ in the following section.
320
	Default: off.
321

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

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

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

    
344
	<tag>define <m/constant/ = <m/expression/</tag>
345
	Define a constant. You can use it later in every place you could use a value of the same type.
346
	Besides, there are some predefined numeric constants based on /etc/iproute2/rt_* files.
347
	A list of defined constants can be seen (together with other symbols) using 'show symbols' command.
348

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

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

    
362
	<tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
363
	This option allows to specify address and port where BGP
364
	protocol should listen. It is global option as listening
365
	socket is common to all BGP instances. Default is to listen on
366
	all addresses (0.0.0.0) and port 179. In IPv6 mode, option
367
	<cf/dual/ can be used to specify that BGP socket should accept
368
	both IPv4 and IPv6 connections (but even in that case, BIRD
369
	would accept IPv6 routes only). Such behavior was default in
370
	older versions of BIRD.
371

    
372
	<tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
373
	This option allows to specify a format of date/time used by
374
	BIRD.  The first argument specifies for which purpose such
375
	format is used. <cf/route/ is a format used in 'show route'
376
	command output, <cf/protocol/ is used in 'show protocols'
377
	command output, <cf/base/ is used for other commands and
378
	<cf/log/ is used in a log file.
379

    
380
	"<m/format1/" is a format string using <it/strftime(3)/
381
	notation (see <it/man strftime/ for details). <m/limit> and
382
	"<m/format2/" allow to specify the second format string for
383
	times in past deeper than <m/limit/ seconds. There are few
384
	shorthands: <cf/iso long/ is a ISO 8601 date/time format
385
	(YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
386
	%T"/. <cf/iso short/ is a variant of ISO 8601 that uses just
387
	the time format (hh:mm:ss) for near times (up to 20 hours in
388
	the past) and the date format (YYYY-MM-DD) for far times. This
389
	is a shorthand for <cf/"%T" 72000 "%F"/.
390

    
391
	By default, BIRD uses the <cf/iso short/ format for <cf/route/ and
392
	<cf/protocol/ times, and the <cf/iso long/ format for <cf/base/ and
393
	<cf/log/ times.
394

    
395
	In pre-1.4.0 versions, BIRD used an short, ad-hoc format for
396
	<cf/route/ and <cf/protocol/ times, and a <cf/iso long/ similar format
397
	(DD-MM-YYYY hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats
398
	could be set by <cf/old short/ and <cf/old long/ compatibility
399
	shorthands.
400

    
401
	<tag>table <m/name/ [sorted]</tag>
402
	Create a new routing table. The default routing table is
403
	created implicitly, other routing tables have to be added by
404
	this command. Option <cf/sorted/ can be used to enable
405
	sorting of routes, see <ref id="dsc-sorted" name="sorted table">
406
	description for details.
407

    
408
	<tag>roa table <m/name/ [ { roa table options ... } ]</tag>
409
	Create a new ROA (Route Origin Authorization) table. ROA
410
	tables can be used to validate route origination of BGP
411
	routes. A ROA table contains ROA entries, each consist of a
412
	network prefix, a max prefix length and an AS number. A ROA
413
	entry specifies prefixes which could be originated by that AS
414
	number. ROA tables could be filled with data from RPKI (RFC
415
	6480) or from public databases like Whois. ROA tables are 
416
	examined by <cf/roa_check()/ operator in filters.
417

    
418
	Currently, there is just one option,
419
	<cf>roa <m/prefix/ max <m/num/ as <m/num/</cf>, which
420
	can be used to populate the ROA table with static ROA
421
	entries. The option may be used multiple times. Other entries
422
	can be added dynamically by <cf/add roa/ command.
423

    
424
	<tag>eval <m/expr/</tag>
425
	Evaluates given filter expression. It is used by us for	testing of filters.
426
</descrip>
427

    
428
<sect>Protocol options
429

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

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

    
440
<descrip>
441
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
442

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

    
446
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
447
	Set protocol debugging options. If asked, each protocol is capable of
448
	writing trace messages about its work to the log (with category
449
	<cf/trace/). You can either request printing of <cf/all/ trace messages
450
	or only of the types selected: <cf/states/ for protocol state changes
451
	(protocol going up, down, starting, stopping etc.),
452
	<cf/routes/ for routes exchanged with the routing table,
453
	<cf/filters/ for details on route filtering,
454
	<cf/interfaces/ for interface change events sent to the protocol,
455
	<cf/events/ for events internal to the protocol and
456
	<cf/packets/ for packets sent and received by the protocol. Default: off.
457

    
458
	<tag>mrtdump all|off|{ states, messages }</tag>
459
	Set protocol MRTdump flags. MRTdump is a standard binary
460
	format for logging information from routing protocols and
461
	daemons.  These flags control what kind of information is
462
	logged from the protocol to the MRTdump file (which must be
463
	specified by global <cf/mrtdump/ option, see the previous
464
	section). Although these flags are similar to flags of
465
	<cf/debug/ option, their meaning is different and
466
	protocol-specific. For BGP protocol, <cf/states/ logs BGP
467
	state changes and <cf/messages/ logs received BGP messages.
468
	Other protocols does not support MRTdump yet.
469

    
470
	<tag>router id <m/IPv4 address/</tag>
471
	This option can be used to override global router id for a
472
	given protocol. Default: uses global router id.
473

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

    
480
	<tag>export <m/filter/</tag>
481
	This is similar to the <cf>import</cf> keyword, except that it
482
	works in the direction from the routing table to the protocol.
483
	Default: <cf/none/.
484

    
485
	<tag>import keep filtered <m/switch/</tag>
486
	Usually, if an import filter rejects a route, the route is
487
	forgotten. When this option is active, these routes are
488
	kept in the routing table, but they are hidden and not
489
	propagated to other protocols. But it is possible to show them
490
	using <cf/show route filtered/. Note that this option does not
491
	work for the pipe protocol. Default: off.
492

    
493
	<tag><label id="import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
494
	Specify an import route limit (a maximum number of routes
495
	imported from the protocol) and optionally the action to be
496
	taken when the limit is hit. Warn action just prints warning
497
	log message. Block action discards new routes coming from the
498
	protocol. Restart and disable actions shut the protocol down
499
	like appropriate commands. Disable is the default action if an
500
	action is not explicitly specified. Note that limits are reset
501
	during protocol reconfigure, reload or restart. Default: <cf/off/.
502

    
503
	<tag>receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
504
	Specify an receive route limit (a maximum number of routes
505
	received from the protocol and remembered). It works almost
506
	identically to <cf>import limit</cf> option, the only
507
	difference is that if <cf/import keep filtered/ option is
508
	active, filtered routes are counted towards the limit and
509
	blocked routes are forgotten, as the main purpose of the
510
	receive limit is to protect routing tables from
511
	overflow. Import limit, on the contrary, counts accepted
512
	routes only and routes blocked by the limit are handled like
513
	filtered routes. Default: <cf/off/.
514

    
515
	<tag>export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
516
	Specify an export route limit, works similarly to
517
	the <cf>import limit</cf> option, but for the routes exported
518
	to the protocol. This option is experimental, there are some
519
	problems in details of its behavior -- the number of exported
520
	routes can temporarily exceed the limit without triggering it
521
	during protocol reload, exported routes counter ignores route
522
	blocking and block action also blocks route updates of already
523
	accepted routes -- and these details will probably change in
524
	the future. Default: <cf/off/.
525

    
526
	<tag>description "<m/text/"</tag>
527
	This is an optional description of the protocol. It is
528
	displayed as a part of the output of 'show route all' command.
529

    
530
	<tag>table <m/name/</tag>
531
	Connect this protocol to a non-default routing table.
532
</descrip>
533

    
534
<p>There are several options that give sense only with certain protocols:
535

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

    
539
	Specifies a set of interfaces on which the protocol is activated with
540
	given interface-specific options. A set of interfaces specified by one
541
	interface option is described using an interface pattern. The
542
	interface pattern consists of a sequence of clauses (separated by
543
	commas), each clause may contain a mask, a prefix, or both of them. An
544
	interface matches the clause if its name matches the mask (if
545
	specified) and its address matches the prefix (if specified). Mask is
546
	specified as shell-like pattern. For IPv6, the prefix part of a clause
547
	is generally ignored and interfaces are matched just by their name.
548

    
549
	An interface matches the pattern if it matches any of its
550
	clauses. If the clause begins with <cf/-/, matching interfaces are
551
	excluded. Patterns are parsed left-to-right, thus
552
	<cf/interface "eth0", -"eth*", "*";/ means eth0 and all
553
	non-ethernets.
554

    
555
	An interface option can be used more times with different
556
	interfaces-specific options, in that case for given interface
557
	the first matching interface option is used.
558
	
559
	This option is allowed in Direct, OSPF, RIP and RAdv protocols,
560
	but in OSPF protocol it is used in <cf/area/ subsection.
561

    
562
	Default: none.
563

    
564
	Examples:
565

    
566
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
567
	<cf>type broadcast</cf> option.
568

    
569
	<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the protocol
570
	on enumerated interfaces with <cf>type ptp</cf> option.
571
	
572
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
573
	interfaces that have address from 192.168.0.0/16, but not
574
	from 192.168.1.0/24.
575

    
576
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
577
	interfaces that have address from 192.168.0.0/16, but not
578
	from 192.168.1.0/24.
579

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

    
583
	<tag><label id="dsc-prio">tx class|dscp <m/num/</tag>
584
        This option specifies the value of ToS/DS/Class field in IP
585
        headers of the outgoing protocol packets. This may affect how the
586
        protocol packets are processed by the network relative to the
587
        other network traffic. With <cf/class/ keyword, the value
588
        (0-255) is used for the whole ToS/Class octet (but two bits
589
        reserved for ECN are ignored). With <cf/dscp/ keyword, the
590
        value (0-63) is used just for the DS field in the
591
        octet. Default value is 0xc0 (DSCP 0x30 - CS6).
592

    
593
	<tag>tx priority <m/num/</tag>
594
        This option specifies the local packet priority. This may
595
        affect how the protocol packets are processed in the local TX
596
        queues. This option is Linux specific. Default value is 7
597
        (highest priority, privileged traffic).
598

    
599
	<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>
600
	Specifies a password that can be used by the protocol. Password option can
601
	be used more times to specify more passwords. If more passwords are
602
	specified, it is a protocol-dependent decision which one is really
603
	used. Specifying passwords does not mean that authentication is
604
	enabled, authentication can be enabled by separate, protocol-dependent
605
	<cf/authentication/ option.
606
	
607
	This option is allowed in OSPF and RIP protocols. BGP has also
608
	<cf/password/ option, but it is slightly different and described
609
	separately.
610

    
611
	Default: none.
612
</descrip>
613

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

    
616
<descrip>
617
	<tag>id <M>num</M></tag>
618
	 ID of the password, (0-255). If it's not used, BIRD will choose
619
	 ID based on an order of the password item in the interface. For
620
	 example, second password item in one interface will have default
621
	 ID 2. ID is used by some routing protocols to identify which
622
	 password was used to authenticate protocol packets.
623

    
624
	<tag>generate from "<m/time/"</tag>
625
	 The start time of the usage of the password for packet signing.
626
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
627

    
628
	<tag>generate to "<m/time/"</tag>
629
	 The last time of the usage of the password for packet signing.
630

    
631
	<tag>accept from "<m/time/"</tag>
632
	 The start time of the usage of the password for packet verification.
633

    
634
	<tag>accept to "<m/time/"</tag>
635
	 The last time of the usage of the password for packet verification.
636
</descrip>
637

    
638
<chapt>Remote control
639

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

    
655
<p>There is also lightweight variant of BIRD client called
656
<file/birdcl/, which does not support command line editing and history
657
and has minimal dependencies. This is useful for running BIRD in
658
resource constrained environments, where Readline library (required
659
for regular BIRD client) is not available.
660

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

    
664
<p>Here is a brief list of supported functions:
665

    
666
<descrip>
667
	<tag>show status</tag>
668
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
669

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

    
673
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
674
	Show detailed information about OSPF interfaces.
675

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

    
679
	<tag>show ospf state [all] [<m/name/]</tag>
680
	Show detailed information about OSPF areas based on a content
681
	of the link-state database. It shows network topology, stub
682
	networks, aggregated networks and routers from other areas and
683
	external routes. The command shows information about reachable
684
	network nodes, use option <cf/all/ to show information about
685
	all network nodes in the link-state database.
686

    
687
	<tag>show ospf topology [all] [<m/name/]</tag>
688
	Show a topology of OSPF areas based on a content of the
689
	link-state database.  It is just a stripped-down version of
690
	'show ospf state'.
691

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

    
695
	<tag>show static [<m/name/]</tag>
696
	Show detailed information about static routes.
697

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

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

    
704
	<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>
705
	Show contents of a routing table (by default of the main one or
706
        the table attached to a respective protocol),
707
	that is routes, their metrics and (in case the <cf/all/ switch is given)
708
	all their attributes.
709

    
710
	<tag>show bfd sessions [<m/name/]</tag>
711
	Show information about BFD sessions.
712

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

    
720
	<p>You can also ask for printing only routes processed and accepted by
721
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
722
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
723
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
724
	that are exported to the specified protocol. With <cf/preexport/, the
725
	export filter of the protocol is skipped.
726

    
727
	<p>You can also select just routes added by a specific protocol.
728
	<cf>protocol <m/p/</cf>.
729

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

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

    
737
	<tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
738
	Show contents of a ROA table (by default of the first one).
739
	You can specify a <m/prefix/ to print ROA entries for a
740
	specific network. If you use <cf>for <m/prefix/</cf>, you'll
741
	get all entries relevant for route validation of the network
742
	prefix; i.e., ROA entries whose prefixes cover the network
743
	prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA entries
744
	covered by the network prefix. You could also use <cf/as/ option
745
	to show just entries for given AS.
746

    
747
	<tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
748
	Add a new ROA entry to a ROA table. Such entry is called
749
	<it/dynamic/ compared to <it/static/ entries specified in the
750
	config file. These dynamic entries survive reconfiguration.
751

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

    
757
	<tag>flush roa [table <m/t/>]</tag>
758
	Remove all dynamic ROA entries from a ROA table.
759

    
760
	<tag>configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
761
	Reload configuration from a given file. BIRD will smoothly
762
	switch itself to the new configuration, protocols are
763
	reconfigured if possible, restarted otherwise. Changes in
764
	filters usually lead to restart of affected protocols.
765

    
766
	If <cf/soft/ option is used, changes in filters does not cause
767
	BIRD to restart affected protocols, therefore already accepted
768
	routes (according to old filters) would be still propagated,
769
	but new routes would be processed according to the new
770
	filters.
771

    
772
	If <cf/timeout/ option is used, config timer is activated. The
773
	new configuration could be either confirmed using
774
	<cf/configure confirm/ command, or it will be reverted to the
775
	old one when the config timer expires. This is useful for cases
776
	when reconfiguration breaks current routing and a router becames
777
	inaccessible for an administrator. The config timeout expiration is
778
	equivalent to <cf/configure undo/ command. The timeout duration
779
	could be specified, default is 300 s.
780

    
781
	<tag>configure confirm</tag>
782
	Deactivate the config undo timer and therefore confirm the current
783
	configuration.
784

    
785
	<tag>configure undo</tag>
786
	Undo the last configuration change and smoothly switch back to
787
	the previous (stored) configuration. If the last configuration
788
	change was soft, the undo change is also soft. There is only
789
	one level of undo, but in some specific cases when several
790
	reconfiguration requests are given immediately in a row and
791
	the intermediate ones are skipped then the undo also skips them back.
792

    
793
	<tag>configure check ["<m/config file/"]</tag>
794
	Read and parse given config file, but do not use it. useful
795
	for checking syntactic and some semantic validity of an config
796
	file.
797

    
798
	<tag>enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
799
	Enable, disable or restart a given protocol instance,
800
	instances matching the <cf><m/pattern/</cf> or
801
	<cf/all/ instances.
802

    
803
	<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
804
	
805
	Reload a given protocol instance, that means re-import routes
806
	from the protocol instance and re-export preferred routes to
807
	the instance. If <cf/in/ or <cf/out/ options are used, the
808
	command is restricted to one direction (re-import or
809
	re-export).
810

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

    
816
	Re-export always succeeds, but re-import is protocol-dependent
817
	and might fail (for example, if BGP neighbor does not support
818
	route-refresh extension). In that case, re-export is also
819
	skipped. Note that for the pipe protocol, both directions are
820
	always reloaded together (<cf/in/ or <cf/out/ options are
821
	ignored in that case).
822

    
823
	<tag/down/
824
	Shut BIRD down.
825

    
826
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
827
	Control protocol debugging.
828

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

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

    
836
	<tag>eval <m/expr/</tag>
837
	Evaluate given expression.
838

    
839
</descrip>
840

    
841
<chapt>Filters
842

    
843
<sect>Introduction
844

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

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

    
855
<code>
856
filter not_too_far
857
int var;
858
{
859
	if defined( rip_metric ) then
860
		var = rip_metric;
861
	else {
862
		var = 1;
863
		rip_metric = 1;
864
	}
865
	if rip_metric &gt; 10 then
866
		reject "RIP metric is too big";
867
	else
868
		accept "ok";
869
}
870
</code>
871

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

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

    
883
<code>
884
function name ()
885
int local_variable;
886
{
887
	local_variable = 5;
888
}
889

    
890
function with_parameters (int parameter)
891
{
892
	print parameter;
893
}
894
</code>
895

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

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

    
907
<p>A nice trick to debug filters is to use <cf>show route filter
908
<m/name/</cf> from the command line client. An example session might look
909
like:
910

    
911
<code>
912
pavel@bug:~/bird$ ./birdc -s bird.ctl
913
BIRD 0.0.0 ready.
914
bird> show route
915
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
916
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
917
127.0.0.0/8        dev lo [direct1 23:21] (240)
918
bird> show route ?
919
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
920
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
921
127.0.0.0/8        dev lo [direct1 23:21] (240)
922
bird>
923
</code>
924

    
925
<sect>Data types
926

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

    
930
<descrip>
931
	<tag/bool/ This is a boolean type, it can have only two values,
932
	  <cf/true/ and <cf/false/. Boolean is the only type you can use in
933
	  <cf/if/ statements.
934

    
935
	<tag/int/ This is a general integer type. It is an unsigned 32bit type;
936
	  i.e., you can expect it to store values from 0 to 4294967295.
937
	  Overflows are not checked. You can use <cf/0x1234/ syntax to write
938
	  hexadecimal values.
939

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

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

    
949
	<tag/string/ This is a string of characters. There are no ways to modify
950
	  strings in filters. You can pass them between functions, assign them
951
	  to variables of type <cf/string/, print such variables, use standard
952
	  string comparison operations (e.g. <cf/=, !=, &lt;, &gt;, &lt;=,
953
	  &gt;=/), but you can't concatenate two strings. String literals are
954
	  written as <cf/"This is a string constant"/. Additionaly matching
955
	  <cf/&tilde;/ operator could be used to match a string value against a
956
	  shell pattern (represented also as a string).
957

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

    
966
	<tag/prefix/ This type can hold a network prefix consisting of IP
967
	  address and prefix length. Prefix literals are written
968
	  as <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
969
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
970
	  operators on prefixes: <cf/.ip/ which extracts the IP address from the
971
	  pair, and <cf/.len/, which separates prefix length from the
972
	  pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
973

    
974
	<tag/ec/ This is a specialized type used to represent BGP extended
975
	  community values. It is essentially a 64bit value, literals of this
976
	  type are usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>,
977
	  where <cf/kind/ is a kind of extended community (e.g. <cf/rt/ /
978
	  <cf/ro/ for a route target / route origin communities), the format and
979
	  possible values of <cf/key/ and <cf/value/ are usually integers, but
980
	  it depends on the used kind. Similarly to pairs, ECs can be
981
	  constructed using expressions for <cf/key/ and <cf/value/ parts,
982
	  (e.g. <cf/(ro, myas, 3*10)/, where <cf/myas/ is an integer variable).
983
 
984
	<tag/int|pair|quad|ip|prefix|ec|enum set/ Filters recognize four types
985
	  of sets. Sets are similar to strings: you can pass them around but you
986
	  can't modify them. Literals of type <cf>int set</cf> look like <cf> [
987
	  1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are
988
	  permitted in sets.
989

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

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

    
1001
	  You can also use expressions for int, pair and EC set values. However it must
1002
	  be possible to evaluate these expressions before daemon boots. So you can use
1003
	  only constants inside them. E.g.
1004
	<code>
1005
	 define one=1;
1006
	 define myas=64500;
1007
	 int set odds;
1008
	 pair set ps;
1009
	 ec set es;
1010

    
1011
	 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
1012
	 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
1013
	 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
1014
	</code>
1015

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

    
1024
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
1025
	  <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), 
1026
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
1027
	  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>
1028
	  and all its supernets (network prefixes that contain it).
1029

    
1030
	  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
1031
	  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
1032
	  <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
1033
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
1034
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
1035
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
1036

    
1037
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
1038
	  in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
1039
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
1040
	  <cf>192.168.0.0/16{24,32}</cf>.
1041

    
1042
	<tag/enum/
1043
	  Enumeration types are fixed sets of possibilities. You can't define your own
1044
	  variables of such type, but some route attributes are of enumeration
1045
	  type. Enumeration types are incompatible with each other.
1046

    
1047
	<tag/bgppath/
1048
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
1049
	  There are several special operators on bgppaths:
1050

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

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

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

    
1058
          <cf><m/P/.len</cf> returns the length of path <m/P/.
1059

    
1060
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path
1061
          <m/P/ and returns the result.
1062

    
1063
          <cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN
1064
	  <m/A/ from from path <m/P/ and returns the result.
1065
	  <m/A/ may also be an integer set, in that case the
1066
	  operator deletes all ASNs from path <m/P/ that are also
1067
	  members of set <m/A/.
1068

    
1069
          <cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path
1070
	  <m/P/ that are not members of integer set <m/A/.
1071
	  I.e., <cf/filter/ do the same as <cf/delete/ with inverted
1072
	  set <m/A/.
1073

    
1074
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
1075
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
1076
          (for example <cf/bgp_path/). Similarly for <cf/delete/ and <cf/filter/.
1077

    
1078
	<tag/bgpmask/
1079
	  BGP masks are patterns used for BGP path matching
1080
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
1081
	  resemble wildcard patterns as used by UNIX shells. Autonomous
1082
	  system numbers match themselves, <cf/*/ matches any (even empty)
1083
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
1084
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
1085
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
1086
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
1087
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
1088
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
1089
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
1090

    
1091
	<tag/clist/
1092
	  Clist is similar to a set, except that unlike other sets, it
1093
	  can be modified. The type is used for community list (a set
1094
	  of pairs) and for cluster list (a set of quads). There exist
1095
	  no literals of this type. There are three special operators on
1096
	  clists:
1097

    
1098
	  <cf><m/C/.len</cf> returns the length of clist <m/C/.
1099

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

    
1105
          <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad)
1106
	  <m/P/ from clist <m/C/ and returns the result.  If clist
1107
	  <m/C/ does not contain item <m/P/, it does nothing.
1108
	  <m/P/ may also be a pair (or quad) set, in that case the
1109
	  operator deletes all items from clist <m/C/ that are also
1110
	  members of set <m/P/. Moreover, <m/P/ may also be a clist,
1111
	  which works analogously; i.e., it works as clist difference.
1112

    
1113
          <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist
1114
	  <m/C/ that are not members of pair (or quad) set <m/P/.
1115
	  I.e., <cf/filter/ do the same as <cf/delete/ with inverted
1116
	  set <m/P/. <m/P/ may also be a clist, which works analogously;
1117
	  i.e., it works as clist intersection.
1118

    
1119
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1120
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route
1121
          attribute (for example <cf/bgp_community/). Similarly for
1122
          <cf/delete/ and <cf/filter/.
1123

    
1124
	<tag/eclist/
1125
	  Eclist is a data type used for BGP extended community lists.
1126
	  Eclists are very similar to clists, but they are sets of ECs
1127
	  instead of pairs. The same operations (like <cf/add/,
1128
	  <cf/delete/, or <cf/&tilde;/ membership operator) can be
1129
	  used to modify or test eclists, with ECs instead of pairs as
1130
	  arguments.
1131
</descrip>
1132

    
1133
<sect>Operators
1134

    
1135
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
1136
<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;/). 
1137
Special operators include <cf/&tilde;/ for "is element of a set" operation - it can be
1138
used on element and set of elements of the same type (returning true if element is contained in the given set), or
1139
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
1140
prefix and prefix (returning true if first prefix is more specific than second one) or on bgppath and bgpmask (returning true if the path matches the mask) or on number and bgppath (returning true if the number is in the path) or on bgppath and int (number) set (returning true if any ASN from the path is in the set) or on pair/quad and clist (returning true if the pair/quad is element of the clist) or on clist and pair/quad set (returning true if there is an element of the clist that is also a member of the pair/quad set).
1141

    
1142
<p>There is one operator related to ROA infrastructure -
1143
<cf/roa_check()/. It examines a ROA table and does RFC 6483 route
1144
origin validation for a given network prefix. The basic usage
1145
is <cf>roa_check(<m/table/)</cf>, which checks current route (which
1146
should be from BGP to have AS_PATH argument) in the specified ROA
1147
table and returns ROA_UNKNOWN if there is no relevant ROA, ROA_VALID
1148
if there is a matching ROA, or ROA_INVALID if there are some relevant
1149
ROAs but none of them match. There is also an extended variant
1150
<cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to
1151
specify a prefix and an ASN as arguments.
1152

    
1153

    
1154
<sect>Control structures
1155

    
1156
<p>Filters support two control structures: conditions and case switches. 
1157

    
1158
<p>Syntax of a condition is: <cf>if
1159
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
1160
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
1161
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.
1162

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

    
1169
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
1170

    
1171
<code>
1172
case arg1 {
1173
	2: print "two"; print "I can do more commands without {}";
1174
	3 .. 5: print "three to five";
1175
	else: print "something else";
1176
}
1177

    
1178
if 1234 = i then printn "."; else { 
1179
  print "not 1234"; 
1180
  print "You need {} around multiple commands"; 
1181
}
1182
</code>
1183

    
1184
<sect>Route attributes
1185

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

    
1193
<descrip>
1194
	<tag><m/prefix/ net</tag>
1195
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
1196

    
1197
	<tag><m/enum/ scope</tag>
1198
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for
1199
	routes local to this host, <cf/SCOPE_LINK/ for those specific
1200
	for a physical link, <cf/SCOPE_SITE/ and
1201
	<cf/SCOPE_ORGANIZATION/ for private routes and
1202
	<cf/SCOPE_UNIVERSE/ for globally visible routes. This
1203
	attribute is not interpreted by BIRD and can be used to mark
1204
	routes in filters. The default value for new routes is
1205
	<cf/SCOPE_UNIVERSE/.
1206

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

    
1210
	<tag><m/ip/ from</tag>
1211
	The router which the route has originated from.
1212
	
1213
	<tag><m/ip/ gw</tag>
1214
	Next hop packets routed using this route should be forwarded to.
1215

    
1216
	<tag><m/string/ proto</tag>
1217
	The name of the protocol which the route has been imported from. Read-only.
1218

    
1219
	<tag><m/enum/ source</tag>
1220
	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/.
1221

    
1222
	<tag><m/enum/ cast</tag>
1223
	Route type (Currently <cf/RTC_UNICAST/ for normal routes,
1224
	<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will
1225
	be used in the future for broadcast, multicast and anycast
1226
	routes). Read-only.
1227

    
1228
	<tag><m/enum/ dest</tag>
1229
	Type of destination the packets should be sent to
1230
	(<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1231
	<cf/RTD_DEVICE/ for routing to a directly-connected network,
1232
	<cf/RTD_MULTIPATH/ for multipath destinations,
1233
	<cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1234
	<cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that
1235
	should be returned with ICMP host unreachable / ICMP
1236
	administratively prohibited messages). Can be changed, but
1237
	only to <cf/RTD_BLACKHOLE/, <cf/RTD_UNREACHABLE/ or
1238
	<cf/RTD_PROHIBIT/.
1239

    
1240
	<tag><m/string/ ifname</tag>
1241
	Name of the outgoing interface. Sink routes (like blackhole,
1242
	unreachable or prohibit) and multipath routes have no interface
1243
	associated with them, so <cf/ifname/ returns an empty string for
1244
	such routes. Read-only.
1245

    
1246
	<tag><m/int/ ifindex</tag>
1247
	Index of the outgoing interface. System wide index of the
1248
	interface. May be used for interface matching, however
1249
	indexes might change on interface creation/removal. Zero is
1250
	returned for routes with undefined outgoing
1251
	interfaces. Read-only.
1252

    
1253
	<tag><m/int/ igp_metric</tag>
1254
	The optional attribute that can be used to specify a distance
1255
	to the network for routes that do not have a native protocol
1256
	metric attribute (like <cf/ospf_metric1/ for OSPF routes). It
1257
	is used mainly by BGP to compare internal distances to boundary
1258
	routers (see below). It is also used when the route is exported
1259
	to OSPF as a default value for OSPF type 1 metric.
1260
</descrip>
1261

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

    
1264
<sect>Other statements
1265

    
1266
<p>The following statements are available:
1267

    
1268
<descrip>
1269
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
1270

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

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

    
1275
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
1276
	Prints given expressions; useful mainly while debugging
1277
	filters. The <cf/printn/ variant does not terminate the line.
1278

    
1279
	<tag>quitbird</tag>
1280
	Terminates BIRD. Useful when debugging the filter interpreter.
1281
</descrip>
1282

    
1283
<chapt>Protocols
1284

    
1285
<sect><label id="sect-bfd">BFD
1286

    
1287
<sect1>Introduction
1288

    
1289
<p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
1290
is an independent tool providing liveness and failure detection. Routing
1291
protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
1292
liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
1293
seconds by default in OSPF, could be set down to several seconds). BFD offers
1294
universal, fast and low-overhead mechanism for failure detection, which could be
1295
attached to any routing protocol in an advisory role.
1296

    
1297
<p>BFD consists of mostly independent BFD sessions. Each session monitors an
1298
unicast bidirectional path between two BFD-enabled routers. This is done by
1299
periodically sending control packets in both directions. BFD does not handle
1300
neighbor discovery, BFD sessions are created on demand by request of other
1301
protocols (like OSPF or BGP), which supply appropriate information like IP
1302
addresses and associated interfaces. When a session changes its state, these
1303
protocols are notified and act accordingly (e.g. break an OSPF adjacency when
1304
the BFD session went down).
1305

    
1306
<p>BIRD implements basic BFD behavior as defined in
1307
RFC 5880<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5880.txt">
1308
(some advanced features like the echo mode or authentication are not implemented),
1309
IP transport for BFD as defined in
1310
RFC 5881<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5881.txt"> and
1311
RFC 5883<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5883.txt">
1312
and interaction with client protocols as defined in
1313
RFC 5882<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5882.txt">.
1314

    
1315
<p>Note that BFD implementation in BIRD is currently a new feature in
1316
development, expect some rough edges and possible UI and configuration changes
1317
in the future. Also note that we currently support at most one protocol instance.
1318

    
1319
<sect1>Configuration
1320

    
1321
<p>BFD configuration consists mainly of multiple definitions of interfaces.
1322
Most BFD config options are session specific. When a new session is requested
1323
and dynamically created, it is configured from one of these definitions. For
1324
sessions to directly connected neighbors, <cf/interface/ definitions are chosen
1325
based on the interface associated with the session, while <cf/multihop/
1326
definition is used for multihop sessions. If no definition is relevant, the
1327
session is just created with the default configuration. Therefore, an empty BFD
1328
configuration is often sufficient.
1329

    
1330
<p>Note that to use BFD for other protocols like OSPF or BGP, these protocols
1331
also have to be configured to request BFD sessions, usually by <cf/bfd/ option.
1332

    
1333
<p>Some of BFD session options require <m/time/ value, which has to be specified
1334
with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds
1335
are allowed as units, practical minimum values are usually in order of tens of
1336
milliseconds.
1337

    
1338
<code>
1339
protocol bfd [&lt;name&gt;] {
1340
	interface &lt;interface pattern&gt; {
1341
		interval &lt;time&gt;;
1342
		min rx interval &lt;time&gt;;
1343
		min tx interval &lt;time&gt;;
1344
		idle tx interval &lt;time&gt;;
1345
		multiplier &lt;num&gt;;
1346
		passive &lt;switch&gt;;
1347
	};
1348
	multihop {
1349
		interval &lt;time&gt;;
1350
		min rx interval &lt;time&gt;;
1351
		min tx interval &lt;time&gt;;
1352
		idle tx interval &lt;time&gt;;
1353
		multiplier &lt;num&gt;;
1354
		passive &lt;switch&gt;;
1355
	};
1356
	neighbor &lt;ip&gt; [dev "&lt;interface&gt;"] [local &lt;ip&gt;] [multihop &lt;switch&gt;];
1357
}
1358
</code>
1359

    
1360
<descrip>
1361
	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag>
1362
	Interface definitions allow to specify options for sessions associated
1363
	with such interfaces and also may contain interface specific options.
1364
	See <ref id="dsc-iface" name="interface"> common option for a detailed
1365
	description of interface patterns. Note that contrary to the behavior of
1366
	<cf/interface/ definitions of other protocols, BFD protocol would accept
1367
	sessions (in default configuration) even on interfaces not covered by
1368
	such definitions.
1369

    
1370
	<tag>multihop { <m/options/ }</tag>
1371
	Multihop definitions allow to specify options for multihop BFD sessions,
1372
	in the same manner as <cf/interface/ definitions are used for directly
1373
	connected sessions. Currently only one such definition (for all multihop
1374
	sessions) could be used.
1375

    
1376
	<tag>neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>
1377
	BFD sessions are usually created on demand as requested by other
1378
	protocols (like OSPF or BGP). This option allows to explicitly add
1379
	a BFD session to the specified neighbor regardless of such requests.
1380
	
1381
	The session is identified by the IP address of the neighbor, with
1382
	optional specification of used interface and local IP.  By default
1383
	the neighbor must be directly connected, unless the the session is
1384
	configured as multihop. Note that local IP must be specified for
1385
	multihop sessions.
1386
</descrip>
1387

    
1388
<p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):
1389

    
1390
<descrip>
1391
	<tag>interval <m/time/</tag>
1392
	BFD ensures availability of the forwarding path associated with the
1393
	session by periodically sending BFD control packets in both
1394
	directions. The rate of such packets is controlled by two options,
1395
	<cf/min rx interval/ and <cf/min tx interval/ (see below). This option
1396
	is just a shorthand to set both of these options together.
1397

    
1398
	<tag>min rx interval <m/time/</tag>
1399
	This option specifies the minimum RX interval, which is announced to the
1400
	neighbor and used there to limit the neighbor's rate of generated BFD
1401
	control packets. Default: 10 ms.
1402

    
1403
	<tag>min tx interval <m/time/</tag>
1404
	This option specifies the desired TX interval, which controls the rate
1405
	of generated BFD control packets (together with <cf/min rx interval/
1406
	announced by the neighbor). Note that this value is used only if the BFD
1407
	session is up, otherwise the value of <cf/idle tx interval/ is used
1408
	instead. Default: 100 ms.
1409

    
1410
	<tag>idle tx interval <m/time/</tag>
1411
	In order to limit unnecessary traffic in cases where a neighbor is not
1412
	available or not running BFD, the rate of generated BFD control packets
1413
	is lower when the BFD session is not up. This option specifies the
1414
	desired TX interval in such cases instead of <cf/min tx interval/.
1415
	Default: 1 s.
1416

    
1417
	<tag>multiplier <m/num/</tag>
1418
	Failure detection time for BFD sessions is based on established rate of
1419
	BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this
1420
	multiplier, which is essentially (ignoring jitter) a number of missed
1421
	packets after which the session is declared down. Note that rates and
1422
	multipliers could be different in each direction of a BFD session.
1423
	Default: 5.
1424

    
1425
	<tag>passive <m/switch/</tag>
1426
	Generally, both BFD session endpoinds try to establish the session by
1427
	sending control packets to the other side. This option allows to enable
1428
	passive mode, which means that the router does not send BFD packets
1429
	until it has received one from the other side. Default: disabled.
1430
</descrip>
1431

    
1432
<sect1>Example
1433

    
1434
<p><code>
1435
protocol bfd {
1436
	interface "eth*" {
1437
		min rx interval 20 ms;
1438
		min tx interval 50 ms;
1439
		idle tx interval 300 ms;
1440
	};
1441
	interface "gre*" {
1442
		interval 200 ms;
1443
		multiplier 10;
1444
		passive;
1445
	};
1446
	multihop {
1447
		interval 200 ms;
1448
		multiplier 10;
1449
	};
1450

    
1451
	neighbor 192.168.1.10;
1452
	neighbor 192.168.2.2 dev "eth2";
1453
	neighbor 192.168.10.1 local 192.168.1.1 multihop;
1454
}
1455
</code>
1456

    
1457
<sect>BGP
1458

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

    
1466
<p>BGP works in terms of autonomous systems (often abbreviated as
1467
AS). Each AS is a part of the network with common management and
1468
common routing policy. It is identified by a unique 16-bit number
1469
(ASN).  Routers within each AS usually exchange AS-internal routing
1470
information with each other using an interior gateway protocol (IGP,
1471
such as OSPF or RIP). Boundary routers at the border of the AS
1472
communicate global (inter-AS) network reachability information with
1473
their neighbors in the neighboring AS'es via exterior BGP (eBGP) and
1474
redistribute received information to other routers in the AS via
1475
interior BGP (iBGP).
1476

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

    
1482
<p>BIRD supports all requirements of the BGP4 standard as defined in
1483
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
1484
It also supports the community attributes
1485
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
1486
capability negotiation
1487
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
1488
MD5 password authentication
1489
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
1490
extended communities
1491
(RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">),
1492
route reflectors 
1493
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
1494
multiprotocol extensions
1495
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
1496
4B AS numbers 
1497
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">),
1498
and 4B AS numbers in extended communities
1499
(RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">).
1500

    
1501

    
1502
For IPv6, it uses the standard multiprotocol extensions defined in
1503
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
1504
including changes described in the
1505
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
1506
and applied to IPv6 according to
1507
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
1508

    
1509
<sect1>Route selection rules
1510

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

    
1517
<itemize>
1518
	<item>Prefer route with the highest Local Preference attribute.
1519
	<item>Prefer route with the shortest AS path.
1520
	<item>Prefer IGP origin over EGP and EGP origin over incomplete.
1521
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
1522
	<item>Prefer routes received via eBGP over ones received via iBGP.
1523
	<item>Prefer routes with lower internal distance to a boundary router.
1524
	<item>Prefer the route with the lowest value of router ID of the
1525
	advertising router.
1526
</itemize>
1527

    
1528
<sect1>IGP routing table
1529

    
1530
<p>BGP is mainly concerned with global network reachability and with
1531
routes to other autonomous systems. When such routes are redistributed
1532
to routers in the AS via BGP, they contain IP addresses of a boundary
1533
routers (in route attribute NEXT_HOP). BGP depends on existing IGP
1534
routing table with AS-internal routes to determine immediate next hops
1535
for routes and to know their internal distances to boundary routers
1536
for the purpose of BGP route selection. In BIRD, there is usually
1537
one routing table used for both IGP routes and BGP routes.
1538

    
1539
<sect1>Configuration
1540

    
1541
<p>Each instance of the BGP corresponds to one neighboring router.
1542
This allows to set routing policy and all the other parameters differently
1543
for each neighbor using the following configuration parameters:
1544

    
1545
<descrip>
1546
	<tag>local [<m/ip/] as <m/number/</tag> Define which AS we are part
1547
	of. (Note that contrary to other IP routers, BIRD is able to act as a
1548
	router located in multiple AS'es simultaneously, but in such cases you
1549
	need to tweak the BGP paths manually in the filters to get consistent
1550
	behavior.) Optional <cf/ip/ argument specifies a source address,
1551
	equivalent to the <cf/source address/ option (see below).  This
1552
	parameter is mandatory.
1553

    
1554
	<tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router this
1555
	instance will be talking to and what AS it's located in. In case the
1556
	neighbor is in the same AS as we are, we automatically switch to iBGP.
1557
	This parameter is mandatory.
1558

    
1559
	<tag>direct</tag> Specify that the neighbor is directly connected. The
1560
	IP address of the neighbor must be from a directly reachable IP range
1561
	(i.e. associated with one of your router's interfaces), otherwise the
1562
	BGP session wouldn't start but it would wait for such interface to
1563
	appear. The alternative is the <cf/multihop/ option.  Default: enabled
1564
	for eBGP.
1565

    
1566
	<tag>multihop [<m/number/]</tag> Configure multihop BGP session to a
1567
	neighbor that isn't directly connected.  Accurately, this option should
1568
	be used if the configured neighbor IP address does not match with any
1569
	local network subnets. Such IP address have to be reachable through
1570
	system routing table.  The alternative is the <cf/direct/ option. For
1571
	multihop BGP it is recommended to explicitly configure the source
1572
	address to have it stable. Optional <cf/number/ argument can be used to
1573
	specify the number of hops (used for TTL). Note that the number of
1574
	networks (edges) in a path is counted; i.e., if two BGP speakers are
1575
	separated by one router, the number of hops is 2. Default: enabled for
1576
	iBGP.
1577

    
1578
	<tag>source address <m/ip/</tag> Define local address we
1579
	should use for next hop calculation and as a source address
1580
	for the BGP session. Default: the address of the local
1581
	end of the interface our neighbor is connected to.
1582

    
1583
	<tag>next hop self</tag> Avoid calculation of the Next Hop
1584
	attribute and always advertise our own source address as a
1585
	next hop.  This needs to be used only occasionally to
1586
	circumvent misconfigurations of other routers.  Default:
1587
	disabled.
1588

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

    
1594
	<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
1595
	in BGP-IPv6 sometimes contains just the global IPv6 address,
1596
	but sometimes it has to contain both global and link-local
1597
	IPv6 addresses. This option specifies what to do if BIRD have
1598
	to send both addresses but does not know link-local address.
1599
	This situation might happen when routes from other protocols
1600
	are exported to BGP, or when improper updates are received
1601
	from BGP peers.  <cf/self/ means that BIRD advertises its own
1602
	local address instead. <cf/drop/ means that BIRD skips that
1603
	prefixes and logs error. <cf/ignore/ means that BIRD ignores
1604
	the problem and sends just the global address (and therefore
1605
	forms improper BGP update). Default: <cf/self/, unless BIRD
1606
	is configured as a route server (option <cf/rs client/), in
1607
	that case default is <cf/ignore/, because route servers usually
1608
	do not forward packets themselves.
1609

    
1610
	<tag>gateway direct|recursive</tag>For received routes, their
1611
	<cf/gw/ (immediate next hop) attribute is computed from
1612
	received <cf/bgp_next_hop/ attribute. This option specifies
1613
	how it is computed. Direct mode means that the IP address from
1614
	<cf/bgp_next_hop/ is used if it is directly reachable,
1615
	otherwise the neighbor IP address is used. Recursive mode
1616
	means that the gateway is computed by an IGP routing table
1617
	lookup for the IP address from <cf/bgp_next_hop/. Recursive
1618
	mode is the behavior specified by the BGP standard. Direct
1619
	mode is simpler, does not require any routes in a routing
1620
	table, and was used in older versions of BIRD, but does not
1621
	handle well nontrivial iBGP setups and multihop.  Recursive
1622
	mode is incompatible with <ref id="dsc-sorted" name="sorted
1623
	tables">. Default: <cf/direct/ for direct sessions,
1624
	<cf/recursive/ for multihop sessions.
1625

    
1626
	<tag>igp table <m/name/</tag> Specifies a table that is used
1627
	as an IGP routing table. Default: the same as the table BGP is
1628
	connected to.
1629

    
1630
	<tag>bfd <M>switch</M></tag>
1631
	BGP could use BFD protocol as an advisory mechanism for neighbor
1632
	liveness and failure detection. If enabled, BIRD setups a BFD session
1633
	for the BGP neighbor and tracks its liveness by it. This has an
1634
	advantage of an order of magnitude lower detection times in case of
1635
	failure. Note that BFD protocol also has to be configured, see
1636
	<ref id="sect-bfd" name="BFD"> section for details. Default: disabled.
1637

    
1638
	<tag>ttl security <m/switch/</tag> Use GTSM (RFC 5082 - the
1639
	generalized TTL security mechanism). GTSM protects against
1640
	spoofed packets by ignoring received packets with a smaller
1641
	than expected TTL. To work properly, GTSM have to be enabled
1642
	on both sides of a BGP session. If both <cf/ttl security/ and
1643
	<cf/multihop/ options are enabled, <cf/multihop/ option should
1644
	specify proper hop value to compute expected TTL. Kernel
1645
	support required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD:
1646
	since long ago, IPv4 only. Note that full (ICMP protection,
1647
	for example) RFC 5082 support is provided by Linux
1648
	only. Default: disabled.
1649
	
1650
	<tag>password <m/string/</tag> Use this password for MD5 authentication
1651
	of BGP sessions. Default: no authentication. Password has to be set by
1652
	external utility (e.g. setkey(8)) on BSD systems.
1653

    
1654
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
1655
        initiating outgoing connections and accepting incoming
1656
        connections. In passive mode, outgoing connections are not
1657
        initiated. Default: off.
1658

    
1659
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
1660
	a route reflection client. Default: disabled.
1661

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

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

    
1678
	<tag>secondary <m/switch/</tag> Usually, if an import filter
1679
	rejects a selected route, no other route is propagated for
1680
	that network. This option allows to try the next route in
1681
	order until one that is accepted is found or all routes for
1682
	that network are rejected. This can be used for route servers
1683
	that need to propagate different tables to each client but do
1684
	not want to have these tables explicitly (to conserve memory).
1685
	This option requires that the connected routing table is
1686
	<ref id="dsc-sorted" name="sorted">. Default: off.
1687

    
1688
	<tag>allow local as [<m/number/]</tag> 
1689
	BGP prevents routing loops by rejecting received routes with
1690
	the local AS number in the AS path. This option allows to
1691
	loose or disable the check. Optional <cf/number/ argument can
1692
	be used to specify the maximum number of local ASNs in the AS
1693
	path that is allowed for received routes. When the option is
1694
	used without the argument, the check is completely disabled
1695
	and you should ensure loop-free behavior by some other means.
1696
	Default: 0 (no local AS number allowed).
1697

    
1698
	<tag>enable route refresh <m/switch/</tag> When BGP speaker
1699
	changes its import filter, it has to re-examine all routes
1700
	received from its neighbor against the new filter. As these
1701
	routes might not be available, there is a BGP protocol
1702
	extension Route Refresh (specified in RFC 2918) that allows
1703
	BGP speaker to request re-advertisement of all routes from its
1704
	neighbor. This option specifies whether BIRD advertises this
1705
	capability and accepts such requests. Even when disabled, BIRD
1706
	can send route refresh requests. Default: on.
1707

    
1708
	<tag>interpret communities <m/switch/</tag> RFC 1997 demands
1709
	that BGP speaker should process well-known communities like
1710
	no-export (65535, 65281) or no-advertise (65535, 65282). For
1711
	example, received route carrying a no-adverise community
1712
	should not be advertised to any of its neighbors. If this
1713
	option is enabled (which is by default), BIRD has such
1714
	behavior automatically (it is evaluated when a route is
1715
	exported to the BGP protocol just before the export filter).
1716
	Otherwise, this integrated processing of well-known
1717
	communities is disabled. In that case, similar behavior can be
1718
	implemented in the export filter.  Default: on.
1719

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

    
1728
	<tag>capabilities <m/switch/</tag> Use capability advertisement
1729
	to advertise optional capabilities. This is standard behavior
1730
	for newer BGP implementations, but there might be some older
1731
	BGP implementations that reject such connection attempts.
1732
	When disabled (off), features that request it (4B AS support)
1733
	are also disabled. Default: on, with automatic fallback to
1734
	off when received capability-related error.
1735

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

    
1742
	<tag>route limit <m/number/</tag> The maximal number of routes
1743
	that may be imported from the protocol. If the route limit is
1744
	exceeded, the connection is closed with an error. Limit is currently implemented as
1745
	<cf/import limit <m/number/ action restart/. This option is obsolete and it is
1746
        replaced by <ref id="import-limit" name="import limit option">.  Default: no limit.
1747

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

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

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

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

    
1764
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
1765
	retrying a failed attempt to connect. Default: 120 seconds.
1766

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

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

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

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

    
1782
	<tag>med metric <m/switch/</tag> Enable comparison of MED
1783
	attributes (during best route selection) even between routes
1784
	received from different ASes.  This may be useful if all MED
1785
	attributes contain some consistent metric, perhaps enforced in
1786
	import filters of AS boundary routers. If this option is
1787
	disabled, MED attributes are compared only if routes are
1788
	received from the same AS (which is the standard behavior).
1789
	Default: off.
1790

    
1791
	<tag>deterministic med <m/switch/</tag> BGP route selection
1792
	algorithm is often viewed as a comparison between individual
1793
	routes (e.g. if a new route appears and is better than the
1794
	current best one, it is chosen as the new best one). But the
1795
	proper route selection, as specified by RFC 4271, cannot be
1796
	fully implemented in that way. The problem is mainly in
1797
	handling the MED attribute. BIRD, by default, uses an
1798
	simplification based on individual route comparison, which in
1799
	some cases may lead to temporally dependent behavior (i.e. the
1800
	selection is dependent on the order in which routes appeared).
1801
	This option enables a different (and slower) algorithm
1802
	implementing proper RFC 4271 route selection, which is
1803
	deterministic. Alternative way how to get deterministic
1804
	behavior is to use <cf/med metric/ option. This option is
1805
	incompatible with <ref id="dsc-sorted" name="sorted tables">.
1806
	Default: off.
1807

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

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

    
1816
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
1817
	Discriminator to be used during route selection when the MED attribute
1818
	is missing. Default: 0.
1819

    
1820
	<tag>default bgp_local_pref <m/number/</tag> A default value
1821
	for the Local Preference attribute. It is used when a new
1822
	Local Preference attribute is attached to a route by the BGP
1823
	protocol itself (for example, if a route is received through
1824
	eBGP and therefore does not have such attribute). Default: 100
1825
	(0 in pre-1.2.0 versions of BIRD).
1826
</descrip>
1827

    
1828
<sect1>Attributes
1829

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

    
1834
<descrip>
1835
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1836
	the packet will travel through when forwarded according to the particular route.
1837
	In case of internal BGP it doesn't contain the number of the local AS.
1838

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

    
1843
	<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
1844
	is an optional attribute which is used on external (inter-AS) links to
1845
	convey to an adjacent AS the optimal entry point into the local AS.
1846
	The received attribute is also propagated over internal BGP links.
1847
	The attribute value is zeroed when a route is exported to an external BGP
1848
	instance to ensure that the attribute received from a neighboring AS is
1849
	not propagated to other neighboring ASes. A new value might be set in
1850
	the export filter of an external BGP instance.
1851
	See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
1852
	for further discussion of BGP MED attribute.
1853

    
1854
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1855
	if the route has originated in an interior routing protocol or
1856
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1857
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1858
	is unknown.
1859

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

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

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

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

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

    
1894
	<tag>clist <cf/bgp_cluster_list/ [I, O]</tag> This attribute contains a list
1895
	of cluster IDs of route reflectors. Each route reflector prepends its
1896
	cluster ID when reflecting the route.
1897
</descrip>
1898

    
1899
<sect1>Example
1900

    
1901
<p><code>
1902
protocol bgp {
1903
	local as 65000;			     # Use a private AS number
1904
	neighbor 198.51.100.130 as 64496;    # Our neighbor ...
1905
	multihop;			     # ... which is connected indirectly
1906
	export filter {			     # We use non-trivial export rules
1907
		if source = RTS_STATIC then { # Export only static routes
1908
		        # Assign our community
1909
			bgp_community.add((65000,64501));
1910
			# Artificially increase path length
1911
			# by advertising local AS number twice
1912
			if bgp_path ~ [= 65000 =] then
1913
				bgp_path.prepend(65000);
1914
			accept;
1915
		}
1916
		reject;
1917
	};
1918
	import all;
1919
	source address 198.51.100.14;	# Use a non-standard source address
1920
}
1921
</code>
1922

    
1923
<sect>Device
1924

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

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

    
1933
<sect1>Configuration
1934

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

    
1942
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1943
	If a network interface has more than one network address, BIRD
1944
	has to choose one of them as a primary one. By default, BIRD
1945
	chooses the lexicographically smallest address as the primary
1946
	one.
1947

    
1948
	This option allows to specify which network address should be
1949
	chosen as a primary one. Network addresses that match
1950
	<m/prefix/ are preferred to non-matching addresses. If more
1951
	<cf/primary/ options are used, the first one has the highest
1952
	preference. If "<m/mask/" is specified, then such
1953
	<cf/primary/ option is relevant only to matching network
1954
	interfaces.
1955

    
1956
	In all cases, an address marked by operating system as
1957
	secondary cannot be chosen as the primary one. 
1958
</descrip>
1959

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

    
1963
<p><code>
1964
protocol device {
1965
	scan time 10;		# Scan the interfaces often
1966
	primary "eth0" 192.168.1.1;
1967
	primary 192.168.0.0/16;
1968
}
1969
</code>
1970

    
1971
<sect>Direct
1972

    
1973
<p>The Direct protocol is a simple generator of device routes for all the
1974
directly connected networks according to the list of interfaces provided
1975
by the kernel via the Device protocol.
1976

    
1977
<p>The question is whether it is a good idea to have such device
1978
routes in BIRD routing table. OS kernel usually handles device routes
1979
for directly connected networks by itself so we don't need (and don't
1980
want) to export these routes to the kernel protocol. OSPF protocol
1981
creates device routes for its interfaces itself and BGP protocol is
1982
usually used for exporting aggregate routes. Although there are some
1983
use cases that use the direct protocol (like abusing eBGP as an IGP
1984
routing protocol), in most cases it is not needed to have these device
1985
routes in BIRD routing table and to use the direct protocol.
1986

    
1987
<p>There is one notable case when you definitely want to use the
1988
direct protocol -- running BIRD on BSD systems. Having high priority
1989
device routes for directly connected networks from the direct protocol
1990
protects kernel device routes from being overwritten or removed by IGP
1991
routes during some transient network conditions, because a lower
1992
priority IGP route for the same network is not exported to the kernel
1993
routing table. This is an issue on BSD systems only, as on Linux
1994
systems BIRD cannot change non-BIRD route in the kernel routing table.
1995

    
1996
<p>The only configurable thing about direct is what interfaces it watches:
1997

    
1998
<p><descrip>
1999
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
2000
	protocol will generate device routes for all the interfaces
2001
	available. If you want to restrict it to some subset of interfaces
2002
	(for example if you're using multiple routing tables for policy
2003
	routing and some of the policy domains don't contain all interfaces),
2004
	just use this clause.
2005
</descrip>
2006

    
2007
<p>Direct device routes don't contain any specific attributes.
2008

    
2009
<p>Example config might look like this:
2010

    
2011
<p><code>
2012
protocol direct {
2013
	interface "-arc*", "*";		# Exclude the ARCnets
2014
}
2015
</code>
2016

    
2017
<sect>Kernel
2018

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

    
2028
<p>Unfortunately, there is one thing that makes the routing table
2029
synchronization a bit more complicated. In the kernel routing table
2030
there are also device routes for directly connected networks. These
2031
routes are usually managed by OS itself (as a part of IP address
2032
configuration) and we don't want to touch that.  They are completely
2033
ignored during the scan of the kernel tables and also the export of
2034
device routes from BIRD tables to kernel routing tables is restricted
2035
to prevent accidental interference. This restriction can be disabled using
2036
<cf/device routes/ switch.
2037

    
2038
<p>If your OS supports only a single routing table, you can configure
2039
only one instance of the Kernel protocol. If it supports multiple
2040
tables (in order to allow policy routing; such an OS is for example
2041
Linux), you can run as many instances as you want, but each of them
2042
must be connected to a different BIRD routing table and to a different
2043
kernel table.
2044

    
2045
<p>Because the kernel protocol is partially integrated with the
2046
connected routing table, there are two limitations - it is not
2047
possible to connect more kernel protocols to the same routing table
2048
and changing route destination/gateway in an export
2049
filter of a kernel protocol does not work. Both limitations can be
2050
overcome using another routing table and the pipe protocol.
2051

    
2052
<sect1>Configuration
2053

    
2054
<p><descrip>
2055
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
2056
	routing tables when it exits (instead of cleaning them up).
2057
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
2058
	kernel routing table.
2059
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
2060
	routing tables by other routing daemons or by the system administrator.
2061
	This is possible only on systems which support identification of route
2062
	authorship.
2063

    
2064
	<tag>device routes <m/switch/</tag> Enable export of device
2065
	routes to the kernel routing table. By default, such routes
2066
	are rejected (with the exception of explicitly configured
2067
	device routes from the static protocol) regardless of the
2068
	export filter to protect device routes in kernel routing table
2069
	(managed by OS itself) from accidental overwriting or erasing.
2070

    
2071
	<tag>kernel table <m/number/</tag> Select which kernel table should
2072
	this particular instance of the Kernel protocol work with. Available
2073
	only on systems supporting multiple routing tables.
2074
</descrip>
2075

    
2076
<sect1>Attributes
2077

    
2078
<p>The Kernel protocol defines several attributes. These attributes
2079
are translated to appropriate system (and OS-specific) route attributes.
2080
We support these attributes:
2081

    
2082
<descrip>
2083
	<tag>int <cf/krt_source/</tag> The original source of the imported
2084
	kernel route.  The value is system-dependent. On Linux, it is
2085
	a value of the protocol field of the route. See
2086
	/etc/iproute2/rt_protos for common values.  On BSD, it is
2087
	based on STATIC and PROTOx flags. The attribute is read-only.
2088

    
2089
	<tag>int <cf/krt_metric/</tag> The kernel metric of
2090
	the route.  When multiple same routes are in a kernel routing
2091
	table, the Linux kernel chooses one with lower metric.
2092

    
2093
	<tag>ip <cf/krt_prefsrc/</tag> (Linux) The preferred source address.
2094
 	Used in source address selection for outgoing packets. Have to
2095
 	be one of IP addresses of the router.
2096

    
2097
	<tag>int <cf/krt_realm/</tag> (Linux) The realm of the route. Can be
2098
	used for traffic classification.
2099
</descrip>
2100

    
2101
<sect1>Example
2102

    
2103
<p>A simple configuration can look this way:
2104

    
2105
<p><code>
2106
protocol kernel {
2107
	export all;
2108
}
2109
</code>
2110

    
2111
<p>Or for a system with two routing tables:
2112

    
2113
<p><code>
2114
protocol kernel {		# Primary routing table
2115
	learn;			# Learn alien routes from the kernel
2116
	persist;		# Don't remove routes on bird shutdown
2117
	scan time 10;		# Scan kernel routing table every 10 seconds
2118
	import all;
2119
	export all;
2120
}
2121

    
2122
protocol kernel {		# Secondary routing table
2123
	table auxtable;
2124
	kernel table 100;
2125
	export all;
2126
}
2127
</code>
2128

    
2129
<sect>OSPF
2130

    
2131
<sect1>Introduction
2132

    
2133
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
2134
protocol. The current IPv4 version (OSPFv2) is defined in RFC
2135
2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> and
2136
the current IPv6 version (OSPFv3) is defined in RFC 5340<htmlurl
2137
url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt">  It's a link state
2138
(a.k.a. shortest path first) protocol -- each router maintains a
2139
database describing the autonomous system's topology. Each participating
2140
router has an identical copy of the database and all routers run the
2141
same algorithm calculating a shortest path tree with themselves as a
2142
root. OSPF chooses the least cost path as the best path.
2143

    
2144
<p>In OSPF, the autonomous system can be split to several areas in order
2145
to reduce the amount of resources consumed for exchanging the routing
2146
information and to protect the other areas from incorrect routing data.
2147
Topology of the area is hidden to the rest of the autonomous system.
2148

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

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

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

    
2166
<sect1>Configuration
2167

    
2168
<p>In the main part of configuration, there can be multiple definitions of
2169
OSPF areas, each with a different id. These definitions includes many other
2170
switches and multiple definitions of interfaces. Definition of interface
2171
may contain many switches and constant definitions and list of neighbors
2172
on nonbroadcast networks.
2173

    
2174
<code>
2175
protocol ospf &lt;name&gt; {
2176
	rfc1583compat &lt;switch&gt;;
2177
	stub router &lt;switch&gt;;
2178
	tick &lt;num&gt;;
2179
	ecmp &lt;switch&gt; [limit &lt;num&gt;];
2180
	area &lt;id&gt; {
2181
		stub;
2182
		nssa;
2183
		summary &lt;switch&gt;;
2184
		default nssa &lt;switch&gt;;
2185
		default cost &lt;num&gt;;
2186
		default cost2 &lt;num&gt;;
2187
		translator &lt;switch&gt;;
2188
		translator stability &lt;num&gt;;
2189

    
2190
                networks {
2191
			&lt;prefix&gt;;
2192
			&lt;prefix&gt; hidden;
2193
		}
2194
                external {
2195
			&lt;prefix&gt;;
2196
			&lt;prefix&gt; hidden;
2197
			&lt;prefix&gt; tag &lt;num&gt;;
2198
		}
2199
		stubnet &lt;prefix&gt;;
2200
		stubnet &lt;prefix&gt; {
2201
			hidden &lt;switch&gt;;
2202
			summary &lt;switch&gt;;
2203
			cost &lt;num&gt;;
2204
		}
2205
		interface &lt;interface pattern&gt; [instance &lt;num&gt;] {
2206
			cost &lt;num&gt;;
2207
			stub &lt;switch&gt;;
2208
			hello &lt;num&gt;;
2209
			poll &lt;num&gt;;
2210
			retransmit &lt;num&gt;;
2211
			priority &lt;num&gt;;
2212
			wait &lt;num&gt;;
2213
			dead count &lt;num&gt;;
2214
			dead &lt;num&gt;;
2215
			secondary &lt;switch&gt;;
2216
			rx buffer [normal|large|&lt;num&gt;];
2217
			tx length &lt;num&gt;;
2218
			type [broadcast|bcast|pointopoint|ptp|
2219
				nonbroadcast|nbma|pointomultipoint|ptmp];
2220
			strict nonbroadcast &lt;switch&gt;;
2221
			real broadcast &lt;switch&gt;;
2222
			ptp netmask &lt;switch&gt;;
2223
			check link &lt;switch&gt;;
2224
			bfd &lt;switch&gt;;
2225
			ecmp weight &lt;num&gt;;
2226
			ttl security [&lt;switch&gt;; | tx only]
2227
			tx class|dscp &lt;num&gt;;
2228
			tx priority &lt;num&gt;;
2229
			authentication [none|simple|cryptographic];
2230
			password "&lt;text&gt;";
2231
			password "&lt;text&gt;" {
2232
				id &lt;num&gt;;
2233
				generate from "&lt;date&gt;";
2234
				generate to "&lt;date&gt;";
2235
				accept from "&lt;date&gt;";
2236
				accept to "&lt;date&gt;";
2237
			};
2238
			neighbors {
2239
				&lt;ip&gt;;
2240
				&lt;ip&gt; eligible;
2241
			};
2242
		};
2243
		virtual link &lt;id&gt; [instance &lt;num&gt;] {
2244
			hello &lt;num&gt;;
2245
			retransmit &lt;num&gt;;
2246
			wait &lt;num&gt;;
2247
			dead count &lt;num&gt;;
2248
			dead &lt;num&gt;;
2249
			authentication [none|simple|cryptographic];
2250
			password "&lt;text&gt;";
2251
		};
2252
	};
2253
}
2254
</code>
2255

    
2256
<descrip>
2257
	<tag>rfc1583compat <M>switch</M></tag>
2258
	 This option controls compatibility of routing table
2259
	 calculation with RFC 1583<htmlurl
2260
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
2261
	 value is no.
2262

    
2263
	<tag>stub router <M>switch</M></tag>
2264
	 This option configures the router to be a stub router, i.e.,
2265
	 a router that participates in the OSPF topology but does not
2266
	 allow transit traffic. In OSPFv2, this is implemented by
2267
	 advertising maximum metric for outgoing links, as suggested
2268
	 by RFC 3137<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3137.txt">.
2269
	 In OSPFv3, the stub router behavior is announced by clearing
2270
	 the R-bit in the router LSA. Default value is no.
2271

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

    
2278
	<tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
2279
	 This option specifies whether OSPF is allowed to generate
2280
	 ECMP (equal-cost multipath) routes. Such routes are used when
2281
	 there are several directions to the destination, each with
2282
	 the same (computed) cost. This option also allows to specify
2283
	 a limit on maximal number of nexthops in one route. By
2284
	 default, ECMP is disabled.  If enabled, default value of the
2285
	 limit is 16.
2286

    
2287
	<tag>area <M>id</M></tag>
2288
	 This defines an OSPF area with given area ID (an integer or an IPv4
2289
	 address, similarly to a router ID). The most important area is
2290
	 the backbone (ID 0) to which every other area must be connected.
2291

    
2292
	<tag>stub</tag>
2293
	 This option configures the area to be a stub area. External
2294
	 routes are not flooded into stub areas. Also summary LSAs can be
2295
	 limited in stub areas (see option <cf/summary/).
2296
	 By default, the area is not a stub area.
2297

    
2298
	<tag>nssa</tag>
2299
	 This option configures the area to be a NSSA (Not-So-Stubby
2300
	 Area). NSSA is a variant of a stub area which allows a
2301
	 limited way of external route propagation. Global external
2302
	 routes are not propagated into a NSSA, but an external route
2303
	 can be imported into NSSA as a (area-wide) NSSA-LSA (and
2304
	 possibly translated and/or aggregated on area boundary).
2305
	 By default, the area is not NSSA.
2306

    
2307
	<tag>summary <M>switch</M></tag>
2308
	 This option controls propagation of summary LSAs into stub or
2309
	 NSSA areas. If enabled, summary LSAs are propagated as usual,
2310
	 otherwise just the default summary route (0.0.0.0/0) is
2311
	 propagated (this is sometimes called totally stubby area). If
2312
	 a stub area has more area boundary routers, propagating
2313
	 summary LSAs could lead to more efficient routing at the cost
2314
	 of larger link state database. Default value is no.
2315

    
2316
	<tag>default nssa <M>switch</M></tag>
2317
 	 When <cf/summary/ option is enabled, default summary route is
2318
	 no longer propagated to the NSSA. In that case, this option
2319
	 allows to originate default route as NSSA-LSA to the NSSA.
2320
	 Default value is no.
2321

    
2322
	<tag>default cost <M>num</M></tag>
2323
	 This option controls the cost of a default route propagated to
2324
	 stub and NSSA areas. Default value is 1000.
2325

    
2326
	<tag>default cost2 <M>num</M></tag>
2327
	 When a default route is originated as NSSA-LSA, its cost
2328
	 can use either type 1 or type 2 metric. This option allows
2329
	 to specify the cost of a default route in type 2 metric.
2330
	 By default, type 1 metric (option <cf/default cost/) is used.
2331

    
2332
	<tag>translator <M>switch</M></tag>
2333
	 This option controls translation of NSSA-LSAs into external
2334
	 LSAs. By default, one translator per NSSA is automatically
2335
	 elected from area boundary routers. If enabled, this area
2336
	 boundary router would unconditionally translate all NSSA-LSAs
2337
	 regardless of translator election. Default value is no.
2338

    
2339
	<tag>translator stability <M>num</M></tag>
2340
	 This option controls the translator stability interval (in
2341
	 seconds). When the new translator is elected, the old one
2342
	 keeps translating until the interval is over. Default value
2343
	 is 40.
2344

    
2345
	<tag>networks { <m/set/ }</tag>
2346
         Definition of area IP ranges. This is used in summary LSA origination.
2347
	 Hidden networks are not propagated into other areas.
2348

    
2349
	<tag>external { <m/set/ }</tag>
2350
         Definition of external area IP ranges for NSSAs. This is used
2351
	 for NSSA-LSA translation. Hidden networks are not translated
2352
	 into external LSAs. Networks can have configured route tag.
2353

    
2354
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
2355
	 Stub networks are networks that are not transit networks
2356
	 between OSPF routers. They are also propagated through an
2357
	 OSPF area as a part of a link state database. By default,
2358
	 BIRD generates a stub network record for each primary network
2359
	 address on each OSPF interface that does not have any OSPF
2360
	 neighbors, and also for each non-primary network address on
2361
	 each OSPF interface. This option allows to alter a set of
2362
	 stub networks propagated by this router. 
2363

    
2364
	 Each instance of this option adds a stub network with given
2365
	 network prefix to the set of propagated stub network, unless
2366
	 option <cf/hidden/ is used. It also suppresses default stub
2367
	 networks for given network prefix. When option
2368
	 <cf/summary/ is used, also default stub networks that are
2369
	 subnetworks of given stub network are suppressed. This might
2370
	 be used, for example, to aggregate generated stub networks.
2371
	 
2372
	<tag>interface <M>pattern</M> [instance <m/num/]</tag>
2373
	 Defines that the specified interfaces belong to the area being defined.
2374
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
2375
	 In OSPFv3, you can specify instance ID for that interface
2376
	 description, so it is possible to have several instances of
2377
	 that interface with different options or even in different areas.
2378

    
2379
	<tag>virtual link <M>id</M> [instance <m/num/]</tag>
2380
	 Virtual link to router with the router id. Virtual link acts
2381
         as a point-to-point interface belonging to backbone. The
2382
         actual area is used as transport area. This item cannot be in
2383
         the backbone. In OSPFv3, you could also use several virtual
2384
         links to one destination with different instance IDs.
2385

    
2386
	<tag>cost <M>num</M></tag>
2387
	 Specifies output cost (metric) of an interface. Default value is 10.
2388

    
2389
	<tag>stub <M>switch</M></tag>
2390
	 If set to interface it does not listen to any packet and does not send
2391
	 any hello. Default value is no.
2392

    
2393
	<tag>hello <M>num</M></tag>
2394
	 Specifies interval in seconds between sending of Hello messages. Beware, all
2395
	 routers on the same network need to have the same hello interval.
2396
	 Default value is 10.
2397

    
2398
	<tag>poll <M>num</M></tag>
2399
	 Specifies interval in seconds between sending of Hello messages for
2400
	 some neighbors on NBMA network. Default value is 20.
2401

    
2402
	<tag>retransmit <M>num</M></tag>
2403
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
2404
	 Default value is 5.
2405

    
2406
        <tag>priority <M>num</M></tag>
2407
	 On every multiple access network (e.g., the Ethernet) Designed Router
2408
	 and Backup Designed router are elected. These routers have some
2409
	 special functions in the flooding process. Higher priority increases
2410
	 preferences in this election. Routers with priority 0 are not
2411
	 eligible. Default value is 1.
2412

    
2413
	<tag>wait <M>num</M></tag>
2414
	 After start, router waits for the specified number of seconds between starting
2415
	 election and building adjacency. Default value is 40.
2416
	 
2417
	<tag>dead count <M>num</M></tag>
2418
	 When the router does not receive any messages from a neighbor in
2419
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
2420

    
2421
	<tag>dead <M>num</M></tag>
2422
	 When the router does not receive any messages from a neighbor in
2423
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
2424
	 <cf/dead count/ and <cf/dead/ are used, <cf/dead/ has precendence.
2425

    
2426
	<tag>secondary <M>switch</M></tag>
2427
	On BSD systems, older versions of BIRD supported OSPFv2 only for the
2428
	primary IP address of an interface, other IP ranges on the interface
2429
	were handled as stub networks. Since v1.4.1, regular operation on
2430
	secondary IP addresses is supported, but disabled by default for
2431
	compatibility. This option allows to enable it. The option is a
2432
	transitional measure, will be removed in the next major release as the
2433
	behavior will be changed. On Linux systems, the option is irrelevant, as
2434
	operation on non-primary addresses is already the regular behavior.
2435

    
2436
	<tag>rx buffer <M>num</M></tag>
2437
	This option allows to specify the size of buffers used for packet
2438
	processing. The buffer size should be bigger than maximal size of any
2439
	packets. By default, buffers are dynamically resized as needed, but a
2440
	fixed value could be specified. Value <cf/large/ means maximal allowed
2441
	packet size - 65535.
2442

    
2443
	<tag>tx length <M>num</M></tag>
2444
	Transmitted OSPF messages that contain large amount of information are
2445
	segmented to separate OSPF packets to avoid IP fragmentation. This
2446
	option specifies the soft ceiling for the length of generated OSPF
2447
	packets. Default value is the MTU of the network interface. Note that
2448
	larger OSPF packets may still be generated if underlying OSPF messages
2449
	cannot be splitted (e.g. when one large LSA is propagated).
2450

    
2451
	<tag>type broadcast|bcast</tag>
2452
	 BIRD detects a type of a connected network automatically, but
2453
	 sometimes it's convenient to force use of a different type
2454
	 manually. On broadcast networks (like ethernet), flooding
2455
	 and Hello messages are sent using multicasts (a single packet
2456
	 for all the neighbors). A designated router is elected and it
2457
	 is responsible for synchronizing the link-state databases and
2458
	 originating network LSAs. This network type cannot be used on
2459
	 physically NBMA networks and on unnumbered networks (networks
2460
	 without proper IP prefix).
2461

    
2462
	<tag>type pointopoint|ptp</tag>
2463
	 Point-to-point networks connect just 2 routers together. No
2464
	 election is performed and no network LSA is originated, which
2465
	 makes it simpler and faster to establish. This network type
2466
	 is useful not only for physically PtP ifaces (like PPP or
2467
	 tunnels), but also for broadcast networks used as PtP links.
2468
	 This network type cannot be used on physically NBMA networks.
2469

    
2470
	<tag>type nonbroadcast|nbma</tag>
2471
	 On NBMA networks, the packets are sent to each neighbor
2472
	 separately because of lack of multicast capabilities.
2473
	 Like on broadcast networks, a designated router is elected,
2474
	 which plays a central role in propagation of LSAs.
2475
	 This network type cannot be used on unnumbered networks.
2476

    
2477
	<tag>type pointomultipoint|ptmp</tag>
2478
	 This is another network type designed to handle NBMA
2479
	 networks. In this case the NBMA network is treated as a
2480
	 collection of PtP links. This is useful if not every pair of
2481
	 routers on the NBMA network has direct communication, or if
2482
	 the NBMA network is used as an (possibly unnumbered) PtP
2483
	 link.
2484

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

    
2489
	<tag>real broadcast <m/switch/</tag>
2490
	 In <cf/type broadcast/ or <cf/type ptp/ network
2491
	 configuration, OSPF packets are sent as IP multicast
2492
	 packets. This option changes the behavior to using
2493
	 old-fashioned IP broadcast packets. This may be useful as a
2494
	 workaround if IP multicast for some reason does not work or
2495
	 does not work reliably. This is a non-standard option and
2496
	 probably is not interoperable with other OSPF
2497
	 implementations. Default value is no.
2498

    
2499
	<tag>ptp netmask <m/switch/</tag>
2500
	 In <cf/type ptp/ network configurations, OSPFv2
2501
	 implementations should ignore received netmask field in hello
2502
	 packets and should send hello packets with zero netmask field
2503
	 on unnumbered PtP links. But some OSPFv2 implementations
2504
	 perform netmask checking even for PtP links. This option
2505
	 specifies whether real netmask will be used in hello packets
2506
	 on <cf/type ptp/ interfaces. You should ignore this option
2507
	 unless you meet some compatibility problems related to this
2508
	 issue. Default value is no for unnumbered PtP links, yes
2509
	 otherwise.
2510

    
2511
	<tag>check link <M>switch</M></tag>
2512
	 If set, a hardware link state (reported by OS) is taken into
2513
	 consideration. When a link disappears (e.g. an ethernet cable is
2514
	 unplugged), neighbors are immediately considered unreachable
2515
	 and only the address of the iface (instead of whole network
2516
	 prefix) is propagated. It is possible that some hardware
2517
	 drivers or platforms do not implement this feature. Default value is no.
2518

    
2519
	<tag>bfd <M>switch</M></tag>
2520
	OSPF could use BFD protocol as an advisory mechanism for neighbor
2521
	liveness and failure detection. If enabled, BIRD setups a BFD session
2522
	for each OSPF neighbor and tracks its liveness by it. This has an
2523
	advantage of an order of magnitude lower detection times in case of
2524
	failure. Note that BFD protocol also has to be configured, see
2525
	<ref id="sect-bfd" name="BFD"> section for details. Default value is no.
2526

    
2527
	<tag>ttl security [<m/switch/ | tx only]</tag>
2528
	 TTL security is a feature that protects routing protocols
2529
	 from remote spoofed packets by using TTL 255 instead of TTL 1
2530
	 for protocol packets destined to neighbors. Because TTL is
2531
	 decremented when packets are forwarded, it is non-trivial to
2532
	 spoof packets with TTL 255 from remote locations. Note that
2533
	 this option would interfere with OSPF virtual links.
2534

    
2535
	 If this option is enabled, the router will send OSPF packets
2536
	 with TTL 255 and drop received packets with TTL less than
2537
	 255. If this option si set to <cf/tx only/, TTL 255 is used
2538
	 for sent packets, but is not checked for received
2539
	 packets. Default value is no.
2540

    
2541
	<tag>tx class|dscp|priority <m/num/</tag>
2542
         These options specify the ToS/DiffServ/Traffic class/Priority
2543
         of the outgoing OSPF packets. See <ref id="dsc-prio" name="tx
2544
         class"> common option for detailed description.
2545

    
2546
	<tag>ecmp weight <M>num</M></tag>
2547
	 When ECMP (multipath) routes are allowed, this value specifies
2548
	 a relative weight used for nexthops going through the iface.
2549
	 Allowed values are 1-256. Default value is 1.
2550

    
2551
	<tag>authentication none</tag>
2552
	 No passwords are sent in OSPF packets. This is the default value.
2553

    
2554
	<tag>authentication simple</tag>
2555
	 Every packet carries 8 bytes of password. Received packets
2556
	 lacking this password are ignored. This authentication mechanism is
2557
	 very weak.
2558

    
2559
	<tag>authentication cryptographic</tag>
2560
	 16-byte long MD5 digest is appended to every packet. For the digest
2561
         generation 16-byte long passwords are used. Those passwords are 
2562
         not sent via network, so this mechanism is quite secure.
2563
         Packets can still be read by an attacker.
2564

    
2565
	<tag>password "<M>text</M>"</tag>
2566
	 An 8-byte or 16-byte password used for authentication.
2567
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
2568

    
2569
	<tag>neighbors { <m/set/ } </tag>
2570
	 A set of neighbors to which Hello messages on NBMA or PtMP
2571
	 networks are to be sent. For NBMA networks, some of them
2572
	 could be marked as eligible. In OSPFv3, link-local addresses
2573
	 should be used, using global ones is possible, but it is
2574
	 nonstandard and might be problematic. And definitely,
2575
	 link-local and global addresses should not be mixed.
2576

    
2577
</descrip>
2578

    
2579
<sect1>Attributes
2580

    
2581
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
2582
Metric is ranging from 1 to infinity (65535).
2583
External routes use <cf/metric type 1/ or <cf/metric type 2/.
2584
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
2585
<cf/metric of type 2/ is always longer
2586
than any <cf/metric of type 1/ or any <cf/internal metric/.
2587
<cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute
2588
<cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/.
2589
If you specify both metrics only metric1 is used.
2590

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

    
2598
<sect1>Example
2599

    
2600
<p>
2601

    
2602
<code>
2603
protocol ospf MyOSPF {
2604
        rfc1583compat yes;
2605
        tick 2;
2606
	export filter {
2607
		if source = RTS_BGP then {
2608
			ospf_metric1 = 100;
2609
			accept;
2610
		}
2611
		reject;
2612
	};
2613
	area 0.0.0.0 {
2614
		interface "eth*" {
2615
			cost 11;
2616
			hello 15;
2617
			priority 100;
2618
			retransmit 7;
2619
			authentication simple;
2620
			password "aaa";
2621
		};
2622
		interface "ppp*" {
2623
			cost 100;
2624
			authentication cryptographic;
2625
			password "abc" {
2626
				id 1;
2627
				generate to "22-04-2003 11:00:06";
2628
				accept from "17-01-2001 12:01:05";
2629
			};
2630
			password "def" {
2631
				id 2;
2632
				generate to "22-07-2005 17:03:21";
2633
				accept from "22-02-2001 11:34:06";
2634
			};
2635
		};
2636
		interface "arc0" {
2637
			cost 10;
2638
			stub yes;
2639
		};
2640
		interface "arc1";
2641
	};
2642
	area 120 {
2643
		stub yes;
2644
		networks {
2645
			172.16.1.0/24;
2646
			172.16.2.0/24 hidden;
2647
		}
2648
		interface "-arc0" , "arc*" {
2649
			type nonbroadcast;
2650
			authentication none;
2651
			strict nonbroadcast yes;
2652
			wait 120;
2653
			poll 40;
2654
			dead count 8;
2655
			neighbors {
2656
				192.168.120.1 eligible;
2657
				192.168.120.2;
2658
				192.168.120.10;
2659
			};
2660
		};
2661
	};
2662
}
2663
</code>
2664

    
2665
<sect>Pipe
2666

    
2667
<sect1>Introduction
2668

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

    
2676
<p>The Pipe protocol may work in the transparent mode mode or in the opaque mode.
2677
In the transparent mode, the Pipe protocol retransmits all routes from
2678
one table to the other table, retaining their original source and
2679
attributes.  If import and export filters are set to accept, then both
2680
tables would have the same content. The transparent mode is the default mode.
2681

    
2682
<p>In the opaque mode, the Pipe protocol retransmits optimal route
2683
from one table to the other table in a similar way like other
2684
protocols send and receive routes. Retransmitted route will have the
2685
source set to the Pipe protocol, which may limit access to protocol
2686
specific route attributes. This mode is mainly for compatibility, it
2687
is not suggested for new configs. The mode can be changed by
2688
<tt/mode/ option.
2689

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

    
2701
<sect1>Configuration
2702

    
2703
<p><descrip>
2704
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
2705
	primary one is selected by the <cf/table/ keyword.
2706

    
2707
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is transparent.
2708
</descrip>
2709

    
2710
<sect1>Attributes
2711

    
2712
<p>The Pipe protocol doesn't define any route attributes.
2713

    
2714
<sect1>Example
2715

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

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

    
2730
<code>
2731
table as1;				# Define the tables
2732
table as2;
2733

    
2734
protocol kernel kern1 {			# Synchronize them with the kernel
2735
	table as1;
2736
	kernel table 1;
2737
}
2738

    
2739
protocol kernel kern2 {
2740
	table as2;
2741
	kernel table 2;
2742
}
2743

    
2744
protocol bgp bgp1 {			# The outside connections
2745
	table as1;
2746
	local as 1;
2747
	neighbor 192.168.0.1 as 1001;
2748
	export all;
2749
	import all;
2750
}
2751

    
2752
protocol bgp bgp2 {
2753
	table as2;
2754
	local as 2;
2755
	neighbor 10.0.0.1 as 1002;
2756
	export all;
2757
	import all;
2758
}
2759

    
2760
protocol pipe {				# The Pipe
2761
	table as1;
2762
	peer table as2;
2763
	export filter {
2764
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
2765
			if preference>10 then preference = preference-10;
2766
			if source=RTS_BGP then bgp_path.prepend(1);
2767
			accept;
2768
		}
2769
		reject;
2770
	};
2771
	import filter {
2772
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
2773
			if preference>10 then preference = preference-10;
2774
			if source=RTS_BGP then bgp_path.prepend(2);
2775
			accept;
2776
		}
2777
		reject;
2778
	};
2779
}
2780
</code>
2781

    
2782
<sect>RAdv
2783

    
2784
<sect1>Introduction
2785

    
2786
<p>The RAdv protocol is an implementation of Router Advertisements,
2787
which are used in the IPv6 stateless autoconfiguration. IPv6 routers
2788
send (in irregular time intervals or as an answer to a request)
2789
advertisement packets to connected networks. These packets contain
2790
basic information about a local network (e.g. a list of network
2791
prefixes), which allows network hosts to autoconfigure network
2792
addresses and choose a default route. BIRD implements router behavior
2793
as defined in
2794
RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">
2795
and also the DNS extensions from
2796
RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">.
2797

    
2798
<sect1>Configuration
2799

    
2800
<p>There are several classes of definitions in RAdv configuration --
2801
interface definitions, prefix definitions and DNS definitions:
2802

    
2803
<descrip>
2804
	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag>
2805
	Interface definitions specify a set of interfaces on which the
2806
	protocol is activated and contain interface specific options.
2807
	See <ref id="dsc-iface" name="interface"> common options for
2808
	detailed description.
2809

    
2810
	<tag>prefix <m/prefix/ { <m/options/ }</tag>
2811
	Prefix definitions allow to modify a list of advertised
2812
	prefixes. By default, the advertised prefixes are the same as
2813
	the network prefixes assigned to the interface. For each
2814
	network prefix, the matching prefix definition is found and
2815
	its options are used. If no matching prefix definition is
2816
	found, the prefix is used with default options.
2817

    
2818
	Prefix definitions can be either global or interface-specific.
2819
	The second ones are part of interface options. The prefix
2820
	definition matching is done in the first-match style, when
2821
	interface-specific definitions are processed before global
2822
	definitions. As expected, the prefix definition is matching if
2823
	the network prefix is a subnet of the prefix in prefix
2824
	definition.
2825

    
2826
	<tag>rdnss { <m/options/ }</tag>
2827
	RDNSS definitions allow to specify a list of advertised
2828
	recursive DNS servers together with their options. As options
2829
	are seldom necessary, there is also a short variant <cf>rdnss
2830
	<m/address/</cf> that just specifies one DNS server. Multiple
2831
	definitions are cumulative. RDNSS definitions may also be
2832
	interface-specific when used inside interface options. By
2833
	default, interface uses both global and interface-specific
2834
	options, but that can be changed by <cf/rdnss local/ option.
2835

    
2836
	<tag>dnssl { <m/options/ }</tag>
2837
	DNSSL definitions allow to specify a list of advertised DNS
2838
	search domains together with their options. Like <cf/rdnss/
2839
	above, multiple definitions are cumulative, they can be used
2840
	also as interface-specific options and there is a short
2841
	variant <cf>dnssl <m/domain/</cf> that just specifies one DNS
2842
        search domain.
2843

    
2844
	<label id="dsc-trigger"> <tag>trigger <m/prefix/</tag>
2845
	RAdv protocol could be configured to change its behavior based
2846
	on availability of routes. When this option is used, the
2847
	protocol waits in suppressed state until a <it/trigger route/
2848
	(for the specified network) is exported to the protocol, the
2849
	protocol also returnsd to suppressed state if the
2850
	<it/trigger route/ disappears. Note that route export depends
2851
	on specified export filter, as usual. This option could be
2852
	used, e.g., for handling failover in multihoming scenarios.
2853

    
2854
	During suppressed state, router advertisements are generated,
2855
	but with some fields zeroed. Exact behavior depends on which
2856
	fields are zeroed, this can be configured by
2857
	<cf/sensitive/ option for appropriate fields. By default, just
2858
	<cf/default lifetime/ (also called <cf/router lifetime/) is
2859
	zeroed, which means hosts cannot use the router as a default
2860
	router. <cf/preferred lifetime/ and <cf/valid lifetime/ could
2861
	also be configured as <cf/sensitive/ for a prefix, which would
2862
	cause autoconfigured IPs to be deprecated or even removed.
2863
</descrip>
2864

    
2865
<p>Interface specific options:
2866

    
2867
<descrip>
2868
	<tag>max ra interval <m/expr/</tag>
2869
	Unsolicited router advertisements are sent in irregular time
2870
	intervals. This option specifies the maximum length of these
2871
	intervals, in seconds. Valid values are 4-1800. Default: 600
2872

    
2873
	<tag>min ra interval <m/expr/</tag>
2874
	This option specifies the minimum length of that intervals, in
2875
	seconds. Must be at least 3 and at most 3/4 * <cf/max ra interval/.
2876
	Default: about 1/3 * <cf/max ra interval/.
2877

    
2878
	<tag>min delay <m/expr/</tag>
2879
	The minimum delay between two consecutive router advertisements,
2880
	in seconds. Default: 3
2881

    
2882
	<tag>managed <m/switch/</tag>
2883
	This option specifies whether hosts should use DHCPv6 for
2884
	IP address configuration. Default: no
2885

    
2886
	<tag>other config <m/switch/</tag>
2887
	This option specifies whether hosts should use DHCPv6 to
2888
	receive other configuration information. Default: no
2889

    
2890
	<tag>link mtu <m/expr/</tag>
2891
	This option specifies which value of MTU should be used by
2892
	hosts. 0 means unspecified. Default: 0
2893

    
2894
	<tag>reachable time <m/expr/</tag>
2895
	This option specifies the time (in milliseconds) how long
2896
	hosts should assume a neighbor is reachable (from the last
2897
	confirmation). Maximum is 3600000, 0 means unspecified.
2898
	Default 0.
2899

    
2900
	<tag>retrans timer <m/expr/</tag>
2901
	This option specifies the time (in milliseconds) how long
2902
	hosts should wait before retransmitting Neighbor Solicitation
2903
	messages. 0 means unspecified. Default 0.
2904

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

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

    
2916
	<tag>rdnss local <m/switch/</tag>
2917
	Use only local (interface-specific) RDNSS definitions for this
2918
	interface. Otherwise, both global and local definitions are
2919
	used. Could also be used to disable RDNSS for given interface
2920
	if no local definitons are specified. Default: no.
2921

    
2922
	<tag>dnssl local <m/switch/</tag>
2923
	Use only local DNSSL definitions for this interface. See
2924
	<cf/rdnss local/ option above. Default: no.
2925
</descrip>
2926

    
2927

    
2928
<p>Prefix specific options:
2929

    
2930
<descrip>
2931
	<tag>skip <m/switch/</tag>
2932
	This option allows to specify that given prefix should not be
2933
	advertised. This is useful for making exceptions from a
2934
	default policy of advertising all prefixes. Note that for
2935
	withdrawing an already advertised prefix it is more useful to
2936
	advertise it with zero valid lifetime. Default: no
2937

    
2938
	<tag>onlink <m/switch/</tag>
2939
	This option specifies whether hosts may use the advertised
2940
	prefix for onlink determination. Default: yes
2941

    
2942
	<tag>autonomous <m/switch/</tag>
2943
	This option specifies whether hosts may use the advertised
2944
	prefix for stateless autoconfiguration. Default: yes
2945

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

    
2954
	<tag>preferred lifetime <m/expr/ [sensitive <m/switch/]</tag>
2955
	This option specifies the time (in seconds) how long (after
2956
	the receipt of RA) IP addresses generated from the prefix
2957
	using stateless autoconfiguration remain preferred. For
2958
	<cf/sensitive/ option, see <ref id="dsc-trigger" name="trigger">.
2959
	Default: 14400 (4 hours), <cf/sensitive/ no.
2960
</descrip>
2961

    
2962

    
2963
<p>RDNSS specific options:
2964

    
2965
<descrip>
2966
	<tag>ns <m/address/</tag>
2967
	This option specifies one recursive DNS server. Can be used
2968
	multiple times for multiple servers. It is mandatory to have
2969
	at least one <cf/ns/ option in <cf/rdnss/ definition.
2970

    
2971
	<tag>lifetime [mult] <m/expr/</tag>
2972
	This option specifies the time how long the RDNSS information
2973
        may be used by clients after the receipt of RA. It is
2974
        expressed either in seconds or (when <cf/mult/ is used) in
2975
        multiples of <cf/max ra interval/. Note that RDNSS information
2976
        is also invalidated when <cf/default lifetime/ expires. 0
2977
        means these addresses are no longer valid DNS servers.
2978
	Default: 3 * <cf/max ra interval/.
2979
</descrip>
2980

    
2981

    
2982
<p>DNSSL specific options:
2983

    
2984
<descrip>
2985
	<tag>domain <m/address/</tag>
2986
	This option specifies one DNS search domain. Can be used
2987
	multiple times for multiple domains. It is mandatory to have
2988
	at least one <cf/domain/ option in <cf/dnssl/ definition.
2989

    
2990
	<tag>lifetime [mult] <m/expr/</tag>
2991
	This option specifies the time how long the DNSSL information
2992
        may be used by clients after the receipt of RA. Details are
2993
	the same as for RDNSS <cf/lifetime/ option above.
2994
	Default: 3 * <cf/max ra interval/.
2995
</descrip>
2996

    
2997

    
2998
<sect1>Example
2999

    
3000
<p><code>
3001
protocol radv {
3002
	interface "eth2" {
3003
		max ra interval 5;	# Fast failover with more routers
3004
		managed yes;		# Using DHCPv6 on eth2
3005
		prefix ::/0 {
3006
			autonomous off;	# So do not autoconfigure any IP
3007
		};
3008
	};
3009

    
3010
	interface "eth*";		# No need for any other options
3011

    
3012
	prefix 2001:0DB8:1234::/48 {
3013
		preferred lifetime 0;	# Deprecated address range
3014
	};
3015

    
3016
	prefix 2001:0DB8:2000::/48 {
3017
		autonomous off;		# Do not autoconfigure
3018
	};
3019

    
3020
	rdnss 2001:0DB8:1234::10;	# Short form of RDNSS
3021

    
3022
	rdnss {
3023
		lifetime mult 10;
3024
		ns 2001:0DB8:1234::11;
3025
		ns 2001:0DB8:1234::12;
3026
	};
3027

    
3028
	dnssl {
3029
		lifetime 3600;
3030
		domain "abc.com";
3031
		domain "xyz.com";
3032
	};
3033
}
3034
</code>
3035

    
3036
<sect>RIP
3037

    
3038
<sect1>Introduction
3039

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

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

    
3057
<sect1>Configuration
3058

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

    
3061
<descrip>
3062
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
3063
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
3064
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
3065
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
3066
	  section. Default: none.
3067

    
3068
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
3069
	  be honored. (Always, when sent from a  host on a directly connected
3070
	  network or never.) Routing table updates are honored only from
3071
	  neighbors, that is not configurable. Default: never.
3072
</descrip>
3073

    
3074
<p>There are some options that can be specified per-interface:
3075

    
3076
<descrip>
3077
	<tag>metric <m/num/</tag>
3078
	  This option specifies the metric of the interface. Valid
3079

    
3080
	<tag>mode multicast|broadcast|quiet|nolisten|version1</tag>
3081
	  This option selects the mode for RIP to work in. If nothing is
3082
	  specified, RIP runs in multicast mode. <cf/version1/ is
3083
	  currently equivalent to <cf/broadcast/, and it makes RIP talk
3084
	  to a broadcast address even through multicast mode is
3085
	  possible. <cf/quiet/ option means that RIP will not transmit
3086
	  any periodic messages to this interface and <cf/nolisten/
3087
	  means that RIP will send to this interface butnot listen to it.
3088

    
3089
	<tag>ttl security [<m/switch/ | tx only]</tag>
3090
	 TTL security is a feature that protects routing protocols
3091
	 from remote spoofed packets by using TTL 255 instead of TTL 1
3092
	 for protocol packets destined to neighbors. Because TTL is
3093
	 decremented when packets are forwarded, it is non-trivial to
3094
	 spoof packets with TTL 255 from remote locations.
3095

    
3096
	 If this option is enabled, the router will send RIP packets
3097
	 with TTL 255 and drop received packets with TTL less than
3098
	 255. If this option si set to <cf/tx only/, TTL 255 is used
3099
	 for sent packets, but is not checked for received
3100
	 packets. Such setting does not offer protection, but offers
3101
	 compatibility with neighbors regardless of whether they use
3102
	 ttl security.
3103

    
3104
	 Note that for RIPng, TTL security is a standard behavior
3105
	 (required by RFC 2080), but BIRD uses <cf/tx only/ by
3106
	 default, for compatibility with older versions. For IPv4 RIP,
3107
	 default value is no.
3108

    
3109
	<tag>tx class|dscp|priority <m/num/</tag>
3110
          These options specify the ToS/DiffServ/Traffic class/Priority
3111
          of the outgoing RIP packets. See <ref id="dsc-prio" name="tx
3112
          class"> common option for detailed description.
3113
</descrip>
3114

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

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

    
3124
	<tag>infinity <M>number</M></tag>
3125
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
3126
	  even slower.
3127

    
3128
	<tag>period <M>number</M>
3129
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
3130
	  number will mean faster convergence but bigger network
3131
	  load. Do not use values lower than 12.
3132

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

    
3136
	<tag>garbage time <M>number</M>
3137
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
3138
</descrip>
3139

    
3140
<sect1>Attributes
3141

    
3142
<p>RIP defines two route attributes:
3143

    
3144
<descrip>
3145
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
3146
	When routes from different RIP instances are available and all of them have the same
3147
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
3148
	When importing a non-RIP route, the metric defaults to 5.
3149

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

    
3155
<sect1>Example
3156

    
3157
<p><code>
3158
protocol rip MyRIP_test {
3159
        debug all;
3160
        port 1520;
3161
        period 12;
3162
        garbage time 60;
3163
        interface "eth0" { metric 3; mode multicast; };
3164
	interface "eth*" { metric 2; mode broadcast; };
3165
        honor neighbor;
3166
        authentication none;
3167
        import filter { print "importing"; accept; };
3168
        export filter { print "exporting"; accept; };
3169
}
3170
</code>
3171

    
3172
<sect>Static
3173

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

    
3182
<p>There are five types of static routes: `classical' routes telling
3183
to forward packets to a neighboring router, multipath routes
3184
specifying several (possibly weighted) neighboring routers, device
3185
routes specifying forwarding to hosts on a directly connected network,
3186
recursive routes computing their nexthops by doing route table lookups
3187
for a given IP and special routes (sink, blackhole etc.) which specify
3188
a special action to be done instead of forwarding the packet.
3189

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

    
3195
<p>The Static protocol does not have many configuration options. The
3196
definition of the protocol contains mainly a list of static routes:
3197

    
3198
<descrip>
3199
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
3200
	a neighboring router.
3201
	<tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
3202
	Static multipath route. Contains several nexthops (gateways), possibly
3203
 	with their weights.
3204
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
3205
	route through an interface to hosts on a directly connected network.
3206
	<tag>route <m/prefix/ recursive <m/ip/</tag> Static recursive route,
3207
	its nexthop depends on a route table lookup for given IP address.
3208
	<tag>route <m/prefix/ blackhole|unreachable|prohibit</tag> Special routes
3209
	specifying to silently drop the packet, return it as unreachable or return
3210
	it as administratively prohibited. First two targets are also known
3211
	as <cf/drop/ and <cf/reject/.
3212

    
3213
	<tag>check link <m/switch/</tag>
3214
	If set, hardware link states of network interfaces are taken
3215
	into consideration.  When link disappears (e.g. ethernet cable
3216
	is unplugged), static routes directing to that interface are
3217
	removed. It is possible that some hardware drivers or
3218
	platforms do not implement this feature. Default: off.
3219

    
3220
	<tag>igp table <m/name/</tag> Specifies a table that is used
3221
	for route table lookups of recursive routes. Default: the
3222
	same table as the protocol is connected to.
3223
</descrip>
3224

    
3225
<p>Static routes have no specific attributes.
3226

    
3227
<p>Example static config might look like this:
3228

    
3229
<p><code>
3230
protocol static {
3231
	table testable;			 # Connect to a non-default routing table
3232
	route 0.0.0.0/0 via 198.51.100.130; # Default route
3233
	route 10.0.0.0/8 multipath	 # Multipath route
3234
		via 198.51.100.10 weight 2
3235
		via 198.51.100.20
3236
		via 192.0.2.1;
3237
	route 203.0.113.0/24 unreachable; # Sink route
3238
	route 10.2.0.0/24 via "arc0";	 # Secondary network
3239
}
3240
</code>
3241

    
3242
<chapt>Conclusions
3243

    
3244
<sect>Future work
3245

    
3246
<p>Although BIRD supports all the commonly used routing protocols,
3247
there are still some features which would surely deserve to be
3248
implemented in future versions of BIRD:
3249

    
3250
<itemize>
3251
<item>Opaque LSA's
3252
<item>Route aggregation and flap dampening
3253
<item>Multipath routes
3254
<item>Multicast routing protocols
3255
<item>Ports to other systems
3256
</itemize>
3257

    
3258
<sect>Getting more help
3259

    
3260
<p>If you use BIRD, you're welcome to join the bird-users mailing list
3261
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
3262
where you can share your experiences with the other users and consult
3263
your problems with the authors. To subscribe to the list, just send a
3264
<tt/subscribe bird-users/ command in a body of a mail to
3265
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
3266
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
3267

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

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

    
3278
<p><it/Good luck!/
3279

    
3280
</book>
3281

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