USB Armory MkII Tutorial 2

Most recent update: 2025-02-01

How to use USB Armory MkII (Part 2 Communication)

CDC Ethernet

In the previous part, when we lsusb, we see the output like this:

$  lsusb
Bus  001  Device  045:  ID  0525:a4a2  Netchip  Technology,  Inc.  Linux-USB  Ethernet/RNDIS  Gadget

As usbarmory becoming as ethernet interface, The PC recognize usbarmory as an ethernet interface. we can interact with the USB armory just like TCP/IP server through its USB port. When configured for Ethernet operation the USB armory board automatically triggers the relevant host driver to enable TCP/IP communication. The USB armory standard Debian image configures it with IP address 10.0.0.1/24 and default gateway 10.0.0.2. The image comes with a DHCP server enabled by default,

On the USB Armory side

Configuration Files:

• Use lsmod | grep g_ether to make sure that USB Armory loads the USB Ethernet gadget module.
• If it is not loaded, you can manually load it:

  sudo modprobe g_ether
  

• In /etc/modprobe.d/usbarmory.conf, you can specify the MAC addresses and other options:

  options g_ether use_eem=0 dev_addr=aa:bb:cc:dd:ee:f1 host_addr=aa:bb:cc:dd:ee:f2
  

  After making changes, update initramfs:

  sudo update-initramfs -u
  sudo reboot
  

Change IP (Network Configuration File)

Unfortunately, my router’s IP conflicts the default USB Armory IP becuase i use ethernet cable to connect to the internet. We can set a static IP address by modifying the network configuration files directly through UART. Open the Network Configuration File: On Debian-based systems, network interfaces are typically configured in /etc/network/interfaces. Open this file using vim.

sudo vim /etc/network/interfaces

Find the USB Ethernet Interface Configuration: Look for a section that defines the usb0 interface or another interface that’s used for Ethernet over USB. It might look like this:

auto usb0
iface usb0 inet static
    address 10.0.0.1
    netmask 255.255.255.0
    network 10.0.0.0
    gateway 10.0.0.2

Change the IP Address: Replace the default IP address (10.0.0.1) with your desired IP address, such as 192.168.100.2. The updated section might look like this:

auto usb0
iface usb0 inet static
    address 192.168.100.2
    netmask 255.255.255.0
    network 192.168.100.0
    gateway 192.168.100.1

Fixes: 192.168.100.2 → USB Armory IP
192.168.100.1 → Host machine (acts as a router)

Restart the Networking Service: To apply the changes, restart the networking service on the USB Armory.

sudo systemctl restart networking

Alternatively, you can bring down the usb0 interface and bring it up again:

sudo ifdown usb0 && sudo ifup usb0

Verify the New IP Address: You can verify that the new IP address has been applied using the ip addr command:

ip addr show usb0

1. It should now display 192.168.100.2 (or whatever IP you set).

Verify the Default Route Check if USB Armory has the correct default gateway:

ip route show

Expected output (USB Armory):

default via 192.168.100.1 dev usb0
192.168.100.0/24 dev usb0 proto kernel scope link src 192.168.100.2

Connect via SSH

Now, to ssh to USB Armory, we can simply have

ssh usbarmory@192.168.100.2

The password is also usbarmory

In the next post, we will talk about how to load and run a single program without Debian OS (no micro SD card or internal Nand required)

Connection Sharing between USB armory and host machine

This sub-section is about connection sharing between USB armory and host machine.This part is quite buggy, I will try to fix it in the future when I have a better understanding of computer networking R.I.P ECE50863. On the host side (mine is a linux machine with Ubuntu)

1. Enable the USB Ethernet Interface

On the host (Linux machine), bring up the USB virtual Ethernet interface (assuming it’s called usb0). You may need to adjust usb0 if the interface name is different.

/sbin/ip link set usb0 up

side: how to check the interface name?

dmesg | grep -i eth

and I see kernel message like this:

[95350.828215] usb 1-6: Product: RNDIS/Ethernet Gadget
[95350.843027] cdc_ether: probe of 1-6:1.0 failed with error -16
[95350.843050] usbcore: registered new interface driver cdc_ether
[97522.387555] usb 1-6: Product: RNDIS/Ethernet Gadget
[97522.390911] cdc_ether 1-6:1.0 usb0: register 'cdc_ether' at usb-0000:00:14.0-6, CDC Ethernet Device, 1a:55:89:a2:69:42
[97522.395020] cdc_ether 1-6:1.0 enx1a5589a26942: renamed from usb0

This means system successfully detected the USB Armory as a CDC Ethernet device, but renamed usb0 to enx1a5589a26942 instead of keeping usb0. This is a common behavior in modern Linux systems that use Predictable Network Interface Names (systemd-based naming). Since your USB Armory is now recognized as enx1a5589a26942, use that name instead of usb0. Try the following:

sudo ip link set enx1a5589a26942 up

2. Set a Static IP Address on the Host

Assign the host (your Linux computer) an IP address that the USB Armory can communicate with, such as 10.0.0.2/24.

sudo /sbin/ip addr add 192.168.100.1/24 dev usb0
or
sudo /sbin/ip addr add 192.168.100.1/24 dev enx1a5589a26942

By default, ip addr add is temporary and will reset after a reboot.

3. Enable IP Masquerading for Internet Sharing

To allow the USB Armory to access the internet through your host’s wireless interface (e.g., wlan0. use ifconfig to check the interface name), you need to enable masquerading on outgoing connections. This command creates a NAT rule that masquerades (hides) the USB Armory’s traffic as if it’s coming from your host.

sudo /sbin/iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -o wlan0 -j MASQUERADE
or 
sudo /sbin/iptables -t nat -A POSTROUTING -s 192.168.100.0/24 -o wlp6s0 -j MASQUERADE

4. Enable IP Forwarding on the Host

To route packets between the USB Armory and other networks (e.g., the internet), you need to enable IP forwarding on the host.

sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"

On the USB Armory, you need to set up the correct default gateway and IP.

# Assign the correct IP to USB Armory
sudo ip addr add 192.168.100.2/24 dev usb0
sudo ip link set usb0 up
# Set the host machine as the gateway
sudo ip route add default via 192.168.100.2

Now test internet access from the USB Armory:

# Ping Google from USB Armory
ping -c 4 8.8.8.8

Now your USB Armory can access the internet through your host machine. The rest of the blog is about DHCP server on the USB Armory and some basic network configuration on Linux

Notes on IP config

Dynamic Host Configuration Protocol (DHCP) is a protocol that automatically assigns IP addresses, subnet masks, gateways, and other network parameters to devices on a network. When a device (like the USB Armory or any computer) is configured to use DHCP, it does not need a statically configured IP address. Instead, it requests one from a DHCP server, which assigns it dynamically. A DHCP server dynamically assigns an IP address to the device for a specific lease time. This address can change over time.If the device is a client (like your USB Armory), it receives its IP from the DHCP server. You can set up a DHCP server on the USB Armory itself (e.g., using isc-dhcp-server), or the device can receive an IP address from an external DHCP server (such as from your home router). For the DHCP server, the configuration is usually stored in /etc/dhcp/dhcpd.conf (on Debian-based systems). On the client side (USB Armory), to use DHCP, the network interface should be set to dhcp in the configuration file. To set a specific interface (e.g., usb0) to use DHCP, the configuration should look like this:

1. Edit /etc/network/interfaces:

sudo nano /etc/network/interfaces

2. Set the Interface to Use DHCP:

Add or modify the relevant section for the interface (usb0 in this case):

auto usb0
iface usb0 inet dhcp

• auto usb0: This ensures that the usb0 interface will automatically be brought up at boot.
• iface usb0 inet dhcp: This configures usb0 to use DHCP to obtain an IP address automatically.

3. Restart Networking:

After editing the file, restart the networking service for the changes to take effect:

sudo systemctl restart networking

Network Configuration File (Static IP) In contrast, network configuration files are used for setting up static IP addresses and network parameters. This means you manually define the IP address, subnet mask, gateway, and DNS servers that the device will use, and they remain fixed unless you change them manually. In this case, there’s no interaction with a DHCP server. All settings are configured locally on the device, and the device won’t request an IP from the network. Since the IP address is fixed, it is useful when the device needs to always have the same IP (e.g., for a server, or for ease of access). On Debian-based systems, the network configuration file usually stored in /etc/network/interfaces. On newer systems using Netplan (Ubuntu), it may be in /etc/netplan/

Change IP (DHCP Server Status)

When I sudo reboot USB Armory, I encountered this error

[FAILED] Failed to start isc-dhcp-s…er.service - LSB: DHCP server. 
See 'systemctl status isc-dhcp-server.service' for details.

To solve this, ensure that the DHCP server is configured to serve the usb0 interface and is set to provide IP addresses in the range that matches your USB Armory configuration (e.g., 192.168.100.x range).

Check the DHCP Configuration

The default configuration file is usually located at /etc/dhcp/dhcpd.conf

sudo vim /etc/dhcp/dhcpd.conf

Make sure the file contains only one subnet section:

subnet 192.168.100.0 netmask 255.255.255.0 {
    range 192.168.100.10 192.168.100.20;
    option routers 192.168.100.1;
    option broadcast-address 192.168.100.255;
    option domain-name-servers 8.8.8.8, 8.8.4.4;
}

IP range (192.168.100.10 → 192.168.100.20) ensures only valid addresses are assigned. Router (192.168.100.1) is correctly set to your host machine.

Next: Ensure that the DHCP server is bound to the correct interface (usb0) by checking /etc/default/isc-dhcp-server:

sudo vim /etc/default/isc-dhcp-server

Make sure that the line specifying the interfaces includes usb0, like this:

INTERFACESv4="usb0"

Test the DHCP Configuration for Syntax Errors

You can test the DHCP configuration to ensure there are no syntax errors by running:

sudo dhcpd -t

Restart the DHCP Server

After making any changes to the configuration files, restart the isc-dhcp-server service:

sudo systemctl restart isc-dhcp-server

Check its status again to ensure it’s running properly:

systemctl status isc-dhcp-server

Restart Networking on USB Armory On the USB Armory, restart networking so it requests an IP from DHCP:

sudo dhclient -r usb0
sudo dhclient usb0

Check if USB Armory Got an IP

ip a show usb0

Expected output:

2: usb0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500
    inet 192.168.100.10/24 scope global usb0