Revision 96264d4d

View differences:

doc/bird.sgml
52 52
networks in order to allow hosts not connected directly to the same local area network to
53 53
communicate with each other. They also communicate with the other routers in the Internet to discover
54 54
the topology of the network which allows them to find optimal (in terms of some metric) rules for
55
forwarding of packets (which will be called routes in the rest of this document) and to adapt themselves to the
55
forwarding of packets (which are called routing tables) and to adapt themselves to the
56 56
changing conditions such as outages of network links, building of new connections and so on. Most of
57 57
these routers are costly dedicated devices running obscure firmware which is hard to configure and
58 58
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 
......
62 62
<p>A <em/Routing Daemon/ is in UNIX terminology a non-interactive program running on
63 63
background which does the dynamic part of Internet routing, that is it communicates
64 64
with the other routers, calculates routing tables and sends them to the OS kernel
65
which does the actual packet forwarding. There already exist other such routing daemons: routed (rip only), GateD<HTMLURL URL="http://www.gated.org/">
66
 (non free), Zebra<HTMLURL URL="http://www.zebra.org"> and MRTD<HTMLURL URL="http://www.zcu.cz/ftp/mirrors/mmrz/mrtd">, but their capabilities are limited and
65
which does the actual packet forwarding. There already exist other such routing daemons: routed (RIP only), GateD<HTMLURL URL="http://www.gated.org/">
66
 (non-free), Zebra<HTMLURL URL="http://www.zebra.org"> and MRTD<HTMLURL URL="http://www.zcu.cz/ftp/mirrors/mmrz/mrtd">, but their capabilities are limited and
67 67
they are relatively hard to configure and maintain.
68 68

  
69 69
<p>BIRD is an Internet Routing Daemon designed to avoid all of these shortcomings,
......
75 75
	<item>both IPv4 and IPv6 protocols
76 76
	<item>multiple routing tables
77 77
	<item>the Border Gateway Protocol (BGPv4)
78
	<item>the Routing Interchange Protocol (RIPv2)
78
	<item>the Routing Information Protocol (RIPv2)
79 79
	<item>the Open Shortest Path First protocol (OSPFv2)
80 80
	<item>a virtual protocol for exchange of routes between different routing tables on a single host
81 81
	<item>a command-line interface allowing on-line control and inspection
......
137 137

  
138 138
<chapt>About routing tables
139 139

  
140
<p>BIRD has one or more routing tables, which may or may not be
141
synchronized with kernel and which may or may not be synchronized with
142
each other (see the Pipe protocol). Each routing table contains list of
140
<p>BIRD has one or more routing tables which may or may not be
141
synchronized with OS kernel and which may or may not be synchronized with
142
each other (see the Pipe protocol). Each routing table contains a list of
143 143
known routes. Each route consists of:
144 144

  
145 145
<itemize>
146
	<item>network prefix this route is for (consists of network address and number of bits forming the network part of the address)
147
	<item>preference of this route (taken from preference of
148
	protocol and possibly altered by filters)
149
	<item>IP address of router who told us about this route
146
	<item>network prefix this route is for (network address and prefix length -- the number of bits forming the network part of the address; also known as a netmask)
147
	<item>preference of this route
148
	<item>IP address of router which told us about this route
150 149
	<item>IP address of router we should forward the packets to
151 150
	using this route
152 151
	<item>other attributes common to all routes
......
154 153
	may not be present (typically protocol metrics)
155 154
</itemize>
156 155

  
157
Routing table maintains more than
158
one entry for a network, but at most one entry for one network and one
159
protocol. The entry with biggest preference is used for routing. If
156
Routing table maintains multiple entries
157
for a network, but at most one entry for one network and one
158
protocol. The entry with the highest preference is used for routing (we
159
will call such an entry the <it/selected route/). If
160 160
there are more entries with the same preference and they are from the same
161
protocol, protocol decides (typically according to metrics). If not,
162
internal ordering is used to decide. You can
163
get list of route attributes in "Route attributes" section in
164
filters. 
165

  
166
<p>Protocols are connected to routing tables through filters. Routes
167
that come from other routers go to the protocol, it then passes them to
168
filters, if import filter accepts route, it gets to main routing
169
table. It is then broadcasted to all other protocols (filtered through
170
their export filters), which typically send it to other routers.
171

  
172
Filters can alter routes passed between routing tables and
173
protocols.
161
protocol, the protocol decides (typically according to metrics). If they aren't,
162
an internal ordering is used to break the tie. You can
163
get the list of route attributes in the Route attributes section.
164

  
165
<p>Each protocol is connected to a routing table through two filters
166
which can accept, reject and modify the routes. An <it/export/
167
filter checks routes passed from the routing table to the protocol,
168
an <it/import/ filter checks routes in the opposite direction.
169
When the routing table gets a route from a protocol, it recalculates
170
the selected route and broadcasts it to all protocols connected to
171
the table. The protocols typically send the update to other routers
172
in the network.
174 173

  
175 174
<chapt>Configuration
176 175

  
......
235 234
	<tag>filter <m/name local variables/{ <m/commands/ }</tag> Define a filter. You can learn more about filters
236 235
	in the following chapter. 
237 236

  
238
	<tag>function <m/name (parameters) local variables/ { <m/commands/ }</tag> Define a function. You can learn more
237
	<tag>function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag> Define a function. You can learn more
239 238
	about functions in the following chapter.
240 239
 
241 240
	<tag>protocol rip|ospf|bgp|... <m/[name]/ { <m>protocol options</m> }</tag> Define a protocol
......
303 302
	time from which the password is not used for sending, but it is recognized on reception. <cf/id/ is password ID as needed by
304 303
	certain protocols. Format of <cf><m/time/</cf> is <tt>dd-mm-yyyy HH:MM:SS</tt>.
305 304

  
306
	<tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [ ... ] } ]</tag> Specifies which
305
	<tag>interface "<m/mask/"|<m/prefix/ [ { <m/option/ ; [...] } ]</tag> Specifies which
307 306
	interfaces is this protocol active on and allows you to set options on a
308 307
	per-interface basis. Mask is specified as in shell-like patterns, thus <cf>interface
309 308
	"*" { mode broadcast; };</cf> will start the protocol on all interfaces with <cf>mode
......
351 350
	<tag>show symbols</tag>
352 351
	Show the list of symbols defined in the configuration (names of protocols, routing tables etc.).
353 352

  
354
	<tag>show route [<m/prefix/|for <m/prefix or IP/] [primary] [table <m/sym/] [all] [stats|count] [filter <m/name/|where <m/condition/] [(import|proto) <m/sym/]</tag>
353
	<tag>show route [[for] <m/prefix/|<m/IP/] [table <m/sym/] [filter <m/f/|where <m/c/] [(import|proto) <m/p/] [<m/options/]</tag>
355 354
	Show contents of a routing table (by default of the main one),
356 355
	that is routes, their metrics and (in case the <cf/all/ switch is given)
357 356
	all their attributes.
......
602 601
	Next hop packets routed using this route should be forwarded to.
603 602

  
604 603
	<tag><m/enum/ source</tag>
605
	what protocol has told me about this route. Possible values: <cf/RTS_DUMMY, RTS_STATIC, RTS_INHERIT, RTS_DEVICE, RTS_STATIC_DEVICE, RTS_REDIRECT, RTS_RIP, RTS_OSPF, RTS_OSPF_EXT, RTS_OSPF_IA, RTS_OSPF_BOUNDARY, RTS_BGP, RTS_PIPE/.
604
	what protocol has told me about this route. Possible values: <cf/RTS_DUMMY/, <cf/RTS_STATIC/, <cf/RTS_INHERIT/, <cf/RTS_DEVICE/, <cf/RTS_STATIC_DEVICE/, <cf/RTS_REDIRECT/, <cf/RTS_RIP/, <cf/RTS_OSPF/, <cf/RTS_OSPF_EXT/, <cf/RTS_OSPF_IA/, <cf/RTS_OSPF_BOUNDARY/, <cf/RTS_BGP/, <cf/RTS_PIPE/.
606 605

  
607 606
	<tag><m/enum/ cast</tag>
608
	Route type (<cf/RTC_UNICAST/ for normal routes, <cf/RTC_BROADCAST, RTC_MULTICAST, RTC_ANYCAST/ for broadcast, multicast and anycast routes). Read-only.
607
	Route type (<cf/RTC_UNICAST/ for normal routes, <cf/RTC_BROADCAST/, <cf/RTC_MULTICAST/, <cf/RTC_ANYCAST/ for broadcast, multicast and anycast routes). Read-only.
609 608

  
610 609
	<tag><m/enum/ dest</tag>
611 610
	Type of destination the packets should be sent to (<cf/RTD_ROUTER/ for forwarding to a neighboring router, <cf/RTD_NETWORK/ for routing to a directly-connected network, <cf/RTD_BLACKHOLE/ for packets to be silently discarded, <cf/RTD_UNREACHABLE/, <cf/RTD_PROHIBIT/ for packets that should be returned with ICMP host unreachable / ICMP administratively prohibited messages). Read-only.
......
820 819

  
821 820
<p><code>
822 821
protocol bgp {
823
	local as 65000;				# Use a private AS number
824
	neighbor 62.168.0.130 as 5588;		# Our neighbor...
825
	multihop 20 via 62.168.0.13;		# ... which is connected indirectly
826
	export filter {				# We use non-trivial export rules
827
		if source = RTS_STATIC then {	# Export only static routes
822
	local as 65000;			     # Use a private AS number
823
	neighbor 62.168.0.130 as 5588;	     # Our neighbor ...
824
	multihop 20 via 62.168.0.13;	     # ... which is connected indirectly
825
	export filter {			     # We use non-trivial export rules
826
		if source = RTS_STATIC then { # Export only static routes
828 827
		        # Assign our community
829 828
			bgp_community.add((65000,5678));
830 829
			# Artificially increase path length
......
836 835
		reject;
837 836
	};
838 837
	import all;
839
	source address 62.168.0.1;		# Use a non-standard source address
838
	source address 62.168.0.1;	# Use a non-standard source address
840 839
}
841 840
</code>
842 841

  
......
1413 1412

  
1414 1413
<p><code>
1415 1414
protocol static {
1416
	table testable;				# Connect to a non-default routing table
1417
	route 0.0.0.0/0 via 62.168.0.13;	# Default route
1418
	route 62.168.0.0/25 reject;		# Sink route
1419
	route 10.2.0.0/24 via "arc0";		# Secondary network
1415
	table testable;			 # Connect to a non-default routing table
1416
	route 0.0.0.0/0 via 62.168.0.13; # Default route
1417
	route 62.168.0.0/25 reject;	 # Sink route
1418
	route 10.2.0.0/24 via "arc0";	 # Secondary network
1420 1419
}
1421 1420
</code>
1422 1421

  
1423
<chapt>Problems
1424

  
1425
<p>BIRD is relatively young system, and probably contains some
1426
bugs. You can report bugs at bird-users mailing list (<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">), but before you do,
1427
please make sure you have read available documentation, make sure are running latest version (available at <HTMLURL
1428
URL="ftp://bird.network.cz/pub/bird" name="bird.network.cz:/pub/bird">). (Of course, patch
1429
which fixes the bug along with bug report is always welcome). If you
1430
want to use BIRD, join mailing list by sending
1431
<tt/subscribe bird-users/ to <HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">. Main home page of bird is <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">. When
1432
trying to understand, what is going on, Internet standards are
1433
relevant reading; you can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
1422
<chapt>Conclusions
1423

  
1424
<sect>Future work
1425

  
1426
<p>Although BIRD supports all the commonly used routing protocols,
1427
there are still some features which would surely deserve to be
1428
implemented in future versions of BIRD:
1429

  
1430
<itemize>
1431
<item>OSPF for IPv6 networks
1432
<item>OSPF NSSA areas and opaque LSA's
1433
<item>Route aggregation and flap dampening
1434
<item>Generation of IPv6 router advertisements
1435
<item>Multipath routes
1436
<item>Multicast routing protocols
1437
<item>Ports to other systems
1438
</itemize>
1439

  
1440
<sect>Getting more help
1441

  
1442
<p>If you use BIRD, you're welcome to join the bird-users mailing list
1443
(<HTMLURL URL="mailto:bird-users@bird.network.cz" name="bird-users@bird.network.cz">)
1444
where you can share your experiences with the other users and consult
1445
your problems with the authors. To subscribe to the list, just send a
1446
<tt/subscribe bird-users/ command in a body of a mail to
1447
(<HTMLURL URL="mailto:majordomo@bird.network.cz" name="majordomo@bird.network.cz">).
1448
The home page of BIRD can be found at <HTMLURL URL="http://bird.network.cz/" name="http://bird.network.cz/">.
1449

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

  
1457
<p>If you want to understand what is going inside, Internet standards are
1458
a good and interesting reading. You can get them from <HTMLURL URL="ftp://ftp.rfc-editor.org/" name="ftp.rfc-editor.org"> (or a nicely sorted version from <HTMLURL URL="ftp://atrey.karlin.mff.cuni.cz/pub/rfc" name="atrey.karlin.mff.cuni.cz:/pub/rfc">).
1434 1459

  
1435 1460
<p><it/Good luck!/
1436 1461

  

Also available in: Unified diff