$ lsusb
...
Bus 001 Device 005: ID 0b95:1790 ASIX Electronics Corp. AX88179 Gigabit Ethernet
...

$ lsusb
...
Bus 001 Device 012: ID 0bda:8153 Realtek Semiconductor Corp.
...

# lsusb -vd 0b95:1790
Bus 001 Device 005: ID 0b95:1790 ASIX Electronics Corp. AX88179 Gigabit Ethernet
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.10
  bDeviceClass          255 Vendor Specific Class
  bDeviceSubClass       255 Vendor Specific Subclass
  bDeviceProtocol         0 
  bMaxPacketSize0        64
  idVendor           0x0b95 ASIX Electronics Corp.
  idProduct          0x1790 AX88179 Gigabit Ethernet
  bcdDevice            1.00
  iManufacturer           1 ASIX Elec. Corp.
  iProduct                2 AX88179
  iSerial                 3 000050B6152E37
...
    MaxPower              248mA
...
      iInterface              4 Network_Interface
...

(Here after renaming the devices with systemd, but more about that later.)

## The speedy network on a Raspberry Pi ##

Well, it only is twice as fast as the 100MBit ethernet, but still: The possibilities on the USB bus could be known better. And with those USB ethernet adapters working out of the box there is no reason not to have this tool in the box.


### The standard ethernet port ###

With an `sudo pacman -S iperf` on several nodes (or sudo salt '*' pkg.install iperf on a helotism installation  with SaltStack) "iPerf The TCP, UDP and SCTP network bandwidth measurement tool" https://iperf.fr/ is available (only dependencies are gcc-libs) and can be started on server mode on one node:

(Later ended with Ctrl C.)

The other node then connects to the server by IP or hostname. Here the iPerf server was started on node spoke02, and some other node connects to it:

The **94.2 Mbits/sec** are the connection at the ethernet port.


### The USB adapter is twice as fast ###

The exact IP addresses are not important here, as this example connects to a Netgear WNDR3800 router running OpenWRT.

The **179 Mbits/sec** are about twice the speed. Of course this does not perform magic.
If in the following visualization the nodes "spoke01" and "spoke02" are connected to "axle" via a switch, with "axle" connected to the switch through the standard ethernet port, then there is no way "spoke01" and "spoke01" will get more than roughly 50 MBit/sec throughput to the uplink router.

![Visualization of possible speed test scanarios](/technology/physical/building-blocks/images/usb-ethernet-adapter.png)

But all these performance measurements are not the full picture as a second network adapter offers many more capabilities than just its speed.

In this text the wording "USB Gigabit Ethernet Adapter" was carefully avoided as the USB 2.0 ports will not provide anthing near such speeds for the adapter.

## Configuring an USB ethernet adatper with systemd ##

To integrate these adapters into the network setup their location on the USB bus is of interest. A quick way to find their physical location is using `udevadm info` with the device path. Here lan0 is the renamed ethernet port of a Raspberry Pi 3 b:

The DEVPATH and ID_PATH variables give the physical location which can be used later in a convenient way with systemd.

Repeating this udevadm call with USB ethernet adapters on several USB ports reveals this layout:

![The installation workflow](/technology/physical/raspberry-pi/rpi-3-b_udev_ID_PATH.png)

Here is the DEVPATH on the lower left USB port:

So the physical location varies like

- ID_PATH=platform-3f980000.usb-usb-0:1.**1**:1.0
- ID_PATH=platform-3f980000.usb-usb-0:1.**3**:1.0


### The structure of systemd network device configuration ###

There are

- device configuration *"foobar.**link**"* ([man page](https://www.freedesktop.org/software/systemd/man/systemd.link.html)) and

- network configuration *"foobar.**network**"* ([man page](https://www.freedesktop.org/software/systemd/man/systemd.network.html)) files

with the device configuration being called by a udev component. As usual with systemd, their location bay be in three different places, namely */usr/lib/systemd/network*, */run/systemd/network* or */etc/systemd/network* with files in */etc* having the highest priority.

#### The .link device configuration

This files contains the two sections **[Match]** and **[Link]** and it is the [Match] section where the USB bus location comes in handy: It pays to read all systemd documentation carefully for the the word "glob":

>[Match] Section Options
>
>Path=
>A whitespace-separated list of shell-style **globs** matching the persistent path, as exposed by the udev property "ID_PATH".

Globbing means more than just the wildcard with asterisks, but also character lists in square brackets, [amongst other things](http://www.tldp.org/LDP/abs/html/globbingref.html).

So a `Path=platform-3f980000.usb-usb-0:1.[245]:1.0` does match the three ports besides the lower left one.

Which makes it trivially easy to not just rename the device (a HUGE discussion when systemd first hit the distros) but also set the maximum MTU or configure WOL wake on lan.

Even a random MAC address can easily be achieved, something can might come handy when testing an initial setup and forcing a DHCP server to hand out a new IP address every time:

On the other hand a fixed device name like seen above is configured with:

The above means that on the lower left USB port a USB ethernet adapter will always be given the device name uwan0 (which might stand for USB WAN area device 0, but can be freely chosen).

Of course the udev-way of writing into udev rule files is also possible. But there is a certain elegance in this and its sibling config file to complete a network configuration:

#### The network configuration

With such a fixed device name a basic network configuration looks like this:

As uwan0 will only be applied to devices in that lower left USB port this is a rock-solid setup to link the Helotism cluster to an uplink router and get a dynamic IP address.

The [man page](https://www.freedesktop.org/software/systemd/man/systemd.link.html) list several example configurations at the end of the page.

A lightweight DHCP server is available, although not used in the Helotism project as Dnsmasq offers additional features.

One of the basic requirements of the Helotism project is to provide several network-related capabilities:

![The installation workflow](/business/marketing/images/helotism-scope.png)

The **router** capability is very easily achieved with this setting in one of the `.network` files:

The options `IPForward` and `IPMasquerade` are all that is needed to turn that board into a router:

- `IPForward` does set the sysctl setting ip_forward

- `IPMasquerade` does set an iptables rule in the nat chain for POSTROUTING:

The behaviour might change in the future from iptables to nftables: [[systemd-devel] [HEADSUP] nspawn/networkd: moving from iptables to	nftables](https://lists.freedesktop.org/archives/systemd-devel/2015-May/032531.html), so following the [change log ](https://github.com/systemd/systemd/blob/master/NEWS) is always a good idea.

As visible above the setting is to enable masquerading **on all devices**. If this behaviour is not desired, of course iptables can be configured as usual (minus the settings in the .network files).

Overall a very convenient configuration.

## A minimal example ##

An USB ethernet adapter plugged into a current ArchLinuxARM installation is automatically detected, without the need for a `.link` configuration file. Here the output of a 2016 version of the "Belkin B2B048 USB 3.0 Gigabit Ethernet Adapter":

Without any renaming done on udev level the preditive device name is:

The bad news is: This name `enxa0cec81ebdda` is the same for all four USB ports! So for any etwork devices of importance it may be better to standardize the name with a `.link` configuration file.

But as a minimal example for a second network device on a Raspberry Pi the following configuration gives full control over a second IP address:

Or for a static address: