Ethernet_over_USB.rst 7.16 KB
Newer Older
1 2
.. _devkit_ethernet_usb:

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
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: <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.

58 59
Board
~~~~~
60

61
Log in to the board as described in :ref:`imx8_devkit_usb_console`::
62

63
   picocom -b 115200 /dev/ttyACM0
64

65 66
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::
67

68
   sudo ip addr add 192.168.42.2/24 dev usb0
69

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

72
   sudo ip route add default via 192.168.42.1 dev usb0
73

74 75 76
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.
77

78 79
Workstation
~~~~~~~~~~~
80

81 82 83 84
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::
85

86
   sudo ip addr add 192.168.42.1/24 dev enp0s18f2u1
87

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

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

93
Enable IP forwarding on the workstation using the following commands::
94

95 96
   sudo modprobe ip_tables
   sudo sysctl net.ipv4.ip_forward=1
97

98 99 100 101 102 103 104 105
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.
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207

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: <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 :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.