Advanced users • [HOWTO] Headless configuration of a Raspberry Pi using USB Ethernet Gadget on Bookworm

A method to get a headless configuration of a Raspberry Pi using USB Ethernet Gadget on Bookworm

Summary
This method should allow you to write a fresh Raspberry Pi OS Bookworm image, edit some files on the ‘bootfs’ FAT32 volume, boot the Raspberry Pi using a USB cable connected to a PC (Windows, Linux or MacOS), and have a USB Ethernet connection to the Raspberry Pi to connect using SSH.

This method is very similar to others I’ve seen, but has some advantages:

• Doesn’t require other access, such as local console, SSH over Ethernet, or over Wi-Fi, to edit files, or make changes.
• Uses the native Network-Manager system to manage the connection.
• Supports DHCP, and if not available, falls back to a Link-Local address.
• Supports IPv6.
• Supports mDNS (hostname works).

Questions, feedback and suggestions for improvement are welcome.

Notes
Power

• The Raspberry Pi must only be powered from the host USB connection. Powering the Raspberry Pi from the USB and another power supply could cause damage to the Raspberry Pi and the host computer.
• Powering a Raspberry Pi from a host computers USB port will likely not provide as much power as an official power supply. You should expect to run into power issues on models of Raspberry Pi 4 Model B and above, since they have the highest power demands. See here for more information on power requirements: https://www.raspberrypi.com/documentati ... wer-supply

Raspberry Pi Models this method will work on

• I've listed below the models of Raspberry Pi I have successfully tested this method on. Other models of Raspberry Pi may also work with additional effort. For more information about Ethernet Gadget see here: viewtopic.php?t=306121

Method

1. Using Raspberry Pi Imager write a fresh Raspberry Pi OS (Bookworm) image to the bootable medium of your choice; i.e. MicroSD card or USB Flash Drive. Make sure to customise the image with your preferred hostname, username, and password, and enable SSH.
2. Once the image write has been verified, and RPImager reports the drive can be removed, remove and reinsert the drive so you can edit some files.
3. Edit ‘config.txt’ and add “dtoverlay=dwc2”. I added it to the “[ALL]” section at the end. It should look something like this:
   

   Code:

   [all]dtoverlay=dwc2

4. Edit ‘cmdline.txt’ and add “modules-load=dwc2,g_ether” to the single line, after "rootwait", and before "quiet". It should look something like this:
   

   Code:

   [snip] rootwait modules-load=dwc2,g_ether quiet [snip]

5. Edit ‘firstrun.sh’ and add the following text to the file immediately above the line "rm -f /boot/firstrun.sh":
   

   Code:

   # Remove the rule setting gadget devices to be unmanagendcp /usr/lib/udev/rules.d/85-nm-unmanaged.rules /etc/udev/rules.d/85-nm-unmanaged.rulessed 's/^[^#]*gadget/#\ &/' -i /etc/udev/rules.d/85-nm-unmanaged.rules# Create a NetworkManager connection file that tries DHCP firstCONNFILE1=/etc/NetworkManager/system-connections/usb0-dhcp.nmconnectionUUID1=$(uuid -v4)cat <<- EOF >${CONNFILE1}[connection]id=usb0-dhcpuuid=${UUID1}type=ethernetinterface-name=usb0autoconnect-priority=100autoconnect-retries=2[ethernet][ipv4]dhcp-timeout=3method=auto[ipv6]addr-gen-mode=defaultmethod=auto[proxy]EOF# Create a NetworkManager connection file that assigns a Link-Local address if DHCP failsCONNFILE2=/etc/NetworkManager/system-connections/usb0-ll.nmconnectionUUID2=$(uuid -v4)cat <<- EOF >${CONNFILE2}[connection]id=usb0-lluuid=${UUID2}type=ethernetinterface-name=usb0autoconnect-priority=50[ethernet][ipv4]method=link-local[ipv6]addr-gen-mode=defaultmethod=auto[proxy]EOF# NetworkManager will ignore nmconnection files with incorrect permissions so change them herechmod 600 ${CONNFILE1}chmod 600 ${CONNFILE2}

6. After editing and saving the files above, safely eject the drive and insert into your Raspberry Pi of choice.
7. Boot the Raspberry Pi by powering it from a USB port on your chosen host computer.
8. Practise some patience; depending on the Raspberry Pi model the initial boot and configuration may take a few minutes and a few reboots.
9. From the host computer you should be able to ping the hostname you configured using IPv6 and IPv4:
   

   Code:

   C:\Users\phattmatt>ping raspberrypi.localPinging raspberrypi.local [fe80::2e41:2a92:aca1:69e8%46] with 32 bytes of data:Reply from fe80::2e41:2a92:aca1:69e8%46: time<1msReply from fe80::2e41:2a92:aca1:69e8%46: time<1msReply from fe80::2e41:2a92:aca1:69e8%46: time<1msReply from fe80::2e41:2a92:aca1:69e8%46: time<1msPing statistics for fe80::2e41:2a92:aca1:69e8%46:    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),Approximate round trip times in milli-seconds:    Minimum = 0ms, Maximum = 0ms, Average = 0msC:\Users\phattmatt>ping -4 raspberrypi.localPinging raspberrypi.local [169.254.143.52] with 32 bytes of data:Reply from 169.254.143.52: bytes=32 time<1ms TTL=64Reply from 169.254.143.52: bytes=32 time<1ms TTL=64Reply from 169.254.143.52: bytes=32 time<1ms TTL=64Reply from 169.254.143.52: bytes=32 time<1ms TTL=64Ping statistics for 169.254.143.52:    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),Approximate round trip times in milli-seconds:    Minimum = 0ms, Maximum = 0ms, Average = 0ms

10. You can now attempt to SSH to the Raspberry Pi and check your network config:
    

    Code:

    C:\Users\phattmatt>ssh pi@raspberrypi.localpi@raspberrypi.local's password:Linux raspberrypi 6.6.31+rpt-rpi-v6 #1 Raspbian 1:6.6.31-1+rpt1 (2024-05-29) armv6lThe programs included with the Debian GNU/Linux system are free software;the exact distribution terms for each program are described in theindividual files in /usr/share/doc/*/copyright.Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extentpermitted by applicable law.Last login: Thu Sep 12 16:22:10 2024 from 169.254.162.114pi@raspberrypi:~ $ nmcli connection showNAME       UUID                                  TYPE      DEVICElo         82fb1681-3a2b-4360-8354-4552515850f4  loopback  lousb0-ll    ce0de487-20b6-4c5d-9b03-c5cc371d752e  ethernet  usb0usb0-dhcp  2503e7c1-8272-41d5-8fc3-12bab49e0e4c  ethernet  --pi@raspberrypi:~ $ ip address1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00    inet 127.0.0.1/8 scope host lo       valid_lft forever preferred_lft forever    inet6 ::1/128 scope host noprefixroute       valid_lft forever preferred_lft forever2: usb0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000    link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff    inet 169.254.143.52/16 brd 169.254.255.255 scope link noprefixroute usb0       valid_lft forever preferred_lft forever    inet6 fe80::2e41:2a92:aca1:69e8/64 scope link noprefixroute       valid_lft forever preferred_lft forever3: wlan0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN group default qlen 1000    link/ether yy:yy:yy:yy:yy:yy brd ff:ff:ff:ff:ff:ff

Further steps
Share your host computer's Internet connection with the Raspberry Pi. This will configure a DHCP server and routing that will allow the Raspberry Pi to connect to the Internet via the host computer.

Windows 11
On Windows 11 the sharing option is hidden away on a legacy control panel; search for “View network connections” to open the legacy panel. Find the network connection that your host uses to get Internet access, open the properties page and then the ‘Sharing’ tab. Choose the RNDIS of the Raspberry Pi for the ‘Home networking connection’ option. Once configured, reboot the Raspberry Pi so it can get the DHCP network settings.

MacOS Monterey
The network sharing option can be found in ‘System Preferences’, ‘Sharing’, ‘Internet Sharing’. Select the RNDIS interface of the Raspberry Pi in the “To computers using” option. Once configured, reboot the Raspberry Pi so it can get the DHCP network settings.

Quirks, warnings, and things to note

Windows 11 RNDIS Driver
Windows 11 may identify the USB connection as a serial interface, rather than an RNDIS network device. In my case I identified which serial port it was in Device Manager and updated the driver via ‘Update Driver -> Search automatically for drivers -> Search for updated drivers on Windows Update -> Advanced options -> Optional updates -> Driver updates”. I used a USB Ethernet/RNDIS Gadget driver from ACER and it’s been working fine.

If there is no DHCP it will result in a re-connection
If there is no DHCP then the Raspberry Pi will disconnect at least once before configuring a Link-Local IP address. This is a consequence of Network-Managers behaviour of treating the connection as failed and de-configuring it before moving onto a Link-Local connection.

There is some hope for improvement as there are some changes proposed/merged in a later release of Network-Manager (see references below).

The MAC address of the usb0 device will change on every boot
This may cause problems with DHCP allocation when you are rebooting often. On my Windows 11 network sharing DHCP server I am getting a DHCP lease time of 604800 seconds, which is one week. But I'm not certain how many IP addresses are available (it's a /24 network, so maximum of ~250) , or if the leases are cleared on a Windows reboot.

Testing
I’ve tested this method with the following:

Windows 11 as the host, using Link-Local and DHCP (Network Sharing)

• Raspberry Pi OS 64-bit Lite Bookworm (image dated: 2024-07-04)
  • Raspberry Pi 5 (Host USB-C to RPi USB-C and Host USB-A to RPi USB-C)
  • Raspberry Pi 4 Model B (Host USB-A to RPi USB-C)
  • Raspberry Pi Zero 2 W (Host USB-A to RPi Micro USB Data)
• Raspberry Pi OS 32-bit Lite Bookworm (image dated: 2024-07-04)
  • Raspberry Pi Zero W (Host USB-A to RPi Micro USB Data)

MacOS Monterey as the host, using Link-Local and DHCP (Network Sharing)

• Raspberry Pi OS 64-bit Lite Bookworm (image dated: 2024-07-04)
  • Raspberry Pi 4 Model B (Host USB-A to RPi USB-C)

How does this work
The changes to the files above do the following:

1. The 'config.txt' and 'cmdline.txt' changes tell the Linux Kernel to load the drivers necessary to present an Ethernet networking device that runs over the USB link.
2. The 'firstrun.sh' changes do a few things:
   1. Modifies the UDEV/Network-Manager config so that 'gadget' (RNDIS) devices are no longer ignored by Network-Manager.
   2. Creates a Network-Manager connection profile to configure DHCP on the usb0 Ethernet device, this will be tried first.
   3. Creates a Network-Manager connection profile to configure a Link-Local IP address on the usb0 Ethernet device, this will be tried if DHCP fails.
   4. Changes the permissions of the files so Network-Manager will read them.

References

https://github.com/raspberrypi/linux/issues/5737
https://www.linuxquestions.org/question ... 175672529/
https://www.factoryforward.com/pi-zero- ... -resolved/
https://medium.com/@michi.hammerl/setti ... 93ddf2f80e
viewtopic.php?t=347973
https://www.networkmanager.dev/docs/api ... -ipv4.html
https://gitlab.freedesktop.org/NetworkM ... issues/966
https://gitlab.freedesktop.org/NetworkM ... uests/1187
https://gitlab.freedesktop.org/NetworkM ... ssues/1555
https://gitlab.freedesktop.org/NetworkM ... uests/1980

Statistics: Posted by phattmatt — Thu Sep 12, 2024 4:51 pm — Replies 2 — Views 126

---