bird.sgml 213 KB
Newer Older
1
<!doctype birddoc system>
2
3

<!--
Jan Maria Matejka's avatar
Jan Maria Matejka committed
4
	BIRD 2.0 documentation
5

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

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

15
    (set-fill-column 80)
16
17
18
19
20

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

 -->

21
<book>
22

Jan Maria Matejka's avatar
Jan Maria Matejka committed
23
<title>BIRD 2.0 User's Guide
24
<author>
25
26
Ondrej Filip <it/&lt;feela@network.cz&gt;/,
Pavel Machek <it/&lt;pavel@ucw.cz&gt;/,
Ondrej Filip's avatar
Ondrej Filip committed
27
Martin Mares <it/&lt;mj@ucw.cz&gt;/,
Jan Maria Matejka's avatar
Jan Maria Matejka committed
28
Jan Matejka <it/&lt;mq@jmq.cz&gt;/,
Ondrej Filip's avatar
Ondrej Filip committed
29
Ondrej Zajicek <it/&lt;santiago@crfreenet.org&gt;/
30
</author>
31
32

<abstract>
33
This document contains user documentation for the BIRD Internet Routing Daemon project.
34
35
36
37
38
39
40
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

41

42
<chapt>Introduction
43
<label id="intro">
44

45
<sect>What is BIRD
46
<label id="what-is-bird">
47

48
<p>The name `BIRD' is actually an acronym standing for `BIRD Internet Routing
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
Daemon'. Let's take a closer look at the meaning of the name:

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

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

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

<p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
83
84
85
86
to support all the routing technology used in the today's Internet or planned to
be used in near future and to have a clean extensible architecture allowing new
routing protocols to be incorporated easily. Among other features, BIRD
supports:
87
88
89
90
91

<itemize>
	<item>both IPv4 and IPv6 protocols
	<item>multiple routing tables
	<item>the Border Gateway Protocol (BGPv4)
Jan Maria Matejka's avatar
Jan Maria Matejka committed
92
	<item>the Routing Information Protocol (RIPv2, RIPng)
93
	<item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
Ondřej Zajíček's avatar
Ondřej Zajíček committed
94
	<item>the Babel Routing Protocol
95
	<item>the Router Advertisements for IPv6 hosts
96
97
	<item>a virtual protocol for exchange of routes between different
		routing tables on a single host
98
99
	<item>a command-line interface allowing on-line control and inspection
		of status of the daemon
100
101
102
103
104
	<item>soft reconfiguration (no need to use complex online commands to
		change the configuration, just edit the configuration file and
		notify BIRD to re-read it and it will smoothly switch itself to
		the new configuration, not disturbing routing protocols unless
		they are affected by the configuration changes)
105
	<item>a powerful language for route filtering
106
107
</itemize>

108
109
110
111
112
113
114
115
<p>BIRD has been developed at the Faculty of Math and Physics, Charles
University, Prague, Czech Republic as a student project. It can be freely
distributed under the terms of the GNU General Public License.

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

Jan Maria Matejka's avatar
Jan Maria Matejka committed
117
118
119
120
<p>BIRD 1.x supported either IPv4 or IPv6 protocol, but had to be compiled separately
for each one. BIRD~2 supports both of them with a possibility of further extension.
BIRD~2 supports Linux at least 3.16, FreeBSD 10, NetBSD 7.0, and OpenBSD 5.8.
Anyway, it will probably work well also on older systems.
121

122
<sect>Installing BIRD
123
<label id="install">
124

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

<code>
129
130
131
132
	./configure
	make
	make install
	vi /usr/local/etc/bird.conf
Pavel Machek's avatar
Pavel Machek committed
133
	bird
134
135
</code>

136
<p>You can use <tt>./configure --help</tt> to get a list of configure
Jan Maria Matejka's avatar
Jan Maria Matejka committed
137
options. The most important ones are: <tt/--with-protocols=/ to produce a slightly smaller
138
139
140
BIRD executable by configuring out routing protocols you don't use, and
<tt/--prefix=/ to install BIRD to a place different from <file>/usr/local</file>.

141

142
<sect>Running BIRD
143
<label id="argv">
Pavel Machek's avatar
Pavel Machek committed
144

Pavel Machek's avatar
Pavel Machek committed
145
<p>You can pass several command-line options to bird:
146

Pavel Machek's avatar
Pavel Machek committed
147
<descrip>
148
	<tag><label id="argv-config">-c <m/config name/</tag>
Martin Mareš's avatar
Fixes.    
Martin Mareš committed
149
	use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>.
Pavel Machek's avatar
Pavel Machek committed
150

151
	<tag><label id="argv-debug">-d</tag>
152
	enable debug messages and run bird in foreground.
Pavel Machek's avatar
Pavel Machek committed
153

154
	<tag><label id="argv-log-file">-D <m/filename of debug log/</tag>
155
156
	log debugging information to given file instead of stderr.

157
158
	<tag><label id="argv-foreground">-f</tag>
	run bird in foreground.
159

160
	<tag><label id="argv-group">-g <m/group/</tag>
161
	use that group ID, see the next section for details.
162

163
164
	<tag><label id="argv-help">-h, --help</tag>
	display command-line options to bird.
165

166
	<tag><label id="argv-local">-l</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
167
	look for a configuration file and a communication socket in the current
Ondřej Zajíček's avatar
Ondřej Zajíček committed
168
	working directory instead of in default system locations. However, paths
Ondřej Zajíček's avatar
Ondřej Zajíček committed
169
170
	specified by options <cf/-c/, <cf/-s/ have higher priority.

171
172
173
174
175
176
177
	<tag><label id="argv-parse">-p</tag>
	just parse the config file and exit. Return value is zero if the config
	file is valid, nonzero if there are some errors.

	<tag><label id="argv-pid">-P <m/name of PID file/</tag>
	create a PID file with given filename.

178
	<tag><label id="argv-recovery">-R</tag>
179
	apply graceful restart recovery after start.
180

181
182
183
184
185
186
187
	<tag><label id="argv-socket">-s <m/name of communication socket/</tag>
	use given filename for a socket for communications with the client,
	default is <it/prefix/<file>/var/run/bird.ctl</file>.

	<tag><label id="argv-user">-u <m/user/</tag>
	drop privileges and use that user ID, see the next section for details.

188
189
	<tag><label id="argv-version">--version</tag>
	display bird version.
Pavel Machek's avatar
Pavel Machek committed
190
</descrip>
191

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

194

195
<sect>Privileges
196
<label id="privileges">
197

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

208
<p>An unprivileged user (as an argument to <cf/-u/ options) may be the user
209
210
211
212
213
214
215
216
217
<cf/nobody/, but it is suggested to use a new dedicated user account (like
<cf/bird/). The similar considerations apply for the group option, but there is
one more condition -- the users in the same group can use <file/birdc/ to
control BIRD.

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

219

Jan Maria Matejka's avatar
Jan Maria Matejka committed
220
221
222
223
<chapt>Architecture
<label id="architecture">

<sect>Routing tables
224
<label id="routing-tables">
225

Jan Maria Matejka's avatar
Jan Maria Matejka committed
226
227
228
229
230
231
<p>The heart of BIRD is a routing table. BIRD has several independent routing tables;
each of them contains routes of exactly one <m/nettype/ (see below). There are two
default tables -- <cf/master4/ for IPv4 routes and <cf/master6/ for IPv6 routes.
Other tables must be explicitly configured.

<p>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
232
233
234
These routing tables are not kernel forwarding tables. No forwarding is done by
BIRD. If you want to forward packets using the routes in BIRD tables, you may
use the Kernel protocol (see below) to synchronize them with kernel FIBs.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
235
236

<p>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
237
238
239
240
241
242
Every nettype defines a (kind of) primary key on routes. Every route source can
supply one route for every possible primary key; new route announcement replaces
the old route from the same source, keeping other routes intact. BIRD always
chooses the best route for each primary key among the known routes and keeps the
others as suboptimal. When the best route is retracted, BIRD re-runs the best
route selection algorithm to find the current best route.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
243
244
245

<p>
The global best route selection algorithm is (roughly) as follows:
246
247

<itemize>
Jan Maria Matejka's avatar
Jan Maria Matejka committed
248
249
250
	<item>Preferences of the routes are compared.
	<item>Source protocol instance preferences are compared.
	<item>If source protocols are the same (e.g. BGP vs. BGP), the protocol's route selection algorithm is invoked.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
251
	<item>If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined.
252
253
</itemize>

Ondřej Zajíček's avatar
Ondřej Zajíček committed
254
255
<p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected
route from a list of entries for one network. But if the <cf/sorted/ option is
256
257
258
259
260
261
262
263
264
265
activated, these lists of entries are kept completely sorted (according to
preference or some protocol-dependent metric). This is needed for some features
of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to
accept not just a selected route, but the first route (in the sorted list) that
is accepted by filters), but it is incompatible with some other features (e.g.
<cf/deterministic med/ option of BGP protocol, which activates a way of choosing
selected route that cannot be described using comparison and ordering). Minor
advantage is that routes are shown sorted in <cf/show route/, minor disadvantage
is that it is slightly more computationally expensive.

Jan Maria Matejka's avatar
Jan Maria Matejka committed
266
267
268
269
270
<sect>Routes and network types
<label id="routes">

<p>BIRD works with several types of routes. Some of them are typical IP routes,
others are better described as forwarding rules. We call them all routes,
Ondřej Zajíček's avatar
Ondřej Zajíček committed
271
regardless of this difference.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
272

Ondřej Zajíček's avatar
Ondřej Zajíček committed
273
274
275
<p>Every route consists of several attributes (read more about them in the
<ref id="route-attributes" name="Route attributes"> section); the common for all
routes are:
Jan Maria Matejka's avatar
Jan Maria Matejka committed
276
277
278
279
280
281
282
283
284
285
286

<itemize>
	<item>IP address of router which told us about this route
	<item>Source protocol instance
	<item>Route preference
	<item>Optional attributes defined by protocols
</itemize>

<p>Other attributes depend on nettypes. Some of them are part of the primary key, these are marked (PK).

<sect1>IPv4 and IPv6 routes
Ondřej Zajíček's avatar
Ondřej Zajíček committed
287
<label id="ip-routes">
Jan Maria Matejka's avatar
Jan Maria Matejka committed
288
289
290
291
292
293
294
295

<p>The traditional routes. Configuration keywords are <cf/ipv4/ and <cf/ipv6/.

<itemize>
	<item>(PK) Route destination (IP prefix together with its length)
	<item>Route next hops (see below)
</itemize>

Ondřej Zajíček's avatar
Ondřej Zajíček committed
296
297
298
299
300
301
302
303
304
305
306
307
308
309
<sect1>IPv6 source-specific routes
<label id="ip-sadr-routes">

<p>The IPv6 routes containing both destination and source prefix. They are used
for source-specific routing (SSR), also called source-address dependent routing
(SADR), see <rfc id="8043">. Currently limited mostly to the Babel protocol.
Configuration keyword is <cf/ipv6 sadr/.

<itemize>
	<item>(PK) Route destination (IP prefix together with its length)
	<item>(PK) Route source (IP prefix together with its length)
	<item>Route next hops (see below)
</itemize>

Jan Maria Matejka's avatar
Jan Maria Matejka committed
310
<sect1>VPN IPv4 and IPv6 routes
Ondřej Zajíček's avatar
Ondřej Zajíček committed
311
<label id="vpn-routes">
Jan Maria Matejka's avatar
Jan Maria Matejka committed
312
313
314
315
316
317
318
319
320
321
322

<p>Routes for IPv4 and IPv6 with VPN Route Distinguisher (<rfc id="4364">).
Configuration keywords are <cf/vpn4/ and <cf/vpn6/.

<itemize>
	<item>(PK) Route destination (IP prefix together with its length)
	<item>(PK) Route distinguisher (according to <rfc id="4364">)
	<item>Route next hops
</itemize>

<sect1>Route Origin Authorization for IPv4 and IPv6
Ondřej Zajíček's avatar
Ondřej Zajíček committed
323
<label id="roa-routes">
Jan Maria Matejka's avatar
Jan Maria Matejka committed
324
325

<p>These entries can be used to validate route origination of BGP routes.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
326
A ROA entry specifies prefixes which could be originated by an AS number.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
327
328
329
330
331
332
333
334
335
Their keywords are <cf/roa4/ and <cf/roa6/.

<itemize>
	<item>(PK) IP prefix together with its length
	<item>(PK) Matching prefix maximal length
	<item>(PK) AS number
</itemize>

<sect1>Flowspec for IPv4 and IPv6
Ondřej Zajíček's avatar
Ondřej Zajíček committed
336
<label id="flow-routes">
Jan Maria Matejka's avatar
Jan Maria Matejka committed
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376

<p>Flowspec rules are a form of firewall and traffic flow control rules
distributed mostly via BGP. These rules may help the operators stop various
network attacks in the beginning before eating up the whole bandwidth.
Configuration keywords are <cf/flow4/ and <cf/flow6/.

<itemize>
	<item>(PK) IP prefix together with its length
	<item>(PK) Flow definition data
	<item>Flow action (encoded internally as BGP communities according to <rfc id="5575">)
</itemize>

<sect1>MPLS switching rules
<label id="mpls-routes">

<p>This nettype is currently a stub before implementing more support of <rfc id="3031">.
BIRD currently does not support any label distribution protocol nor any label assignment method.
Only the Kernel, Pipe and Static protocols can use MPLS tables.
Configuration keyword is <cf/mpls/.

<itemize>
	<item>(PK) MPLS label
	<item>Route next hops
</itemize>

<sect1>Route next hops
<label id="route-next-hop">

<p>This is not a nettype. The route next hop is a complex attribute common for many
nettypes as you can see before. Every next hop has its assigned device
(either assumed from its IP address or set explicitly). It may have also
an IP address and an MPLS stack (one or both independently).
Maximal MPLS stack depth is set (in compile time) to 8 labels.

<p>Every route (when eligible to have a next hop) can have more than one next hop.
In that case, every next hop has also its weight.

<sect>Protocols and channels
<label id="protocols-concept">

Ondřej Zajíček's avatar
Ondřej Zajíček committed
377
<p>BIRD protocol is an abstract class of producers and consumers of the routes.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
378
379
380
381
Each protocol may run in multiple instances and bind on one side to route
tables via channels, on the other side to specified listen sockets (BGP),
interfaces (Babel, OSPF, RIP), APIs (Kernel, Direct), or nothing (Static, Pipe).

Ondřej Zajíček's avatar
Ondřej Zajíček committed
382
<p>There are also two protocols that do not have any channels -- BFD and Device.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
383
384
385
386
387
388
389
Both of them are kind of service for other protocols.

<p>Each protocol is connected to a routing table through a channel. Some protocols
support only one channel (OSPF, RIP), some protocols support more channels (BGP, Direct).
Each channel has two filters which can accept, reject and modify the routes.
An <it/export/ filter is applied to routes passed from the routing table to the protocol,
an <it/import/ filter is applied to routes in the opposite direction.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
390

391
<sect>Graceful restart
392
<label id="graceful-restart">
393
394
395
396
397
398
399
400
401
402
403
404
405

<p>When BIRD is started after restart or crash, it repopulates routing tables in
an uncoordinated manner, like after clean start. This may be impractical in some
cases, because if the forwarding plane (i.e. kernel routing tables) remains
intact, then its synchronization with BIRD would temporarily disrupt packet
forwarding until protocols converge. Graceful restart is a mechanism that could
help with this issue. Generally, it works by starting protocols and letting them
repopulate routing tables while deferring route propagation until protocols
acknowledge their convergence. Note that graceful restart behavior have to be
configured for all relevant protocols and requires protocol-specific support
(currently implemented for Kernel and BGP protocols), it is activated for
particular boot by option <cf/-R/.

406

407
<chapt>Configuration
408
<label id="config">
Pavel Machek's avatar
Pavel Machek committed
409

410
<sect>Introduction
411
<label id="config-intro">
412

413
414
415
416
417
418
419
420
421
422
423
<p>BIRD is configured using a text configuration file. Upon startup, BIRD reads
<it/prefix/<file>/etc/bird.conf</file> (unless the <tt/-c/ command line option
is given). Configuration may be changed at user's request: if you modify the
config file and then signal BIRD with <tt/SIGHUP/, it will adjust to the new
config. Then there's the client which allows you to talk with BIRD in an
extensive way.

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

<p>Here is an example of a simple config file. It enables synchronization of
432
433
routing tables with OS kernel, learns network interfaces and runs RIP on all
network interfaces found.
434

435
<code>
436
protocol kernel {
437
438
439
	ipv4 {
		export all;	# Default is export none
	};
Pavel Machek's avatar
Pavel Machek committed
440
	persist;		# Don't remove routes on BIRD shutdown
441
442
443
444
445
446
}

protocol device {
}

protocol rip {
447
448
449
450
	ipv4 {
		import all;
		export all;
	};
Ondřej Zajíček's avatar
Ondřej Zajíček committed
451
	interface "*";
452
}
453
</code>
454

455

456
<sect>Global options
457
<label id="global-opts">
Pavel Machek's avatar
Pavel Machek committed
458

459
<p><descrip>
Jan Maria Matejka's avatar
Jan Maria Matejka committed
460
	<tag><label id="opt-include">include "<m/filename/";</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
461
462
463
464
465
466
467
468
	This statement causes inclusion of a new file. The <m/filename/ could
	also be a wildcard, in that case matching files are included in
	alphabetic order. The maximal depth is 8. Note that this statement can
	be used anywhere in the config file, even inside other options, but
	always on the beginning of line. In the following example, the first
	semicolon belongs to the <cf/include/, the second to <cf/ipv6 table/.
	If the <file/tablename.conf/ contains exactly one token (the name of the
	table), this construction is correct:
Jan Maria Matejka's avatar
Jan Maria Matejka committed
469
470
471
472
<code>
ipv6 table
include "tablename.conf";;
</code>
473

474
	<tag><label id="opt-log">log "<m/filename/"|syslog [name <m/name/]|stderr all|{ <m/list of classes/ }</tag>
475
	Set logging of messages having the given class (either <cf/all/ or
476
	<cf/{ error|trace [, <m/.../] }/ etc.) into selected destination (a file specified
477
478
	as a filename string, syslog with optional name argument, or the stderr
	output). Classes are:
479
	<cf/info/, <cf/warning/, <cf/error/ and <cf/fatal/ for messages about local problems,
Ondřej Zajíček's avatar
Ondřej Zajíček committed
480
481
482
	<cf/debug/ for debugging messages,
	<cf/trace/ when you want to know what happens in the network,
	<cf/remote/ for messages about misbehavior of remote machines,
483
	<cf/auth/ about authentication failures,
484
485
486
	<cf/bug/ for internal BIRD bugs.
	You may specify more than one <cf/log/ line to establish logging to
	multiple destinations. Default: log everything to the system log.
487

488
	<tag><label id="opt-debug-protocols">debug protocols all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
489
490
	Set global defaults of protocol debugging options. See <cf/debug/ in the
	following section. Default: off.
Pavel Machek's avatar
Pavel Machek committed
491

492
	<tag><label id="opt-debug-commands">debug commands <m/number/</tag>
493
494
495
	Control logging of client connections (0 for no logging, 1 for logging
	of connects and disconnects, 2 and higher for logging of all client
	commands). Default: 0.
496

497
	<tag><label id="opt-debug-latency">debug latency <m/switch/</tag>
498
499
500
	Activate tracking of elapsed time for internal events. Recent events
	could be examined using <cf/dump events/ command. Default: off.

501
	<tag><label id="opt-debug-latency-limit">debug latency limit <m/time/</tag>
502
503
504
	If <cf/debug latency/ is enabled, this option allows to specify a limit
	for elapsed time. Events exceeding the limit are logged. Default: 1 s.

505
	<tag><label id="opt-watchdog-warn">watchdog warning <m/time/</tag>
506
507
508
	Set time limit for I/O loop cycle. If one iteration took more time to
	complete, a warning is logged. Default: 5 s.

509
	<tag><label id="opt-watchdog-timeout">watchdog timeout <m/time/</tag>
510
511
512
513
	Set time limit for I/O loop cycle. If the limit is breached, BIRD is
	killed by abort signal. The timeout has effective granularity of
	seconds, zero means disabled. Default: disabled (0).

514
	<tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag>
515
516
	Set MRTdump file name. This option must be specified to allow MRTdump
	feature. Default: no dump file.
517

518
	<tag><label id="opt-mrtdump-protocols">mrtdump protocols all|off|{ states|messages [, <m/.../] }</tag>
519
520
	Set global defaults of MRTdump options. See <cf/mrtdump/ in the
	following section. Default: off.
521

522
	<tag><label id="opt-filter">filter <m/name local variables/{ <m/commands/ }</tag>
523
524
	Define a filter. You can learn more about filters in the following
	chapter.
525

526
	<tag><label id="opt-function">function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
527
	Define a function. You can learn more about functions in the following chapter.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
528

Ondřej Zajíček's avatar
Ondřej Zajíček committed
529
	<tag><label id="opt-protocol">protocol rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
530
531
532
533
534
535
536
	Define a protocol instance called <cf><m/name/</cf> (or with a name like
	"rip5" generated automatically if you don't specify any
	<cf><m/name/</cf>). You can learn more about configuring protocols in
	their own chapters. When <cf>from <m/name2/</cf> expression is used,
	initial protocol options are taken from protocol or template
	<cf><m/name2/</cf> You can run more than one instance of most protocols
	(like RIP or BGP). By default, no instances are configured.
537

Ondřej Zajíček's avatar
Ondřej Zajíček committed
538
	<tag><label id="opt-template">template rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
539
540
541
542
543
544
545
	Define a protocol template instance called <m/name/ (or with a name like
	"bgp1" generated automatically if you don't specify any	<m/name/).
	Protocol templates can be used to group common options when many
	similarly configured protocol instances are to be defined. Protocol
	instances (and other templates) can use templates by using <cf/from/
	expression and the name of the template. At the moment templates (and
	<cf/from/ expression) are not implemented for OSPF protocol.
546

547
	<tag><label id="opt-define">define <m/constant/ = <m/expression/</tag>
548
549
550
551
	Define a constant. You can use it later in every place you could use a
	value of the same type. Besides, there are some predefined numeric
	constants based on /etc/iproute2/rt_* files. A list of defined constants
	can be seen (together with other symbols) using 'show symbols' command.
552

553
554
	<tag><label id="opt-router-id">router id <m/IPv4 address/</tag>
	Set BIRD's router ID. It's a world-wide unique identification of your
Jan Maria Matejka's avatar
Jan Maria Matejka committed
555
556
	router, usually one of router's IPv4 addresses. Default: the lowest
	IPv4 address of a non-loopback interface.
557

558
	<tag><label id="opt-router-id-from">router id from [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../]</tag>
Jan Maria Matejka's avatar
Jan Maria Matejka committed
559
560
	Set BIRD's router ID based on an IPv4 address of an interface specified by
	an interface pattern.
561
	See <ref id="proto-iface" name="interface"> section for detailed
562
	description of interface patterns with extended clauses.
563

564
	<tag><label id="opt-graceful-restart">graceful restart wait <m/number/</tag>
565
566
567
568
569
	During graceful restart recovery, BIRD waits for convergence of routing
	protocols. This option allows to specify a timeout for the recovery to
	prevent waiting indefinitely if some protocols cannot converge. Default:
	240 seconds.

570
	<tag><label id="opt-timeformat">timeformat route|protocol|base|log "<m/format1/" [<m/limit/ "<m/format2/"]</tag>
571
572
573
574
575
576
577
	This option allows to specify a format of date/time used by BIRD. The
	first argument specifies for which purpose such format is used.
	<cf/route/ is a format used in 'show route' command output,
	<cf/protocol/ is used in 'show protocols' command output, <cf/base/ is
	used for other commands and <cf/log/ is used in a log file.

	"<m/format1/" is a format string using <it/strftime(3)/ notation (see
578
579
580
581
582
583
584
585
586
587
	<it/man strftime/ for details). It is extended to support sub-second
	time part with variable precision (up to microseconds) using "%f"
	conversion code (e.g., "%T.%3f" is hh:mm:ss.sss time). <m/limit/ and
	"<m/format2/" allow to specify the second format string for times in
	past deeper than <m/limit/ seconds.

	There are several shorthands: <cf/iso long/ is a ISO 8601 date/time
	format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F
	%T"/. Similarly, <cf/iso long ms/ and <cf/iso long us/ are ISO 8601
	date/time formats with millisecond or microsecond precision.
588
589
	<cf/iso short/ is a variant of ISO 8601 that uses just the time format
	(hh:mm:ss) for near times (up to 20 hours in the past) and the date
590
591
592
	format (YYYY-MM-DD) for far times. This is a shorthand for <cf/"%T"
	72000 "%F"/. And there are also <cf/iso short ms/ and <cf/iso short us/
	high-precision variants of that.
593

594
595
	By default, BIRD uses the <cf/iso short ms/ format for <cf/route/ and
	<cf/protocol/ times, and the <cf/iso long ms/ format for <cf/base/ and
596
597
	<cf/log/ times.

Jan Maria Matejka's avatar
Jan Maria Matejka committed
598
	<tag><label id="opt-table"><m/nettype/ table <m/name/ [sorted]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
599
600
601
602
603
	Create a new routing table. The default routing tables <cf/master4/ and
	<cf/master6/ are created implicitly, other routing tables have to be
	added by this command.  Option <cf/sorted/ can be used to enable sorting
	of routes, see <ref id="dsc-table-sorted" name="sorted table">
	description for details.
604

605
	<tag><label id="opt-eval">eval <m/expr/</tag>
Jan Maria Matejka's avatar
Jan Maria Matejka committed
606
	Evaluates given filter expression. It is used by the developers for testing of filters.
607
608
</descrip>

Ondřej Zajíček's avatar
Ondřej Zajíček committed
609

610
<sect>Protocol options
611
<label id="protocol-opts">
612

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

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

Pavel Machek's avatar
Pavel Machek committed
623
<descrip>
624
	<tag><label id="proto-disabled">disabled <m/switch/</tag>
625
626
627
	Disables the protocol. You can change the disable/enable status from the
	command line interface without needing to touch the configuration.
	Disabled protocols are not activated. Default: protocol is enabled.
Pavel Machek's avatar
Pavel Machek committed
628

629
	<tag><label id="proto-debug">debug all|off|{ states|routes|filters|interfaces|events|packets [, <m/.../] }</tag>
Pavel Machek's avatar
Pavel Machek committed
630
631
632
633
	Set protocol debugging options. If asked, each protocol is capable of
	writing trace messages about its work to the log (with category
	<cf/trace/). You can either request printing of <cf/all/ trace messages
	or only of the types selected: <cf/states/ for protocol state changes
634
635
636
637
638
	(protocol going up, down, starting, stopping etc.), <cf/routes/ for
	routes exchanged with the routing table, <cf/filters/ for details on
	route filtering, <cf/interfaces/ for interface change events sent to the
	protocol, <cf/events/ for events internal to the protocol and <cf/packets/
	for packets sent and received by the protocol. Default: off.
Pavel Machek's avatar
Pavel Machek committed
639

640
	<tag><label id="proto-mrtdump">mrtdump all|off|{ states|messages [, <m/.../] }</tag>
641
642
643
644
645
646
647
648
	Set protocol MRTdump flags. MRTdump is a standard binary format for
	logging information from routing protocols and daemons. These flags
	control what kind of information is logged from the protocol to the
	MRTdump file (which must be specified by global <cf/mrtdump/ option, see
	the previous section). Although these flags are similar to flags of
	<cf/debug/ option, their meaning is different and protocol-specific. For
	BGP protocol, <cf/states/ logs BGP state changes and <cf/messages/ logs
	received BGP messages. Other protocols does not support MRTdump yet.
649

650
	<tag><label id="proto-router-id">router id <m/IPv4 address/</tag>
651
652
	This option can be used to override global router id for a given
	protocol. Default: uses global router id.
653

654
	<tag><label id="proto-description">description "<m/text/"</tag>
655
656
	This is an optional description of the protocol. It is displayed as a
	part of the output of 'show route all' command.
657

Ondřej Zajíček's avatar
Ondřej Zajíček committed
658
659
660
661
662
	<tag><label id="proto-vrf">vrf "<m/text/"</tag>
	Associate the protocol with specific VRF. The protocol will be
	restricted to interfaces assigned to the VRF and will use sockets bound
	to the VRF. Appropriate VRF interface must exist on OS level. For kernel
	protocol, an appropriate table still must be explicitly selected by
Ondřej Zajíček's avatar
Ondřej Zajíček committed
663
664
665
	<cf/table/ option. Note that for proper VRF support it is necessary to
	use Linux kernel version at least 4.14, older versions have limited VRF
	implementation.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
666
667

	<tag><label id="proto-channel"><m/channel name/ [{<m/channel config/}]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
668
669
670
671
	Every channel must be explicitly stated. See the protocol-specific
	configuration for the list of supported channel names. See the
	<ref id="channel-opts" name="channel configuration section"> for channel
	definition.
672
673
</descrip>

674
<p>There are several options that give sense only with certain protocols:
675
676

<descrip>
677
	<tag><label id="proto-iface">interface [-] [ "<m/mask/" ] [ <m/prefix/ ] [, <m/.../] [ { <m/option/; [<m/.../] } ]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
678
679
	Specifies a set of interfaces on which the protocol is activated with
	given interface-specific options. A set of interfaces specified by one
680
681
	interface option is described using an interface pattern. The interface
	pattern consists of a sequence of clauses (separated by commas), each
682
683
	clause is a mask specified as a shell-like pattern. Interfaces are
	matched by their name.
684
685
686

	An interface matches the pattern if it matches any of its clauses. If
	the clause begins with <cf/-/, matching interfaces are excluded. Patterns
687
	are processed left-to-right, thus <cf/interface "eth0", -"eth*", "*";/
688
689
	means eth0 and all non-ethernets.

690
691
692
693
694
695
	Some protocols (namely OSPFv2 and Direct) support extended clauses that
	may contain a mask, a prefix, or both of them. An interface matches such
	clause if its name matches the mask (if specified) and its address
	matches the prefix (if specified). Extended clauses are used when the
	protocol handles multiple addresses on an interface independently.

696
697
698
	An interface option can be used more times with different interface-specific
	options, in that case for given interface the first matching interface
	option is used.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
699

Ondřej Zajíček's avatar
Ondřej Zajíček committed
700
	This option is allowed in Babel, BFD, Device, Direct, OSPF, RAdv and RIP
Jan Maria Matejka's avatar
Jan Maria Matejka committed
701
	protocols. In OSPF protocol it is used in the <cf/area/ subsection.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
702
703
704
705
706

	Default: none.

	Examples:

707
708
	<cf>interface "*" { type broadcast; };</cf> - start the protocol on all
	interfaces with <cf>type broadcast</cf> option.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
709

710
711
	<cf>interface "eth1", "eth4", "eth5" { type ptp; };</cf> - start the
	protocol on enumerated interfaces with <cf>type ptp</cf> option.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
712

713
714
715
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
	on all interfaces that have address from 192.168.0.0/16, but not from
	192.168.1.0/24.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
716

717
718
719
	<cf>interface -192.168.1.0/24, 192.168.0.0/16;</cf> - start the protocol
	on all interfaces that have address from 192.168.0.0/16, but not from
	192.168.1.0/24.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
720
721
722
723

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

724
	<tag><label id="proto-tx-class">tx class|dscp <m/num/</tag>
725
726
727
728
729
730
731
	This option specifies the value of ToS/DS/Class field in IP headers of
	the outgoing protocol packets. This may affect how the protocol packets
	are processed by the network relative to the other network traffic. With
	<cf/class/ keyword, the value (0-255) is used for the whole ToS/Class
	octet (but two bits reserved for ECN are ignored). With	<cf/dscp/
	keyword, the value (0-63) is used just for the DS field in the octet.
	Default value is 0xc0 (DSCP 0x30 - CS6).
732

733
	<tag><label id="proto-tx-priority">tx priority <m/num/</tag>
734
735
736
	This option specifies the local packet priority. This may affect how the
	protocol packets are processed in the local TX queues. This option is
	Linux specific. Default value is 7 (highest priority, privileged traffic).
737

Pavel Tvrdík's avatar
Pavel Tvrdík committed
738
739
740
741
742
743
744
	<tag><label id="proto-pass">password "<m/password/" [ { <m>password options</m> } ]</tag>
	Specifies a password that can be used by the protocol as a shared secret
	key. Password option can be used more times to specify more passwords.
	If more passwords are specified, it is a protocol-dependent decision
	which one is really used. Specifying passwords does not mean that
	authentication is enabled, authentication can be enabled by separate,
	protocol-dependent <cf/authentication/ option.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
745

Ondřej Zajíček's avatar
Ondřej Zajíček committed
746
	This option is allowed in BFD, OSPF and RIP protocols. BGP has also
Ondřej Zajíček's avatar
Ondřej Zajíček committed
747
748
749
750
751
752
753
754
	<cf/password/ option, but it is slightly different and described
	separately.
	Default: none.
</descrip>

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

<descrip>
755
	<tag><label id="proto-pass-id">id <M>num</M></tag>
756
	ID of the password, (1-255). If it is not used, BIRD will choose ID based
757
758
759
760
	on an order of the password item in the interface. For example, second
	password item in one interface will have default ID 2. ID is used by
	some routing protocols to identify which password was used to
	authenticate protocol packets.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
761

762
	<tag><label id="proto-pass-gen-from">generate from "<m/time/"</tag>
763
764
	The start time of the usage of the password for packet signing.
	The format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
765

766
	<tag><label id="proto-pass-gen-to">generate to "<m/time/"</tag>
767
	The last time of the usage of the password for packet signing.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
768

769
	<tag><label id="proto-pass-accept-from">accept from "<m/time/"</tag>
770
	The start time of the usage of the password for packet verification.
Pavel Machek's avatar
Pavel Machek committed
771

772
	<tag><label id="proto-pass-accept-to">accept to "<m/time/"</tag>
773
	The last time of the usage of the password for packet verification.
Pavel Tvrdík's avatar
Pavel Tvrdík committed
774
775
776
777
778
779
780
781
782
783
784
785
786

	<tag><label id="proto-pass-from">from "<m/time/"</tag>
	Shorthand for setting both <cf/generate from/ and <cf/accept from/.

	<tag><label id="proto-pass-to">to "<m/time/"</tag>
	Shorthand for setting both <cf/generate to/ and <cf/accept to/.

	<tag><label id="proto-pass-algorithm">algorithm ( keyed md5 | keyed sha1 | hmac sha1 | hmac sha256 | hmac sha384 | hmac sha512 )</tag>
	The message authentication algorithm for the password when cryptographic
	authentication is enabled. The default value depends on the protocol.
	For RIP and OSPFv2 it is Keyed-MD5 (for compatibility), for OSPFv3
	protocol it is HMAC-SHA-256.

787
</descrip>
788

Ondřej Zajíček's avatar
Ondřej Zajíček committed
789

Jan Maria Matejka's avatar
Jan Maria Matejka committed
790
791
<sect>Channel options
<label id="channel-opts">
792

Jan Maria Matejka's avatar
Jan Maria Matejka committed
793
<p>Every channel belongs to a protocol and is configured inside its block. The
794
795
796
797
minimal channel config is empty, then it uses default values. The name of the
channel implies its nettype. Channel definitions can be inherited from protocol
templates. Multiple definitions of the same channel are forbidden, but channels
inherited from templates can be updated by new definitions.
798

Jan Maria Matejka's avatar
Jan Maria Matejka committed
799
800
<descrip>
	<tag><label id="proto-table">table <m/name/</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
801
802
803
804
805
806
	Specify a table to which the channel is connected. Default: the first
	table of given nettype.

	<tag><label id="proto-preference">preference <m/expr/</tag>
	Sets the preference of routes generated by the protocol and imported
	through this channel. Default: protocol dependent.
807

Jan Maria Matejka's avatar
Jan Maria Matejka committed
808
809
810
	<tag><label id="proto-import">import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/boolean filter expression/</tag>
	Specify a filter to be used for filtering routes coming from the
	protocol to the routing table. <cf/all/ is for keeping all routes,
811
812
	<cf/none/ is for dropping all routes. Default: <cf/all/ (except for
	EBGP).
813

Jan Maria Matejka's avatar
Jan Maria Matejka committed
814
815
	<tag><label id="proto-export">export <m/filter/</tag>
	This is similar to the <cf>import</cf> keyword, except that it works in
816
817
	the direction from the routing table to the protocol. Default: <cf/none/
	(except for EBGP).
818

Jan Maria Matejka's avatar
Jan Maria Matejka committed
819
820
821
822
823
824
	<tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag>
	Usually, if an import filter rejects a route, the route is forgotten.
	When this option is active, these routes are kept in the routing table,
	but they are hidden and not propagated to other protocols. But it is
	possible to show them using <cf/show route filtered/. Note that this
	option does not work for the pipe protocol. Default: off.
825

Jan Maria Matejka's avatar
Jan Maria Matejka committed
826
827
828
829
830
831
832
833
	<tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
	Specify an import route limit (a maximum number of routes imported from
	the protocol) and optionally the action to be taken when the limit is
	hit. Warn action just prints warning log message. Block action discards
	new routes coming from the protocol. Restart and disable actions shut
	the protocol down like appropriate commands. Disable is the default
	action if an action is not explicitly specified. Note that limits are
	reset during protocol reconfigure, reload or restart. Default: <cf/off/.
834

Jan Maria Matejka's avatar
Jan Maria Matejka committed
835
836
837
838
839
840
841
842
843
	<tag><label id="proto-receive-limit">receive limit [<m/number/ | off ] [action warn | block | restart | disable]</tag>
	Specify an receive route limit (a maximum number of routes received from
	the protocol and remembered). It works almost identically to <cf>import
	limit</cf> option, the only difference is that if <cf/import keep
	filtered/ option is active, filtered routes are counted towards the
	limit and blocked routes are forgotten, as the main purpose of the
	receive limit is to protect routing tables from overflow. Import limit,
	on the contrary, counts accepted routes only and routes blocked by the
	limit are handled like filtered routes. Default: <cf/off/.
844

Jan Maria Matejka's avatar
Jan Maria Matejka committed
845
846
847
848
849
850
851
852
853
	<tag><label id="proto-export-limit">export limit [ <m/number/ | off ] [action warn | block | restart | disable]</tag>
	Specify an export route limit, works similarly to the <cf>import
	limit</cf> option, but for the routes exported to the protocol. This
	option is experimental, there are some problems in details of its
	behavior -- the number of exported routes can temporarily exceed the
	limit without triggering it during protocol reload, exported routes
	counter ignores route blocking and block action also blocks route
	updates of already accepted routes -- and these details will probably
	change in the future. Default: <cf/off/.
854
855
</descrip>

Jan Maria Matejka's avatar
Jan Maria Matejka committed
856
857
858
859
860
<p>This is a trivial example of RIP configured for IPv6 on all interfaces:
<code>
protocol rip ng {
	ipv6;
	interface "*";
861
862
863
}
</code>

864
<p>This is a non-trivial example.
Jan Maria Matejka's avatar
Jan Maria Matejka committed
865
866
867
868
869
870
871
872
873
<code>
protocol rip ng {
	ipv6 {
		table mytable6;
		import filter { ... };
		export filter { ... };
		import limit 50;
	};
	interface "*";
874
875
876
}
</code>

877
878
879
880
881
882
883
884
<p>And this is even more complicated example using templates.
<code>
template bgp {
	local 198.51.100.14 as 65000;

	ipv4 {
		table mytable4;
		import filter { ... };
885
		export none;
886
887
888
889
	};
	ipv6 {
		table mytable6;
		import filter { ... };
890
		export none;
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
	};
}

protocol bgp from  {
	neighbor 198.51.100.130 as 64496;

	# IPv4 channel is inherited as-is, while IPv6
	# channel is adjusted by export filter option
	ipv6 {
		export filter { ... };
	};
}
</code>


Pavel Machek's avatar
Pavel Machek committed
906
<chapt>Remote control
907
<label id="remote-control">
Pavel Machek's avatar
Pavel Machek committed
908

909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
<p>You can use the command-line client <file>birdc</file> to talk with a running
BIRD. Communication is done using a <file/bird.ctl/ UNIX domain socket (unless
changed with the <tt/-s/ option given to both the server and the client). The
commands can perform simple actions such as enabling/disabling of protocols,
telling BIRD to show various information, telling it to show routing table
filtered by filter, or asking BIRD to reconfigure. Press <tt/?/ at any time to
get online help. Option <tt/-r/ can be used to enable a restricted mode of BIRD
client, which allows just read-only commands (<cf/show .../). Option <tt/-v/ can
be passed to the client, to make it dump numeric return codes along with the
messages. You do not necessarily need to use <file/birdc/ to talk to BIRD, your
own applications could do that, too -- the format of communication between BIRD
and <file/birdc/ is stable (see the programmer's documentation).

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

<p>Many commands have the <m/name/ of the protocol instance as an argument.
Ondřej Zajíček's avatar
Ondřej Zajíček committed
928
929
This argument can be omitted if there exists only a single instance.

Pavel Machek's avatar
Pavel Machek committed
930
<p>Here is a brief list of supported functions:
931
932

<descrip>
933
	<tag><label id="cli-show-status">show status</tag>
934
935
	Show router status, that is BIRD version, uptime and time from last
	reconfiguration.
Pavel Machek's avatar
Pavel Machek committed
936

937
	<tag><label id="cli-show-interfaces">show interfaces [summary]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
938
939
940
	Show the list of interfaces. For each interface, print its type, state,
	MTU and addresses assigned.

941
	<tag><label id="cli-show-protocols">show protocols [all]</tag>
942
943
944
	Show list of protocol instances along with tables they are connected to
	and protocol status, possibly giving verbose information, if <cf/all/ is
	specified.
945

Jan Maria Matejka's avatar
Jan Maria Matejka committed
946
	<!-- TODO: Move these protocol-specific remote control commands to the protocol sections -->
947
	<tag><label id="cli-show-ospf-iface">show ospf interface [<m/name/] ["<m/interface/"]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
948
949
	Show detailed information about OSPF interfaces.

950
	<tag><label id="cli-show-ospf-neighbors">show ospf neighbors [<m/name/] ["<m/interface/"]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
951
952
	Show a list of OSPF neighbors and a state of adjacency to them.

953
	<tag><label id="cli-show-ospf-state">show ospf state [all] [<m/name/]</tag>
954
955
956
957
958
959
	Show detailed information about OSPF areas based on a content of the
	link-state database. It shows network topology, stub networks,
	aggregated networks and routers from other areas and external routes.
	The command shows information about reachable network nodes, use option
	<cf/all/ to show information about all network nodes in the link-state
	database.
960

961
	<tag><label id="cli-show-ospf-topology">show ospf topology [all] [<m/name/]</tag>
962
963
	Show a topology of OSPF areas based on a content of the link-state
	database. It is just a stripped-down version of 'show ospf state'.
964

965
	<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>
966
967
	Show contents of an OSPF LSA database. Options could be used to filter
	entries.
968

969
	<tag><label id="cli-show-rip-interfaces">show rip interfaces [<m/name/] ["<m/interface/"]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
970
971
	Show detailed information about RIP interfaces.

972
	<tag><label id="cli-show-rip-neighbors">show rip neighbors [<m/name/] ["<m/interface/"]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
973
974
	Show a list of RIP neighbors and associated state.

975
	<tag><label id="cli-show-static">show static [<m/name/]</tag>
Ondřej Zajíček's avatar
Ondřej Zajíček committed
976
977
	Show detailed information about static routes.

978
	<tag><label id="cli-show-bfd-sessions">show bfd sessions [<m/name/]</tag>
979
980
	Show information about BFD sessions.

981
	<tag><label id="cli-show-symbols">show symbols [table|filter|function|protocol|template|roa|<m/symbol/]</tag>
982
983
	Show the list of symbols defined in the configuration (names of
	protocols, routing tables etc.).
Pavel Machek's avatar
Pavel Machek committed
984

985
	<tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table (<m/t/ | all)] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [(stats|count)] [<m/options/]</tag>
986
	Show contents of specified routing tables, that is routes, their metrics
987
	and (in case the <cf/all/ switch is given) all their attributes.
Pavel Machek's avatar
Pavel Machek committed
988
989
990
991
992
993
994
995

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

996
997
998
999
1000
1001
1002
1003
1004
	<p>The <cf/show route/ command can process one or multiple routing
	tables. The set of selected tables is determined on three levels: First,
	tables can be explicitly selected by <cf/table/ switch, which could be
	used multiple times, all tables are specified by <cf/table all/. Second,
	tables can be implicitly selected by channels or protocols that are
	arguments of several other switches (e.g., <cf/export/, <cf/protocol/).
	Last, the set of default tables is used: <cf/master4/, <cf/master6/ and
	each first table of any other network type.

Pavel Machek's avatar
Pavel Machek committed
1005
1006
1007
	<p>You can also ask for printing only routes processed and accepted by
	a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ }
	</cf> or matching a given condition (<cf>where <m/condition/</cf>).
1008
1009

	The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for
1010
1011
1012
1013
	printing of routes that are exported to the specified protocol or
	channel. With <cf/preexport/, the export filter of the channel is
	skipped. With <cf/noexport/, routes rejected by the export filter are
	printed instead. Note that routes not exported for other reasons
1014
	(e.g. secondary routes or routes imported from that protocol) are not
1015
1016
	printed even with <cf/noexport/. These switches also imply that
	associated routing tables are selected instead of default ones.
Pavel Machek's avatar
Pavel Machek committed
1017

1018
	<p>You can also select just routes added by a specific protocol.
1019
1020
	<cf>protocol <m/p/</cf>. This switch also implies that associated
	routing tables are selected instead of default ones.
1021

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

Pavel Machek's avatar
Pavel Machek committed
1026
1027
1028
	<p>The <cf/stats/ switch requests showing of route statistics (the
	number of networks, number of routes before and after filtering). If
	you use <cf/count/ instead, only the statistics will be printed.
1029

1030
	<tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag>
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
	Reload configuration from a given file. BIRD will smoothly switch itself
	to the new configuration, protocols are reconfigured if possible,
	restarted otherwise. Changes in filters usually lead to restart of
	affected protocols.

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

	If <cf/timeout/ option is used, config timer is activated. The new
	configuration could be either confirmed using <cf/configure confirm/
	command, or it will be reverted to the old one when the config timer
	expires. This is useful for cases when reconfiguration breaks current
1045
	routing and a router becomes inaccessible for an administrator. The
1046
1047
	config timeout expiration is equivalent to <cf/configure undo/
	command. The timeout duration could be specified, default is 300 s.
1048

1049
	<tag><label id="cli-configure-confirm">configure confirm</tag>
1050
1051
1052
	Deactivate the config undo timer and therefore confirm the current
	configuration.

1053
	<tag><label id="cli-configure-undo">configure undo</tag>
1054
1055
1056
1057
1058
1059
	Undo the last configuration change and smoothly switch back to the
	previous (stored) configuration. If the last configuration change was
	soft, the undo change is also soft. There is only one level of undo, but
	in some specific cases when several reconfiguration requests are given
	immediately in a row and the intermediate ones are skipped then the undo
	also skips them back.
1060

1061
	<tag><label id="cli-configure-check">configure check ["<m/config file/"]</tag>
1062
1063
	Read and parse given config file, but do not use it. useful for checking
	syntactic and some semantic validity of an config file.
1064

1065
	<tag><label id="cli-enable-disable-restart">enable|disable|restart <m/name/|"<m/pattern/"|all</tag>
1066
1067
	Enable, disable or restart a given protocol instance, instances matching
	the <cf><m/pattern/</cf> or <cf/all/ instances.
1068

1069
	<tag><label id="cli-reload">reload [in|out] <m/name/|"<m/pattern/"|all</tag>
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
	Reload a given protocol instance, that means re-import routes from the
	protocol instance and re-export preferred routes to the instance. If
	<cf/in/ or <cf/out/ options are used, the command is restricted to one
	direction (re-import or re-export).

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

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

1086
	<tag><label id="cli-down">down</tag>
Pavel Machek's avatar
Pavel Machek committed
1087
	Shut BIRD down.
1088

1089
	<tag><label id="cli-debug">debug <m/protocol/|<m/pattern/|all all|off|{ states|routes|filters|events|packets [, <m/.../] }</tag>
1090
	Control protocol debugging.
1091

1092
	<tag><label id="cli-dump">dump resources|sockets|interfaces|neighbors|attributes|routes|protocols</tag>
1093
1094
	Dump contents of internal data structures to the debugging output.

1095
	<tag><label id="cli-echo">echo all|off|{ <m/list of log classes/ } [ <m/buffer-size/ ]</tag>
1096
	Control echoing of log messages to the command-line output.
1097
	See <ref id="opt-log" name="log option"> for a list of log classes.
1098

1099
	<tag><label id="cli-eval">eval <m/expr/</tag>
1100
	Evaluate given expression.
1101
</descrip>
Pavel Machek's avatar
Pavel Machek committed
1102

1103

1104
<chapt>Filters
1105
<label id="filters">
1106

1107
<sect>Introduction
1108
<label id="filters-intro">
1109

1110
1111
1112
1113
1114
1115
<p>BIRD contains a simple programming language. (No, it can't yet read mail :-).
There are two objects in this language: filters and functions. Filters are
interpreted by BIRD core when a route is being passed between protocols and
routing tables. The filter language contains control structures such as if's and
switches, but it allows no loops. An example of a filter using many features can
be found in <file>filter/test.conf</file>.
1116

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

1122
<code>
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
filter not_too_far
int var;
{
	if defined( rip_metric ) then
		var = rip_metric;
	else {
		var = 1;
		rip_metric = 1;
	}
	if rip_metric &gt; 10 then
		reject "RIP metric is too big";
	else
		accept "ok";
}
1137
</code>
1138

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

1148
1149
1150
<p>BIRD supports functions, so that you don't have to repeat the same blocks of
code over and over. Functions can have zero or more parameters and they can have
local variables. Recursion is not allowed. Function definitions look like this:
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164

<code>
function name ()
int local_variable;
{
	local_variable = 5;
}

function with_parameters (int parameter)
{
	print parameter;
}
</code>

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

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

1177
1178
<p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf>
from the command line client. An example session might look like:
Pavel Machek's avatar
Pavel Machek committed
1179
1180
1181
1182
1183
1184
1185
1186
1187

<code>
pavel@bug:~/bird$ ./birdc -s bird.ctl
BIRD 0.0.0 ready.
bird> show route
10.0.0.0/8         dev eth0 [direct1 23:21] (240)
195.113.30.2/32    dev tunl1 [direct1 23:21] (240)
127.0.0.0/8        dev lo [direct1 23:21] (240)
bird> show route ?
1188
show route [<prefix>] [table <t>] [filter <f>] [all] [primary]...
Martin Mareš's avatar
Fixes.    
Martin Mareš committed
1189
bird> show route filter { if 127.0.0.5 &tilde; net then accept; }
Pavel Machek's avatar
Pavel Machek committed
1190
1191
1192
1193
127.0.0.0/8        dev lo [direct1 23:21] (240)
bird>
</code>