Linux Implementation (iproute2 vs ifconfig)
Relevant source files
The following files were used as context for generating this wiki page:
The Linux implementation of the spoof utility provides a dual-tool approach for network interface discovery and MAC address modification. It prioritizes the modern iproute2 suite (the ip command) while maintaining a fallback to the legacy net-tools suite (ifconfig). This architecture ensures compatibility across diverse Linux distributions, ranging from modern systems without net-tools to legacy environments where iproute2 might be unavailable.
Sources: src/index.ts:160-163, README.md:121-122, CLAUDE.md:112-113
Tool Selection Logic
The system utilizes a lazy detection mechanism to determine which Linux networking tool to employ. By default, the application checks for the existence of the ip binary using the which ip command. However, users can override this automatic selection via configuration or CLI flags.
Tool Priority Hierarchy
- User Preference: If
preferIfconfigis set totrue, the system bypassesipdetection and defaults to legacy tools. - Modern Check: If no preference is set, the system checks for
ipcommand availability. - Legacy Fallback: If the
ipcommand is missing or explicitly rejected, the system reverts toifconfig.
Sources: src/index.ts:114-118, src/index.ts:153-156, src/cli.ts:79-81
The following diagram illustrates the decision-making process for selecting the Linux backend:
Sources: src/index.ts:153-156, src/index.ts:160-163
Interface Discovery
Interface discovery on Linux involves parsing the text output of system commands to construct NetworkInterface objects. The parsing logic differs significantly between the two supported tools.
Modern Discovery (iproute2)
When using ip link show, the system parses multi-line output to extract the device name and its associated MAC address.
| Data Point | Extraction Logic |
|---|---|
| Device Name | Matches the pattern ^\d+:\s+(\S+?)[@:] from the start of the block. |
| MAC Address | Extracted from lines matching ^\s+link\/ether\s+([0-9a-f:]+). |
| Port Type | Determined by the getLinuxPortType utility based on naming prefixes (e.g., wl for Wi-Fi, eth for Ethernet). |
Sources: src/index.ts:172-195, test/findInterfaces.test.ts:133-140
Legacy Discovery (ifconfig)
The legacy findInterfacesLinuxIfconfig function parses the output of the ifconfig command. It identifies interface blocks by looking for the HWaddr keyword and extracts the device name and MAC address from the surrounding text.
Sources: src/index.ts:285-300, test/findInterfaces.test.ts:219-224
MAC Address Modification
Modification of the MAC address on Linux requires bringing the interface down before applying the change and bringing it back up afterward. Both backends follow this three-step sequence.
iproute2 Modification Sequence
The ip command implementation uses the link set sub-commands:
ip link set dev <device> downip link set dev <device> address <mac>ip link set dev <device> up
Sources: src/index.ts:468-472, test/setInterfaceMAC.test.ts:169-178
ifconfig Modification Sequence
The ifconfig implementation combines the "down" and "address" steps into a single command:
ifconfig <device> down hw ether <mac>ifconfig <device> up
Sources: src/index.ts:476-477, test/setInterfaceMAC.test.ts:215-224
The following sequence diagram represents the execution flow for changing a MAC address on Linux:
Key Functions and Configuration
The following table summarizes the primary elements of the Linux implementation:
| Element | Type | Description |
|---|---|---|
setPreferIfconfig(value) | Function | Sets the preferIfconfig flag to force legacy tool usage. |
hasIpCommandAsync() | Async Function | Uses which ip to check for iproute2 availability. |
getLinuxPortType(device, flags) | Function | Heuristic that maps device names (e.g., docker0, wlan0) to human-readable types like "Virtual" or "Wi-Fi". |
getInterfaceMACLinux(device) | Function | Retrieves the current active MAC address for a specific device. |
--prefer-ifconfig | CLI Flag | Global flag passed to the CLI to trigger setPreferIfconfig(true). |
Sources: src/index.ts:143-145, src/index.ts:214-233, src/cli.ts:79-81, src/cli.ts:148
Summary
The Linux implementation in spoof is designed for maximum compatibility by abstracting networking commands behind a unified API. By supporting both iproute2 and ifconfig, the project remains functional across various generations of Linux environments. The modification logic ensures system stability by properly cycling the interface state (down/up) during the address change process.
Sources: src/index.ts:457-482, README.md:121-122