Statistics
| Branch: | Revision:

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

History | View | Annotate | Download (123 KB)

1
<!doctype birddoc system>
2

    
3
<!--
4
	BIRD documentation
5

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

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

    
14
    (set-fill-column 100)
15

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

    
18
 -->
19

    
20
<book>
21

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

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

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

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

    
39
<chapt>Introduction
40

    
41
<sect>What is BIRD
42

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

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

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

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

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

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

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

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

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

    
109
<sect>Installing BIRD
110

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

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

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

    
128
<sect>Running BIRD
129

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

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

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

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

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

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

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

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

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

    
158
<sect>Privileges
159

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

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

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

    
184
<chapt>About routing tables
185

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

    
191
<itemize>
192
	<item>network prefix this route is for (network address and prefix length -- the number of bits forming the network part of the address; also known as a netmask)
193
	<item>preference of this route
194
	<item>IP address of router which told us about this route
195
	<item>IP address of router we should forward the packets to
196
	using this route
197
	<item>other attributes common to all routes
198
	<item>dynamic attributes defined by protocols which may or
199
	may not be present (typically protocol metrics)
200
</itemize>
201

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

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

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

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

    
239

    
240
<chapt>Configuration
241

    
242
<sect>Introduction
243

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

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

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

    
259

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

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

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

    
278

    
279
<sect>Global options
280

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

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

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

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

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

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

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

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

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

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

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

    
342
	<tag>listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
343
	This option allows to specify address and port where BGP
344
	protocol should listen. It is global option as listening
345
	socket is common to all BGP instances. Default is to listen on
346
	all addresses (0.0.0.0) and port 179. In IPv6 mode, option
347
	<cf/dual/ can be used to specify that BGP socket should accept
348
	both IPv4 and IPv6 connections (but even in that case, BIRD
349
	would accept IPv6 routes only). Such behavior was default in
350
	older versions of BIRD.
351

    
352
	<tag>timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
353
	This option allows to specify a format of date/time used by
354
	BIRD.  The first argument specifies for which purpose such
355
	format is used. <cf/route/ is a format used in 'show route'
356
	command output, <cf/protocol/ is used in 'show protocols'
357
	command output, <cf/base/ is used for other commands and
358
	<cf/log/ is used in a log file.
359

    
360
	"<m/format1/" is a format string using <it/strftime(3)/
361
	notation (see <it/man strftime/ for details). <m/limit> and
362
	"<m/format2/" allow to specify the second format string for
363
	times in past deeper than <m/limit/ seconds. There are two
364
	shorthands: <cf/iso long/ is a ISO 8601 date/time format
365
	(YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
366
	%T"/. <cf/iso short/ is a variant of ISO 8601 that uses just
367
	the time format (hh:mm:ss) for near times (up to 20 hours in
368
	the past) and the date format (YYYY-MM-DD) for far times. This
369
	is a shorthand for <cf/"%T" 72000 "%F"/.
370

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

    
377
	<tag>table <m/name/ [sorted]</tag>
378
	Create a new routing table. The default routing table is
379
	created implicitly, other routing tables have to be added by
380
	this command. Option <cf/sorted/ can be used to enable
381
	sorting of routes, see <ref id="dsc-sorted" name="sorted table">
382
	description for details.
383

    
384
	<tag>roa table <m/name/ [ { roa table options ... } ]</tag>
385
	Create a new ROA (Route Origin Authorization) table. ROA
386
	tables can be used to validate route origination of BGP
387
	routes. A ROA table contains ROA entries, each consist of a
388
	network prefix, a max prefix length and an AS number. A ROA
389
	entry specifies prefixes which could be originated by that AS
390
	number. ROA tables could be filled with data from RPKI (RFC
391
	6480) or from public databases like Whois. ROA tables are 
392
	examined by <cf/roa_check()/ operator in filters.
393

    
394
	Currently, there is just one option,
395
	<cf>roa <m/prefix/ max <m/num/ as <m/num/</cf>, which
396
	can be used to populate the ROA table with static ROA
397
	entries. The option may be used multiple times. Other entries
398
	can be added dynamically by <cf/add roa/ command.
399

    
400
	<tag>eval <m/expr/</tag> Evaluates given filter expression. It
401
	is used by us for testing of filters.
402
</descrip>
403

    
404
<sect>Protocol options
405

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

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

    
416
<descrip>
417
	<tag>preference <m/expr/</tag> Sets the preference of routes generated by this protocol. Default: protocol dependent.
418

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

    
422
	<tag>debug all|off|{ states, routes, filters, interfaces, events, packets }</tag>
423
	Set protocol debugging options. If asked, each protocol is capable of
424
	writing trace messages about its work to the log (with category
425
	<cf/trace/). You can either request printing of <cf/all/ trace messages
426
	or only of the types selected: <cf/states/ for protocol state changes
427
	(protocol going up, down, starting, stopping etc.),
428
	<cf/routes/ for routes exchanged with the routing table,
429
	<cf/filters/ for details on route filtering,
430
	<cf/interfaces/ for interface change events sent to the protocol,
431
	<cf/events/ for events internal to the protocol and
432
	<cf/packets/ for packets sent and received by the protocol. Default: off.
433

    
434
	<tag>mrtdump all|off|{ states, messages }</tag>
435

    
436
	Set protocol MRTdump flags. MRTdump is a standard binary
437
	format for logging information from routing protocols and
438
	daemons.  These flags control what kind of information is
439
	logged from the protocol to the MRTdump file (which must be
440
	specified by global <cf/mrtdump/ option, see the previous
441
	section). Although these flags are similar to flags of
442
	<cf/debug/ option, their meaning is different and
443
	protocol-specific. For BGP protocol, <cf/states/ logs BGP
444
	state changes and <cf/messages/ logs received BGP messages.
445
	Other protocols does not support MRTdump yet.
446

    
447
	<tag>router id <m/IPv4 address/</tag> This option can be used
448
	to override global router id for a given protocol. Default:
449
	uses global router id.
450

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

    
457
	<tag>export <m/filter/</tag>
458
	This is similar to the <cf>import</cf> keyword, except that it
459
	works in the direction from the routing table to the protocol.
460
	Default: <cf/none/.
461

    
462
	<tag>import keep rejected <m/bool/</tag>
463
	Usually, if an import filter rejects a route, the route is
464
	forgotten. When this option is active, rejected routes are
465
	kept in the routing table, but they are hidden and not
466
	propagated to other protocols. But it is possible to show them
467
	using <cf/show route rejected/. Note that this option does not
468
	work for the pipe protocol. Default: off.
469

    
470
	<tag>import limit <m/number/ [action warn | block | restart | disable]</tag>
471
	Specify an import route limit (a maximum number of routes
472
	imported from the protocol) and optionally the action to be
473
	taken when the limit is hit. Warn action just prints warning
474
	log message. Block action ignores new routes coming from the
475
	protocol. Restart and disable actions shut the protocol down
476
	like appropriate commands. Disable is the default action if an
477
	action is not explicitly specified. Note that limits are reset
478
	during protocol reconfigure, reload or restart. Also note that
479
	if <cf/import keep rejected/ is active, rejected routes are
480
	counted towards the limit and blocked routes are forgotten, as
481
	the main purpose of the import limit is to protect routing
482
	tables from overflow. Default: <cf/none/.
483

    
484
	<tag>export limit <m/number/ [action warn | block | restart | disable]</tag>
485
	Specify an export route limit, works similarly to
486
	the <cf>import limit</cf> option, but for the routes exported
487
	to the protocol. This option is experimental, there are some
488
	problems in details of its behavior -- the number of exported
489
	routes can temporarily exceed the limit without triggering it
490
	during protocol reload, exported routes counter ignores route
491
	blocking and block action also blocks route updates of already
492
	accepted routes -- and these details will probably change in
493
	the future. Default: <cf/none/.
494

    
495
	<tag>description "<m/text/"</tag> This is an optional
496
	description of the protocol. It is displayed as a part of the
497
	output of 'show route all' command.
498

    
499
	<tag>table <m/name/</tag> Connect this protocol to a non-default routing table.
500
</descrip>
501

    
502
<p>There are several options that give sense only with certain protocols:
503

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

    
507
	Specifies a set of interfaces on which the protocol is activated with
508
	given interface-specific options. A set of interfaces specified by one
509
	interface option is described using an interface pattern. The
510
	interface pattern consists of a sequence of clauses (separated by
511
	commas), each clause may contain a mask, a prefix, or both of them. An
512
	interface matches the clause if its name matches the mask (if
513
	specified) and its address matches the prefix (if specified). Mask is
514
	specified as shell-like pattern. For IPv6, the prefix part of a clause
515
	is generally ignored and interfaces are matched just by their name.
516

    
517
	An interface matches the pattern if it matches any of its
518
	clauses. If the clause begins with <cf/-/, matching interfaces are
519
	excluded. Patterns are parsed left-to-right, thus
520
	<cf/interface "eth0", -"eth*", "*";/ means eth0 and all
521
	non-ethernets.
522

    
523
	An interface option can be used more times with different
524
	interfaces-specific options, in that case for given interface
525
	the first matching interface option is used.
526
	
527
	This option is allowed in Direct, OSPF, RIP and RAdv protocols,
528
	but in OSPF protocol it is used in <cf/area/ subsection.
529

    
530
	Default: none.
531

    
532
	Examples:
533

    
534
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all interfaces with
535
	<cf>type broadcast</cf> option.
536

    
537
	<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the protocol
538
	on enumerated interfaces with <cf>type ptp</cf> option.
539
	
540
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
541
	interfaces that have address from 192.168.0.0/16, but not
542
	from 192.168.1.0/24.
543

    
544
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol on all
545
	interfaces that have address from 192.168.0.0/16, but not
546
	from 192.168.1.0/24.
547

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

    
551
	<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>
552
	Specifies a password that can be used by the protocol. Password option can
553
	be used more times to specify more passwords. If more passwords are
554
	specified, it is a protocol-dependent decision which one is really
555
	used. Specifying passwords does not mean that authentication is
556
	enabled, authentication can be enabled by separate, protocol-dependent
557
	<cf/authentication/ option.
558
	
559
	This option is allowed in OSPF and RIP protocols. BGP has also
560
	<cf/password/ option, but it is slightly different and described
561
	separately.
562

    
563
	Default: none.
564
</descrip>
565

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

    
568
<descrip>
569
	<tag>id <M>num</M></tag>
570
	 ID of the password, (0-255). If it's not used, BIRD will choose
571
	 ID based on an order of the password item in the interface. For
572
	 example, second password item in one interface will have default
573
	 ID 2. ID is used by some routing protocols to identify which
574
	 password was used to authenticate protocol packets.
575

    
576
	<tag>generate from "<m/time/"</tag>
577
	 The start time of the usage of the password for packet signing.
578
	 The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
579

    
580
	<tag>generate to "<m/time/"</tag>
581
	 The last time of the usage of the password for packet signing.
582

    
583
	<tag>accept from "<m/time/"</tag>
584
	 The start time of the usage of the password for packet verification.
585

    
586
	<tag>accept to "<m/time/"</tag>
587
	 The last time of the usage of the password for packet verification.
588
</descrip>
589

    
590
<chapt>Remote control
591

    
592
<p>You can use the command-line client <file>birdc</file> to talk with
593
a running BIRD. Communication is done using a <file/bird.ctl/ UNIX
594
domain socket (unless changed with the <tt/-s/ option given to both
595
the server and the client). The commands can perform simple actions
596
such as enabling/disabling of protocols, telling BIRD to show various
597
information, telling it to show routing table filtered by filter, or
598
asking BIRD to reconfigure. Press <tt/?/ at any time to get online
599
help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
600
client, which allows just read-only commands (<cf/show .../). Option
601
<tt/-v/ can be passed to the client, to make it dump numeric return
602
codes along with the messages. You do not necessarily need to use
603
<file/birdc/ to talk to BIRD, your own applications could do that, too
604
-- the format of communication between BIRD and <file/birdc/ is stable
605
(see the programmer's documentation).
606

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

    
610
<p>Here is a brief list of supported functions:
611

    
612
<descrip>
613
	<tag>dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
614
	Dump contents of internal data structures to the debugging output.
615

    
616
	<tag>show status</tag>
617
	Show router status, that is BIRD version, uptime and time from last reconfiguration.
618

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

    
622
	<tag>show ospf interface [<m/name/] ["<m/interface/"]</tag>
623
	Show detailed information about OSPF interfaces.
624

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

    
628
	<tag>show ospf state [all] [<m/name/]</tag>
629
	Show detailed information about OSPF areas based on a content
630
	of the link-state database. It shows network topology, stub
631
	networks, aggregated networks and routers from other areas and
632
	external routes. The command shows information about reachable
633
	network nodes, use option <cf/all/ to show information about
634
	all network nodes in the link-state database.
635

    
636
	<tag>show ospf topology [all] [<m/name/]</tag>
637
	Show a topology of OSPF areas based on a content of the
638
	link-state database.  It is just a stripped-down version of
639
	'show ospf state'.
640

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

    
644
	<tag>show static [<m/name/]</tag>
645
	Show detailed information about static routes.
646

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

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

    
653
	<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>
654
	Show contents of a routing table (by default of the main one),
655
	that is routes, their metrics and (in case the <cf/all/ switch is given)
656
	all their attributes.
657

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

    
665
	<p>You can also ask for printing only routes processed and accepted by
666
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
667
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
668
	The <cf/export/ and <cf/preexport/ switches ask for printing of entries
669
	that are exported to the specified protocol. With <cf/preexport/, the
670
	export filter of the protocol is skipped.
671

    
672
	<p>You can also select just routes added by a specific protocol.
673
	<cf>protocol <m/p/</cf>.
674

    
675
	<p>If BIRD is configured to keep rejected routes (see </cf/import keep rejected/
676
	option), you can show them instead of routes by using </cf/rejected/ switch.
677

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

    
682
	<tag>show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/>]</tag>
683
	Show contents of a ROA table (by default of the first one).
684
	You can specify a <m/prefix/ to print ROA entries for a
685
	specific network. If you use <cf>for <m/prefix/</cf>, you'll
686
	get all entries relevant for route validation of the network
687
	prefix; i.e., ROA entries whose prefixes cover the network
688
	prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA entries
689
	covered by the network prefix. You could also use <cf/as/ option
690
	to show just entries for given AS.
691

    
692
	<tag>add roa <m/prefix/ max <m/num/] as <m/num/ [table <m/t/>]</tag>
693
	Add a new ROA entry to a ROA table. Such entry is called
694
	<it/dynamic/ compared to <it/static/ entries specified in the
695
	config file. These dynamic entries survive reconfiguration.
696

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

    
702
	<tag>flush roa [table <m/t/>]</tag>
703
	Remove all dynamic ROA entries from a ROA table.
704

    
705
	<tag>configure [soft] ["<m/config file/"]</tag>
706
	Reload configuration from a given file. BIRD will smoothly
707
	switch itself to the new configuration, protocols are
708
	reconfigured if possible, restarted otherwise. Changes in
709
	filters usually lead to restart of affected protocols. If
710
	<cf/soft/ option is used, changes in filters does not cause
711
	BIRD to restart affected protocols, therefore already accepted
712
	routes (according to old filters) would be still propagated,
713
	but new routes would be processed according to the new
714
	filters.
715

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

    
719
	<tag>reload [in|out] <m/name/|"<m/pattern/"|all</tag>
720
	
721
	Reload a given protocol instance, that means re-import routes
722
	from the protocol instance and re-export preferred routes to
723
	the instance. If <cf/in/ or <cf/out/ options are used, the
724
	command is restricted to one direction (re-import or
725
	re-export).
726

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

    
732
	Re-export always succeeds, but re-import is protocol-dependent
733
	and might fail (for example, if BGP neighbor does not support
734
	route-refresh extension). In that case, re-export is also
735
	skipped. Note that for the pipe protocol, both directions are
736
	always reloaded together (<cf/in/ or <cf/out/ options are
737
	ignored in that case).
738

    
739
	<tag/down/
740
	Shut BIRD down.
741

    
742
	<tag>debug <m/protocol/|<m/pattern/|all all|off|{ states | routes | filters | events | packets }</tag>
743
	Control protocol debugging.
744
</descrip>
745

    
746
<chapt>Filters
747

    
748
<sect>Introduction
749

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

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

    
760
<code>
761
filter not_too_far
762
int var;
763
{
764
	if defined( rip_metric ) then
765
		var = rip_metric;
766
	else {
767
		var = 1;
768
		rip_metric = 1;
769
	}
770
	if rip_metric &gt; 10 then
771
		reject "RIP metric is too big";
772
	else
773
		accept "ok";
774
}
775
</code>
776

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

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

    
788
<code>
789
function name ()
790
int local_variable;
791
{
792
	local_variable = 5;
793
}
794

    
795
function with_parameters (int parameter)
796
{
797
	print parameter;
798
}
799
</code>
800

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

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

    
812
<p>A nice trick to debug filters is to use <cf>show route filter
813
<m/name/</cf> from the command line client. An example session might look
814
like:
815

    
816
<code>
817
pavel@bug:~/bird$ ./birdc -s bird.ctl
818
BIRD 0.0.0 ready.
819
bird> show route
820
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
821
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
822
127.0.0.0/8        dev lo [direct1 23:21] (240)
823
bird> show route ?
824
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
825
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
826
127.0.0.0/8        dev lo [direct1 23:21] (240)
827
bird>
828
</code>
829

    
830
<sect>Data types
831

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

    
835
<descrip>
836
	<tag/bool/ This is a boolean type, it can have only two values, <cf/true/ and
837
	  <cf/false/. Boolean is the only type you can use in <cf/if/
838
	  statements.
839

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

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

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

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

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

    
862
	<tag/prefix/ This type can hold a network prefix consisting of IP address and prefix length. Prefix literals are written as
863
	  <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or
864
	  <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
865
	  operators on prefixes:
866
	  <cf/.ip/ which extracts the IP address from the pair, and <cf/.len/, which separates prefix
867
	  length from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true.
868

    
869
	<tag/ec/ This is a specialized type used to represent BGP
870
	  extended community values. It is essentially a 64bit value,
871
	  literals of this type are usually written as <cf>(<m/kind/,
872
	  <m/key/, <m/value/)</cf>, where <cf/kind/ is a kind of
873
	  extended community (e.g. <cf/rt/ / <cf/ro/ for a route
874
	  target / route origin communities), the format and possible
875
	  values of <cf/key/ and <cf/value/ are usually integers, but
876
	  it depends on the used kind. Similarly to pairs, ECs can be
877
	  constructed using expressions for <cf/key/ and
878
	  <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
879
	  <cf/myas/ is an integer variable).
880
 
881
	<tag/int|pair|quad|ip|prefix|ec|enum set/
882
	  Filters recognize four types of sets. Sets are similar to strings: you can pass them around
883
	  but you can't modify them. Literals of type <cf>int set</cf> look like <cf>
884
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
885
	  sets.
886

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

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

    
898
	  You can also use expressions for int, pair and EC set values. However it must
899
	  be possible to evaluate these expressions before daemon boots. So you can use
900
	  only constants inside them. E.g.
901
	<code>
902
	 define one=1;
903
	 define myas=64500;
904
	 int set odds;
905
	 pair set ps;
906
	 ec set es;
907

    
908
	 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
909
	 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
910
	 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
911
	</code>
912

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

    
921
	  There are also two shorthands for prefix patterns: <cf><m>address</m>/<m/len/+</cf> is a shorthand for
922
	  <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), 
923
	  that means network prefix <cf><m>address</m>/<m/len/</cf> and all its subnets. <cf><m>address</m>/<m/len/-</cf>
924
	  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>
925
	  and all its supernets (network prefixes that contain it).
926

    
927
	  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
928
	  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
929
	  <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
930
	  IP address) whose prefix length is 20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP address
931
	  <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf> is true,
932
	  but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
933

    
934
	  Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
935
	  in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as 
936
	  <cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
937
	  <cf>192.168.0.0/16{24,32}</cf>.
938

    
939
	<tag/enum/
940
	  Enumeration types are fixed sets of possibilities. You can't define your own
941
	  variables of such type, but some route attributes are of enumeration
942
	  type. Enumeration types are incompatible with each other.
943

    
944
	<tag/bgppath/
945
	  BGP path is a list of autonomous system numbers. You can't write literals of this type.
946
	  There are several special operators on bgppaths:
947

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

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

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

    
955
          <cf><m/P/.len</cf> returns the length of path <m/P/.
956

    
957
          <cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and returns the result.
958
          Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
959
          <cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
960
          (for example <cf/bgp_path/).
961

    
962
	<tag/bgpmask/
963
	  BGP masks are patterns used for BGP path matching
964
	  (using <cf>path &tilde; [= 2 3 5 * =]</cf> syntax). The masks
965
	  resemble wildcard patterns as used by UNIX shells. Autonomous
966
	  system numbers match themselves, <cf/*/ matches any (even empty)
967
	  sequence of arbitrary AS numbers and <cf/?/ matches one arbitrary AS number.
968
	  For example, if <cf>bgp_path</cf> is 4 3 2 1, then:
969
	  <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true, but 
970
	  <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false.
971
	  BGP mask expressions can also contain integer expressions enclosed in parenthesis
972
	  and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>.
973
	  There is also old syntax that uses / .. / instead of [= .. =] and ? instead of *.
974

    
975
	<tag/clist/
976
	  Clist is similar to a set, except that unlike other sets, it
977
	  can be modified. The type is used for community list (a set
978
	  of pairs) and for cluster list (a set of quads). There exist
979
	  no literals of this type. There are three special operators on
980
	  clists:
981

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

    
987
          <cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad)
988
	  <m/P/ from clist <m/C/ and returns the result.  If clist
989
	  <m/C/ does not contain item <m/P/, it does nothing.
990
	  <m/P/ may also be a pair (or quad) set, in that case the
991
	  operator deletes all items from clist <m/C/ that are also
992
	  members of set <m/P/. Moreover, <m/P/ may also be a clist,
993
	  which works analogously; i.e., it works as clist difference.
994

    
995
          <cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist
996
	  <m/C/ that are not members of pair (or quad) set <m/P/.
997
	  I.e., <cf/filter/ do the same as <cf/delete/ with inverted
998
	  set <m/P/. <m/P/ may also be a clist, which works analogously;
999
	  i.e., it works as clist intersection.
1000

    
1001
          Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1002
          <cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route
1003
          attribute (for example <cf/bgp_community/). Similarly for
1004
          <cf/delete/ and <cf/filter/.
1005

    
1006
	<tag/eclist/
1007
	  Eclist is a data type used for BGP extended community lists.
1008
	  Eclists are very similar to clists, but they are sets of ECs
1009
	  instead of pairs. The same operations (like <cf/add/,
1010
	  <cf/delete/, or <cf/&tilde;/ membership operator) can be
1011
	  used to modify or test eclists, with ECs instead of pairs as
1012
	  arguments.
1013
</descrip>
1014

    
1015
<sect>Operators
1016

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

    
1024
<p>There is one operator related to ROA infrastructure -
1025
<cf/roa_check()/. It examines a ROA table and does RFC 6483 route
1026
origin validation for a given network prefix. The basic usage
1027
is <cf>roa_check(<m/table/)</cf>, which checks current route (which
1028
should be from BGP to have AS_PATH argument) in the specified ROA
1029
table and returns ROA_UNKNOWN if there is no relevant ROA, ROA_VALID
1030
if there is a matching ROA, or ROA_INVALID if there are some relevant
1031
ROAs but none of them match. There is also an extended variant
1032
<cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to
1033
specify a prefix and an ASN as arguments.
1034

    
1035

    
1036
<sect>Control structures
1037

    
1038
<p>Filters support two control structures: conditions and case switches. 
1039

    
1040
<p>Syntax of a condition is: <cf>if
1041
<M>boolean expression</M> then <M>command1</M>; else <M>command2</M>;</cf> and you can use <cf>{
1042
<M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of either command. The <cf>else</cf>
1043
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.
1044

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

    
1051
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
1052

    
1053
<code>
1054
case arg1 {
1055
	2: print "two"; print "I can do more commands without {}";
1056
	3 .. 5: print "three to five";
1057
	else: print "something else";
1058
}
1059

    
1060
if 1234 = i then printn "."; else { 
1061
  print "not 1234"; 
1062
  print "You need {} around multiple commands"; 
1063
}
1064
</code>
1065

    
1066
<sect>Route attributes
1067

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

    
1075
<descrip>
1076
	<tag><m/prefix/ net</tag>
1077
	Network the route is talking about. Read-only. (See the chapter about routing tables.)
1078

    
1079
	<tag><m/enum/ scope</tag>
1080
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for
1081
	routes local to this host, <cf/SCOPE_LINK/ for those specific
1082
	for a physical link, <cf/SCOPE_SITE/ and
1083
	<cf/SCOPE_ORGANIZATION/ for private routes and
1084
	<cf/SCOPE_UNIVERSE/ for globally visible routes. This
1085
	attribute is not interpreted by BIRD and can be used to mark
1086
	routes in filters. The default value for new routes is
1087
	<cf/SCOPE_UNIVERSE/.
1088

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

    
1092
	<tag><m/ip/ from</tag>
1093
	The router which the route has originated from. Read-only.
1094
	
1095
	<tag><m/ip/ gw</tag>
1096
	Next hop packets routed using this route should be forwarded to.
1097

    
1098
	<tag><m/string/ proto</tag>
1099
	The name of the protocol which the route has been imported from. Read-only.
1100

    
1101
	<tag><m/enum/ source</tag>
1102
	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/.
1103

    
1104
	<tag><m/enum/ cast</tag>
1105

    
1106
	Route type (Currently <cf/RTC_UNICAST/ for normal routes,
1107
	<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will
1108
	be used in the future for broadcast, multicast and anycast
1109
	routes). Read-only.
1110

    
1111
	<tag><m/enum/ dest</tag>
1112
	Type of destination the packets should be sent to
1113
	(<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1114
	<cf/RTD_DEVICE/ for routing to a directly-connected network,
1115
	<cf/RTD_MULTIPATH/ for multipath destinations,
1116
	<cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1117
	<cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that
1118
	should be returned with ICMP host unreachable / ICMP
1119
	administratively prohibited messages). Can be changed, but
1120
	only to <cf/RTD_BLACKHOLE/, <cf/RTD_UNREACHABLE/ or
1121
	<cf/RTD_PROHIBIT/.
1122

    
1123
	<tag><m/int/ igp_metric</tag>
1124
	The optional attribute that can be used to specify a distance
1125
	to the network for routes that do not have a native protocol
1126
	metric attribute (like <cf/ospf_metric1/ for OSPF routes). It
1127
	is used mainly by BGP to compare internal distances to boundary
1128
	routers (see below). It is also used when the route is exported
1129
	to OSPF as a default value for OSPF type 1 metric.
1130
</descrip>
1131

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

    
1134
<sect>Other statements
1135

    
1136
<p>The following statements are available:
1137

    
1138
<descrip>
1139
	<tag><m/variable/ = <m/expr/</tag> Set variable to a given value.
1140

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

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

    
1145
	<tag>print|printn <m/expr/ [<m/, expr.../]</tag>
1146
	Prints given expressions; useful mainly while debugging
1147
	filters. The <cf/printn/ variant does not terminate the line.
1148

    
1149
	<tag>quitbird</tag>
1150
	Terminates BIRD. Useful when debugging the filter interpreter.
1151
</descrip>
1152

    
1153
<chapt>Protocols
1154

    
1155
<sect>BGP
1156

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

    
1164
<p>BGP works in terms of autonomous systems (often abbreviated as
1165
AS). Each AS is a part of the network with common management and
1166
common routing policy. It is identified by a unique 16-bit number
1167
(ASN).  Routers within each AS usually exchange AS-internal routing
1168
information with each other using an interior gateway protocol (IGP,
1169
such as OSPF or RIP). Boundary routers at the border of
1170
the AS communicate global (inter-AS) network reachability information with
1171
their neighbors in the neighboring AS'es via exterior BGP (eBGP) and
1172
redistribute received information to other routers in the AS via
1173
interior BGP (iBGP).
1174

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

    
1180
<p>BIRD supports all requirements of the BGP4 standard as defined in
1181
RFC 4271<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4271.txt">
1182
It also supports the community attributes
1183
(RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">),
1184
capability negotiation
1185
(RFC 3392<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc3392.txt">),
1186
MD5 password authentication
1187
(RFC 2385<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2385.txt">),
1188
extended communities
1189
(RFC 4360<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4360.txt">),
1190
route reflectors 
1191
(RFC 4456<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4456.txt">),
1192
multiprotocol extensions
1193
(RFC 4760<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4760.txt">),
1194
4B AS numbers 
1195
(RFC 4893<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4893.txt">),
1196
and 4B AS numbers in extended communities
1197
(RFC 5668<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc5668.txt">).
1198

    
1199

    
1200
For IPv6, it uses the standard multiprotocol extensions defined in
1201
RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt">
1202
including changes described in the
1203
latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt">
1204
and applied to IPv6 according to
1205
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
1206

    
1207
<sect1>Route selection rules
1208

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

    
1215
<itemize>
1216
	<item>Prefer route with the highest Local Preference attribute.
1217
	<item>Prefer route with the shortest AS path.
1218
	<item>Prefer IGP origin over EGP and EGP origin over incomplete.
1219
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
1220
	<item>Prefer routes received via eBGP over ones received via iBGP.
1221
	<item>Prefer routes with lower internal distance to a boundary router.
1222
	<item>Prefer the route with the lowest value of router ID of the
1223
	advertising router.
1224
</itemize>
1225

    
1226
<sect1>IGP routing table
1227

    
1228
<p>BGP is mainly concerned with global network reachability and with
1229
routes to other autonomous systems. When such routes are redistributed
1230
to routers in the AS via BGP, they contain IP addresses of a boundary
1231
routers (in route attribute NEXT_HOP). BGP depends on existing IGP
1232
routing table with AS-internal routes to determine immediate next hops
1233
for routes and to know their internal distances to boundary routers
1234
for the purpose of BGP route selection. In BIRD, there is usually
1235
one routing table used for both IGP routes and BGP routes.
1236

    
1237
<sect1>Configuration
1238

    
1239
<p>Each instance of the BGP corresponds to one neighboring router.
1240
This allows to set routing policy and all the other parameters differently
1241
for each neighbor using the following configuration parameters:
1242

    
1243
<descrip>
1244
	<tag>local [<m/ip/] as <m/number/</tag> Define which AS we
1245
	are part of. (Note that contrary to other IP routers, BIRD is
1246
	able to act as a router located in multiple AS'es
1247
	simultaneously, but in such cases you need to tweak the BGP
1248
	paths manually in the filters to get consistent behavior.)
1249
	Optional <cf/ip/ argument specifies a source address,
1250
	equivalent to the <cf/source address/ option (see below).
1251
	This parameter is mandatory.
1252

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

    
1259
	<tag>multihop [<m/number/]</tag> Configure multihop BGP
1260
	session to a neighbor that isn't directly connected.
1261
	Accurately, this option should be used if the configured
1262
	neighbor IP address does not match with any local network
1263
	subnets. Such IP address have to be reachable through system
1264
	routing table. For multihop BGP it is recommended to
1265
	explicitly configure <cf/source address/ to have it
1266
	stable. Optional <cf/number/ argument can be used to specify
1267
	the number of hops (used for TTL). Note that the number of
1268
	networks (edges) in a path is counted, i.e. if two BGP
1269
	speakers are separated by one router, the number of hops is
1270
	2. Default: switched off.
1271

    
1272
	<tag>source address <m/ip/</tag> Define local address we
1273
	should use for next hop calculation and as a source address
1274
	for the BGP session. Default: the address of the local
1275
	end of the interface our neighbor is connected to.
1276

    
1277
	<tag>next hop self</tag> Avoid calculation of the Next Hop
1278
	attribute and always advertise our own source address as a
1279
	next hop.  This needs to be used only occasionally to
1280
	circumvent misconfigurations of other routers.  Default:
1281
	disabled.
1282

    
1283
	<tag>missing lladdr self|drop|ignore</tag>Next Hop attribute
1284
	in BGP-IPv6 sometimes contains just the global IPv6 address,
1285
	but sometimes it has to contain both global and link-local
1286
	IPv6 addresses. This option specifies what to do if BIRD have
1287
	to send both addresses but does not know link-local address.
1288
	This situation might happen when routes from other protocols
1289
	are exported to BGP, or when improper updates are received
1290
	from BGP peers.  <cf/self/ means that BIRD advertises its own
1291
	local address instead. <cf/drop/ means that BIRD skips that
1292
	prefixes and logs error. <cf/ignore/ means that BIRD ignores
1293
	the problem and sends just the global address (and therefore
1294
	forms improper BGP update). Default: <cf/self/, unless BIRD
1295
	is configured as a route server (option <cf/rs client/), in
1296
	that case default is <cf/ignore/, because route servers usually
1297
	do not forward packets themselves.
1298

    
1299
	<tag>gateway direct|recursive</tag>For received routes, their
1300
	<cf/gw/ (immediate next hop) attribute is computed from
1301
	received <cf/bgp_next_hop/ attribute. This option specifies
1302
	how it is computed. Direct mode means that the IP address from
1303
	<cf/bgp_next_hop/ is used if it is directly reachable,
1304
	otherwise the neighbor IP address is used. Recursive mode
1305
	means that the gateway is computed by an IGP routing table
1306
	lookup for the IP address from <cf/bgp_next_hop/. Recursive
1307
	mode is the behavior specified by the BGP standard. Direct
1308
	mode is simpler, does not require any routes in a routing
1309
	table, and was used in older versions of BIRD, but does not
1310
	handle well nontrivial iBGP setups and multihop.  Recursive
1311
	mode is incompatible with <ref id="dsc-sorted" name="sorted
1312
	tables">. Default: <cf/direct/ for singlehop eBGP,
1313
	<cf/recursive/ otherwise.
1314

    
1315
	<tag>igp table <m/name/</tag> Specifies a table that is used
1316
	as an IGP routing table. Default: the same as the table BGP is
1317
	connected to.
1318
	
1319
	<tag>ttl security <m/switch/</tag> Use GTSM (RFC 5082 - the
1320
	generalized TTL security mechanism). GTSM protects against
1321
	spoofed packets by ignoring received packets with a smaller
1322
	than expected TTL. To work properly, GTSM have to be enabled
1323
	on both sides of a BGP session. If both <cf/ttl security/ and
1324
	<cf/multihop/ options are enabled, <cf/multihop/ option should
1325
	specify proper hop value to compute expected TTL. Kernel
1326
	support required: Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD:
1327
	since long ago, IPv4 only. Note that full (ICMP protection,
1328
	for example) RFC 5082 support is provided by Linux
1329
	only. Default: disabled.
1330
	
1331
	<tag>password <m/string/</tag> Use this password for MD5 authentication
1332
	of BGP sessions. Default: no authentication. Password has to be set by
1333
	external utility (e.g. setkey(8)) on BSD systems.
1334

    
1335
	<tag>passive <m/switch/</tag> Standard BGP behavior is both
1336
        initiating outgoing connections and accepting incoming
1337
        connections. In passive mode, outgoing connections are not
1338
        initiated. Default: off.
1339

    
1340
	<tag>rr client</tag> Be a route reflector and treat the neighbor as
1341
	a route reflection client. Default: disabled.
1342

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

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

    
1359
	<tag>secondary <m/switch/</tag> Usually, if an import filter
1360
	rejects a selected route, no other route is propagated for
1361
	that network. This option allows to try the next route in
1362
	order until one that is accepted is found or all routes for
1363
	that network are rejected. This can be used for route servers
1364
	that need to propagate different tables to each client but do
1365
	not want to have these tables explicitly (to conserve memory).
1366
	This option requires that the connected routing table is
1367
	<ref id="dsc-sorted" name="sorted">. Default: off.
1368

    
1369
	<tag>enable route refresh <m/switch/</tag> When BGP speaker
1370
	changes its import filter, it has to re-examine all routes
1371
	received from its neighbor against the new filter. As these
1372
	routes might not be available, there is a BGP protocol
1373
	extension Route Refresh (specified in RFC 2918) that allows
1374
	BGP speaker to request re-advertisement of all routes from its
1375
	neighbor. This option specifies whether BIRD advertises this
1376
	capability and accepts such requests. Even when disabled, BIRD
1377
	can send route refresh requests. Default: on.
1378

    
1379
	<tag>interpret communities <m/switch/</tag> RFC 1997 demands
1380
	that BGP speaker should process well-known communities like
1381
	no-export (65535, 65281) or no-advertise (65535, 65282). For
1382
	example, received route carrying a no-adverise community
1383
	should not be advertised to any of its neighbors. If this
1384
	option is enabled (which is by default), BIRD has such
1385
	behavior automatically (it is evaluated when a route is
1386
	exported to the BGP protocol just before the export filter).
1387
	Otherwise, this integrated processing of well-known
1388
	communities is disabled. In that case, similar behavior can be
1389
	implemented in the export filter.  Default: on.
1390

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

    
1399
	<tag>capabilities <m/switch/</tag> Use capability advertisement
1400
	to advertise optional capabilities. This is standard behavior
1401
	for newer BGP implementations, but there might be some older
1402
	BGP implementations that reject such connection attempts.
1403
	When disabled (off), features that request it (4B AS support)
1404
	are also disabled. Default: on, with automatic fallback to
1405
	off when received capability-related error.
1406

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

    
1413
	<tag>route limit <m/number/</tag> The maximal number of routes
1414
	that may be imported from the protocol. If the route limit is
1415
	exceeded, the connection is closed with error. Limit is currently implemented as
1416
	<cf/import limit number exceed restart/. Default: no limit.
1417

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

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

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

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

    
1434
	<tag>connect retry time <m/number/</tag> Time in seconds to wait before
1435
	retrying a failed attempt to connect. Default: 120 seconds.
1436

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

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

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

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

    
1452
	<tag>med metric <m/switch/</tag> Enable comparison of MED
1453
	attributes (during best route selection) even between routes
1454
	received from different ASes.  This may be useful if all MED
1455
	attributes contain some consistent metric, perhaps enforced in
1456
	import filters of AS boundary routers. If this option is
1457
	disabled, MED attributes are compared only if routes are
1458
	received from the same AS (which is the standard behavior).
1459
	Default: off.
1460

    
1461
	<tag>deterministic med <m/switch/</tag> BGP route selection
1462
	algorithm is often viewed as a comparison between individual
1463
	routes (e.g. if a new route appears and is better than the
1464
	current best one, it is chosen as the new best one). But the
1465
	proper route selection, as specified by RFC 4271, cannot be
1466
	fully implemented in that way. The problem is mainly in
1467
	handling the MED attribute. BIRD, by default, uses an
1468
	simplification based on individual route comparison, which in
1469
	some cases may lead to temporally dependent behavior (i.e. the
1470
	selection is dependent on the order in which routes appeared).
1471
	This option enables a different (and slower) algorithm
1472
	implementing proper RFC 4271 route selection, which is
1473
	deterministic. Alternative way how to get deterministic
1474
	behavior is to use <cf/med metric/ option. This option is
1475
	incompatible with <ref id="dsc-sorted" name="sorted tables">.
1476
	Default: off.
1477

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

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

    
1486
	<tag>default bgp_med <m/number/</tag> Value of the Multiple Exit
1487
	Discriminator to be used during route selection when the MED attribute
1488
	is missing. Default: 0.
1489

    
1490
	<tag>default bgp_local_pref <m/number/</tag> A default value
1491
	for the Local Preference attribute. It is used when a new
1492
	Local Preference attribute is attached to a route by the BGP
1493
	protocol itself (for example, if a route is received through
1494
	eBGP and therefore does not have such attribute). Default: 100
1495
	(0 in pre-1.2.0 versions of BIRD).
1496
</descrip>
1497

    
1498
<sect1>Attributes
1499

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

    
1504
<descrip>
1505
	<tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path
1506
	the packet will travel through when forwarded according to the particular route.
1507
	In case of internal BGP it doesn't contain the number of the local AS.
1508

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

    
1513
	<tag>int <cf/bgp_med/ [O]</tag> The Multiple Exit Discriminator of the route
1514
	is an optional attribute which is used on external (inter-AS) links to
1515
	convey to an adjacent AS the optimal entry point into the local AS.
1516
	The received attribute is also propagated over internal BGP links.
1517
	The attribute value is zeroed when a route is exported to an external BGP
1518
	instance to ensure that the attribute received from a neighboring AS is
1519
	not propagated to other neighboring ASes. A new value might be set in
1520
	the export filter of an external BGP instance.
1521
	See RFC 4451<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4451.txt">
1522
	for further discussion of BGP MED attribute.
1523

    
1524
	<tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/
1525
	if the route has originated in an interior routing protocol or
1526
	<cf/ORIGIN_EGP/ if it's been imported from the <tt>EGP</tt> protocol
1527
	(nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/ if the origin
1528
	is unknown.
1529

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

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

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

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

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

    
1564
	<tag>clist <cf/bgp_cluster_list/ [I, O]</tag> This attribute contains a list
1565
	of cluster IDs of route reflectors. Each route reflector prepends its
1566
	cluster ID when reflecting the route.
1567
</descrip>
1568

    
1569
<sect1>Example
1570

    
1571
<p><code>
1572
protocol bgp {
1573
	local as 65000;			     # Use a private AS number
1574
	neighbor 198.51.100.130 as 64496;    # Our neighbor ...
1575
	multihop;			     # ... which is connected indirectly
1576
	export filter {			     # We use non-trivial export rules
1577
		if source = RTS_STATIC then { # Export only static routes
1578
		        # Assign our community
1579
			bgp_community.add((65000,64501));
1580
			# Artificially increase path length
1581
			# by advertising local AS number twice
1582
			if bgp_path ~ [= 65000 =] then
1583
				bgp_path.prepend(65000);
1584
			accept;
1585
		}
1586
		reject;
1587
	};
1588
	import all;
1589
	source address 198.51.100.14;	# Use a non-standard source address
1590
}
1591
</code>
1592

    
1593
<sect>Device
1594

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

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

    
1603
<sect1>Configuration
1604

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

    
1612
	<tag>primary  [ "<m/mask/" ] <m/prefix/</tag>
1613
	If a network interface has more than one network address, BIRD
1614
	has to choose one of them as a primary one. By default, BIRD
1615
	chooses the lexicographically smallest address as the primary
1616
	one.
1617

    
1618
	This option allows to specify which network address should be
1619
	chosen as a primary one. Network addresses that match
1620
	<m/prefix/ are preferred to non-matching addresses. If more
1621
	<cf/primary/ options are used, the first one has the highest
1622
	preference. If "<m/mask/" is specified, then such
1623
	<cf/primary/ option is relevant only to matching network
1624
	interfaces.
1625

    
1626
	In all cases, an address marked by operating system as
1627
	secondary cannot be chosen as the primary one. 
1628
</descrip>
1629

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

    
1633
<p><code>
1634
protocol device {
1635
	scan time 10;		# Scan the interfaces often
1636
	primary "eth0" 192.168.1.1;
1637
	primary 192.168.0.0/16;
1638
}
1639
</code>
1640

    
1641
<sect>Direct
1642

    
1643
<p>The Direct protocol is a simple generator of device routes for all the
1644
directly connected networks according to the list of interfaces provided
1645
by the kernel via the Device protocol.
1646

    
1647
<p>The question is whether it is a good idea to have such device
1648
routes in BIRD routing table. OS kernel usually handles device routes
1649
for directly connected networks by itself so we don't need (and don't
1650
want) to export these routes to the kernel protocol. OSPF protocol
1651
creates device routes for its interfaces itself and BGP protocol is
1652
usually used for exporting aggregate routes. Although there are some
1653
use cases that use the direct protocol (like abusing eBGP as an IGP
1654
routing protocol), in most cases it is not needed to have these device
1655
routes in BIRD routing table and to use the direct protocol.
1656

    
1657
<p>The only configurable thing about direct is what interfaces it watches:
1658

    
1659
<p><descrip>
1660
	<tag>interface <m/pattern [, ...]/</tag> By default, the Direct
1661
	protocol will generate device routes for all the interfaces
1662
	available. If you want to restrict it to some subset of interfaces
1663
	(for example if you're using multiple routing tables for policy
1664
	routing and some of the policy domains don't contain all interfaces),
1665
	just use this clause.
1666
</descrip>
1667

    
1668
<p>Direct device routes don't contain any specific attributes.
1669

    
1670
<p>Example config might look like this:
1671

    
1672
<p><code>
1673
protocol direct {
1674
	interface "-arc*", "*";		# Exclude the ARCnets
1675
}
1676
</code>
1677

    
1678
<sect>Kernel
1679

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

    
1689
<p>Unfortunately, there is one thing that makes the routing table
1690
synchronization a bit more complicated. In the kernel routing table
1691
there are also device routes for directly connected networks. These
1692
routes are usually managed by OS itself (as a part of IP address
1693
configuration) and we don't want to touch that.  They are completely
1694
ignored during the scan of the kernel tables and also the export of
1695
device routes from BIRD tables to kernel routing tables is restricted
1696
to prevent accidental interference. This restriction can be disabled using
1697
<cf/device routes/ switch.
1698

    
1699
<p>If your OS supports only a single routing table, you can configure
1700
only one instance of the Kernel protocol. If it supports multiple
1701
tables (in order to allow policy routing; such an OS is for example
1702
Linux), you can run as many instances as you want, but each of them
1703
must be connected to a different BIRD routing table and to a different
1704
kernel table.
1705

    
1706
<p>Because the kernel protocol is partially integrated with the
1707
connected routing table, there are two limitations - it is not
1708
possible to connect more kernel protocols to the same routing table
1709
and changing route destination/gateway in an export
1710
filter of a kernel protocol does not work. Both limitations can be
1711
overcome using another routing table and the pipe protocol.
1712

    
1713
<sect1>Configuration
1714

    
1715
<p><descrip>
1716
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
1717
	routing tables when it exits (instead of cleaning them up).
1718
	<tag>scan time <m/number/</tag> Time in seconds between two consecutive scans of the
1719
	kernel routing table.
1720
	<tag>learn <m/switch/</tag> Enable learning of routes added to the kernel
1721
	routing tables by other routing daemons or by the system administrator.
1722
	This is possible only on systems which support identification of route
1723
	authorship.
1724

    
1725
	<tag>device routes <m/switch/</tag> Enable export of device
1726
	routes to the kernel routing table. By default, such routes
1727
	are rejected (with the exception of explicitly configured
1728
	device routes from the static protocol) regardless of the
1729
	export filter to protect device routes in kernel routing table
1730
	(managed by OS itself) from accidental overwriting or erasing.
1731

    
1732
	<tag>kernel table <m/number/</tag> Select which kernel table should
1733
	this particular instance of the Kernel protocol work with. Available
1734
	only on systems supporting multiple routing tables.
1735
</descrip>
1736

    
1737
<sect1>Attributes
1738

    
1739
<p>The Kernel protocol defines several attributes. These attributes
1740
are translated to appropriate system (and OS-specific) route attributes.
1741
We support these attributes:
1742

    
1743
<descrip>
1744
	<tag>int <cf/krt_source/</tag> The original source of the imported
1745
	kernel route.  The value is system-dependent. On Linux, it is
1746
	a value of the protocol field of the route. See
1747
	/etc/iproute2/rt_protos for common values.  On BSD, it is
1748
	based on STATIC and PROTOx flags. The attribute is read-only.
1749

    
1750
	<tag>int <cf/krt_metric/</tag> The kernel metric of
1751
	the route.  When multiple same routes are in a kernel routing
1752
	table, the Linux kernel chooses one with lower metric.
1753

    
1754
	<tag>ip <cf/krt_prefsrc/</tag> (Linux) The preferred source address.
1755
 	Used in source address selection for outgoing packets. Have to
1756
 	be one of IP addresses of the router.
1757

    
1758
	<tag>int <cf/krt_realm/</tag> (Linux) The realm of the route. Can be
1759
	used for traffic classification.
1760
</descrip>
1761

    
1762
<sect1>Example
1763

    
1764
<p>A simple configuration can look this way:
1765

    
1766
<p><code>
1767
protocol kernel {
1768
	export all;
1769
}
1770
</code>
1771

    
1772
<p>Or for a system with two routing tables:
1773

    
1774
<p><code>
1775
protocol kernel {		# Primary routing table
1776
	learn;			# Learn alien routes from the kernel
1777
	persist;		# Don't remove routes on bird shutdown
1778
	scan time 10;		# Scan kernel routing table every 10 seconds
1779
	import all;
1780
	export all;
1781
}
1782

    
1783
protocol kernel {		# Secondary routing table
1784
	table auxtable;
1785
	kernel table 100;
1786
	export all;
1787
}
1788
</code>
1789

    
1790
<sect>OSPF
1791

    
1792
<sect1>Introduction
1793

    
1794
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
1795
protocol. The current IPv4 version (OSPFv2) is defined in RFC
1796
2328<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2328.txt"> and
1797
the current IPv6 version (OSPFv3) is defined in RFC 5340<htmlurl
1798
url="ftp://ftp.rfc-editor.org/in-notes/rfc5340.txt">  It's a link state
1799
(a.k.a. shortest path first) protocol -- each router maintains a
1800
database describing the autonomous system's topology. Each participating
1801
router has an identical copy of the database and all routers run the
1802
same algorithm calculating a shortest path tree with themselves as a
1803
root. OSPF chooses the least cost path as the best path.
1804

    
1805
<p>In OSPF, the autonomous system can be split to several areas in order
1806
to reduce the amount of resources consumed for exchanging the routing
1807
information and to protect the other areas from incorrect routing data.
1808
Topology of the area is hidden to the rest of the autonomous system.
1809

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

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

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

    
1827
<sect1>Configuration
1828

    
1829
<p>In the main part of configuration, there can be multiple definitions of
1830
OSPF areas, each with a different id. These definitions includes many other
1831
switches and multiple definitions of interfaces. Definition of interface
1832
may contain many switches and constant definitions and list of neighbors
1833
on nonbroadcast networks.
1834

    
1835
<code>
1836
protocol ospf &lt;name&gt; {
1837
	rfc1583compat &lt;switch&gt;;
1838
	tick &lt;num&gt;;
1839
	ecmp &lt;switch&gt; [limit &lt;num&gt;];
1840
	area &lt;id&gt; {
1841
		stub;
1842
		nssa;
1843
		summary &lt;switch&gt;;
1844
		default nssa &lt;switch&gt;;
1845
		default cost &lt;num&gt;;
1846
		default cost2 &lt;num&gt;;
1847
		translator &lt;switch&gt;;
1848
		translator stability &lt;num&gt;;
1849

    
1850
                networks {
1851
			&lt;prefix&gt;;
1852
			&lt;prefix&gt; hidden;
1853
		}
1854
                external {
1855
			&lt;prefix&gt;;
1856
			&lt;prefix&gt; hidden;
1857
			&lt;prefix&gt; tag &lt;num&gt;;
1858
		}
1859
		stubnet &lt;prefix&gt;;
1860
		stubnet &lt;prefix&gt; {
1861
			hidden &lt;switch&gt;;
1862
			summary &lt;switch&gt;;
1863
			cost &lt;num&gt;;
1864
		}
1865
		interface &lt;interface pattern&gt; [instance &lt;num&gt;] {
1866
			cost &lt;num&gt;;
1867
			stub &lt;switch&gt;;
1868
			hello &lt;num&gt;;
1869
			poll &lt;num&gt;;
1870
			retransmit &lt;num&gt;;
1871
			priority &lt;num&gt;;
1872
			wait &lt;num&gt;;
1873
			dead count &lt;num&gt;;
1874
			dead &lt;num&gt;;
1875
			rx buffer [normal|large|&lt;num&gt;];
1876
			type [broadcast|bcast|pointopoint|ptp|
1877
				nonbroadcast|nbma|pointomultipoint|ptmp];
1878
			strict nonbroadcast &lt;switch&gt;;
1879
			real broadcast &lt;switch&gt;;
1880
			check link &lt;switch&gt;;
1881
			ecmp weight &lt;num&gt;;
1882
			authentication [none|simple|cryptographic];
1883
			password "&lt;text&gt;";
1884
			password "&lt;text&gt;" {
1885
				id &lt;num&gt;;
1886
				generate from "&lt;date&gt;";
1887
				generate to "&lt;date&gt;";
1888
				accept from "&lt;date&gt;";
1889
				accept to "&lt;date&gt;";
1890
			};
1891
			neighbors {
1892
				&lt;ip&gt;;
1893
				&lt;ip&gt; eligible;
1894
			};
1895
		};
1896
		virtual link &lt;id&gt; [instance &lt;num&gt;] {
1897
			hello &lt;num&gt;;
1898
			retransmit &lt;num&gt;;
1899
			wait &lt;num&gt;;
1900
			dead count &lt;num&gt;;
1901
			dead &lt;num&gt;;
1902
			authentication [none|simple|cryptographic];
1903
			password "&lt;text&gt;";
1904
		};
1905
	};
1906
}
1907
</code>
1908

    
1909
<descrip>
1910
	<tag>rfc1583compat <M>switch</M></tag>
1911
	 This option controls compatibility of routing table
1912
	 calculation with RFC 1583<htmlurl
1913
	 url="ftp://ftp.rfc-editor.org/in-notes/rfc1583.txt">. Default
1914
	 value is no.
1915

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

    
1922
	<tag>ecmp <M>switch</M> [limit <M>number</M>]</tag>
1923
	 This option specifies whether OSPF is allowed to generate
1924
	 ECMP (equal-cost multipath) routes. Such routes are used when
1925
	 there are several directions to the destination, each with
1926
	 the same (computed) cost. This option also allows to specify
1927
	 a limit on maximal number of nexthops in one route. By
1928
	 default, ECMP is disabled.  If enabled, default value of the
1929
	 limit is 16.
1930

    
1931
	<tag>area <M>id</M></tag>
1932
	 This defines an OSPF area with given area ID (an integer or an IPv4
1933
	 address, similarly to a router ID). The most important area is
1934
	 the backbone (ID 0) to which every other area must be connected.
1935

    
1936
	<tag>stub</tag>
1937
	 This option configures the area to be a stub area. External
1938
	 routes are not flooded into stub areas. Also summary LSAs can be
1939
	 limited in stub areas (see option <cf/summary/).
1940
	 By default, the area is not a stub area.
1941

    
1942
	<tag>nssa</tag>
1943
	 This option configures the area to be a NSSA (Not-So-Stubby
1944
	 Area). NSSA is a variant of a stub area which allows a
1945
	 limited way of external route propagation. Global external
1946
	 routes are not propagated into a NSSA, but an external route
1947
	 can be imported into NSSA as a (area-wide) NSSA-LSA (and
1948
	 possibly translated and/or aggregated on area boundary).
1949
	 By default, the area is not NSSA.
1950

    
1951
	<tag>summary <M>switch</M></tag>
1952
	 This option controls propagation of summary LSAs into stub or
1953
	 NSSA areas. If enabled, summary LSAs are propagated as usual,
1954
	 otherwise just the default summary route (0.0.0.0/0) is
1955
	 propagated (this is sometimes called totally stubby area). If
1956
	 a stub area has more area boundary routers, propagating
1957
	 summary LSAs could lead to more efficient routing at the cost
1958
	 of larger link state database. Default value is no.
1959

    
1960
	<tag>default nssa <M>switch</M></tag>
1961
 	 When <cf/summary/ option is enabled, default summary route is
1962
	 no longer propagated to the NSSA. In that case, this option
1963
	 allows to originate default route as NSSA-LSA to the NSSA.
1964
	 Default value is no.
1965

    
1966
	<tag>default cost <M>num</M></tag>
1967
	 This option controls the cost of a default route propagated to
1968
	 stub and NSSA areas. Default value is 1000.
1969

    
1970
	<tag>default cost2 <M>num</M></tag>
1971
	 When a default route is originated as NSSA-LSA, its cost
1972
	 can use either type 1 or type 2 metric. This option allows
1973
	 to specify the cost of a default route in type 2 metric.
1974
	 By default, type 1 metric (option <cf/default cost/) is used.
1975

    
1976
	<tag>translator <M>switch</M></tag>
1977
	 This option controls translation of NSSA-LSAs into external
1978
	 LSAs. By default, one translator per NSSA is automatically
1979
	 elected from area boundary routers. If enabled, this area
1980
	 boundary router would unconditionally translate all NSSA-LSAs
1981
	 regardless of translator election. Default value is no.
1982

    
1983
	<tag>translator stability <M>num</M></tag>
1984
	 This option controls the translator stability interval (in
1985
	 seconds). When the new translator is elected, the old one
1986
	 keeps translating until the interval is over. Default value
1987
	 is 40.
1988

    
1989
	<tag>networks { <m/set/ }</tag>
1990
         Definition of area IP ranges. This is used in summary LSA origination.
1991
	 Hidden networks are not propagated into other areas.
1992

    
1993
	<tag>external { <m/set/ }</tag>
1994
         Definition of external area IP ranges for NSSAs. This is used
1995
	 for NSSA-LSA translation. Hidden networks are not translated
1996
	 into external LSAs. Networks can have configured route tag.
1997

    
1998
	<tag>stubnet <m/prefix/ { <m/options/ }</tag>
1999
	 Stub networks are networks that are not transit networks
2000
	 between OSPF routers. They are also propagated through an
2001
	 OSPF area as a part of a link state database. By default,
2002
	 BIRD generates a stub network record for each primary network
2003
	 address on each OSPF interface that does not have any OSPF
2004
	 neighbors, and also for each non-primary network address on
2005
	 each OSPF interface. This option allows to alter a set of
2006
	 stub networks propagated by this router. 
2007

    
2008
	 Each instance of this option adds a stub network with given
2009
	 network prefix to the set of propagated stub network, unless
2010
	 option <cf/hidden/ is used. It also suppresses default stub
2011
	 networks for given network prefix. When option
2012
	 <cf/summary/ is used, also default stub networks that are
2013
	 subnetworks of given stub network are suppressed. This might
2014
	 be used, for example, to aggregate generated stub networks.
2015
	 
2016
	<tag>interface <M>pattern</M> [instance <m/num/]</tag>
2017
	 Defines that the specified interfaces belong to the area being defined.
2018
	 See <ref id="dsc-iface" name="interface"> common option for detailed description.
2019
	 In OSPFv3, you can specify instance ID for that interface
2020
	 description, so it is possible to have several instances of
2021
	 that interface with different options or even in different areas.
2022

    
2023
	<tag>virtual link <M>id</M> [instance <m/num/]</tag>
2024
	 Virtual link to router with the router id. Virtual link acts
2025
         as a point-to-point interface belonging to backbone. The
2026
         actual area is used as transport area. This item cannot be in
2027
         the backbone. In OSPFv3, you could also use several virtual
2028
         links to one destination with different instance IDs.
2029

    
2030
	<tag>cost <M>num</M></tag>
2031
	 Specifies output cost (metric) of an interface. Default value is 10.
2032

    
2033
	<tag>stub <M>switch</M></tag>
2034
	 If set to interface it does not listen to any packet and does not send
2035
	 any hello. Default value is no.
2036

    
2037
	<tag>hello <M>num</M></tag>
2038
	 Specifies interval in seconds between sending of Hello messages. Beware, all
2039
	 routers on the same network need to have the same hello interval.
2040
	 Default value is 10.
2041

    
2042
	<tag>poll <M>num</M></tag>
2043
	 Specifies interval in seconds between sending of Hello messages for
2044
	 some neighbors on NBMA network. Default value is 20.
2045

    
2046
	<tag>retransmit <M>num</M></tag>
2047
	 Specifies interval in seconds between retransmissions of unacknowledged updates.
2048
	 Default value is 5.
2049

    
2050
        <tag>priority <M>num</M></tag>
2051
	 On every multiple access network (e.g., the Ethernet) Designed Router
2052
	 and Backup Designed router are elected. These routers have some
2053
	 special functions in the flooding process. Higher priority increases
2054
	 preferences in this election. Routers with priority 0 are not
2055
	 eligible. Default value is 1.
2056

    
2057
	<tag>wait <M>num</M></tag>
2058
	 After start, router waits for the specified number of seconds between starting
2059
	 election and building adjacency. Default value is 40.
2060
	 
2061
	<tag>dead count <M>num</M></tag>
2062
	 When the router does not receive any messages from a neighbor in
2063
	 <m/dead count/*<m/hello/ seconds, it will consider the neighbor down.
2064

    
2065
	<tag>dead <M>num</M></tag>
2066
	 When the router does not receive any messages from a neighbor in
2067
	 <m/dead/ seconds, it will consider the neighbor down. If both directives
2068
	 <m/dead count/ and <m/dead/ are used, <m/dead/ has precendence.
2069

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

    
2075
	<tag>type broadcast|bcast</tag>
2076
	 BIRD detects a type of a connected network automatically, but
2077
	 sometimes it's convenient to force use of a different type
2078
	 manually. On broadcast networks (like ethernet), flooding
2079
	 and Hello messages are sent using multicasts (a single packet
2080
	 for all the neighbors). A designated router is elected and it
2081
	 is responsible for synchronizing the link-state databases and
2082
	 originating network LSAs. This network type cannot be used on
2083
	 physically NBMA networks and on unnumbered networks (networks
2084
	 without proper IP prefix).
2085

    
2086
	<tag>type pointopoint|ptp</tag>
2087
	 Point-to-point networks connect just 2 routers together. No
2088
	 election is performed and no network LSA is originated, which
2089
	 makes it simpler and faster to establish. This network type
2090
	 is useful not only for physically PtP ifaces (like PPP or
2091
	 tunnels), but also for broadcast networks used as PtP links.
2092
	 This network type cannot be used on physically NBMA networks.
2093

    
2094
	<tag>type nonbroadcast|nbma</tag>
2095
	 On NBMA networks, the packets are sent to each neighbor
2096
	 separately because of lack of multicast capabilities.
2097
	 Like on broadcast networks, a designated router is elected,
2098
	 which plays a central role in propagation of LSAs.
2099
	 This network type cannot be used on unnumbered networks.
2100

    
2101
	<tag>type pointomultipoint|ptmp</tag>
2102
	 This is another network type designed to handle NBMA
2103
	 networks. In this case the NBMA network is treated as a
2104
	 collection of PtP links. This is useful if not every pair of
2105
	 routers on the NBMA network has direct communication, or if
2106
	 the NBMA network is used as an (possibly unnumbered) PtP
2107
	 link.
2108

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

    
2113
	<tag>real broadcast <m/switch/</tag>
2114
	 In <cf/type broadcast/ or <cf/type ptp/ network
2115
	 configuration, OSPF packets are sent as IP multicast
2116
	 packets. This option changes the behavior to using
2117
	 old-fashioned IP broadcast packets. This may be useful as a
2118
	 workaround if IP multicast for some reason does not work or
2119
	 does not work reliably. This is a non-standard option and
2120
	 probably is not interoperable with other OSPF
2121
	 implementations. Default value is no.
2122

    
2123
	<tag>check link <M>switch</M></tag>
2124
	 If set, a hardware link state (reported by OS) is taken into
2125
	 consideration. When a link disappears (e.g. an ethernet cable is
2126
	 unplugged), neighbors are immediately considered unreachable
2127
	 and only the address of the iface (instead of whole network
2128
	 prefix) is propagated. It is possible that some hardware
2129
	 drivers or platforms do not implement this feature. Default value is no.
2130

    
2131
	<tag>ecmp weight <M>num</M></tag>
2132
	 When ECMP (multipath) routes are allowed, this value specifies
2133
	 a relative weight used for nexthops going through the iface.
2134
	 Allowed values are 1-256. Default value is 1.
2135

    
2136
	<tag>authentication none</tag>
2137
	 No passwords are sent in OSPF packets. This is the default value.
2138

    
2139
	<tag>authentication simple</tag>
2140
	 Every packet carries 8 bytes of password. Received packets
2141
	 lacking this password are ignored. This authentication mechanism is
2142
	 very weak.
2143

    
2144
	<tag>authentication cryptographic</tag>
2145
	 16-byte long MD5 digest is appended to every packet. For the digest
2146
         generation 16-byte long passwords are used. Those passwords are 
2147
         not sent via network, so this mechanism is quite secure.
2148
         Packets can still be read by an attacker.
2149

    
2150
	<tag>password "<M>text</M>"</tag>
2151
	 An 8-byte or 16-byte password used for authentication.
2152
	 See <ref id="dsc-pass" name="password"> common option for detailed description.
2153

    
2154
	<tag>neighbors { <m/set/ } </tag>
2155
	 A set of neighbors to which Hello messages on NBMA or PtMP
2156
	 networks are to be sent. For NBMA networks, some of them
2157
	 could be marked as eligible.
2158

    
2159
</descrip>
2160

    
2161
<sect1>Attributes
2162

    
2163
<p>OSPF defines four route attributes. Each internal route has a <cf/metric/.
2164
Metric is ranging from 1 to infinity (65535).
2165
External routes use <cf/metric type 1/ or <cf/metric type 2/.
2166
A <cf/metric of type 1/ is comparable with internal <cf/metric/, a
2167
<cf/metric of type 2/ is always longer
2168
than any <cf/metric of type 1/ or any <cf/internal metric/.
2169
<cf/Internal metric/ or <cf/metric of type 1/ is stored in attribute
2170
<cf/ospf_metric1/, <cf/metric type 2/ is stored in attribute <cf/ospf_metric2/.
2171
If you specify both metrics only metric1 is used.
2172

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

    
2180
<sect1>Example
2181

    
2182
<p>
2183

    
2184
<code>
2185
protocol ospf MyOSPF {
2186
        rfc1583compat yes;
2187
        tick 2;
2188
	export filter {
2189
		if source = RTS_BGP then {
2190
			ospf_metric1 = 100;
2191
			accept;
2192
		}
2193
		reject;
2194
	};
2195
	area 0.0.0.0 {
2196
		interface "eth*" {
2197
			cost 11;
2198
			hello 15;
2199
			priority 100;
2200
			retransmit 7;
2201
			authentication simple;
2202
			password "aaa";
2203
		};
2204
		interface "ppp*" {
2205
			cost 100;
2206
			authentication cryptographic;
2207
			password "abc" {
2208
				id 1;
2209
				generate to "22-04-2003 11:00:06";
2210
				accept from "17-01-2001 12:01:05";
2211
			};
2212
			password "def" {
2213
				id 2;
2214
				generate to "22-07-2005 17:03:21";
2215
				accept from "22-02-2001 11:34:06";
2216
			};
2217
		};
2218
		interface "arc0" {
2219
			cost 10;
2220
			stub yes;
2221
		};
2222
		interface "arc1";
2223
	};
2224
	area 120 {
2225
		stub yes;
2226
		networks {
2227
			172.16.1.0/24;
2228
			172.16.2.0/24 hidden;
2229
		}
2230
		interface "-arc0" , "arc*" {
2231
			type nonbroadcast;
2232
			authentication none;
2233
			strict nonbroadcast yes;
2234
			wait 120;
2235
			poll 40;
2236
			dead count 8;
2237
			neighbors {
2238
				192.168.120.1 eligible;
2239
				192.168.120.2;
2240
				192.168.120.10;
2241
			};
2242
		};
2243
	};
2244
}
2245
</code>
2246

    
2247
<sect>Pipe
2248

    
2249
<sect1>Introduction
2250

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

    
2258
<p>The Pipe protocol may work in the transparent mode mode or in the opaque mode.
2259
In the transparent mode, the Pipe protocol retransmits all routes from
2260
one table to the other table, retaining their original source and
2261
attributes.  If import and export filters are set to accept, then both
2262
tables would have the same content. The transparent mode is the default mode.
2263

    
2264
<p>In the opaque mode, the Pipe protocol retransmits optimal route
2265
from one table to the other table in a similar way like other
2266
protocols send and receive routes. Retransmitted route will have the
2267
source set to the Pipe protocol, which may limit access to protocol
2268
specific route attributes. This mode is mainly for compatibility, it
2269
is not suggested for new configs. The mode can be changed by
2270
<tt/mode/ option.
2271

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

    
2283
<sect1>Configuration
2284

    
2285
<p><descrip>
2286
	<tag>peer table <m/table/</tag> Defines secondary routing table to connect to. The
2287
	primary one is selected by the <cf/table/ keyword.
2288

    
2289
	<tag>mode opaque|transparent</tag> Specifies the mode for the pipe to work in. Default is opaque.
2290
</descrip>
2291

    
2292
<sect1>Attributes
2293

    
2294
<p>The Pipe protocol doesn't define any route attributes.
2295

    
2296
<sect1>Example
2297

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

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

    
2312
<code>
2313
table as1;				# Define the tables
2314
table as2;
2315

    
2316
protocol kernel kern1 {			# Synchronize them with the kernel
2317
	table as1;
2318
	kernel table 1;
2319
}
2320

    
2321
protocol kernel kern2 {
2322
	table as2;
2323
	kernel table 2;
2324
}
2325

    
2326
protocol bgp bgp1 {			# The outside connections
2327
	table as1;
2328
	local as 1;
2329
	neighbor 192.168.0.1 as 1001;
2330
	export all;
2331
	import all;
2332
}
2333

    
2334
protocol bgp bgp2 {
2335
	table as2;
2336
	local as 2;
2337
	neighbor 10.0.0.1 as 1002;
2338
	export all;
2339
	import all;
2340
}
2341

    
2342
protocol pipe {				# The Pipe
2343
	table as1;
2344
	peer table as2;
2345
	export filter {
2346
		if net ~ [ 1.0.0.0/8+] then {	# Only AS1 networks
2347
			if preference>10 then preference = preference-10;
2348
			if source=RTS_BGP then bgp_path.prepend(1);
2349
			accept;
2350
		}
2351
		reject;
2352
	};
2353
	import filter {
2354
		if net ~ [ 2.0.0.0/8+] then {	# Only AS2 networks
2355
			if preference>10 then preference = preference-10;
2356
			if source=RTS_BGP then bgp_path.prepend(2);
2357
			accept;
2358
		}
2359
		reject;
2360
	};
2361
}
2362
</code>
2363

    
2364
<sect>RAdv
2365

    
2366
<sect1>Introduction
2367

    
2368
<p>The RAdv protocol is an implementation of Router Advertisements,
2369
which are used in the IPv6 stateless autoconfiguration. IPv6 routers
2370
send (in irregular time intervals or as an answer to a request)
2371
advertisement packets to connected networks. These packets contain
2372
basic information about a local network (e.g. a list of network
2373
prefixes), which allows network hosts to autoconfigure network
2374
addresses and choose a default route. BIRD implements router behavior
2375
as defined in
2376
RFC 4861<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc4861.txt">
2377
and also the DNS extensions from
2378
RFC 6106<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc6106.txt">.
2379

    
2380
<sect1>Configuration
2381

    
2382
<p>There are several classes of definitions in RAdv configuration --
2383
interface definitions, prefix definitions and DNS definitions:
2384

    
2385
<descrip>
2386
	<tag>interface <m/pattern [, ...]/  { <m/options/ }</tag>
2387
	Interface definitions specify a set of interfaces on which the
2388
	protocol is activated and contain interface specific options.
2389
	See <ref id="dsc-iface" name="interface"> common options for
2390
	detailed description.
2391

    
2392
	<tag>prefix <m/prefix/ { <m/options/ }</tag>
2393
	Prefix definitions allow to modify a list of advertised
2394
	prefixes. By default, the advertised prefixes are the same as
2395
	the network prefixes assigned to the interface. For each
2396
	network prefix, the matching prefix definition is found and
2397
	its options are used. If no matching prefix definition is
2398
	found, the prefix is used with default options.
2399

    
2400
	Prefix definitions can be either global or interface-specific.
2401
	The second ones are part of interface options. The prefix
2402
	definition matching is done in the first-match style, when
2403
	interface-specific definitions are processed before global
2404
	definitions. As expected, the prefix definition is matching if
2405
	the network prefix is a subnet of the prefix in prefix
2406
	definition.
2407

    
2408
	<tag>rdnss { <m/options/ }</tag>
2409
	RDNSS definitions allow to specify a list of advertised
2410
	recursive DNS servers together with their options. As options
2411
	are seldom necessary, there is also a short variant <cf>rdnss
2412
	<m/address/</cf> that just specifies one DNS server. Multiple
2413
	definitions are cumulative. RDNSS definitions may also be
2414
	interface-specific when used inside interface options. By
2415
	default, interface uses both global and interface-specific
2416
	options, but that can be changed by <cf/rdnss local/ option.
2417

    
2418
	<tag>dnssl { <m/options/ }</tag>
2419
	DNSSL definitions allow to specify a list of advertised DNS
2420
	search domains together with their options. Like <cf/rdnss/
2421
	above, multiple definitions are cumulative, they can be used
2422
	also as interface-specific options and there is a short
2423
	variant <cf>dnssl <m/domain/</cf> that just specifies one DNS
2424
        search domain.
2425
</descrip>
2426

    
2427
<p>Interface specific options:
2428

    
2429
<descrip>
2430
	<tag>max ra interval <m/expr/</tag>
2431
	Unsolicited router advertisements are sent in irregular time
2432
	intervals. This option specifies the maximum length of these
2433
	intervals, in seconds. Valid values are 4-1800. Default: 600
2434

    
2435
	<tag>min ra interval <m/expr/</tag>
2436
	This option specifies the minimum length of that intervals, in
2437
	seconds. Must be at least 3 and at most 3/4 * <cf/max ra interval/.
2438
	Default: about 1/3 * <cf/max ra interval/.
2439

    
2440
	<tag>min delay <m/expr/</tag>
2441
	The minimum delay between two consecutive router advertisements,
2442
	in seconds. Default: 3
2443

    
2444
	<tag>managed <m/switch/</tag>
2445
	This option specifies whether hosts should use DHCPv6 for
2446
	IP address configuration. Default: no
2447

    
2448
	<tag>other config <m/switch/</tag>
2449
	This option specifies whether hosts should use DHCPv6 to
2450
	receive other configuration information. Default: no
2451

    
2452
	<tag>link mtu <m/expr/</tag>
2453
	This option specifies which value of MTU should be used by
2454
	hosts. 0 means unspecified. Default: 0
2455

    
2456
	<tag>reachable time <m/expr/</tag>
2457
	This option specifies the time (in milliseconds) how long
2458
	hosts should assume a neighbor is reachable (from the last
2459
	confirmation). Maximum is 3600000, 0 means unspecified.
2460
	Default 0.
2461

    
2462
	<tag>retrans timer <m/expr/</tag>
2463
	This option specifies the time (in milliseconds) how long
2464
	hosts should wait before retransmitting Neighbor Solicitation
2465
	messages. 0 means unspecified. Default 0.
2466

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

    
2471
	<tag>default lifetime <m/expr/</tag>
2472
	This option specifies the time (in seconds) how long (after
2473
	the receipt of RA) hosts may use the router as a default
2474
	router. 0 means do not use as a default router. Default: 3 *
2475
	<cf/max ra interval/.
2476

    
2477
	<tag>rdnss local <m/switch/</tag>
2478
	Use only local (interface-specific) RDNSS definitions for this
2479
	interface. Otherwise, both global and local definitions are
2480
	used. Could also be used to disable RDNSS for given interface
2481
	if no local definitons are specified. Default: no.
2482

    
2483
	<tag>dnssl local <m/switch/</tag>
2484
	Use only local DNSSL definitions for this interface. See
2485
	<cf/rdnss local/ option above. Default: no.
2486
</descrip>
2487

    
2488

    
2489
<p>Prefix specific options:
2490

    
2491
<descrip>
2492
	<tag>onlink <m/switch/</tag>
2493
	This option specifies whether hosts may use the advertised
2494
	prefix for onlink determination. Default: yes
2495

    
2496
	<tag>autonomous <m/switch/</tag>
2497
	This option specifies whether hosts may use the advertised
2498
	prefix for stateless autoconfiguration. Default: yes
2499

    
2500
	<tag>valid lifetime <m/expr/</tag>
2501
	This option specifies the time (in seconds) how long (after
2502
	the receipt of RA) the prefix information is valid, i.e.,
2503
	autoconfigured IP addresses can be assigned and hosts with
2504
	that IP addresses are considered directly reachable. 0 means
2505
	the prefix is no longer valid. Default: 86400 (1 day)
2506

    
2507
	<tag>preferred lifetime <m/expr/</tag>
2508
	This option specifies the time (in seconds) how long (after
2509
	the receipt of RA) IP addresses generated from the prefix
2510
	using stateless autoconfiguration remain preferred. Default:
2511
	14400 (4 hours)
2512
</descrip>
2513

    
2514

    
2515
<p>RDNSS specific options:
2516

    
2517
<descrip>
2518
	<tag>ns <m/address/</tag>
2519
	This option specifies one recursive DNS server. Can be used
2520
	multiple times for multiple servers. It is mandatory to have
2521
	at least one <cf/ns/ option in <cf/rdnss/ definition.
2522

    
2523
	<tag>lifetime [mult] <m/expr/</tag>
2524
	This option specifies the time how long the RDNSS information
2525
        may be used by clients after the receipt of RA. It is
2526
        expressed either in seconds or (when <cf/mult/ is used) in
2527
        multiples of <cf/max ra interval/. Note that RDNSS information
2528
        is also invalidated when <cf/default lifetime/ expires. 0
2529
        means these addresses are no longer valid DNS servers.
2530
	Default: 3 * <cf/max ra interval/.
2531
</descrip>
2532

    
2533

    
2534
<p>DNSSL specific options:
2535

    
2536
<descrip>
2537
	<tag>domain <m/address/</tag>
2538
	This option specifies one DNS search domain. Can be used
2539
	multiple times for multiple domains. It is mandatory to have
2540
	at least one <cf/domain/ option in <cf/dnssl/ definition.
2541

    
2542
	<tag>lifetime [mult] <m/expr/</tag>
2543
	This option specifies the time how long the DNSSL information
2544
        may be used by clients after the receipt of RA. Details are
2545
	the same as for RDNSS <cf/lifetime/ option above.
2546
	Default: 3 * <cf/max ra interval/.
2547
</descrip>
2548

    
2549

    
2550
<sect1>Example
2551

    
2552
<p><code>
2553
protocol radv {
2554
	interface "eth2" {
2555
		max ra interval 5;	# Fast failover with more routers
2556
		managed yes;		# Using DHCPv6 on eth2
2557
		prefix ::/0 {
2558
			autonomous off;	# So do not autoconfigure any IP
2559
		};
2560
	};
2561

    
2562
	interface "eth*";		# No need for any other options
2563

    
2564
	prefix 2001:0DB8:1234::/48 {
2565
		preferred lifetime 0;	# Deprecated address range
2566
	};
2567

    
2568
	prefix 2001:0DB8:2000::/48 {
2569
		autonomous off;		# Do not autoconfigure
2570
	};
2571

    
2572
	rdnss 2001:0DB8:1234::10;	# Short form of RDNSS
2573

    
2574
	rdnss {
2575
		lifetime mult 10;
2576
		ns 2001:0DB8:1234::11;
2577
		ns 2001:0DB8:1234::12;
2578
	};
2579

    
2580
	dnssl {
2581
		lifetime 3600;
2582
		domain "abc.com";
2583
		domain "xyz.com";
2584
	};
2585
}
2586
</code>
2587

    
2588
<sect>RIP
2589

    
2590
<sect1>Introduction
2591

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

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

    
2609
<sect1>Configuration
2610

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

    
2613
<descrip>
2614
	<tag/authentication none|plaintext|md5/ selects authentication method to be used. <cf/none/ means that
2615
	  packets are not authenticated at all, <cf/plaintext/ means that a plaintext password is embedded
2616
	  into each packet, and <cf/md5/ means that packets are authenticated using a MD5 cryptographic
2617
	  hash. If you set authentication to not-none, it is a good idea to add <cf>password</cf>
2618
	  section. Default: none.
2619

    
2620
	<tag>honor always|neighbor|never </tag>specifies when should requests for dumping routing table
2621
	  be honored. (Always, when sent from a  host on a directly connected
2622
	  network or never.) Routing table updates are honored only from
2623
	  neighbors, that is not configurable. Default: never.
2624
</descrip>
2625

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

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

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

    
2643
	<tag>infinity <M>number</M></tag>
2644
	  selects the value of infinity, default is 16. Bigger values will make protocol convergence
2645
	  even slower.
2646

    
2647
	<tag>period <M>number</M>
2648
	  </tag>specifies the number of seconds between periodic updates. Default is 30 seconds. A lower
2649
	  number will mean faster convergence but bigger network
2650
	  load. Do not use values lower than 10.
2651

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

    
2655
	<tag>garbage time <M>number</M>
2656
	  </tag>specifies how old route has to be to be discarded. Default is 10*<cf/period/.
2657
</descrip>
2658

    
2659
<sect1>Attributes
2660

    
2661
<p>RIP defines two route attributes:
2662

    
2663
<descrip>
2664
	<tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/).
2665
	When routes from different RIP instances are available and all of them have the same
2666
	preference, BIRD prefers the route with lowest <cf/rip_metric/.
2667
	When importing a non-RIP route, the metric defaults to 5.
2668

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

    
2674
<sect1>Example
2675

    
2676
<p><code>
2677
protocol rip MyRIP_test {
2678
        debug all;
2679
        port 1520;
2680
        period 10;
2681
        garbage time 60;
2682
        interface "eth0" { metric 3; mode multicast; };
2683
	interface "eth*" { metric 2; mode broadcast; };
2684
        honor neighbor;
2685
        authentication none;
2686
        import filter { print "importing"; accept; };
2687
        export filter { print "exporting"; accept; };
2688
}
2689
</code>
2690

    
2691
<sect>Static
2692

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

    
2701
<p>There are five types of static routes: `classical' routes telling
2702
to forward packets to a neighboring router, multipath routes
2703
specifying several (possibly weighted) neighboring routers, device
2704
routes specifying forwarding to hosts on a directly connected network,
2705
recursive routes computing their nexthops by doing route table lookups
2706
for a given IP and special routes (sink, blackhole etc.) which specify
2707
a special action to be done instead of forwarding the packet.
2708

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

    
2714
<p>The Static protocol does not have many configuration options. The
2715
definition of the protocol contains mainly a list of static routes:
2716

    
2717
<descrip>
2718
	<tag>route <m/prefix/ via <m/ip/</tag> Static route through
2719
	a neighboring router.
2720
	<tag>route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [via ...]</tag>
2721
	Static multipath route. Contains several nexthops (gateways), possibly
2722
 	with their weights.
2723
	<tag>route <m/prefix/ via <m/"interface"/</tag> Static device
2724
	route through an interface to hosts on a directly connected network.
2725
	<tag>route <m/prefix/ recursive <m/ip/</tag> Static recursive route,
2726
	its nexthop depends on a route table lookup for given IP address.
2727
	<tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes
2728
	specifying to drop the packet, return it as unreachable or return
2729
	it as administratively prohibited.
2730

    
2731
	<tag>check link <m/switch/</tag>
2732
	If set, hardware link states of network interfaces are taken
2733
	into consideration.  When link disappears (e.g. ethernet cable
2734
	is unplugged), static routes directing to that interface are
2735
	removed. It is possible that some hardware drivers or
2736
	platforms do not implement this feature. Default: off.
2737

    
2738
	<tag>igp table <m/name/</tag> Specifies a table that is used
2739
	for route table lookups of recursive routes. Default: the
2740
	same table as the protocol is connected to.
2741
</descrip>
2742

    
2743
<p>Static routes have no specific attributes.
2744

    
2745
<p>Example static config might look like this:
2746

    
2747
<p><code>
2748
protocol static {
2749
	table testable;			 # Connect to a non-default routing table
2750
	route 0.0.0.0/0 via 198.51.100.130; # Default route
2751
	route 10.0.0.0/8 multipath	 # Multipath route
2752
		via 198.51.100.10 weight 2
2753
		via 198.51.100.20
2754
		via 192.0.2.1;
2755
	route 203.0.113.0/24 reject;	 # Sink route
2756
	route 10.2.0.0/24 via "arc0";	 # Secondary network
2757
}
2758
</code>
2759

    
2760
<chapt>Conclusions
2761

    
2762
<sect>Future work
2763

    
2764
<p>Although BIRD supports all the commonly used routing protocols,
2765
there are still some features which would surely deserve to be
2766
implemented in future versions of BIRD:
2767

    
2768
<itemize>
2769
<item>Opaque LSA's
2770
<item>Route aggregation and flap dampening
2771
<item>Multipath routes
2772
<item>Multicast routing protocols
2773
<item>Ports to other systems
2774
</itemize>
2775

    
2776
<sect>Getting more help
2777

    
2778
<p>If you use BIRD, you're welcome to join the bird-users mailing list
2779
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
2780
where you can share your experiences with the other users and consult
2781
your problems with the authors. To subscribe to the list, just send a
2782
<tt/subscribe bird-users/ command in a body of a mail to
2783
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
2784
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
2785

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

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

    
2796
<p><it/Good luck!/
2797

    
2798
</book>
2799

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