IO Ninja — all-in-one terminal, sniffer, protocol analyzer
IO Ninja Hardware Client

IO Ninja Hardware Client

Capture Data From Taps Using a Command-line Tool

There are three types of hardware sniffers for IO Ninja: Serial Tap, Ethernet Tap, and I2C/SPI Tap. Each of these taps has a dedicated plugin that unlocks the full range of functionality provided by the hardware. You simply attach an IO Ninja tap to a USB port on your PC, start the corresponding IO Ninja plugin, and view the captured data log in real time. Everything works great, right?

But what if the data link you need to inspect is physically located far away from your PC? Bringing a laptop to the site might not be the most practical solution for various reasons. For example, you might need to capture a data stream overnight, and the site could be a noisy manufacturing floor!

Recognizing these challenges, we developed a dedicated tool to control IO Ninja hardware taps remotely. This tool is called ioninja-hwc, which stands for "IO Ninja Hardware Client." Now, you can connect an IO Ninja tap to a headless Raspberry Pi (or any other Linux machine with USB ports) and control it via SSH from another PC located wherever is most convenient for you.

How Does It Work?

The remote system must be configured to enable ioninja-hwc over SSH connections.

1. Installation of ioninja-hwc

The easiest way to install IO Ninja is through our APT repository or using the *.deb package. Alternatively, you can copy the bin/ioninja-hwc file from the .tar.xz package to usr/local/bin or usr/bin — ioninja-hwc is a self-contained executable, so one file is all you need. If you choose a different directory, refer to the next step.

2. Adding ioninja-hwc to the SSH PATH

It's crucial to ensure that ioninja-hwc is accessible from non-interactive SSH sessions for your user. The non-interactive part means adding it to the PATH in your .bashrc won’t work (since bash isn’t launched).

The easiest solution is to symlink ioninja-hwc into usr/local/bin, usr/bin, or any other standard directory for executables:

$ sudo ln -s <IONINJA_ROOT_DIR>/bin/ioninja-hwc /usr/local/bin/ioninja-hwc

Alternatively, you can add it manually to the SSH session PATH:

  1. Edit /etc/ssh/sshd_config as root and ensure this line is present:
PermitUserEnvironment = true
  1. Edit ~/.ssh/environment (create it if it doesn’t exist) and append the following line:
PATH=$PATH:<IONINJA_ROOT_DIR>/bin/

3. Configuring USB Permissions

By default, all non-standard USB devices on Linux are owned by root and have no read-write permissions for other users. This means you won’t be able to access IO Ninja taps under your user account without sudo, which can be inconvenient.

To resolve this, we recommend allowing all users to access IO Ninja taps. Here’s how to do it:

  1. Create a file at /etc/udev/rules.d/900-ioninja-hw.rules with the following contents:
SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0e26", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0e27", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="326f", ATTR{idProduct}=="0001", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="326f", ATTR{idProduct}=="0002", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="326f", ATTR{idProduct}=="0003", MODE="0666", GROUP="users"
  1. If an IO Ninja tap is plugged in, unplug it and plug it back in (no reboot needed).

4. Hardware Setup

Now, attach your IO Ninja tap to the remote system just as you did on your PC. Make sure to connect the wires or connectors between the tap and the data link you want to monitor. Refer to the hardware manual for wiring details.

Done! The setup is complete.

You can now run IO Ninja on any PC, start one of our new plugins (Serial Tap over SSH or Ethernet Tap over SSH), and capture data remotely over SSH as if the tap were plugged directly into your PC!

Capturing from the Command Line

You can use ioninja-hwc to capture traffic from your hardware taps and save it directly to an .njlog file for further analysis. This provides an alternative to using the "over SSH" plugins, and in some cases, it may be more convenient.

For example, to capture from a Serial Tap connected to your Raspberry Pi, run the following in an SSH session:

$ ioninja-hwc --serial-tap --njlog --out=file.njlog

Replace file.njlog with your desired output file name. Instead of --serial-tap, you can also specify --ethernet-tap, --i2c-tap, or --spi-tap to capture from the corresponding tap.

If you have multiple taps of the same type attached to your system, use the --index parameter to specify the zero-based index of the tap to use. The order is based on the output of the lsusb command.

For example, to capture from the second Serial Tap, use --index=1:

$ ioninja-hwc --serial-tap --index=1 --njlog --out=file.njlog

What Else Can ioninja-hwc Do?

In addition to controlling IO Ninja hardware sniffers, ioninja-hwc has two other important applications:

  1. It can remotely control regular serial devices using the Serial over SSH plugin.
  2. You can now capture packets from your Ethernet Tap directly in Wireshark!

Command-line Option Breakdown

Normally, you won’t need to invoke ioninja-hwc directly — the corresponding plugins will handle that for you. However, if you want to understand what’s happening behind the scenes (for example, if you plan to write a custom script to process data from your Serial Tap), here’s a breakdown of the available command-line options:

IO Ninja Hardware Controller v5.7.2 (amd64)
Usage: ioninja-hwc [<options>...]
General options
  -h, --help                    Display this help
  -v, --version                 Display IO Ninja Hardware Controller version
  -s, --suspend                 Don't start capturing immediately
  --firmware=<file.rpd>         Specify FPGA firmware file (for upload)
  -n, --index=<n>               Open the attached tap #n (zero-based index)

Transport options
  --stdin                       Accept commands trom stdin
  --stdout                      Write output to stdout
  -i, --in, -f=<file>           Read from this file (write unless overriden by -o)
  -o, --out=<file>              Write output to this file
  --njlog                       Write output in the *.njlog format
  -t, --tcp, --tcp-port=<port>  Start a TCP server on this port
  --read-parallelism=<n>        Start <n> reads simultaneously; default: 8
  --read-block-size=<size>      Specify the buffer for each read; default: 8K
  --split-size=<size>           Split the output file after <size> (e.g., 10M)
  --split-time=<time>           Split the output file after <time> (e.g., 30m)

Serial options
  --serial=<COMn>               Open the specified serial port
  --serial-tap                  Open the attached Serial Tap device
  --ser-enum                    Enumerate available serial ports
  --ser-baud=<baud>             Specify serial baud rate
  --ser-data=<bits>             Specify serial data bit count (7|8)
  --ser-stop=<bits>             Specify serial stop bit count (1|15|2)
  --ser-parity=<parity>         Specify serial parity (none|even|odd|mark|space)
  --ser-flow=<flow>             Use RTS/CTS flow control (0|1)
  --ser-dtr=<dtr>               Set serial DTR line (0|1)
  --ser-rts=<rts>               Set serial RTS line (0|1)

I2C/SPI Tap options
  --i2c-tap                     Open the attached I2C/SPI Tap device in I2C mode
  --spi-tap                     Open the attached I2C/SPI Tap device in SPI mode
  --spi-mode=<mode>             Specify SPI mode (0|1|2|3); default: 0
  --spi-data=<bits>             Specify SPI data bits (4|8|12|16); default: 8
  --spi-little-endian           Use little-endian SPI (0|1); default: 0

Ethernet Tap options
  --ethernet-tap                Open the attached Ethernet Tap device
  --pcap                        Output in the *.pcap format

EZ-USB options
  --vid=<vid>                   Specify VID of the device
  --pid=<pid>                   Specify PID of the device
  --ezusb=<file.iic>            Upload an EZ-USB config file