By 苏剑林 | August 02, 2025
A while ago, I got a very mini development board, the Raspberry Pi Zero 2W (hereafter referred to as "Pi"), and paired it with a USB Key adapter board. I've spent the last few days tinkering with it to implement a portable side router. This article records the key technical points for reference by readers with similar needs.
Background
Students who have tinkered with proxies should be familiar with the concept of a "side router" (bypass router), which is mainly used here as a transparent proxy. Nowadays, the relevant technology is quite mature, so building a transparent proxy is not particularly difficult if you have a small host machine. The main focus of this article, however, is on it being "portable," which requires the small host to meet the following characteristics:
1. Compact (otherwise, it's not suitable for carrying around);
2. Equipped with Wi-Fi connectivity;
3. Capable of switching networks at any time.
The third point is the most troublesome. Suppose I bring my laptop and the small host to a new environment and learn the local Wi-Fi credentials; how can I get the small host to connect to the new Wi-Fi? The crux is how the laptop connects to the host when the host isn't yet on the network. If there were an Ethernet port, connecting via a network cable would naturally work, but hosts with Ethernet ports are usually not small, and carrying a network cable is cumbersome (MacBooks also require an adapter).
The Raspberry Pi Zero 2W + USB Key perfectly fulfills this requirement! It can operate as a host while simultaneously simulating a network card. When connected to a computer via the USB port, it can both power the Zero 2W and establish a direct communication channel from the Zero 2W to the computer, allowing us to connect to the Zero 2W without needing Wi-Fi.
Flashing the Image
In fact, this USB direct connection solution for the Pi Zero has been around for a long time. For example, the tutorial "Raspberry Pi Zero USB/Ethernet Connection Configuration Tutorial (macOS platform)" dates back to 2018, but the configuration methods therein are outdated. Here, I am mainly updating the latest solution that works with the help of K2.
First, prepare an SD card and flash the latest Raspberry Pi OS image onto it. With the official Raspberry Pi Imager, flashing the image has become simpler. During the flashing process, take note of a few details: first, you must configure the Wi-Fi credentials (these can be changed later, but the initial configuration needs it), and you must enable SSH. Adjust other settings as needed:
It is recommended to set a hostname and remember it, so that you can later access the Pi directly via the hostname within the local network without having to remember the IP address. After the setup is complete, you can flash the image. Once finished, keep the SD card in the card reader and plug it into your computer (my computer is a MacBook Pro running macOS 15.3.1, hereafter referred to as "Mac"). Find the config.txt file in the root directory of the SD card and add the following line at the end (the current end is [all]):
dtoverlay=dwc2
This completes the image flashing step.
Network Interface Configuration
Now we can insert the SD card into the Pi and then plug the Pi into the Mac via the USB port. The Pi will then power up and boot. Once the boot is complete, since we previously configured the Wi-Fi, the Pi should have successfully connected to the network. At this point, connect the Mac to the same network, and we can SSH into the Pi using ssh me@pi.local. Alternatively, you can find its IP address in the router settings and SSH via the IP.
Next, we execute the following on the Pi:
sudo modprobe g_ether
sudo ip link set usb0 up
sudo ip addr add 169.254.7.11/16 dev usb0
After execution, check with ifconfig; you will find a new network interface named usb0 with the IP set to 169.254.7.11. This is a reserved internal network IP; you can set it yourself, but you can also just copy this if there are no special considerations.
After a short wait, switch to the Mac's "Settings" - "Network." Under normal circumstances, an RNDIS/Ethernet Gadget service will appear and automatically connect. Clicking "Details," you will see an IP assigned via DHCP. Change it to manual mode, with the IP 169.254.7.1 and the Router field left blank. In principle, this IP can also be customized, but you can just copy it if no specific requirements exist.
Switch back to the Pi and run ping 169.254.7.1. If it pings through, it indicates that the Pi and Mac have formed a small local area network via the USB port, where the Mac's IP is 169.254.7.1 and the Pi's IP is 169.254.7.11. On the Mac, you can also connect to the Pi via ssh me@169.254.7.11.
Starting the Service
However, the current network configuration is temporary and will disappear upon restart. We need to configure it as a service that starts automatically at boot so that in the future, even without a network, we can still connect to the Pi via the USB port and ssh me@169.254.7.11. This is our ultimate goal.
On the Pi, create /usr/local/bin/usb0.sh:
#!/bin/bash
sudo modprobe g_ether
sudo ip link set usb0 up
sudo ip addr add 169.254.7.11/16 dev usb0
nohup ping -c 100 169.254.7.1 > /var/log/usb0_ping.log 2>&1 &
exit 0
Then run sudo chmod +x /usr/local/bin/usb0.sh, and create /etc/systemd/system/usb0.service, writing:
[Service]
Type=oneshot
ExecStart=/usr/local/bin/usb0.sh
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
Finally, execute:
sudo systemctl daemon-reload
sudo systemctl enable usb0.service
That's it. In the future, just plug the Pi into the Mac, wait for it to finish booting, and you can connect via ssh me@169.254.7.11. If needed, you can connect to or switch Wi-Fi using sudo raspi-config.
Summary
As for the remaining steps of setting up the side router/transparent proxy, please tinker with them yourself. This article mainly helps you get the "portable" part running; the rest is up to your own exploration.