diff options
Diffstat (limited to 'doc/bird.sgml')
| -rw-r--r-- | doc/bird.sgml | 628 |
1 files changed, 516 insertions, 112 deletions
diff --git a/doc/bird.sgml b/doc/bird.sgml index d9200f26..ab515191 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -456,24 +456,26 @@ protocol rip { used for other commands and <cf/log/ is used in a log file. "<m/format1/" is a format string using <it/strftime(3)/ notation (see - <it/man strftime/ for details). <m/limit> and "<m/format2/" allow to - specify the second format string for times in past deeper than <m/limit/ - seconds. There are few shorthands: <cf/iso long/ is a ISO 8601 date/time - format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F %T"/. + <it/man strftime/ for details). It is extended to support sub-second + time part with variable precision (up to microseconds) using "%f" + conversion code (e.g., "%T.%3f" is hh:mm:ss.sss time). <m/limit/ and + "<m/format2/" allow to specify the second format string for times in + past deeper than <m/limit/ seconds. + + There are several shorthands: <cf/iso long/ is a ISO 8601 date/time + format (YYYY-MM-DD hh:mm:ss) that can be also specified using <cf/"%F + %T"/. Similarly, <cf/iso long ms/ and <cf/iso long us/ are ISO 8601 + date/time formats with millisecond or microsecond precision. <cf/iso short/ is a variant of ISO 8601 that uses just the time format (hh:mm:ss) for near times (up to 20 hours in the past) and the date - format (YYYY-MM-DD) for far times. This is a shorthand for - <cf/"%T" 72000 "%F"/. + format (YYYY-MM-DD) for far times. This is a shorthand for <cf/"%T" + 72000 "%F"/. And there are also <cf/iso short ms/ and <cf/iso short us/ + high-precision variants of that. - By default, BIRD uses the <cf/iso short/ format for <cf/route/ and - <cf/protocol/ times, and the <cf/iso long/ format for <cf/base/ and + By default, BIRD uses the <cf/iso short ms/ format for <cf/route/ and + <cf/protocol/ times, and the <cf/iso long ms/ format for <cf/base/ and <cf/log/ times. - In pre-1.4.0 versions, BIRD used an short, ad-hoc format for <cf/route/ - and <cf/protocol/ times, and a <cf/iso long/ similar format (DD-MM-YYYY - hh:mm:ss) for <cf/base/ and <cf/log/. These timeformats could be set by - <cf/old short/ and <cf/old long/ compatibility shorthands. - <tag><label id="opt-table">table <m/name/ [sorted]</tag> Create a new routing table. The default routing table is created implicitly, other routing tables have to be added by this command. @@ -724,6 +726,138 @@ agreement"). </descrip> + +<sect>Flowspec network type +<label id="flowspec-network-type"> + +<p>The flow specification are rules for routers and firewalls for filtering +purpose. It is described by <rfc id="5575">. There are 3 types of arguments: +<m/inet4/ or <m/inet6/ prefixes, bitmasks matching expressions and numbers +matching expressions. + +Bitmasks matching is written using <m/value/<cf>/</cf><m/mask/ or +<cf/!/<m/value/<cf>/</cf><m/mask/ pairs. It means that <cf/(/<m/data/ <cf/&/ +<m/mask/<cf/)/ is or is not equal to <m/value/. + +Numbers matching is a matching sequence of numbers and ranges separeted by a +commas (<cf/,/) (e.g. <cf/10,20,30/). Ranges can be written using double dots +<cf/../ notation (e.g. <cf/80..90,120..124/). An alternative notation are +sequence of one or more pairs of relational operators and values separated by +logical operators <cf/&&/ or <cf/||/. Allowed relational operators are <cf/=/, +<cf/!=/, <cf/</, <cf/<=/, <cf/>/, <cf/>=/, <cf/true/ and <cf/false/. + +<sect1>IPv4 Flowspec + +<p><descrip> + <tag><label id="flow-dst">dst <m/inet4/</tag> + Set a matching destination prefix (e.g. <cf>dst 192.168.0.0/16</cf>). + Only this option is mandatory in IPv4 Flowspec. + + <tag><label id="flow-src">src <m/inet4/</tag> + Set a matching source prefix (e.g. <cf>src 10.0.0.0/8</cf>). + + <tag><label id="flow-proto">proto <m/numbers-match/</tag> + Set a matching IP protocol numbers (e.g. <cf/proto 6/). + + <tag><label id="flow-port">port <m/numbers-match/</tag> + Set a matching source or destination TCP/UDP port numbers (e.g. + <cf>port 1..1023,1194,3306</cf>). + + <tag><label id="flow-dport">dport <m/numbers-match/</tag> + Set a mating destination port numbers (e.g. <cf>dport 49151</cf>). + + <tag><label id="flow-sport">sport <m/numbers-match/</tag> + Set a matching source port numbers (e.g. <cf>sport = 0</cf>). + + <tag><label id="flow-icmp-type">icmp type <m/numbers-match/</tag> + Set a matching type field number of an ICMP packet (e.g. <cf>icmp type + 3</cf>) + + <tag><label id="flow-icmp-code">icmp code <m/numbers-match/</tag> + Set a matching code field number of an ICMP packet (e.g. <cf>icmp code + 1</cf>) + + <tag><label id="flow-tcp-flags">tcp flags <m/bitmask-match/</tag> + Set a matching bitmask for TCP header flags (aka control bits) (e.g. + <cf>tcp flags 0x03/0x0f;</cf>). The maximum length of mask is 12 bits + (0xfff). + + <tag><label id="flow-length">length <m/numbers-match/</tag> + Set a matching packet length (e.g. <cf>length > 1500;</cf>) + + <tag><label id="flow-dscp">dscp <m/numbers-match/</tag> + Set a matching DiffServ Code Point number (e.g. <cf>length > 1500;</cf>). + + <tag><label id="flow-fragment">fragment <m/fragmentation-type/</tag> + Set a matching type of packet fragmentation. Allowed fragmentation + types are <cf/dont_fragment/, <cf/is_fragment/, <cf/first_fragment/, + <cf/last_fragment/ (e.g. <cf>fragment is_fragment && + !dont_fragment</cf>). +</descrip> + +<p><code> +protocol static { + flow4; + + route flow4 { + dst 10.0.0.0/8; + port > 24 && < 30 || 40..50,60..70,80 && >= 90; + tcp flags 0x03/0x0f; + length > 1024; + dscp = 63; + fragment dont_fragment, is_fragment || !first_fragment; + } drop; +} +</code> + +<sect1>Differences for IPv6 Flowspec + +<p>Flowspec IPv6 are same as Flowspec IPv4 with a few exceptions. +<itemize> + <item>Prefixes <m/inet6/ can be specified not only with prefix length, + but with prefix <cf/offset/ <m/num/ too (e.g. + <cf>::1234:5678:9800:0000/101 offset 64</cf>). Offset means to don't + care of <m/num/ first bits. + <item>IPv6 Flowspec hasn't mandatory any flowspec component. + <item>In IPv6 packets, there is a matching the last next header value + for a matching IP protocol number (e.g. <cf>next header 6</cf>). + <item>It is not possible to set <cf>dont_fragment</cf> as a type of + packet fragmentation. +</itemize> + +<p><descrip> + <tag><label id="flow6-dst">dst <m/inet6/ [offset <m/num/]</tag> + Set a matching destination IPv6 prefix (e.g. <cf>dst + ::1c77:3769:27ad:a11a/128 offset 64</cf>). + + <tag><label id="flow6-src">src <m/inet6/ [offset <m/num/]</tag> + Set a matching source IPv6 prefix (e.g. <cf>src fe80::/64</cf>). + + <tag><label id="flow6-next-header">next header <m/numbers-match/</tag> + Set a matching IP protocol numbers (e.g. <cf>next header != 6</cf>). + + <tag><label id="flow6-label">label <m/bitmask-match/</tag> + Set a 20-bit bitmask for matching Flow Label field in IPv6 packets + (e.g. <cf>label 0x8e5/0x8e5</cf>). +</descrip> + +<p><code> +protocol static { + flow6; + + route flow6 { + dst fec0:1122:3344:5566:7788:99aa:bbcc:ddee/128; + src 0000:0000:0000:0001:1234:5678:9800:0000/101 offset 63; + next header = 23; + sport > 24 && < 30 || = 40 || 50,60,70..80; + dport = 50; + tcp flags 0x03/0x0f, !0/0xff || 0x33/0x33; + fragment !is_fragment || !first_fragment; + label 0xaaaa/0xaaaa && 0x33/0x33; + } drop; +} +</code> + <chapt>Remote control <label id="remote-control"> @@ -802,9 +936,8 @@ This argument can be omitted if there exists only a single instance. Show the list of symbols defined in the configuration (names of protocols, routing tables etc.). - <tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table <m/t/] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [<m/options/]</tag> - Show contents of a routing table (by default of the main one or the - table attached to a respective protocol), that is routes, their metrics + <tag><label id="cli-show-route">show route [[for] <m/prefix/|<m/IP/] [table (<m/t/ | all)] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [(stats|count)] [<m/options/]</tag> + Show contents of specified routing tables, that is routes, their metrics and (in case the <cf/all/ switch is given) all their attributes. <p>You can specify a <m/prefix/ if you want to print routes for a @@ -814,20 +947,31 @@ This argument can be omitted if there exists only a single instance. the selected one at the top, unless <cf/primary/ is given in which case only the selected route is shown. + <p>The <cf/show route/ command can process one or multiple routing + tables. The set of selected tables is determined on three levels: First, + tables can be explicitly selected by <cf/table/ switch, which could be + used multiple times, all tables are specified by <cf/table all/. Second, + tables can be implicitly selected by channels or protocols that are + arguments of several other switches (e.g., <cf/export/, <cf/protocol/). + Last, the set of default tables is used: <cf/master4/, <cf/master6/ and + each first table of any other network type. + <p>You can also ask for printing only routes processed and accepted by a given filter (<cf>filter <m/name/</cf> or <cf>filter { <m/filter/ } </cf> or matching a given condition (<cf>where <m/condition/</cf>). The <cf/export/, <cf/preexport/ and <cf/noexport/ switches ask for - printing of routes that are exported to the specified protocol. - With <cf/preexport/, the export filter of the protocol is skipped. - With <cf/noexport/, routes rejected by the export filter are printed - instead. Note that routes not exported to the protocol for other reasons + printing of routes that are exported to the specified protocol or + channel. With <cf/preexport/, the export filter of the channel is + skipped. With <cf/noexport/, routes rejected by the export filter are + printed instead. Note that routes not exported for other reasons (e.g. secondary routes or routes imported from that protocol) are not - printed even with <cf/noexport/. + printed even with <cf/noexport/. These switches also imply that + associated routing tables are selected instead of default ones. <p>You can also select just routes added by a specific protocol. - <cf>protocol <m/p/</cf>. + <cf>protocol <m/p/</cf>. This switch also implies that associated + routing tables are selected instead of default ones. <p>If BIRD is configured to keep filtered routes (see <cf/import keep filtered/ option), you can show them instead of routes by using @@ -837,27 +981,6 @@ This argument can be omitted if there exists only a single instance. number of networks, number of routes before and after filtering). If you use <cf/count/ instead, only the statistics will be printed. - <tag><label id="cli-show-roa">show roa [<m/prefix/ | in <m/prefix/ | for <m/prefix/] [as <m/num/] [table <m/t/]</tag> - Show contents of a ROA table (by default of the first one). You can - specify a <m/prefix/ to print ROA entries for a specific network. If you - use <cf>for <m/prefix/</cf>, you'll get all entries relevant for route - validation of the network prefix; i.e., ROA entries whose prefixes cover - the network prefix. Or you can use <cf>in <m/prefix/</cf> to get ROA - entries covered by the network prefix. You could also use <cf/as/ option - to show just entries for given AS. - - <tag><label id="cli-add-roa">add roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag> - Add a new ROA entry to a ROA table. Such entry is called <it/dynamic/ - compared to <it/static/ entries specified in the config file. These - dynamic entries survive reconfiguration. - - <tag><label id="cli-delete-roa">delete roa <m/prefix/ max <m/num/ as <m/num/ [table <m/t/]</tag> - Delete the specified ROA entry from a ROA table. Only dynamic ROA - entries (i.e., the ones added by <cf/add roa/ command) can be deleted. - - <tag><label id="cli-flush-roa">flush roa [table <m/t/]</tag> - Remove all dynamic ROA entries from a ROA table. - <tag><label id="cli-configure">configure [soft] ["<m/config file/"] [timeout [<m/num/]]</tag> Reload configuration from a given file. BIRD will smoothly switch itself to the new configuration, protocols are reconfigured if possible, @@ -1064,20 +1187,41 @@ foot). <tag><label id="type-ip">ip</tag> This type can hold a single IP address. Depending on the compile-time configuration of BIRD you are using, it is either an IPv4 or IPv6 - address. IP addresses are written in the standard notation + address; this may be checked by <cf>.is_ip4</cf> which returns <cf/bool/. + IP addresses are written in the standard notation (<cf/10.20.30.40/ or <cf/fec0:3:4::1/). You can apply special operator <cf>.mask(<M>num</M>)</cf> on values of type ip. It masks out all but first <cf><M>num</M></cf> bits from the IP address. So <cf/1.2.3.4.mask(8) = 1.0.0.0/ is true. <tag><label id="type-prefix">prefix</tag> - This type can hold a network prefix consisting of IP address and prefix - length. Prefix literals are written as <cf><m/ipaddress//<m/pxlen/</cf>, + This type can hold a network prefix consisting of IP address, prefix + length and several other values. This is the key in route tables. + + Prefixes may be of several types, which can be determined by the special + operator <cf/.type/. The type may be: + + <cf/NET_IP4/ and <cf/NET_IP6/ prefixes hold an IP prefix. The literals + are written as <cf><m/ipaddress//<m/pxlen/</cf>, or <cf><m>ipaddress</m>/<m>netmask</m></cf>. There are two special - operators on prefixes: <cf/.ip/ which extracts the IP address from the - pair, and <cf/.len/, which separates prefix length from the pair. + operators on IP prefixes: <cf/.ip/ which extracts the IP address from + the pair, and <cf/.len/, which separates prefix length from the pair. So <cf>1.2.0.0/16.len = 16</cf> is true. + <cf/NET_VPN4/ and <cf/NET_VPN6/ prefixes hold an IP prefix with VPN + Route Distinguisher (<rfc id="4364">). They support the same special + operators as IP prefixes, and also <cf/.rd/ which extracts the Route + Distinguisher. Their literals are written + as <cf><m/vpnrd/ <m/ipprefix/</cf> + + <cf/NET_ROA4/ and <cf/NET_ROA6/ prefixes hold an IP prefix range + together with an ASN. They support the same special operators as IP + prefixes, and also <cf/.maxlen/ which extracts maximal prefix length, + and <cf/.asn/ which extracts the ASN. + + <cf/NET_FLOW4/ and <cf/NET_FLOW6/ hold an IP prefix together with a + flowspec rule. Filters currently don't support flowspec parsing. + <tag><label id="type-ec">ec</tag> This is a specialized type used to represent BGP extended community values. It is essentially a 64bit value, literals of this type are @@ -1266,7 +1410,7 @@ foot). <cf/!˜/ membership operators) can be used to modify or test eclists, with ECs instead of pairs as arguments. - <tag/lclist/ + <tag><label id="type-lclist">lclist/</tag> Lclist is a data type used for BGP large community lists. Like eclists, lclists are very similar to clists, but they are sets of LCs instead of pairs. The same operations (like <cf/add/, <cf/delete/ or <cf/˜/ @@ -1467,13 +1611,12 @@ networks. Babel is conceptually very simple in its operation and "just works" in its default configuration, though some configuration is possible and in some cases desirable. -<p>While the Babel protocol is dual stack (i.e., can carry both IPv4 and IPv6 -routes over the same IPv6 transport), BIRD presently implements only the IPv6 -subset of the protocol. No Babel extensions are implemented, but the BIRD -implementation can coexist with implementations using the extensions (and will -just ignore extension messages). +<p>The Babel protocol is dual stack; i.e., it can carry both IPv4 and IPv6 +routes over the same IPv6 transport. For sending and receiving Babel packets, +only a link-local IPv6 address is needed. -<p>The Babel protocol implementation in BIRD is currently in alpha stage. +<p>BIRD does not implement any Babel extensions, but will coexist with +implementations using extensions (and will just ignore extension messages). <sect1>Configuration <label id="babel-config"> @@ -1486,6 +1629,7 @@ protocol babel [<name>] { interface <interface pattern> { type <wired|wireless>; rxcost <number>; + limit <number>; hello interval <number>; update interval <number>; port <number>; @@ -1494,29 +1638,42 @@ protocol babel [<name>] { rx buffer <number>; tx length <number>; check link <switch>; + next hop ipv4 <address>; + next hop ipv6 <address>; }; } </code> <descrip> <tag><label id="babel-type">type wired|wireless </tag> - This option specifies the interface type: Wired or wireless. Wired - interfaces are considered more reliable, and so the default hello - interval is higher, and a neighbour is considered unreachable after only - a small number of "hello" packets are lost. On wireless interfaces, - hello packets are sent more often, and the ETX link quality estimation - technique is used to compute the metrics of routes discovered over this - interface. This technique will gradually degrade the metric of routes - when packets are lost rather than the more binary up/down mechanism of - wired type links. Default: <cf/wired/. + This option specifies the interface type: Wired or wireless. On wired + interfaces a neighbor is considered unreachable after a small number of + Hello packets are lost, as described by <cf/limit/ option. On wireless + interfaces the ETX link quality estimation technique is used to compute + the metrics of routes discovered over this interface. This technique will + gradually degrade the metric of routes when packets are lost rather than + the more binary up/down mechanism of wired type links. Default: + <cf/wired/. <tag><label id="babel-rxcost">rxcost <m/num/</tag> - This specifies the RX cost of the interface. The route metrics will be - computed from this value with a mechanism determined by the interface - <cf/type/. Default: 96 for wired interfaces, 256 for wireless. + This option specifies the nominal RX cost of the interface. The effective + neighbor costs for route metrics will be computed from this value with a + mechanism determined by the interface <cf/type/. Note that in contrast to + other routing protocols like RIP or OSPF, the <cf/rxcost/ specifies the + cost of RX instead of TX, so it affects primarily neighbors' route + selection and not local route selection. Default: 96 for wired interfaces, + 256 for wireless. + + <tag><label id="babel-limit">limit <m/num/</tag> + BIRD keeps track of received Hello messages from each neighbor to + establish neighbor reachability. For wired type interfaces, this option + specifies how many of last 16 hellos have to be correctly received in + order to neighbor is assumed to be up. The option is ignored on wireless + type interfaces, where gradual cost degradation is used instead of sharp + limit. Default: 12. <tag><label id="babel-hello">hello interval <m/num/</tag> - Interval at which periodic "hello" messages are sent on this interface, + Interval at which periodic Hello messages are sent on this interface, in seconds. Default: 4 seconds. <tag><label id="babel-update">update interval <m/num/</tag> @@ -1551,6 +1708,18 @@ protocol babel [<name>] { routes received from them are withdrawn. It is possible that some hardware drivers or platforms do not implement this feature. Default: yes. + + <tag><label id="babel-next-hop-ipv4">next hop ipv4 <m/address/</tag> + Set the next hop address advertised for IPv4 routes advertised on this + interface. If not set, the first IPv4 address found on the interface will + be used, so it should only be necessary to set this option if this + auto-detection fails or finds the wrong address. + + <tag><label id="babel-next-hop-ipv6">next hop ipv6 <m/address/</tag> + Set the next hop address advertised for IPv6 routes advertised on this + interface. If not set, the same link-local address that is used as the + source for Babel packets will be used. In normal operation, it should not + be necessary to set this option. </descrip> <sect1>Attributes @@ -1579,7 +1748,12 @@ protocol babel { # configured on local interfaces, plus re-distribute all routes received # from other babel peers. - export where (source = RTS_DEVICE) || (source = RTS_BABEL); + ipv4 { + export where (source = RTS_DEVICE) || (source = RTS_BABEL); + }; + ipv6 { + export where (source = RTS_DEVICE) || (source = RTS_BABEL); + }; } </code> @@ -1825,17 +1999,39 @@ table it wishes to export along with complete path information (a list of AS'es the packet will travel through if it uses the particular route) in order to avoid routing loops. -<p>BIRD supports all requirements of the BGP4 standard as defined in -<rfc id="4271"> It also supports the community attributes (<rfc id="1997">), -capability negotiation (<rfc id="5492">), MD5 password authentication (<rfc -id="2385">), extended communities (<rfc id="4360">), route reflectors (<rfc -id="4456">), graceful restart (<rfc id="4724">), multiprotocol extensions -(<rfc id="4760">), 4B AS numbers (<rfc id="4893">), and 4B AS numbers in -extended communities (<rfc id="5668">). - +<sect1>Supported standards: +<label id="bgp-standards"> -For IPv6, it uses the standard multiprotocol extensions defined in -<rfc id="4760"> and applied to IPv6 according to <rfc id="2545">. +<itemize> +<item> <rfc id="4271"> - Border Gateway Protocol 4 (BGP) +<item> <rfc id="1997"> - BGP Communities Attribute +<item> <rfc id="2385"> - Protection of BGP Sessions via TCP MD5 Signature +<item> <rfc id="2545"> - Use of BGP Multiprotocol Extensions for IPv6 +<item> <rfc id="2918"> - Route Refresh Capability +<item> <rfc id="3107"> - Carrying Label Information in BGP +<item> <rfc id="4360"> - BGP Extended Communities Attribute +<item> <rfc id="4364"> - BGP/MPLS IPv4 Virtual Private Networks +<item> <rfc id="4456"> - BGP Route Reflection +<item> <rfc id="4486"> - Subcodes for BGP Cease Notification Message +<item> <rfc id="4659"> - BGP/MPLS IPv6 Virtual Private Networks +<item> <rfc id="4724"> - Graceful Restart Mechanism for BGP +<item> <rfc id="4760"> - Multiprotocol extensions for BGP +<item> <rfc id="4798"> - Connecting IPv6 Islands over IPv4 MPLS +<item> <rfc id="5065"> - AS confederations for BGP +<item> <rfc id="5082"> - Generalized TTL Security Mechanism +<item> <rfc id="5492"> - Capabilities Advertisement with BGP +<item> <rfc id="5549"> - Advertising IPv4 NLRI with an IPv6 Next Hop +<item> <rfc id="5575"> - Dissemination of Flow Specification Rules +<item> <rfc id="5668"> - 4-Octet AS Specific BGP Extended Community +<item> <rfc id="6286"> - AS-Wide Unique BGP Identifier +<item> <rfc id="6608"> - Subcodes for BGP Finite State Machine Error +<item> <rfc id="6793"> - BGP Support for 4-Octet AS Numbers +<item> <rfc id="7313"> - Enhanced Route Refresh Capability for BGP +<item> <rfc id="7606"> - Revised Error Handling for BGP UPDATE Messages +<item> <rfc id="7911"> - Advertisement of Multiple Paths in BGP +<item> <rfc id="7947"> - Internet Exchange BGP Route Server +<item> <rfc id="8092"> - BGP Large Communities Attribute +</itemize> <sect1>Route selection rules <label id="bgp-route-select-rules"> @@ -1924,6 +2120,16 @@ using the following configuration parameters: source address for the BGP session. Default: the address of the local end of the interface our neighbor is connected to. + <tag><label id="bgp-strict-bind">strict bind <m/switch/</tag> + Specify whether BGP listening socket should be bound to a specific local + address (the same as the <cf/source address/) and associated interface, + or to all addresses. Binding to a specific address could be useful in + cases like running multiple BIRD instances on a machine, each using its + IP address. Note that listening sockets bound to a specific address and + to all addresses collide, therefore either all BGP protocols (of the + same address family and using the same local port) should have set + <cf/strict bind/, or none of them. Default: disabled. + <tag><label id="bgp-next-hop-self">next hop self</tag> Avoid calculation of the Next Hop attribute and always advertise our own source address as a next hop. This needs to be used only occasionally to @@ -1996,7 +2202,7 @@ using the following configuration parameters: Note that full (ICMP protection, for example) <rfc id="5082"> support is provided by Linux only. Default: disabled. - <tag><label id="bgp-pass">password <m/string/</tag> + <tag><label id="bgp-password">password <m/string/</tag> Use this password for MD5 authentication of BGP sessions (<rfc id="2385">). When used on BSD systems, see also <cf/setkey/ option below. Default: no authentication. @@ -2017,6 +2223,21 @@ using the following configuration parameters: accepting incoming connections. In passive mode, outgoing connections are not initiated. Default: off. + <tag><label id="bgp-confederation">confederation <m/number/</tag> + BGP confederations (<rfc id="5065">) are collections of autonomous + systems that act as one entity to external systems, represented by one + confederation identifier (instead of AS numbers). This option allows to + enable BGP confederation behavior and to specify the local confederation + identifier. When BGP confederations are used, all BGP speakers that are + members of the BGP confederation should have the same confederation + identifier configured. Default: 0 (no confederation). + + <tag><label id="bgp-confederation-member">confederation member <m/switch/</tag> + When BGP confederations are used, this option allows to specify whether + the BGP neighbor is a member of the same confederation as the local BGP + speaker. The option is unnecessary (and ignored) for IBGP sessions, as + the same AS number implies the same confederation. Default: no. + <tag><label id="bgp-rr-client">rr client</tag> Be a route reflector and treat the neighbor as a route reflection client. Default: disabled. @@ -2147,13 +2368,6 @@ using the following configuration parameters: This option is relevant to IPv4 mode with enabled capability advertisement only. Default: on. - <tag><label id="bgp-route-limit">route limit <m/number/</tag> - The maximal number of routes that may be imported from the protocol. If - the route limit is exceeded, the connection is closed with an error. - Limit is currently implemented as <cf>import limit <m/number/ action - restart</cf>. This option is obsolete and it is replaced by - <ref id="proto-import-limit" name="import limit option">. Default: no limit. - <tag><label id="bgp-disable-after-error">disable after error <m/switch/</tag> When an error is encountered (either locally or by the other side), disable the instance automatically and wait for an administrator to fix @@ -2528,7 +2742,7 @@ limitations can be overcome using another routing table and the pipe protocol. routes from other sources (e.g. kernel device routes). Metric 0 has a special meaning of undefined metric, in which either OS default is used, or per-route metric can be set using <cf/krt_metric/ attribute. Default: - 0 (undefined). + 32. <tag><label id="krt-graceful-restart">graceful restart <m/switch/</tag> Participate in graceful restart recovery. If this option is enabled and @@ -2669,15 +2883,17 @@ each router detects all changes. <sect1>Configuration <label id="ospf-config"> -<p>In the main part of configuration, there can be multiple definitions of OSPF -areas, each with a different id. These definitions includes many other switches -and multiple definitions of interfaces. Definition of interface may contain many -switches and constant definitions and list of neighbors on nonbroadcast -networks. +<p>First, the desired OSPF version can be specified by using <cf/ospf v2/ or +<cf/ospf v3/ as a protocol type. By default, OSPFv2 is used. In the main part of +configuration, there can be multiple definitions of OSPF areas, each with a +different id. These definitions includes many other switches and multiple +definitions of interfaces. Definition of interface may contain many switches and +constant definitions and list of neighbors on nonbroadcast networks. <code> -protocol ospf <name> { +protocol ospf [v2|v3] <name> { rfc1583compat <switch>; + rfc5838 <switch>; instance id <num>; stub router <switch>; tick <num>; @@ -2778,15 +2994,23 @@ protocol ospf <name> { This option controls compatibility of routing table calculation with <rfc id="1583">. Default value is no. + <tag><label id="ospf-rfc5838">rfc5838 <m/switch/</tag> + Basic OSPFv3 is limited to IPv6 unicast routing. The <rfc id="5838"> + extension defines support for more address families (IPv4, IPv6, both + unicast and multicast). The extension is enabled by default, but can be + disabled if necessary, as it restricts the range of available instance + IDs. Default value is yes. + <tag><label id="ospf-instance-id">instance id <m/num/</tag> When multiple OSPF protocol instances are active on the same links, they should use different instance IDs to distinguish their packets. Although it could be done on per-interface basis, it is often preferred to set one instance ID to whole OSPF domain/topology (e.g., when multiple instances are used to represent separate logical topologies on the same - physical network). This option specifies the default instance ID for all - interfaces of the OSPF instance. Note that this option, if used, must - precede interface definitions. Default value is 0. + physical network). This option specifies the instance ID for all + interfaces of the OSPF instance, but can be overridden by + <cf/interface/ option. Default value is 0 unless OSPFv3-AF extended + address families are used, see <rfc id="5838"> for that case. <tag><label id="ospf-stub-router">stub router <M>switch</M></tag> This option configures the router to be a stub router, i.e., a router @@ -3680,10 +3904,12 @@ pretty much obsolete. It is still usable on very small networks. <label id="rip-config"> <p>RIP configuration consists mainly of common protocol options and interface -definitions, most RIP options are interface specific. +definitions, most RIP options are interface specific. RIPng (RIP for IPv6) +protocol instance can be configured by using <cf/rip ng/ instead of just +<cf/rip/ as a protocol type. <code> -protocol rip [<name>] { +protocol rip [ng] [<name>] { infinity <number>; ecmp <switch> [limit <number>]; interface <interface pattern> { @@ -3888,8 +4114,8 @@ protocol rip [<name>] { <p>RIP defines two route attributes: <descrip> - <tag><label id="rta-rip-metric">int rip_metric/</tag> - RIP metric of the route (ranging from 0 to <cf/infinity/). When routes + <tag>int <cf/rip_metric/</tag> + RIP metric of the route (ranging from 0 to <cf/infinity/). When routes from different RIP instances are available and all of them have the same preference, BIRD prefers the route with lowest <cf/rip_metric/. When a non-RIP route is exported to RIP, the default metric is 1. @@ -3920,6 +4146,184 @@ protocol rip { } </code> +<sect>RPKI + +<sect1>Introduction + +<p>The Resource Public Key Infrastructure (RPKI) is mechanism for origin +validation of BGP routes (RFC 6480). BIRD supports only so-called RPKI-based +origin validation. There is implemented RPKI to Router (RPKI-RTR) protocol (RFC +6810). It uses some of the RPKI data to allow a router to verify that the +autonomous system announcing an IP address prefix is in fact authorized to do +so. This is not crypto checked so can be violated. But it should prevent the +vast majority of accidental hijackings on the Internet today, e.g. the famous +Pakastani accidental announcement of YouTube's address space. + +<p>The RPKI-RTR protocol receives and maintains a set of ROAs from a cache +server (also called validator). You can validate routes (RFC 6483) using +function <cf/roa_check()/ in filter and set it as import filter at the BGP +protocol. BIRD should re-validate all of affected routes after RPKI update by +RFC 6811, but we don't support it yet! You can use a BIRD's client command +<cf>reload in <m/bgp_protocol_name/</cf> for manual call of revalidation of all +routes. + +<sect1>Supported transports +<itemize> + <item>Unprotected transport over TCP uses a port 323. The cache server + and BIRD router should be on the same trusted and controlled network + for security reasons. + <item>SSHv2 encrypted transport connection uses the normal SSH port + 22. +</itemize> + +<sect1>Configuration + +<p>We currently support just one cache server per protocol. However you can +define more RPKI protocols generally. + +<code> +protocol rpki [<name>] { + roa4 { table <tab>; }; + roa6 { table <tab>; }; + remote <ip> | "<domain>" [port <num>]; + port <num>; + refresh [keep] <num>; + retry [keep] <num>; + expire [keep] <num>; + transport tcp; + transport ssh { + bird private key "</path/to/id_rsa>"; + remote public key "</path/to/known_host>"; + user "<name>"; + }; +} +</code> + +<p>Alse note that you have to specify ROA table into which will be imported +routes from a cache server. If you want to import only IPv4 prefixes you have +to specify only roa4 table. Similarly with IPv6 prefixes only. If you want to +fetch both IPv4 and even IPv6 ROAs you have to specify both types of ROA +tables. + +<sect2>RPKI protocol options + +<descrip> + <tag>remote <m/ip/ | "<m/hostname/" [port <m/num/]</tag> Specifies + a destination address of the cache server. Can be specified by an IP + address or by full domain name string. Only one cache can be specified + per protocol. This option is required. + + <tag>port <m/num/</tag> Specifies the port number. The default port + number is 323 for transport without any encryption and 22 for transport + with SSH encryption. + + <tag>refresh [keep] <m/num/</tag> Time period in seconds. Tells how + long to wait before next attempting to poll the cache using a Serial + Query or a Reset Query packet. Must be lower than 86400 seconds (one + day). Too low value can caused a false positive detection of + network connection problems. A keyword <cf/keep/ suppresses updating + this value by a cache server. + Default: 3600 seconds + + <tag>retry [keep] <m/num/</tag> Time period in seconds between a failed + Serial/Reset Query and a next attempt. Maximum allowed value is 7200 + seconds (two hours). Too low value can caused a false positive + detection of network connection problems. A keyword <cf/keep/ + suppresses updating this value by a cache server. + Default: 600 seconds + + <tag>expire [keep] <m/num/</tag> Time period in seconds. Received + records are deleted if the client was unable to successfully refresh + data for this time period. Must be in range from 600 seconds (ten + minutes) to 172800 seconds (two days). A keyword <cf/keep/ + suppresses updating this value by a cache server. + Default: 7200 seconds + + <tag>transport tcp</tag> Unprotected transport over TCP. It's a default + transport. Should be used only on secure private networks. + Default: tcp + + <tag>transport ssh { <m/SSH transport options.../ }</tag> It enables a + SSHv2 transport encryption. Cannot be combined with a TCP transport. + Default: off +</descrip> + +<sect3>SSH transport options +<descrip> + <tag>bird private key "<m>/path/to/id_rsa</m>"</tag> + A path to the BIRD's private SSH key for authentication. + It can be a <cf><m>id_rsa</m></cf> file. + + <tag>remote public key "<m>/path/to/known_host</m>"</tag> + A path to the cache's public SSH key for verification identity + of the cache server. It could be a path to <cf><m>known_host</m></cf> file. + + <tag>user "<m/name/"</tag> + A SSH user name for authentication. This option is a required. +</descrip> + +<sect1>Examples +<sect2>BGP origin validation +<p>Policy: Don't import <cf/ROA_INVALID/ routes. +<code> +roa4 table r4; +roa6 table r6; + +protocol rpki { + debug all; + + roa4 { table r4; }; + roa6 { table r6; }; + + # Please, do not use rpki-validator.realmv6.org in production + remote "rpki-validator.realmv6.org" port 8282; + + retry keep 5; + refresh keep 30; + expire 600; +} + +filter peer_in { + if (roa_check(r4, net, bgp_path.last) = ROA_INVALID || + roa_check(r6, net, bgp_path.last) = ROA_INVALID) then + { + print "Ignore invalid ROA ", net, " for ASN ", bgp_path.last; + reject; + } + accept; +} + +protocol bgp { + debug all; + local as 65000; + neighbor 192.168.2.1 as 65001; + import filter peer_in; +} +</code> + +<sect2>SSHv2 transport encryption +<code> +roa4 table r4; +roa6 table r6; + +protocol rpki { + debug all; + + roa4 { table r4; }; + roa6 { table r6; }; + + remote 127.0.0.1 port 2345; + transport ssh { + bird private key "/home/birdgeek/.ssh/id_rsa"; + remote public key "/home/birdgeek/.ssh/known_hosts"; + user "birdgeek"; + }; + + # Default interval values +} +</code> + + <sect>Static <label id="static"> @@ -3932,12 +4336,12 @@ return packets as undeliverable if they are in your IP block, you don't have any specific destination for them and you don't want to send them out through the default route to prevent routing loops). -<p>There are five types of static routes: `classical' routes telling to forward -packets to a neighboring router, multipath routes specifying several (possibly -weighted) neighboring routers, device routes specifying forwarding to hosts on a -directly connected network, recursive routes computing their nexthops by doing -route table lookups for a given IP, and special routes (sink, blackhole etc.) -which specify a special action to be done instead of forwarding the packet. +<p>There are four types of static routes: `classical' routes telling to forward +packets to a neighboring router (single path or multipath, possibly weighted), +device routes specifying forwarding to hosts on a directly connected network, +recursive routes computing their nexthops by doing route table lookups for a +given IP, and special routes (sink, blackhole etc.) which specify a special +action to be done instead of forwarding the packet. <p>When the particular destination is not available (the interface is down or the next hop of the route is not a neighbor at the moment), Static just @@ -3966,14 +4370,14 @@ definition of the protocol contains mainly a list of static routes. <p>Route definitions (each may also contain a block of per-route options): <descrip> - <tag><label id="static-route-via-ip">route <m/prefix/ via <m/ip/</tag> - Static route through a neighboring router. For link-local next hops, + <tag><label id="static-route-via-ip">route <m/prefix/ via <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]]</tag> + Static single path route through a neighboring router. For link-local next hops, interface can be specified as a part of the address (e.g., - <cf/via fe80::1234%eth0/). + <cf/via fe80::1234%eth0/). MPLS labels should be specified in outer-first order. - <tag><label id="static-route-via-mpath">route <m/prefix/ multipath via <m/ip/ [weight <m/num/] [bfd <m/switch/] [via <m/.../]</tag> + <tag><label id="static-route-via-mpath">route <m/prefix/ via <m/ip/ [mpls <m/num/[/<m/num/[/<m/num/[...]]]] [weight <m/num/] [bfd <m/switch/] [via ...]</tag> Static multipath route. Contains several nexthops (gateways), possibly - with their weights. + with their weights and MPLS labels. <tag><label id="static-route-via-iface">route <m/prefix/ via <m/"interface"/</tag> Static device route through an interface to hosts on a directly |