Ethernet over USB¶

When updated with a recent image, the USB driver used on the development board allows a network connection to made over the USB cable when the board is used as a USB peripheral. This guide describes how to configure the connection so that the board can access the Internet via the workstation.

Finding the Network Interfaces
Using IPv4
Using IPv6
Troubleshooting

Finding the Network Interfaces ¶

Connect the board to the workstation using the USB cable then check the system log for the appearance of the device:

sudo dmesg | grep rndis_host

This should produce output like the following:

[ 4144.991203] rndis_host 1-2:1.0 usb0: register 'rndis_host' at usb-0000:00:12.2-2, RNDIS device, da:c5:ae:ef:32:72
[ 4144.993363] usbcore: registered new interface driver rndis_host
[ 4145.087029] rndis_host 1-2:1.0 enp0s18f2u1: renamed from usb0
[ 4732.971955] rndis_host 1-2:1.0 enp0s18f2u1: unregister 'rndis_host' usb-0000:00:12.2-2, RNDIS device
[ 4752.177351] rndis_host 1-2:1.0 usb0: register 'rndis_host' at usb-0000:00:12.2-2, RNDIS device, aa:d2:de:22:b0:23
[ 4752.349356] rndis_host 1-2:1.0 enp0s18f2u1: renamed from usb0

In this example output the device appears as enp0s18f2u1 to the system. This can be verified by running ip link command:

ip link

The output should look like the following:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
    link/ether 00:30:18:a1:70:8f brd ff:ff:ff:ff:ff:ff
4: enp0s18f2u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN mode DEFAULT group default qlen 1000
    link/ether 2a:71:82:e2:63:84 brd ff:ff:ff:ff:ff:ff

From the example output we can see that enp0s18f2u1 is the interface to use. The interface on your workstation may be different to this.

The enp3s0 in the above output is the network interface that connects the workstation to the Internet. We want to redirect packets from the board over this interface. The interface on your workstation may be different to this.

Using IPv4 ¶

If you want to use IPv4 networking, follow these instructions to set up a network connection.

Board ¶

Log in to the board as described in USB Serial Console:

picocom -b 115200 /dev/ttyACM0

On the board, choose a local IP address and add it to the usb0 network interface. For example, we can add the 192.168.42.2 address:

sudo ip addr add 192.168.42.2/24 dev usb0

Add a default route via the workstation so that it can access the Internet:

sudo ip route add default via 192.168.42.1 dev usb0

It should be possible to log out of the picocom terminal session and close it with Ctrl-A Ctrl-X. The second half of the configuration process will be done on the workstation.

Workstation ¶

On the workstation, add an address that resides on the same subnet as the address you assigned to the board. In the following example, we add the 192.168.42.1 address to the enp0s18f2u1 interface with the following command:

sudo ip addr add 192.168.42.1/24 dev enp0s18f2u1

The specific interface to use can be found by checking the output of the dmesg command for rndis_host lines such as this one:

[ 6499.216747] rndis_host 1-1:1.0 enp0s18f2u1: renamed from usb0

Enable IP forwarding on the workstation using the following commands:

sudo modprobe ip_tables
sudo sysctl net.ipv4.ip_forward=1

Enable traffic forwarding for the network interface used to access the Internet. In this example, we enable forwarding for the enp3s0 interface:

sudo /usr/sbin/iptables -t nat -A POSTROUTING -o enp3s0 -j MASQUERADE

Again, the interface used for forwarding will be the one that your workstation normally uses to access the Internet. Run ip route to see the list of routes and look for the default entry.

Testing the Connection ¶

Test that USB networking is functioning by using ssh to log in to the board with the 192.168.42.2 address we assigned to it:

ssh purism@192.168.42.2

This should function in the same way as described in Ethernet Connection. If problems occur, see the Troubleshooting section for advice.

Using IPv6 ¶

If you prefer to use IPv6 networking, follow these instructions to set up a network connection.

Workstation ¶

On the workstation, assign a local address to the network interface for the board. In the following example, we add the fe80::1234 address to the enp0s18f2u1 interface:

sudo ip -6 addr add fe80::1234/64 dev enp0s18f2u1

Enable traffic forwarding for the network interface used to access the Internet. In this example, we enable forwarding for the enp3s0 interface:

sudo /usr/sbin/ip6tables -t nat -A POSTROUTING -o enp3s0 -j MASQUERADE

Log in to the board as described in USB Serial Console:

picocom -b 115200 /dev/ttyACM0

The second half of the configuration process will be done on the board.

Board ¶

On the board, run the following command to show information about the usb0 interface:

ip addr show dev usb0

This should produce output like the following:

3: usb0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 36:e1:86:17:d6:5d brd ff:ff:ff:ff:ff:ff
    inet6 fe80::34e1:86ff:fe17:d65d/64 scope link
       valid_lft forever preferred_lft forever

The board will be allocated a different address each time it boots. Make a note of the address given in the output: fe80::34e1:86ff:fe17:d65d in this case.

Add a default route that sends network traffic via the workstation’s address:

sudo ip -6 route add default via fe80::1234 dev usb0

It should be possible to log out of the picocom terminal session and close it with Ctrl-A Ctrl-X.

Testing the Connection ¶

Test that USB networking is functioning by using ssh to log in to the board, in this case using both the fe80::34e1:86ff:fe17:d65d address and enp0s18f2u1 interface we found above:

ssh purism@fe80::34e1:86ff:fe17:d65d%enp0s18f2u1

This should function in the same way as described in Ethernet Connection. If problems occur, see the section below for advice.

Troubleshooting ¶

If a connection cannot be made, here are a few things that are useful to check.

For IPv4 networking, check the iptables rules on the workstation:

sudo /usr/sbin/iptables -L -t nat -v

For IPv6 networking, use ip6tables instead:

sudo /usr/sbin/ip6tables -L -t nat -v

It may also be useful to log in to the board using picocom and list the routes for IPv4 and IPv6 networking:

ip route
ip -6 route

Check that the default route is present for the kind of network you are using.

It can also be useful to check the routes on the workstation. If you do not have IPv6 routing enabled then IPv6 traffic forwarding to the Internet via the workstation will not work.