Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 62e64905

History | View | Annotate | Download (191 KB)

1 04a22949 Martin Mares
<!doctype birddoc system>
2 d37f899b Pavel Machek
3
<!--
4 d150c637 Pavel Machek
	BIRD documentation
5 d37f899b Pavel Machek
6 dad92c30 Ondrej Zajicek
This documentation can have 4 forms: sgml (this is master copy), html, ASCII
7
text and dvi/postscript (generated from sgml using sgmltools). You should always
8
edit master copy.
9 02357f96 Pavel Machek
10 dad92c30 Ondrej Zajicek
This is a slightly modified linuxdoc dtd. Anything in <descrip> tags is
11
considered definition of configuration primitives, <cf> is fragment of
12
configuration within normal text, <m> is "meta" information within fragment of
13
configuration - something in config which is not keyword.
14 d37f899b Pavel Machek
15 dad92c30 Ondrej Zajicek
    (set-fill-column 80)
16 d37f899b Pavel Machek
17
    Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
18
19
 -->
20
21 371adba6 Martin Mares
<book>
22 d37f899b Pavel Machek
23 aa185265 Martin Mares
<title>BIRD User's Guide
24 d37f899b Pavel Machek
<author>
25 aa185265 Martin Mares
Ondrej Filip <it/&lt;feela@network.cz&gt;/,
26
Pavel Machek <it/&lt;pavel@ucw.cz&gt;/,
27 5516a66d Ondrej Filip
Martin Mares <it/&lt;mj@ucw.cz&gt;/,
28
Ondrej Zajicek <it/&lt;santiago@crfreenet.org&gt;/
29 aa185265 Martin Mares
</author>
30 d37f899b Pavel Machek
31
<abstract>
32 aa185265 Martin Mares
This document contains user documentation for the BIRD Internet Routing Daemon project.
33 d37f899b Pavel Machek
</abstract>
34
35
<!-- Table of contents -->
36
<toc>
37
38
<!-- Begin the document -->
39
40 dad92c30 Ondrej Zajicek
41 371adba6 Martin Mares
<chapt>Introduction
42 b9864aa8 Pavel Tvrdik
<label id="intro">
43 d37f899b Pavel Machek
44 371adba6 Martin Mares
<sect>What is BIRD
45 b9864aa8 Pavel Tvrdik
<label id="what-is-bird">
46 d37f899b Pavel Machek
47 b9864aa8 Pavel Tvrdik
<p>The name `BIRD' is actually an acronym standing for `BIRD Internet Routing
48 dad92c30 Ondrej Zajicek
Daemon'. Let's take a closer look at the meaning of the name:
49
50
<p><em/BIRD/: Well, we think we have already explained that. It's an acronym
51
standing for `BIRD Internet Routing Daemon', you remember, don't you? :-)
52
53
<p><em/Internet Routing/: It's a program (well, a daemon, as you are going to
54
discover in a moment) which works as a dynamic router in an Internet type
55
network (that is, in a network running either the IPv4 or the IPv6 protocol).
56
Routers are devices which forward packets between interconnected networks in
57
order to allow hosts not connected directly to the same local area network to
58
communicate with each other. They also communicate with the other routers in the
59
Internet to discover the topology of the network which allows them to find
60
optimal (in terms of some metric) rules for forwarding of packets (which are
61
called routing tables) and to adapt themselves to the changing conditions such
62
as outages of network links, building of new connections and so on. Most of
63
these routers are costly dedicated devices running obscure firmware which is
64
hard to configure and not open to any changes (on the other hand, their special
65
hardware design allows them to keep up with lots of high-speed network
66
interfaces, better than general-purpose computer does). Fortunately, most
67
operating systems of the UNIX family allow an ordinary computer to act as a
68
router and forward packets belonging to the other hosts, but only according to a
69
statically configured table.
70
71
<p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program
72
running on background which does the dynamic part of Internet routing, that is
73
it communicates with the other routers, calculates routing tables and sends them
74
to the OS kernel which does the actual packet forwarding. There already exist
75
other such routing daemons: routed (RIP only), GateD (non-free),
76 7935b9d2 Pavel Tvrdik
<HTMLURL URL="http://www.zebra.org" name="Zebra"> and
77
<HTMLURL URL="http://sourceforge.net/projects/mrt" name="MRTD">,
78 dad92c30 Ondrej Zajicek
but their capabilities are limited and they are relatively hard to configure
79
and maintain.
80 897cd7aa Martin Mares
81
<p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
82 dad92c30 Ondrej Zajicek
to support all the routing technology used in the today's Internet or planned to
83
be used in near future and to have a clean extensible architecture allowing new
84
routing protocols to be incorporated easily. Among other features, BIRD
85
supports:
86 897cd7aa Martin Mares
87
<itemize>
88
	<item>both IPv4 and IPv6 protocols
89
	<item>multiple routing tables
90
	<item>the Border Gateway Protocol (BGPv4)
91 96264d4d Pavel Machek
	<item>the Routing Information Protocol (RIPv2)
92 0c75411b Ondrej Zajicek
	<item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
93 6bcef225 Ondrej Zajicek
	<item>the Router Advertisements for IPv6 hosts
94 dad92c30 Ondrej Zajicek
	<item>a virtual protocol for exchange of routes between different
95
		routing tables on a single host
96 897cd7aa Martin Mares
	<item>a command-line interface allowing on-line control and inspection
97
		of status of the daemon
98 dad92c30 Ondrej Zajicek
	<item>soft reconfiguration (no need to use complex online commands to
99
		change the configuration, just edit the configuration file and
100
		notify BIRD to re-read it and it will smoothly switch itself to
101
		the new configuration, not disturbing routing protocols unless
102
		they are affected by the configuration changes)
103 02357f96 Pavel Machek
	<item>a powerful language for route filtering
104 897cd7aa Martin Mares
</itemize>
105
106 dad92c30 Ondrej Zajicek
<p>BIRD has been developed at the Faculty of Math and Physics, Charles
107
University, Prague, Czech Republic as a student project. It can be freely
108
distributed under the terms of the GNU General Public License.
109
110
<p>BIRD has been designed to work on all UNIX-like systems. It has been
111
developed and tested under Linux 2.0 to 2.6, and then ported to FreeBSD, NetBSD
112
and OpenBSD, porting to other systems (even non-UNIX ones) should be relatively
113
easy due to its highly modular architecture.
114 897cd7aa Martin Mares
115 dad92c30 Ondrej Zajicek
<p>BIRD supports either IPv4 or IPv6 protocol, but have to be compiled separately
116
for each one. Therefore, a dualstack router would run two instances of BIRD (one
117
for IPv4 and one for IPv6), with completely separate setups (configuration
118
files, tools ...).
119 5adc02a6 Ondrej Zajicek
120 d37f899b Pavel Machek
121 371adba6 Martin Mares
<sect>Installing BIRD
122 b9864aa8 Pavel Tvrdik
<label id="install">
123 440439e3 Pavel Machek
124 dad92c30 Ondrej Zajicek
<p>On a recent UNIX system with GNU development tools (GCC, binutils, m4, make)
125
and Perl, installing BIRD should be as easy as:
126 440439e3 Pavel Machek
127
<code>
128 dad92c30 Ondrej Zajicek
	./configure
129
	make
130
	make install
131
	vi /usr/local/etc/bird.conf
132 c184d9d0 Pavel Machek
	bird
133 440439e3 Pavel Machek
</code>
134
135 02357f96 Pavel Machek
<p>You can use <tt>./configure --help</tt> to get a list of configure
136 dad92c30 Ondrej Zajicek
options. The most important ones are: <tt/--enable-ipv6/ which enables building
137
of an IPv6 version of BIRD, <tt/--with-protocols=/ to produce a slightly smaller
138
BIRD executable by configuring out routing protocols you don't use, and
139
<tt/--prefix=/ to install BIRD to a place different from <file>/usr/local</file>.
140
141 b093c328 Pavel Machek
142 02357f96 Pavel Machek
<sect>Running BIRD
143 b9864aa8 Pavel Tvrdik
<label id="argv">
144 36032ded Pavel Machek
145 c184d9d0 Pavel Machek
<p>You can pass several command-line options to bird:
146 d26524fa Pavel Machek
147 c184d9d0 Pavel Machek
<descrip>
148 b9864aa8 Pavel Tvrdik
	<tag><label id="argv-config">-c <m/config name/</tag>
149 66701947 Martin Mares
	use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
150 c184d9d0 Pavel Machek
151 b9864aa8 Pavel Tvrdik
	<tag><label id="argv-debug">-d</tag>
152 02357f96 Pavel Machek
	enable debug messages and run bird in foreground.
153 c184d9d0 Pavel Machek
154 b9864aa8 Pavel Tvrdik
	<tag><label id="argv-log-file">-D <m/filename of debug log/</tag>
155 a4644ed6 Ondrej Zajicek
	log debugging information to given file instead of stderr.
156
157 f5952c73 Pavel Tvrdik
	<tag><label id="argv-foreground">-f</tag>
158
	run bird in foreground.
159 e8b89a61 Ondrej Zajicek
160 b9864aa8 Pavel Tvrdik
	<tag><label id="argv-group">-g <m/group/</tag>
161 e8b89a61 Ondrej Zajicek
	use that group ID, see the next section for details.
162 1cd198cf Ondrej Filip
163 f5952c73 Pavel Tvrdik
	<tag><label id="argv-help">-h, --help</tag>
164
	display command-line options to bird.
165 6eda3f13 Ondrej Zajicek
166 b9864aa8 Pavel Tvrdik
	<tag><label id="argv-local">-l</tag>
167 f2ae2bad Ondrej Zajicek (work)
	look for a configuration file and a communication socket in the current
168 43fc6bb0 Ondrej Zajicek (work)
	working directory instead of in default system locations. However, paths
169 f2ae2bad Ondrej Zajicek (work)
	specified by options <cf/-c/, <cf/-s/ have higher priority.
170
171 f5952c73 Pavel Tvrdik
	<tag><label id="argv-parse">-p</tag>
172
	just parse the config file and exit. Return value is zero if the config
173
	file is valid, nonzero if there are some errors.
174
175
	<tag><label id="argv-pid">-P <m/name of PID file/</tag>
176
	create a PID file with given filename.
177
178 b9864aa8 Pavel Tvrdik
	<tag><label id="argv-recovery">-R</tag>
179 6eda3f13 Ondrej Zajicek
	apply graceful restart recovery after start.
180 22558357 Pavel Tvrdik
181 f5952c73 Pavel Tvrdik
	<tag><label id="argv-socket">-s <m/name of communication socket/</tag>
182
	use given filename for a socket for communications with the client,
183
	default is <it/prefix/<file>/var/run/bird.ctl</file>.
184
185
	<tag><label id="argv-user">-u <m/user/</tag>
186
	drop privileges and use that user ID, see the next section for details.
187
188 22558357 Pavel Tvrdik
	<tag><label id="argv-version">--version</tag>
189
	display bird version.
190 c184d9d0 Pavel Machek
</descrip>
191 d26524fa Pavel Machek
192 02357f96 Pavel Machek
<p>BIRD writes messages about its work to log files or syslog (according to config).
193
194 dad92c30 Ondrej Zajicek
195 e8b89a61 Ondrej Zajicek
<sect>Privileges
196 b9864aa8 Pavel Tvrdik
<label id="privileges">
197 e8b89a61 Ondrej Zajicek
198 dad92c30 Ondrej Zajicek
<p>BIRD, as a routing daemon, uses several privileged operations (like setting
199
routing table and using raw sockets). Traditionally, BIRD is executed and runs
200
with root privileges, which may be prone to security problems. The recommended
201
way is to use a privilege restriction (options <cf/-u/, <cf/-g/). In that case
202
BIRD is executed with root privileges, but it changes its user and group ID to
203
an unprivileged ones, while using Linux capabilities to retain just required
204
privileges (capabilities CAP_NET_*). Note that the control socket is created
205
before the privileges are dropped, but the config file is read after that. The
206
privilege restriction is not implemented in BSD port of BIRD.
207
208 fff7498d Pavel Tvrdik
<p>An unprivileged user (as an argument to <cf/-u/ options) may be the user
209 dad92c30 Ondrej Zajicek
<cf/nobody/, but it is suggested to use a new dedicated user account (like
210
<cf/bird/). The similar considerations apply for the group option, but there is
211
one more condition -- the users in the same group can use <file/birdc/ to
212
control BIRD.
213
214
<p>Finally, there is a possibility to use external tools to run BIRD in an
215
environment with restricted privileges. This may need some configuration, but it
216
is generally easy -- BIRD needs just the standard library, privileges to read
217
the config file and create the control socket and the CAP_NET_* capabilities.
218 e8b89a61 Ondrej Zajicek
219 6eda3f13 Ondrej Zajicek
220 a852c139 Pavel Machek
<chapt>About routing tables
221 b9864aa8 Pavel Tvrdik
<label id="routing-tables">
222 a852c139 Pavel Machek
223 dad92c30 Ondrej Zajicek
<p>BIRD has one or more routing tables which may or may not be synchronized with
224
OS kernel and which may or may not be synchronized with each other (see the Pipe
225
protocol). Each routing table contains a list of known routes. Each route
226
consists of:
227 a852c139 Pavel Machek
228
<itemize>
229 dad92c30 Ondrej Zajicek
	<item>network prefix this route is for (network address and prefix
230
		length -- the number of bits forming the network part of the
231
		address; also known as a netmask)
232 96264d4d Pavel Machek
	<item>preference of this route
233
	<item>IP address of router which told us about this route
234 dad92c30 Ondrej Zajicek
	<item>IP address of router we should forward the packets to using this
235
		route
236 a852c139 Pavel Machek
	<item>other attributes common to all routes
237 dad92c30 Ondrej Zajicek
	<item>dynamic attributes defined by protocols which may or may not be
238
		present (typically protocol metrics)
239 a852c139 Pavel Machek
</itemize>
240
241 dad92c30 Ondrej Zajicek
Routing table maintains multiple entries for a network, but at most one entry
242
for one network and one protocol. The entry with the highest preference is used
243
for routing (we will call such an entry the <it/selected route/). If there are
244
more entries with the same preference and they are from the same protocol, the
245
protocol decides (typically according to metrics). If they aren't, an internal
246
ordering is used to break the tie. You can get the list of route attributes in
247
the Route attributes section.
248
249
<p>Each protocol is connected to a routing table through two filters which can
250
accept, reject and modify the routes. An <it/export/ filter checks routes passed
251
from the routing table to the protocol, an <it/import/ filter checks routes in
252
the opposite direction. When the routing table gets a route from a protocol, it
253
recalculates the selected route and broadcasts it to all protocols connected to
254
the table. The protocols typically send the update to other routers in the
255
network. Note that although most protocols are interested in receiving just
256
selected routes, some protocols (e.g. the <cf/Pipe/ protocol) receive and
257
process all entries in routing tables (accepted by filters).
258
259 b9864aa8 Pavel Tvrdik
<p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected route
260 dad92c30 Ondrej Zajicek
from a list of entries for one network. But if the <cf/sorted/ option is
261
activated, these lists of entries are kept completely sorted (according to
262
preference or some protocol-dependent metric). This is needed for some features
263
of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to
264
accept not just a selected route, but the first route (in the sorted list) that
265
is accepted by filters), but it is incompatible with some other features (e.g.
266
<cf/deterministic med/ option of BGP protocol, which activates a way of choosing
267
selected route that cannot be described using comparison and ordering). Minor
268
advantage is that routes are shown sorted in <cf/show route/, minor disadvantage
269
is that it is slightly more computationally expensive.
270
271 48cf5e84 Ondrej Zajicek
272 6eda3f13 Ondrej Zajicek
<sect>Graceful restart
273 b9864aa8 Pavel Tvrdik
<label id="graceful-restart">
274 6eda3f13 Ondrej Zajicek
275
<p>When BIRD is started after restart or crash, it repopulates routing tables in
276
an uncoordinated manner, like after clean start. This may be impractical in some
277
cases, because if the forwarding plane (i.e. kernel routing tables) remains
278
intact, then its synchronization with BIRD would temporarily disrupt packet
279
forwarding until protocols converge. Graceful restart is a mechanism that could
280
help with this issue. Generally, it works by starting protocols and letting them
281
repopulate routing tables while deferring route propagation until protocols
282
acknowledge their convergence. Note that graceful restart behavior have to be
283
configured for all relevant protocols and requires protocol-specific support
284
(currently implemented for Kernel and BGP protocols), it is activated for
285
particular boot by option <cf/-R/.
286
287 a852c139 Pavel Machek
288 371adba6 Martin Mares
<chapt>Configuration
289 b9864aa8 Pavel Tvrdik
<label id="config">
290 af0b25d2 Pavel Machek
291 371adba6 Martin Mares
<sect>Introduction
292 b9864aa8 Pavel Tvrdik
<label id="config-intro">
293 d37f899b Pavel Machek
294 dad92c30 Ondrej Zajicek
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads
295
<it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option
296
is given). Configuration may be changed at user's request: if you modify the
297
config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new
298
config. Then there's the client which allows you to talk with BIRD in an
299
extensive way.
300
301
<p>In the config, everything on a line after <cf/#/ or inside <cf>/* */</cf> is
302
a comment, whitespace characters are treated as a single space. If there's a
303
variable number of options, they are grouped using the <cf/{ }/ brackets. Each
304
option is terminated by a <cf/;/. Configuration is case sensitive. There are two
305 fff7498d Pavel Tvrdik
ways how to name symbols (like protocol names, filter names, constants etc.). You
306 dad92c30 Ondrej Zajicek
can either use a simple string starting with a letter followed by any
307
combination of letters and numbers (e.g. "R123", "myfilter", "bgp5") or you can
308
enclose the name into apostrophes (<cf/'/) and than you can use any combination
309
of numbers, letters. hyphens, dots and colons (e.g. "'1:strange-name'",
310
"'-NAME-'", "'cool::name'").
311
312
<p>Here is an example of a simple config file. It enables synchronization of
313
routing tables with OS kernel, scans for new network interfaces every 10 seconds
314
and runs RIP on all network interfaces found.
315 d37f899b Pavel Machek
316 a0dd1c74 Pavel Machek
<code>
317 d37f899b Pavel Machek
protocol kernel {
318 d150c637 Pavel Machek
	persist;		# Don't remove routes on BIRD shutdown
319 d37f899b Pavel Machek
	scan time 20;		# Scan kernel routing table every 20 seconds
320
	export all;		# Default is export none
321
}
322
323
protocol device {
324
	scan time 10;		# Scan interfaces every 10 seconds
325
}
326
327
protocol rip {
328
	export all;
329
	import all;
330 f434d191 Ondrej Zajicek
	interface "*";
331 d37f899b Pavel Machek
}
332 a0dd1c74 Pavel Machek
</code>
333 d37f899b Pavel Machek
334 326e33f5 Pavel Machek
335 371adba6 Martin Mares
<sect>Global options
336 b9864aa8 Pavel Tvrdik
<label id="global-opts">
337 af0b25d2 Pavel Machek
338 a0dd1c74 Pavel Machek
<p><descrip>
339 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-include">include "<m/filename/"</tag>
340 4a5eb284 Ondrej Zajicek
	This statement causes inclusion of a new file. <m/Filename/ could also
341 0a505706 Ondrej Zajicek (work)
	be a wildcard, in that case matching files are included in alphabetic
342
	order. The maximal depth is 8. Note that this statement could be used
343
	anywhere in the config file, not just as a top-level option.
344 48ec367a Ondrej Filip
345 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
346 dad92c30 Ondrej Zajicek
	Set logging of messages having the given class (either <cf/all/ or
347 9df52a98 Pavel Tvrdik
	<cf/{ error|trace [, <m/.../] }/ etc.) into selected destination (a file specified
348 dad92c30 Ondrej Zajicek
	as a filename string, syslog with optional name argument, or the stderr
349
	output). Classes are:
350 1632f1fe Pavel Machek
	<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
351 523f020b Ondrej Zajicek
	<cf/debug/ for debugging messages,
352
	<cf/trace/ when you want to know what happens in the network,
353
	<cf/remote/ for messages about misbehavior of remote machines,
354 02357f96 Pavel Machek
	<cf/auth/ about authentication failures,
355 dad92c30 Ondrej Zajicek
	<cf/bug/ for internal BIRD bugs.
356
	You may specify more than one <cf/log/ line to establish logging to
357
	multiple destinations. Default: log everything to the system log.
358 02357f96 Pavel Machek
359 9df52a98 Pavel Tvrdik
	<tag><label id="opt-debug-protocols">debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
360 dad92c30 Ondrej Zajicek
	Set global defaults of protocol debugging options. See <cf/debug/ in the
361
	following section. Default: off.
362 5a203dac Pavel Machek
363 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-debug-commands">debug commands <m/number/</tag>
364 dad92c30 Ondrej Zajicek
	Control logging of client connections (0 for no logging, 1 for logging
365
	of connects and disconnects, 2 and higher for logging of all client
366
	commands). Default: 0.
367 249d238c Pavel Machek
368 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-debug-latency">debug latency <m/switch/</tag>
369 8bcb5fb1 Ondrej Zajicek
	Activate tracking of elapsed time for internal events. Recent events
370
	could be examined using <cf/dump events/ command. Default: off.
371
372 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-debug-latency-limit">debug latency limit <m/time/</tag>
373 8bcb5fb1 Ondrej Zajicek
	If <cf/debug latency/ is enabled, this option allows to specify a limit
374
	for elapsed time. Events exceeding the limit are logged. Default: 1 s.
375
376 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-watchdog-warn">watchdog warning <m/time/</tag>
377 8bcb5fb1 Ondrej Zajicek
	Set time limit for I/O loop cycle. If one iteration took more time to
378
	complete, a warning is logged. Default: 5 s.
379
380 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-watchdog-timeout">watchdog timeout <m/time/</tag>
381 8bcb5fb1 Ondrej Zajicek
	Set time limit for I/O loop cycle. If the limit is breached, BIRD is
382
	killed by abort signal. The timeout has effective granularity of
383
	seconds, zero means disabled. Default: disabled (0).
384
385 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag>
386 dad92c30 Ondrej Zajicek
	Set MRTdump file name. This option must be specified to allow MRTdump
387
	feature. Default: no dump file.
388 cf31112f Ondrej Zajicek
389 9df52a98 Pavel Tvrdik
	<tag><label id="opt-mrtdump-protocols">mrtdump protocols all|off|{ states|messages [, <m/.../] }</tag>
390 dad92c30 Ondrej Zajicek
	Set global defaults of MRTdump options. See <cf/mrtdump/ in the
391
	following section. Default: off.
392 cf31112f Ondrej Zajicek
393 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-filter">filter <m/name local variables/{ <m/commands/ }</tag>
394 dad92c30 Ondrej Zajicek
	Define a filter. You can learn more about filters in the following
395
	chapter.
396 326e33f5 Pavel Machek
397 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-function">function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
398 dad92c30 Ondrej Zajicek
	Define a function. You can learn more about functions in the following chapter.
399 523f020b Ondrej Zajicek
400 9df52a98 Pavel Tvrdik
	<tag><label id="opt-protocol">protocol rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
401 dad92c30 Ondrej Zajicek
	Define a protocol instance called <cf><m/name/</cf> (or with a name like
402
	"rip5" generated automatically if you don't specify any
403
	<cf><m/name/</cf>). You can learn more about configuring protocols in
404
	their own chapters. When <cf>from <m/name2/</cf> expression is used,
405
	initial protocol options are taken from protocol or template
406
	<cf><m/name2/</cf> You can run more than one instance of most protocols
407
	(like RIP or BGP). By default, no instances are configured.
408 a7f23f58 Ondrej Zajicek
409 9df52a98 Pavel Tvrdik
	<tag><label id="opt-template">template rip|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
410 dad92c30 Ondrej Zajicek
	Define a protocol template instance called <m/name/ (or with a name like
411
	"bgp1" generated automatically if you don't specify any	<m/name/).
412
	Protocol templates can be used to group common options when many
413
	similarly configured protocol instances are to be defined. Protocol
414
	instances (and other templates) can use templates by using <cf/from/
415
	expression and the name of the template. At the moment templates (and
416
	<cf/from/ expression) are not implemented for OSPF protocol.
417 249d238c Pavel Machek
418 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-define">define <m/constant/ = <m/expression/</tag>
419 dad92c30 Ondrej Zajicek
	Define a constant. You can use it later in every place you could use a
420
	value of the same type. Besides, there are some predefined numeric
421
	constants based on /etc/iproute2/rt_* files. A list of defined constants
422
	can be seen (together with other symbols) using 'show symbols' command.
423 249d238c Pavel Machek
424 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-router-id">router id <m/IPv4 address/</tag>
425
	Set BIRD's router ID. It's a world-wide unique identification of your
426 dad92c30 Ondrej Zajicek
	router, usually one of router's IPv4 addresses. Default: in IPv4
427
	version, the lowest IP address of a non-loopback interface. In IPv6
428
	version, this option is mandatory.
429 79b4e12e Ondrej Zajicek
430 9df52a98 Pavel Tvrdik
	<tag><label id="opt-router-id-from">router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../]</tag>
431 dad92c30 Ondrej Zajicek
	Set BIRD's router ID based on an IP address of an interface specified by
432
	an interface pattern. The option is applicable for IPv4 version only.
433 b9864aa8 Pavel Tvrdik
	See <ref id="proto-iface" name="interface"> section for detailed
434 d7c06285 Ondrej Zajicek
	description of interface patterns with extended clauses.
435 249d238c Pavel Machek
436 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-listen-bgp">listen bgp [address <m/address/] [port <m/port/] [dual]</tag>
437 dad92c30 Ondrej Zajicek
	This option allows to specify address and port where BGP protocol should
438
	listen. It is global option as listening socket is common to all BGP
439
	instances. Default is to listen on all addresses (0.0.0.0) and port 179.
440
	In IPv6 mode, option <cf/dual/ can be used to specify that BGP socket
441
	should accept both IPv4 and IPv6 connections (but even in that case,
442
	BIRD would accept IPv6 routes only). Such behavior was default in older
443
	versions of BIRD.
444 27579857 Ondrej Zajicek
445 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-graceful-restart">graceful restart wait <m/number/</tag>
446 6eda3f13 Ondrej Zajicek
	During graceful restart recovery, BIRD waits for convergence of routing
447
	protocols. This option allows to specify a timeout for the recovery to
448
	prevent waiting indefinitely if some protocols cannot converge. Default:
449
	240 seconds.
450
451 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-timeformat">timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
452 dad92c30 Ondrej Zajicek
	This option allows to specify a format of date/time used by BIRD. The
453
	first argument specifies for which purpose such format is used.
454
	<cf/route/ is a format used in 'show route' command output,
455
	<cf/protocol/ is used in 'show protocols' command output, <cf/base/ is
456
	used for other commands and <cf/log/ is used in a log file.
457
458
	"<m/format1/" is a format string using <it/strftime(3)/ notation (see
459
	<it/man strftime/ for details). <m/limit> and "<m/format2/" allow to
460
	specify the second format string for times in past deeper than <m/limit/
461
 	seconds. There are few shorthands: <cf/iso long/ is a ISO 8601 date/time
462
	format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F %T"/.
463
	<cf/iso short/ is a variant of ISO 8601 that uses just the time format
464
	(hh:mm:ss) for near times (up to 20 hours in the past) and the date
465
	format (YYYY-MM-DD) for far times. This is a shorthand for
466
	<cf/"%T" 72000 "%F"/.
467 c37e7851 Ondrej Zajicek
468 90eb5e7a Ondrej Zajicek
	By default, BIRD uses the <cf/iso short/ format for <cf/route/ and
469
	<cf/protocol/ times, and the <cf/iso long/ format for <cf/base/ and
470
	<cf/log/ times.
471
472 dad92c30 Ondrej Zajicek
	In pre-1.4.0 versions, BIRD used an short, ad-hoc format for <cf/route/
473
	and <cf/protocol/ times, and a <cf/iso long/ similar format (DD-MM-YYYY
474
	hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats could be set by
475
	<cf/old short/ and <cf/old long/ compatibility shorthands.
476 c37e7851 Ondrej Zajicek
477 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-table">table <m/name/ [sorted]</tag>
478 dad92c30 Ondrej Zajicek
	Create a new routing table. The default routing table is created
479
	implicitly, other routing tables have to be added by this command.
480
	Option <cf/sorted/ can be used to enable sorting of routes, see
481 b9864aa8 Pavel Tvrdik
	<ref id="dsc-table-sorted" name="sorted table"> description for details.
482 af0b25d2 Pavel Machek
483 9df52a98 Pavel Tvrdik
	<tag><label id="opt-roa-table">roa table <m/name/ [ { <m/roa table options .../ } ]</tag>
484 dad92c30 Ondrej Zajicek
	Create a new ROA (Route Origin Authorization) table. ROA tables can be
485
	used to validate route origination of BGP routes. A ROA table contains
486
	ROA entries, each consist of a network prefix, a max prefix length and
487
	an AS number. A ROA entry specifies prefixes which could be originated
488 7935b9d2 Pavel Tvrdik
	by that AS number. ROA tables could be filled with data from RPKI (<rfc
489
	id="6480">) or from public databases like Whois. ROA tables are
490
	examined by <cf/roa_check()/ operator in filters.
491 dad92c30 Ondrej Zajicek
492
	Currently, there is just one option, <cf>roa <m/prefix/ max <m/num/ as
493
	<m/num/</cf>, which can be used to populate the ROA table with static
494
	ROA entries. The option may be used multiple times. Other entries can be
495
	added dynamically by <cf/add roa/ command.
496 af582c48 Ondrej Zajicek
497 b9864aa8 Pavel Tvrdik
	<tag><label id="opt-eval">eval <m/expr/</tag>
498 f8e8fcfa Ondrej Zajicek
	Evaluates given filter expression. It is used by us for	testing of filters.
499 249d238c Pavel Machek
</descrip>
500
501 dad92c30 Ondrej Zajicek
502 371adba6 Martin Mares
<sect>Protocol options
503 b9864aa8 Pavel Tvrdik
<label id="protocol-opts">
504 bfd71178 Pavel Machek
505 dad92c30 Ondrej Zajicek
<p>For each protocol instance, you can configure a bunch of options. Some of
506
them (those described in this section) are generic, some are specific to the
507
protocol (see sections talking about the protocols).
508 7581b81b Pavel Machek
509 dad92c30 Ondrej Zajicek
<p>Several options use a <m/switch/ argument. It can be either <cf/on/,
510
<cf/yes/ or a numeric expression with a non-zero value for the option to be
511
enabled or <cf/off/, <cf/no/ or a numeric expression evaluating to zero to
512
disable it. An empty <m/switch/ is equivalent to <cf/on/ ("silence means
513
agreement").
514 7581b81b Pavel Machek
515 5a203dac Pavel Machek
<descrip>
516 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-preference">preference <m/expr/</tag>
517 dad92c30 Ondrej Zajicek
	Sets the preference of routes generated by this protocol. Default:
518
	protocol dependent.
519 5a203dac Pavel Machek
520 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-disabled">disabled <m/switch/</tag>
521 dad92c30 Ondrej Zajicek
	Disables the protocol. You can change the disable/enable status from the
522
	command line interface without needing to touch the configuration.
523
	Disabled protocols are not activated. Default: protocol is enabled.
524 5a203dac Pavel Machek
525 9df52a98 Pavel Tvrdik
	<tag><label id="proto-debug">debug all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
526 5a203dac Pavel Machek
	Set protocol debugging options. If asked, each protocol is capable of
527
	writing trace messages about its work to the log (with category
528
	<cf/trace/). You can either request printing of <cf/all/ trace messages
529
	or only of the types selected: <cf/states/ for protocol state changes
530 dad92c30 Ondrej Zajicek
	(protocol going up, down, starting, stopping etc.), <cf/routes/ for
531
	routes exchanged with the routing table, <cf/filters/ for details on
532
	route filtering, <cf/interfaces/ for interface change events sent to the
533
	protocol, <cf/events/ for events internal to the protocol and <cf/packets/
534
	for packets sent and received by the protocol. Default: off.
535 5a203dac Pavel Machek
536 9df52a98 Pavel Tvrdik
	<tag><label id="proto-mrtdump">mrtdump all|off|{ states|messages [, <m/.../] }</tag>
537 dad92c30 Ondrej Zajicek
	Set protocol MRTdump flags. MRTdump is a standard binary format for
538
	logging information from routing protocols and daemons. These flags
539
	control what kind of information is logged from the protocol to the
540
	MRTdump file (which must be specified by global <cf/mrtdump/ option, see
541
	the previous section). Although these flags are similar to flags of
542
	<cf/debug/ option, their meaning is different and protocol-specific. For
543
	BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs
544
	received BGP messages. Other protocols does not support MRTdump yet.
545 cf31112f Ondrej Zajicek
546 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-router-id">router id <m/IPv4 address/</tag>
547 dad92c30 Ondrej Zajicek
	This option can be used to override global router id for a given
548
	protocol. Default: uses global router id.
549 4cdd0784 Ondrej Zajicek
550 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-import">import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/filter expression/</tag>
551 dad92c30 Ondrej Zajicek
	Specify a filter to be used for filtering routes coming from the
552
	protocol to the routing table. <cf/all/ is shorthand for <cf/where true/
553
	and <cf/none/ is shorthand for <cf/where false/. Default: <cf/all/.
554 bfd71178 Pavel Machek
555 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-export">export <m/filter/</tag>
556 dad92c30 Ondrej Zajicek
	This is similar to the <cf>import</cf> keyword, except that it works in
557
	the direction from the routing table to the protocol. Default: <cf/none/.
558 af0b25d2 Pavel Machek
559 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag>
560 dad92c30 Ondrej Zajicek
	Usually, if an import filter rejects a route, the route is forgotten.
561
	When this option is active, these routes are kept in the routing table,
562
	but they are hidden and not propagated to other protocols. But it is
563
	possible to show them using <cf/show route filtered/. Note that this
564
	option does not work for the pipe protocol. Default: off.
565 cf98be7b Ondrej Zajicek
566 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
567 dad92c30 Ondrej Zajicek
	Specify an import route limit (a maximum number of routes imported from
568
	the protocol) and optionally the action to be taken when the limit is
569
	hit. Warn action just prints warning log message. Block action discards
570
	new routes coming from the protocol. Restart and disable actions shut
571
	the protocol down like appropriate commands. Disable is the default
572
	action if an action is not explicitly specified. Note that limits are
573
	reset during protocol reconfigure, reload or restart. Default: <cf/off/.
574 b662290f Ondrej Zajicek
575 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-receive-limit">receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
576 dad92c30 Ondrej Zajicek
	Specify an receive route limit (a maximum number of routes received from
577
	the protocol and remembered). It works almost identically to <cf>import
578
	limit</cf> option, the only difference is that if <cf/import keep
579
	filtered/ option is active, filtered routes are counted towards the
580
	limit and blocked routes are forgotten, as the main purpose of the
581
	receive limit is to protect routing tables from overflow. Import limit,
582
	on the contrary, counts accepted routes only and routes blocked by the
583
	limit are handled like filtered routes. Default: <cf/off/.
584 d9b77cc2 Ondrej Zajicek
585 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-export-limit">export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
586 dad92c30 Ondrej Zajicek
	Specify an export route limit, works similarly to the <cf>import
587
	limit</cf> option, but for the routes exported to the protocol. This
588
	option is experimental, there are some problems in details of its
589
	behavior -- the number of exported routes can temporarily exceed the
590
	limit without triggering it during protocol reload, exported routes
591
	counter ignores route blocking and block action also blocks route
592
	updates of already accepted routes -- and these details will probably
593
	change in the future. Default: <cf/off/.
594 ebecb6f6 Ondrej Zajicek
595 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-description">description "<m/text/"</tag>
596 dad92c30 Ondrej Zajicek
	This is an optional description of the protocol. It is displayed as a
597
	part of the output of 'show route all' command.
598 62aa96ca Ondrej Zajicek
599 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-table">table <m/name/</tag>
600 fd6cbe90 Ondrej Zajicek
	Connect this protocol to a non-default routing table.
601 7581b81b Pavel Machek
</descrip>
602
603 a7c9f7c0 Pavel Machek
<p>There are several options that give sense only with certain protocols:
604 7581b81b Pavel Machek
605
<descrip>
606 9df52a98 Pavel Tvrdik
	<tag><label id="proto-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../] [ { <m/option/; [<m/.../] } ]</tag>
607 f434d191 Ondrej Zajicek
	Specifies a set of interfaces on which the protocol is activated with
608
	given interface-specific options. A set of interfaces specified by one
609 dad92c30 Ondrej Zajicek
	interface option is described using an interface pattern. The interface
610
	pattern consists of a sequence of clauses (separated by commas), each
611 d7c06285 Ondrej Zajicek
	clause is a mask specified as a shell-like pattern. Interfaces are
612
	matched by their name.
613 dad92c30 Ondrej Zajicek
614
	An interface matches the pattern if it matches any of its clauses. If
615
	the clause begins with <cf/-/, matching interfaces are excluded. Patterns
616 d7c06285 Ondrej Zajicek
	are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/
617 dad92c30 Ondrej Zajicek
	means eth0 and all non-ethernets.
618
619 d7c06285 Ondrej Zajicek
	Some protocols (namely OSPFv2 and Direct) support extended clauses that
620
	may contain a mask, a prefix, or both of them. An interface matches such
621
	clause if its name matches the mask (if specified) and its address
622
	matches the prefix (if specified). Extended clauses are used when the
623
	protocol handles multiple addresses on an interface independently.
624
625 dad92c30 Ondrej Zajicek
	An interface option can be used more times with different interface-specific
626
	options, in that case for given interface the first matching interface
627
	option is used.
628 523f020b Ondrej Zajicek
629 12640c14 Ondrej Zajicek (work)
	This option is allowed in Babel, BFD, Direct, OSPF, RAdv and RIP
630
	protocols, but in OSPF protocol it is used in the <cf/area/ subsection.
631 f434d191 Ondrej Zajicek
632
	Default: none.
633
634
	Examples:
635
636 dad92c30 Ondrej Zajicek
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all
637
	interfaces with <cf>type broadcast</cf> option.
638 f434d191 Ondrej Zajicek
639 dad92c30 Ondrej Zajicek
	<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the
640
	protocol on enumerated interfaces with <cf>type ptp</cf> option.
641 523f020b Ondrej Zajicek
642 dad92c30 Ondrej Zajicek
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
643
	on all interfaces that have address from 192.168.0.0/16, but not from
644
	192.168.1.0/24.
645 f434d191 Ondrej Zajicek
646 dad92c30 Ondrej Zajicek
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
647
	on all interfaces that have address from 192.168.0.0/16, but not from
648
	192.168.1.0/24.
649 f434d191 Ondrej Zajicek
650
	<cf>interface "eth*" 192.168.1.0/24;</cf> - start the protocol on all
651
	ethernet interfaces that have address from 192.168.1.0/24.
652
653 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-tx-class">tx class|dscp <m/num/</tag>
654 dad92c30 Ondrej Zajicek
	This option specifies the value of ToS/DS/Class field in IP headers of
655
	the outgoing protocol packets. This may affect how the protocol packets
656
	are processed by the network relative to the other network traffic. With
657
	<cf/class/ keyword, the value (0-255) is used for the whole ToS/Class
658
	octet (but two bits reserved for ECN are ignored). With	<cf/dscp/
659
	keyword, the value (0-63) is used just for the DS field in the octet.
660
	Default value is 0xc0 (DSCP 0x30 - CS6).
661 ef4a50be Ondrej Zajicek
662 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-tx-priority">tx priority <m/num/</tag>
663 dad92c30 Ondrej Zajicek
	This option specifies the local packet priority. This may affect how the
664
	protocol packets are processed in the local TX queues. This option is
665
	Linux specific. Default value is 7 (highest priority, privileged traffic).
666 ef4a50be Ondrej Zajicek
667 64385aee Pavel Tvrdík
	<tag><label id="proto-pass">password "<m/password/" [ { <m>password options</m> } ]</tag>
668
	Specifies a password that can be used by the protocol as a shared secret
669
	key. Password option can be used more times to specify more passwords.
670
	If more passwords are specified, it is a protocol-dependent decision
671
	which one is really used. Specifying passwords does not mean that
672
	authentication is enabled, authentication can be enabled by separate,
673
	protocol-dependent <cf/authentication/ option.
674 523f020b Ondrej Zajicek
675 e03dc6a9 Ondrej Zajicek (work)
	This option is allowed in BFD, OSPF and RIP protocols. BGP has also
676 f434d191 Ondrej Zajicek
	<cf/password/ option, but it is slightly different and described
677
	separately.
678
	Default: none.
679
</descrip>
680
681
<p>Password option can contain section with some (not necessary all) password sub-options:
682
683
<descrip>
684 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-pass-id">id <M>num</M></tag>
685 0a21c211 Ondrej Zajicek (work)
	ID of the password, (1-255). If it is not used, BIRD will choose ID based
686 dad92c30 Ondrej Zajicek
	on an order of the password item in the interface. For example, second
687
	password item in one interface will have default ID 2. ID is used by
688
	some routing protocols to identify which password was used to
689
	authenticate protocol packets.
690 f434d191 Ondrej Zajicek
691 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-pass-gen-from">generate from "<m/time/"</tag>
692 dad92c30 Ondrej Zajicek
	The start time of the usage of the password for packet signing.
693
	The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
694 f434d191 Ondrej Zajicek
695 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-pass-gen-to">generate to "<m/time/"</tag>
696 dad92c30 Ondrej Zajicek
	The last time of the usage of the password for packet signing.
697 f434d191 Ondrej Zajicek
698 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-pass-accept-from">accept from "<m/time/"</tag>
699 dad92c30 Ondrej Zajicek
	The start time of the usage of the password for packet verification.
700 5a203dac Pavel Machek
701 b9864aa8 Pavel Tvrdik
	<tag><label id="proto-pass-accept-to">accept to "<m/time/"</tag>
702 dad92c30 Ondrej Zajicek
	The last time of the usage of the password for packet verification.
703 64385aee Pavel Tvrdík
704
	<tag><label id="proto-pass-from">from "<m/time/"</tag>
705
	Shorthand for setting both <cf/generate from/ and <cf/accept from/.
706
707
	<tag><label id="proto-pass-to">to "<m/time/"</tag>
708
	Shorthand for setting both <cf/generate to/ and <cf/accept to/.
709
710
	<tag><label id="proto-pass-algorithm">algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 )</tag>
711
	The message authentication algorithm for the password when cryptographic
712
	authentication is enabled. The default value depends on the protocol.
713
	For RIP and OSPFv2 it is Keyed-MD5 (for compatibility), for OSPFv3
714
	protocol it is HMAC-SHA-256.
715
716 7581b81b Pavel Machek
</descrip>
717 d37f899b Pavel Machek
718 77234bbb Ondrej Zajicek (work)
719
<sect>Flowspec network type
720
<label id="flowspec-network-type">
721
722
<p>The flow specification are rules for routers and firewalls for filtering
723
purpose. It is described by <rfc id="5575">. There are 3 types of arguments:
724
<m/inet4/ or <m/inet6/ prefixes, bitmasks matching expressions and numbers
725
matching expressions.
726
727
Bitmasks matching is written using <m/value/<cf>/</cf><m/mask/ or
728
<cf/!/<m/value/<cf>/</cf><m/mask/ pairs. It means that <cf/(/<m/data/ <cf/&/
729
<m/mask/<cf/)/ is or is not equal to <m/value/.
730
731
Numbers matching is a matching sequence of numbers and ranges separeted by a
732
commas (<cf/,/) (e.g. <cf/10,20,30/). Ranges can be written using double dots
733
<cf/../ notation (e.g. <cf/80..90,120..124/). An alternative notation are
734
sequence of one or more pairs of relational operators and values separated by
735
logical operators <cf/&&/ or <cf/||/. Allowed relational operators are <cf/=/,
736
<cf/!=/, <cf/</, <cf/<=/, <cf/>/, <cf/>=/, <cf/true/ and <cf/false/.
737
738
<sect1>IPv4 Flowspec
739
740
<p><descrip>
741
	<tag><label id="flow-dst">dst <m/inet4/</tag>
742
	Set a matching destination prefix (e.g. <cf>dst 192.168.0.0/16</cf>).
743
	Only this option is mandatory in IPv4 Flowspec.
744
745
	<tag><label id="flow-src">src <m/inet4/</tag>
746
	Set a matching source prefix (e.g. <cf>src 10.0.0.0/8</cf>).
747
748
	<tag><label id="flow-proto">proto <m/numbers-match/</tag>
749
	Set a matching IP protocol numbers (e.g.  <cf/proto 6/).
750
751
	<tag><label id="flow-port">port <m/numbers-match/</tag>
752
	Set a matching source or destination TCP/UDP port numbers (e.g.
753
	<cf>port 1..1023,1194,3306</cf>).
754
755
	<tag><label id="flow-dport">dport <m/numbers-match/</tag>
756
	Set a mating destination port numbers (e.g. <cf>dport 49151</cf>).
757
758
	<tag><label id="flow-sport">sport <m/numbers-match/</tag>
759
	Set a matching source port numbers (e.g. <cf>sport = 0</cf>).
760
761
	<tag><label id="flow-icmp-type">icmp type <m/numbers-match/</tag>
762
	Set a matching type field number of an ICMP packet (e.g. <cf>icmp type
763
	3</cf>)
764
765
	<tag><label id="flow-icmp-code">icmp code <m/numbers-match/</tag>
766
	Set a matching code field number of an ICMP packet (e.g. <cf>icmp code
767
	1</cf>)
768
769
	<tag><label id="flow-tcp-flags">tcp flags <m/bitmask-match/</tag>
770
	Set a matching bitmask for TCP header flags (aka control bits) (e.g.
771
	<cf>tcp flags 0x03/0x0f;</cf>).
772
773
	<tag><label id="flow-length">length <m/numbers-match/</tag>
774
	Set a matching packet length (e.g. <cf>length > 1500;</cf>)
775
776
	<tag><label id="flow-dscp">dscp <m/numbers-match/</tag>
777
	Set a matching DiffServ Code Point number (e.g. <cf>length > 1500;</cf>).
778
779
	<tag><label id="flow-fragment">fragment <m/fragmentation-type/</tag>
780
	Set a matching type of packet fragmentation. Allowed fragmentation
781
	types are <cf/dont_fragment/, <cf/is_fragment/, <cf/first_fragment/,
782
	<cf/last_fragment/ (e.g. <cf>fragment is_fragment &&
783
	!dont_fragment</cf>).
784
</descrip>
785
786
<p><code>
787
protocol static {
788
	flow4;
789
790
	route flow4 {
791
		dst 10.0.0.0/8;
792
		port > 24 && < 30 || 40..50,60..70,80 && >= 90;
793
		tcp flags 0x03/0x0f;
794
		length > 1024;
795
		dscp = 63;
796
		fragment dont_fragment, is_fragment || !first_fragment;
797
	} drop;
798
}
799
</code>
800
801
<sect1>Differences for IPv6 Flowspec
802
803
<p>Flowspec IPv6 are same as Flowspec IPv4 with a few exceptions.
804
<itemize>
805
	<item>Prefixes <m/inet6/ can be specified not only with prefix length,
806
	but with prefix <cf/offset/ <m/num/ too (e.g.
807
	<cf>::1234:5678:9800:0000/101 offset 64</cf>). Offset means to don't
808
	care of <m/num/ first bits.
809
	<item>IPv6 Flowspec hasn't mandatory any flowspec component.
810
	<item>In IPv6 packets, there is a matching the last next header value
811
	for a matching IP protocol number (e.g. <cf>next header 6</cf>).
812
	<item>It is not possible to set <cf>dont_fragment</cf> as a type of
813
	packet fragmentation.
814
</itemize>
815
816
<p><descrip>
817
	<tag><label id="flow6-dst">dst <m/inet6/ [offset <m/num/]</tag>
818
	Set a matching destination IPv6 prefix (e.g. <cf>dst
819
	::1c77:3769:27ad:a11a/128 offset 64</cf>).
820
821
	<tag><label id="flow6-src">src <m/inet6/ [offset <m/num/]</tag>
822
	Set a matching source IPv6 prefix (e.g. <cf>src fe80::/64</cf>).
823
824
	<tag><label id="flow6-next-header">next header <m/numbers-match/</tag>
825
	Set a matching IP protocol numbers (e.g. <cf>next header != 6</cf>).
826
827
	<tag><label id="flow6-label">label <m/bitmask-match/</tag>
828
	Set a 20-bit bitmask for matching Flow Label field in IPv6 packets
829
	(e.g. <cf>label 0x8e5/0x8e5</cf>).
830
</descrip>
831
832
<p><code>
833
protocol static {
834
	flow6;
835
836
	route flow6 {
837
		dst fec0:1122:3344:5566:7788:99aa:bbcc:ddee/128;
838
		src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63;
839
		next header = 23;
840
		sport > 24 && < 30 || = 40 || 50,60,70..80;
841
		dport = 50;
842
		tcp flags 0x03/0x0f, !0/0xff || 0x33/0x33;
843
		fragment !is_fragment || !first_fragment;
844
		label 0xaaaa/0xaaaa && 0x33/0x33;
845
	} drop;
846
}
847
</code>
848
849 5a203dac Pavel Machek
<chapt>Remote control
850 b9864aa8 Pavel Tvrdik
<label id="remote-control">
851 36032ded Pavel Machek
852 dad92c30 Ondrej Zajicek
<p>You can use the command-line client <file>birdc</file> to talk with a running
853
BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless
854
changed with the <tt/-s/ option given to both the server and the client). The
855
commands can perform simple actions such as enabling/disabling of protocols,
856
telling BIRD to show various information, telling it to show routing table
857
filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to
858
get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
859
client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can
860
be passed to the client, to make it dump numeric return codes along with the
861
messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your
862
own applications could do that, too -- the format of communication between BIRD
863
and <file/birdc/ is stable (see the programmer's documentation).
864
865
<p>There is also lightweight variant of BIRD client called <file/birdcl/, which
866
does not support command line editing and history and has minimal dependencies.
867
This is useful for running BIRD in resource constrained environments, where
868
Readline library (required for regular BIRD client) is not available.
869 a5e9f3d2 Ondrej Zajicek
870
<p>Many commands have the <m/name/ of the protocol instance as an argument.
871 f434d191 Ondrej Zajicek
This argument can be omitted if there exists only a single instance.
872
873 5a203dac Pavel Machek
<p>Here is a brief list of supported functions:
874 64722c98 Pavel Machek
875
<descrip>
876 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-status">show status</tag>
877 dad92c30 Ondrej Zajicek
	Show router status, that is BIRD version, uptime and time from last
878
	reconfiguration.
879 5a203dac Pavel Machek
880 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-interfaces">show interfaces [summary]</tag>
881 43fc6bb0 Ondrej Zajicek (work)
	Show the list of interfaces. For each interface, print its type, state,
882
	MTU and addresses assigned.
883
884 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-protocols">show protocols [all]</tag>
885 dad92c30 Ondrej Zajicek
	Show list of protocol instances along with tables they are connected to
886
	and protocol status, possibly giving verbose information, if <cf/all/ is
887
	specified.
888 64722c98 Pavel Machek
889 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-ospf-iface">show ospf interface [<m/name/] ["<m/interface/"]</tag>
890 f434d191 Ondrej Zajicek
	Show detailed information about OSPF interfaces.
891
892 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-ospf-neighbors">show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
893 f434d191 Ondrej Zajicek
	Show a list of OSPF neighbors and a state of adjacency to them.
894
895 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-ospf-state">show ospf state [all] [<m/name/]</tag>
896 dad92c30 Ondrej Zajicek
	Show detailed information about OSPF areas based on a content of the
897
	link-state database. It shows network topology, stub networks,
898
	aggregated networks and routers from other areas and external routes.
899
	The command shows information about reachable network nodes, use option
900
	<cf/all/ to show information about all network nodes in the link-state
901
	database.
902 0ea8fb4a Ondrej Zajicek
903 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-ospf-topology">show ospf topology [all] [<m/name/]</tag>
904 dad92c30 Ondrej Zajicek
	Show a topology of OSPF areas based on a content of the link-state
905
	database. It is just a stripped-down version of 'show ospf state'.
906 64722c98 Pavel Machek
907 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-ospf-lsadb">show ospf lsadb [global | area <m/id/ | link] [type <m/num/] [lsid <m/id/] [self | router <m/id/] [<m/name/] </tag>
908 dad92c30 Ondrej Zajicek
	Show contents of an OSPF LSA database. Options could be used to filter
909
	entries.
910 20ab192b Ondrej Zajicek
911 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-rip-interfaces">show rip interfaces [<m/name/] ["<m/interface/"]</tag>
912 43fc6bb0 Ondrej Zajicek (work)
	Show detailed information about RIP interfaces.
913
914 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-rip-neighbors">show rip neighbors [<m/name/] ["<m/interface/"]</tag>
915 43fc6bb0 Ondrej Zajicek (work)
	Show a list of RIP neighbors and associated state.
916
917 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-static">show static [<m/name/]</tag>
918 f434d191 Ondrej Zajicek
	Show detailed information about static routes.
919
920 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-bfd-sessions">show bfd sessions [<m/name/]</tag>
921 12201fd8 Ondrej Zajicek
	Show information about BFD sessions.
922
923 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-show-symbols">show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
924 dad92c30 Ondrej Zajicek
	Show the list of symbols defined in the configuration (names of
925
	protocols, routing tables etc.).
926 5a203dac Pavel Machek
927 f9bd11c3 Pavel Tvrdik
	<tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table <m/t/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag>
928 dad92c30 Ondrej Zajicek
	Show contents of a routing table (by default of the main one or the
929
	table attached to a respective protocol), that is routes, their metrics
930
	and (in case the <cf/all/ switch is given) all their attributes.
931 5a203dac Pavel Machek
932
	<p>You can specify a <m/prefix/ if you want to print routes for a
933
	specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get
934
	the entry which will be used for forwarding of packets to the given
935
	destination. By default, all routes for each network are printed with
936
	the selected one at the top, unless <cf/primary/ is given in which case
937
	only the selected route is shown.
938
939
	<p>You can also ask for printing only routes processed and accepted by
940
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
941
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
942 7aa80901 Ondrej Zajicek
943
	The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for
944
	printing of routes that are exported to the specified protocol.
945
	With <cf/preexport/, the export filter of the protocol is skipped.
946
	With <cf/noexport/, routes rejected by the export filter are printed
947
	instead. Note that routes not exported to the protocol for other reasons
948
	(e.g. secondary routes or routes imported from that protocol) are not
949
	printed even with <cf/noexport/.
950 5a203dac Pavel Machek
951 4d176e14 Ondrej Filip
	<p>You can also select just routes added by a specific protocol.
952
	<cf>protocol <m/p/</cf>.
953
954 dad92c30 Ondrej Zajicek
	<p>If BIRD is configured to keep filtered routes (see <cf/import keep
955
	filtered/ option), you can show them instead of routes by using
956
	<cf/filtered/ switch.
957 cf98be7b Ondrej Zajicek
958 5a203dac Pavel Machek
	<p>The <cf/stats/ switch requests showing of route statistics (the
959
	number of networks, number of routes before and after filtering). If
960
	you use <cf/count/ instead, only the statistics will be printed.
961
962 74d76f6c Pavel Tvrdik
	<tag><label id="cli-show-roa">show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/]</tag>
963 dad92c30 Ondrej Zajicek
	Show contents of a ROA table (by default of the first one). You can
964
	specify a <m/prefix/ to print ROA entries for a specific network. If you
965
	use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route
966
	validation of the network prefix; i.e., ROA entries whose prefixes cover
967
	the network prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA
968
	entries covered by the network prefix. You could also use <cf/as/ option
969 af582c48 Ondrej Zajicek
	to show just entries for given AS.
970
971 74d76f6c Pavel Tvrdik
	<tag><label id="cli-add-roa">add roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag>
972 dad92c30 Ondrej Zajicek
	Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/
973
	compared to <it/static/ entries specified in the config file. These
974
	dynamic entries survive reconfiguration.
975 af582c48 Ondrej Zajicek
976 74d76f6c Pavel Tvrdik
	<tag><label id="cli-delete-roa">delete roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag>
977 dad92c30 Ondrej Zajicek
	Delete the specified ROA entry from a ROA table. Only dynamic ROA
978
	entries (i.e., the ones added by <cf/add roa/ command) can be deleted.
979 af582c48 Ondrej Zajicek
980 74d76f6c Pavel Tvrdik
	<tag><label id="cli-flush-roa">flush roa [table <m/t/]</tag>
981 af582c48 Ondrej Zajicek
	Remove all dynamic ROA entries from a ROA table.
982
983 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
984 dad92c30 Ondrej Zajicek
	Reload configuration from a given file. BIRD will smoothly switch itself
985
	to the new configuration, protocols are reconfigured if possible,
986
	restarted otherwise. Changes in filters usually lead to restart of
987
	affected protocols.
988
989
	If <cf/soft/ option is used, changes in filters does not cause BIRD to
990
	restart affected protocols, therefore already accepted routes (according
991
	to old filters) would be still propagated, but new routes would be
992
	processed according to the new filters.
993
994
	If <cf/timeout/ option is used, config timer is activated. The new
995
	configuration could be either confirmed using <cf/configure confirm/
996
	command, or it will be reverted to the old one when the config timer
997
	expires. This is useful for cases when reconfiguration breaks current
998 fff7498d Pavel Tvrdik
	routing and a router becomes inaccessible for an administrator. The
999 dad92c30 Ondrej Zajicek
	config timeout expiration is equivalent to <cf/configure undo/
1000
	command. The timeout duration could be specified, default is 300 s.
1001 a92cf57d Ondrej Zajicek
1002 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-configure-confirm">configure confirm</tag>
1003 a92cf57d Ondrej Zajicek
	Deactivate the config undo timer and therefore confirm the current
1004
	configuration.
1005
1006 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-configure-undo">configure undo</tag>
1007 dad92c30 Ondrej Zajicek
	Undo the last configuration change and smoothly switch back to the
1008
	previous (stored) configuration. If the last configuration change was
1009
	soft, the undo change is also soft. There is only one level of undo, but
1010
	in some specific cases when several reconfiguration requests are given
1011
	immediately in a row and the intermediate ones are skipped then the undo
1012
	also skips them back.
1013 a92cf57d Ondrej Zajicek
1014 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-configure-check">configure check ["<m/config file/"]</tag>
1015 dad92c30 Ondrej Zajicek
	Read and parse given config file, but do not use it. useful for checking
1016
	syntactic and some semantic validity of an config file.
1017 a92cf57d Ondrej Zajicek
1018 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-enable-disable-restart">enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
1019 dad92c30 Ondrej Zajicek
	Enable, disable or restart a given protocol instance, instances matching
1020
	the <cf><m/pattern/</cf> or <cf/all/ instances.
1021 bf47fe4b Ondrej Zajicek
1022 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-reload">reload [in|out] <m/name/|"<m/pattern/"|all</tag>
1023 dad92c30 Ondrej Zajicek
	Reload a given protocol instance, that means re-import routes from the
1024
	protocol instance and re-export preferred routes to the instance. If
1025
	<cf/in/ or <cf/out/ options are used, the command is restricted to one
1026
	direction (re-import or re-export).
1027
1028
	This command is useful if appropriate filters have changed but the
1029
	protocol instance was not restarted (or reloaded), therefore it still
1030
	propagates the old set of routes. For example when <cf/configure soft/
1031
	command was used to change filters.
1032
1033
	Re-export always succeeds, but re-import is protocol-dependent and might
1034
	fail (for example, if BGP neighbor does not support route-refresh
1035
	extension). In that case, re-export is also skipped. Note that for the
1036
	pipe protocol, both directions are always reloaded together (<cf/in/ or
1037
	<cf/out/ options are ignored in that case).
1038 8a7fb885 Ondrej Zajicek
1039 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-down">down</tag>
1040 5a203dac Pavel Machek
	Shut BIRD down.
1041 64722c98 Pavel Machek
1042 9df52a98 Pavel Tvrdik
	<tag><label id="cli-debug">debug <m/protocol/|<m/pattern/|all all|off|{ states|routes|filters|events|packets [, <m/.../] }</tag>
1043 64722c98 Pavel Machek
	Control protocol debugging.
1044 508d9360 Ondrej Zajicek
1045 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-dump">dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
1046 508d9360 Ondrej Zajicek
	Dump contents of internal data structures to the debugging output.
1047
1048 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-echo">echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
1049 508d9360 Ondrej Zajicek
	Control echoing of log messages to the command-line output.
1050 b9864aa8 Pavel Tvrdik
	See <ref id="opt-log" name="log option"> for a list of log classes.
1051 508d9360 Ondrej Zajicek
1052 b9864aa8 Pavel Tvrdik
	<tag><label id="cli-eval">eval <m/expr/</tag>
1053 508d9360 Ondrej Zajicek
	Evaluate given expression.
1054 64722c98 Pavel Machek
</descrip>
1055 36032ded Pavel Machek
1056 dad92c30 Ondrej Zajicek
1057 371adba6 Martin Mares
<chapt>Filters
1058 b9864aa8 Pavel Tvrdik
<label id="filters">
1059 d37f899b Pavel Machek
1060 371adba6 Martin Mares
<sect>Introduction
1061 b9864aa8 Pavel Tvrdik
<label id="filters-intro">
1062 d37f899b Pavel Machek
1063 dad92c30 Ondrej Zajicek
<p>BIRD contains a simple programming language. (No, it can't yet read mail :-).
1064
There are two objects in this language: filters and functions. Filters are
1065
interpreted by BIRD core when a route is being passed between protocols and
1066
routing tables. The filter language contains control structures such as if's and
1067
switches, but it allows no loops. An example of a filter using many features can
1068
be found in <file>filter/test.conf</file>.
1069 d37f899b Pavel Machek
1070 dad92c30 Ondrej Zajicek
<p>Filter gets the route, looks at its attributes and modifies some of them if
1071
it wishes. At the end, it decides whether to pass the changed route through
1072
(using <cf/accept/) or whether to <cf/reject/ it. A simple filter looks like
1073
this:
1074 d37f899b Pavel Machek
1075 a0dd1c74 Pavel Machek
<code>
1076 d37f899b Pavel Machek
filter not_too_far
1077
int var;
1078
{
1079
	if defined( rip_metric ) then
1080
		var = rip_metric;
1081
	else {
1082
		var = 1;
1083
		rip_metric = 1;
1084
	}
1085
	if rip_metric &gt; 10 then
1086
		reject "RIP metric is too big";
1087
	else
1088
		accept "ok";
1089
}
1090 a0dd1c74 Pavel Machek
</code>
1091 d37f899b Pavel Machek
1092 dad92c30 Ondrej Zajicek
<p>As you can see, a filter has a header, a list of local variables, and a body.
1093
The header consists of the <cf/filter/ keyword followed by a (unique) name of
1094
filter. The list of local variables consists of <cf><M>type name</M>;</cf>
1095
pairs where each pair defines one local variable. The body consists of <cf>
1096
{ <M>statements</M> }</cf>. Each <m/statement/ is terminated by a <cf/;/. You
1097
can group several statements to a single compound statement by using braces
1098
(<cf>{ <M>statements</M> }</cf>) which is useful if you want to make a bigger
1099
block of code conditional.
1100 1632f1fe Pavel Machek
1101 dad92c30 Ondrej Zajicek
<p>BIRD supports functions, so that you don't have to repeat the same blocks of
1102
code over and over. Functions can have zero or more parameters and they can have
1103
local variables. Recursion is not allowed. Function definitions look like this:
1104 0e5373fd Pavel Machek
1105
<code>
1106
function name ()
1107
int local_variable;
1108
{
1109
	local_variable = 5;
1110
}
1111
1112
function with_parameters (int parameter)
1113
{
1114
	print parameter;
1115
}
1116
</code>
1117
1118 dad92c30 Ondrej Zajicek
<p>Unlike in C, variables are declared after the <cf/function/ line, but before
1119
the first <cf/{/. You can't declare variables in nested blocks. Functions are
1120
called like in C: <cf>name(); with_parameters(5);</cf>. Function may return
1121
values using the <cf>return <m/[expr]/</cf> command. Returning a value exits
1122
from current function (this is similar to C).
1123 0e5373fd Pavel Machek
1124 dad92c30 Ondrej Zajicek
<p>Filters are declared in a way similar to functions except they can't have
1125
explicit parameters. They get a route table entry as an implicit parameter, it
1126
is also passed automatically to any functions called. The filter must terminate
1127
with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in
1128
filter, the route is rejected.
1129 0e5373fd Pavel Machek
1130 dad92c30 Ondrej Zajicek
<p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf>
1131
from the command line client. An example session might look like:
1132 c184d9d0 Pavel Machek
1133
<code>
1134
pavel@bug:~/bird$ ./birdc -s bird.ctl
1135
BIRD 0.0.0 ready.
1136
bird> show route
1137
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
1138
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
1139
127.0.0.0/8        dev lo [direct1 23:21] (240)
1140
bird> show route ?
1141 1632f1fe Pavel Machek
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
1142 66701947 Martin Mares
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
1143 c184d9d0 Pavel Machek
127.0.0.0/8        dev lo [direct1 23:21] (240)
1144
bird>
1145
</code>
1146
1147 dad92c30 Ondrej Zajicek
1148 371adba6 Martin Mares
<sect>Data types
1149 b9864aa8 Pavel Tvrdik
<label id="data-types">
1150 d37f899b Pavel Machek
1151 dad92c30 Ondrej Zajicek
<p>Each variable and each value has certain type. Booleans, integers and enums
1152
are incompatible with each other (that is to prevent you from shooting in the
1153
foot).
1154 d37f899b Pavel Machek
1155
<descrip>
1156 b9864aa8 Pavel Tvrdik
	<tag><label id="type-bool">bool</tag>
1157 dad92c30 Ondrej Zajicek
	This is a boolean type, it can have only two values, <cf/true/ and
1158
	<cf/false/. Boolean is the only type you can use in <cf/if/ statements.
1159
1160 b9864aa8 Pavel Tvrdik
	<tag><label id="type-int">int</tag>
1161 dad92c30 Ondrej Zajicek
	This is a general integer type. It is an unsigned 32bit type; i.e., you
1162
	can expect it to store values from 0 to 4294967295. Overflows are not
1163
	checked. You can use <cf/0x1234/ syntax to write hexadecimal values.
1164
1165 b9864aa8 Pavel Tvrdik
	<tag><label id="type-pair">pair</tag>
1166 dad92c30 Ondrej Zajicek
	This is a pair of two short integers. Each component can have values
1167
	from 0 to 65535. Literals of this type are written as <cf/(1234,5678)/.
1168
	The same syntax can also be used to construct a pair from two arbitrary
1169
	integer expressions (for example <cf/(1+2,a)/).
1170
1171 b9864aa8 Pavel Tvrdik
	<tag><label id="type-quad">quad</tag>
1172 dad92c30 Ondrej Zajicek
	This is a dotted quad of numbers used to represent router IDs (and
1173
	others). Each component can have a value from 0 to 255. Literals of
1174
	this type are written like IPv4 addresses.
1175
1176 b9864aa8 Pavel Tvrdik
	<tag><label id="type-string">string</tag>
1177 dad92c30 Ondrej Zajicek
	This is a string of characters. There are no ways to modify strings in
1178
	filters. You can pass them between functions, assign them to variables
1179
	of type <cf/string/, print such variables, use standard string
1180
	comparison operations (e.g. <cf/=, !=, &lt;, &gt;, &lt;=, &gt;=/), but
1181
	you can't concatenate two strings. String literals are written as
1182 768d5e10 Pavel Tvrdik
	<cf/"This is a string constant"/. Additionally matching (<cf/&tilde;,
1183
	!&tilde;/) operators could be used to match a string value against
1184
	a shell pattern (represented also as a string).
1185 dad92c30 Ondrej Zajicek
1186 b9864aa8 Pavel Tvrdik
	<tag><label id="type-ip">ip</tag>
1187 dad92c30 Ondrej Zajicek
	This type can hold a single IP address. Depending on the compile-time
1188
	configuration of BIRD you are using, it is either an IPv4 or IPv6
1189
	address. IP addresses are written in the standard notation
1190
	(<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator
1191
	<cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but
1192
	first <cf><M>num</M></cf> bits from the IP address. So
1193
	<cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
1194
1195 b9864aa8 Pavel Tvrdik
	<tag><label id="type-prefix">prefix</tag>
1196 dad92c30 Ondrej Zajicek
	This type can hold a network prefix consisting of IP address and prefix
1197
	length. Prefix literals are written as <cf><m/ipaddress//<m/pxlen/</cf>,
1198
	or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
1199
	operators on prefixes: <cf/.ip/ which extracts the IP address from the
1200
	pair, and <cf/.len/, which separates prefix length from the pair.
1201 90dc0f08 Ondrej Filip
	So <cf>1.2.0.0/16.len = 16</cf> is true.
1202 dad92c30 Ondrej Zajicek
1203 b9864aa8 Pavel Tvrdik
	<tag><label id="type-ec">ec</tag>
1204 dad92c30 Ondrej Zajicek
	This is a specialized type used to represent BGP extended community
1205
	values. It is essentially a 64bit value, literals of this type are
1206
	usually written as <cf>(<m/kind/, <m/key/, <m/value/)</cf>, where
1207
	<cf/kind/ is a kind of extended community (e.g. <cf/rt/ / <cf/ro/ for a
1208
	route target / route origin communities), the format and possible values
1209
	of <cf/key/ and <cf/value/ are usually integers, but it depends on the
1210
	used kind. Similarly to pairs, ECs can be constructed using expressions
1211
	for <cf/key/ and <cf/value/ parts, (e.g. <cf/(ro, myas, 3*10)/, where
1212
	<cf/myas/ is an integer variable).
1213 dcde7ae5 Ondrej Zajicek
1214 b9864aa8 Pavel Tvrdik
	<tag><label id="type-lc">lc</tag>
1215 cec4a73c Ondrej Zajicek (work)
	This is a specialized type used to represent BGP large community
1216
	values. It is essentially a triplet of 32bit values, where the first
1217
	value is reserved for the AS number of the issuer, while meaning of
1218
	remaining parts is defined by the issuer. Literals of this type are
1219
	written as <cf/(123, 456, 789)/, with any integer values. Similarly to
1220
	pairs, LCs can be constructed using expressions for its parts, (e.g.
1221
	<cf/(myas, 10+20, 3*10)/, where <cf/myas/ is an integer variable).
1222
1223 b9864aa8 Pavel Tvrdik
	<tag><label id="type-set">int|pair|quad|ip|prefix|ec|lc|enum set</tag>
1224 dad92c30 Ondrej Zajicek
	Filters recognize four types of sets. Sets are similar to strings: you
1225
	can pass them around but you can't modify them. Literals of type <cf>int
1226
	set</cf> look like <cf> [ 1, 2, 5..7 ]</cf>. As you can see, both simple
1227
	values and ranges are permitted in sets.
1228
1229
	For pair sets, expressions like <cf/(123,*)/ can be used to denote
1230
	ranges (in that case <cf/(123,0)..(123,65535)/). You can also use
1231
	<cf/(123,5..100)/ for range <cf/(123,5)..(123,100)/. You can also use
1232
	<cf/*/ and <cf/a..b/ expressions in the first part of a pair, note that
1233
	such expressions are translated to a set of intervals, which may be
1234
	memory intensive. E.g. <cf/(*,4..20)/ is translated to <cf/(0,4..20),
1235
	(1,4..20), (2,4..20), ... (65535, 4..20)/.
1236
1237
	EC sets use similar expressions like pair sets, e.g. <cf/(rt, 123,
1238
	10..20)/ or <cf/(ro, 123, *)/. Expressions requiring the translation
1239
	(like <cf/(rt, *, 3)/) are not allowed (as they usually have 4B range
1240
	for ASNs).
1241
1242 cec4a73c Ondrej Zajicek (work)
	Also LC sets use similar expressions like pair sets. You can use ranges
1243
	and wildcards, but if one field uses that, more specific (later) fields
1244
	must be wildcards. E.g., <cf/(10, 20..30, *)/ or <cf/(10, 20, 30..40)/
1245
	is valid, while <cf/(10, *, 20..30)/ or <cf/(10, 20..30, 40)/ is not
1246
	valid.
1247
1248
	You can also use expressions for int, pair, EC and LC set values.
1249
	However, it must be possible to evaluate these expressions before daemon
1250
	boots. So you can use only constants inside them. E.g.
1251 dad92c30 Ondrej Zajicek
1252 946dc15c Ondrej Filip
	<code>
1253
	 define one=1;
1254 8815d846 Ondrej Zajicek
	 define myas=64500;
1255 946dc15c Ondrej Filip
	 int set odds;
1256
	 pair set ps;
1257 8815d846 Ondrej Zajicek
	 ec set es;
1258 946dc15c Ondrej Filip
1259 8815d846 Ondrej Zajicek
	 odds = [ one, 2+1, 6-one, 2*2*2-1, 9, 11 ];
1260 b54ad333 Ondrej Zajicek
	 ps = [ (1,one+one), (3,4)..(4,8), (5,*), (6,3..6), (7..9,*) ];
1261 8815d846 Ondrej Zajicek
	 es = [ (rt, myas, 3*10), (rt, myas+one, 0..16*16*16-1), (ro, myas+2, *) ];
1262 946dc15c Ondrej Filip
	</code>
1263 b1a597e0 Ondrej Zajicek
1264 dad92c30 Ondrej Zajicek
	Sets of prefixes are special: their literals does not allow ranges, but
1265
	allows prefix patterns that are written
1266
	as <cf><M>ipaddress</M>/<M>pxlen</M>{<M>low</M>,<M>high</M>}</cf>.
1267
	Prefix <cf><m>ip1</m>/<m>len1</m></cf> matches prefix
1268
	pattern <cf><m>ip2</m>/<m>len2</m>{<m>l</m>,<m>h</m>}</cf> if the
1269
	first <cf>min(len1, len2)</cf> bits of <cf/ip1/ and <cf/ip2/ are
1270
	identical and <cf>len1 &lt;= ip1 &lt;= len2</cf>. A valid prefix pattern
1271
	has to satisfy <cf>low &lt;= high</cf>, but <cf/pxlen/ is not
1272
	constrained by <cf/low/ or <cf/high/. Obviously, a prefix matches a
1273
	prefix set literal if it matches any prefix pattern in the prefix set
1274
	literal.
1275
1276
	There are also two shorthands for prefix patterns: <cf><m/address//<m/len/+</cf>
1277
	is a shorthand for <cf><m/address//<m/len/{<m/len/,<m/maxlen/}</cf>
1278
	(where <cf><m/maxlen/</cf> is 32 for IPv4 and 128 for IPv6), that means
1279
	network prefix <cf><m/address//<m/len/</cf> and all its	subnets.
1280
	<cf><m/address//<m/len/-</cf> is a shorthand for
1281
	<cf><m/address//<m/len/{0,<m/len/}</cf>, that means network prefix
1282
	<cf><m/address//<m/len/</cf> and all its supernets (network prefixes
1283
	that contain it).
1284
1285
	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}
1286
	]</cf> matches prefix <cf>1.0.0.0/8</cf>, all subprefixes of
1287
	<cf>2.0.0.0/8</cf>, all superprefixes of <cf>3.0.0.0/8</cf> and prefixes
1288
	<cf/4.X.X.X/ whose prefix length is 16 to 24. <cf>[ 0.0.0.0/0{20,24} ]</cf>
1289
	matches all prefixes (regardless of IP address) whose prefix length is
1290
	20 to 24, <cf>[ 1.2.3.4/32- ]</cf> matches any prefix that contains IP
1291
	address <cf>1.2.3.4</cf>. <cf>1.2.0.0/16 &tilde; [ 1.0.0.0/8{15,17} ]</cf>
1292
	is true, but <cf>1.0.0.0/16 &tilde; [ 1.0.0.0/8- ]</cf> is false.
1293
1294
	Cisco-style patterns like <cf>10.0.0.0/8 ge 16 le 24</cf> can be expressed
1295 523f020b Ondrej Zajicek
	in BIRD as <cf>10.0.0.0/8{16,24}</cf>, <cf>192.168.0.0/16 le 24</cf> as
1296 dad92c30 Ondrej Zajicek
	<cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
1297
	<cf>192.168.0.0/16{24,32}</cf>.
1298 d37f899b Pavel Machek
1299 b9864aa8 Pavel Tvrdik
	<tag><label id="type-enum">enum</tag>
1300 dad92c30 Ondrej Zajicek
	Enumeration types are fixed sets of possibilities. You can't define your
1301
	own variables of such type, but some route attributes are of enumeration
1302
	type. Enumeration types are incompatible with each other.
1303 0e5373fd Pavel Machek
1304 b9864aa8 Pavel Tvrdik
	<tag><label id="type-bgppath">bgppath</tag>
1305 dad92c30 Ondrej Zajicek
	BGP path is a list of autonomous system numbers. You can't write
1306
	literals of this type. There are several special operators on bgppaths:
1307 4cdd0784 Ondrej Zajicek
1308 dad92c30 Ondrej Zajicek
	<cf><m/P/.first</cf> returns the first ASN (the neighbor ASN) in path <m/P/.
1309 4cdd0784 Ondrej Zajicek
1310 dad92c30 Ondrej Zajicek
	<cf><m/P/.last</cf> returns the last ASN (the source ASN) in path <m/P/.
1311 4cdd0784 Ondrej Zajicek
1312 9c9cc35c Ondrej Zajicek (work)
	<cf><m/P/.last_nonaggregated</cf> returns the last ASN in the non-aggregated part of the path <m/P/.
1313
1314 dad92c30 Ondrej Zajicek
	Both <cf/first/ and <cf/last/ return zero if there is no appropriate
1315
	ASN, for example if the path contains an AS set element as the first (or
1316 9c9cc35c Ondrej Zajicek (work)
	the last) part. If the path ends with an AS set, <cf/last_nonaggregated/
1317
	may be used to get last ASN before any AS set.
1318 4cdd0784 Ondrej Zajicek
1319 dad92c30 Ondrej Zajicek
	<cf><m/P/.len</cf> returns the length of path <m/P/.
1320 4cdd0784 Ondrej Zajicek
1321 dad92c30 Ondrej Zajicek
	<cf>prepend(<m/P/,<m/A/)</cf> prepends ASN <m/A/ to path <m/P/ and
1322
	returns the result.
1323 bff9ce51 Ondrej Zajicek
1324 dad92c30 Ondrej Zajicek
	<cf>delete(<m/P/,<m/A/)</cf> deletes all instances of ASN <m/A/ from
1325
	from path <m/P/ and returns the result. <m/A/ may also be an integer
1326
	set, in that case the operator deletes all ASNs from path <m/P/ that are
1327
	also members of set <m/A/.
1328 bff9ce51 Ondrej Zajicek
1329 dad92c30 Ondrej Zajicek
	<cf>filter(<m/P/,<m/A/)</cf> deletes all ASNs from path <m/P/ that are
1330
	not members of integer set <m/A/. I.e., <cf/filter/ do the same as
1331
	<cf/delete/ with inverted set <m/A/.
1332 bff9ce51 Ondrej Zajicek
1333 dad92c30 Ondrej Zajicek
	Statement <cf><m/P/ = prepend(<m/P/, <m/A/);</cf> can be shortened to
1334
	<cf><m/P/.prepend(<m/A/);</cf> if <m/P/ is appropriate route attribute
1335
	(for example <cf/bgp_path/). Similarly for <cf/delete/ and <cf/filter/.
1336 4a5bb2bf Pavel Machek
1337 b9864aa8 Pavel Tvrdik
	<tag><label id="type-bgpmask">bgpmask</tag>
1338 dad92c30 Ondrej Zajicek
	BGP masks are patterns used for BGP path matching (using <cf>path
1339
	&tilde; [= 2 3 5 * =]</cf> syntax). The masks resemble wildcard patterns
1340
	as used by UNIX shells. Autonomous system numbers match themselves,
1341
	<cf/*/ matches any (even empty) sequence of arbitrary AS numbers and
1342 523f020b Ondrej Zajicek
	<cf/?/ matches one arbitrary AS number. For example, if <cf>bgp_path</cf>
1343 dad92c30 Ondrej Zajicek
 	is 4 3 2 1, then: <tt>bgp_path &tilde; [= * 4 3 * =]</tt> is true,
1344
	but <tt>bgp_path &tilde; [= * 4 5 * =]</tt> is false. BGP mask
1345
	expressions can also contain integer expressions enclosed in parenthesis
1346 a0fe1944 Ondrej Filip
	and integer variables, for example <tt>[= * 4 (1+2) a =]</tt>. You can
1347
        also use ranges, for example <tt>[= * 3..5 2 100..200 * =]</tt>.
1348
        There is also old (deprecated) syntax that uses / .. / instead of [= .. =]
1349
        and ? instead of *.
1350 4cdd0784 Ondrej Zajicek
1351 b9864aa8 Pavel Tvrdik
	<tag><label id="type-clist">clist</tag>
1352 dad92c30 Ondrej Zajicek
	Clist is similar to a set, except that unlike other sets, it can be
1353
	modified. The type is used for community list (a set of pairs) and for
1354
	cluster list (a set of quads). There exist no literals of this type.
1355
	There are three special operators on clists:
1356
1357
	<cf><m/C/.len</cf> returns the length of clist <m/C/.
1358
1359
	<cf>add(<m/C/,<m/P/)</cf> adds pair (or quad) <m/P/ to clist <m/C/ and
1360
	returns the result. If item <m/P/ is already in clist <m/C/, it does
1361
	nothing. <m/P/ may also be a clist, in that case all its members are
1362
	added; i.e., it works as clist union.
1363
1364
	<cf>delete(<m/C/,<m/P/)</cf> deletes pair (or quad) <m/P/ from clist
1365
	<m/C/ and returns the result. If clist <m/C/ does not contain item
1366
	<m/P/, it does nothing. <m/P/ may also be a pair (or quad) set, in that
1367
	case the operator deletes all items from clist <m/C/ that are also
1368
	members of set <m/P/. Moreover, <m/P/ may also be a clist, which works
1369
	analogously; i.e., it works as clist difference.
1370
1371
	<cf>filter(<m/C/,<m/P/)</cf> deletes all items from clist <m/C/ that are
1372
	not members of pair (or quad) set <m/P/. I.e., <cf/filter/ do the same
1373
	as <cf/delete/ with inverted set <m/P/. <m/P/ may also be a clist, which
1374
	works analogously; i.e., it works as clist intersection.
1375
1376
	Statement <cf><m/C/ = add(<m/C/, <m/P/);</cf> can be shortened to
1377
	<cf><m/C/.add(<m/P/);</cf> if <m/C/ is appropriate route attribute (for
1378
	example <cf/bgp_community/). Similarly for <cf/delete/ and <cf/filter/.
1379 8815d846 Ondrej Zajicek
1380 b9864aa8 Pavel Tvrdik
	<tag><label id="type-eclist">eclist</tag>
1381 dad92c30 Ondrej Zajicek
	Eclist is a data type used for BGP extended community lists. Eclists
1382
	are very similar to clists, but they are sets of ECs instead of pairs.
1383 768d5e10 Pavel Tvrdik
	The same operations (like <cf/add/, <cf/delete/ or <cf/&tilde;/ and
1384
	<cf/!&tilde;/ membership operators) can be used to modify or test
1385
	eclists, with ECs instead of pairs as arguments.
1386 cec4a73c Ondrej Zajicek (work)
1387 9b0a0ba9 Ondrej Zajicek (work)
	<tag><label id="type-lclist">lclist/</tag>
1388 cec4a73c Ondrej Zajicek (work)
	Lclist is a data type used for BGP large community lists. Like eclists,
1389
	lclists are very similar to clists, but they are sets of LCs instead of
1390
	pairs. The same operations (like <cf/add/, <cf/delete/ or <cf/&tilde;/
1391
	and <cf/!&tilde;/ membership operators) can be used to modify or test
1392
	lclists, with LCs instead of pairs as arguments.
1393 d37f899b Pavel Machek
</descrip>
1394
1395 dad92c30 Ondrej Zajicek
1396 a7c9f7c0 Pavel Machek
<sect>Operators
1397 b9864aa8 Pavel Tvrdik
<label id="operators">
1398 d37f899b Pavel Machek
1399 dad92c30 Ondrej Zajicek
<p>The filter language supports common integer operators <cf>(+,-,*,/)</cf>,
1400
parentheses <cf/(a*(b+c))/, comparison <cf/(a=b, a!=b, a&lt;b, a&gt;=b)/.
1401
Logical operations include unary not (<cf/!/), and (<cf/&amp;&amp;/) and or
1402 768d5e10 Pavel Tvrdik
(<cf/&verbar;&verbar;/). Special operators include (<cf/&tilde;/,
1403
<cf/!&tilde;/) for "is (not) element of a set" operation - it can be used on
1404
element and set of elements of the same type (returning true if element is
1405
contained in the given set), or on two strings (returning true if first string
1406
matches a shell-like pattern stored in second string) or on IP and prefix
1407
(returning true if IP is within the range defined by that prefix), or on prefix
1408
and prefix (returning true if first prefix is more specific than second one) or
1409
on bgppath and bgpmask (returning true if the path matches the mask) or on
1410
number and bgppath (returning true if the number is in the path) or on bgppath
1411
and int (number) set (returning true if any ASN from the path is in the set) or
1412
on pair/quad and clist (returning true if the pair/quad is element of the
1413
clist) or on clist and pair/quad set (returning true if there is an element of
1414
the clist that is also a member of the pair/quad set).
1415 dad92c30 Ondrej Zajicek
1416
<p>There is one operator related to ROA infrastructure - <cf/roa_check()/. It
1417 7935b9d2 Pavel Tvrdik
examines a ROA table and does <rfc id="6483"> route origin validation for a
1418
given network prefix. The basic usage is <cf>roa_check(<m/table/)</cf>, which
1419
checks current route (which should be from BGP to have AS_PATH argument) in the
1420 dad92c30 Ondrej Zajicek
specified ROA table and returns ROA_UNKNOWN if there is no relevant ROA,
1421
ROA_VALID if there is a matching ROA, or ROA_INVALID if there are some relevant
1422 af582c48 Ondrej Zajicek
ROAs but none of them match. There is also an extended variant
1423 dad92c30 Ondrej Zajicek
<cf>roa_check(<m/table/, <m/prefix/, <m/asn/)</cf>, which allows to specify a
1424
prefix and an ASN as arguments.
1425 af582c48 Ondrej Zajicek
1426 d37f899b Pavel Machek
1427 371adba6 Martin Mares
<sect>Control structures
1428 b9864aa8 Pavel Tvrdik
<label id="control-structures">
1429 d37f899b Pavel Machek
1430 523f020b Ondrej Zajicek
<p>Filters support two control structures: conditions and case switches.
1431 a7c9f7c0 Pavel Machek
1432 dad92c30 Ondrej Zajicek
<p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/command1/;
1433
else <m/command2/;</cf> and you can use <cf>{ <m/command_1/; <m/command_2/;
1434
<M>...</M> }</cf> instead of either command. The <cf>else</cf> clause may be
1435
omitted. If the <cf><m>boolean expression</m></cf> is true, <m/command1/ is
1436
executed, otherwise <m/command2/ is executed.
1437
1438
<p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case
1439
<m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [
1440
... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be
1441
on the left side of the &tilde; operator and anything that could be a member of
1442
a set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/
1443
grouping. If <cf><m/expr/</cf> matches one of the <cf/:/ clauses, statements
1444
between it and next <cf/:/ statement are executed. If <cf><m/expr/</cf> matches
1445
neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed.
1446 d37f899b Pavel Machek
1447 a7c9f7c0 Pavel Machek
<p>Here is example that uses <cf/if/ and <cf/case/ structures:
1448 af0b25d2 Pavel Machek
1449
<code>
1450
case arg1 {
1451
	2: print "two"; print "I can do more commands without {}";
1452
	3 .. 5: print "three to five";
1453
	else: print "something else";
1454 a7c9f7c0 Pavel Machek
}
1455 af0b25d2 Pavel Machek
1456 523f020b Ondrej Zajicek
if 1234 = i then printn "."; else {
1457
  print "not 1234";
1458
  print "You need {} around multiple commands";
1459 8798c811 Pavel Machek
}
1460 af0b25d2 Pavel Machek
</code>
1461
1462 dad92c30 Ondrej Zajicek
1463 371adba6 Martin Mares
<sect>Route attributes
1464 b9864aa8 Pavel Tvrdik
<label id="route-attributes">
1465 0e5373fd Pavel Machek
1466 dad92c30 Ondrej Zajicek
<p>A filter is implicitly passed a route, and it can access its attributes just
1467
like it accesses variables. Attempts to access undefined attribute result in a
1468
runtime error; you can check if an attribute is defined by using the
1469
<cf>defined( <m>attribute</m> )</cf> operator. One notable exception to this
1470
rule are attributes of clist type, where undefined value is regarded as empty
1471
clist for most purposes.
1472 a7c9f7c0 Pavel Machek
1473 36032ded Pavel Machek
<descrip>
1474 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-net"><m/prefix/ net</tag>
1475 dad92c30 Ondrej Zajicek
	Network the route is talking about. Read-only. (See the chapter about
1476
	routing tables.)
1477 a7c9f7c0 Pavel Machek
1478 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-scope"><m/enum/ scope</tag>
1479 dad92c30 Ondrej Zajicek
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes
1480
	local to this host, <cf/SCOPE_LINK/ for those specific for a physical
1481
	link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and
1482
	<cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not
1483
	interpreted by BIRD and can be used to mark routes in filters. The
1484
	default value for new routes is <cf/SCOPE_UNIVERSE/.
1485 0e5373fd Pavel Machek
1486 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-preference"><m/int/ preference</tag>
1487 dad92c30 Ondrej Zajicek
	Preference of the route. Valid values are 0-65535. (See the chapter
1488
	about routing tables.)
1489 c184d9d0 Pavel Machek
1490 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-from"><m/ip/ from</tag>
1491 00192d5a Ondrej Zajicek
	The router which the route has originated from.
1492 523f020b Ondrej Zajicek
1493 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-gw"><m/ip/ gw</tag>
1494 a7c9f7c0 Pavel Machek
	Next hop packets routed using this route should be forwarded to.
1495 0e5373fd Pavel Machek
1496 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-proto"><m/string/ proto</tag>
1497 dad92c30 Ondrej Zajicek
	The name of the protocol which the route has been imported from.
1498
	Read-only.
1499 e29fa06e Ondrej Zajicek
1500 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-source"><m/enum/ source</tag>
1501 dad92c30 Ondrej Zajicek
	what protocol has told me about this route. Possible values:
1502
	<cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/,
1503
	<cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/,
1504
	<cf/RTS_OSPF_IA/, <cf/RTS_OSPF_EXT1/, <cf/RTS_OSPF_EXT2/, <cf/RTS_BGP/,
1505 12640c14 Ondrej Zajicek (work)
	<cf/RTS_PIPE/, <cf/RTS_BABEL/.
1506 c184d9d0 Pavel Machek
1507 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-cast"><m/enum/ cast</tag>
1508 ff2857b0 Ondrej Zajicek
	Route type (Currently <cf/RTC_UNICAST/ for normal routes,
1509 dad92c30 Ondrej Zajicek
	<cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ will be used in
1510
	the future for broadcast, multicast and anycast routes). Read-only.
1511 c184d9d0 Pavel Machek
1512 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-dest"><m/enum/ dest</tag>
1513 182a7895 Ondrej Zajicek
	Type of destination the packets should be sent to
1514
	(<cf/RTD_ROUTER/ for forwarding to a neighboring router,
1515
	<cf/RTD_DEVICE/ for routing to a directly-connected network,
1516
	<cf/RTD_MULTIPATH/ for multipath destinations,
1517
	<cf/RTD_BLACKHOLE/ for packets to be silently discarded,
1518 dad92c30 Ondrej Zajicek
	<cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be
1519
	returned with ICMP host unreachable / ICMP administratively prohibited
1520
	messages). Can be changed, but only to <cf/RTD_BLACKHOLE/,
1521
	<cf/RTD_UNREACHABLE/ or <cf/RTD_PROHIBIT/.
1522 b74f45f8 Ondrej Zajicek
1523 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-ifname"><m/string/ ifname</tag>
1524 dad92c30 Ondrej Zajicek
	Name of the outgoing interface. Sink routes (like blackhole, unreachable
1525
	or prohibit) and multipath routes have no interface associated with
1526
	them, so <cf/ifname/ returns an empty string for such routes. Read-only.
1527 a5fc5958 Ondrej Zajicek
1528 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-ifindex"><m/int/ ifindex</tag>
1529 dad92c30 Ondrej Zajicek
	Index of the outgoing interface. System wide index of the interface. May
1530
	be used for interface matching, however indexes might change on interface
1531
	creation/removal. Zero is returned for routes with undefined outgoing
1532 a5fc5958 Ondrej Zajicek
	interfaces. Read-only.
1533
1534 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-igp-metric"><m/int/ igp_metric</tag>
1535 dad92c30 Ondrej Zajicek
	The optional attribute that can be used to specify a distance to the
1536
	network for routes that do not have a native protocol metric attribute
1537
	(like <cf/ospf_metric1/ for OSPF routes). It is used mainly by BGP to
1538
	compare internal distances to boundary routers (see below). It is also
1539
	used when the route is exported to OSPF as a default value for OSPF type
1540
	1 metric.
1541 ba1dda49 Pavel Machek
</descrip>
1542 0e5373fd Pavel Machek
1543 dad92c30 Ondrej Zajicek
<p>There also exist some protocol-specific attributes which are described in the
1544
corresponding protocol sections.
1545
1546 0e5373fd Pavel Machek
1547 1632f1fe Pavel Machek
<sect>Other statements
1548 b9864aa8 Pavel Tvrdik
<label id="other-statements">
1549 69477cad Pavel Machek
1550 a7c9f7c0 Pavel Machek
<p>The following statements are available:
1551 69477cad Pavel Machek
1552
<descrip>
1553 b9864aa8 Pavel Tvrdik
	<tag><label id="assignment"><m/variable/ = <m/expr/</tag>
1554 dad92c30 Ondrej Zajicek
	Set variable to a given value.
1555 326e33f5 Pavel Machek
1556 b9864aa8 Pavel Tvrdik
	<tag><label id="filter-accept-reject">accept|reject [ <m/expr/ ]</tag>
1557 dad92c30 Ondrej Zajicek
	Accept or reject the route, possibly printing <cf><m>expr</m></cf>.
1558 326e33f5 Pavel Machek
1559 b9864aa8 Pavel Tvrdik
	<tag><label id="return">return <m/expr/</tag>
1560 dad92c30 Ondrej Zajicek
	Return <cf><m>expr</m></cf> from the current function, the function ends
1561
	at this point.
1562 326e33f5 Pavel Machek
1563 b9864aa8 Pavel Tvrdik
	<tag><label id="print">print|printn <m/expr/ [<m/, expr.../]</tag>
1564 dad92c30 Ondrej Zajicek
	Prints given expressions; useful mainly while debugging filters. The
1565
	<cf/printn/ variant does not terminate the line.
1566 69477cad Pavel Machek
1567 b9864aa8 Pavel Tvrdik
	<tag><label id="quitbird">quitbird</tag>
1568 1632f1fe Pavel Machek
	Terminates BIRD. Useful when debugging the filter interpreter.
1569 69477cad Pavel Machek
</descrip>
1570
1571 dad92c30 Ondrej Zajicek
1572 371adba6 Martin Mares
<chapt>Protocols
1573 b9864aa8 Pavel Tvrdik
<label id="protocols">
1574 d37f899b Pavel Machek
1575 937e75d8 Ondrej Zajicek (work)
<sect>Babel
1576 b9864aa8 Pavel Tvrdik
<label id="babel">
1577 937e75d8 Ondrej Zajicek (work)
1578
<sect1>Introduction
1579 b9864aa8 Pavel Tvrdik
<label id="babel-intro">
1580 937e75d8 Ondrej Zajicek (work)
1581 7935b9d2 Pavel Tvrdik
<p>The Babel protocol
1582
(<rfc id="6126">) is a loop-avoiding distance-vector routing protocol that is
1583
robust and efficient both in ordinary wired networks and in wireless mesh
1584
networks. Babel is conceptually very simple in its operation and "just works"
1585
in its default configuration, though some configuration is possible and in some
1586
cases desirable.
1587 937e75d8 Ondrej Zajicek (work)
1588
<p>While the Babel protocol is dual stack (i.e., can carry both IPv4 and IPv6
1589
routes over the same IPv6 transport), BIRD presently implements only the IPv6
1590
subset of the protocol. No Babel extensions are implemented, but the BIRD
1591
implementation can coexist with implementations using the extensions (and will
1592
just ignore extension messages).
1593
1594
<p>The Babel protocol implementation in BIRD is currently in alpha stage.
1595
1596
<sect1>Configuration
1597 b9864aa8 Pavel Tvrdik
<label id="babel-config">
1598 937e75d8 Ondrej Zajicek (work)
1599
<p>Babel supports no global configuration options apart from those common to all
1600
other protocols, but supports the following per-interface configuration options:
1601
1602
<code>
1603
protocol babel [<name>] {
1604
	interface <interface pattern> {
1605
		type <wired|wireless>;
1606
		rxcost <number>;
1607
		hello interval <number>;
1608
		update interval <number>;
1609
		port <number>;
1610
		tx class|dscp <number>;
1611
		tx priority <number>;
1612
		rx buffer <number>;
1613
		tx length <number>;
1614
		check link <switch>;
1615
	};
1616
}
1617
</code>
1618
1619
<descrip>
1620 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-type">type wired|wireless </tag>
1621 937e75d8 Ondrej Zajicek (work)
      This option specifies the interface type: Wired or wireless. Wired
1622
      interfaces are considered more reliable, and so the default hello
1623
      interval is higher, and a neighbour is considered unreachable after only
1624
      a small number of "hello" packets are lost. On wireless interfaces,
1625
      hello packets are sent more often, and the ETX link quality estimation
1626
      technique is used to compute the metrics of routes discovered over this
1627
      interface. This technique will gradually degrade the metric of routes
1628
      when packets are lost rather than the more binary up/down mechanism of
1629
      wired type links. Default: <cf/wired/.
1630
1631 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-rxcost">rxcost <m/num/</tag>
1632 937e75d8 Ondrej Zajicek (work)
      This specifies the RX cost of the interface. The route metrics will be
1633
      computed from this value with a mechanism determined by the interface
1634
      <cf/type/. Default: 96 for wired interfaces, 256 for wireless.
1635
1636 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-hello">hello interval <m/num/</tag>
1637 937e75d8 Ondrej Zajicek (work)
      Interval at which periodic "hello" messages are sent on this interface,
1638
      in seconds. Default: 4 seconds.
1639
1640 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-update">update interval <m/num/</tag>
1641 937e75d8 Ondrej Zajicek (work)
      Interval at which periodic (full) updates are sent. Default: 4 times the
1642
      hello interval.
1643
1644 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-port">port <m/number/</tag>
1645 937e75d8 Ondrej Zajicek (work)
      This option selects an UDP port to operate on. The default is to operate
1646
      on port 6696 as specified in the Babel RFC.
1647
1648 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-tx-class">tx class|dscp|priority <m/number/</tag>
1649 937e75d8 Ondrej Zajicek (work)
      These options specify the ToS/DiffServ/Traffic class/Priority of the
1650 b9864aa8 Pavel Tvrdik
      outgoing Babel packets. See <ref id="proto-tx-class" name="tx class"> common
1651 937e75d8 Ondrej Zajicek (work)
      option for detailed description.
1652
1653 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-rx-buffer">rx buffer <m/number/</tag>
1654 937e75d8 Ondrej Zajicek (work)
      This option specifies the size of buffers used for packet processing.
1655
      The buffer size should be bigger than maximal size of received packets.
1656
      The default value is the interface MTU, and the value will be clamped to a
1657
      minimum of 512 bytes + IP packet overhead.
1658
1659 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-tx-length">tx length <m/number/</tag>
1660 937e75d8 Ondrej Zajicek (work)
      This option specifies the maximum length of generated Babel packets. To
1661
      avoid IP fragmentation, it should not exceed the interface MTU value.
1662
      The default value is the interface MTU value, and the value will be
1663
      clamped to a minimum of 512 bytes + IP packet overhead.
1664
1665 b9864aa8 Pavel Tvrdik
      <tag><label id="babel-check-link">check link <m/switch/</tag>
1666 937e75d8 Ondrej Zajicek (work)
      If set, the hardware link state (as reported by OS) is taken into
1667
      consideration. When the link disappears (e.g. an ethernet cable is
1668
      unplugged), neighbors are immediately considered unreachable and all
1669
      routes received from them are withdrawn. It is possible that some
1670
      hardware drivers or platforms do not implement this feature. Default:
1671
      yes.
1672
</descrip>
1673
1674 12640c14 Ondrej Zajicek (work)
<sect1>Attributes
1675 b9864aa8 Pavel Tvrdik
<label id="babel-attr">
1676 12640c14 Ondrej Zajicek (work)
1677
<p>Babel defines just one attribute: the internal babel metric of the route. It
1678
is exposed as the <cf/babel_metric/ attribute and has range from 1 to infinity
1679
(65535).
1680
1681
<sect1>Example
1682 b9864aa8 Pavel Tvrdik
<label id="babel-exam">
1683 12640c14 Ondrej Zajicek (work)
1684
<p><code>
1685
protocol babel {
1686
	interface "eth*" {
1687
		type wired;
1688
	};
1689
	interface "wlan0", "wlan1" {
1690
		type wireless;
1691
		hello interval 1;
1692
		rxcost 512;
1693
	};
1694
	interface "tap0";
1695
1696
	# This matches the default of babeld: redistribute all addresses
1697
	# configured on local interfaces, plus re-distribute all routes received
1698
	# from other babel peers.
1699
1700
	export where (source = RTS_DEVICE) || (source = RTS_BABEL);
1701
}
1702
</code>
1703
1704 937e75d8 Ondrej Zajicek (work)
1705 5bf35a9a Pavel Tvrdik
<sect>BFD
1706 b9864aa8 Pavel Tvrdik
<label id="bfd">
1707 1ec52253 Ondrej Zajicek
1708
<sect1>Introduction
1709 b9864aa8 Pavel Tvrdik
<label id="bfd-intro">
1710 1ec52253 Ondrej Zajicek
1711
<p>Bidirectional Forwarding Detection (BFD) is not a routing protocol itself, it
1712
is an independent tool providing liveness and failure detection. Routing
1713
protocols like OSPF and BGP use integrated periodic "hello" messages to monitor
1714
liveness of neighbors, but detection times of these mechanisms are high (e.g. 40
1715
seconds by default in OSPF, could be set down to several seconds). BFD offers
1716
universal, fast and low-overhead mechanism for failure detection, which could be
1717
attached to any routing protocol in an advisory role.
1718
1719
<p>BFD consists of mostly independent BFD sessions. Each session monitors an
1720
unicast bidirectional path between two BFD-enabled routers. This is done by
1721
periodically sending control packets in both directions. BFD does not handle
1722
neighbor discovery, BFD sessions are created on demand by request of other
1723
protocols (like OSPF or BGP), which supply appropriate information like IP
1724
addresses and associated interfaces. When a session changes its state, these
1725
protocols are notified and act accordingly (e.g. break an OSPF adjacency when
1726
the BFD session went down).
1727
1728 7935b9d2 Pavel Tvrdik
<p>BIRD implements basic BFD behavior as defined in <rfc id="5880"> (some
1729
advanced features like the echo mode or authentication are not implemented), IP
1730
transport for BFD as defined in <rfc id="5881"> and <rfc id="5883"> and
1731
interaction with client protocols as defined in <rfc id="5882">.
1732 1ec52253 Ondrej Zajicek
1733
<p>Note that BFD implementation in BIRD is currently a new feature in
1734
development, expect some rough edges and possible UI and configuration changes
1735
in the future. Also note that we currently support at most one protocol instance.
1736
1737 d96ec7f6 Ondrej Zajicek
<p>BFD packets are sent with a dynamic source port number. Linux systems use by
1738
default a bit different dynamic port range than the IANA approved one
1739
(49152-65535). If you experience problems with compatibility, please adjust
1740
<cf>/proc/sys/net/ipv4/ip_local_port_range</cf>
1741
1742 1ec52253 Ondrej Zajicek
<sect1>Configuration
1743 b9864aa8 Pavel Tvrdik
<label id="bfd-config">
1744 1ec52253 Ondrej Zajicek
1745
<p>BFD configuration consists mainly of multiple definitions of interfaces.
1746
Most BFD config options are session specific. When a new session is requested
1747
and dynamically created, it is configured from one of these definitions. For
1748
sessions to directly connected neighbors, <cf/interface/ definitions are chosen
1749
based on the interface associated with the session, while <cf/multihop/
1750
definition is used for multihop sessions. If no definition is relevant, the
1751
session is just created with the default configuration. Therefore, an empty BFD
1752
configuration is often sufficient.
1753
1754
<p>Note that to use BFD for other protocols like OSPF or BGP, these protocols
1755
also have to be configured to request BFD sessions, usually by <cf/bfd/ option.
1756
1757
<p>Some of BFD session options require <m/time/ value, which has to be specified
1758
with the appropriate unit: <m/num/ <cf/s/|<cf/ms/|<cf/us/. Although microseconds
1759
are allowed as units, practical minimum values are usually in order of tens of
1760
milliseconds.
1761
1762
<code>
1763
protocol bfd [&lt;name&gt;] {
1764
	interface &lt;interface pattern&gt; {
1765
		interval &lt;time&gt;;
1766
		min rx interval &lt;time&gt;;
1767
		min tx interval &lt;time&gt;;
1768
		idle tx interval &lt;time&gt;;
1769
		multiplier &lt;num&gt;;
1770
		passive &lt;switch&gt;;
1771 e03dc6a9 Ondrej Zajicek (work)
		authentication none;
1772
		authentication simple;
1773
		authentication [meticulous] keyed md5|sha1;
1774
		password "&lt;text&gt;";
1775
		password "&lt;text&gt;" {
1776
			id &lt;num&gt;;
1777
			generate from "&lt;date&gt;";
1778
			generate to "&lt;date&gt;";
1779
			accept from "&lt;date&gt;";
1780
			accept to "&lt;date&gt;";
1781
			from "&lt;date&gt;";
1782
			to "&lt;date&gt;";
1783
		};
1784 1ec52253 Ondrej Zajicek
	};
1785
	multihop {
1786
		interval &lt;time&gt;;
1787
		min rx interval &lt;time&gt;;
1788
		min tx interval &lt;time&gt;;
1789
		idle tx interval &lt;time&gt;;
1790
		multiplier &lt;num&gt;;
1791
		passive &lt;switch&gt;;
1792
	};
1793
	neighbor &lt;ip&gt; [dev "&lt;interface&gt;"] [local &lt;ip&gt;] [multihop &lt;switch&gt;];
1794
}
1795
</code>
1796
1797
<descrip>
1798 9df52a98 Pavel Tvrdik
	<tag><label id="bfd-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
1799 1ec52253 Ondrej Zajicek
	Interface definitions allow to specify options for sessions associated
1800
	with such interfaces and also may contain interface specific options.
1801 b9864aa8 Pavel Tvrdik
	See <ref id="proto-iface" name="interface"> common option for a detailed
1802 1ec52253 Ondrej Zajicek
	description of interface patterns. Note that contrary to the behavior of
1803
	<cf/interface/ definitions of other protocols, BFD protocol would accept
1804
	sessions (in default configuration) even on interfaces not covered by
1805
	such definitions.
1806
1807 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-multihop">multihop { <m/options/ }</tag>
1808 1ec52253 Ondrej Zajicek
	Multihop definitions allow to specify options for multihop BFD sessions,
1809
	in the same manner as <cf/interface/ definitions are used for directly
1810
	connected sessions. Currently only one such definition (for all multihop
1811
	sessions) could be used.
1812
1813 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-neighbor">neighbor <m/ip/ [dev "<m/interface/"] [local <m/ip/] [multihop <m/switch/]</tag>
1814 1ec52253 Ondrej Zajicek
	BFD sessions are usually created on demand as requested by other
1815
	protocols (like OSPF or BGP). This option allows to explicitly add
1816
	a BFD session to the specified neighbor regardless of such requests.
1817 523f020b Ondrej Zajicek
1818 1ec52253 Ondrej Zajicek
	The session is identified by the IP address of the neighbor, with
1819 dad92c30 Ondrej Zajicek
	optional specification of used interface and local IP. By default
1820 fff7498d Pavel Tvrdik
	the neighbor must be directly connected, unless the session is
1821 1ec52253 Ondrej Zajicek
	configured as multihop. Note that local IP must be specified for
1822
	multihop sessions.
1823
</descrip>
1824
1825
<p>Session specific options (part of <cf/interface/ and <cf/multihop/ definitions):
1826
1827
<descrip>
1828 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-interval">interval <m/time/</tag>
1829 1ec52253 Ondrej Zajicek
	BFD ensures availability of the forwarding path associated with the
1830
	session by periodically sending BFD control packets in both
1831
	directions. The rate of such packets is controlled by two options,
1832
	<cf/min rx interval/ and <cf/min tx interval/ (see below). This option
1833
	is just a shorthand to set both of these options together.
1834
1835 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-min-rx-interval">min rx interval <m/time/</tag>
1836 1ec52253 Ondrej Zajicek
	This option specifies the minimum RX interval, which is announced to the
1837
	neighbor and used there to limit the neighbor's rate of generated BFD
1838
	control packets. Default: 10 ms.
1839
1840 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-min-tx-interval">min tx interval <m/time/</tag>
1841 1ec52253 Ondrej Zajicek
	This option specifies the desired TX interval, which controls the rate
1842
	of generated BFD control packets (together with <cf/min rx interval/
1843
	announced by the neighbor). Note that this value is used only if the BFD
1844
	session is up, otherwise the value of <cf/idle tx interval/ is used
1845
	instead. Default: 100 ms.
1846
1847 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-idle-tx-interval">idle tx interval <m/time/</tag>
1848 1ec52253 Ondrej Zajicek
	In order to limit unnecessary traffic in cases where a neighbor is not
1849
	available or not running BFD, the rate of generated BFD control packets
1850
	is lower when the BFD session is not up. This option specifies the
1851
	desired TX interval in such cases instead of <cf/min tx interval/.
1852
	Default: 1 s.
1853
1854 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-multiplier">multiplier <m/num/</tag>
1855 1ec52253 Ondrej Zajicek
	Failure detection time for BFD sessions is based on established rate of
1856
	BFD control packets (<cf>min rx/tx interval</cf>) multiplied by this
1857
	multiplier, which is essentially (ignoring jitter) a number of missed
1858
	packets after which the session is declared down. Note that rates and
1859
	multipliers could be different in each direction of a BFD session.
1860
	Default: 5.
1861
1862 b9864aa8 Pavel Tvrdik
	<tag><label id="bfd-passive">passive <m/switch/</tag>
1863 fff7498d Pavel Tvrdik
	Generally, both BFD session endpoints try to establish the session by
1864 1ec52253 Ondrej Zajicek
	sending control packets to the other side. This option allows to enable
1865
	passive mode, which means that the router does not send BFD packets
1866
	until it has received one from the other side. Default: disabled.
1867 e03dc6a9 Ondrej Zajicek (work)
1868
	<tag>authentication none</tag>
1869
	No passwords are sent in BFD packets. This is the default value.
1870
1871
	<tag>authentication simple</tag>
1872
	Every packet carries 16 bytes of password. Received packets lacking this
1873
	password are ignored. This authentication mechanism is very weak.
1874
1875
	<tag>authentication [meticulous] keyed md5|sha1</tag>
1876
	An authentication code is appended to each packet. The cryptographic
1877
	algorithm is keyed MD5 or keyed SHA-1. Note that the algorithm is common
1878
	for all keys (on one interface), in contrast to OSPF or RIP, where it
1879
	is a per-key option. Passwords (keys) are not sent open via network.
1880
1881
	The <cf/meticulous/ variant means that cryptographic sequence numbers
1882
	are increased for each sent packet, while in the basic variant they are
1883
	increased about once per second. Generally, the <cf/meticulous/ variant
1884
	offers better resistance to replay attacks but may require more
1885
	computation.
1886
1887
	<tag>password "<M>text</M>"</tag>
1888
	Specifies a password used for authentication. See <ref id="dsc-pass"
1889
	name="password"> common option for detailed description. Note that
1890
	password option <cf/algorithm/ is not available in BFD protocol. The
1891
	algorithm is selected by <cf/authentication/ option for all passwords.
1892
1893 1ec52253 Ondrej Zajicek
</descrip>
1894
1895
<sect1>Example
1896 b9864aa8 Pavel Tvrdik
<label id="bfd-exam">
1897 1ec52253 Ondrej Zajicek
1898
<p><code>
1899
protocol bfd {
1900
	interface "eth*" {
1901
		min rx interval 20 ms;
1902
		min tx interval 50 ms;
1903
		idle tx interval 300 ms;
1904
	};
1905
	interface "gre*" {
1906
		interval 200 ms;
1907
		multiplier 10;
1908
		passive;
1909
	};
1910
	multihop {
1911
		interval 200 ms;
1912
		multiplier 10;
1913
	};
1914
1915
	neighbor 192.168.1.10;
1916
	neighbor 192.168.2.2 dev "eth2";
1917
	neighbor 192.168.10.1 local 192.168.1.1 multihop;
1918
}
1919
</code>
1920
1921 dad92c30 Ondrej Zajicek
1922 371adba6 Martin Mares
<sect>BGP
1923 b9864aa8 Pavel Tvrdik
<label id="bgp">
1924 1b55b1a3 Martin Mares
1925 dad92c30 Ondrej Zajicek
<p>The Border Gateway Protocol is the routing protocol used for backbone level
1926
routing in the today's Internet. Contrary to other protocols, its convergence
1927
does not rely on all routers following the same rules for route selection,
1928
making it possible to implement any routing policy at any router in the network,
1929
the only restriction being that if a router advertises a route, it must accept
1930
and forward packets according to it.
1931
1932
<p>BGP works in terms of autonomous systems (often abbreviated as AS). Each AS
1933
is a part of the network with common management and common routing policy. It is
1934
identified by a unique 16-bit number (ASN). Routers within each AS usually
1935
exchange AS-internal routing information with each other using an interior
1936
gateway protocol (IGP, such as OSPF or RIP). Boundary routers at the border of
1937
the AS communicate global (inter-AS) network reachability information with their
1938
neighbors in the neighboring AS'es via exterior BGP (eBGP) and redistribute
1939
received information to other routers in the AS via interior BGP (iBGP).
1940
1941
<p>Each BGP router sends to its neighbors updates of the parts of its routing
1942
table it wishes to export along with complete path information (a list of AS'es
1943
the packet will travel through if it uses the particular route) in order to
1944
avoid routing loops.
1945 56ab03c7 Martin Mares
1946 5459fac6 Martin Mares
<p>BIRD supports all requirements of the BGP4 standard as defined in
1947 7935b9d2 Pavel Tvrdik
<rfc id="4271"> It also supports the community attributes (<rfc id="1997">),
1948
capability negotiation (<rfc id="5492">), MD5 password authentication (<rfc
1949
id="2385">), extended communities (<rfc id="4360">), route reflectors (<rfc
1950
id="4456">), graceful restart (<rfc id="4724">), multiprotocol extensions
1951
(<rfc id="4760">), 4B AS numbers (<rfc id="4893">), and 4B AS numbers in
1952
extended communities (<rfc id="5668">).
1953 1adc17b4 Ondrej Zajicek
1954
1955 5459fac6 Martin Mares
For IPv6, it uses the standard multiprotocol extensions defined in
1956 7935b9d2 Pavel Tvrdik
<rfc id="4760"> and applied to IPv6 according to <rfc id="2545">.
1957 5459fac6 Martin Mares
1958 371adba6 Martin Mares
<sect1>Route selection rules
1959 b9864aa8 Pavel Tvrdik
<label id="bgp-route-select-rules">
1960 5459fac6 Martin Mares
1961
<p>BGP doesn't have any simple metric, so the rules for selection of an optimal
1962
route among multiple BGP routes with the same preference are a bit more complex
1963 dad92c30 Ondrej Zajicek
and they are implemented according to the following algorithm. It starts the
1964
first rule, if there are more "best" routes, then it uses the second rule to
1965
choose among them and so on.
1966 5459fac6 Martin Mares
1967
<itemize>
1968 5a203dac Pavel Machek
	<item>Prefer route with the highest Local Preference attribute.
1969 5459fac6 Martin Mares
	<item>Prefer route with the shortest AS path.
1970 b74f45f8 Ondrej Zajicek
	<item>Prefer IGP origin over EGP and EGP origin over incomplete.
1971 5459fac6 Martin Mares
	<item>Prefer the lowest value of the Multiple Exit Discriminator.
1972 b74f45f8 Ondrej Zajicek
	<item>Prefer routes received via eBGP over ones received via iBGP.
1973
	<item>Prefer routes with lower internal distance to a boundary router.
1974 5a203dac Pavel Machek
	<item>Prefer the route with the lowest value of router ID of the
1975 5459fac6 Martin Mares
	advertising router.
1976
</itemize>
1977 56ab03c7 Martin Mares
1978 b74f45f8 Ondrej Zajicek
<sect1>IGP routing table
1979 b9864aa8 Pavel Tvrdik
<label id="bgp-igp-routing-table">
1980 b74f45f8 Ondrej Zajicek
1981 dad92c30 Ondrej Zajicek
<p>BGP is mainly concerned with global network reachability and with routes to
1982
other autonomous systems. When such routes are redistributed to routers in the
1983
AS via BGP, they contain IP addresses of a boundary routers (in route attribute
1984
NEXT_HOP). BGP depends on existing IGP routing table with AS-internal routes to
1985
determine immediate next hops for routes and to know their internal distances to
1986
boundary routers for the purpose of BGP route selection. In BIRD, there is
1987
usually one routing table used for both IGP routes and BGP routes.
1988 b74f45f8 Ondrej Zajicek
1989 371adba6 Martin Mares
<sect1>Configuration
1990 b9864aa8 Pavel Tvrdik
<label id="bgp-config">
1991 56ab03c7 Martin Mares
1992 dad92c30 Ondrej Zajicek
<p>Each instance of the BGP corresponds to one neighboring router. This allows
1993
to set routing policy and all the other parameters differently for each neighbor
1994
using the following configuration parameters:
1995 5459fac6 Martin Mares
1996
<descrip>
1997 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-local">local [<m/ip/] as <m/number/</tag>
1998 dad92c30 Ondrej Zajicek
	Define which AS we are part of. (Note that contrary to other IP routers,
1999
	BIRD is able to act as a router located in multiple AS'es simultaneously,
2000
	but in such cases you need to tweak the BGP paths manually in the filters
2001
	to get consistent behavior.) Optional <cf/ip/ argument specifies a source
2002
	address, equivalent to the <cf/source address/ option (see below). This
2003 f3e59178 Ondrej Zajicek
	parameter is mandatory.
2004
2005 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-neighbor">neighbor [<m/ip/] [port <m/number/] [as <m/number/]</tag>
2006 dad92c30 Ondrej Zajicek
	Define neighboring router this instance will be talking to and what AS
2007 a1beb8f3 Ondrej Zajicek
	it is located in. In case the neighbor is in the same AS as we are, we
2008
	automatically switch to iBGP. Optionally, the remote port may also be
2009
	specified. The parameter may be used multiple times with different
2010
	sub-options (e.g., both <cf/neighbor 10.0.0.1 as 65000;/ and
2011
	<cf/neighbor 10.0.0.1; neighbor as 65000;/ are valid). This parameter is
2012
	mandatory.
2013
2014 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-iface">interface <m/string/</tag>
2015 a1beb8f3 Ondrej Zajicek
	Define interface we should use for link-local BGP IPv6 sessions.
2016
	Interface can also be specified as a part of <cf/neighbor address/
2017
	(e.g., <cf/neighbor fe80::1234%eth0 as 65000;/). It is an error to use
2018
	this parameter for non link-local sessions.
2019 dad92c30 Ondrej Zajicek
2020 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-direct">direct</tag>
2021 dad92c30 Ondrej Zajicek
	Specify that the neighbor is directly connected. The IP address of the
2022
	neighbor must be from a directly reachable IP range (i.e. associated
2023
	with one of your router's interfaces), otherwise the BGP session
2024
	wouldn't start but it would wait for such interface to appear. The
2025
	alternative is the <cf/multihop/ option. Default: enabled for eBGP.
2026
2027 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-multihop">multihop [<m/number/]</tag>
2028 dad92c30 Ondrej Zajicek
	Configure multihop BGP session to a neighbor that isn't directly
2029
	connected. Accurately, this option should be used if the configured
2030
	neighbor IP address does not match with any local network subnets. Such
2031
	IP address have to be reachable through system routing table. The
2032
	alternative is the <cf/direct/ option. For multihop BGP it is
2033
	recommended to explicitly configure the source address to have it
2034
	stable. Optional <cf/number/ argument can be used to specify the number
2035
	of hops (used for TTL). Note that the number of networks (edges) in a
2036
	path is counted; i.e., if two BGP speakers are separated by one router,
2037
	the number of hops is 2. Default: enabled for iBGP.
2038
2039 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-source-address">source address <m/ip/</tag>
2040 dad92c30 Ondrej Zajicek
	Define local address we should use for next hop calculation and as a
2041
	source address for the BGP session. Default: the address of the local
2042 9be9a264 Ondrej Zajicek
	end of the interface our neighbor is connected to.
2043
2044 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-next-hop-self">next hop self</tag>
2045 dad92c30 Ondrej Zajicek
	Avoid calculation of the Next Hop attribute and always advertise our own
2046
	source address as a next hop. This needs to be used only occasionally to
2047
	circumvent misconfigurations of other routers. Default: disabled.
2048
2049 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-next-hop-keep">next hop keep</tag>
2050 dad92c30 Ondrej Zajicek
	Forward the received Next Hop attribute even in situations where the
2051
	local address should be used instead, like when the route is sent to an
2052
	interface with a different subnet. Default: disabled.
2053
2054 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-missing-lladdr">missing lladdr self|drop|ignore</tag>
2055 dad92c30 Ondrej Zajicek
	Next Hop attribute in BGP-IPv6 sometimes contains just the global IPv6
2056
	address, but sometimes it has to contain both global and link-local IPv6
2057
	addresses. This option specifies what to do if BIRD have to send both
2058
	addresses but does not know link-local address. This situation might
2059
	happen when routes from other protocols are exported to BGP, or when
2060
	improper updates are received from BGP peers. <cf/self/ means that BIRD
2061
	advertises its own local address instead. <cf/drop/ means that BIRD
2062
	skips that prefixes and logs error. <cf/ignore/ means that BIRD ignores
2063
	the problem and sends just the global address (and therefore forms
2064
	improper BGP update). Default: <cf/self/, unless BIRD is configured as a
2065
	route server (option <cf/rs client/), in that case default is <cf/ignore/,
2066
	because route servers usually do not forward packets themselves.
2067
2068 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-gateway">gateway direct|recursive</tag>
2069 dad92c30 Ondrej Zajicek
	For received routes, their <cf/gw/ (immediate next hop) attribute is
2070
	computed from received <cf/bgp_next_hop/ attribute. This option
2071
	specifies how it is computed. Direct mode means that the IP address from
2072
	<cf/bgp_next_hop/ is used if it is directly reachable, otherwise the
2073
	neighbor IP address is used. Recursive mode means that the gateway is
2074
	computed by an IGP routing table lookup for the IP address from
2075 6683d42d Ondrej Zajicek
	<cf/bgp_next_hop/. Note that there is just one level of indirection in
2076
	recursive mode - the route obtained by the lookup must not be recursive
2077
	itself, to prevent mutually recursive routes.
2078
2079
	Recursive mode is the behavior specified by the BGP
2080 dad92c30 Ondrej Zajicek
	standard. Direct mode is simpler, does not require any routes in a
2081
	routing table, and was used in older versions of BIRD, but does not
2082
	handle well nontrivial iBGP setups and multihop. Recursive mode is
2083 b9864aa8 Pavel Tvrdik
	incompatible with <ref id="dsc-table-sorted" name="sorted tables">. Default:
2084 dad92c30 Ondrej Zajicek
	<cf/direct/ for direct sessions, <cf/recursive/ for multihop sessions.
2085
2086 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-igp-table">igp table <m/name/</tag>
2087 dad92c30 Ondrej Zajicek
	Specifies a table that is used as an IGP routing table. Default: the
2088
	same as the table BGP is connected to.
2089 1ec52253 Ondrej Zajicek
2090 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-check-link">check link <M>switch</M></tag>
2091 523f020b Ondrej Zajicek
	BGP could use hardware link state into consideration.  If enabled,
2092
	BIRD tracks the link state of the associated interface and when link
2093
	disappears (e.g. an ethernet cable is unplugged), the BGP session is
2094
	immediately shut down. Note that this option cannot be used with
2095
	multihop BGP. Default: disabled.
2096
2097 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-bfd">bfd <M>switch</M></tag>
2098 1ec52253 Ondrej Zajicek
	BGP could use BFD protocol as an advisory mechanism for neighbor
2099
	liveness and failure detection. If enabled, BIRD setups a BFD session
2100
	for the BGP neighbor and tracks its liveness by it. This has an
2101
	advantage of an order of magnitude lower detection times in case of
2102
	failure. Note that BFD protocol also has to be configured, see
2103 b9864aa8 Pavel Tvrdik
	<ref id="bfd" name="BFD"> section for details. Default: disabled.
2104 1ec52253 Ondrej Zajicek
2105 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-ttl-security">ttl security <m/switch/</tag>
2106 7935b9d2 Pavel Tvrdik
	Use GTSM (<rfc id="5082"> - the generalized TTL security mechanism). GTSM
2107
	protects against spoofed packets by ignoring received packets with a
2108 dad92c30 Ondrej Zajicek
	smaller than expected TTL. To work properly, GTSM have to be enabled on
2109 7935b9d2 Pavel Tvrdik
	both sides of a BGP session. If both <cf/ttl security/ and
2110
	<cf/multihop/ options are enabled, <cf/multihop/ option should specify
2111
	proper hop value to compute expected TTL. Kernel support required:
2112
	Linux: 2.6.34+ (IPv4), 2.6.35+ (IPv6), BSD: since long ago, IPv4 only.
2113
	Note that full (ICMP protection, for example) <rfc id="5082"> support is
2114
	provided by Linux only. Default: disabled.
2115 523f020b Ondrej Zajicek
2116 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-pass">password <m/string/</tag>
2117 7935b9d2 Pavel Tvrdik
	Use this password for MD5 authentication of BGP sessions (<rfc id="2385">). When
2118
	used on BSD systems, see also <cf/setkey/ option below. Default: no
2119
	authentication.
2120 a7baa098 Ondrej Zajicek (work)
2121 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-setkey">setkey <m/switch/</tag>
2122 a7baa098 Ondrej Zajicek (work)
	On BSD systems, keys for TCP MD5 authentication are stored in the global
2123
	SA/SP database, which can be accessed by external utilities (e.g.
2124
	setkey(8)). BIRD configures security associations in the SA/SP database
2125
	automatically based on <cf/password/ options (see above), this option
2126
	allows to disable automatic updates by BIRD when manual configuration by
2127
	external utilities is preferred. Note that automatic SA/SP database
2128
	updates are currently implemented only for FreeBSD. Passwords have to be
2129
	set manually by an external utility on NetBSD and OpenBSD. Default:
2130
	enabled (ignored on non-FreeBSD).
2131 dad92c30 Ondrej Zajicek
2132 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-passive">passive <m/switch/</tag>
2133 dad92c30 Ondrej Zajicek
	Standard BGP behavior is both initiating outgoing connections and
2134 7935b9d2 Pavel Tvrdik
	accepting incoming connections. In passive mode, outgoing connections
2135 dad92c30 Ondrej Zajicek
	are not initiated. Default: off.
2136
2137 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-rr-client">rr client</tag>
2138 dad92c30 Ondrej Zajicek
	Be a route reflector and treat the neighbor as a route reflection
2139
	client. Default: disabled.
2140
2141 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-rr-cluster-id">rr cluster id <m/IPv4 address/</tag>
2142 dad92c30 Ondrej Zajicek
	Route reflectors use cluster id to avoid route reflection loops. When
2143
	there is one route reflector in a cluster it usually uses its router id
2144
	as a cluster id, but when there are more route reflectors in a cluster,
2145
	these need to be configured (using this option) to use a common cluster
2146
	id. Clients in a cluster need not know their cluster id and this option
2147
	is not allowed for them. Default: the same as router id.
2148
2149 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-rs-client">rs client</tag>
2150 dad92c30 Ondrej Zajicek
	Be a route server and treat the neighbor as a route server client.
2151
	A route server is used as a replacement for full mesh EBGP routing in
2152
	Internet exchange points in a similar way to route reflectors used in
2153 7935b9d2 Pavel Tvrdik
	IBGP routing. BIRD does not implement obsoleted <rfc id="1863">, but
2154
	uses ad-hoc implementation, which behaves like plain EBGP but reduces
2155 dad92c30 Ondrej Zajicek
	modifications to advertised route attributes to be transparent (for
2156 7935b9d2 Pavel Tvrdik
	example does not prepend its AS number to AS PATH attribute and
2157
	keeps MED attribute). Default: disabled.
2158 dad92c30 Ondrej Zajicek
2159 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-secondary">secondary <m/switch/</tag>
2160 dad92c30 Ondrej Zajicek
	Usually, if an export filter rejects a selected route, no other route is
2161
	propagated for that network. This option allows to try the next route in
2162
	order until one that is accepted is found or all routes for that network
2163
	are rejected. This can be used for route servers that need to propagate
2164
	different tables to each client but do not want to have these tables
2165
	explicitly (to conserve memory). This option requires that the connected
2166 b9864aa8 Pavel Tvrdik
	routing table is <ref id="dsc-table-sorted" name="sorted">. Default: off.
2167 48cf5e84 Ondrej Zajicek
2168 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-add-paths">add paths <m/switch/|rx|tx</tag>
2169 10115b1d Ondrej Zajicek
	Standard BGP can propagate only one path (route) per destination network
2170
	(usually the selected one). This option controls the add-path protocol
2171
	extension, which allows to advertise any number of paths to a
2172
	destination. Note that to be active, add-path has to be enabled on both
2173
	sides of the BGP session, but it could be enabled separately for RX and
2174
	TX direction. When active, all available routes accepted by the export
2175
	filter are advertised to the neighbor. Default: off.
2176
2177 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-allow-local-as">allow local as [<m/number/]</tag>
2178 dad92c30 Ondrej Zajicek
	BGP prevents routing loops by rejecting received routes with the local
2179
	AS number in the AS path. This option allows to loose or disable the
2180
	check. Optional <cf/number/ argument can be used to specify the maximum
2181
	number of local ASNs in the AS path that is allowed for received
2182
	routes. When the option is used without the argument, the check is
2183
	completely disabled and you should ensure loop-free behavior by some
2184
	other means. Default: 0 (no local AS number allowed).
2185
2186 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-enable-route-refresh">enable route refresh <m/switch/</tag>
2187 9aed29e6 Ondrej Zajicek
	After the initial route exchange, BGP protocol uses incremental updates
2188
	to keep BGP speakers synchronized. Sometimes (e.g., if BGP speaker
2189
	changes its import filter, or if there is suspicion of inconsistency) it
2190
	is necessary to do a new complete route exchange. BGP protocol extension
2191 7935b9d2 Pavel Tvrdik
	Route Refresh (<rfc id="2918">) allows BGP speaker to request
2192
	re-advertisement of all routes from its neighbor. BGP protocol
2193
	extension Enhanced Route Refresh (<rfc id="7313">) specifies explicit
2194
	begin and end for such exchanges, therefore the receiver can remove
2195
	stale routes that were not advertised during the exchange. This option
2196
	specifies whether BIRD advertises these capabilities and supports
2197
	related procedures. Note that even when disabled, BIRD can send route
2198
	refresh requests.  Default: on.
2199 bf47fe4b Ondrej Zajicek
2200 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-graceful-restart">graceful restart <m/switch/|aware</tag>
2201 6eda3f13 Ondrej Zajicek
	When a BGP speaker restarts or crashes, neighbors will discard all
2202
	received paths from the speaker, which disrupts packet forwarding even
2203 7935b9d2 Pavel Tvrdik
	when the forwarding plane of the speaker remains intact. <rfc
2204
	id="4724"> specifies an optional graceful restart mechanism to
2205
	alleviate this issue. This option controls the mechanism. It has three
2206
	states: Disabled, when no support is provided. Aware, when the graceful
2207
	restart support is announced and the support for restarting neighbors
2208
	is provided, but no local graceful restart is allowed (i.e.
2209
	receiving-only role). Enabled, when the full graceful restart
2210
	support is provided (i.e. both restarting and receiving role). Note
2211
	that proper support for local graceful restart requires also
2212
	configuration of other protocols.  Default: aware.
2213 6eda3f13 Ondrej Zajicek
2214 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-graceful-restart-time">graceful restart time <m/number/</tag>
2215 6eda3f13 Ondrej Zajicek
	The restart time is announced in the BGP graceful restart capability
2216
	and specifies how long the neighbor would wait for the BGP session to
2217
	re-establish after a restart before deleting stale routes. Default:
2218
	120 seconds.
2219
2220 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-interpret-communities">interpret communities <m/switch/</tag>
2221 7935b9d2 Pavel Tvrdik
	<rfc id="1997"> demands that BGP speaker should process well-known
2222
	communities like no-export (65535, 65281) or no-advertise (65535,
2223
	65282). For example, received route carrying a no-adverise community
2224
	should not be advertised to any of its neighbors. If this option is
2225
	enabled (which is by default), BIRD has such behavior automatically (it
2226
	is evaluated when a route is exported to the BGP protocol just before
2227
	the export filter).  Otherwise, this integrated processing of
2228
	well-known communities is disabled. In that case, similar behavior can
2229
	be implemented in the export filter.  Default: on.
2230 dad92c30 Ondrej Zajicek
2231 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-enable-as4">enable as4 <m/switch/</tag>
2232 dad92c30 Ondrej Zajicek
	BGP protocol was designed to use 2B AS numbers and was extended later to
2233
	allow 4B AS number. BIRD supports 4B AS extension, but by disabling this
2234
	option it can be persuaded not to advertise it and to maintain old-style
2235
	sessions with its neighbors. This might be useful for circumventing bugs
2236
	in neighbor's implementation of 4B AS extension. Even when disabled
2237
	(off), BIRD behaves internally as AS4-aware BGP router. Default: on.
2238
2239 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-enable-extended-messages">enable extended messages <m/switch/</tag>
2240 79a4f74a Pavel Tvrdík
	The BGP protocol uses maximum message length of 4096 bytes. This option
2241
	provides an extension to allow extended messages with length up
2242
	to 65535 bytes. Default: off.
2243
2244 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-capabilities">capabilities <m/switch/</tag>
2245 dad92c30 Ondrej Zajicek
	Use capability advertisement to advertise optional capabilities. This is
2246
	standard behavior for newer BGP implementations, but there might be some
2247
	older BGP implementations that reject such connection attempts. When
2248
	disabled (off), features that request it (4B AS support) are also
2249
	disabled. Default: on, with automatic fallback to off when received
2250
	capability-related error.
2251
2252 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-advertise-ipv4">advertise ipv4 <m/switch/</tag>
2253 dad92c30 Ondrej Zajicek
	Advertise IPv4 multiprotocol capability. This is not a correct behavior
2254 7935b9d2 Pavel Tvrdik
	according to the strict interpretation of <rfc id="4760">, but it is
2255
	widespread and required by some BGP implementations (Cisco and Quagga).
2256
	This option is relevant to IPv4 mode with enabled capability
2257
	advertisement only. Default: on.
2258 dad92c30 Ondrej Zajicek
2259 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-route-limit">route limit <m/number/</tag>
2260 dad92c30 Ondrej Zajicek
	The maximal number of routes that may be imported from the protocol. If
2261
	the route limit is exceeded, the connection is closed with an error.
2262
	Limit is currently implemented as <cf>import limit <m/number/ action
2263
	restart</cf>. This option is obsolete and it is replaced by
2264 7935b9d2 Pavel Tvrdik
	<ref id="proto-import-limit" name="import limit option">. Default: no limit.
2265 dad92c30 Ondrej Zajicek
2266 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-disable-after-error">disable after error <m/switch/</tag>
2267 dad92c30 Ondrej Zajicek
	When an error is encountered (either locally or by the other side),
2268
	disable the instance automatically and wait for an administrator to fix
2269
	the problem manually. Default: off.
2270
2271 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-hold-time">hold time <m/number/</tag>
2272 dad92c30 Ondrej Zajicek
	Time in seconds to wait for a Keepalive message from the other side
2273
	before considering the connection stale. Default: depends on agreement
2274
	with the neighboring router, we prefer 240 seconds if the other side is
2275
	willing to accept it.
2276
2277 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-startup-hold-time">startup hold time <m/number/</tag>
2278 dad92c30 Ondrej Zajicek
	Value of the hold timer used before the routers have a chance to exchange
2279
	open messages and agree on the real value. Default: 240	seconds.
2280
2281 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-keepalive-time">keepalive time <m/number/</tag>
2282 dad92c30 Ondrej Zajicek
	Delay in seconds between sending of two consecutive Keepalive messages.
2283
	Default: One third of the hold time.
2284
2285 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-connect-delay-time">connect delay time <m/number/</tag>
2286 6cf72d7a Ondrej Zajicek
	Delay in seconds between protocol startup and the first attempt to
2287
	connect. Default: 5 seconds.
2288
2289 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-connect-retry-time">connect retry time <m/number/</tag>
2290 dad92c30 Ondrej Zajicek
	Time in seconds to wait before retrying a failed attempt to connect.
2291
	Default: 120 seconds.
2292
2293 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-error-wait-time">error wait time <m/number/,<m/number/</tag>
2294 dad92c30 Ondrej Zajicek
	Minimum and maximum delay in seconds between a protocol failure (either
2295
	local or reported by the peer) and automatic restart. Doesn't apply
2296
	when <cf/disable after error/ is configured. If consecutive errors
2297
	happen, the delay is increased exponentially until it reaches the
2298
	maximum. Default: 60, 300.
2299
2300 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-error-forget-time">error forget time <m/number/</tag>
2301 dad92c30 Ondrej Zajicek
	Maximum time in seconds between two protocol failures to treat them as a
2302
	error sequence which makes <cf/error wait time/ increase exponentially.
2303
	Default: 300 seconds.
2304
2305 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-path-metric">path metric <m/switch/</tag>
2306 dad92c30 Ondrej Zajicek
	Enable comparison of path lengths when deciding which BGP route is the
2307
	best one. Default: on.
2308
2309 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-med-metric">med metric <m/switch/</tag>
2310 dad92c30 Ondrej Zajicek
	Enable comparison of MED attributes (during best route selection) even
2311
	between routes received from different ASes. This may be useful if all
2312
	MED attributes contain some consistent metric, perhaps enforced in
2313
	import filters of AS boundary routers. If this option is disabled, MED
2314
	attributes are compared only if routes are received from the same AS
2315
	(which is the standard behavior). Default: off.
2316
2317 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-deterministic-med">deterministic med <m/switch/</tag>
2318 dad92c30 Ondrej Zajicek
	BGP route selection algorithm is often viewed as a comparison between
2319
	individual routes (e.g. if a new route appears and is better than the
2320
	current best one, it is chosen as the new best one). But the proper
2321 7935b9d2 Pavel Tvrdik
	route selection, as specified by <rfc id="4271">, cannot be fully
2322
	implemented in that way. The problem is mainly in handling the MED
2323
	attribute. BIRD, by default, uses an simplification based on individual
2324
	route comparison, which in some cases may lead to temporally dependent
2325
	behavior (i.e. the selection is dependent on the order in which routes
2326
	appeared). This option enables a different (and slower) algorithm
2327
	implementing proper <rfc id="4271"> route selection, which is
2328
	deterministic. Alternative way how to get deterministic behavior is to
2329
	use <cf/med metric/ option. This option is incompatible with <ref
2330
	id="dsc-table-sorted" name="sorted tables">.  Default: off.
2331 be4cd99a Ondrej Zajicek
2332 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-igp-metric">igp metric <m/switch/</tag>
2333 dad92c30 Ondrej Zajicek
	Enable comparison of internal distances to boundary routers during best
2334
 	route selection. Default: on.
2335
2336 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-prefer-older">prefer older <m/switch/</tag>
2337 dad92c30 Ondrej Zajicek
	Standard route selection algorithm breaks ties by comparing router IDs.
2338
	This changes the behavior to prefer older routes (when both are external
2339 7935b9d2 Pavel Tvrdik
	and from different peer). For details, see <rfc id="5004">. Default: off.
2340 dad92c30 Ondrej Zajicek
2341 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-default-med">default bgp_med <m/number/</tag>
2342 dad92c30 Ondrej Zajicek
	Value of the Multiple Exit Discriminator to be used during route
2343
	selection when the MED attribute is missing. Default: 0.
2344
2345 b9864aa8 Pavel Tvrdik
	<tag><label id="bgp-default-local-pref">default bgp_local_pref <m/number/</tag>
2346 dad92c30 Ondrej Zajicek
	A default value for the Local Preference attribute. It is used when
2347
	a new Local Preference attribute is attached to a route by the BGP
2348
	protocol itself (for example, if a route is received through eBGP and
2349
	therefore does not have such attribute). Default: 100 (0 in pre-1.2.0
2350
	versions of BIRD).
2351 5459fac6 Martin Mares
</descrip>
2352
2353 371adba6 Martin Mares
<sect1>Attributes
2354 b9864aa8 Pavel Tvrdik
<label id="bgp-attr">
2355 56ab03c7 Martin Mares
2356 dad92c30 Ondrej Zajicek
<p>BGP defines several route attributes. Some of them (those marked with
2357
`<tt/I/' in the table below) are available on internal BGP connections only,
2358
some of them (marked with `<tt/O/') are optional.
2359 5459fac6 Martin Mares
2360
<descrip>
2361 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-path">bgppath bgp_path/</tag>
2362 dad92c30 Ondrej Zajicek
	Sequence of AS numbers describing the AS path the packet will travel
2363
	through when forwarded according to the particular route. In case of
2364
	internal BGP it doesn't contain the number of the local AS.
2365
2366 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-local-pref">int bgp_local_pref/ [I]</tag>
2367 dad92c30 Ondrej Zajicek
	Local preference value used for selection among multiple BGP routes (see
2368
	the selection rules above). It's used as an additional metric which is
2369
	propagated through the whole local AS.
2370
2371 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-med">int bgp_med/ [O]</tag>
2372 dad92c30 Ondrej Zajicek
	The Multiple Exit Discriminator of the route is an optional attribute
2373
	which is used on external (inter-AS) links to convey to an adjacent AS
2374
	the optimal entry point into the local AS. The received attribute is
2375
	also propagated over internal BGP links. The attribute value is zeroed
2376
	when a route is exported to an external BGP instance to ensure that the
2377
	attribute received from a neighboring AS is not propagated to other
2378
	neighboring ASes. A new value might be set in the export filter of an
2379 7935b9d2 Pavel Tvrdik
	external BGP instance. See <rfc id="4451"> for further discussion of
2380
	BGP MED attribute.
2381 5a203dac Pavel Machek
2382 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-origin">enum bgp_origin/</tag>
2383 dad92c30 Ondrej Zajicek
	Origin of the route: either <cf/ORIGIN_IGP/ if the route has originated
2384
	in an interior routing protocol or <cf/ORIGIN_EGP/ if it's been imported
2385
	from the <tt>EGP</tt> protocol (nowadays it seems to be obsolete) or
2386
	<cf/ORIGIN_INCOMPLETE/ if the origin is unknown.
2387 5a203dac Pavel Machek
2388 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-next-hop">ip bgp_next_hop/</tag>
2389 dad92c30 Ondrej Zajicek
	Next hop to be used for forwarding of packets to this destination. On
2390
	internal BGP connections, it's an address of the originating router if
2391
	it's inside the local AS or a boundary router the packet will leave the
2392
	AS through if it's an exterior route, so each BGP speaker within the AS
2393
	has a chance to use the shortest interior path possible to this point.
2394 5a203dac Pavel Machek
2395 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-atomic-aggr">void bgp_atomic_aggr/ [O]</tag>
2396 dad92c30 Ondrej Zajicek
	This is an optional attribute which carries no value, but the sole
2397
	presence of which indicates that the route has been aggregated from
2398
	multiple routes by some router on the path from the originator.
2399 5a203dac Pavel Machek
2400 5459fac6 Martin Mares
<!-- we don't handle aggregators right since they are of a very obscure type
2401
	<tag>bgp_aggregator</tag>
2402
-->
2403 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-community">clist bgp_community/ [O]</tag>
2404 dad92c30 Ondrej Zajicek
	List of community values associated with the route. Each such value is a
2405
	pair (represented as a <cf/pair/ data type inside the filters) of 16-bit
2406
	integers, the first of them containing the number of the AS which
2407
	defines the community and the second one being a per-AS identifier.
2408
	There are lots of uses of the community mechanism, but generally they
2409
	are used to carry policy information like "don't export to USA peers".
2410
	As each AS can define its own routing policy, it also has a complete
2411
	freedom about which community attributes it defines and what will their
2412
	semantics be.
2413
2414 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-ext-community">eclist bgp_ext_community/ [O]</tag>
2415 dad92c30 Ondrej Zajicek
	List of extended community values associated with the route. Extended
2416
	communities have similar usage as plain communities, but they have an
2417
	extended range (to allow 4B ASNs) and a nontrivial structure with a type
2418
	field. Individual community values are represented using an <cf/ec/ data
2419
	type inside the filters.
2420
2421 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-large-community">lclist <cf/bgp_large_community/ [O]</tag>
2422 cec4a73c Ondrej Zajicek (work)
	List of large community values associated with the route. Large BGP
2423
	communities is another variant of communities, but contrary to extended
2424
	communities they behave very much the same way as regular communities,
2425
	just larger -- they are uniform untyped triplets of 32bit numbers.
2426
	Individual community values are represented using an <cf/lc/ data type
2427
	inside the filters.
2428
2429 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-originator-id">quad bgp_originator_id/ [I, O]</tag>
2430 dad92c30 Ondrej Zajicek
	This attribute is created by the route reflector when reflecting the
2431
	route and contains the router ID of the originator of the route in the
2432
	local AS.
2433
2434 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-bgp-cluster-list">clist bgp_cluster_list/ [I, O]</tag>
2435 dad92c30 Ondrej Zajicek
	This attribute contains a list of cluster IDs of route reflectors. Each
2436
	route reflector prepends its cluster ID when reflecting the route.
2437 5459fac6 Martin Mares
</descrip>
2438
2439 371adba6 Martin Mares
<sect1>Example
2440 b9864aa8 Pavel Tvrdik
<label id="bgp-exam">
2441 56ab03c7 Martin Mares
2442 5459fac6 Martin Mares
<p><code>
2443
protocol bgp {
2444 96264d4d Pavel Machek
	local as 65000;			     # Use a private AS number
2445 9491f9f5 Ondrej Zajicek
	neighbor 198.51.100.130 as 64496;    # Our neighbor ...
2446 6bcef225 Ondrej Zajicek
	multihop;			     # ... which is connected indirectly
2447 96264d4d Pavel Machek
	export filter {			     # We use non-trivial export rules
2448
		if source = RTS_STATIC then { # Export only static routes
2449 79a4f74a Pavel Tvrdík
			# Assign our community
2450 9491f9f5 Ondrej Zajicek
			bgp_community.add((65000,64501));
2451 a852c139 Pavel Machek
			# Artificially increase path length
2452 5a203dac Pavel Machek
			# by advertising local AS number twice
2453 9491f9f5 Ondrej Zajicek
			if bgp_path ~ [= 65000 =] then
2454
				bgp_path.prepend(65000);
2455 5459fac6 Martin Mares
			accept;
2456
		}
2457
		reject;
2458
	};
2459
	import all;
2460 9491f9f5 Ondrej Zajicek
	source address 198.51.100.14;	# Use a non-standard source address
2461 5459fac6 Martin Mares
}
2462
</code>
2463
2464 dad92c30 Ondrej Zajicek
2465 371adba6 Martin Mares
<sect>Device
2466 b9864aa8 Pavel Tvrdik
<label id="device">
2467 1b55b1a3 Martin Mares
2468 dad92c30 Ondrej Zajicek
<p>The Device protocol is not a real routing protocol. It doesn't generate any
2469
routes and it only serves as a module for getting information about network
2470 79a2b697 Martin Mares
interfaces from the kernel.
2471
2472 dad92c30 Ondrej Zajicek
<p>Except for very unusual circumstances, you probably should include this
2473
protocol in the configuration since almost all other protocols require network
2474
interfaces to be defined for them to work with.
2475 79a2b697 Martin Mares
2476 6f5603ba Ondrej Zajicek
<sect1>Configuration
2477 b9864aa8 Pavel Tvrdik
<label id="device-config">
2478 79a2b697 Martin Mares
2479
<p><descrip>
2480 dad92c30 Ondrej Zajicek
2481 b9864aa8 Pavel Tvrdik
	<tag><label id="device-scan-time">scan time <m/number/</tag>
2482 dad92c30 Ondrej Zajicek
	Time in seconds between two scans of the network interface list. On
2483
	systems where we are notified about interface status changes
2484
	asynchronously (such as newer versions of Linux), we need to scan the
2485
	list only in order to avoid confusion by lost notification messages,
2486
	so the default time is set to a large value.
2487
2488 b9864aa8 Pavel Tvrdik
	<tag><label id="device-primary">primary [ "<m/mask/" ] <m/prefix/</tag>
2489 dad92c30 Ondrej Zajicek
	If a network interface has more than one network address, BIRD has to
2490
	choose one of them as a primary one. By default, BIRD chooses the
2491
	lexicographically smallest address as the primary one.
2492
2493
	This option allows to specify which network address should be chosen as
2494
	a primary one. Network addresses that match <m/prefix/ are preferred to
2495
	non-matching addresses. If more <cf/primary/ options are used, the first
2496
	one has the highest preference. If "<m/mask/" is specified, then such
2497
	<cf/primary/ option is relevant only to matching network interfaces.
2498
2499
	In all cases, an address marked by operating system as secondary cannot
2500
	be chosen as the primary one.
2501 79a2b697 Martin Mares
</descrip>
2502
2503
<p>As the Device protocol doesn't generate any routes, it cannot have
2504 6f5603ba Ondrej Zajicek
any attributes. Example configuration looks like this:
2505 79a2b697 Martin Mares
2506
<p><code>
2507
protocol device {
2508
	scan time 10;		# Scan the interfaces often
2509 6f5603ba Ondrej Zajicek
	primary "eth0" 192.168.1.1;
2510
	primary 192.168.0.0/16;
2511 79a2b697 Martin Mares
}
2512
</code>
2513
2514 dad92c30 Ondrej Zajicek
2515 371adba6 Martin Mares
<sect>Direct
2516 b9864aa8 Pavel Tvrdik
<label id="direct">
2517 1b55b1a3 Martin Mares
2518 79a2b697 Martin Mares
<p>The Direct protocol is a simple generator of device routes for all the
2519 dad92c30 Ondrej Zajicek
directly connected networks according to the list of interfaces provided by the
2520
kernel via the Device protocol.
2521
2522
<p>The question is whether it is a good idea to have such device routes in BIRD
2523
routing table. OS kernel usually handles device routes for directly connected
2524
networks by itself so we don't need (and don't want) to export these routes to
2525
the kernel protocol. OSPF protocol creates device routes for its interfaces
2526
itself and BGP protocol is usually used for exporting aggregate routes. Although
2527
there are some use cases that use the direct protocol (like abusing eBGP as an
2528
IGP routing protocol), in most cases it is not needed to have these device
2529 c429d4a4 Ondrej Zajicek
routes in BIRD routing table and to use the direct protocol.
2530 79a2b697 Martin Mares
2531 dad92c30 Ondrej Zajicek
<p>There is one notable case when you definitely want to use the direct protocol
2532
-- running BIRD on BSD systems. Having high priority device routes for directly
2533
connected networks from the direct protocol protects kernel device routes from
2534
being overwritten or removed by IGP routes during some transient network
2535
conditions, because a lower priority IGP route for the same network is not
2536
exported to the kernel routing table. This is an issue on BSD systems only, as
2537
on Linux systems BIRD cannot change non-BIRD route in the kernel routing table.
2538 cf3a704b Ondrej Zajicek
2539 e90dd656 Ondrej Zajicek (work)
<p>There are just few configuration options for the Direct protocol:
2540 79a2b697 Martin Mares
2541
<p><descrip>
2542 9df52a98 Pavel Tvrdik
	<tag><label id="direct-iface">interface <m/pattern/ [, <m/.../]</tag>
2543 dad92c30 Ondrej Zajicek
	By default, the Direct protocol will generate device routes for all the
2544
	interfaces available. If you want to restrict it to some subset of
2545 d7c06285 Ondrej Zajicek
	interfaces or addresses (e.g. if you're using multiple routing tables
2546
	for policy routing and some of the policy domains don't contain all
2547 b9864aa8 Pavel Tvrdik
	interfaces), just use this clause. See <ref id="proto-iface" name="interface">
2548 d7c06285 Ondrej Zajicek
	common option for detailed description. The Direct protocol uses
2549
	extended interface clauses.
2550 e90dd656 Ondrej Zajicek (work)
2551 b9864aa8 Pavel Tvrdik
	<tag><label id="direct-check-link">check link <m/switch/</tag>
2552 e90dd656 Ondrej Zajicek (work)
	If enabled, a hardware link state (reported by OS) is taken into
2553
	consideration. Routes for directly connected networks are generated only
2554
	if link up is reported and they are withdrawn when link disappears
2555
	(e.g., an ethernet cable is unplugged). Default value is no.
2556 79a2b697 Martin Mares
</descrip>
2557
2558
<p>Direct device routes don't contain any specific attributes.
2559
2560 4f88ac47 Pavel Machek
<p>Example config might look like this:
2561 79a2b697 Martin Mares
2562
<p><code>
2563
protocol direct {
2564
	interface "-arc*", "*";		# Exclude the ARCnets
2565
}
2566
</code>
2567
2568 dad92c30 Ondrej Zajicek
2569 371adba6 Martin Mares
<sect>Kernel
2570 b9864aa8 Pavel Tvrdik
<label id="krt">
2571 1b55b1a3 Martin Mares
2572 0e4789c2 Martin Mares
<p>The Kernel protocol is not a real routing protocol. Instead of communicating
2573 c429d4a4 Ondrej Zajicek
with other routers in the network, it performs synchronization of BIRD's routing
2574 dad92c30 Ondrej Zajicek
tables with the OS kernel. Basically, it sends all routing table updates to the
2575
kernel and from time to time it scans the kernel tables to see whether some
2576
routes have disappeared (for example due to unnoticed up/down transition of an
2577
interface) or whether an `alien' route has been added by someone else (depending
2578
on the <cf/learn/ switch, such routes are either ignored or accepted to our
2579 f8e2d916 Martin Mares
table).
2580 0e4789c2 Martin Mares
2581 dad92c30 Ondrej Zajicek
<p>Unfortunately, there is one thing that makes the routing table synchronization
2582
a bit more complicated. In the kernel routing table there are also device routes
2583
for directly connected networks. These routes are usually managed by OS itself
2584
(as a part of IP address configuration) and we don't want to touch that. They
2585
are completely ignored during the scan of the kernel tables and also the export
2586
of device routes from BIRD tables to kernel routing tables is restricted to
2587
prevent accidental interference. This restriction can be disabled using
2588 c429d4a4 Ondrej Zajicek
<cf/device routes/ switch.
2589
2590 dad92c30 Ondrej Zajicek
<p>If your OS supports only a single routing table, you can configure only one
2591
instance of the Kernel protocol. If it supports multiple tables (in order to
2592
allow policy routing; such an OS is for example Linux), you can run as many
2593
instances as you want, but each of them must be connected to a different BIRD
2594
routing table and to a different kernel table.
2595 0e4789c2 Martin Mares
2596 dad92c30 Ondrej Zajicek
<p>Because the kernel protocol is partially integrated with the connected
2597
routing table, there are two limitations - it is not possible to connect more
2598
kernel protocols to the same routing table and changing route destination
2599
(gateway) in an export filter of a kernel protocol does not work. Both
2600
limitations can be overcome using another routing table and the pipe protocol.
2601 71ca7716 Ondrej Zajicek
2602 371adba6 Martin Mares
<sect1>Configuration
2603 b9864aa8 Pavel Tvrdik
<label id="krt-config">
2604 0e4789c2 Martin Mares
2605
<p><descrip>
2606 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-persist">persist <m/switch/</tag>
2607 6eda3f13 Ondrej Zajicek
	Tell BIRD to leave all its routes in the routing tables when it exits
2608
	(instead of cleaning them up).
2609
2610 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-scan-time">scan time <m/number/</tag>
2611 6eda3f13 Ondrej Zajicek
	Time in seconds between two consecutive scans of the kernel routing
2612
	table.
2613
2614 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-learn">learn <m/switch/</tag>
2615 6eda3f13 Ondrej Zajicek
	Enable learning of routes added to the kernel routing tables by other
2616
	routing daemons or by the system administrator. This is possible only on
2617
	systems which support identification of route authorship.
2618
2619 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-device-routes">device routes <m/switch/</tag>
2620 6eda3f13 Ondrej Zajicek
	Enable export of device routes to the kernel routing table. By default,
2621
	such routes are rejected (with the exception of explicitly configured
2622
	device routes from the static protocol) regardless of the export filter
2623
	to protect device routes in kernel routing table (managed by OS itself)
2624
	from accidental overwriting or erasing.
2625
2626 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-kernel-table">kernel table <m/number/</tag>
2627 6eda3f13 Ondrej Zajicek
	Select which kernel table should this particular instance of the Kernel
2628
	protocol work with. Available only on systems supporting multiple
2629
	routing tables.
2630
2631 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-metric">metric <m/number/</tag> (Linux)
2632 4adcb9df Ondrej Zajicek (work)
	Use specified value as a kernel metric (priority) for all routes sent to
2633
	the kernel. When multiple routes for the same network are in the kernel
2634
	routing table, the Linux kernel chooses one with lower metric. Also,
2635
	routes with different metrics do not clash with each other, therefore
2636
	using dedicated metric value is a reliable way to avoid overwriting
2637
	routes from other sources (e.g. kernel device routes). Metric 0 has a
2638
	special meaning of undefined metric, in which either OS default is used,
2639
	or per-route metric can be set using <cf/krt_metric/ attribute. Default:
2640
	0 (undefined).
2641
2642 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-graceful-restart">graceful restart <m/switch/</tag>
2643 6eda3f13 Ondrej Zajicek
	Participate in graceful restart recovery. If this option is enabled and
2644
	a graceful restart recovery is active, the Kernel protocol will defer
2645
	synchronization of routing tables until the end of the recovery. Note
2646
	that import of kernel routes to BIRD is not affected.
2647 8d9eef17 Ondrej Zajicek
2648 b9864aa8 Pavel Tvrdik
	<tag><label id="krt-merge-paths">merge paths <M>switch</M> [limit <M>number</M>]</tag>
2649 8d9eef17 Ondrej Zajicek
	Usually, only best routes are exported to the kernel protocol. With path
2650
	merging enabled, both best routes and equivalent non-best routes are
2651
	merged during export to generate one ECMP (equal-cost multipath) route
2652
	for each network. This is useful e.g. for BGP multipath. Note that best
2653
	routes are still pivotal for route export (responsible for most
2654
	properties of resulting ECMP routes), while exported non-best routes are
2655
	responsible just for additional multipath next hops. This option also
2656
	allows to specify a limit on maximal number of nexthops in one route. By
2657
	default, multipath merging is disabled. If enabled, default value of the
2658
	limit is 16.
2659 0e4789c2 Martin Mares
</descrip>
2660
2661 71ca7716 Ondrej Zajicek
<sect1>Attributes
2662 b9864aa8 Pavel Tvrdik
<label id="krt-attr">
2663 71ca7716 Ondrej Zajicek
2664 dad92c30 Ondrej Zajicek
<p>The Kernel protocol defines several attributes. These attributes are
2665
translated to appropriate system (and OS-specific) route attributes. We support
2666
these attributes:
2667 71ca7716 Ondrej Zajicek
2668
<descrip>
2669 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-krt-source">int krt_source/</tag>
2670 dad92c30 Ondrej Zajicek
	The original source of the imported kernel route. The value is
2671
	system-dependent. On Linux, it is a value of the protocol field of the
2672
	route. See /etc/iproute2/rt_protos for common values. On BSD, it is
2673 72aed1a0 Ondrej Zajicek
	based on STATIC and PROTOx flags. The attribute is read-only.
2674
2675 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-krt-metric">int krt_metric/</tag> (Linux)
2676 dad92c30 Ondrej Zajicek
	The kernel metric of the route. When multiple same routes are in a
2677
	kernel routing table, the Linux kernel chooses one with lower metric.
2678 4adcb9df Ondrej Zajicek (work)
	Note that preferred way to set kernel metric is to use protocol option
2679
	<cf/metric/, unless per-route metric values are needed.
2680 9ba2798c Ondrej Zajicek
2681 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-krt-prefsrc">ip krt_prefsrc/</tag> (Linux)
2682 dad92c30 Ondrej Zajicek
	The preferred source address. Used in source address selection for
2683 79a4f74a Pavel Tvrdík
	outgoing packets. Has to be one of the IP addresses of the router.
2684 71ca7716 Ondrej Zajicek
2685 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-krt-realm">int krt_realm/</tag> (Linux)
2686 dad92c30 Ondrej Zajicek
	The realm of the route. Can be used for traffic classification.
2687 6e75d0d2 Ondrej Zajicek (work)
2688 b9864aa8 Pavel Tvrdik
	<tag><label id="rta-krt-scope">int krt_scope/</tag> (Linux IPv4)
2689 6e75d0d2 Ondrej Zajicek (work)
	The scope of the route. Valid values are 0-254, although Linux kernel
2690
	may reject some values depending on route type and nexthop. It is
2691
	supposed to represent `indirectness' of the route, where nexthops of
2692
	routes are resolved through routes with a higher scope, but in current
2693
	kernels anything below <it/link/ (253) is treated as <it/global/ (0).
2694
	When not present, global scope is implied for all routes except device
2695
	routes, where link scope is used by default.
2696 71ca7716 Ondrej Zajicek
</descrip>
2697
2698 6683d42d Ondrej Zajicek
<p>In Linux, there is also a plenty of obscure route attributes mostly focused
2699
on tuning TCP performance of local connections. BIRD supports most of these
2700
attributes, see Linux or iproute2 documentation for their meaning. Attributes
2701
<cf/krt_lock_*/ and <cf/krt_feature_*/ have type bool, others have type int.
2702
Supported attributes are:
2703
2704
<cf/krt_mtu/, <cf/krt_lock_mtu/, <cf/krt_window/, <cf/krt_lock_window/,
2705
<cf/krt_rtt/, <cf/krt_lock_rtt/, <cf/krt_rttvar/, <cf/krt_lock_rttvar/,
2706
<cf/krt_sstresh/, <cf/krt_lock_sstresh/, <cf/krt_cwnd/, <cf/krt_lock_cwnd/,
2707
<cf/krt_advmss/, <cf/krt_lock_advmss/, <cf/krt_reordering/, <cf/krt_lock_reordering/,
2708
<cf/krt_hoplimit/, <cf/krt_lock_hoplimit/, <cf/krt_rto_min/, <cf/krt_lock_rto_min/,
2709
<cf/krt_initcwnd/, <cf/krt_initrwnd/, <cf/krt_quickack/,
2710
<cf/krt_feature_ecn/, <cf/krt_feature_allfrag/
2711
2712 71ca7716 Ondrej Zajicek
<sect1>Example
2713 b9864aa8 Pavel Tvrdik
<label id="krt-exam">
2714 71ca7716 Ondrej Zajicek
2715 326e33f5 Pavel Machek
<p>A simple configuration can look this way:
2716 0e4789c2 Martin Mares
2717
<p><code>
2718
protocol kernel {
2719
	export all;
2720
}
2721
</code>
2722
2723
<p>Or for a system with two routing tables:
2724
2725
<p><code>
2726
protocol kernel {		# Primary routing table
2727
	learn;			# Learn alien routes from the kernel
2728
	persist;		# Don't remove routes on bird shutdown
2729
	scan time 10;		# Scan kernel routing table every 10 seconds
2730
	import all;
2731
	export all;
2732
}
2733
2734
protocol kernel {		# Secondary routing table
2735
	table auxtable;
2736
	kernel table 100;
2737
	export all;
2738 a2a3ced8 Martin Mares
}
2739 0e4789c2 Martin Mares
</code>
2740
2741 dad92c30 Ondrej Zajicek
2742 371adba6 Martin Mares
<sect>OSPF
2743 b9864aa8 Pavel Tvrdik
<label id="ospf">
2744 1b55b1a3 Martin Mares
2745 8fd12e6b Ondrej Filip
<sect1>Introduction
2746 b9864aa8 Pavel Tvrdik
<label id="ospf-intro">
2747 8fd12e6b Ondrej Filip
2748 3ca3e999 Martin Mares
<p>Open Shortest Path First (OSPF) is a quite complex interior gateway
2749 7935b9d2 Pavel Tvrdik
protocol. The current IPv4 version (OSPFv2) is defined in <rfc id="2328"> and
2750
the current IPv6 version (OSPFv3) is defined in <rfc id="5340"> It's a link
2751
state (a.k.a. shortest path first) protocol -- each router maintains a database
2752
describing the autonomous system's topology. Each participating router has an
2753
identical copy of the database and all routers run the same algorithm
2754
calculating a shortest path tree with themselves as a root. OSPF chooses the
2755
least cost path as the best path.
2756 dad92c30 Ondrej Zajicek
2757
<p>In OSPF, the autonomous system can be split to several areas in order to
2758
reduce the amount of resources consumed for exchanging the routing information
2759
and to protect the other areas from incorrect routing data. Topology of the area
2760
is hidden to the rest of the autonomous system.
2761
2762
<p>Another very important feature of OSPF is that it can keep routing information
2763
from other protocols (like Static or BGP) in its link state database as external
2764
routes. Each external route can be tagged by the advertising router, making it
2765
possible to pass additional information between routers on the boundary of the
2766
autonomous system.
2767
2768
<p>OSPF quickly detects topological changes in the autonomous system (such as
2769
router interface failures) and calculates new loop-free routes after a short
2770
period of convergence. Only a minimal amount of routing traffic is involved.
2771 8fd12e6b Ondrej Filip
2772 3ca3e999 Martin Mares
<p>Each router participating in OSPF routing periodically sends Hello messages
2773 dad92c30 Ondrej Zajicek
to all its interfaces. This allows neighbors to be discovered dynamically. Then
2774
the neighbors exchange theirs parts of the link state database and keep it
2775
identical by flooding updates. The flooding process is reliable and ensures that
2776
each router detects all changes.
2777 8fd12e6b Ondrej Filip
2778
<sect1>Configuration
2779 b9864aa8 Pavel Tvrdik
<label id="ospf-config">
2780 8fd12e6b Ondrej Filip
2781 dad92c30 Ondrej Zajicek
<p>In the main part of configuration, there can be multiple definitions of OSPF
2782
areas, each with a different id. These definitions includes many other switches
2783
and multiple definitions of interfaces. Definition of interface may contain many
2784
switches and constant definitions and list of neighbors on nonbroadcast
2785
networks.
2786 8fd12e6b Ondrej Filip
2787
<code>
2788 088bc8ad Ondrej Filip
protocol ospf &lt;name&gt; {
2789 1632f1fe Pavel Machek
	rfc1583compat &lt;switch&gt;;
2790 178a197a Ondrej Zajicek
	instance id &lt;num&gt;;
2791 f623ab98 Ondrej Zajicek
	stub router &lt;switch&gt;;
2792 62eee823 Ondrej Filip
	tick &lt;num&gt;;
2793 e91f6960 Ondrej Zajicek
	ecmp &lt;switch&gt; [limit &lt;num&gt;];
2794 145368f5 Ondrej Zajicek
	merge external &lt;switch&gt;;
2795 088bc8ad Ondrej Filip
	area &lt;id&gt; {
2796 2918e610 Ondrej Zajicek
		stub;
2797
		nssa;
2798 bde872bb Ondrej Zajicek
		summary &lt;switch&gt;;
2799 2918e610 Ondrej Zajicek
		default nssa &lt;switch&gt;;
2800
		default cost &lt;num&gt;;
2801
		default cost2 &lt;num&gt;;
2802 bde872bb Ondrej Zajicek
		translator &lt;switch&gt;;
2803
		translator stability &lt;num&gt;;
2804
2805 16319aeb Ondrej Filip
                networks {
2806
			&lt;prefix&gt;;
2807
			&lt;prefix&gt; hidden;
2808
		}
2809 bde872bb Ondrej Zajicek
                external {
2810
			&lt;prefix&gt;;
2811
			&lt;prefix&gt; hidden;
2812
			&lt;prefix&gt; tag &lt;num&gt;;
2813
		}
2814 38675202 Ondrej Zajicek
		stubnet &lt;prefix&gt;;
2815
		stubnet &lt;prefix&gt; {
2816
			hidden &lt;switch&gt;;
2817