]>
Commit | Line | Data |
---|---|---|
04a22949 | 1 | <!doctype birddoc system> |
d37f899b PM |
2 | |
3 | <!-- | |
d150c637 | 4 | BIRD documentation |
d37f899b | 5 | |
326e33f5 PM |
6 | This is slightly modified linuxdoc dtd. Anything in <descrip> tags is considered definition of |
7 | configuration primitives, <cf> is fragment of configuration within normal text, <m> is | |
cd4fecb6 | 8 | "meta" information within fragment of configuration - something in config which is not keyword. |
d37f899b PM |
9 | |
10 | (set-fill-column 100) | |
11 | ||
12 | Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later. | |
13 | ||
14 | --> | |
15 | ||
371adba6 | 16 | <book> |
d37f899b | 17 | |
aa185265 | 18 | <title>BIRD User's Guide |
d37f899b | 19 | <author> |
aa185265 MM |
20 | Ondrej Filip <it/<feela@network.cz>/, |
21 | Pavel Machek <it/<pavel@ucw.cz>/, | |
22 | Martin Mares <it/<mj@ucw.cz>/ | |
23 | </author> | |
d37f899b | 24 | |
d37f899b | 25 | <abstract> |
aa185265 | 26 | This document contains user documentation for the BIRD Internet Routing Daemon project. |
d37f899b PM |
27 | </abstract> |
28 | ||
29 | <!-- Table of contents --> | |
30 | <toc> | |
31 | ||
32 | <!-- Begin the document --> | |
33 | ||
371adba6 | 34 | <chapt>Introduction |
d37f899b | 35 | |
371adba6 | 36 | <sect>What is BIRD |
d37f899b | 37 | |
897cd7aa MM |
38 | <p><label id="intro"> |
39 | The name `BIRD' is actually an acronym standing for `BIRD Internet Routing Daemon'. | |
40 | Let's take a closer look at the meaning of the name: | |
41 | ||
42 | <p><em/BIRD/: Well, we think we have already explained that. It's an acronym standing | |
43 | for `BIRD Internet Routing Daemon', you remember, don't you? :-) | |
44 | ||
45 | <p><em/Internet Routing/: It's a program (well, a daemon, as you are going to discover in a moment) | |
46 | which works as a dynamic router in an Internet type network (that is, in a network running either | |
47 | the IPv4 or the IPv6 protocol). Routers are devices which forward packets between interconnected | |
48 | networks in order to allow hosts not connected directly to the same local area network to | |
49 | communicate with each other. They also communicate with other routers in the Internet to discover | |
50 | the topology of the network which allows them to find optimal (in terms of some metric) rules for | |
51 | forwarding of packets (which will be called routes in the rest of this document) and to adapt to the | |
52 | changing conditions such as outages of network links, building of new connections and so on. Most of | |
53 | these routers are costly dedicated devices running obscure firmware which is hard to configure and | |
75317ab8 MM |
54 | not open to any changes (but these costly dedicated beasts are needed |
55 | for routing on many fast interfaces -- a PC class machine can not keep up with more than 4 | |
56 | 100Mbps cards). Fortunately, most operating systems of the UNIX family allow an ordinary | |
897cd7aa MM |
57 | computer to act as a router and forward packets belonging to the other hosts, but only according to |
58 | a statically configured table. | |
59 | ||
60 | <p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on | |
61 | background which does the dynamic part of Internet routing, that is it communicates | |
62 | with the other routers, calculates routing tables and sends them to the OS kernel | |
068b4127 PM |
63 | which does the actual packet forwarding. There are other such routing daemons: routed (rip only), GateD <HTMLURL URL="http://www.gated.org/"> |
64 | (non free) and Zebra <HTMLURL URL="http://www.zebra.org">, but their capabilities are limited and | |
65 | they are relatively hard to configure and maintain. | |
897cd7aa MM |
66 | |
67 | <p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings, | |
5459fac6 | 68 | to support all the routing technology used in the today's Internet or planned to be |
897cd7aa MM |
69 | used in near future and to have a clean extensible architecture allowing new routing |
70 | protocols to be incorporated easily. Among other features, BIRD supports: | |
71 | ||
72 | <itemize> | |
73 | <item>both IPv4 and IPv6 protocols | |
74 | <item>multiple routing tables | |
75 | <item>the Border Gateway Protocol (BGPv4) | |
76 | <item>the Routing Interchange Protocol (RIPv2) | |
77 | <item>the Open Shortest Path First protocol (OSPFv2) | |
78 | <item>a virtual protocol for exchange of routes between internal routing tables | |
79 | <item>a command-line interface allowing on-line control and inspection | |
80 | of status of the daemon | |
81 | <item>soft reconfiguration (no need to use complex online commands | |
82 | to change the configuration, just edit the configuration file | |
83 | and notify BIRD to re-read it and it will smoothly switch | |
84 | to the new configuration, not disturbing routing protocols | |
85 | unless they are affected by the configuration changes) | |
86 | <item>powerful language for route filtering | |
87 | </itemize> | |
88 | ||
89 | <p>BIRD has been developed at the Faculty of Math and Physics, Charles University, Prague, | |
e9df1bb6 | 90 | Czech Republic as a student project. It can be freely distributed under the terms of the GNU General |
897cd7aa MM |
91 | Public License. |
92 | ||
93 | <p>BIRD has been designed to work on all UNIX-like systems. It has been developed and | |
94 | tested under Linux 2.0 to 2.3, but porting to other systems (even non-UNIX ones) should | |
068b4127 | 95 | be relatively easy due to its highly modular architecture. |
d37f899b | 96 | |
371adba6 | 97 | <sect>About this documentation |
d37f899b | 98 | |
326e33f5 | 99 | <p>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. |
c184d9d0 | 100 | |
371adba6 | 101 | <sect>About routing tables |
c184d9d0 PM |
102 | |
103 | <p>Bird has one or more routing tables, which may or may not be | |
104 | synchronized with kernel and which may or may not be synchronized with | |
cd4fecb6 | 105 | each other (see the Pipe protocol). Each routing table contains list of |
326e33f5 PM |
106 | known routes. Each route consists of: |
107 | ||
108 | <itemize> | |
109 | <item>network this route is for | |
110 | <item>preference of this route (taken from preference of | |
75317ab8 | 111 | protocol and possibly altered by filters) |
326e33f5 PM |
112 | <item>ip address of router who told us about this route |
113 | <item>ip address of router we should use for packets routing | |
114 | using this route | |
115 | <item>other attributes common to all routes | |
116 | <item>dynamic attributes defined by protocols, which may or | |
117 | may not be present (typically protocol metric) | |
118 | </itemize> | |
119 | ||
120 | Routing table maintains more than | |
c184d9d0 PM |
121 | one entry for network, but at most one entry for one network and one |
122 | protocol. The entry with biggest preference is used for routing. If | |
123 | there are more entries with same preference and they are from same | |
326e33f5 PM |
124 | protocol, protocol decides (typically according to metrics). If not, |
125 | internal ordering is used to decide. You can | |
c184d9d0 PM |
126 | get list of route attributes in "Route attributes" section in |
127 | filters. Filters can alter routes passed between routing tables and | |
128 | protocols. | |
129 | ||
371adba6 | 130 | <sect>Installing BIRD |
440439e3 | 131 | |
75317ab8 | 132 | <p>On recent UNIX (with GNU-compatible tools -- BIRD relies on GCC extensions) |
326e33f5 | 133 | system, installing BIRD should be as easy as: |
440439e3 PM |
134 | |
135 | <code> | |
136 | ./configure | |
137 | make | |
138 | make install | |
139 | vi /usr/local/etc/bird.conf | |
c184d9d0 | 140 | bird |
440439e3 PM |
141 | </code> |
142 | ||
c184d9d0 PM |
143 | <p>You can use <tt>./configure --help</tt> to get list of configure |
144 | options. Most important (and not easily guessed) option is | |
75317ab8 | 145 | <tt/--enable-ipv6/, which enables IPv6 support. |
36032ded | 146 | |
c184d9d0 | 147 | <p>You can pass several command-line options to bird: |
d26524fa | 148 | |
c184d9d0 PM |
149 | <descrip> |
150 | <tag>-c <m/config name/</tag> | |
151 | use given config file instead of <file>bird.conf</file>. | |
152 | ||
153 | <tag>-d</tag> | |
154 | enable debugging. | |
155 | ||
156 | <tag>-D <m/filename for debug log/</tag> | |
326e33f5 | 157 | log debugging information to given file. |
c184d9d0 PM |
158 | |
159 | <tag>-s <m/name of communication socket/</tag> | |
160 | use given filename for socket for communications with bird client, default is <file/bird.ctl/. | |
161 | </descrip> | |
d26524fa | 162 | |
371adba6 | 163 | <chapt>Configuration |
af0b25d2 | 164 | |
371adba6 | 165 | <sect>Introduction |
d37f899b | 166 | |
d150c637 | 167 | <p>BIRD is configured using text configuration file. At startup, BIRD reads <file/bird.conf/ (unless |
cd4fecb6 | 168 | <tt/-c/ command line option is given). Configuration may be changed on user request: if you modify |
326e33f5 PM |
169 | config file and then signal BIRD with SIGHUP, it will adjust to new |
170 | config. Then there's BIRD client, | |
1b55b1a3 | 171 | which allows you to talk with BIRD in more extensive way than just telling it to reconfigure. BIRD |
d150c637 PM |
172 | writes messages about its work to log files or syslog (according to config). |
173 | ||
326e33f5 | 174 | <p>In config, everything on a line after <cf/#/ or inside <cf>/* |
cd4fecb6 | 175 | */</cf> is a comment, whitespace is ignored, C-style comments <cf>/* comment */</cf> are also |
326e33f5 PM |
176 | recognized. If there's variable number of options, they are grouped using |
177 | <cf/{ }/ brackets. Each option is terminated by <cf/;/. Configuration | |
178 | is case sensitive. | |
179 | ||
180 | <p>Really simple configuration file might look like this: It enables | |
181 | synchronization of routing tables with kernel, scans for | |
182 | new network interfaces every 10 seconds and runs RIP on all interfaces found. | |
4a5bb2bf | 183 | |
d37f899b | 184 | |
a0dd1c74 | 185 | <code> |
d37f899b | 186 | protocol kernel { |
d150c637 | 187 | persist; # Don't remove routes on BIRD shutdown |
d37f899b PM |
188 | scan time 20; # Scan kernel routing table every 20 seconds |
189 | export all; # Default is export none | |
190 | } | |
191 | ||
192 | protocol device { | |
193 | scan time 10; # Scan interfaces every 10 seconds | |
194 | } | |
195 | ||
196 | protocol rip { | |
197 | export all; | |
198 | import all; | |
199 | } | |
a0dd1c74 | 200 | </code> |
d37f899b | 201 | |
326e33f5 | 202 | |
371adba6 | 203 | <sect>Global options |
af0b25d2 | 204 | |
a0dd1c74 | 205 | <p><descrip> |
2f647f3f PM |
206 | <tag>log "<m/filename/"|syslog|stderr all|{ <m/list of classes/ }</tag> |
207 | set logging of classes (either all or <cf/{ | |
242352b7 | 208 | error, trace }/ etc.) into selected destination. Classes are: |
98627595 PM |
209 | <cf/info/, <cf/warning/, <cf/error/, <cf/fatal/ for messages about local problems |
210 | <cf/debug/ for debugging messages, | |
211 | <cf/trace/ when you want to know what happens on network, | |
212 | <cf/remote/ for messages about misbehavior of remote side, | |
213 | <cf/auth/ about authentication failures, | |
214 | <cf/bug/ for internal bugs | |
d150c637 | 215 | of BIRD. You may specify more than one <cf/log/ line to log to multiple |
7581b81b | 216 | destinations. |
249d238c | 217 | |
7581b81b | 218 | <tag>debug protocols all|off|{ states, routes, filters, interfaces, events, packets }</tag> |
d150c637 | 219 | sets global default of protocol debugging options. |
249d238c | 220 | |
326e33f5 PM |
221 | <tag>filter <m/name local variables/{ <m/commands/ }</tag> define filter. You can learn more about filters |
222 | in next chapter. | |
223 | ||
224 | <tag>function <m/name (parameters) local variables/ { <m/commands/ }</tag> define function. You can learn more | |
225 | about functions | |
7581b81b | 226 | in next chapter. |
bfd71178 | 227 | |
d150c637 | 228 | <tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> define protocol |
7581b81b | 229 | instance, called name (or called something like rip5 if you omit name). You can learn more |
d150c637 PM |
230 | about configuring protocols in their own chapters. You can run more than one instance of |
231 | most protocols (like rip or bgp). | |
249d238c | 232 | |
326e33f5 | 233 | <tag>define constant = (<m/expression/)|<m/number/</tag> define constant. You can use it later in every place |
7581b81b | 234 | you could use simple integer. |
249d238c | 235 | |
d150c637 PM |
236 | <tag>router id <m/IPv4 address/</tag> set router id. Router id needs to be world-wide |
237 | unique. It is usually one of router's IPv4 addresses. | |
249d238c | 238 | |
326e33f5 PM |
239 | <tag>table <m/name/</tag> create new routing table. Default |
240 | routing table is created implicitly, other routing tables have | |
241 | to be added by this command. | |
af0b25d2 | 242 | |
326e33f5 PM |
243 | <tag>eval <m/expr/</tag> evaluates given filter expression. It |
244 | is used by us for testing. | |
249d238c PM |
245 | </descrip> |
246 | ||
371adba6 | 247 | <sect>Protocol options |
bfd71178 | 248 | |
af0b25d2 PM |
249 | <p>Several options are per-protocol, but all protocols support them. They are described here. |
250 | ||
251 | <descrip> | |
d150c637 | 252 | <tag>preference <m/expr/</tag> sets preference of routes generated by this protocol. |
7581b81b | 253 | |
1b55b1a3 | 254 | <tag>disabled</tag> disables given protocol. You can disable/enable protocol from command |
326e33f5 | 255 | line interface without needing to touch config. Disabled protocol is not activated. |
7581b81b PM |
256 | |
257 | <tag>debug <m/setting/</tag> this is similar to global debug setting, except that it only | |
d150c637 PM |
258 | affects one protocol. Only messages in selected debugging categories will be written to |
259 | logs. | |
7581b81b PM |
260 | |
261 | <tag>import <m/filter/</tag> filter can be either either <cf> { <m>filter commands</m> | |
326e33f5 PM |
262 | }</cf> or <cf>filter <m/name/</cf> or <cf/all/ or <cf/none/. Import filter works in direction from protocol to main |
263 | routing table. All is shorthand for <cf/{ accept; }/ and none is shorthand for <cf/{ reject; }/. | |
bfd71178 | 264 | |
7581b81b PM |
265 | <tag>export <m/filter/</tag> This is similar to <cf>export</cf> keyword, except that it |
266 | works in direction from main routing table to protocol. | |
af0b25d2 PM |
267 | |
268 | <tag>table <m/name/</tag> Connect this protocol to non-default table. | |
7581b81b PM |
269 | </descrip> |
270 | ||
271 | <p>There are per-protocol options that give sense only with certain protocols. | |
272 | ||
273 | <descrip> | |
274 | <tag>passwords { password "<m/password/" from <m/time/ to <m/time/ passive <m/time/ id | |
275 | <m/num/ [...] }</tag> specifies passwords to be used with this protocol. Passive time is | |
326e33f5 | 276 | time from which password is not announced, but is recognized on reception. id is password id, as needed by |
7581b81b PM |
277 | certain protocols. |
278 | ||
d150c637 PM |
279 | <tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [ ... ] } ]</tag> specifies, which |
280 | interfaces this protocol is active at, and allows you to set options on | |
281 | interface-by-interface basis. Mask is specified in shell-like patters, thus <cf>interface | |
282 | "*" { mode broadcast; };</cf> will start given protocol on all interfaces, with <cf>mode | |
326e33f5 PM |
283 | broadcast;</cf> option. If first character of mask is <cf/-/, such interfaces are |
284 | excluded. Masks are parsed left-to-right, thus <cf/interface "-eth0", "*";/ means all but | |
75317ab8 | 285 | the ethernets. |
d150c637 | 286 | |
7581b81b | 287 | </descrip> |
d37f899b | 288 | |
371adba6 | 289 | <sect>Client |
36032ded PM |
290 | |
291 | <p>You can use command-line client <file>birdc</file> to talk with | |
292 | running BIRD. Communications is done using <file/bird.ctl/ unix domain | |
293 | socket (unless changed with <tt/-s/ option given to both server and | |
294 | client). Client can do simple actions such as enabling/disabling | |
295 | protocols, telling BIRD to show various information, telling it to | |
296 | show routing table filtered by any filter, or telling bird to | |
297 | reconfigure. Press <tt/?/ at any time to get online help. Option | |
298 | <tt/-v/ can be passed to client, telling it to dump numeric return | |
75317ab8 | 299 | codes. You do not necessarily need to use BIRDC to talk to BIRD, your |
c184d9d0 | 300 | own application could do that, too -- format of communication between |
75317ab8 | 301 | BIRD and BIRDC is stable (see programmer's documentation). |
c184d9d0 | 302 | |
36032ded | 303 | |
371adba6 | 304 | <chapt>Filters |
d37f899b | 305 | |
371adba6 | 306 | <sect>Introduction |
d37f899b | 307 | |
d150c637 PM |
308 | <p>BIRD contains rather simple programming language. (No, it can not yet read mail :-). There are |
309 | two objects in this language: filters and functions. Filters are called by BIRD core when route is | |
d37f899b | 310 | being passed between protocol and main routing table, and filters may call functions. Functions may |
0e5373fd | 311 | call other functions, but recursion is not allowed. Filter language contains control structures such |
d37f899b | 312 | as if's and switches, but it allows no loops. Filters are |
7581b81b | 313 | interpreted. Filter using many features can be found in <file>filter/test.conf</file>. |
d37f899b | 314 | |
0e5373fd PM |
315 | <p>Filter basically gets the route, looks at its attributes and |
316 | modifies some of them if it wishes. At the end, it decides, whether to | |
326e33f5 | 317 | pass change route through (using <cf/accept/), or whether to <cf/reject/ given route. Simple filter looks |
0e5373fd | 318 | like this: |
d37f899b | 319 | |
a0dd1c74 | 320 | <code> |
d37f899b PM |
321 | filter not_too_far |
322 | int var; | |
323 | { | |
324 | if defined( rip_metric ) then | |
325 | var = rip_metric; | |
326 | else { | |
327 | var = 1; | |
328 | rip_metric = 1; | |
329 | } | |
330 | if rip_metric > 10 then | |
331 | reject "RIP metric is too big"; | |
332 | else | |
333 | accept "ok"; | |
334 | } | |
a0dd1c74 | 335 | </code> |
d37f899b | 336 | |
0e5373fd PM |
337 | <p>As you can see, filter has a header, list of local variables, and body. Header consists of |
338 | <cf/filter/ keyword, followed by (unique) name of filter. List of local variables consists of | |
0e7a720a | 339 | pairs <cf><M>type name</M>;</cf>, where each pair defines one local variable. Body consists of |
326e33f5 | 340 | <cf> { <M>statements</M> }</cf>. Each Statement is terminated by <cf/;/. You can group |
7581b81b | 341 | several statements into one by <cf>{ <M>statements</M> }</cf> construction, that is useful if |
d37f899b PM |
342 | you want to make bigger block of code conditional. |
343 | ||
0e5373fd | 344 | <p>Bird supports functions, so that you don't have to repeat same blocks of code over and |
326e33f5 PM |
345 | over. Functions can have zero or more parameters, and can have local variables. They |
346 | look like this: | |
0e5373fd PM |
347 | |
348 | <code> | |
349 | function name () | |
350 | int local_variable; | |
351 | { | |
352 | local_variable = 5; | |
353 | } | |
354 | ||
355 | function with_parameters (int parameter) | |
356 | { | |
357 | print parameter; | |
358 | } | |
359 | </code> | |
360 | ||
361 | <p>Unlike C, variables are declared after function line but before first {. You can not declare | |
362 | variables in nested blocks. Functions are called like in C: <cf>name(); | |
363 | with_parameters(5);</cf>. Function may return value using <cf>return <m/[expr]/</cf> | |
364 | syntax. Returning value exits from current function (this is similar to C). | |
365 | ||
366 | <p>Filters are declared in similar way to functions, except they can not have explicit | |
367 | parameters. They get route table entry as implicit parameter. Route table entry is passed implicitly | |
2f647f3f | 368 | to any functions being called. Filter must terminate with either |
326e33f5 | 369 | <cf/accept/ or <cf/reject/ statement. If there's runtime error in filter, route |
2f647f3f | 370 | is rejected. |
0e5373fd | 371 | |
c184d9d0 PM |
372 | <p>Nice trick to debug filters is using <cf>show route filter |
373 | <m/name/</cf> from command line client. Example session might look | |
374 | like: | |
375 | ||
376 | <code> | |
377 | pavel@bug:~/bird$ ./birdc -s bird.ctl | |
378 | BIRD 0.0.0 ready. | |
379 | bird> help | |
380 | No such command. | |
381 | bird> | |
382 | bird> show route | |
383 | 10.0.0.0/8 dev eth0 [direct1 23:21] (240) | |
384 | 195.113.30.2/32 dev tunl1 [direct1 23:21] (240) | |
385 | 127.0.0.0/8 dev lo [direct1 23:21] (240) | |
386 | bird> show route ? | |
387 | show route [<prefix>] [table <t>] [filter <f>] [all] [primary] [(import|protocol) <p>] [stats] Show routing table | |
388 | bird> show route filter { if 127.0.0.5 ~ net then accept; } | |
389 | 127.0.0.0/8 dev lo [direct1 23:21] (240) | |
390 | bird> | |
391 | </code> | |
392 | ||
371adba6 | 393 | <sect>Data types |
d37f899b | 394 | |
326e33f5 PM |
395 | <p>Each variable and each value has certain type. Unlike C, booleans, integers and enums are |
396 | incompatible with each other (that is to prevent you from shooting in the foot). | |
d37f899b PM |
397 | |
398 | <descrip> | |
326e33f5 PM |
399 | <tag/bool/ this is boolean type, it can have only two values, <cf/true/ and |
400 | <cf/false/. Boolean is not compatible with integer and is the only type you can use in if | |
7581b81b | 401 | statements. |
d37f899b | 402 | |
7581b81b | 403 | <tag/int/ this is common integer, you can expect it to store signed values from -2000000000 |
36032ded | 404 | to +2000000000. Overflows are not checked. |
d37f899b | 405 | |
7581b81b PM |
406 | <tag/pair/ this is pair of two short integers. Each component can have values from 0 to |
407 | 65535. Constant of this type is written as <cf/(1234,5678)/. | |
d37f899b | 408 | |
7581b81b PM |
409 | <tag/string/ this is string of characters. There are no ways to modify strings in |
410 | filters. You can pass them between functions, assign to variable of type string, print | |
411 | such variables, but you can not concatenate two strings (for example). String constants | |
0e5373fd | 412 | are written as <cf/"This is a string constant"/. |
d37f899b | 413 | |
326e33f5 | 414 | <tag/ip/ this type can hold single ip address. Depending on compile-time configuration of BIRD you are using, it |
7581b81b | 415 | can be IPv4 or IPv6 address. IPv4 addresses are written (as you would expect) as |
0e7a720a PM |
416 | <cf/1.2.3.4/. You can apply special operator <cf>.mask(<M>num</M>)</cf> |
417 | on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from ip | |
d37f899b PM |
418 | address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. |
419 | ||
326e33f5 | 420 | <tag/prefix/ this type can hold ip address and prefix length. Prefixes are written as |
0e5373fd PM |
421 | <cf><M>ipaddress</M>/<M>pxlen</M></cf>, or |
422 | <cf><m>ipaddress</m>/<m>netmask</m></cf> There are two special | |
423 | operators on prefix: | |
7581b81b | 424 | <cf/.ip/, which separates ip address from the pair, and <cf/.len/, which separates prefix |
326e33f5 | 425 | len from the pair. So <cf>1.2.0.0/16.pxlen = 16</cf> is true. |
d37f899b | 426 | |
326e33f5 | 427 | <tag/int|ip|prefix|pair|enum set/ |
d37f899b | 428 | filters know four types of sets. Sets are similar to strings: you can pass them around |
52276996 | 429 | but you can not modify them. Constant of type <cf>set int</cf> looks like <cf> |
d37f899b | 430 | [ 1, 2, 5..7 ]</cf>. As you can see, both simple values and ranges are permitted in |
c184d9d0 | 431 | sets. Sets of prefixes are special: you can specify which prefix lengths should match them by |
52276996 | 432 | 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 |
7581b81b | 433 | prefixes 3.X.X.X, whose prefix length is 5 to 6. 3.0.0.0/8+ is shorthand for 3.0.0.0/{0,8}, |
c184d9d0 PM |
434 | 3.0.0.0/8- is shorthand for 3.0.0.0/{0,7}. For example, |
435 | <tt>1.2.0.0/16 ~ [ 1.0.0.0/8{ 15 , 17 } ]</tt> is true, but | |
436 | <tt>1.0.0.0/8 ~ [ 1.0.0.0/8- ]</tt> is false. | |
d37f899b PM |
437 | |
438 | <tag/enum/ | |
326e33f5 PM |
439 | enumeration types are halfway-internal in the BIRD. You can't define your own |
440 | variable of enumeration type, but some route attributes are of enumeration | |
216fd83c | 441 | type. Enumeration types are incompatible with each other, again, for your |
d37f899b | 442 | protection. |
0e5373fd PM |
443 | |
444 | <tag/bgppath/ | |
326e33f5 | 445 | bgp path is list of autonomous systems. You can't write constant of this type. |
4a5bb2bf PM |
446 | |
447 | <tag/bgpmask/ | |
448 | bgp mask is mask used for matching bgp paths | |
c184d9d0 PM |
449 | (using <cf>path ~ / 2 3 5 ? / syntax </cf>). Matching is |
450 | done using shell-like pattern: <cf/?/ means | |
451 | "any number of any autonomous systems". Pattern for single | |
452 | unknown autonomous system is not supported. (We | |
4a5bb2bf | 453 | did not want to use * because then it becomes too easy to |
c184d9d0 | 454 | write <cf>/*</cf> which is start of comment.) For example, |
326e33f5 | 455 | <tt>/ 4 3 2 1 / ~ / ? 4 3 ? /</tt> is true, but |
c184d9d0 | 456 | <tt>/ 4 3 2 1 / ~ / ? 4 5 ? /</tt> is false. |
0e5373fd | 457 | |
4a5bb2bf PM |
458 | <tag/clist/ |
459 | community list. This is similar to set of pairs, | |
460 | except that unlike other sets, it can be modified. | |
326e33f5 | 461 | You can't write constant of this type. |
0e5373fd | 462 | |
d37f899b PM |
463 | </descrip> |
464 | ||
371adba6 | 465 | <sect>Operations |
d37f899b | 466 | |
1b55b1a3 | 467 | <p>Filter language supports common integer operations <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison |
af0b25d2 | 468 | <cf/(a=b, a!=b, a<b, a>=b)/. Special operators include <cf/˜/ for "in" operation. In operation can be |
2f647f3f PM |
469 | used on element and set of that elements, or on ip and prefix, or on |
470 | prefix and prefix or on bgppath and bgpmask or on pair and clist. Its result | |
0e5373fd | 471 | is true if element is in given set or if ip address is inside given prefix. Operator <cf/=/ is used to assign value |
326e33f5 | 472 | to variable. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/>). |
d37f899b | 473 | |
371adba6 | 474 | <sect>Control structures |
d37f899b | 475 | |
7581b81b PM |
476 | <p>Filters support two control structures: if/then/else and case. Syntax of if/then/else is <cf>if |
477 | <M>expression</M> then <M>command</M>; else <M>command</M>;</cf> and you can use <cf>{ | |
478 | <M>command_1</M>; <M>command_2</M>; <M>...</M> }</cf> instead of one or both commands. <cf>else</cf> | |
479 | clause may be omitted. | |
d37f899b | 480 | |
7581b81b PM |
481 | <p><cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else | |
482 | <m/num_or_prefix [ .. num_or_prefix]/ : <m/statement/ ; [ ... ] }</cf>. Expression after | |
af0b25d2 | 483 | <cf>case</cf> can be of any type that can be on the left side of ˜ operator, and anything that could |
326e33f5 PM |
484 | be member of set is allowed before <cf/:/. Multiple commands are allowed without <cf/{}/ grouping |
485 | and break is implicit before each case. If argument | |
486 | matches neither of <cf/:/ clauses, <cf/else:/ clause is used. (Case is actually implemented as set matching, | |
7581b81b | 487 | internally.) |
d37f899b | 488 | |
af0b25d2 PM |
489 | <p>Here is example that uses if and case structures: |
490 | ||
491 | <code> | |
492 | case arg1 { | |
493 | 2: print "two"; print "I can do more commands without {}"; | |
494 | 3 .. 5: print "three to five"; | |
495 | else: print "something else"; | |
496 | } | |
497 | ||
326e33f5 | 498 | if 1234 = i then printn "."; else { print "not 1234"; print "You need {} around multiple commands"; } |
af0b25d2 PM |
499 | </code> |
500 | ||
371adba6 | 501 | <sect>Route attributes |
0e5373fd | 502 | |
36032ded PM |
503 | <p>Filter is implicitly passed route, and it can access its |
504 | attributes, just like it accesses variables. Access to undefined | |
505 | attribute results in runtime error; you can check if attribute is | |
506 | defined using <cf>defined( <m>attribute</m> )</cf> syntax. | |
0e5373fd | 507 | |
36032ded | 508 | <descrip> |
cd4fecb6 | 509 | <tag><m/prefix/ net</tag> |
326e33f5 | 510 | network this route is talking about. (See section about routing tables) |
0e5373fd | 511 | |
cd4fecb6 | 512 | <tag><m/int/ preference</tag> |
326e33f5 | 513 | preference of this route. (See section about routing tables) |
c184d9d0 | 514 | |
cd4fecb6 | 515 | <tag><m/ip/ from</tag> |
0e5373fd PM |
516 | who told me about this route. |
517 | ||
cd4fecb6 | 518 | <tag><m/ip/ gw</tag> |
216fd83c | 519 | what is next hop packets routed using this route should be forwarded to. |
0e5373fd | 520 | |
cd4fecb6 | 521 | <tag><m/enum/ source</tag> |
0e5373fd | 522 | what protocol told me about this route. This can have values such as <cf/RTS_RIP/ or <cf/RTS_OSPF_EXT/. |
c184d9d0 | 523 | |
cd4fecb6 MM |
524 | <tag><m/enum/ scope</tag> |
525 | FIXME! | |
c184d9d0 | 526 | |
cd4fecb6 MM |
527 | <tag><m/enum/ cast</tag> |
528 | FIXME! | |
c184d9d0 | 529 | |
cd4fecb6 MM |
530 | <tag><m/enum/ dest</tag> |
531 | FIXME! | |
ba1dda49 | 532 | </descrip> |
0e5373fd PM |
533 | |
534 | <p>Plus, there are protocol-specific attributes, which are described in protocol sections. | |
535 | ||
371adba6 | 536 | <sect>Utility functions |
69477cad | 537 | |
1b55b1a3 | 538 | <p>There are few functions you might find convenient to use: |
69477cad PM |
539 | |
540 | <descrip> | |
326e33f5 PM |
541 | <tag>accept</tag> accept this route |
542 | ||
543 | <tag>reject</tag> reject this route | |
544 | ||
545 | <tag>return <m/expr/</tag> return given value from function, function ends at this point. | |
546 | ||
440439e3 PM |
547 | <tag>print|printn <m/expr/ [ <m/, expr .../ ]</tag> |
548 | prints given expressions, useful mainly while debugging | |
549 | filters. Printn variant does not go to new line. | |
69477cad PM |
550 | |
551 | <tag>quitbird</tag> | |
216fd83c | 552 | terminates bird. Useful while debugging filter interpreter. |
69477cad PM |
553 | </descrip> |
554 | ||
371adba6 | 555 | <chapt>Protocols |
d37f899b | 556 | |
371adba6 | 557 | <sect>BGP |
1b55b1a3 | 558 | |
56ab03c7 | 559 | <p>The Border Gateway Protocol is the routing protocol used for backbone |
5459fac6 | 560 | level routing in the today's Internet. Contrary to other protocols, its convergence |
56ab03c7 MM |
561 | doesn't rely on all routers following the same rules for route selection, |
562 | making it possible to implement any routing policy at any router in the | |
563 | network, the only restriction being that if a router advertises a route, | |
564 | it must accept and forward packets according to it. | |
565 | ||
566 | <p>BGP works in terms of autonomous systems (often abbreviated as AS). Each | |
567 | AS is a part of the network with common management and common routing policy. | |
568 | Routers within each AS usually communicate using either a interior routing | |
569 | protocol (such as OSPF or RIP) or an interior variant of BGP (called iBGP). | |
570 | Boundary routers at the border of the AS communicate with their peers | |
571 | in the neighboring AS'es via exterior BGP (eBGP). | |
572 | ||
573 | <p>Each BGP router sends to its neighbors updates of the parts of its | |
326e33f5 | 574 | routing table it wishes to export, along with complete path information |
56ab03c7 MM |
575 | (a list of AS'es the packet will travel through if it uses that particular |
576 | route) in order to avoid routing loops. | |
577 | ||
5459fac6 MM |
578 | <p>BIRD supports all requirements of the BGP4 standard as defined in |
579 | RFC 1771<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1771.txt"> | |
580 | including several enhancements from the | |
581 | latest draft<htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-09.txt">. | |
582 | It also supports the community attributes as per | |
583 | RFC 1997<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc1997.txt">, | |
56ca7acd MM |
584 | capability negotiation defined in |
585 | RFC 2842<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2842.txt">, | |
5459fac6 MM |
586 | For IPv6, it uses the standard multiprotocol extensions defined in |
587 | RFC 2283<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2283.txt"> | |
588 | including changes described in the | |
589 | latest draft <htmlurl url="ftp://ftp.rfc-editor.org/internet-drafts/draft-ietf-idr-bgp4-multiprotocol-v2-05.txt"> | |
590 | and applied to IPv6 according to | |
591 | RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">. | |
592 | ||
371adba6 | 593 | <sect1>Route selection rules |
5459fac6 MM |
594 | |
595 | <p>BGP doesn't have any simple metric, so the rules for selection of an optimal | |
596 | route among multiple BGP routes with the same preference are a bit more complex | |
597 | and are implemented according to the following algorithm. First it uses the first | |
598 | rule, if there are more "best" routes, then it uses the second rule to choose | |
599 | among them and so on. | |
600 | ||
601 | <itemize> | |
602 | <item>Prefer route with the highest local preference attribute. | |
603 | <item>Prefer route with the shortest AS path. | |
604 | <item>Prefer IGP origin over EGP and EGP over incomplete. | |
605 | <item>Prefer the lowest value of the Multiple Exit Discriminator. | |
606 | <item>Prefer internal routes over external routes. | |
607 | <item>Prefer route with the lowest value of router ID of the | |
608 | advertising router. | |
609 | </itemize> | |
56ab03c7 | 610 | |
371adba6 | 611 | <sect1>Configuration |
56ab03c7 | 612 | |
5459fac6 MM |
613 | <p>Each instance of the BGP corresponds to one neighboring router. |
614 | This allows to set routing policy and all other parameters differently | |
615 | for each neighbor using the following protocol parameters: | |
616 | ||
617 | <descrip> | |
618 | <tag>local as <m/number/</tag> Define which AS we are part of. (Note that | |
619 | contrary to other IP routers, BIRD is able to act as a router located | |
620 | in multiple AS'es simultaneously, but in such cases you need to tweak | |
621 | the BGP paths manually in the filters to get consistent behavior.) | |
622 | This parameter is mandatory. | |
623 | <tag>neighbor <m/ip/ as <m/number/</tag> Define neighboring router | |
624 | this instance will be talking to and what AS it's located in. Unless | |
625 | you use the <cf/multihop/ clause, it must be directly connected to one | |
f8e2d916 MM |
626 | of your router's interfaces. In case the neighbor is in the same AS |
627 | as we are, we automatically switch to iBGP. This parameter is mandatory. | |
5459fac6 MM |
628 | <tag>multihop <m/number/ via <m/ip/</tag> Configure multihop BGP to a |
629 | neighbor which is connected at most <m/number/ hops far and to which | |
630 | we should route via our direct neighbor with address <m/ip/. | |
631 | Default: switched off. | |
632 | <tag>next hop self</tag> Avoid calculation of the Next Hop attribute | |
633 | and always advertise our own source address (see below) as a next hop. | |
634 | This needs to be used only | |
635 | occasionally to circumvent misconfigurations of other routers. | |
636 | Default: disabled. | |
637 | <tag>source address <m/ip/</tag> Define local address we should use | |
638 | for next hop calculation. Default: the address of the local end | |
639 | of the interface our neighbor is connected to. | |
640 | <tag>disable after error <m/switch/</tag> When an error is encountered (either | |
641 | locally or by the other side), disable the instance automatically | |
642 | and wait for an administrator to solve the problem manually. Default: off. | |
643 | <tag>hold time <m/number/</tag> Time in seconds to wait for a keepalive | |
644 | message from the other side before considering the connection stale. | |
645 | Default: depends on agreement with the neighboring router, we prefer | |
646 | 240 seconds if the other side is willing to accept it. | |
647 | <tag>startup hold time <m/number/</tag> Value of the hold timer used | |
648 | before the routers have a chance to exchange OPEN messages and agree | |
649 | on the real value. Default: 240 seconds. | |
650 | <tag>keepalive time <m/number/</tag> Delay in seconds between sending | |
651 | of two consecutive keepalive messages. Default: One third of the hold time. | |
652 | <tag>connect retry time <m/number/</tag> Time in seconds to wait before | |
653 | retrying a failed connect attempt. Default: 120 seconds. | |
654 | <tag>start delay time <m/number/</tag> Delay in seconds between protocol | |
655 | startup and first attempt to connect. Default: 5 seconds. | |
656 | <tag>error wait time <m/number/, <m/number/</tag> Minimum and maximum delay in seconds between protocol | |
657 | failure (either local or reported by the peer) and automatic startup. | |
658 | Doesn't apply when <cf/disable after error/ is configured. If consecutive | |
659 | errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300. | |
660 | <tag>error forget time <m/number/</tag> Maximum time in seconds between two protocol | |
661 | failures to treat them as a error sequence which makes the <cf/error wait time/ | |
662 | increase exponentially. Default: 300 seconds. | |
663 | <tag>path metric <m/switch/</tag> Enable comparison of path lengths | |
664 | when deciding which BGP route is the best one. Default: on. | |
665 | <tag>default bgp_med <m/number/</tag> Value of the Multiple Exit | |
666 | Discriminator to be used during route selection when the MED attribute | |
667 | is missing. Default: infinite. | |
668 | <tag>default bgp_local_pref <m/number/</tag> Value of the Local Preference | |
669 | to be used during route selection when the Local Preference attribute | |
670 | is missing. Default: 0. | |
671 | </descrip> | |
672 | ||
371adba6 | 673 | <sect1>Attributes |
56ab03c7 | 674 | |
5459fac6 MM |
675 | <p>BGP defines several route attributes. Some of them (those marked with `I' in the |
676 | table below) are available on internal BGP connections only, some of them (marked | |
677 | with `O') are optional. | |
678 | ||
679 | <descrip> | |
326e33f5 | 680 | <tag>bgppath <cf/bgp_path/</tag> Sequence of AS numbers describing the AS path |
5459fac6 MM |
681 | the packet will travel through when forwarded according to this route. On |
682 | internal BGP connections it doesn't contain the number of the local AS. | |
683 | <tag>int <cf/bgp_local_pref/ [I]</tag> Local preference value used for | |
684 | selection among multiple BGP routes (see the selection rules above). It's | |
685 | used as an additional metric which is propagated through the whole local AS. | |
686 | <tag>int <cf/bgp_med/ [IO]</tag> The Multiple Exit Discriminator of the route | |
f8e2d916 | 687 | is an optional attribute which is often used within the local AS to |
5459fac6 MM |
688 | reflect interior distances to various boundary routers. See the route selection |
689 | rules above for exact semantics. | |
326e33f5 | 690 | <tag>enum <cf/bgp_origin/</tag> Origin of the route: either <cf/ORIGIN_IGP/, |
5459fac6 | 691 | if the route has originated in interior routing protocol of an AS or |
326e33f5 PM |
692 | <cf/ORIGIN_EGP/, if it's been imported from the <tt>EGP</tt> protocol |
693 | (nowadays it seems to be obsolete) or <cf/ORIGIN_INCOMPLETE/, if the origin | |
5459fac6 MM |
694 | is unknown. |
695 | <tag>ip <cf/bgp_next_hop/</tag> Next hop to be used for forwarding of packets | |
696 | to this destination. On internal BGP connections, it's an address of the | |
697 | originating router if it's inside the local AS or a boundary router the | |
698 | packet will leave the AS through if it's an exterior route, so each BGP | |
699 | speaker within the AS has a chance to use the shortest interior path | |
700 | possible to this point. | |
701 | <tag>void <cf/bgp_atomic_aggr/ [O]</tag> This is an optional attribute | |
702 | which carries no value, but which sole presence indicates that the route | |
703 | has been aggregated from multiple routes by some AS on the path from | |
704 | the originator. | |
705 | <!-- we don't handle aggregators right since they are of a very obscure type | |
706 | <tag>bgp_aggregator</tag> | |
707 | --> | |
708 | <tag>clist <cf/bgp_community/ [O]</tag> List of community values associated | |
709 | with the route. Each such value is a pair (represented as a <cf/pair/ data | |
710 | type inside the filters) of 16-bit integers, the first of them containing a number of the AS which defines | |
711 | the community and the second one is a per-AS identifier. There are lots | |
712 | of uses of the community mechanism, but generally they are used to carry | |
713 | policy information like "don't export to USA peers". As each AS can define | |
326e33f5 | 714 | its own routing policy, it also has a complete freedom about which community |
5459fac6 MM |
715 | attributes it defines and what their semantics will be. |
716 | </descrip> | |
717 | ||
371adba6 | 718 | <sect1>Example |
56ab03c7 | 719 | |
5459fac6 MM |
720 | <p><code> |
721 | protocol bgp { | |
722 | local as 65000; # Use a private AS number | |
723 | neighbor 62.168.0.130 as 5588; # Our neighbor | |
724 | multihop 20 via 62.168.0.13; # Which is connected indirectly | |
725 | export filter { # We use non-trivial export rules | |
726 | if source = RTS_STATIC then { # Export only static routes | |
727 | bgp_community.add((65000,5678)); # Assign our community | |
728 | if bgp_path ~ / 65000 / then # Artificially increase path length | |
729 | bgp_path.prepend(65000); # by prepending local AS number twice | |
730 | accept; | |
731 | } | |
732 | reject; | |
733 | }; | |
734 | import all; | |
735 | source address 62.168.0.1; # Use non-standard source address | |
736 | } | |
737 | </code> | |
738 | ||
371adba6 | 739 | <sect>Device |
1b55b1a3 | 740 | |
79a2b697 MM |
741 | <p>The Device protocol is not a real routing protocol as it doesn't generate |
742 | any routes and only serves as a module for getting information about network | |
743 | interfaces from the kernel. | |
744 | ||
0e694e04 MM |
745 | <p>Except for very unusual circumstances, you probably should include |
746 | this protocol in the configuration since almost all other protocol | |
747 | require network interfaces to be defined in order to work. | |
79a2b697 | 748 | |
5459fac6 | 749 | <p>The only configurable thing is interface scan time: |
79a2b697 MM |
750 | |
751 | <p><descrip> | |
752 | <tag>scan time <m/number/</tag> Time in seconds between two scans | |
753 | of the network interface list. On systems where we are notified about | |
754 | interface status changes asynchronously (such as newer versions of | |
755 | Linux), we need to scan the list only to avoid confusion by lost | |
756 | notifications, so the default time is set to a large value. | |
757 | </descrip> | |
758 | ||
79a2b697 | 759 | <p>As the Device protocol doesn't generate any routes, it cannot have |
4f88ac47 | 760 | any attributes. Example configuration looks really simple: |
79a2b697 MM |
761 | |
762 | <p><code> | |
763 | protocol device { | |
764 | scan time 10; # Scan the interfaces often | |
765 | } | |
766 | </code> | |
767 | ||
371adba6 | 768 | <sect>Direct |
1b55b1a3 | 769 | |
79a2b697 MM |
770 | <p>The Direct protocol is a simple generator of device routes for all the |
771 | directly connected networks according to the list of interfaces provided | |
772 | by the kernel via the Device protocol. | |
773 | ||
774 | <p>It's highly recommended to include this protocol in your configuration | |
775 | unless you want to use BIRD as a route server or a route reflector, that is | |
776 | on a machine which doesn't forward packets and only participates in | |
777 | distribution of routing information. | |
778 | ||
4f88ac47 | 779 | <p>Only configurable thing about direct is what interfaces it watches: |
79a2b697 MM |
780 | |
781 | <p><descrip> | |
0e694e04 | 782 | <tag>interface <m/pattern [, ...]/</tag> By default, the Direct |
79a2b697 MM |
783 | protocol will generate device routes for all the interfaces |
784 | available. If you want to restrict it to some subset of interfaces | |
785 | (for example if you're using multiple routing tables for policy | |
786 | routing and some of the policy domains don't contain all interfaces), | |
787 | just use this clause. | |
788 | </descrip> | |
789 | ||
79a2b697 MM |
790 | <p>Direct device routes don't contain any specific attributes. |
791 | ||
4f88ac47 | 792 | <p>Example config might look like this: |
79a2b697 MM |
793 | |
794 | <p><code> | |
795 | protocol direct { | |
796 | interface "-arc*", "*"; # Exclude the ARCnets | |
797 | } | |
798 | </code> | |
799 | ||
371adba6 | 800 | <sect>Kernel |
1b55b1a3 | 801 | |
0e4789c2 MM |
802 | <p>The Kernel protocol is not a real routing protocol. Instead of communicating |
803 | with other routers in the network, it performs synchronization of BIRD's routing | |
804 | tables with OS kernel. Basically, it sends all routing table updates to the kernel | |
805 | and from time to time it scans the kernel tables to see whether some routes have | |
806 | disappeared (for example due to unnoticed up/down transition of an interface) | |
f8e2d916 MM |
807 | or whether an `alien' route has been added by someone else (depending on the |
808 | <cf/learn/ switch, such routes are either deleted or we accept them to our | |
809 | table). | |
0e4789c2 MM |
810 | |
811 | <p>If your OS supports only a single routing table, you can configure only one | |
812 | instance of the Kernel protocol. If it supports multiple tables (in order to | |
813 | allow policy routing), you can run as many instances as you want, but each of | |
814 | them must be connected to a different BIRD routing table and to a different | |
815 | kernel table. | |
816 | ||
371adba6 | 817 | <sect1>Configuration |
0e4789c2 MM |
818 | |
819 | <p><descrip> | |
820 | <tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the | |
326e33f5 | 821 | routing tables when it exits (instead of cleaning them up). |
0e4789c2 MM |
822 | <tag>scan time <m/number/</tag> Time in seconds between two scans of the |
823 | kernel routing table. | |
824 | <tag>learn <m/switch/</tag> Enable learning of routes added to the kernel | |
825 | routing tables by other routing daemons or by the system administrator. | |
826 | This is possible only on systems which support identification of route | |
827 | authorship. | |
828 | <tag>kernel table <m/number/</tag> Select which kernel table should | |
829 | this particular instance of the Kernel protocol work with. Available | |
830 | only on systems supporting multiple routing tables. | |
831 | </descrip> | |
832 | ||
326e33f5 | 833 | <p>A simple configuration can look this way: |
0e4789c2 MM |
834 | |
835 | <p><code> | |
836 | protocol kernel { | |
837 | import all; | |
838 | export all; | |
839 | } | |
840 | </code> | |
841 | ||
842 | <p>Or for a system with two routing tables: | |
843 | ||
844 | <p><code> | |
845 | protocol kernel { # Primary routing table | |
846 | learn; # Learn alien routes from the kernel | |
847 | persist; # Don't remove routes on bird shutdown | |
848 | scan time 10; # Scan kernel routing table every 10 seconds | |
849 | import all; | |
850 | export all; | |
851 | } | |
852 | ||
853 | protocol kernel { # Secondary routing table | |
854 | table auxtable; | |
855 | kernel table 100; | |
856 | export all; | |
a2a3ced8 | 857 | } |
0e4789c2 MM |
858 | </code> |
859 | ||
860 | <p>The Kernel protocol doesn't define any route attributes. | |
861 | ||
371adba6 | 862 | <sect>OSPF |
1b55b1a3 | 863 | |
371adba6 | 864 | <sect>Pipe |
1b55b1a3 | 865 | |
371adba6 | 866 | <sect1>Introduction |
a2a3ced8 MM |
867 | |
868 | <p>The Pipe protocol serves as a link between two routing tables, allowing routes to be | |
869 | passed from a table declared as primary (i.e., the one the pipe is connected using the | |
870 | <cf/table/ configuration keyword) to the secondary one (declared using <cf/peer table/) | |
871 | and vice versa, depending on what's allowed by the filters. Export filters control export | |
872 | of routes from the primary table to the secondary one, import filters control the opposite | |
873 | direction. | |
874 | ||
326e33f5 | 875 | <p>The primary use of multiple routing tables and the pipe protocol is for policy routing, |
a2a3ced8 MM |
876 | where handling of a single packet doesn't depend only on its destination address, but also |
877 | on its source address, source interface, protocol type and other similar parameters. | |
326e33f5 | 878 | In many systems (Linux 2.2 being a good example) the kernel allows to enforce routing policies |
a2a3ced8 MM |
879 | by defining routing rules which choose one of several routing tables to be used for a packet |
880 | according to its parameters. Setting of these rules is outside the scope of BIRD's work | |
881 | (you can use the <tt/ip/ command), but you can create several routing tables in BIRD, | |
882 | connect them to the kernel ones, use filters to control which routes appear in which tables | |
883 | and also you can employ the Pipe protocol to export a selected subset of one table in | |
884 | another one. | |
885 | ||
371adba6 | 886 | <sect1>Configuration |
a2a3ced8 MM |
887 | |
888 | <p><descrip> | |
889 | <tag>peer table <m/table/</tag> Define secondary routing table to connect to. The | |
890 | primary one is selected by the <cf/table/ keyword. | |
891 | </descrip> | |
892 | ||
371adba6 | 893 | <sect1>Attributes |
a2a3ced8 MM |
894 | |
895 | <p>The Pipe protocol doesn't define any route attributes. | |
896 | ||
371adba6 | 897 | <sect1>Example |
a2a3ced8 MM |
898 | |
899 | <p>Let's consider a router which serves as a boundary router of two different autonomous | |
900 | systems, each of them connected to a subset of interfaces of the router, having its own | |
901 | exterior connectivity and wishing to use the other AS as a backup connectivity in case | |
902 | of outage of its own exterior line. | |
903 | ||
904 | <p>Probably the simplest solution to this situation is to use two routing tables (we'll | |
905 | call them <cf/as1/ and <cf/as2/) and set up kernel routing rules, so that packets having | |
906 | arrived from interfaces belonging to the first AS will be routed according to <cf/as1/ | |
907 | and similarly for the second AS. Thus we have split our router to two logical routers, | |
908 | each one acting on its own routing table, having its own routing protocols on its own | |
909 | interfaces. In order to use the other AS's routes for backup purposes, we can pass | |
910 | the routes between the tables through a Pipe protocol while decreasing their preferences | |
911 | and correcting their BGP paths to reflect AS boundary crossing. | |
912 | ||
913 | <code> | |
914 | table as1; # Define the tables | |
915 | table as2; | |
916 | ||
917 | protocol kernel kern1 { # Synchronize them with the kernel | |
918 | table as1; | |
919 | kernel table 1; | |
920 | } | |
921 | ||
922 | protocol kernel kern2 { | |
923 | table as2; | |
924 | kernel table 2; | |
925 | } | |
926 | ||
927 | protocol bgp bgp1 { # The outside connections | |
928 | table as1; | |
929 | local as 1; | |
930 | neighbor 192.168.0.1 as 1001; | |
931 | export all; | |
932 | import all; | |
933 | } | |
934 | ||
935 | protocol bgp bgp2 { | |
936 | table as2; | |
937 | local as 2; | |
938 | neighbor 10.0.0.1 as 1002; | |
939 | export all; | |
940 | import all; | |
941 | } | |
942 | ||
943 | protocol pipe { # The Pipe | |
944 | table as1; | |
945 | peer table as2; | |
946 | export filter { | |
947 | if net ~ [ 1.0.0.0/8+] then { # Only AS1 networks | |
948 | if preference>10 then preference = preference-10; | |
949 | if source=RTS_BGP then bgp_path.prepend(1); | |
950 | accept; | |
951 | } | |
952 | reject; | |
953 | }; | |
954 | import filter { | |
955 | if net ~ [ 2.0.0.0/8+] then { # Only AS2 networks | |
956 | if preference>10 then preference = preference-10; | |
957 | if source=RTS_BGP then bgp_path.prepend(2); | |
958 | accept; | |
959 | } | |
960 | reject; | |
961 | }; | |
962 | } | |
963 | </code> | |
964 | ||
371adba6 | 965 | <sect>Rip |
d37f899b | 966 | |
371adba6 | 967 | <sect1>Introduction |
d37f899b | 968 | |
326e33f5 PM |
969 | <p>Rip protocol (sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts |
970 | distances to all networks it can reach. When router hears distance to other network, it increments | |
d37f899b PM |
971 | it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes |
972 | unreachable, routers keep telling each other that distance is old distance plus 1 (actually, plus | |
973 | interface metric, which is usually one). After some time, distance reaches infinity (that's 15 in | |
974 | rip) and all routers know that network is unreachable. Rip tries to minimize situations where | |
7581b81b | 975 | counting to infinity is necessary, because it is slow. Due to infinity being 16, you can not use |
0e7a720a | 976 | rip on networks where maximal distance is bigger than 15 hosts. You can read more about rip at <HTMLURL |
326e33f5 | 977 | URL="http://www.ietf.org/html.charters/rip-charter.html">. Both IPv4 |
75317ab8 | 978 | and IPv6 versions of rip are supported by BIRD, historical RIPv1 is |
326e33f5 | 979 | currently not fully supported. |
440439e3 PM |
980 | |
981 | <p>Rip is very simple protocol, and it is not too good. Slow | |
982 | convergence, big network load and inability to handle bigger networks | |
983 | makes it pretty much obsolete in IPv4 world. (It is still usable on | |
984 | very small networks, through.) It is widely used in IPv6 world, | |
985 | because they are no good implementations of OSPFv3. | |
d37f899b | 986 | |
371adba6 | 987 | <sect1>Configuration |
d37f899b PM |
988 | |
989 | <p>In addition to options generic to other protocols, rip supports following options: | |
990 | ||
991 | <descrip> | |
7581b81b | 992 | <tag/authentication none|password|md5/ selects authentication method to use. None means that |
0e7a720a | 993 | packets are not authenticated at all, password means that plaintext password is embedded |
7581b81b | 994 | into each packet, and md5 means that packets are authenticated using md5 cryptographic |
0e7a720a PM |
995 | hash. If you set authentication to non-none, it is good idea to add <cf>passwords { }</cf> |
996 | section. | |
7581b81b | 997 | |
2d6627a7 PM |
998 | <tag>honor always|neighbor|never </tag>specifies, when should be requests for dumping routing table |
999 | honored. (Always, when sent from host on directly connected | |
1000 | network, or never.) Routing table updates are honored only from | |
1001 | neighbors, that is not configurable. | |
d37f899b PM |
1002 | </descrip> |
1003 | ||
1004 | <p>There are two options that can be specified per-interface. First is <cf>metric</cf>, with | |
7581b81b | 1005 | default one. Second is <cf>mode multicast|broadcast|quiet|nolisten|version1</cf>, it selects mode for |
1b55b1a3 | 1006 | rip to work in. If nothing is specified, rip runs in multicast mode. <cf>version1</cf> is |
d37f899b PM |
1007 | currently equivalent to <cf>broadcast</cf>, and it makes rip talk at broadcast address even |
1008 | through multicast mode is possible. <cf>quiet</cf> option means that rip will not transmit | |
1009 | periodic messages onto this interface and <cf>nolisten</cf> means that rip will talk to this | |
1010 | interface but not listen on it. | |
1011 | ||
9d893489 PM |
1012 | <p>Following options generally override specified behavior from RFC. If you use any of these |
1013 | options, BIRD will no longer be RFC-compatible, which means it will not be able to talk to anything | |
d150c637 | 1014 | other than equally misconfigured BIRD. I warned you. |
d37f899b PM |
1015 | |
1016 | <descrip> | |
0e7a720a | 1017 | <tag>port <M>number</M></tag> |
d150c637 | 1018 | selects IP port to operate on, default 520. (This is useful when testing BIRD, if you |
216fd83c | 1019 | set this to address >1024, you will not need to run bird with UID==0). |
d37f899b | 1020 | |
0e7a720a | 1021 | <tag>infinity <M>number</M></tag> |
d37f899b PM |
1022 | select value of infinity, default 16. Bigger values will make protocol convergence |
1023 | even slower. | |
1024 | ||
0e7a720a | 1025 | <tag>period <M>number</M> |
d37f899b | 1026 | </tag>specifies number of seconds between periodic updates. Default is 30 seconds. Lower |
326e33f5 PM |
1027 | number will mean faster convergence but bigger network |
1028 | load. Do not use values lower than 10. | |
d37f899b | 1029 | |
f3b33928 | 1030 | <tag>timeout time <M>number</M> |
d37f899b PM |
1031 | </tag>specifies how old route has to be to be considered unreachable. Default is 4*period. |
1032 | ||
f3b33928 | 1033 | <tag>garbage time <M>number</M> |
d37f899b PM |
1034 | </tag>specifies how old route has to be to be discarded. Default is 10*period. |
1035 | </descrip> | |
1036 | ||
371adba6 | 1037 | <sect1>Attributes |
d37f899b | 1038 | |
1b55b1a3 MM |
1039 | <p>RIP defines two route attributes: |
1040 | ||
1041 | <descrip> | |
1042 | <tag>int <cf/rip_metric/</tag> RIP metric of the route (ranging from 0 to <cf/infinity/). | |
1043 | When routes from different RIP instances are available and all of them have the same | |
1044 | preference, BIRD prefers the route with lowest <cf/rip_metric/. | |
1045 | ||
1046 | <tag>int <cf/rip_tag/</tag> RIP route tag: a 16-bit number which can be used | |
1047 | to carry additional information with the route (for example, an originating AS number | |
1048 | in case of external routes). | |
1049 | </descrip> | |
1050 | ||
371adba6 | 1051 | <sect1>Example |
1b55b1a3 MM |
1052 | |
1053 | <p><code> | |
d37f899b PM |
1054 | protocol rip MyRIP_test { |
1055 | debug all; | |
1056 | port 1520; | |
326e33f5 PM |
1057 | period 10; |
1058 | garbage time 60; | |
d150c637 | 1059 | interface "eth0" { metric 3; mode multicast; } "eth1" { metric 2; mode broadcast; }; |
326e33f5 | 1060 | honor neighbor; |
d37f899b PM |
1061 | authentication none; |
1062 | import filter { print "importing"; accept; }; | |
1063 | export filter { print "exporting"; accept; }; | |
1064 | } | |
a0dd1c74 | 1065 | </code> |
d37f899b | 1066 | |
371adba6 | 1067 | <sect>Static |
1b55b1a3 | 1068 | |
0e4789c2 | 1069 | <p>The Static protocol doesn't communicate with other routers in the network, |
f8e2d916 | 1070 | but instead it allows you to define routes manually. This is often used for |
79a2b697 MM |
1071 | specifying how to forward packets to parts of the network which don't use |
1072 | dynamic routing at all and also for defining sink routes (i.e., those | |
1073 | telling to return packets as undeliverable if they are in your IP block, | |
1074 | you don't have any specific destination for them and you don't want to send | |
1075 | them out through the default route to prevent routing loops). | |
1076 | ||
1077 | <p>There are three types of static routes: `classical' routes telling to | |
1078 | forward packets to a neighboring router, device routes specifying forwarding | |
1079 | to hosts on a directly connected network and special routes (sink, blackhole | |
1080 | etc.) which specify a special action to be done instead of forwarding the | |
1081 | packet. | |
1082 | ||
1083 | <p>When the particular destination is not available (the interface is down or | |
1084 | the next hop of the route is not a neighbor at the moment), Static just | |
326e33f5 | 1085 | uninstalls the route from the table it is connected to and adds it again as soon |
79a2b697 MM |
1086 | as the destinations becomes adjacent again. |
1087 | ||
79a2b697 | 1088 | <p>The Static protocol has no configuration options. Instead, the |
326e33f5 | 1089 | definition of the protocol contains a list of static routes: |
79a2b697 MM |
1090 | |
1091 | <descrip> | |
1092 | <tag>route <m/prefix/ via <m/ip/</tag> Static route through | |
1093 | a neighboring router. | |
1094 | <tag>route <m/prefix/ via <m/"interface"/</tag> Static device | |
1095 | route through an interface to hosts on a directly connected network. | |
1096 | <tag>route <m/prefix/ drop|reject|prohibit</tag> Special routes | |
1097 | specifying to drop the packet, return it as unreachable or return | |
1098 | it as administratively prohibited. | |
1099 | </descrip> | |
1100 | ||
79a2b697 MM |
1101 | <p>Static routes have no specific attributes. |
1102 | ||
4f88ac47 | 1103 | <p>Example static config might look like this: |
79a2b697 MM |
1104 | |
1105 | <p><code> | |
1106 | protocol static { | |
1107 | table testable; # Connect to non-default routing table | |
1108 | route 0.0.0.0/0 via 62.168.0.13; # Default route | |
1109 | route 62.168.0.0/25 reject; # Sink route | |
1110 | route 10.2.0.0/24 via "arc0"; # Secondary network | |
1111 | } | |
1112 | </code> | |
1113 | ||
371adba6 | 1114 | <chapt>Problems |
69477cad | 1115 | |
c184d9d0 | 1116 | <p>BIRD is relatively young system, and probably contains some |
cd4fecb6 | 1117 | bugs. You can report bugs at <HTMLURL URL="fixme">, but before you do, |
75317ab8 | 1118 | please make sure you have read available documentation, make sure are running latest version (available at <HTMLURL |
c184d9d0 | 1119 | URL="fixme">), and that bug was not already reported by someone else |
cd4fecb6 | 1120 | (mailing list archives are at <HTMLURL URL="fixme">). (Of course, patch |
326e33f5 PM |
1121 | which fixes the bug along with bug report is always welcome). If you |
1122 | want to join the development, join developer's mailing list by sending | |
cd4fecb6 MM |
1123 | <tt/????/ to <HTMLURL URL="fixme">. You can also get current sources from |
1124 | anoncvs at <HTMLURL URL="fixme">. You can find this documentation online | |
75317ab8 | 1125 | at <HTMLURL URL="fixme">, main home page of bird is <HTMLURL URL="fixme">. When |
c184d9d0 | 1126 | trying to understand, what is going on, Internet standards are |
cd4fecb6 | 1127 | relevant reading; you can get them from <HTMLURL URL="fixme">. |
69477cad | 1128 | |
c184d9d0 | 1129 | <p><it/Good luck!/ |
69477cad | 1130 | |
371adba6 | 1131 | </book> |
7581b81b | 1132 | |
a0dd1c74 | 1133 | <!-- |
75317ab8 MM |
1134 | LocalWords: GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel |
1135 | LocalWords: linuxdoc dtd descrip config conf syslog stderr auth ospf bgp Mbps | |
1136 | LocalWords: router's eval expr num birdc ctl unix if's enums bool int ip GCC | |
1137 | LocalWords: len ipaddress pxlen netmask enum bgppath bgpmask clist gw md eth | |
1138 | LocalWords: RTS printn quitbird iBGP AS'es eBGP RFC multiprotocol IGP Machek | |
3caca73f MM |
1139 | LocalWords: EGP misconfigurations keepalive pref aggr aggregator BIRD's |
1140 | LocalWords: OS'es AS's multicast nolisten misconfigured UID blackhole | |
75317ab8 | 1141 | LocalWords: uninstalls ethernets |
3caca73f | 1142 | --> |