Update CANBUS.md for Bookworm

[JamesH1978]

This is a PR to add the steps needed for bookworm installations to enable the can0 network for host hardware

Thanks
James

[KevinOConnor]

Thanks for working on this. For what it is worth, I'm not sure our audience will immediately know what "bookworm" and "bullseye" are. Can we just change to the new system and remove the old recommendations? (Or are there OS distros out there that don't support the new system?) Alternatively, is there some package on debian bookworm that could be installed so that it works with the old system?

Cheers,
-Kevin

[Sineos]

Can we just change to the new system and remove the old recommendations?

I'm not sure if I recommended this as a general practice. From what I read, it depends on the systemd version. There seem to be bugs and missing functionality if it is too old.
Additionally, I wouldn't mix different network management methods. If the distribution's standard method is the legacy interfaces approach, it's probably best to stick with it.

Probably the easiest way to identify which approach to use is by checking /etc/network. If there is no interfaces or interfaces.d, then the systemd method needs to be used.

Regarding the link file, I have noticed something a bit uncomfortable. Depending on the distribution and type of CAN adapter, the OS might automatically assign a link file. Probably this makes sense as the link files essentially are just some sort of udev rule.
On my side, an example looks like this:

# networkctl status can0
● 3: can0
               Link File: /usr/lib/systemd/network/73-usb-net-by-mac.link
            Network File: /etc/systemd/network/80-can.network
                   State: carrier (configured)
            Online state: unknown
                    Type: can
                    Kind: can
                    Path: platform-5310000.usb-usb-0:1.5:1.0
                  Driver: gs_usb
                  Vendor: OpenMoko, Inc.
                   Model: Geschwister Schneider CAN adapter
                     MTU: 16
                   QDisc: pfifo_fast
Number of Queues (Tx/Rx): 1/1
       Activation Policy: up
     Required For Online: no

In this case, creating a /etc/systemd/network/80-can.link file to modify the TX queue length wouldn't do anything. I had to modify the link file as assigned by the OS.

Maybe a safe way to handle this:

1. Bring up the network via the .network file.
2. Use networkctl status can0 to show the details.
3. If no link file is assigned, create one with the appropriate content. If one exists, modify it to add the relevant section.

[JamesH1978]

Thanks @Sineos @KevinOConnor

Unfortunately we are living in a two tier situation where people are still installing legacy or using pre made images like mainsailOS which is still Bullseye or installing newest bookworm versions of Debian. I am not sure how we deal with that. It is not the intention to provide instructions to completely change the networking system on someones device, that is likely way out of the docs remit IMO

We tried 3 methods of setting up can0 in Bookwork,

a)create the network file, and apply txqueuelength via a service that just runs ifconfig can0 txqueuelen 128 as an ExecStart with a WantedBy=sys-subsystem-net-devices-can0.device

b) Esotericals way of applying a UDEV rule

c) using a link file as detailed here

I went with c) for ease of setup more than anything, I was not aware that a link file would be applied if no can0 already exists though, @Sineos what distro is this?

Thanks
James

[thijstriemstra]

I ran into this issue yesterday while setting up CAN and was going to follow these instructions: https://github.com/Esoterical/voron_canbus/blob/main/Getting_Started.md

But will give this a try.

[thijstriemstra]

Bullseye -> Debian Bullseye

[thijstriemstra]

Debian Bookworm

[Sineos]

My recommendation is to avoid naming distributions completely, as it will either be incomplete or outdated.

For me, the best approach is for the user to check the existence of the interfaces file. If it is available, use the traditional method; if not, go for systemd.

The machines I have set up using this approach all work pretty flawlessly with the .network and .link setup. The example above, where the .link is pre-allocated by the OS, is from Armbian 24.11 on Ubuntu 24.04. I have seen machines that would leave the .link empty and expect it to be defined manually. Unfortunately, I have not been able to identify the logic behind this.

As such, I'd recommend bringing up the interface with the .network file only and checking what the OS is expecting. The .link anyway is only needed to modify the queue length, so it can be easily adapted in the second step.

With the command

ip -details -statistics link show can0

you can both check for the queue length as well as any RX / TX errors, so it might be worthwhile adding it.

[JamesH1978]

Thats all well and good and makes sense, but we have to make it succinct and doable by the average uninformed user. i don't like giving them an "either or" in the first place, as they wont read the or and decide its broken because the first thing didnt work. It is a quandary how we best approach documenting multiple systems and ways

Thanks
James

[Sineos]

I agree, but I'm afraid that there is no such thing as a free lunch.
AFAIK, the ability to specify TX queue length has only been added in systemd from version 248 onwards. This already takes Bullseye out of the equation.
See https://github.com/systemd/systemd/blob/5dc89b327f2361c2a8a43c74871ae5bdd6a6c814/NEWS#L6892-L6893

[Sineos]

@JamesH1978, if your main concern is user-facing complexity, a potential solution could be to automate setting up the interface via a script. The description could reference the script as well as the manual approach for those who are interested or more advanced.

FWIW, I hacked together a PoC. If it is deemed useful, please go ahead and add it to this PR. I'm not interested in any copyrights whatsoever.

"Legacy" Method:

# python3 linux_setup_can0.py
[*] Checking if the script is run as root...
[+] Script is running as root.
[*] Please enter the CAN bitrate. Allowed values are 250000, 500000, 1000000.
CAN Bitrate (default: 500000):
[*] Checking if /etc/network/interfaces.d exists...
[+] /etc/network/interfaces.d exists.
[*] Creating /etc/network/interfaces.d/can0...
[+] /etc/network/interfaces.d/can0 created successfully.
[*] Bringing up can0 interface...
RTNETLINK answers: Connection timed out
ifup: failed to bring up can0
[-] First attempt to bring up can0 interface failed: Command '['ifup', 'can0']' returned non-zero exit status 1.
[*] Waiting 10 seconds before retrying...
[+] can0 interface brought up successfully on the second attempt.
[*] Checking if can0 interface is up...
[+] can0 interface is up and running.
[+] CAN interface configuration completed successfully.
[*] A reboot is recommended to ensure all changes take effect.

systemd with pre-allocated link file

# python linux_setup_can0.py
[*] Checking if the script is run as root...
[+] Script is running as root.
[*] Please enter the CAN bitrate. Allowed values are 250000, 500000, 1000000.
CAN Bitrate (default: 500000):
[*] Checking if /etc/network/interfaces.d exists...
[-] /etc/network/interfaces.d does not exist.
[*] Checking systemd version...
[+] Systemd version 255 is greater than 248.
[*] Creating /etc/systemd/network/80-can.network...
[+] /etc/systemd/network/80-can.network created successfully.
[*] Reloading systemd network configuration...
[+] Systemd network configuration reloaded successfully.
[*] Checking if can0 interface is up...
[+] can0 interface is up and running.
[*] Checking if a .link file is specified for can0...
[+] Link file found: /usr/lib/systemd/network/73-usb-net-by-mac.link
[*] Modifying /usr/lib/systemd/network/73-usb-net-by-mac.link...
[+] /usr/lib/systemd/network/73-usb-net-by-mac.link modified successfully.
[*] Reloading systemd network configuration...
[+] Systemd network configuration reloaded successfully.
[*] Checking if can0 interface has qlen set to 128...
[+] can0 interface has qlen set to 128.
[+] CAN interface configuration completed successfully.
[*] A reboot is recommended to ensure all changes take effect.

linux_setup_can0.py.txt

[KevinOConnor]

Thanks for working on this.

FWIW, I'd prefer not to add additional system installation scripts to the Klipper repo - it's too much of an ongoing maintenance burden.

I'm not sure what the best way forward is.

It is not the intention to provide instructions to completely change the networking system on someones device, that is likely way out of the docs remit IMO

Agreed.

We tried 3 methods of setting up can0 in Bookwork

Maybe use Esoterical's udev method for setting txqueuelength, and then alert the user to install either /etc/network/interfaces.d/can0 (without the up ip link set $IFACE txqueuelen 128) or /etc/systemd/network/80-can0.network .

Not sure.
-Kevin

[Sineos]

Maybe use Esoterical's udev method for setting txqueuelength, and then alert the user to install either /etc/network/interfaces.d/can0 (without the up ip link set $IFACE txqueuelen 128) or /etc/systemd/network/80-can0.network .

From the user perspective, I see no benefit in making the ifupdown method more complex by introducing udev rules.

Since all Debian and Debian-like distributions use systemd in their currently stable releases, I would describe systemd first and leave the ifupdown method as is. It will likely disappear sooner rather than later anyway.

Finally, the Linux side of Klipper will always introduce additional complexity. Luckily, today KIAUH hides most of it, acting as an excellent Swiss Army Knife for Klipper installations. If it did not exist, the need for installation scripts and helpers would be much more prominent.

[JamesH1978]

As far as i know, and as you say @Sineos all current debian versions should be able to use systemd networkd, so we could just drop the old info completely. i will need to install a copy of mainsailOS on bullseye to check this works

Thanks
James

[Sineos]

From my gut feeling and reading a lot about this topic, I'd not recommend doing this:

• There seem to be quite a few bugs around the network portion of systemd in older versions.
• There has been a lot of movement between the old stable distribution (e.g., Bullseye) with versions around 247 and the current stable versions (e.g., Bookworm) with versions around 255.
• No distribution that I know of, before the currently stable ones, "dared" to switch to systemd-networking - probably for a reason.

As such, I personally also do not agree with Esoterical's approach of recommending it unconditionally and mixing ifupdown-based distributions with the systemd approach. The ifupdown method is battle-tested and apparently stable. I'm not sure if a bit of documentation simplification is worth potentially introducing subtle issues.