diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/configuration/channel-options.md ./user/configuration/channel-options.md
--- ../docs.worktrees/v2.17.2/user/configuration/channel-options.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/configuration/channel-options.md 2025-10-03 13:05:22.801689426 +0800
@@ -30,10 +30,12 @@
`none` is for dropping all routes. Default: `all` (except for
EBGP).
-export *filter*
+export \[ in *prefix* \] *filter*
This is similar to the `import` keyword, except that it works in
- the direction from the routing table to the protocol. Default: `none`
- (except for EBGP and L3VPN).
+ the direction from the routing table to the protocol. If `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: `none` (except for EBGP and L3VPN).
import keep filtered *switch*
Usually, if an import filter rejects a route, the route is forgotten.
@@ -47,7 +49,8 @@
`roa_check()` or `aspa_check()` operators). In contrast to other
filter operators, this status for the same route may change as the
content of ROA and ASPA tables changes. When this option is active, BIRD
- activates automatic reload of affected channels whenever ROA and ASPA
+ activates automatic reload of the appropriate subset of prefixes imported
+ or exported by the channels whenever ROA and ASPA
tables are updated (after a short settle time). When disabled, route
reloads have to be requested manually. The option is ignored if neither
`roa_check()` nor `aspa_check()` is used in channel filters. Note
@@ -85,6 +88,13 @@
updates of already accepted routes -- and these details will probably
change in the future. Default: `off`.
+export block *number*
+Set the minimum amount of routes exported at once when feeding or
+ if \`merge paths\` or \`secondary\` is selected. This affects overall latency.
+ Basically, when your export filters are very expensive, processing
+ the whole block of routes may take too much time. In such cases, you may need to
+ shrink this value to improve responsiveness. Default: `16384`.
+
This is a trivial example of RIP configured for IPv6 on all interfaces:
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/configuration/global-options.md ./user/configuration/global-options.md
--- ../docs.worktrees/v2.17.2/user/configuration/global-options.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/configuration/global-options.md 2025-10-03 13:05:22.801689426 +0800
@@ -14,7 +14,7 @@
ipv6 table
include "tablename.conf";;
-log "*filename*" \[*limit* "*backup*"\] \| syslog \[name *name*\] \| stderr \| udp *address* \[port *port*\] all\|{ *list of classes* }
+log "*filename*" \[*limit* "*backup*"\] \| fixed "*filename*" *size* \| syslog \[name *name*\] \| stderr \| udp *address* \[port *port*\] all\|{ *list of classes* }
Set logging of messages having the given class (either `all` or `{
error|trace [, `*...*`] }` etc.) into selected destination - a file
specified as a filename string (with optional log rotation information),
@@ -33,7 +33,8 @@
Logging directly to file supports basic log rotation -- there is an
optional log file limit and a backup filename, when log file reaches the
limit, the current log file is renamed to the backup filename and a new
- log file is created.
+ log file is created. It's also possible to log to a single file behaving
+ as a ring buffer with a fixed size.
You may specify more than one `log` line to establish logging to
multiple destinations. Default: log everything to the system log, or
@@ -52,7 +53,7 @@
debug tables all\|off\|{ states\|routes\|filters\|events \[, *...*\] }
Set global defaults of table debugging options.
- See [debug](#table-debug) in the table section.
+ See [debug](#rtable-debug) in the table section.
Default: off.
debug commands *number*
@@ -60,9 +61,10 @@
of connects and disconnects, 2 and higher for logging of all client
commands). Default: 0.
-debug latency *switch*
-Activate tracking of elapsed time for internal events. Recent events
- could be examined using `dump events` command. Default: off.
+debug latency all\|off\|{ ping\|wakeup\|scheduling\|sockets\|events\|timers }
+Activate tracking of internal scheduler actions. This is a developer
+ and technical support tool for cases when internal events are missed.
+ You should keep this off unless you know what you are doing. Default: off.
debug latency limit *time*
If `debug latency` is enabled, this option allows to specify a limit
@@ -183,3 +185,65 @@
eval *expr*
Evaluates given filter expression. It is used by the developers for testing of filters.
+
+### Thread setup
+
+BIRD runs in several threads. There is one main thread, taking care about startup,
+shutdown, (re)configuration, CLI and several protocols which have not yet been updated
+to run in other threads. Then there are several thread groups, running the rest.
+
+Default thread group is `worker`. This group runs (by default) BGP, BMP, MRT,
+Pipe and RPKI. Also the routing table maintenance routines run in these threads.
+For BFD, there is another thread group called
+`express`, with minimal latency, expecting all tasks to be extremely fast.
+The threads are started as soon as some work is required from them, therefore
+if you don't configure BFD, the express thread won't start.
+
+Any configuration of thread groups must be strictly placed before any table
+or protocol configuration, as these depend on the thread group existence.
+
+Thread groups are configured by writing `thread group `*name*` {}` blocks,
+which contain the following options:
+
+threads *number*
+Set how many threads should BIRD spawn in this thread group.
+ Every thread can utilize one complete CPU core. You probably want to
+ keep at least one free core for other processes. The maximum feasible
+ thread count heavily depends on the actual workload and must be determined
+ by testing or estimation. Default: 1
+
+default *bool*
+Mark this thread group as default. There must be exactly one thread group
+ marked as default. Default default thread group: `worker`
+
+max latency *time*
+Set maximum latency for the thread group. The group tries to dispatch every
+ event before this time elapses. Setting this too low causes BIRD
+ to spend lots of time on overhead and fill logs with reports.
+ Setting this too high causes BIRD to hold locks for long times.
+ Do not change unless you know what you are doing.
+ Default: 1 s for worker, 10 ms for express.
+
+min time *time*
+Set minimum awarded loop execution time for the thread group.
+ This is an internal performance tuning knob which may change between
+ minor versions. Do not change unless you know what you are doing.
+ Default: 10 ms for worker, 1 ms for express.
+
+max time *time*
+Set maximum awarded loop execution time for the thread group. This is
+ an internal performance tuning knob which may change between
+ minor versions. Do not change unless you know what you are doing.
+ Default: 300 ms for worker, 10 ms for express.
+
+wakeup time *time*
+Set maximum sleep time for the thread group. Every thread will wake up
+ after this time even if no work is requested. This is an internal
+ IO loop knob which may change between minor versions.
+ Do not change unless you know what you are doing.
+ Default: 31415 s for worker, 60 s for express.
+
+There is also a "simple" thread group setting. If you write
+`threads `*number* on top level, it is equivalent to setting
+the worker group thread count to that number, and the express group thread count
+to one. This setting is deprecated and may disappear in some future version.
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/configuration/protocol-options.md ./user/configuration/protocol-options.md
--- ../docs.worktrees/v2.17.2/user/configuration/protocol-options.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/configuration/protocol-options.md 2025-10-03 13:05:22.801689426 +0800
@@ -15,6 +15,13 @@
command line interface without needing to touch the configuration.
Disabled protocols are not activated. Default: protocol is enabled.
+restart time limit *time*
+Set time limit for subsequent automatic restarts of the protocol.
+ If the protocol hits the limit (with a restart action) before this time
+ elapses from starting the protocol, the protocol is disabled with
+ an error message in the config file. This doesn't apply to manual
+ restarts or reconfiguration. Default: 5 s.
+
debug all\|off\|{ states\|routes\|filters\|interfaces\|events\|packets \[, *...*\] }
Set protocol debugging options. If asked, each protocol is capable of
writing trace messages about its work to the log (with category
@@ -75,6 +82,11 @@
[channel configuration section](#channel-opts) for channel
definition.
+thread group *name*
+Assign this protocol's tasks to this thread group. Ignored in protocols
+ not yet updated for the multithreaded execution model.
+ Default: `worker`.
+
There are several options that give sense only with certain protocols:
interface \[-\] \[ "*mask*" \] \[ *prefix* \] \[, *...*\] \[ { *option*; \[*...*\] } \]
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/configuration/routing-table-options.md ./user/configuration/routing-table-options.md
--- ../docs.worktrees/v2.17.2/user/configuration/routing-table-options.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/configuration/routing-table-options.md 2025-10-03 13:05:22.805689425 +0800
@@ -5,12 +5,6 @@
that implicit tables (`master4` and `master6`) can be redefined in order
to set options.
-debug all\|off\|{ states\|routes\|filters \[, *...*\] }
-Set table debugging options. Like in [protocol
-debugging](#proto-debug), tables are capable of writing trace
- messages about its work to the log (with category `trace`).
- For now, this does nothing, but in version 3, it is used. Default: off.
-
sorted *switch*
Usually, a routing table just chooses the selected (best) route from a
list of routes for each network, while keeping remaining routes unsorted.
@@ -41,20 +35,6 @@
disadvantage is that trie-enabled routing tables require more memory,
which may be an issue especially in multi-table setups. Default: off.
-min settle time *time*
-Specify a minimum value of the settle time. When a ROA table changes,
- automatic [RPKI reload](#proto-rpki-reload) may be
- triggered, after a short settle time. Minimum settle time is a delay
- from the last ROA table change to wait for more updates. Default: 1 s.
-
-max settle time *time*
-Specify a maximum value of the settle time. When a ROA table changes,
- automatic [RPKI reload](#proto-rpki-reload) may be
- triggered, after a short settle time. Maximum settle time is an upper
- limit to the settle time from the initial ROA table change even if
- there are consecutive updates gradually renewing the settle time.
- Default: 20 s.
-
gc threshold *number*
Specify a minimum amount of removed networks that triggers a garbage
collection (GC) cycle. Default: 1000.
@@ -69,3 +49,48 @@
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).
+
+cork threshold *number* *number*
+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 but if you experience memory bloating on import
+ surges, this knob is the first to turn down. Default: 333300 1011010.
+
+export settle time *time* *time*
+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: `1 ms 100 ms`. You have to always provide both values.
+
+route refresh export settle time *time* *time*
+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 [export settle
+time](#rtable-export-settle-time).
+ Default values: `100 ms 3 s`.
+
+digest settle time *time* *time*
+Minimum and maximum settle times, respectively, for table change digests.
+ This settle time applies to ROA table changes where a trie is generated
+ containing all changed ROAs to automatically reload depending channels.
+ Default values: `1 s 20 s`.
+
+debug all\|off\|{ states\|routes\|events \[, *...*\] }
+Set table debugging options. Each table can write some trace messages
+ into log with category `trace`. You can request `all` trace messages
+ or select some types: `states` for table state changes and auxiliary
+ processes, `routes` for auxiliary route notifications (next hop update,
+ flowspec revalidation) and `events` for more detailed auxiliary routine
+ debug. See also [channel debugging option](#channel-debug).
+ Default: off.
+
+thread group *name*
+Assign this table's maintenance tasks to this thread group.
+ Default: `worker`.
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/filters/control-structures.md ./user/filters/control-structures.md
--- ../docs.worktrees/v2.17.2/user/filters/control-structures.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/filters/control-structures.md 2025-10-03 13:05:22.805689425 +0800
@@ -23,10 +23,10 @@
a set, while the *set_body_expr* before `:` can be anything (constants,
intervals, expressions) that could be a part of a set literal. One exception is
prefix type, which can be used in sets bud not in `case` structure. Multiple
-commands are allowed without `{}` grouping. If *expr* matches one
-of the `:` clauses, statements between it and next `:` statement are
+commands must be grouped by `{}`. If *expr* matches one
+of the `:` clauses, the statement or block after it is
executed. If *expr* matches neither of the `:` clauses, the
-statements after `else:` are executed.
+statement or block after `else:` is executed.
Here is example that uses `if` and `case` structures:
@@ -42,7 +42,7 @@
}
case arg1 {
- 2: print "two"; print "I can do more commands without {}";
+ 2: { print "two"; print "Multiple commands must brace themselves."; }
3 .. 5: print "three to five";
else: print "something else";
}
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/filters/route-attributes.md ./user/filters/route-attributes.md
--- ../docs.worktrees/v2.17.2/user/filters/route-attributes.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/filters/route-attributes.md 2025-10-03 13:05:22.805689425 +0800
@@ -21,17 +21,8 @@
primary key of the routing table. Read-only. (See the [chapter about
routes](#routes).)
-*enum* scope
-The scope of the route. Possible values: `SCOPE_HOST` for routes
- local to this host, `SCOPE_LINK` for those specific for a physical
- link, `SCOPE_SITE` and `SCOPE_ORGANIZATION` for private routes and
- `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 `SCOPE_UNIVERSE`.
-
*int* preference
-Preference of the route. Valid values are 0-65535. (See the chapter
- about routing tables.)
+Preference of the route.
*ip* from
The router which the route has originated from.
@@ -72,14 +63,6 @@
creation/removal. Zero is returned for routes with undefined outgoing
interfaces. Read-only.
-*bool* onlink
-Onlink flag means that the specified nexthop is accessible on the
- interface regardless of IP prefixes configured on the interface.
- The attribute can be used to configure such next hops by first setting
- `onlink = true` and `ifname`, and then setting `gw`. Possible
- use case for setting this flag is to automatically build overlay IP-IP
- networks on linux.
-
*int* weight
Multipath weight of route next hops. Valid values are 1-256. Reading
returns the weight of the first next hop, setting it sets weights of all
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/protocols/bfd.md ./user/protocols/bfd.md
--- ../docs.worktrees/v2.17.2/user/protocols/bfd.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/protocols/bfd.md 2025-10-03 13:05:22.805689425 +0800
@@ -62,6 +62,11 @@
are allowed as units, practical minimum values are usually in order of tens of
milliseconds.
+Beware, all BFD instances pick up requests and sessions asynchronously, and
+any instance can pick up any matching request, regardless of the order in the
+configuration file. There may be a future update, allowing for strict matching,
+yet for now, we do not have such an option.
+
protocol bfd [] {
accept [ipv4|ipv6] [direct|multihop];
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/protocols/bgp.md ./user/protocols/bgp.md
--- ../docs.worktrees/v2.17.2/user/protocols/bgp.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/protocols/bgp.md 2025-10-03 13:05:22.809689424 +0800
@@ -894,6 +894,11 @@
9234 as "strict mode" and is used to enforce corresponding
configuration at your conterpart side. Default: disabled.
+tx size warning *number*
+If this option is set, the bgp protocol prints warning when it consumes at least
+ given size of memory. This includes also the memory consumed
+ by any export table. Zero means disabled. Default: disabled.
+
### Channel configuration
BGP supports several AFIs and SAFIs over one connection. Every AFI/SAFI
@@ -1030,13 +1035,6 @@
be examined later by `show route`, and can be used to reconfigure
import filters without full route refresh. Default: off.
-Note that currently the import table breaks routes with recursive
- nexthops (e.g. ones from IBGP, see [gateway
-recursive](#bgp-gateway)), they are not properly updated after next hop change. For
- the same reason, it also breaks re-evaluation of flowspec routes with
- [flowspec validation](#bgp-validate) option enabled on
- flowspec channels.
-
export table *switch*
A BGP export table contains all routes sent to given BGP neighbor, after
application of export filters. It is also called **Adj-RIB-Out** in BGP
@@ -1047,6 +1045,13 @@
`show route`, and can be used to eliminate unnecessary updates or
withdraws. Default: off.
+export settle time *time* *time*
+Minimum and maximum settle times, respectively, for announcements from
+ export table to external readers. These values don't apply for regular TX,
+ just for side channel exports. You will probably never need to change
+ these values.
+ Default values: `10 ms 100 ms`. You have to always provide both values.
+
secondary *switch*
Usually, if an export filter rejects a selected route, no other route is
propagated for that network. This option allows to try the next route in
Only in ../docs.worktrees/v2.17.2/user/protocols: perf.md
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/protocols/pipe.md ./user/protocols/pipe.md
--- ../docs.worktrees/v2.17.2/user/protocols/pipe.md 2025-10-03 13:14:18.777578290 +0800
+++ ./user/protocols/pipe.md 2025-10-03 13:05:22.809689424 +0800
@@ -36,6 +36,14 @@
Defines secondary routing table to connect to. The primary one is
selected by the `table` keyword.
+max generation *expr*
+Sets maximal generation of route that may pass through this pipe.
+ The generation value is increased by one by each pipe on its path.
+ Not meeting this requirement causes an error message complaining about
+ an overpiped route. If you have long chains of pipes, you probably want
+ to raise this value; anyway the default of 16 should be enough for even
+ most strange uses. Maximum is 254.
+
### Attributes
The Pipe protocol doesn't define any route attributes.
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/remote-control/configuration.md ./user/remote-control/configuration.md
--- ../docs.worktrees/v2.17.2/user/remote-control/configuration.md 2025-10-03 13:14:18.781578289 +0800
+++ ./user/remote-control/configuration.md 2025-10-03 13:05:22.809689424 +0800
@@ -5,13 +5,20 @@
BIRD or the CLI tool connects there instead.
It's also possible to configure additional remote control sockets in the
-configuration file by `cli "name";` and you can open how many
+configuration file by `cli "name" { restrict
+Set the socket to be restricted as if the user always sent the
+ `restrict` command after connecting. The user may still overload
+ the daemon by requesting insanely complex filters so you shouldn't
+ expose this socket to public even if restricted.
+
+v2 attributes
+Display the names and composition of route attributes the same way as BIRD 2 does.
+ This is a compatibility option for easier transition from BIRD 2 to BIRD 3.
diff '--color=auto' -bur ../docs.worktrees/v2.17.2/user/remote-control/usage.md ./user/remote-control/usage.md
--- ../docs.worktrees/v2.17.2/user/remote-control/usage.md 2025-10-03 13:14:18.781578289 +0800
+++ ./user/remote-control/usage.md 2025-10-03 13:05:22.809689424 +0800
@@ -18,6 +18,10 @@
and protocol status, possibly giving verbose information, if `all` is
specified.
+reload bgp \[in\|out\] \[*name*\]
+Manually request (in) or send (out) route refresh (or both) on the
+ given BGP protocol(s).
+
show ospf interface \[*name*\] \["*interface*"\]
Show detailed information about OSPF interfaces.
@@ -156,7 +160,7 @@
Enable, disable or restart a given protocol instance, instances matching
the *pattern* or `all` instances.
-reload \[in\|out\] *name*\|"*pattern*"\|all
+reload filters \[in\|out\] (*name*\|"*pattern*"\|all) \[partial prefix\]
Reload a given protocol instance, that means re-import routes from the
protocol instance and re-export preferred routes to the instance. If
`in` or `out` options are used, the command is restricted to one
@@ -167,6 +171,9 @@
propagates the old set of routes. For example when `configure soft`
command was used to change filters.
+If `partial prefix` option is used, only corresponding routes are reloaded.
+ Protocol BGP does partial reload only if it has import table enabled, otherwise partial reload for BGP is refused.
+
Re-export always succeeds, but re-import is protocol-dependent and might
fail (for example, if BGP neighbor does not support route-refresh
extension). In that case, re-export is also skipped. Note that for the
