intona IN3032UG User manual

IN3032UG: Ethernet Debugger User Guide
The information disclosed to you hereunder (the “Materials”) is provided solely for the selection and use
of Intona products. To the maximum extent permitted by applicable law: (1) Materials are made available
”AS IS” and with all faults, Intona hereby DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS,
IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE; and (2) Intona shall not be liable
(whether in contract or tort, including negligence, or under any other theory of liability) for any loss or damage
of any kind or nature related to, arising under, or in connection with, the Materials (including your use of the
Materials), including for any direct, indirect, special, incidental, or consequential loss or damage (including
loss of data, profits, goodwill, or any type of loss or damage suffered as a result of any action brought by
a third party) even if such damage or loss was reasonably foreseeable or Intona had been advised of the
possibility of the same. Intona assumes no obligation to correct any errors contained in the Materials or to
notify you of updates to the Materials or to product specifications. You may not reproduce, modify, distribute,
or publicly display the Materials without prior written consent. Intona products are not designed or intended
to be fail-safe or for use in any application requiring fail-safe performance.
© Copyright Intona Technology GmbH, Germany.
Intona and other designated brands included herein are trademarks of Intona in Germany and other countries.
All other trademarks are the property of their respective owners.
Website: https://intona.eu

Contents
1 Introduction 4
1.1 Features.............................................. 4
1.2 Requirements........................................... 4
1.3 Restrictions............................................ 4
1.4 Firmware Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.1 Firmware 1.09 (unreleased) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.2 Firmware 1.08 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.3 Firmware 1.06 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.4 Firmware 1.00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5 Host Tool Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.1 Host tool git master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.2 Host tool v1.4 (60a3f48, windows build 66) . . . . . . . . . . . . . . . . . . . . . . 6
1.5.3 Host tool v1.3 (cfbdb79, windows build 64) . . . . . . . . . . . . . . . . . . . . . . 7
1.5.4 Host tool v1.2 (ff97f53) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5.5 Host tool v1.1 (686fe4f) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5.6 Host tool v1 (f5eed9c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2 Hardware Setup 8
2.1 LEDMeaning ........................................... 8
2.1.1 PortLEDs......................................... 8
2.1.2 MainLED ......................................... 8
3 Software Installation 9
3.1 Linux................................................ 9
3.2 macOS .............................................. 9
3.3 Windows ............................................. 9
3.4 Verifying Device Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5 Wireshark extcap Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5.1 Linux,macOS....................................... 10
3.5.2 macOS (app bundle) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.5.3 Windows ......................................... 11
3.6 Firmware Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.6.1 Unix-like ......................................... 11
3.6.2 Windows ......................................... 12
4 Capturing 13
4.1 Wireshark extcap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.1 Capturing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.2 Wireshark extcap Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Directly Starting Wireshark from Host Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Statistics ............................................. 14
4.4 Capturing to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.5 Selecting the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.6 Configuring the Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5 Other Features 15
5.1 PoE Passthrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 PTPTimestamps......................................... 15
5.3 Supported Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.4 Interactive Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.5 Scripting.............................................. 16
5.6 Supported Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.7 IPCInterface ........................................... 17
5.7.1 Windows ......................................... 17
2

Contents
5.7.2 UNIX (Linux/Mac) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.7.3 Protocol.......................................... 18
5.8 Identify Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.9 LatencyTester .......................................... 20
5.9.1 Introduction........................................ 20
5.9.2 Instructions........................................ 20
5.10 Packet Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.11BlockingPorts .......................................... 24
5.12 Packet Disruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.13MDIOAccess........................................... 25
5.13.1 Raw MDIO access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.13.2 Changing PHY Ethernet Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.14 Device Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6 Known Problems 26
7 Further Readings 26
7.1 WhitePapers........................................... 26
7.1.1 Ethernet Debugger Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
7.2 Statements ............................................ 26
7.2.1 Letter of Volatility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3

1 Introduction
1 Introduction
The Intona Ethernet Debugger is a device to capture packets between two Gigabit Ethernet devices. It
provides two ethernet ports, and each port forwards all traffic to the other port, as well as to a PC con-
nected via USB. The intended purpose is low level debugging of anything above the ethernet physical
layer, mainly using Wireshark and similar protocol analyzers. It helps when developing your own proto-
cols layered on top of ethernet, developing your own MAC, or just for observing what is going on on your
network.
1.1 Features
This device can log complete ethernet packets as received by the PHY. There is no processing of captured
packets – preamble, SFD, and FCS are all left intact. Packets with incorrect CRC sums are not discarded.
Ethernet packets which violate the specification are captured as far it is possible. Some normally invisible
low level details are explicitly logged, such as interpacket gaps and CRC errors. Jumbo frames (ethernet
packets longer than 1500 bytes) are supported and fully captured up to 16KB size.
Capture output is directly streamed to the PC. There is no kernel device driver. The device is accessed
through a libusb userspace driver. You do not necessarily need elevated privileges. Installing the device
will not destabilize your system. In particular, the device is not exposed as network device. This has the
advantage that your OS will not mess with it. Neither will it attempt to drop or filter packets received
through it, nor will it attempt to send random packets to it (ARP etc.). The latter would show up in
Wireshark, and confuse your development efforts.
Capture can be directly started from Wireshark (if installed correctly). The userspace driver also provides
a command line interface, which can be used to access advanced feature. An IPC interface is provided
for use cases like scripting.
The debugger can block packets in one or both directions, corrupt packets, inject new packets. This is
interesting for development and security research. (For example, you can test resilience of your ethernet
connected device or software against random packet drops, test its behavior on flooding, or implement a
network stack fuzzer.)
There are many other features. See Other features section.
1.2 Requirements
The software works on Windows, Linux, and macOS. We provide an installer for Windows. Windows 10
64 bit is required, but Windows 7 may work as well. For macOS, a homebrew tap is provided1. For Linux,
source code and build instructions are provided2, which should work on any Linux distro.
USB 3.0 or later host and cable are recommended. USB 2.0 may work in low bandwidth scenarios. Us-
ing an USB hub, and/or connecting multiple USB devices to an USB hub/host may reduce the maximum
bandwidth at which capture is possible without capture overflows.
1.3 Restrictions
Ethernet is intercepted by putting two PHYs between the two ports. There is no direct connection between
the ethernet TX/RX wires of the ports. Each PHY negotiates the ethernet connection separately. No link
can be established without USB power.
1https://github.com/intona/homebrew-ethernet-debugger
2https://github.com/intona/ethernet-debugger#build-instructions
4

1 Introduction
Old firmware (before 1.06) requires the user to set the ethernet speed manually if the devices connected
to the debugger’s ports negotiated different ethernet standards (for example 100 MBit vs. 1 Gb).
The PC needs to be fast to capture at full speed. Capturing in real time with maximum ethernet bandwidth
directly to Wireshark or a slow hard disk may not be possible. (This is due to host performance problems
outside of our control.) Packet buffer overflows should be expected when operating near maximum band-
width. There is no hardware packet filter.
1.4 Firmware Changelog
The firmware version is reported in the bcdDevice field in the USB device descriptor, or can be determined
by using the ”hw_info” command in the host tool.
1.4.1 Firmware 1.09 (unreleased)
Updating to host tool v1.5 is recommended.
Bug xes
•Fix hardware FIFO overow problems with high bandwidth and very small packets (possibly
out-of-spec)
•Fix capture corruption problems in some rare low bandwidth capture scenarios
1.4.2 Firmware 1.08
Updating to host tool v1.3 is recommended.
Bug xes
• Fix occasional packet corruption with some links in 100 MBit mode (this affects both packet capture
and ethernet communication)
• Hopefully fix 10 MBit mode
• Improve speed settings handling (always enable auto negotiation and control advertisings instead)
• Work around a FX3 issue that made firmware updates under USB 2 very slow
Potential incompatibilities and problems
• The ”inject” command now works only if both links are connected and use the same speed mode
1.4.3 Firmware 1.06
Updating to host tool v1.2 is recommended.
Bug xes
• Fix device becoming unable to capture packets on FIFO overflows
Potential incompatibilities and problems
• This is compatible down to host software v1, but host software v1.2 is recommended; there may be
strange behavior with host software v1 in certain cases
• The device accesses some MDIO registers automatically now, instead of leaving the host software
in full control
New features
• Add autospeed mode (do not require user to manually adjust each PHY’s speed if they have negoti-
ated different speeds)
• The autospeed setting is persistently stored on the device
5

1 Introduction
• Improved packet timestamp accuracy
1.4.4 Firmware 1.00
• Initial release.
1.5 Host Tool Changelog
The host tool’s version can be determined with the ”hw_info” command, or simply running ”nose
--version”.
Note: you can also look at the public git repository’s commit log.
1.5.1 Host tool git master
Unreleased, but publicly available. (Also picked up by Homebrew formulae.)
May be referenced as host tool v1.5 in this document.
Potential incompatibilities and problems
•Improvements to packet parsing (including rmware v1.09 specics), which should not cause
any problems, but could
•Change ”Bytes captured” display in the capture stats, uses different rounding
Bug xes
•Skip possibly old data when starting capture
•Fix description of some hw_info elds
•Fix undened behavior in USB error handling path
New features
•Add --nopad, --bw-bytes, --bw-packets parameters to ”inject” command
•Add --update parameter to ”hw_info” command
•Add --capture-speed-test command line option
1.5.2 Host tool v1.4 (60a3f48, windows build 66)
Potential incompatibilities and problems
• Change auto-exit behavior (should be mostly the same for most users, but use with scripting might
be affected)
• Change --exit-on option in an incompatible way
Bug xes
• Fix sporadic hangs when nose exits (these could even hog the USB device and prevent restarting
capture)
• Handle unusual preamble lengths better (for example, do not cut off data bytes at the start of the
packet on short preamble)
New features
• Option to strip FCS (CRC field) from captured data (--strip-fcs)
6

1 Introduction
1.5.3 Host tool v1.3 (cfbdb79, windows build 64)
Bug xes
• Correct doubled injector packet count reported by hw_info command
• Work around problems with libreadline 8.1
• Fix ”inject” command (may need firmware 1.08 for larger packets)
• Adjust maximum packet size capture limits
New features
• Latency tester feature
• Tab completion (if built with readline; dysfunctional on Windows)
• New options: --cmd, --run, --exit-on, --exit-timeout
1.5.4 Host tool v1.2 (ff97f53)
Updating to firmware 1.06 is recommended.
Potential incompatibilities and problems
• Firmware update is now invoked differently
• Changes to inject and disrupt command parameters
Bug xes
• In Wireshark extcap mode, terminate properly if no packets were captured
New features
• Full support for firmware 1.06
• Slightly improved link status reporting
• Extend capabilities of inject and disrupt commands
• Change USB device name format and include device address (allows distinguishing multiple devices
connected to chained hubs)
• Accept device serial number as device name and report it via extcap to Wireshark
• Add quoting/escaping and named arguments to command parser
• Perform more parameter validation in command/option parser
• Unify PHY/port names to A/B/AB/none (a mix of conventions was used before)
1.5.5 Host tool v1.1 (686fe4f)
• Add ”speed” convenience command
• Improve capture stats log behavior
• Note that this used to be untagged in the public git repository
1.5.6 Host tool v1 (f5eed9c)
• Initial release
• Note that this used to be untagged in the public git repository
7

2 Hardware Setup
2 Hardware Setup
The ethernet debugger needs to be powered via USB to forward any packets. Without power, communica-
tion between the two ports is blocked. Make sure USB cable and host port are at least USB 3.0 compliant.
If you use USB hubs or USB isolators, make sure they all support USB 3.0. USB 2.0 will work, but will
provide degraded functionality, as USB 2.0 bandwidth is lower than that of Gigabit Ethernet.
Attach the ethernet cables to the ports. Make sure you are breathing regularly. As soon as both port LEDs
indicate a connection, and the negotiated ethernet speed matches between both ports, communication
is possible.
2.1 LED Meaning
2.1.1 Port LEDs
The LED in use indicates the ethernet speed mode. If packets are sent or received, the corresponding
LEDs will blink.
Speed LED L LED R
1000 MBit off on
100 MBit on on
10 MBit on off
no link off off
Note that it’s possible for one port to have a link, while the other port does not. They also can have
mismatched speed. In both cases, capture will not work.
2.1.2 Main LED
Normally, the main LED should be blue. It will blink if capturing is in progress. The following states exist:
LED state Meaning
Blue USB super speed connection is up
Green USB high speed connection is up (slow, but functional)
Cyan USB power only (will not work)
Blue blinking capturing at USB super speed is in progress
Green blinking capturing at USB high speed is in progress (will drop packets)
Blue/green blinking the blink_led command is being used (only for a short moment)
Red initial bootloader failed (probably flash problem)
Red blinking bootloader failed (probably flash problem)
Off low level bootloader/firmware crash, or no USB power
Red/yellow blinking fatal higher level firmware error
Red/blue or Red/green blinking firmware update failed; running factory firmware version
(The blue/green color indicates USB speed, see above.)
When you experience problems, it is useful to describe the LED state exactly in support requests, even if
the observed variant is not listed above.
8

3 Software Installation
3 Software Installation
The software consists of a host tool, called ”nose”. It performs the following roles:
• userspace driver for the device
• Wireshark integration via Wireshark extcap
• command line tool for explicit access
3.1 Linux
No binaries or packages are provided. You can build it from the public git repository. Binary builds or
packages for popular Linux distributions may be provided if there is enough demand.
• build the host tool from the git repository (see https://github.com/intona/ethernet-debugger#build-
instructions)
• create a symlink for Wireshark extcap (see Wireshark section for details)
You may need to install an udev rule to get access to the USB device as normal user:
sudo cp udev.rules /etc/udev/rules.d/50-intona-ethernet-debugger.rules
sudo udevadm trigger
3.2 macOS
No binaries are provided. Hence the software is provided as source code, you can automatically download
and build it using Homebrew.
brew install --HEAD intona/ethernet-debugger/nose
Homebrew is a 3rd party project for installing freely available software on macOS. See https://brew.sh/
for details and how to install Homebrew itself.
You need to setup Wireshark extcap manually. See below.
We decided to not provide binaries for macOS because it is quite impossible to deliver unified, stable
executables that will work on various releases of both software API and CPU types. Think of the platform
change to ARM. This is no issue when compiling from sources using Homebrew.
3.3 Windows
• make sure that Wireshark is installed before you proceed
• double-click the installer
• press next a lot of times
It does not matter whether the device is connected during installation. In fact, the installer does not try to
access the device at all.
You can reinstall any time. Updating Wireshark might remove the Ethernet Debugger Wireshark integra-
tion. Reinstalling the Ethernet Debugger will restore it.
9

3 Software Installation
3.4 Verifying Device Access
A simple way to verify whether the software works is by simply running the host tool. It is a command
line program. On Windows, double-clicking nose.exe will open a terminal window, while on Unix, you
need to open a terminal window manually, and then run nose in it.
If the installation succeeded, and the device is connected, you should see the following:
Device 2:3:7 opened.
PHY A: link=down speed=0MBit
PHY B: link=down speed=0MBit
Warning: no link.
The example above has the device on USB bus 2, port 3, device address 7.
If the device could not be found or accessed, the following is shown:
No devices found.
You can stop the host tool by closing the terminal or by entering the ”exit” command.
3.5 Wireshark extcap Setup
Wireshark is the recommended way to use the Ethernet Debugger. It is 3rd party software and not devel-
oped by Intona. Download and install it from Wireshark’s website: https://www.wireshark.org/download
.html
Normally, the Windows installation procedure installs our host tool as a Wireshark ”extcap”. In short,
”extcap” allows external programs (such as our host tool) to provide a capturing source. See the Wireshark
extcap section for details. If the host tool is not correctly installed as extcap source, you will not be able
to start capture from the Wireshark GUI (but other methods of capturing will still work.)
The host tool supports extcap directly via special command line parameters. It must be located in the
”extcap” sub directory within the Wireshark installation directory or the user’s Wireshark configuration
directory. The paths depend on the operating system and the Wireshark installation location.
You can confirm whether it’s installed correctly by opening the Wireshark about dialog, and switching to
the ”Plugins” tab. There should be an entry named ”nose”.
Old Wireshark versions
The non-global/user-specific extcap paths below require at least Wireshark 3.1.1. Older
releases support global paths only.
3.5.1 Linux, macOS
It is recommended to create a symlink to the host tool. The global path is something like /usr/lib/wireshark/extcap/
or /usr/lib/x86_64-linux-gnu/wireshark/extcap/. The exact path depends on the Linux distro. The user-
specific path is usually ~/.config/wireshark/extcap/.
The following should install it locally, assuming ”nose” is already installed:
mkdir -p ~/.config/wireshark/extcap/
ln -s `which nose` ~/.config/wireshark/extcap/nose
10