_   _          _  ____      
    | | | |        (_)/ ___|     
    | |_| |__   ___ _/ /___  ___ 
    | __| '_ \ / _ \ | ___ \/ __|
    | |_| | | |  __/ | \_/ |\__ \
     \__|_| |_|\___| |_____/|___/
                  _/ |           

             │ hire me │

Network bridging for PI Zero

Tags: linux The Raspberry PI Zero is a wonderfull small Linux computer that takes the Raspberry Pi appeal to the next level: The even more compact form factor allows for some serious applications where space is limited.

However, the small size comes at a cost: The regular PI Zero does not have any networking capabilities and even the PI Zero W which has WiFi onboard sometimes lets the user desire a proper wired connection.

This article explains, how to configure a temporary network bridge in order to share your computers network connection to the pi. It assumes, that your workstation is running some flavour of linux. This method has been tested with debian, but should work on all distributions.

Our network will look something like the following, with our workstation sitting between our network and the pi. You can think of the term “bridging a network” as holding together some wires in order to get a connection. In this instance our workstation will “hold together the wires” in order to let the pi connect to the network.

----------         ---------------        ------
| Router |  <--->  | Workstation |  <---> | PI |
----------   LAN   ---------------   USB  ------
          (or WIFI)                  

Setup the pi: enable SSH via USB

Setting up the PI to use the USB connection as network link is already well documented, so I will not loose any more words on the topic. Here are a couple of links in order to set your pi up:

In case you are having issues, try the following things recommended by the second article:

  • Ensure, that you have the avahi-daemon installed and running on your workstation.
  • Ensure, that avahi-browse -alr is finding the SSH Service advertised by the pi.
  • Set the IPv4 and IPv6 methods to “Link local only” (This assumes, that you are using network-manager)


The following tools will be needed in order to follow the steps in this post:

  • brctl: An easy CLI interface to create and manage bridged interfaces. Intallable on debian via sudo apt-get install bridge-utils and on arch via sudo pacman -S bridge-utils
  • dhcpcd: DHCP Client that will help us finding IPs for all interfaces. Installable on debian via sudo apt-get install dhcpcd and on arch via sudo pacman -S dhcpcd

Creating a bridge

At this point you should

  • be able to connect to the PI via SSH over USB, but not be able to access the internet from it.
  • have installed the packages metioned above

Note for the following passages: I will assume, that the network interface on the PI-end is named usb0 while the network interface on the internet-end is named eth0. If you are using WiFi, then your second interface will likely be named wlp2s0 or wifi0. If you are unsure about the names of your interfaces, use sudo ip link list or sudo ifconfig in order to find them out.

To start of, we need to bring our network interfaces into promiscuous mode. “What is promiscuous mode?” I hear you ask. By default network interfaces will only pass on packets that are intended to be received by the current machine and discard everything else before it passes on to the CPU. In order to bridge networks our workstation must be able to accept packets that are not intended for it, but for the PI and for machines on the other side of the network. Promiscuous mode enables this behaviour.

# Bring both interfaces into promiscuous mode
sudo ip link set eth0 promisc on
sudo ip link set usb0 promisc on

Now, we must create a new bridge that will end up connecting the two networks. In this instance I will name that bridge interface br0 to conform with the network interface naming conventions, but you are free to pick anything else.

# Creating a new bridge interface
sudo brctl addbr br0

# Set the forwarding delay to 0.
# While this is not necessarry, I learned that it help with faster configuration
sudo brctl setfd br0 0

# Add the two interfaces to the bridge
sudo brctl addif br0 eth0 usb0

# Bringing the bridge interface up
sudo ip link set br0

At this point you have successfully bridged the two networks, but it is somewhat likely that internet connections are not available on both devices. This comes from the bridge interface not having an IP assigned to it. While I know, that this is technically not always needed, it has proven to resolve a lot of problems in the past.

# Enable DHCP on br0
sudo dhcpcd br0

At this point you should be able to

  • Connect to the PI from your workstation
  • Connect to the internet from your workstation
  • Connect to the internet from the PI
  • Connect to other computers on the network to the PI.

Basically your PI is now a full client on your network.

Congratulations, you have bridged your networks

Cleaning up

After you have done your business you have to clean up the configurations you just created:

# Disable bridge interface
sudo ip link set br0 down

# Delete bridge interface
sudo brctl delbr br0

# Disable promiscuous mode 
sudo ip link set eth0 promisc off
sudo ip link set usb0 promisc off