Statistics
| Branch: | Revision:

iof-bird-daemon / doc / bird.sgml @ 249d238c

History | View | Annotate | Download (13.5 KB)

1
<!doctype linuxdoc system>
2

    
3
<!--
4
	Bird documentation
5

    
6
    This is bird documentation system. It looks like html, but it is _not_ html: nonstandard
7
    extensions are in use in order to auto-generate nice tex source. Use TT tag to markup short
8
    texts that should be rendered in fixed-space font, and further specify what kind of text this
9
    is. Currently TT file and TT conf are being used. For multi-line texts, use PRE section, again
10
    with option saying what kind of section this is. Use DL conf for definition of configuration
11
    keywords.
12

    
13
    (set-fill-column 100)
14

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

    
17
 -->
18

    
19
<article>
20

    
21
<title>Bird
22
<author>
23
Pavel Machek <tt/pavel@ucw.cz/
24

    
25
<date>2000
26
<abstract>
27
This document contains documentation for Basic Internet Routing Daemon
28
</abstract>
29

    
30
<!-- Table of contents -->
31
<toc>
32

    
33
<!-- Begin the document -->
34

    
35
<sect>Introduction
36

    
37
<sect1>What is bird
38

    
39
<p><label id="intro">
40
You may wonder what 'bird' means. It is acronym of 'Basic Internet Routing Daemon', and we think
41
that's cool name. Its task is similar to what firmware of Cisco routers does, or what gated
42
(<HTMLURL URL="fixme">) does. However, you can not run Cisco's firmware on "normal" computer
43
and gated is really hard to configure and comes under wrong license. Bird is being developed on
44
Charles University, Prague, and can be freely distributed under terms of GNU General Public
45
License. Bird is designed to run on unix and unix-like systems, it is primarily developed on Linux.
46

    
47
<sect1>About this documentation
48

    
49
<p>This documentation can have 4 forms: extended html (this is master copy), html with stripped
50
extensions, ascii text (generated from html) and dvi/postscript (generated from html using
51
html2latex and latex). You should always edit master copy; if you do so be sure to read comment at
52
beggining of file. If you want to view documentation, you can either launch your www browser at
53
master copy (and hope that browser does not have incompatible extensions from our), or you can
54
generate nice printed copy.
55

    
56
<sect1>Configuration
57

    
58
<p>Bird is configured using text configuration file. At startup, bird reads <file/bird.conf/
59
(unless -c command line parameter is given). Really simple configuration file might look like this:
60

    
61
<cf><verb>
62

    
63
protocol kernel {
64
	persist;		# Don't remove routes on bird shutdown
65
	scan time 20;		# Scan kernel routing table every 20 seconds
66
	export all;		# Default is export none
67
}
68

    
69
protocol device {
70
	scan time 10;		# Scan interfaces every 10 seconds
71
}
72

    
73
protocol rip {
74
	export all;
75
	import all;
76
}
77
</verb></cf>
78

    
79
<p>Everything on a line after # is a comment, whitespace is
80
ignored. If there's variable number of options, it is grouped using {
81
} brackets. 
82
				
83
<descrip>
84
	<tag>log "<i/filename/"|syslog|stderr all|{ debug, trace, info,
85
	remote, warning, error, auth, fatal, bug }</tag> set logging of
86
	classes (either all or { error, trace } etc.) into selected destination. 
87
				  
88
	<tag>debug protocols all|off|{ states, routes, filters,
89
	interfaces, events, packets }</tag> set debugging options.
90

    
91
	<tag>filter <i/name/ { <i/commands/ }</tag> define filter. You can
92
	learn more about filters in next chapter.
93

    
94
	<tag>protocol rip|ospf|bgp <i/name/ { <i>protocol options</i> }</tag> define
95
	protocol instance, called name. You can learn more about
96
	configuring protocols in their own chapters.
97

    
98
	<tag>define constant = expression</tag> define constant. You can
99
	use it later in every place you could use simple integer.
100

    
101
	<tag>router id <i/ip_address/</tag> set router id.
102

    
103
	<tag>table <i/name/</tag> create new routing table.
104
</descrip>
105

    
106
<p>You can find example of more complicated configuration file in <file>doc/bird.conf.example</file>.
107

    
108
<sect>Filters
109

    
110
<sect1>Introduction
111

    
112
<p>Bird contains rather simple programming language. (No, it can not yet read mail :-). There are
113
two objects in this language: filters and functions. Filters are called by bird core when route is
114
being passed between protocol and main routing table, and filters may call functions. Functions may
115
call other functions but recursion is not allowed. Filter language contains control structures such
116
as if's and switches, but it allows no loops. Filters are
117
interpretted. Filter using many features can be found in <file>filter/test.conf</file>. 
118

    
119
<p>There's one strange thing with filter language: it does not permit you to create loops. There's
120
no equivalent of while() or for() command, and recursive functions are not permitted.
121

    
122
<p pgm>You can find sources of filters language in
123
<file>filter/</file> directory. <file>filter/config.Y</file> contains
124
filter gramar, and basically translates source from user into tree of
125
<cf>f_inst</cf> structures. These trees are later interpreted using
126
code in <file>filter/filter.c</file>. Filters internally work with
127
values/variables in <TT c>struct f_val</TT>, which contains type of
128
value and value.
129

    
130
<p>Filter basically looks like this:
131

    
132
<cf><verb>
133
filter not_too_far
134
int var;
135
{
136
	if defined( rip_metric ) then
137
		var = rip_metric;
138
	else {
139
		var = 1;
140
		rip_metric = 1;
141
	}
142
	if rip_metric &gt; 10 then
143
		reject "RIP metric is too big";
144
	else
145
		accept "ok";
146
}
147
</verb></cf>
148

    
149
<p>As you can see, filter has a header, list of local variables, and body. Header consists of <cf/filter/ keyword, followed by (unique) name of filter. List of local variables consists of
150
pairs <cf><I>type name</I>;</cf>, where each pair defines one local variable. Body consists of
151
<cf> { <I>statments</I> }</cf>. Statements are terminated by <cf/;/. You can group
152
several statments into one by <cf>{ <I>statments</I> }</cf> construction, that is usefull if
153
you want to make bigger block of code conditional.
154

    
155
<sect1>Data types
156

    
157
<p>Each variable and each value has certain type. Unlike C, filters distinguish between integers and
158
booleans (that is to prevent you from shooting in the foot).
159

    
160
<descrip>
161
	<tag/bool/ this is boolean type, it can have only two values,
162
	  <cf/TRUE/ and <cf/FALSE/. Boolean is not compatible with
163
	  integer and is the only type you can use in if statments.
164

    
165
	<tag/int/ this is common integer, you can expect it to store
166
	  signed values from -2000000000 to +2000000000.
167

    
168
	<tag/pair/ this is pair of two short integers. Each component
169
	  can have values from 0 to 65535. Constant of this type is
170
	  written as <cf/(1234,5678)/.
171

    
172
	<tag/string/ this is string of characters. There are no ways to modify strings in filters. You can
173
	  pass them between functions, assign to variable of type string, print such variables, but
174
	  you can not concatenate two strings (for example). String constants are written as <cf/
175
	  "This is string constant"/.
176

    
177
	<tag/ip/ this type can hold single ip address. Depending on version of bird you are using, it
178
	  can be ipv4 or ipv6 address. Ipv4 addresses addresses are written (as you would expect) as
179
	  <cf/1.2.3.4/. You can apply special operator <cf>.mask(<I>num</I>)</cf>
180
	  on values of type ip. It masks out all but first <cf><I>num</I></cf> bits from ip
181
	  address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
182

    
183
	<tag/prefix/ this type can hold ip address, prefix len
184
	  pair. Prefixes are written as <cf><I>ip address</I>/<I>px
185
	  len</I></cf>. There are two special operators on prefix:
186
	  <cf/.ip/, which separates ip address from the pair, and
187
	  <cf/.len/, which separates prefix len from the pair.
188

    
189
	<tag/set int|ip|prefix|pair/
190
	  filters know four types of sets. Sets are similar to strings: you can pass them around
191
	  but you can not modify them. Constant of type <cf>set int</cf> looks like <cf>
192
	  [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in
193
	  sets. Sets of prefixes are special: you can specify which prefixes should match them by
194
	  using <cf>[ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]</cf>. 3.0.0.0/8{5,6} matches
195
	  prefixes 3.X.X.X, whose prefixlength is 5 to 6. 3.0.0.0/8+ is shorthand for 3.0.0.0/{0,8},
196
	  3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}.
197

    
198
	<tag/enum/
199
	  enumerational types are halfway-internal in the bird. You can not define your own
200
	  variable of enumerational type, but some pre-defined variables are of enumerational
201
	  type. Enumerational types are incompatible with each other, again, its for your
202
	  protection.
203
</descrip>
204

    
205
<sect1>Operations
206

    
207
<p>Filter language supports common integer operations (+,-,*,/), parenthesis (a*(b+c)), comparation
208
(a=b, a!=b, a&lt;b, a&gt;=b). Special operators include ~ for "in" operation. In operation can be
209
used on element and set of that elements, or on ip and prefix, or on prefix and prefix. Its result
210
is true if element is in given set or if ip adress is inside given prefix.
211

    
212
<sect1>Functions
213

    
214
<p>Bird supports functions, so that you don't have to repeat same blocks of code over and
215
over. Functions can have zero or more parameters, and can have local variables. Function basically
216
looks like this:
217

    
218
<cf><verb>
219
function name ()
220
int local_variable;
221
{
222
	local_variable = 5;
223
}
224

    
225
function with_parameters (int parameter)
226
{
227
	print parameter;
228
}
229
</verb></cf>
230

    
231
<p>Unlike C, variables are declared after function line but before first {. You can not declare
232
variables in nested blocks. Functions are called like in C: <cf>name(); with_parameters(5);</cf>.
233

    
234
<p>Filters are declared in similar way to functions, except they can not have explicit
235
parameters. They get route table entry as implicit parameter.
236

    
237
<sect1>Control structures
238

    
239
<p>Filters support two control structures: if/then/else and
240
case. Syntax of if/then/else is <cf>if <I>expression</I> then
241
<I>command</I>; else <I>command</I>;</cf> and you can use <cf>{
242
<I>command_1</I>; <I>command_2</I>; <I>...</I> }</cf> instead of one
243
or both commands. <cf>else</cf> clause may be ommited. Case is
244
used like this:
245

    
246
<cf><verb>
247
        case <I>argument</I> {
248
        2: print "dva"; print "jeste jednou dva";
249
        3 .. 5: print "tri az pet";
250
        else: print "neco jineho";
251
        }
252
</verb></cf>
253

    
254
where <I>argument</I> is any argument that can be on the left side of ~ operator, and anything that
255
could be member of set is allowed before :. Multiple commands are allowed without {} grouping. If
256
argument matches neither of : clauses, else: clause is used. (Case is actually implemented as set
257
matching, internally.)
258

    
259
<sect>Protocols
260

    
261
<sect1>Rip
262

    
263
<sect2>Introduction
264

    
265
<p>Rip protocol (sometimes called Rest In Pieces) is simple protocol, where each router broadcasts
266
distances to all networks he can reach. When router hears distance to other network, it increments
267
it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes
268
unreachable, routers keep telling each other that distance is old distance plus 1 (actually, plus
269
interface metric, which is usually one). After some time, distance reaches infinity (that's 15 in
270
rip) and all routers know that network is unreachable. Rip tries to minimize situations where
271
counting to infinity is neccessary, because it is slow. Due to infinity being 16, you can not use
272
rip on networks where maximal distance is bigger than 15 hosts. You can read more about rip at <A
273
HREF="fixme">rfc1234</A>.
274

    
275
<sect2>Configuration
276

    
277
<p>In addition to options generic to other protocols, rip supports following options:
278

    
279
<descrip>
280
	<tag/authentication none|password|md5/
281
	  selects authenticaion method to use. None means that packets are not authenticated at
282
	  all, password means that plaintext password is embedded into each packet, and md5 means
283
	  that packets are authenticated using md5 cryptographics hash. See <A
284
	  HREF="fixme">rfc1234</A>. If you set authentication to non-none, it is good idea to add
285
	  <cf>passwords { }</cf> section.
286
</descrip>
287

    
288
<p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with
289
default one.  Second is <cf>mode broadcast|quiet|nolisten|version1</cf>, it selects mode for
290
rip to work in. If nothing is specified, rip runs in multicasts mode. <cf>version1</cf> is
291
currently equivalent to <cf>broadcast</cf>, and it makes rip talk at broadcast address even
292
through multicast mode is possible. <cf>quiet</cf> option means that rip will not transmit
293
periodic messages onto this interface and <cf>nolisten</cf> means that rip will talk to this
294
interface but not listen on it.
295

    
296
<p>Following options generally override specified behaviour from rfc. If you use any of these
297
options, bird will no longer be rfc-compatible, which means it will not be able to talk to anything
298
other than equally (mis-)configured bird. I warned you.
299

    
300
<descrip>
301
	<tag>port <I>number</I></tag>
302
	  selects IP port to operate on, default 520. (This is usefull when testing bird, if you
303
	  set this to address &gt;1024, you will not need to run bird with uid==0).
304

    
305
	<tag>infinity <I>number</I></tag>
306
	  select value of infinity, default 16. Bigger values will make protocol convergence
307
	  even slower.
308

    
309
	<tag>period <I>number</I>
310
	  </tag>specifies number of seconds between periodic updates. Default is 30 seconds. Lower
311
	  number will mean faster convergence but bigger network load.
312

    
313
	<tag>timeouttime <I>number</I>
314
	  </tag>specifies how old route has to be to be considered unreachable. Default is 4*period.
315

    
316
	<tag>garbagetime <I>number</I>
317
	  </tag>specifies how old route has to be to be discarded. Default is 10*period.
318
</descrip>
319

    
320
<p>In addition, rip defines two filter variables, both of type it. <cf>rip_metric</cf> is rip
321
metric of current route, <cf>rip_tag</cf> is tag of current route.
322

    
323
<cf><verb>
324

    
325
protocol rip MyRIP_test {
326
        debug all;
327
        port 1520;
328
        period 7;
329
        garbagetime 60;
330
        interface "*";
331
        honour neighbour;
332
        passwords { password "ahoj" from 0 to 10;
333
                password "nazdar" from 10;
334
        }
335
        authentication none;
336
        import filter { print "importing"; accept; };
337
        export filter { print "exporting"; accept; };
338
}
339
</verb></cf>
340

    
341
</article>