USB Armory MkII Tutorial 2
Published:
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
- 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.
Why Is this step Necessary?
Your Linux machine (host) and the USB Armory (device) need to be in the same network range to communicate. By default, a USB Ethernet device may not have an IP configured, so you must manually assign one. /24 means the first 24 bits of the address (192.168.100.x) are reserved for the network. Usable IP range: 192.168.100.1 (Linux host) 192.168.100.2 (USB Armory) 192.168.100.3-192.168.100.254 (other possible devices) Broadcast address: 192.168.100.255 Network address: 192.168.100.0 (not assignable to devices) This ensures that 192.168.100.1 (your PC) and 192.168.100.2 (USB Armory) are in the same logical subnet.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
Explanation of the command
| Parameter | Description | |----------------------|------------| | `-s 192.168.100.0/24` | Specifies that this rule applies to all devices in the 192.168.100.0/24 subnet (USB Armory’s subnet). | | `-o wlan0` or `-o wlp6s0` | Specifies that the outgoing interface is the Wi-Fi interface (replace `wlan0` with the actual name from `ip a`). | | `-j MASQUERADE` | Enables IP masquerading, making traffic from 192.168.100.x look like it’s coming from the host. |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 theusb0
interface will automatically be brought up at boot.iface usb0 inet dhcp
: This configuresusb0
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