Revision cf3e3845

View differences:

doc/bird.sgml
91 91
	<item>the Border Gateway Protocol (BGPv4)
92 92
	<item>the Routing Information Protocol (RIPv2, RIPng)
93 93
	<item>the Open Shortest Path First protocol (OSPFv2, OSPFv3)
94
	<item>the Babel Routing Protocol
94 95
	<item>the Router Advertisements for IPv6 hosts
95 96
	<item>a virtual protocol for exchange of routes between different
96 97
		routing tables on a single host
......
228 229
Other tables must be explicitly configured.
229 230

  
230 231
<p>
231
These routing tables are not kernel forwarding tables. No forwarding is done in BIRD.
232
If you want to forward packets using the routes in BIRD's tables, you may
233
use the Kernel protocol (see below) to synchronize them with kernel's FIBs.
232
These routing tables are not kernel forwarding tables. No forwarding is done by
233
BIRD. If you want to forward packets using the routes in BIRD tables, you may
234
use the Kernel protocol (see below) to synchronize them with kernel FIBs.
234 235

  
235 236
<p>
236
Every nettype defines a (kind of) primary key on routes. Every route source
237
can supply one route for every possible primary key; new route announcement
238
replaces the old route from the same source, keeping other routes intact.
239
BIRD always chooses the best route for every primary key among the known
240
routes and keeps the others as suboptimal. When the best route is retracted,
241
BIRD re-runs the best route selection algorithm to find the current best route.
237
Every nettype defines a (kind of) primary key on routes. Every route source can
238
supply one route for every possible primary key; new route announcement replaces
239
the old route from the same source, keeping other routes intact. BIRD always
240
chooses the best route for each primary key among the known routes and keeps the
241
others as suboptimal. When the best route is retracted, BIRD re-runs the best
242
route selection algorithm to find the current best route.
242 243

  
243 244
<p>
244 245
The global best route selection algorithm is (roughly) as follows:
......
246 247
<itemize>
247 248
	<item>Preferences of the routes are compared.
248 249
	<item>Source protocol instance preferences are compared.
249
	<item>If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined.
250 250
	<item>If source protocols are the same (e.g. BGP vs. BGP), the protocol's route selection algorithm is invoked.
251
	<item>If source protocols are different (e.g. BGP vs. OSPF), result of the algorithm is undefined.
251 252
</itemize>
252 253

  
253
<p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected route
254
from a list of entries for one network. But if the <cf/sorted/ option is
254
<p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected
255
route from a list of entries for one network. But if the <cf/sorted/ option is
255 256
activated, these lists of entries are kept completely sorted (according to
256 257
preference or some protocol-dependent metric). This is needed for some features
257 258
of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to
......
267 268

  
268 269
<p>BIRD works with several types of routes. Some of them are typical IP routes,
269 270
others are better described as forwarding rules. We call them all routes,
270
regardless on this difference.
271
regardless of this difference.
271 272

  
272
<p>Every route consists of several attributes (read more about them in the <ref id="route-attributes" name="Route attributes"> section); the common for all routes are:
273
<p>Every route consists of several attributes (read more about them in the
274
<ref id="route-attributes" name="Route attributes"> section); the common for all
275
routes are:
273 276

  
274 277
<itemize>
275 278
	<item>IP address of router which told us about this route
......
281 284
<p>Other attributes depend on nettypes. Some of them are part of the primary key, these are marked (PK).
282 285

  
283 286
<sect1>IPv4 and IPv6 routes
284
<label id="ipv4-ipv6-routes">
287
<label id="ip-routes">
285 288

  
286 289
<p>The traditional routes. Configuration keywords are <cf/ipv4/ and <cf/ipv6/.
287 290

  
......
291 294
</itemize>
292 295

  
293 296
<sect1>VPN IPv4 and IPv6 routes
294
<label id="vpn4-vpn6-routes">
297
<label id="vpn-routes">
295 298

  
296 299
<p>Routes for IPv4 and IPv6 with VPN Route Distinguisher (<rfc id="4364">).
297 300
Configuration keywords are <cf/vpn4/ and <cf/vpn6/.
......
303 306
</itemize>
304 307

  
305 308
<sect1>Route Origin Authorization for IPv4 and IPv6
306
<label id="roa4-roa6-routes">
309
<label id="roa-routes">
307 310

  
308 311
<p>These entries can be used to validate route origination of BGP routes.
309
An ROA entry specifies prefixes which could be originated by an AS number.
312
A ROA entry specifies prefixes which could be originated by an AS number.
310 313
Their keywords are <cf/roa4/ and <cf/roa6/.
311 314

  
312 315
<itemize>
......
316 319
</itemize>
317 320

  
318 321
<sect1>Flowspec for IPv4 and IPv6
319
<label id="flow4-flow6-routes">
322
<label id="flow-routes">
320 323

  
321 324
<p>Flowspec rules are a form of firewall and traffic flow control rules
322 325
distributed mostly via BGP. These rules may help the operators stop various
......
357 360
<sect>Protocols and channels
358 361
<label id="protocols-concept">
359 362

  
360
<p>BIRD's protocol is an abstract class of producers and consumers of the routes.
363
<p>BIRD protocol is an abstract class of producers and consumers of the routes.
361 364
Each protocol may run in multiple instances and bind on one side to route
362 365
tables via channels, on the other side to specified listen sockets (BGP),
363 366
interfaces (Babel, OSPF, RIP), APIs (Kernel, Direct), or nothing (Static, Pipe).
364 367

  
365
<p>There are also two protocols which do not have any channels -- BFD and Device.
368
<p>There are also two protocols that do not have any channels -- BFD and Device.
366 369
Both of them are kind of service for other protocols.
367 370

  
368 371
<p>Each protocol is connected to a routing table through a channel. Some protocols
......
439 442

  
440 443
<p><descrip>
441 444
	<tag><label id="opt-include">include "<m/filename/";</tag>
442
	This statement causes inclusion of a new file. The <m/filename/ could also
443
	be a wildcard, in that case matching files are included in alphabetic
444
	order. The maximal depth is 8. Note that this statement can be used
445
	anywhere in the config file, even inside other options, but always on the beginning of line.
446
	In the following example, the first semicolon belongs to the <cf/include/, the second to <cf/ipv6 table/.
447
	If the <file/tablename.conf/ contains exactly one token (the name of the table), this construction is correct:
445
	This statement causes inclusion of a new file. The <m/filename/ could
446
	also be a wildcard, in that case matching files are included in
447
	alphabetic order. The maximal depth is 8. Note that this statement can
448
	be used anywhere in the config file, even inside other options, but
449
	always on the beginning of line. In the following example, the first
450
	semicolon belongs to the <cf/include/, the second to <cf/ipv6 table/.
451
	If the <file/tablename.conf/ contains exactly one token (the name of the
452
	table), this construction is correct:
448 453
<code>
449 454
ipv6 table
450 455
include "tablename.conf";;
......
505 510
	<tag><label id="opt-function">function <m/name/ (<m/parameters/) <m/local variables/ { <m/commands/ }</tag>
506 511
	Define a function. You can learn more about functions in the following chapter.
507 512

  
508
	<tag><label id="opt-protocol">protocol rip [|ng]|ospf [v2|v3]|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
513
	<tag><label id="opt-protocol">protocol rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
509 514
	Define a protocol instance called <cf><m/name/</cf> (or with a name like
510 515
	"rip5" generated automatically if you don't specify any
511 516
	<cf><m/name/</cf>). You can learn more about configuring protocols in
......
514 519
	<cf><m/name2/</cf> You can run more than one instance of most protocols
515 520
	(like RIP or BGP). By default, no instances are configured.
516 521

  
517
	<tag><label id="opt-template">template rip [|ng]|ospf [v2|v3]|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
522
	<tag><label id="opt-template">template rip|ospf|bgp|<m/.../ [<m/name/ [from <m/name2/]] { <m>protocol options</m> }</tag>
518 523
	Define a protocol template instance called <m/name/ (or with a name like
519 524
	"bgp1" generated automatically if you don't specify any	<m/name/).
520 525
	Protocol templates can be used to group common options when many
......
575 580
	<cf/log/ times.
576 581

  
577 582
	<tag><label id="opt-table"><m/nettype/ table <m/name/ [sorted]</tag>
578
	Create a new routing table. The default routing tables <cf/master4/ and <cf/master6/ are created
579
	implicitly, other routing tables have to be added by this command.
580
	Option <cf/sorted/ can be used to enable sorting of routes, see
581
	<ref id="dsc-table-sorted" name="sorted table"> description for details.
582

  
583
<!--
584
	<tag><label id="opt-roa-table">roa table <m/name/ [ { <m/roa table options .../ } ]</tag>
585
	Create a new ROA (Route Origin Authorization) table. ROA tables can be
586
	used to validate route origination of BGP routes. A ROA table contains
587
	ROA entries, each consist of a network prefix, a max prefix length and
588
	an AS number. A ROA entry specifies prefixes which could be originated
589
	by that AS number. ROA tables could be filled with data from RPKI (<rfc
590
	id="6480">) or from public databases like Whois. ROA tables are
591
	examined by <cf/roa_check()/ operator in filters.
592

  
593
	Currently, there is just one option, <cf>roa <m/prefix/ max <m/num/ as
594
	<m/num/</cf>, which can be used to populate the ROA table with static
595
	ROA entries. The option may be used multiple times. Other entries can be
596
	added dynamically by <cf/add roa/ command.
597
-->
583
	Create a new routing table. The default routing tables <cf/master4/ and
584
	<cf/master6/ are created implicitly, other routing tables have to be
585
	added by this command.  Option <cf/sorted/ can be used to enable sorting
586
	of routes, see <ref id="dsc-table-sorted" name="sorted table">
587
	description for details.
598 588

  
599 589
	<tag><label id="opt-eval">eval <m/expr/</tag>
600 590
	Evaluates given filter expression. It is used by the developers for testing of filters.
601 591
</descrip>
602 592

  
593

  
603 594
<sect>Protocol options
604 595
<label id="protocol-opts">
605 596

  
......
614 605
agreement").
615 606

  
616 607
<descrip>
617
	<tag><label id="proto-preference">preference <m/expr/</tag>
618
	Sets the preference of routes generated by this protocol. Default:
619
	protocol dependent.
620

  
621 608
	<tag><label id="proto-disabled">disabled <m/switch/</tag>
622 609
	Disables the protocol. You can change the disable/enable status from the
623 610
	command line interface without needing to touch the configuration.
......
662 649
	multihop BGP.
663 650

  
664 651
	<tag><label id="proto-channel"><m/channel name/ [{<m/channel config/}]</tag>
665
	Every channel must be explicitly stated. See the protocol-specific configuration
666
	for the list of supported channel names.
667
	See the <ref id="channel-opts" name="channel configuration section"> for channel definition.
652
	Every channel must be explicitly stated. See the protocol-specific
653
	configuration for the list of supported channel names. See the
654
	<ref id="channel-opts" name="channel configuration section"> for channel
655
	definition.
668 656
</descrip>
669 657

  
670 658
<p>There are several options that give sense only with certain protocols:
......
693 681
	options, in that case for given interface the first matching interface
694 682
	option is used.
695 683

  
696
	This option is allowed in Babel, BFD, Direct, OSPF, RAdv and RIP
684
	This option is allowed in Babel, BFD, Device, Direct, OSPF, RAdv and RIP
697 685
	protocols. In OSPF protocol it is used in the <cf/area/ subsection.
698 686

  
699 687
	Default: none.
......
782 770

  
783 771
</descrip>
784 772

  
773

  
785 774
<sect>Channel options
786 775
<label id="channel-opts">
787 776

  
788 777
<p>Every channel belongs to a protocol and is configured inside its block. The
789
minimal channel config is empty, then it uses the default values.
790
The channel's name implies its nettype.
778
minimal channel config is empty, then it uses the default values. The name of
779
the channel implies its nettype.
791 780

  
792 781
<descrip>
793 782
	<tag><label id="proto-table">table <m/name/</tag>
794
	Connect this channel to a non-default routing table. Default 
783
	Specify a table to which the channel is connected. Default: the first
784
	table of given nettype.
785

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

  
796 790
	<tag><label id="proto-import">import all | none | filter <m/name/ | filter { <m/filter commands/ } | where <m/boolean filter expression/</tag>
797 791
	Specify a filter to be used for filtering routes coming from the
......
1187 1181
	a shell pattern (represented also as a string).
1188 1182

  
1189 1183
	<tag><label id="type-ip">ip</tag>
1190
	This type can hold a single IP address. The IPv4 addresses are stored
1191
	as IPv4-Mapped IPv6 addresses so one data type for both of them is used.
1192
	Whether the address is IPv4 or not may be checked by 
1193
	<cf>.is_ip4</cf> which returns <cf/bool/.
1194
        IP addresses are written in the standard notation
1195
	(<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator
1196
	<cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but
1197
	first <cf><M>num</M></cf> bits from the IP address. So
1184
	This type can hold a single IP address. The IPv4 addresses are stored as
1185
	IPv4-Mapped IPv6 addresses so one data type for both of them is used.
1186
	Whether the address is IPv4 or not may be checked by <cf>.is_ip4</cf>
1187
	which returns <cf/bool/. IP addresses are written in the standard
1188
	notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special
1189
	operator <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out
1190
	all but first <cf><M>num</M></cf> bits from the IP address. So
1198 1191
	<cf/1.2.3.4.mask(8) = 1.0.0.0/ is true.
1199 1192

  
1200 1193
	<tag><label id="type-prefix">prefix</tag>
......
1207 1200
	<cf/NET_IP4/ and <cf/NET_IP6/ prefixes hold an IP prefix. The literals
1208 1201
	are written as <cf><m/ipaddress//<m/pxlen/</cf>,
1209 1202
	or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special
1210
	operators on these: <cf/.ip/ which extracts the IP address from
1211
	the pair, and <cf/.len/, which separates prefix length from the pair.
1203
	operators on these: <cf/.ip/ which extracts the IP address from the
1204
	pair, and <cf/.len/, which separates prefix length from the pair.
1212 1205
	So <cf>1.2.0.0/16.len = 16</cf> is true.
1213 1206

  
1214 1207
	<cf/NET_VPN4/ and <cf/NET_VPN6/ prefixes hold an IP prefix with VPN
......
1225 1218
	<cf/NET_FLOW4/ and <cf/NET_FLOW6/ hold an IP prefix together with a
1226 1219
	flowspec rule. Filters currently don't support flowspec parsing.
1227 1220

  
1228
	<cf/NET_MPLS/ holds a single MPLS label and its handling is currently not implemented.
1221
	<cf/NET_MPLS/ holds a single MPLS label and its handling is currently
1222
	not implemented.
1229 1223

  
1230 1224
	<tag><label id="type-vpnrd">vpnrd</tag>
1231 1225
	This is a route distinguisher according to <rfc id="4364">. There are
......
1328 1322
	<cf>192.168.0.0/16{16,24}</cf> and <cf>192.168.0.0/16 ge 24</cf> as
1329 1323
	<cf>192.168.0.0/16{24,32}</cf>.
1330 1324

  
1331
	It's possible to mix IPv4 and IPv6 prefixes/addresses in a prefix/ip set
1325
	It is possible to mix IPv4 and IPv6 prefixes/addresses in a prefix/ip set
1332 1326
	but its behavior may change between versions without any warning; don't do
1333 1327
	it unless you are more than sure what you are doing. (Really, don't do it.)
1334 1328

  
......
1509 1503

  
1510 1504
<descrip>
1511 1505
	<tag><label id="rta-net"><m/prefix/ net</tag>
1512
	The network prefix or anything else the route is talking about.
1513
	The primary key of the table. Read-only. (See the <ref id="routes" name="chapter about routes">.)
1506
	The network prefix or anything else the route is talking about. The
1507
	primary key of the routing table. Read-only. (See the <ref id="routes"
1508
	name="chapter about routes">.)
1514 1509

  
1515 1510
	<tag><label id="rta-scope"><m/enum/ scope</tag>
1516 1511
	The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes
......
1638 1633
		type <wired|wireless>;
1639 1634
		rxcost <number>;
1640 1635
		limit <number>;
1641
		hello interval <number>;
1642
		update interval <number>;
1636
		hello interval <time>;
1637
		update interval <time>;
1643 1638
		port <number>;
1644 1639
		tx class|dscp <number>;
1645 1640
		tx priority <number>;
......
1654 1649

  
1655 1650
<descrip>
1656 1651
      <tag><label id="babel-channel">ipv4|ipv6 <m/channel config/</tag>
1657
      The supported channels are IPv4 and IPv6. 
1652
      The supported channels are IPv4 and IPv6.
1658 1653

  
1659 1654
      <tag><label id="babel-type">type wired|wireless </tag>
1660 1655
      This option specifies the interface type: Wired or wireless. On wired
......
1683 1678
      type interfaces, where gradual cost degradation is used instead of sharp
1684 1679
      limit. Default: 12.
1685 1680

  
1686
      <tag><label id="babel-hello">hello interval <m/num/</tag>
1681
      <tag><label id="babel-hello">hello interval <m/time/ s|ms</tag>
1687 1682
      Interval at which periodic Hello messages are sent on this interface,
1688
      in seconds. Default: 4 seconds.
1683
      with time units. Default: 4 seconds.
1689 1684

  
1690
      <tag><label id="babel-update">update interval <m/num/</tag>
1691
      Interval at which periodic (full) updates are sent. Default: 4 times the
1692
      hello interval.
1685
      <tag><label id="babel-update">update interval <m/time/ s|ms</tag>
1686
      Interval at which periodic (full) updates are sent, with time
1687
      units. Default: 4 times the hello interval.
1693 1688

  
1694 1689
      <tag><label id="babel-port">port <m/number/</tag>
1695 1690
      This option selects an UDP port to operate on. The default is to operate
......
1722 1717

  
1723 1718
      <tag><label id="babel-next-hop-ipv4">next hop ipv4 <m/address/</tag>
1724 1719
      Set the next hop address advertised for IPv4 routes advertised on this
1725
      interface. If not set, the first IPv4 address found on the interface will
1726
      be used, so it should only be necessary to set this option if this
1727
      auto-detection fails or finds the wrong address.
1720
      interface. Default: the preferred IPv4 address of the interface.
1728 1721

  
1729 1722
      <tag><label id="babel-next-hop-ipv6">next hop ipv6 <m/address/</tag>
1730 1723
      Set the next hop address advertised for IPv6 routes advertised on this
......
1771 1764
<sect1>Known issues
1772 1765
<label id="babel-issues">
1773 1766

  
1774
<p>When retracting a route, Babel sends instead an unreachable route for a little while (according to RFC). The
1775
interaction of this behavior with other protocols is not well tested and strange things may happen.
1767
<p>When retracting a route, Babel generates an unreachable route for a little
1768
while (according to RFC). The interaction of this behavior with other protocols
1769
is not well tested and strange things may happen.
1770

  
1776 1771

  
1777 1772
<sect>BFD
1778 1773
<label id="bfd">
......
2149 2144
	BIRD tracks the link state of the associated interface and when link
2150 2145
	disappears (e.g. an ethernet cable is unplugged), the BGP session is
2151 2146
	immediately shut down. Note that this option cannot be used with
2152
	multihop BGP. Default: disabled.
2147
	multihop BGP. Default: enabled for direct BGP, disabled otherwise.
2153 2148

  
2154 2149
	<tag><label id="bgp-bfd">bfd <M>switch</M></tag>
2155 2150
	BGP could use BFD protocol as an advisory mechanism for neighbor
......
2386 2381

  
2387 2382
	<tag><label id="bgp-igp-metric">igp metric <m/switch/</tag>
2388 2383
	Enable comparison of internal distances to boundary routers during best
2389
 	route selection. Default: on.
2384
	route selection. Default: on.
2390 2385

  
2391 2386
	<tag><label id="bgp-prefer-older">prefer older <m/switch/</tag>
2392 2387
	Standard route selection algorithm breaks ties by comparing router IDs.
......
2601 2596

  
2602 2597
<p><code>
2603 2598
protocol bgp {
2604
	local as 65000;			     # Use a private AS number
2599
	local 198.51.100.14 as 65000;	     # Use a private AS number
2605 2600
	neighbor 198.51.100.130 as 64496;    # Our neighbor ...
2606 2601
	multihop;			     # ... which is connected indirectly
2607
	source address 198.51.100.14;	# Use a non-standard source address
2608 2602
	ipv4 {
2609 2603
		export filter {			     # We use non-trivial export rules
2610 2604
			if source = RTS_STATIC then { # Export only static routes
......
2655 2649
<label id="device-config">
2656 2650

  
2657 2651
<p><descrip>
2658

  
2659 2652
	<tag><label id="device-scan-time">scan time <m/number/</tag>
2660 2653
	Time in seconds between two scans of the network interface list. On
2661 2654
	systems where we are notified about interface status changes
......
2663 2656
	list only in order to avoid confusion by lost notification messages,
2664 2657
	so the default time is set to a large value.
2665 2658

  
2666
	<tag><label id="device-primary">primary [ "<m/mask/" ] <m/prefix/</tag>
2667
	If a network interface has more than one network address, BIRD has to
2668
	choose one of them as a primary one. By default, BIRD chooses the
2669
	lexicographically smallest address as the primary one.
2670

  
2671
	This option allows to specify which network address should be chosen as
2672
	a primary one. Network addresses that match <m/prefix/ are preferred to
2673
	non-matching addresses. If more <cf/primary/ options are used, the first
2674
	one has the highest preference. If "<m/mask/" is specified, then such
2675
	<cf/primary/ option is relevant only to matching network interfaces.
2676

  
2677
	In all cases, an address marked by operating system as secondary cannot
2678
	be chosen as the primary one.
2659
	<tag><label id="device-iface">interface <m/pattern/ [, <m/.../]</tag>
2660

  
2661
	By default, the Device protocol handles all interfaces without any
2662
	configuration. Interface definitions allow to specify optional
2663
	parameters for specific interfaces. See <ref id="proto-iface"
2664
	name="interface"> common option for detailed description. Currently only
2665
	one interface option is available:
2666

  
2667
	<tag><label id="device-preferred">preferred <m/ip/</tag>
2668
	If a network interface has more than one IP address, BIRD chooses one of
2669
	them as a preferred one. Preferred IP address is used as source address
2670
	for packets or announced next hop by routing protocols. Precisely, BIRD
2671
	chooses one preferred IPv4 address, one preferred IPv6 address and one
2672
	preferred link-local IPv6 address. By default, BIRD chooses the first
2673
	found IP address as the preferred one.
2674

  
2675
	This option allows to specify which IP address should be preferred. May
2676
	be used multiple times for different address classes (IPv4, IPv6, IPv6
2677
	link-local). In all cases, an address marked by operating system as
2678
	secondary cannot be chosen as the primary one.
2679 2679
</descrip>
2680 2680

  
2681 2681
<p>As the Device protocol doesn't generate any routes, it cannot have
......
2684 2684
<p><code>
2685 2685
protocol device {
2686 2686
	scan time 10;		# Scan the interfaces often
2687
	primary "eth0" 192.168.1.1;
2688
	primary 192.168.0.0/16;
2687
	interface "eth0" {
2688
		preferred 192.168.1.1;
2689
		preferred 2001:db8:1:10::1;
2690
	};
2689 2691
}
2690 2692
</code>
2691 2693

  
2694

  
2692 2695
<sect>Direct
2693 2696
<label id="direct">
2694 2697

  
2695 2698
<p>The Direct protocol is a simple generator of device routes for all the
2696 2699
directly connected networks according to the list of interfaces provided by the
2697
kernel via the Device protocol. The Direct protocol supports IPv4 and IPv6 channels
2698
in any count.
2700
kernel via the Device protocol. The Direct protocol supports both IPv4 and IPv6
2701
channels.
2699 2702

  
2700 2703
<p>The question is whether it is a good idea to have such device routes in BIRD
2701 2704
routing table. OS kernel usually handles device routes for directly connected
......
2739 2742

  
2740 2743
<p><code>
2741 2744
protocol direct {
2742
	interface "-arc*", "*";		# Exclude the ARCnets
2743 2745
	ipv4;
2744
	ipv4 { table myothertable; };
2745 2746
	ipv6;
2747
	interface "-arc*", "*";		# Exclude the ARCnets
2746 2748
}
2747 2749
</code>
2748 2750

  
2751

  
2749 2752
<sect>Kernel
2750 2753
<label id="krt">
2751 2754

  
......
2778 2781
kernel protocols to the same routing table and changing route destination
2779 2782
(gateway) in an export filter of a kernel protocol does not work. Both
2780 2783
limitations can be overcome using another routing table and the pipe protocol.
2781
The Kernel protocol obviously supports only two channels -- IPv4 and IPv6; only
2782
one of them can be configured in each protocol instance.
2784

  
2785
<p>The Kernel protocol supports both IPv4 and IPv6 channels; only one of them
2786
can be configured in each protocol instance.
2783 2787

  
2784 2788
<sect1>Configuration
2785 2789
<label id="krt-config">
......
2798 2802
	routing daemons or by the system administrator. This is possible only on
2799 2803
	systems which support identification of route authorship.
2800 2804

  
2801
	<tag><label id="krt-device-routes">device routes <m/switch/</tag>
2802
	Enable export of device routes to the kernel routing table. By default,
2803
	such routes are rejected (with the exception of explicitly configured
2804
	device routes from the static protocol) regardless of the export filter
2805
	to protect device routes in kernel routing table (managed by OS itself)
2806
	from accidental overwriting or erasing.
2807

  
2808 2805
	<tag><label id="krt-kernel-table">kernel table <m/number/</tag>
2809 2806
	Select which kernel table should this particular instance of the Kernel
2810 2807
	protocol work with. Available only on systems supporting multiple
......
2971 2968
definitions of interfaces. Definition of interface may contain many switches and
2972 2969
constant definitions and list of neighbors on nonbroadcast networks.
2973 2970

  
2974
<p>OSPF v2 needs one IPv4 channel, OSPF v3 needs one IPv6 channel.
2971
<p>OSPFv2 needs one IPv4 channel. OSPFv3 needs either one IPv6 channel, or one
2972
IPv4 channel (<rfc id="5838">). Therefore, it is possible to use OSPFv3 for both
2973
IPv4 and Pv6 routing, but it is necessary to have two protocol instances anyway.
2974
If no channel is configured, appropriate channel is defined with default
2975
parameters.
2975 2976

  
2976 2977
<code>
2977 2978
protocol ospf [v2|v3] &lt;name&gt; {
......
3114 3115
	(equal-cost multipath) routes. Such routes are used when there are
3115 3116
	several directions to the destination, each with the same (computed)
3116 3117
	cost. This option also allows to specify a limit on maximum number of
3117
	nexthops in one route. By default, ECMP is disabled. If enabled,
3118
	default	value of the limit is 16.
3118
	nexthops in one route. By default, ECMP is enabled if supported by
3119
	Kernel. Default value of the limit is 16.
3119 3120

  
3120 3121
	<tag><label id="ospf-merge-external">merge external <M>switch</M></tag>
3121 3122
	This option specifies whether OSPF should merge external routes from
......
3354 3355
	are immediately considered unreachable and only the address of the iface
3355 3356
	(instead of whole network prefix) is propagated. It is possible that
3356 3357
	some hardware drivers or platforms do not implement this feature.
3357
	Default value is no.
3358
	Default value is yes.
3358 3359

  
3359 3360
	<tag><label id="ospf-bfd">bfd <M>switch</M></tag>
3360 3361
	OSPF could use BFD protocol as an advisory mechanism for neighbor
......
3441 3442

  
3442 3443
<p><code>
3443 3444
protocol ospf MyOSPF {
3444
	rfc1583compat yes;
3445
	tick 2;
3446 3445
	ipv4 {
3447 3446
		export filter {
3448 3447
			if source = RTS_BGP then {
......
3549 3548
<sect1>Configuration
3550 3549
<label id="pipe-config">
3551 3550

  
3552
<p>Technically, the Pipe protocol is just a channel connected to a table on both sides.
3553
Therefore, the configuration block for <cf/protocol pipe/ shall directly include
3554
standard channel config options; see the example below.
3551
<p>Essentially, the Pipe protocol is just a channel connected to a table on both
3552
sides. Therefore, the configuration block for <cf/protocol pipe/ shall directly
3553
include standard channel config options; see the example below.
3555 3554

  
3556 3555
<p><descrip>
3557 3556
	<tag><label id="pipe-peer-table">peer table <m/table/</tag>
3558 3557
	Defines secondary routing table to connect to. The primary one is
3559 3558
	selected by the <cf/table/ keyword.
3560

  
3561
	<tag><label id="pipe-mode">mode opaque|transparent</tag>
3562
	Specifies the mode for the pipe to work in. Default is transparent.
3563 3559
</descrip>
3564 3560

  
3565 3561
<sect1>Attributes
......
3586 3582
to reflect the AS boundary crossing.
3587 3583

  
3588 3584
<code>
3589
table as1;				# Define the tables
3590
table as2;
3585
ipv4 table as1;				# Define the tables
3586
ipv4 table as2;
3591 3587

  
3592 3588
protocol kernel kern1 {			# Synchronize them with the kernel
3593
	ipv4 { table as1; };
3589
	ipv4 { table as1; export all; };
3594 3590
	kernel table 1;
3595 3591
}
3596 3592

  
3597 3593
protocol kernel kern2 {
3598
	ipv4 { table as2; };
3594
	ipv4 { table as2; export all; };
3599 3595
	kernel table 2;
3600 3596
}
3601 3597

  
3602 3598
protocol bgp bgp1 {			# The outside connections
3603
	ipv4 {
3604
		table as1;
3605
		export all;
3606
		import all;
3607
	};
3599
	ipv4 { table as1; export all; };
3608 3600
	local as 1;
3609 3601
	neighbor 192.168.0.1 as 1001;
3610 3602
}
3611 3603

  
3612 3604
protocol bgp bgp2 {
3613
	ipv4 {
3614
		table as2;
3615
		export all;
3616
		import all;
3617
	};
3605
	ipv4 { table as2; export all; };
3618 3606
	local as 2;
3619 3607
	neighbor 10.0.0.1 as 1002;
3620 3608
}
......
3657 3645
in <rfc id="4861">, router preferences and specific routes (<rfc id="4191">),
3658 3646
and DNS extensions (<rfc id="6106">).
3659 3647

  
3660
<p>The RAdv protocols supports only IPv6 channels.
3648
<p>The RAdv protocols supports just IPv6 channel.
3661 3649

  
3662 3650
<sect1>Configuration
3663 3651
<label id="radv-config">
......
3827 3815
	option above. Default: no.
3828 3816
</descrip>
3829 3817

  
3830

  
3831 3818
<p>Prefix specific options
3832 3819

  
3833 3820
<descrip>
......
3879 3866
	valid DNS servers. Default: 3 * <cf/max ra interval/.
3880 3867
</descrip>
3881 3868

  
3882

  
3883 3869
<p>DNSSL specific options:
3884 3870

  
3885 3871
<descrip>
......
3917 3903
<label id="radv-exam">
3918 3904

  
3919 3905
<p><code>
3920
table radv_routes;			# Manually configured routes go here
3906
ipv6 table radv_routes;			# Manually configured routes go here
3921 3907

  
3922 3908
protocol static {
3923
	table radv_routes;
3909
	ipv6 { table radv_routes; };
3924 3910

  
3925 3911
	route 2001:0DB8:4000::/48 unreachable;
3926 3912
	route 2001:0DB8:4010::/48 unreachable;
......
3933 3919

  
3934 3920
protocol radv {
3935 3921
	propagate routes yes;		# Propagate the routes from the radv_routes table
3936
	table radv_routes;
3937
	export all;
3922
	ipv6 { table radv_routes; export all; };
3938 3923

  
3939 3924
	interface "eth2" {
3940 3925
		max ra interval 5;	# Fast failover with more routers
......
3970 3955
}
3971 3956
</code>
3972 3957

  
3958

  
3973 3959
<sect>RIP
3974 3960
<label id="rip">
3975 3961

  
......
4003 3989
protocol instance can be configured by using <cf/rip ng/ instead of just
4004 3990
<cf/rip/ as a protocol type.
4005 3991

  
3992
<p>RIP needs one IPv4 channel. RIPng needs one IPv6 channel. If no channel is
3993
configured, appropriate channel is defined with default parameters.
3994

  
4006 3995
<code>
4007 3996
protocol rip [ng] [&lt;name&gt;] {
4008 3997
	infinity &lt;number&gt;;
......
4053 4042
	(equal-cost multipath) routes. Such routes are used when there are
4054 4043
	several directions to the destination, each with the same (computed)
4055 4044
	cost. This option also allows to specify a limit on maximum number of
4056
	nexthops in one route. By default, ECMP is disabled. If enabled,
4057
	default	value of the limit is 16.
4045
	nexthops in one route. By default, ECMP is enabled if supported by
4046
	Kernel. Default value of the limit is 16.
4058 4047

  
4059 4048
	<tag><label id="rip-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag>
4060 4049
	Interface definitions specify a set of interfaces on which the
......
4200 4189
	unplugged), neighbors are immediately considered unreachable and all
4201 4190
	routes received from them are withdrawn. It is possible that some
4202 4191
	hardware drivers or platforms do not implement this feature.
4203
	Default: no.
4192
	Default: yes.
4204 4193
</descrip>
4205 4194

  
4206 4195
<sect1>Attributes
......
4227 4216

  
4228 4217
<p><code>
4229 4218
protocol rip {
4230
	import all;
4231
	export all;
4219
	ipv4 {
4220
		import all;
4221
		export all;
4222
	};
4232 4223
	interface "eth*" {
4233 4224
		metric 2;
4234 4225
		port 1520;
......
4241 4232
}
4242 4233
</code>
4243 4234

  
4235

  
4244 4236
<sect>RPKI
4245 4237

  
4246 4238
<sect1>Introduction
......
4248 4240
<p>The Resource Public Key Infrastructure (RPKI) is mechanism for origin
4249 4241
validation of BGP routes (RFC 6480). BIRD supports only so-called RPKI-based
4250 4242
origin validation. There is implemented RPKI to Router (RPKI-RTR) protocol (RFC
4251
6810).  It uses some of the RPKI data to allow a router to verify that the
4243
6810). It uses some of the RPKI data to allow a router to verify that the
4252 4244
autonomous system announcing an IP address prefix is in fact authorized to do
4253 4245
so. This is not crypto checked so can be violated. But it should prevent the
4254 4246
vast majority of accidental hijackings on the Internet today, e.g. the famous
......
4294 4286
}
4295 4287
</code>
4296 4288

  
4297
<p>Alse note that you have to specify the ROA channel.
4298
If you want to import only IPv4 prefixes you have
4299
to specify only roa4 channel. Similarly with IPv6 prefixes only. If you want to
4300
fetch both IPv4 and even IPv6 ROAs you have to specify both channels.
4289
<p>Alse note that you have to specify the ROA channel. If you want to import
4290
only IPv4 prefixes you have to specify only roa4 channel. Similarly with IPv6
4291
prefixes only. If you want to fetch both IPv4 and even IPv6 ROAs you have to
4292
specify both channels.
4301 4293

  
4302 4294
<sect2>RPKI protocol options
4303 4295

  
......
4365 4357

  
4366 4358
protocol rpki {
4367 4359
	debug all;
4368
	
4360

  
4369 4361
	roa4 { table r4; };
4370 4362
	roa6 { table r6; };
4371 4363

  
4372 4364
	# Please, do not use rpki-validator.realmv6.org in production
4373 4365
	remote "rpki-validator.realmv6.org" port 8282;
4374
	
4366

  
4375 4367
	retry keep 5;
4376 4368
	refresh keep 30;
4377 4369
	expire 600;
4378 4370
}
4379 4371

  
4380
filter peer_in {
4381
	if (roa_check(r4, net, bgp_path.last) = ROA_INVALID ||
4382
	    roa_check(r6, net, bgp_path.last) = ROA_INVALID) then
4372
filter peer_in_v4 {
4373
	if (roa_check(r4, net, bgp_path.last) = ROA_INVALID) then
4383 4374
	{
4384 4375
		print "Ignore invalid ROA ", net, " for ASN ", bgp_path.last;
4385 4376
		reject;
......
4391 4382
	debug all;
4392 4383
	local as 65000;
4393 4384
	neighbor 192.168.2.1 as 65001;
4394
	import filter peer_in;
4385
	ipv4 { import filter peer_in_v4; };
4395 4386
}
4396 4387
</code>
4397 4388

  
......
4402 4393

  
4403 4394
protocol rpki {
4404 4395
	debug all;
4405
	
4396

  
4406 4397
	roa4 { table r4; };
4407 4398
	roa6 { table r6; };
4408
	
4399

  
4409 4400
	remote 127.0.0.1 port 2345;
4410 4401
	transport ssh {
4411 4402
		bird private key "/home/birdgeek/.ssh/id_rsa";
4412 4403
		remote public key "/home/birdgeek/.ssh/known_hosts";
4413 4404
		user "birdgeek";
4414 4405
	};
4415
	
4406

  
4416 4407
	# Default interval values
4417 4408
}
4418 4409
</code>
4419 4410

  
4420 4411

  
4421

  
4422 4412
<sect>Static
4423 4413
<label id="static">
4424 4414

  
......
4461 4451
	<tag>route <m/prefix/ via <m/ip/|<m/"interface"/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag>
4462 4452
	Next hop routes may bear one or more <ref id="route-next-hop" name="next hops">.
4463 4453
	Every next hop is preceded by <cf/via/ and configured as shown.
4454

  
4464 4455
	<tag>route <m/prefix/ recursive <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag>
4465 4456
	Recursive nexthop resolves the given IP in the configured IGP table and
4466 4457
	uses that route's next hop. The MPLS stacks are concatenated; on top is
4467 4458
	the IGP's nexthop stack and on bottom is this route's stack.
4459

  
4468 4460
	<tag>route <m/prefix/ blackhole|unreachable|prohibit</tag>
4469 4461
	Special routes specifying to silently drop the packet, return it as
4470 4462
	unreachable or return it as administratively prohibited. First two
......
4559 4551
		length > 1024;
4560 4552
		dscp = 63;
4561 4553
		fragment dont_fragment, is_fragment || !first_fragment;
4562
	} drop;
4554
	};
4563 4555
}
4564 4556
</code>
4565 4557

  
......
4607 4599
		tcp flags 0x03/0x0f, !0/0xff || 0x33/0x33;
4608 4600
		fragment !is_fragment || !first_fragment;
4609 4601
		label 0xaaaa/0xaaaa && 0x33/0x33;
4610
	} drop;
4602
	};
4611 4603
}
4612 4604
</code>
4613 4605

  
......
4661 4653
}
4662 4654
</code>
4663 4655

  
4656

  
4664 4657
<chapt>Conclusions
4665 4658
<label id="conclusion">
4666 4659

  
sysdep/unix/krt.h
49 49
  btime scan_time;		/* How often we re-scan routes */
50 50
  int persist;			/* Keep routes when we exit */
51 51
  int learn;			/* Learn routes from other sources */
52
  int devroutes;		/* Allow export of device routes */
52
  int devroutes;		/* XXX: remove */
53 53
  int graceful_restart;		/* Regard graceful restart recovery */
54 54
};
55 55

  

Also available in: Unified diff