Doc suggestion - clarifying behaviour when routes are moving between protocols

[Mark Shuttleworth]

Hi Alexander

On Thu, 8 Feb 2024 at 13:28, Alexander Zubkov <green at qrator.net> wrote:

> Actually the best route selection algorithm can be found here:
> https://bird.network.cz/?get_doc&v=20&f=bird-2.html#ss2.1
>

Can't argue that it's there, but even with the benefit of hindsight it is a
little terse :)

Admittedly I am not a networking specialist, but perhaps that makes my
feedback useful in terms of gaining new users and bringing Bird to a wider
audience. My previous experience has been playing with Babel for this same
personal project, and Bird is obviously a step up in complexity given its
support for many different protocols. As an aside, it's great to see Babel
support in Bird :)

At the time, here's what I struggled with. Hopefully some of this will be
helpful in shaping docs for new users.

It would be useful early in the doc to have a visualisation of the
relationship between a table such as master4 and a protocol, like kernel or
ospf. I found drawing a picture for myself helped to make import vs export
clear. Perhaps the docs can have a picture like that! My suggestion would
be to make that visualisation include multiple protocols such as the kernel
protocol and one of the routing protocols like RIP or OSPF, so that it can
help explain how a route might move between routers (OSPF) and into the
local machine routing table. I would walk through a full example, showing
movement of routes in both directions from both protocols. Describe, step
by step, how a kernel route would be learned and imported into a table like
ipv4, and then exported by OSPF, and vice versa. Perhaps this is obvious to
a routing expert but it wasn't obvious to me as someone playing with a
proper routing daemon for the first time.

The multi-protocol case (kernel protocol and ospf protocol) may be less
interesting to someone who's focused on BGP or OSPF across many routers,
but it seems to me to be critical to the new user experience. A new user is
likely to have one, two or three routers, and they need to move routes
between them AND get those routes installed into the kernel, so they have
to understand the multi-protocol interaction dynamics. This is where things
like preference, which are not things one can learn about just by reading
about OSPF or RIP, come into play.

The part of the doc you refer to is critical - it covers the main deal
which is 'which routes from the various protocols will move into position
where they can be actioned', but it's also very terse, and it's just a
paragraph or two in a long stretch of detail. It also uses the term
'preference' twice, and I'm not sure those two uses refer to the same
thing. It says 'Preferences of the routes are compared' and 'Source
protocol instance preferences are compared' but neither 'route preference'
nor 'source protocol instance preference' has been defined before this
text. I'm still not sure how I would go and look at a setup with birdc and
find out easily what the route preference or source protocol instance
preference would be.

So I think all of this warrants a section on its own, early in the overall
documentation, that walks through the behaviours of protocols, channels,
and tables, and how they interact. It's notable that other people have
found a need to try and explain this more clearly themselves - digging
around to compose this email I found another example at
https://blog.kintone.io/entry/bird which may be helpful to you.

It would also help if logging of decisions wrt import or export captured
more of the rationale for the decision. As I dug into this I saw messages
like 'route rejected by protocol', but no rationale for that rejection (it
turned out to be the preference).  Because the relationship between tables
and protocols, import and export is unclear initially, it would be helpful
to be explicit in these log messages. Would it be possible to say something
like this:


*  <TRACE> 10.2.21.0/24 <http://10.2.21.0/24> from kernel import to
master4 accepted**  <TRACE> **10.2.34.0/24 <http://10.2.34.0/24> from
*
*master4 export to ospf1 rejected because protocol preference 100<30*

In this example I'm replacing angle brackets with explicit import / export,
and listing the table names explicitly, to try and make it easier for a new
user to follow that log and not be confused. I'm trying to show direction
in the order - from kernel import to master4, and from master4 export to
ospf1. The reason for the rejection would help to then dig in to details
like protocol preferences.

In debugging with birdc, I found the layouts rather inscrutable and could
not find documentation. For example:

bird> show route
Table master4:
0.0.0.0/0            unicast [ospf1 2024-01-31] * E2 (150/40/900)
[192.168.12.2]
via 192.168.4.248 on bond-lan weight 1
via 192.168.4.249 on bond-lan weight 1
192.168.254.48/30    unicast [ospf1 2024-01-31] * I (150/40)
[192.168.254.57]
via 192.168.4.248 on bond-lan weight 1
via 192.168.4.249 on bond-lan weight 1

What is each of those fields? It would be nice if the docs for the protocol
also explained how birdc represents routes from that protocol. In this
case, the docs at https://bird.network.cz/?get_doc&v=20&f=bird-6.html#ss6.11
could show the various permutations of an OSPF route, and point out where
preference and metrics are (it took a lot of googling to understand "E2
(150/40/900)" :)

Similarly, while preference is a critical element of the table import /
export route selection algorithm, it's hard to know what it actually is.
For example, where is the preference of this protocol instance?

bird> show ospf
ospf1:
RFC1583 compatibility: disabled
Stub router: No
RT scheduler tick: 1
Number of areas: 1
Number of LSAs in DB: 32
Area: 0.0.0.0 (0) [BACKBONE]
Stub: No
NSSA: No
Transit: No
Number of interfaces: 3
Number of neighbors: 4
Number of adjacent neighbors: 4

Apologies if this is newbie stuff, and hopefully it helps you get your
future newbies through that learning process faster with fewer questions to
your list :)

Mark
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://trubka.network.cz/pipermail/bird-users/attachments/20240209/06f3591f/attachment.htm>