.. _devkit_ethernet_usb:
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.
.. contents::
:local:
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: 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: 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: 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 :ref:`imx8_devkit_usb_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 :ref:`imx8_devkit_ethernet`.
If problems occur, see the :ref:`devkit_howto_usb_ethernet_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 :ref:`imx8_devkit_usb_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: 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 :ref:`imx8_devkit_ethernet`.
If problems occur, see the section below for advice.
.. _devkit_howto_usb_ethernet_troubleshooting:
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.