diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/bird.sgml | 353 | ||||
| -rw-r--r-- | doc/prog-head.sgml | 2 | ||||
| -rw-r--r-- | doc/reply_codes | 1 | ||||
| -rw-r--r-- | doc/roadmap.md | 307 |
4 files changed, 597 insertions, 66 deletions
diff --git a/doc/bird.sgml b/doc/bird.sgml index 5cf09bfe..3f6acaed 100644 --- a/doc/bird.sgml +++ b/doc/bird.sgml @@ -14,7 +14,7 @@ configuration - something in config which is not keyword. (set-fill-column 80) - Copyright 1999,2000 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later. + Copyright 1999 - 2022 CZ.NIC, z.s.p.o , distribute under GPL version 2 or later. --> @@ -144,13 +144,6 @@ BIRD executable by configuring out routing protocols you don't use, and <p>You can pass several command-line options to bird: <descrip> - <tag><label id="argv-block">-B <m/exp/</tag> - allocate memory using 2^<cf/exp/ byte sized blocks; - if you're expecting high memory load, raise this to - reduce number of allocated memory pages. For a million routes - in one table, the recommended setting is 18. - Default is your system page size, typically 12 for 4096 bytes. - <tag><label id="argv-config">-c <m/config name/</tag> use given configuration file instead of <it/prefix/<file>/etc/bird.conf</file>. @@ -258,16 +251,9 @@ The global best route selection algorithm is (roughly) as follows: </itemize> <p><label id="dsc-table-sorted">Usually, a routing table just chooses a selected -route from a list of entries for one network. But if the <cf/sorted/ option is -activated, these lists of entries are kept completely sorted (according to -preference or some protocol-dependent metric). This is needed for some features -of some protocols (e.g. <cf/secondary/ option of BGP protocol, which allows to -accept not just a selected route, but the first route (in the sorted list) that -is accepted by filters), but it is incompatible with some other features (e.g. -<cf/deterministic med/ option of BGP protocol, which activates a way of choosing -selected route that cannot be described using comparison and ordering). Minor -advantage is that routes are shown sorted in <cf/show route/, minor disadvantage -is that it is slightly more computationally expensive. +route from a list of entries for one network. Optionally, these lists of entries +are kept completely sorted (according to preference or some protocol-dependent +metric). See <ref id="rtable-sorted" name="sorted"> table option for details. <sect>Routes and network types <label id="routes"> @@ -519,6 +505,11 @@ include "tablename.conf";; See <ref id="channel-debug" name="debug"> in the channel section. Default: off. + <tag><label id="opt-debug-tables">debug tables all|off|{ states|routes|filters|events [, <m/.../] }</tag> + Set global defaults of table debugging options. + See <ref id="rtable-debug" name="debug"> in the table section. + Default: off. + <tag><label id="opt-debug-commands">debug commands <m/number/</tag> Control logging of client connections (0 for no logging, 1 for logging of connects and disconnects, 2 and higher for logging of all client @@ -541,6 +532,12 @@ include "tablename.conf";; killed by abort signal. The timeout has effective granularity of seconds, zero means disabled. Default: disabled (0). + <tag><label id="opt-threads">threads <m/number/</tag> + Set how many worker threads should BIRD spawn. Tests show that every + thread can utilize one complete CPU core, therefore you probably want to + keep at least one free core. The maximum feasible thread count heavily + depends on the actual workload and must be determined by testing or estimation. Default: 1 + <tag><label id="opt-mrtdump">mrtdump "<m/filename/"</tag> Set MRTdump file name. This option must be specified to allow MRTdump feature. Default: no dump file. @@ -634,18 +631,107 @@ include "tablename.conf";; <cf/protocol/ times, and the <cf/iso long ms/ format for <cf/base/ and <cf/log/ times. - <tag><label id="opt-table"><m/nettype/ table <m/name/ [sorted]</tag> - Create a new routing table. The default routing tables <cf/master4/ and - <cf/master6/ are created implicitly, other routing tables have to be - added by this command. Option <cf/sorted/ can be used to enable sorting - of routes, see <ref id="dsc-table-sorted" name="sorted table"> - description for details. + <tag><label id="opt-table"><m/nettype/ table <m/name/ [ { <m/option/; [<m/.../] } ]</tag> + Define a new routing table. The default routing tables <cf/master4/ and + <cf/master6/ are defined implicitly, other routing tables have to be + defined by this option. See the <ref id="rtable-opts" + name="routing table configuration section"> for routing table options. <tag><label id="opt-eval">eval <m/expr/</tag> Evaluates given filter expression. It is used by the developers for testing of filters. </descrip> +<sect>Routing table options +<label id="rtable-opts"> + +<p>Most routing tables do not need any options and are defined without an option +block, but there are still some options to tweak routing table behavior. Note +that implicit tables (<cf/master4/ and <cf/master6/) can be redefined in order +to set options. + +<descrip> + <tag><label id="rtable-sorted">sorted <m/switch/</tag> + Usually, a routing table just chooses the selected (best) route from a + list of routes for each network, while keeping remaining routes unsorted. + If enabled, these lists of routes are kept completely sorted (according + to preference or some protocol-dependent metric). + + This is needed for some protocol features (e.g. <cf/secondary/ option of + BGP protocol, which allows to accept not just a selected route, but the + first route (in the sorted list) that is accepted by filters), but it is + incompatible with some other features (e.g. <cf/deterministic med/ + option of BGP protocol, which activates a way of choosing selected route + that cannot be described using comparison and ordering). Minor advantage + is that routes are shown sorted in <cf/show route/, minor disadvantage + is that it is slightly more computationally expensive. Default: off. + + <tag><label id="rtable-trie">trie <m/switch/</tag> + BIRD routing tables are implemented with hash tables, which is efficient + for exact-match lookups, but inconvenient for longest-match lookups or + interval lookups (finding superprefix or subprefixes). This option + activates additional trie structure that is used to accelerate these + lookups, while using the hash table for exact-match lookups. + + This has advantage for <ref id="rpki" name="RPKI"> (on ROA tables), + for <ref id="bgp-gateway" name="recursive next-hops"> (on IGP tables), + and is required for <ref id="bgp-validate" name="flowspec validation"> + (on base IP tables). Another advantage is that interval results (like + from <cf/show route in .../ command) are lexicographically sorted. The + disadvantage is that trie-enabled routing tables require more memory, + which may be an issue especially in multi-table setups. Default: off. + + <tag><label id="rtable-gc-threshold">gc threshold <m/number/</tag> + Specify a minimum amount of removed networks that triggers a garbage + collection (GC) cycle. Default: 1000. + + <tag><label id="rtable-gc-period">gc period <m/time/</tag> + Specify a period of time between consecutive GC cycles. When there is a + significant amount of route withdraws, GC cycles are executed repeatedly + with given period time (with some random factor). When there is just + small amount of changes, GC cycles are not executed. In extensive route + server setups, running GC on hundreds of full BGP routing tables can + take significant amount of time, therefore they should use higher GC + periods. Default: adaptive, based on number of routing tables in the + configuration. From 10 s (with <= 25 routing tables) up to 600 s (with + >= 1500 routing tables). + + <tag><label id="rtable-cork-threshold">cork threshold <m/number/ <m/number/</tag> + Too many pending exports may lead to memory bloating. In such cases, + BIRD tries to relieve the memory pressure by pausing some routines until + the queue sizes get low enough. This option allows the user to set the + thresholds; first value is the low threshold (when to resume), the + second one is the high threshold (when to pause). The higher is the + threshold, the more memory can get used. In most cases, the defaults + should work for you. Default: 1024 8192. + + <tag><label id="rtable-export-settle-time">export settle time <m/time/ <m/time/</tag> + Minimum and maximum settle times, respectively, for export announcements. + When multiple routes are changing, this mechanism waits for the changes + to settle before waking up sleeping export threads but if the changes are coming + steadily, BIRD isn't waiting forever; at most the maximum time. + Default values: <cf/1 ms 100 ms/. You have to always provide both values. + + <tag><label id="rtable-route-refresh-export-settle-time">route refresh export settle time <m/time/ <m/time/</tag> + Minimum and maximum settle times, respectively, for export announcements + (the same as above), valid when any channel is currently doing a route refresh. + This serves a purpose of even more aggresive change bundling, knowing that there + is some active process generating changes in a fast pace. If you don't want + this feature, set this to the same values as <ref id="rtable-export-settle-time" name="export settle time">. + Default values: <cf/100 ms 3 s/. + + <tag><label id="rtable-debug">debug all|off|{ states|routes|events [, <m/.../] }</tag> + Set table debugging options. Each table can write some trace messages + into log with category <cf/trace/. You can request <cf/all/ trace messages + or select some types: <cf/states/ for table state changes and auxiliary + processes, <cf/routes/ for auxiliary route notifications (next hop update, + flowspec revalidation) and <cf/events/ for more detailed auxiliary routine + debug. See also <ref id="channel-debug" name="channel debugging option">. + Default: off. + +</descrip> + + <sect>Protocol options <label id="protocol-opts"> @@ -873,10 +959,12 @@ inherited from templates can be updated by new definitions. <cf/none/ is for dropping all routes. Default: <cf/all/ (except for EBGP). - <tag><label id="proto-export">export <m/filter/</tag> + <tag><label id="proto-export">export [ in <m/prefix/ ] <m/filter/</tag> This is similar to the <cf>import</cf> keyword, except that it works in - the direction from the routing table to the protocol. Default: <cf/none/ - (except for EBGP). + the direction from the routing table to the protocol. If <cf/in/ keyword is used, + only routes inside the given prefix are exported. Other routes are completely + ignored (e.g. no logging and no statistics). + Default: <cf/none/ (except for EBGP). <tag><label id="proto-import-keep-filtered">import keep filtered <m/switch/</tag> Usually, if an import filter rejects a route, the route is forgotten. @@ -898,6 +986,16 @@ inherited from templates can be updated by new definitions. <ref id="bgp-export-table" name="export table"> (for respective direction). Default: on. + <tag><label id="rtable-min-settle-time">roa settle time <m/time/ <m/time/</tag> + Minimum and maximum settle times, respectively, for ROA table changes. + The automatic reload is triggered after the minimum time after the last + ROA table change has been received but not later than the maximum time after + first unprocessed ROA table change. Therefore with default values, the + automatic reload happens 1 second after the ROA table stops updating, yet if it + were to be later than 20 seconds after the ROA table starts updating, + the automatic reload is triggered anyway. Default values: <cf/1 s 20 s/. + You have to always provide both values. + <tag><label id="proto-import-limit">import limit [<m/number/ | off ] [action warn | block | restart | disable]</tag> Specify an import route limit (a maximum number of routes imported from the protocol) and optionally the action to be taken when the limit is @@ -1057,14 +1155,16 @@ 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/ | all)] [filter <m/f/|where <m/c/] [(export|preexport|noexport) <m/p/] [protocol <m/p/] [(stats|count)] [<m/options/]</tag> + <tag><label id="cli-show-route">show route [[(for|in)] <m/prefix/|for <m/IP/] [table (<m/t/|all)] [(import|export) table <m/p/.<m/c/] [filter <m/f/|where <m/cond/] [(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 specific network. If you use <cf>for <m/prefix or IP/</cf>, you'll get the entry which will be used for forwarding of packets to the given - destination. By default, all routes for each network are printed with + destination. Finally, if you use <cf>in <m/prefix/</cf>, you get all + prefixes covered by the given prefix. + By default, all routes for each network are printed with the selected one at the top, unless <cf/primary/ is given in which case only the selected route is shown. @@ -1077,6 +1177,11 @@ This argument can be omitted if there exists only a single instance. Last, the set of default tables is used: <cf/master4/, <cf/master6/ and each first table of any other network type. + <p>There are internal tables when <cf/(import|export) table/ options + are used for some channels. They can be selected explicitly with + <cf/(import|export) table/ switch, specifying protocol <m/p/ and + channel name <m/c/. + <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>). @@ -1112,6 +1217,11 @@ This argument can be omitted if there exists only a single instance. restarted otherwise. Changes in filters usually lead to restart of affected protocols. + The previous configuration is saved and the user can switch back to it + with <ref id="cli-configure-undo" name="configure undo"> command. The + old saved configuration is released (even if the reconfiguration attempt + fails due to e.g. a syntax error). + If <cf/soft/ option is used, changes in filters does not cause BIRD to restart affected protocols, therefore already accepted routes (according to old filters) would be still propagated, but new routes would be @@ -1204,8 +1314,8 @@ this: <code> filter not_too_far -int var; { + int var; if defined( rip_metric ) then var = rip_metric; else { @@ -1234,9 +1344,9 @@ local variables. Recursion is not allowed. Function definitions look like this: <code> function name () -int local_variable; { - local_variable = 5; + int local_variable; + int another_variable = 5; } function with_parameters (int parameter) @@ -1245,16 +1355,19 @@ function with_parameters (int parameter) } </code> -<p>Unlike in C, variables are declared after the <cf/function/ line, but before -the first <cf/{/. You can't declare variables in nested blocks. Functions are -called like in C: <cf>name(); with_parameters(5);</cf>. Function may return -values using the <cf>return <m/[expr]/</cf> command. Returning a value exits -from current function (this is similar to C). +<p>Like in C programming language, variables are declared inside function body, +either at the beginning, or mixed with other statements. Declarations may +contain initialization. You can also declare variables in nested blocks, such +variables have scope restricted to such block. There is a deprecated syntax to +declare variables after the <cf/function/ line, but before the first <cf/{/. +Functions are called like in C: <cf>name(); with_parameters(5);</cf>. Function +may return values using the <cf>return <m/[expr]/</cf> command. Returning a +value exits from current function (this is similar to C). -<p>Filters are defined in a way similar to functions except they can't have +<p>Filters are defined in a way similar to functions except they cannot have explicit parameters. They get a route table entry as an implicit parameter, it is also passed automatically to any functions called. The filter must terminate -with either <cf/accept/ or <cf/reject/ statement. If there's a runtime error in +with either <cf/accept/ or <cf/reject/ statement. If there is a runtime error in filter, the route is rejected. <p>A nice trick to debug filters is to use <cf>show route filter <m/name/</cf> @@ -1624,7 +1737,8 @@ prefix and an ASN as arguments. <sect>Control structures <label id="control-structures"> -<p>Filters support two control structures: conditions and case switches. +<p>Filters support several control structures: conditions, for loops and case +switches. <p>Syntax of a condition is: <cf>if <M>boolean expression</M> then <m/commandT/; else <m/commandF/;</cf> and you can use <cf>{ <m/command1/; <m/command2/; @@ -1632,6 +1746,14 @@ else <m/commandF/;</cf> and you can use <cf>{ <m/command1/; <m/command2/; omitted. If the <cf><m>boolean expression</m></cf> is true, <m/commandT/ is executed, otherwise <m/commandF/ is executed. +<p>For loops allow to iterate over elements in compound data like BGP paths or +community lists. The syntax is: <cf>for [ <m/type/ ] <m/variable/ in <m/expr/ +do <m/command/;</cf> and you can also use compound command like in conditions. +The expression is evaluated to a compound data, then for each element from such +data the command is executed with the item assigned to the variable. A variable +may be an existing one (when just name is used) or a locally defined (when type +and name is used). In both cases, it must have the same type as elements. + <p>The <cf>case</cf> is similar to case from Pascal. Syntax is <cf>case <m/expr/ { else: | <m/num_or_prefix [ .. num_or_prefix]/: <m/statement/ ; [ ... ] }</cf>. The expression after <cf>case</cf> can be of any type which can be @@ -1644,16 +1766,21 @@ neither of the <cf/:/ clauses, the statements after <cf/else:/ are executed. <p>Here is example that uses <cf/if/ and <cf/case/ structures: <code> +if 1234 = i then printn "."; else { + print "not 1234"; + print "You need {} around multiple commands"; +} + +for int asn in bgp_path do { + printn "ASN: ", asn; + if asn < 65536 then print " (2B)"; else print " (4B)"; +} + case arg1 { 2: print "two"; print "I can do more commands without {}"; 3 .. 5: print "three to five"; else: print "something else"; } - -if 1234 = i then printn "."; else { - print "not 1234"; - print "You need {} around multiple commands"; -} </code> @@ -1682,17 +1809,8 @@ Common route attributes are: primary key of the routing table. Read-only. (See the <ref id="routes" name="chapter about routes">.) - <tag><label id="rta-scope"><m/enum/ scope</tag> - The scope of the route. Possible values: <cf/SCOPE_HOST/ for routes - local to this host, <cf/SCOPE_LINK/ for those specific for a physical - link, <cf/SCOPE_SITE/ and <cf/SCOPE_ORGANIZATION/ for private routes and - <cf/SCOPE_UNIVERSE/ for globally visible routes. This attribute is not - interpreted by BIRD and can be used to mark routes in filters. The - default value for new routes is <cf/SCOPE_UNIVERSE/. - <tag><label id="rta-preference"><m/int/ preference</tag> - Preference of the route. Valid values are 0-65535. (See the chapter - about routing tables.) + Preference of the route. <tag><label id="rta-from"><m/ip/ from</tag> The router which the route has originated from. @@ -1794,7 +1912,7 @@ protocol sections. <label id="babel-intro"> <p>The Babel protocol -(<rfc id="6126">) is a loop-avoiding distance-vector routing protocol that is +(<rfc id="8966">) is a loop-avoiding distance-vector routing protocol that is robust and efficient both in ordinary wired networks and in wireless mesh networks. Babel is conceptually very simple in its operation and "just works" in its default configuration, though some configuration is possible and in some @@ -1838,6 +1956,7 @@ protocol babel [<name>] { check link <switch>; next hop ipv4 <address>; next hop ipv6 <address>; + extended next hop <switch>; authentication none|mac [permissive]; password "<text>"; password "<text>" { @@ -1942,6 +2061,11 @@ protocol babel [<name>] { source for Babel packets will be used. In normal operation, it should not be necessary to set this option. + <tag><label id="babel-extended-next-hop">extended next hop <m/switch/</tag> + If enabled, BIRD will accept and emit IPv4 routes with an IPv6 next + hop when IPv4 addresses are absent from the interface as described in + <rfc id="9229">. Default: yes. + <tag><label id="babel-authentication">authentication none|mac [permissive]</tag> Selects authentication method to be used. <cf/none/ means that packets are not authenticated at all, <cf/mac/ means MAC authentication is @@ -2112,6 +2236,13 @@ protocol bfd [<name>] { to configure separate BFD protocol instances for IPv4 and for IPv6 sessions. + <tag><label id="bfd-strict-bind">strict bind <m/switch/</tag> + Specify whether each BFD interface should use a separate listening + socket bound to its local address, or just use a shared listening socket + accepting all addresses. Binding to a specific address could be useful + in cases like running multiple BIRD instances on a machine, each + handling a different set of interfaces. Default: disabled. + <tag><label id="bfd-iface">interface <m/pattern/ [, <m/.../] { <m/options/ }</tag> Interface definitions allow to specify options for sessions associated with such interfaces and also may contain interface specific options. @@ -2296,6 +2427,10 @@ avoid routing loops. <item> <rfc id="8092"> - BGP Large Communities Attribute <item> <rfc id="8203"> - BGP Administrative Shutdown Communication <item> <rfc id="8212"> - Default EBGP Route Propagation Behavior without Policies +<item> <rfc id="8654"> - Extended Message Support for BGP +<item> <rfc id="9072"> - Extended Optional Parameters Length for BGP OPEN Message +<item> <rfc id="9117"> - Revised Validation Procedure for BGP Flow Specifications +<item> <rfc id="9234"> - Route Leak Prevention and Detection Using Roles </itemize> <sect1>Route selection rules @@ -2515,12 +2650,19 @@ using the following configuration parameters: keeps MED attribute). Default: disabled. <tag><label id="bgp-allow-local-pref">allow bgp_local_pref <m/switch/</tag> - A standard BGP implementation do not send the Local Preference attribute - to eBGP neighbors and ignore this attribute if received from eBGP + Standard BGP implementations do not send the Local Preference attribute + to EBGP neighbors and ignore this attribute if received from EBGP neighbors, as per <rfc id="4271">. When this option is enabled on an - eBGP session, this attribute will be sent to and accepted from the peer, + EBGP session, this attribute will be sent to and accepted from the peer, which is useful for example if you have a setup like in <rfc id="7938">. - The option does not affect iBGP sessions. Default: off. + The option does not affect IBGP sessions. Default: off. + + <tag><label id="bgp-allow-med">allow bgp_med <m/switch/</tag> + Standard BGP implementations do not propagate the MULTI_EXIT_DESC + attribute unless it is configured locally. When this option is enabled + on an EBGP session, this attribute will be sent to the peer regardless, + which is useful for example if you have a setup like in <rfc id="7938">. + The option does not affect IBGP sessions. Default: off. <tag><label id="bgp-allow-local-as">allow local as [<m/number/]</tag> BGP prevents routing loops by rejecting received routes with the local @@ -2658,9 +2800,16 @@ using the following configuration parameters: <tag><label id="bgp-hold-time">hold time <m/number/</tag> Time in seconds to wait for a Keepalive message from the other side - before considering the connection stale. Default: depends on agreement - with the neighboring router, we prefer 240 seconds if the other side is - willing to accept it. + before considering the connection stale. The effective value is + negotiated during session establishment and it is a minimum of this + configured value and the value proposed by the peer. The zero value has + a special meaning, signifying that no keepalives are used. Default: 240 + seconds. + + <tag><label id="bgp-min-hold-time">min hold time <m/number/</tag> + Minimum value of the hold time that is accepted during session negotiation. + If the peer proposes a lower value, the session is rejected with error. + Default: none. <tag><label id="bgp-startup-hold-time">startup hold time <m/number/</tag> Value of the hold timer used before the routers have a chance to exchange @@ -2668,8 +2817,15 @@ using the following configuration parameters: <tag><label id="bgp-keepalive-time">keepalive time <m/number/</tag> Delay in seconds between sending of two consecutive Keepalive messages. + The effective value depends on the negotiated hold time, as it is scaled + to maintain proportion between the keepalive time and the hold time. Default: One third of the hold time. + <tag><label id="bgp-min-keepalive-time">min keepalive time <m/number/</tag> + Minimum value of the keepalive time that is accepted during session + negotiation. If the proposed hold time would lead to a lower value of + the keepalive time, the session is rejected with error. Default: none. + <tag><label id="bgp-connect-delay-time">connect delay time <m/number/</tag> Delay in seconds between protocol startup and the first attempt to connect. Default: 5 seconds. @@ -2680,7 +2836,7 @@ using the following configuration parameters: <tag><label id="bgp-error-wait-time">error wait time <m/number/,<m/number/</tag> Minimum and maximum delay in seconds between a protocol failure (either - local or reported by the peer) and automatic restart. Doesn't apply + local or reported by the peer) and automatic restart. Doesn not apply when <cf/disable after error/ is configured. If consecutive errors happen, the delay is increased exponentially until it reaches the maximum. Default: 60, 300. @@ -2736,6 +2892,29 @@ using the following configuration parameters: protocol itself (for example, if a route is received through eBGP and therefore does not have such attribute). Default: 100 (0 in pre-1.2.0 versions of BIRD). + + <tag><label id="bgp-local-role">local role <m/role-name/</tag> + BGP roles are a mechanism for route leak prevention and automatic route + filtering based on common BGP topology relationships. They are defined + in <rfc id="9234">. Instead of manually configuring filters and + communities, automatic filtering is done with the help of the OTC + attribute - a flag for routes that should be sent only to customers. + The same attribute is also used to automatically detect and filter route + leaks created by third parties. + + This option is valid for EBGP sessions, but it is not recommended to be + used within AS confederations (which would require manual filtering of + <cf/bgp_otc/ attribute on confederation boundaries). + + Possible <cf><m/role-name/</cf> values are: <cf/provider/, + <cf/rs_server/, <cf/rs_client/, <cf/customer/ and <cf/peer/. + Default: No local role assigned. + + <tag><label id="bgp-require-roles">require roles <m/switch/</tag> + If this option is set, the BGP roles must be defined on both sides, + otherwise the session will not be established. This behavior is defined + in <rfc id="9234"> as "strict mode" and is used to enforce corresponding + configuration at your conterpart side. Default: disabled. </descrip> <sect1>Channel configuration @@ -2806,6 +2985,20 @@ be used in explicit configuration. BGP session (if acceptable), or the preferred address of an associated interface. + <tag><label id="bgp-next-hop-prefer">next hop prefer global</tag> + Prefer global IPv6 address to link-local IPv6 address for immediate next + hops of received routes. For IPv6 routes, the Next Hop attribute may + contain both a global IP address and a link-local IP address. For IBGP + sessions, the global IP address is resolved (<ref id="bgp-gateway" + name="gateway recursive">) through an IGP routing table + (<ref id="bgp-igp-table" name="igp table">) to get an immediate next + hop. If the resulting IGP route is a direct route (i.e., the next hop is + a direct neighbor), then the link-local IP address from the Next Hop + attribute is used as the immediate next hop. This option change it to + use the global IP address instead. Note that even with this option + enabled a route may end with a link-local immediate next hop when the + IGP route has one. Default: disabled. + <tag><label id="bgp-gateway">gateway direct|recursive</tag> For received routes, their <cf/gw/ (immediate next hop) attribute is computed from received <cf/bgp_next_hop/ attribute. This option @@ -2858,6 +3051,31 @@ be used in explicit configuration. explicitly (to conserve memory). This option requires that the connected routing table is <ref id="dsc-table-sorted" name="sorted">. Default: off. + <tag><label id="bgp-validate">validate <m/switch/</tag> + Apply flowspec validation procedure as described in <rfc id="8955"> + section 6 and <rfc id="9117">. The Validation procedure enforces that + only routers in the forwarding path for a network can originate flowspec + rules for that network. The validation procedure should be used for EBGP + to prevent injection of malicious flowspec rules from outside, but it + should also be used for IBGP to ensure that selected flowspec rules are + consistent with selected IP routes. The validation procedure uses an IP + routing table (<ref id="bgp-base-table" name="base table">, see below) + against which flowspec rules are validated. This option is limited to + flowspec channels. Default: off (for compatibility reasons). + + Note that currently the flowspec validation does not work reliably + together with <ref id="bgp-import-table" name="import table"> option + enabled on flowspec channels. + + <tag><label id="bgp-base-table">base table <m/name/</tag> + Specifies an IP table used for the flowspec validation procedure. The + table must have enabled <cf/trie/ option, otherwise the validation + procedure would not work. The type of the table must be <cf/ipv4/ for + <cf/flow4/ channels and <cf/ipv6/ for <cf/flow6/ channels. This option + is limited to flowspec channels. Default: the main table of the + <cf/ipv4/ / <cf/ipv6/ channel of the same BGP instance, or the + <cf/master4/ / <cf/master6/ table if there is no such channel. + <tag><label id="bgp-extended-next-hop">extended next hop <m/switch/</tag> BGP expects that announced next hops have the same address family as associated network prefixes. This option provides an extension to use @@ -3018,6 +3236,11 @@ some of them (marked with `<tt/O/') are optional. This attribute contains accumulated IGP metric, which is a total distance to the destination through multiple autonomous systems. Currently, the attribute is not accessible from filters. + + <tag><label id="bgp-otc">int bgp_otc [O]</tag> + This attribute is defined in <rfc id="9234">. OTC is a flag that marks + routes that should be sent only to customers. If <ref id="bgp-role" + name="local Role"> is configured it set automatically. </descrip> <sect1>Example @@ -5185,7 +5408,7 @@ Note that for negated matches, value must be either zero or equal to bitmask <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>). + Set a matching 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>). diff --git a/doc/prog-head.sgml b/doc/prog-head.sgml index 43ee4ef6..4daca3a3 100644 --- a/doc/prog-head.sgml +++ b/doc/prog-head.sgml @@ -12,9 +12,9 @@ <title>BIRD Programmer's Documentation <author> Ondrej Filip <it/<feela@network.cz>/, -Maria Matejka <it/<mq@jmq.cz>/, Martin Mares <it/<mj@ucw.cz>/, Ondrej Zajicek <it/<santiago@crfreenet.org>/ +Maria Matejka <it/<mq@jmq.cz>/, </author> <abstract> diff --git a/doc/reply_codes b/doc/reply_codes index 02f4e656..bcbbbb03 100644 --- a/doc/reply_codes +++ b/doc/reply_codes @@ -61,6 +61,7 @@ Reply codes of BIRD command-line interface 1023 Show Babel interfaces 1024 Show Babel neighbors 1025 Show Babel entries +1026 Show threads 8000 Reply too long 8001 Route not found diff --git a/doc/roadmap.md b/doc/roadmap.md new file mode 100644 index 00000000..f6b9d475 --- /dev/null +++ b/doc/roadmap.md @@ -0,0 +1,307 @@ +# Project roadmap + +## Planned for 2023 + +### SNMP AgentX plugin for BIRD status export +Allow for easier status monitoring. + +### BGP Monitoring Protocol (BMP) +BGP Monitoring Protocol (RFC 7854) is a protocol between a BGP speaker and +a monitoring node, which is notified about route updates and neighbor state +changes of the BGP speaker. + +### Better coverage of automatic tests +Functionality tests should cover more possible configurations and +combinations. Integration tests should run automatically between different OS +versions and HW architectures. Experimental support for performance regression tests. + +### Release 3.0-alpha1 +Missing: MRT, merging + +### Show BFD sessions details +CLI command showing detailed information about BFD sessions state + +### Review and merge Babel extended next hop patches (RFC 9229) +Babel extension to allow IPv4 routes with IPv6 next hop. Patch on mailing list. + +### Consolidate protocol statistics +Consolidate protocol statistics, make them useful for SNMP plugin and implement +'show XX stats' command. + +### TCP-AO if it appears in Linux and BSD upstream +Resolve whether we should or shouldn't control the kernel key management. +Design and implement our side for both Linux and BSD. + +### Conditional routes (v3) +Filters should be extended to allow conditional expressions based on a number of +matching routes in a routing table. This would allow to specify aggregate routes +using a static protocol and conditions like 'if there is at least 1000 routes +from this BGP protocol, accept this default route'. This feature comes handy +when a router needs to detect whether its BGP upstream is alive and working. +Based of number of routes received, the router can then announce or retract a +default route to OSPF, making multi-exit network routing simpler and more +effective. + +### Aggregating routes +Requested by customer: aggregating multiple routes by a common set of attributes. + +Implementation choice: the user specifies + + EXPORT filter before aggregation AGGREGATE ON list of expressions to compare MERGE what to do with the remaining attributes + +Example usage: + +* aggregating information from multiple internal BGP routes into one external +* creating a multipath route from multiple BGP routes (currently done by MERGE PATHS) +* (in future) computing a minimal route set for kernel to make forwarding faster instead of writing the received full BGP set there + +### PREF64 option in RA (RFC 8781) +Inform hosts about prefix used to synthesize NAT64 addresses. Requested in list: +http://trubka.network.cz/pipermail/bird-users/2022-November/016401.html + +### Logging via UDP +Got a patch, probably never merged. May be useful. +http://trubka.network.cz/pipermail/bird-users/2022-January/015893.html + +### BGP Tunnel Encapsulation Attribute (RFC 9012) +Packets sent to BGP next hop may be encapsulated using various tunnel +technologies. Useful for L3VPN. + +### BGP AS Cones and ASPA support +Extend the RPKI protocol with AS Cones and ASPA loading. Implement AS Cones +and ASPA validation routines. There may be some pending patches from QRator. + +### DHCPv6 relay agent +DHCPv6 relay agents (RFC 8415, RFC 8987) forward DHCPv6 messages between clients and +servers. They also ensure that prefixes delegated by DHCPv6-PD are routable, +i.e. they should generate routes for these prefixes. + +### Nexthop attributes and ECMP filtering +Currently we have route attributes, but with ECMP routes it is necessary to +store per-nexthop data (like weight or encapsulation). We also do not have +proper way to manipulate with multiple nexthops from filters. Attributes should +be extended to allow per-nexthop ones and filters should be extended to allow +access multiple nexthops and their attributes. + +### Performance accounting +Extended internal statistics about time spent in different modules of BIRD. If +the route server admin checks why it takes 15 minutes to converge, this should +give some basic info about performance. [MM: Internally needed by 3.0, already in progress] + +### MPLS support +Finalize and merge improved MPLS infrastructure (including MPLS label allocator +and supporting code), improve its reconfiguration support and support for +segment routing. + +### BGP Segment Routing Extension (RFC 8669) +Receive and announce Segment Identifiers (SIDs) for BGP next hops. + +## Backlog for following years + +*The order of these items is not significant.* + +### Flowspec attribute filtering +Flowspec routes have many parameters, but these are not accessible from filters. +Filters should be extended to access all these attributes, but first it is +necessary to cleanup attribute handling in filters. + +### BGP Optimal Route Reflection (RFC 9107) +Implement BGP best route selection on route reflectors to adhere to POV of +client, not RR. Also requested by somebody, don't remember who and when. + +### OSPF Traffic engineering extensions (RFC 3630) +Requested in list. May include lots of other RFC's as we have neglected this +feature for a long time. +http://trubka.network.cz/pipermail/bird-users/2022-January/015911.html + +### IPv6 preference in documentation (?) +Address world's reluctance of legacy IPv4 deprecation by updating the +documentation in such a way that IPv6 is preferred and first seen. + +### BGP local prefix leak prevention (?) +Reject local prefixes on eBGP sessions by default to prevent leaks to public Internet. +Unless explicitly enabled by config, of course. + +### Re-bogonization of 240/4 legacy range (?) +We shouldn't believe that every operator does the +filtering right and they could simply rely on pre-2.0.10 behavior which +filtered this out by default. + +### IPv4 multicast +Basic infrastructure for IPv4 multicast routing, including nettypes for +multicast routes and multicast requests, multicast kernel protocol and IGMPv2 +protocol. + +### PIM-BIDIR +Bidirectional PIM (RFC 5015) is a multicast routing protocol, variant of PIM-SM. +It uses bidirectional shared trees rooted in Rendezvous Point (RP) to connect +sources and receivers. + +There is an old branch containing this. We should have merged this years ago. + +### Improved VRF support +BIRD has working VRF support, but it needs improvements. VRF entities should be +first-class objects with explicit configuration, with a set of properties and +default values (like default routing tables, or router ID) for associated +protocols. Default kernel table ID should be autodetected. There should be +better handling of VRF route leaking - when a route is propagated between VRFs, +its nexthop should reflects that. Setup of VRFs in OS is out of scope. + +### Linux kernel nexthop abstraction +Netlink allows setting nexthops as objects and using them in routes. It should +be much faster than conventional route update. + +### Protocol attributes for filtering +Filters can access route attributes, but sometimes it could be useful to access +attributes of associated protocol (like neighbor-as or neighbor-ip for BGP +protocol). But it would require to have internal object model (below) first, +as we do not want to implement it independently for each protocol attribute. + +### Mutable static routes +Extension to the static protocol that would allow to add/remove/change static +routes from CLI. + +### Multipipe +Pipe-like protocol: When a route is exported to this protocol, it runs its +filter extended with capability to announce any number of new routes to any +table from one filter run. Its primary purpose is to allow user-specified +route aggregation and other non-linear operations. + +### BGP minimum route advertisement interval (MRAI) +BGP specifies minimum interval between route advertisements for the same +network. This is not implemented in BIRD. It should be implemented for 3.0 to +avoid unnecessary re-routing spikes. + +### OSPF unnumbered interfaces +The OSPFv2 protocol allows interfaces that do not have proper IP range but have +peer IP addresses (like PtP links). It should be extended to also allow true +unnumbered interfaces with no addresses (by using an IP address from some +loopback device). This would require to have stricter separation between IP +addresses and interfaces in OSPFv2. + +### OSPF Segment Routing Extension (RFC 8665) +MPLS label distribution using segment routing and simple OSPF extension. + +### MPLS Label Distribution Protocol (LDP) +Label Distribution Protocol (RFC 5036) is a protocol for establishing +label-switched paths and distributing of MPLS labels between MPLS routers. +These paths and labels are based on existing unlabeled routing information. + +### IPv6 multicast +Basic infrastructure for IPv6 multicast routing, including nettypes for +multicast routes and multicast requests, multicast kernel protocol and MLDv1 +protocol. Most of these (with the exception of MLDv1) is just a variant of +IPv4 multicast. + +### IGMP/MLD multicast proxy +A simple IGMP/MLD multicast proxy, which sends IGMP/MLD requests on a configured +uplink interface based on received requests on downlink interfaces, and updates +associated multicast routes. + +### Source-specific multicast (SSM) +Infrastructure for multicasts should be extended to handle source-specific +multicasts. Extend multicast nettypes to include source addresses, handle them +in multicast kernel protocols and implement IGMPv3/MLDv2 protocols. + +### PIM-SSM +PIM-SSM is a source-specific multicast routing protocol, a subset of PIM-SM +protocol (RFC 7761). It is restricted to source-specific multicasts, which +eliminates many problematic parts of PIM-SM. + +### Seamless BFD +New version of BFD negotiation defined in RFC 7880-7886 enables faster +continuity tests by dissemination discriminators by the governing protocols. + +### OSPF Graceful Link Shutdown +To enable seamless maintenance of single links, OSPF can advertise such a link +getting down in advance, allowing to re-route. Defined in RFC 8379. + +## Long-term + +### Internal object model +We need to define explicit internal object model, where existing objects +(protocols, channels, tables, routes, interfaces ...) and their properties are +described in a way that allows introspection sufficient for implementing +features (control protocol, CLI, filter access, perhaps reconfiguration) in a +generic manner. + +### Generic configuration model +Configuration options are implicitly defined by the configuration parsing code. +We need to define explicit configuration model independent of the parsing code +and generic parsing code using that model. This will allow uniform validation of +configuration properties, generic access to configuration from control protocol +and possibly independent configuration backends (like one for Netconf). + +### New control protocol +BIRD should have a well-documented machine readable protocol. Requirements for +such protocol are: + +* Generic machine readable abstract-tree representation (like CBOR) +* Both request/reply and subscribe/notify access patterns +* Access objects and properties using internal object model +* In-band introspection based on internal object model + +From Maria's notes: + +* CBOR-based protocol for both control and route exports +* Python3 library with example implementation of CLI +* (maybe) Ansible modules +* RFC 9164: CBOR tags for IP addresses and prefices +* RFC 9254: YANG-CBOR mapping +* RFC 9277: Stable storage of CBOR (files) + +## Perhaps + +### IS-IS +IS-IS routing protocol is a nice-to-have alternative to OSPF. + +### BGPsec +BGPsec (RFC 8205) is a new path security extension to BGP. + +### PIM-SM +PIM-SM (RFC 7761) is a prevailing multicast routing protocol, but more +complicated than planned PIM-BIDIR and PIM-SSM. + +### Netconf +Network Configuration Protocol (RFC 6241) is a XML/JSON protocol for +configuration management of network devices. It would benefit from generic +configuration model (above). + +### NetConf overlay +Machine-friendly config file editor daemon (standalone) with standard NetConf +interface on one side and BIRD config file + reconfiguration requests on the +other side. Python3 seems to be better choice than C for this kind of work. + +### Backend for 802.11r +Let's assume a bunch of boxes, all having some public wifi APs and some (secure) uplinks. +Design and implement an automatic backbone protocol to allow for simple almost-zeroconf +setup of e.g. a conference room or train / bus public wifi or even a local home network, +all with hostapd seamlessly transferring clients between APs via 802.11r. +Possible collab with Turris. + +### BFD Multipoint Connectivity +Checking whether multiple "receivers" can communicate with a single "sender". +Possibly useful after merging PIM-BIDIR and implementing other PIMs. RFC 8562-8563. + +### BGP Link State extension +BGP-LS allows to transport information about network topology across BGP links. +This should help e.g. to run traffic-engineering between more confederated ASs. +Also needed to implement Seamless BFD on BGP: RFC 9247 + +### Locator/ID Separation Protocol +LISP intends to break up addressing to Routing Locators and Endpoint +Identifiers. This may help multihoming networks in future. RFC 9299-9306. + +### Backend for IPv6 Multihoming without BGP +Implement and configure BIRD in such a way that local nodes are seamlessly +connected to the Internet via multiple upstreams, using Network Prefix +Translation and other techniques. Possible collab with Turris. + +## Minor + +* RFC 8510: OSPF LLS Extension for Local Interface ID Advertisement +* RFC 8538: BGP Graceful Restart Hard Reset +* RFC 8326: BGP Graceful Session Shutdown Community auto-apply +* RFC 8962: Become part of the IETF Protocol Police +* RFC 9072: Extended Optional Parameters Length for BGP OPEN Message +* RFC 9339: OSPF Reverse Metric |