[draft] feat(usbgadget): share JetKVM's internet via USB ethernet

[dlorch]

An early PoC implementation to share JetKVM's internet via USB Ethernet to the target host.

What can be seen on the screenshot:

• A USB Ethernet device is connected
• A traceroute that sends packets through the JetKVM device to the internet

Prerequisites

Requires USB Ethernet, NAT and nftables support in the OS from jetkvm/rv1106-system#16

USB gadget ethernet

Following USB ethernet protocols are available:

• Ethernet Control Model (ECM)
• Ethernet Emulation Model (EEM)
• Network Control Model (NCM)
• Remote Network Driver Interface Specification (RNDIS)

I am not an expert in the standards. I have used ECM for testing.

The standards basically differ in terms of transfer speeds and driver support in the OS. The Wiki page on Ethernet over USB has more information.

Setup

On the JetKVM, in /userdata/kvm_config.json, enable:

• "ethernet_ecm": true
• "network_config": { "nat_enable": true }

Observe the following log entries from JetKVM to validate the setup has worked:

2025-05-15T20:38:32Z INF jetkvm network enabling NAT iface=eth0
2025-05-15T20:38:33Z INF jetkvm usb enabling USB Ethernet iface=usb0 ipv4addr=172.16.55.1/24

On the target device, bring the interface up and set it up as a default route:

ip addr add 172.16.55.12/24 dev enxf2252a378082
ip link set dev enxf2252a378082 up
ip addr show dev enxf2252a378082

ping 172.16.55.1 # JetKVM
ip route replace default via 172.16.55.1 dev enxf2252a378082

I've picked the network 172.16.55.0/24 (RFC 1918) as a private network for USB ethernet

TODO

• Enable USB Ethernet and NAT
• Automatically set up target device via DHCP
• UI support for
  • Enable NAT
  • Set USB Ethernet MAC address (now: randomly assigned)
  • Set USB Ethernet Network CIDR (now: 172.16.55.0/24)
  • Select one of USB Ethernet protocol (ECM, EEM, NCM, RNDIS)

[IDisposable]

This is super nice... why 172.16.55.0/24 instead of 172.16.0.0/12?

[dlorch]

This is super nice... why 172.16.55.0/24 instead of 172.16.0.0/12?

The smallest possible network that's hopefully not overlapping with anything existing on the host. I randomly chose this network from the available RFC 1918 space.

• /24 is easy to work with (first three octets represent the network, the last octet is available for hosts)
• We could also go smaller with a /30 (2^2 = 4 addresses) or possibly a /31 (2^1 = 2 addresses)

[IDisposable]

Looks really cool, can't wait for the kernel system image to support it.

[dlorch]

@IDisposable thank you for sharing the excitement on this feature. As you've noticed, the code needs a lot of work and is not yet ready for line-by-line scrutiny. This PR is in DRAFT state for this reason.

The main things I wanted to learn and that are demonstrated as part of this PoC:

• How to configure USB Gadget Ethernet devices: https://www.collabora.com/news-and-blog/blog/2019/02/18/modern-usb-gadget-on-linux-and-how-to-integrate-it-with-systemd-part-1/
• Different types of USB Ethernet protocols: https://en.wikipedia.org/wiki/Ethernet_over_USB
• How to enable NAT (specifically Source NAT or SNAT) using nftables: https://wiki.nftables.org/wiki-nftables/index.php/Performing_Network_Address_Translation_(NAT)
• How to run commands on bootup of the JetKVM using the init* functions, in what sequence I have to bring up NAT and the USB Ethernet interface for things to work and where those hooks are in the code.

There has been a lot of great improvements lately on network interface management in dev, and there is a lot of potential to re-use that for configuring the USB Ethernet device.