This topic contains guidelines for using the target platform as a network bridge between two networks.

Requirements

To make a target platform act as a network bridge between two networks:

  • The target platform must have at least two network interfaces (either wired or wireless).

  • The Linux kernel image of the target platform must support network bridging. By default, the Linux kernel compiled with Digi Embedded Yocto already supports bridging.

Methods

There are two methods for connecting a pair of networks:

  • Bridging: The platform device acts like a tunnel that connects the two networks (or two network segments), forming one big subnet that allows devices to connect to each other without the need for routers.

  • IP forwarding: The platform device translates the address of a packet to a new destination according to a routing table.

The following instructions explain the bridging method.

Access point bridging

This chapter illustrates how to configure a target platform to act as a network bridge. Consider the following scenario:

  • A target platform embedded device acts as the bridge.

  • The target is connected through one wired Ethernet interface to a wired LAN that has access to the Internet.

  • There are three Wi-Fi devices to connect by bridge.

  • There is no Wi-Fi AP, so the Wi-Fi devices cannot access the LAN.

Network bridging diagram

By configuring the platform as a bridge, you can connect the three Wi-Fi devices to the LAN and gain access to the Internet.

A network bridge can be established between two network interfaces of any kind: two wired Ethernets, a wired Ethernet and a USB-Ethernet gadget, a USB-Ethernet gadget and a Wi-Fi interface, and so on.

This topic demonstrates how to establish a network bridge between a wired Ethernet (eth0) and a Wi-Fi interface in AP mode (wlan0), including how to configure the Wi-Fi interface. You can follow similar steps to create the bridge between arbitrary network interfaces as long as you configure each interface properly.

Digi programs one MAC address for the Wi-Fi interface during manufacturing of the SOM. This is the MAC address used for the wlan0 interface. The Wi-Fi chip supports up to three other virtual MAC addresses that you need to program before using (otherwise they have default values). See [{XREF_yocto_r_uboot-environment-variables}] for instructions.

Network bridging support on the kernel

Network bridging support on the kernel requires the following options:

Networking support -->
    Networking options -->
        [*]  802.1d Ethernet Bridging (CONFIG_BRIDGE)
        [*]  IGMP MLD snooping (CONFIG_BRIDGE_IGMP_SNOOPING)
These options are enabled by default on Digi Embedded Yocto kernel configuration.

Configure NetworkManager

For the bridge to work, you must prevent the Network Manager daemon from managing the network interfaces involved in the bridge.

Add the relevant network interfaces (in the example eth0 and wlan1) to the list of unmanaged-devices in /etc/NetworkManager/NetworkManager.conf.

/etc/NetworkManager/NetworkManager.conf
[main]
plugins=ifupdown,keyfile
no-auto-default=type:ethernet
rc-manager=file

[ifupdown]
managed=false

[keyfile]
unmanaged-devices=interface-name:p2p*;interface-name:wlan1;interface-name:eth0
 
[device]
wifi.scan-rand-mac-address=no

Restart the Network Manager daemon to use the new configuration:

~# systemctl restart NetworkManager.service

Wired network interface

Make sure the wired network interface is connected to the network and bring it up:

~# ifconfig eth0 up

Wireless network interface

Bring the Wi-Fi interface down to reconfigure it:

~# ifdown wlan1

Configuration as SoftAP

Configure the Wi-Fi interface as SoftAP. Edit the file /etc/network/interfaces and type the following for the Wi-Fi interface:

/etc/network/interfaces
auto wlan1
iface wlan1 inet manual
        post-up systemctl start hostapd@wlan1.service
        pre-down systemctl stop hostapd@wlan1.service

This configuration:

  • Sets the Wi-Fi interface as manual so that it doesn’t get an IP when it is brought up.

  • Calls the systemd service hostapd@wlan1.service that runs the hostapd daemon.

Configure the connection settings of your wireless interface at file /etc/hostapd_<iface>.conf on your target’s root filesystem. The following example shows a configuration that uses WPA-PSK/AES authentication with SSID my-bridge-ap:

/etc/hostapd_wlan1.conf
ctrl_interface=/var/run/hostapd
ctrl_interface_group=0
interface=wlan1
driver=nl80211
 
# WPA2-AES encryption
ssid=my-brigde-ap
auth_algs=1
wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=CCMP
wpa_passphrase=password-wpa2aes
 
# IEEE 802.11ac
hw_mode=a
channel=36
ieee80211ac=1
ieee80211n=1

Start the Wi-Fi interface as SoftAP

Bring the interface up with the new SoftAP configuration:

~# ifup wlan1

Bridge interface

Create the bridge interface br0:

~# brctl addbr br0

Remove the IP addresses of the two network interfaces that the bridge will join (in this example eth0 and wlan1).

~# ifconfig eth0 0.0.0.0
~# ifconfig wlan1 0.0.0.0

Add each network interface to the br0 bridge:

~# brctl addif br0 eth0
~# brctl addif br0 wlan1

Verify the bridge lists the two interfaces:

~# brctl show
bridge name    bridge id              STP enabled   interfaces
br0            8000.0004f3280000      no            eth0
                                                    wlan1

If the interfaces are not correctly listed as associated to the bridge, delete the bridge and recreate it. To remove the bridge and restart the procedure, do the following:

~# ifconfig br0 down
~# brctl delbr br0

Assign a static or dynamic IP address to the bridge.

This step is optional but recommended if you want to reach the bridge (the target platform) in the network.

~# ifconfig br0 192.168.1.5 netmask 255.255.0.0

Bring the bridge up:

~# ifconfig br0 up

Configuration is complete. Your Wi-Fi devices should now be able to connect to the target platform (acting as SoftAP), and reach any device in the LAN network, or the Internet (if the LAN has access to it).

Create the bridge interface automatically at boot time

To automatically create the bridge interface at startup, edit /etc/network/interface and add the following lines at the end of the file:

/etc/network/interfaces
auto br0
iface br0 inet static
	bridge_ports eth0 wlan1
	address 192.168.1.5
	netmask 255.255.0.0
The bridge must appear as the last item in the file to make sure the involved interfaces exist when the bridge is created.

Client side bridging (Wi-Fi extender)

For a Wi-Fi extender configuration both the AP and the client sides needs to be bridged. This configuration allows to extend a wireless LAN across a Wi-Fi direct bridge, effectively extending the LAN.

802.11 4 address mode

The 802.11 standard uses three fields on the MAC frame to carry layer 2 MAC address information. This 3 address model does not support client side bridging as the source MAC address is dropped on the frames transmitted between AP and station. To overcome this limitation, 802.11 defines an optional 4 address mode. The 802.11 standard only provisions the extra field without providing implementation details.

Several OEMs use this 4 address mode to implement Wi-Fi extender features, for example for Wireless Distribution Service (WDS). These implementations are non-standard and require matching hardware and software on all devices, and usually require softMAC chipsets, that is, chipsets that use the mac80211 layer on the Linux kernel. This softMAC devices usually suffer from a performance penalty compared to devices that implement their own MAC layer in hardware (hard MAC).

The Qualcomm QCA6574 chipset is a hard MAC device and 4 address mode is not currently supported.

Wi-Fi extender with BATMAN layer 2 protocol

However, Wi-Fi extender can be implemented by using a layer 2 routing protocol to provide the source address resolution missing from the 3 address 802.11 mode.

The setup below uses the BATMAN (Better Approach to Mobile Adhoc Networking) layer 2 protocol implemented as a driver in the Linux kernel:

Client side bridging for Wi-Fi extender using BATMAN

  • Configure the Linux kernel with support for BATMAN advanced.

Networking support -->
     Networking options -->
	[*]  B.A.T.M.A.N Advanced Meshing Protocol (CONFIG_BATMAN_ADV)
These options are enabled by default on Digi Embedded Yocto kernel configuration.

  • Set up a Wi-Fi direct link, for example using the Negotiated GO method described at Wi-Fi Direct.

  • Add the P2P interface to the BATMAN interface at both ends:

~# batctl if add p2p-p2p0-0
~# ip link set up dev bat0

  • Bridge the wired Ethernet and BATMAN interface at both ends:

~# ifconfig eth0 0.0.0.0
~# ifconfig bat0 0.0.0.0
~# brctl addbr br0
~# brctl addif br0 eth0
~# brctl addif br0 bat0
~# ifconfig br0 up

The network will take up to 30 seconds to be established as the nodes need to discover each other. Devices at both sides of the bridge should now be configured on the same subnet and will be able to ping each other.

Automatic Wi-Fi extender setup

To automatically establish a Wi-Fi extender link between p2p0 and eth0, configure NetworkManager as follows:

  1. Edit the /etc/NetworkManager/NetworkManager.conf file specify the unmanaged interfaces involved in the bridge:

    /etc/NetworkManager/NetworkManager.conf
    [keyfile]
unmanaged-devices=interface-name:p2p*;interface-name:wlan*;interface-name:eth*;interface-name:bat*

  2. Add a new br0 connection with a p2p-bridge connection ID to /etc/NetworkManager/system-connections/:

    ~# nmcli con add type bridge ifname br0 con-name p2p-bridge ip4 <local_bridge_IP>/24

    Replace the <local_bridge_IP> above with the IP address you want to assign to the local bridge.

    That command will create the file shown next:

    /etc/NetworkManager/system-connections/p2p-bridge.nmconnection
    [connection]
id=p2p-bridge
type=bridge
interface-name=br0

[ipv4]
address1=<local_bridge_IP>/24
dns-search=
method=manual

[ipv6]
addr-gen-mode=stable-privacy
dns-search=
method=auto

  3. Edit the /etc/network/interfaces file to add the P2P peer MAC address to the p2p0 interface:

    /etc/network/interfaces
    p2p-peer-mac AA:BB:CC:AA:BB:CC

    Use the MAC address associated with the p2p0 interface. For example, for the following device:

    ~# iw dev
phy#0
        Interface p2p0
                ifindex 7
                wdev 0x2
                addr 02:04:f3:8d:40:03
                type managed
                txpower 0.00 dBm
        Interface wlan0
                ifindex 6
                wdev 0x1
                addr 00:04:f3:8d:40:03
                type managed
                txpower 0.00 dBm
If you want to use interfaces other than p2p0 and eth0 modifications in the script source are required.