Project 1: Network Interface Inspector

A network interface audit tool that reports interface state, addresses, link speed, driver, and DNS/gateway context.

Quick Reference

Attribute Value
Difficulty Level 1: Beginner
Time Estimate 1 week
Main Programming Language Bash (shell scripting)
Alternative Programming Languages Python, Go, Rust
Coolness Level Level 2: Practical but forgettable
Business Potential 1. Resume gold
Prerequisites Basic Linux CLI
Key Topics Interfaces, Link Layer, and Neighbor Discovery, Legacy Tool Translation and iproute2 Model

1. Learning Objectives

By completing this project, you will:

  1. Build the core tool described in the project and validate output against a golden transcript.
  2. Explain how the tool maps to the Linux networking layer model.
  3. Diagnose at least one real or simulated failure using the tool’s output.

2. All Theory Needed (Per-Concept Breakdown)

This section includes every concept required to implement this project successfully.

Fundamentals

Interfaces are the kernel’s handle for network connectivity. Each interface has a name, link state, MTU, MAC address (for Ethernet), and byte/error counters. When traffic stays on the local link, delivery is done at Layer 2, so IP addresses must be mapped to MAC addresses using ARP (IPv4) or Neighbor Discovery (IPv6). Linux exposes interface state and addressing with iproute2 (ip link, ip addr), physical capabilities with ethtool, and configuration ownership with nmcli when NetworkManager is in control. A key principle: “UP” only means the interface is administratively enabled; it does not guarantee a physical link. To know whether packets can truly move, you must verify carrier state, negotiated speed/duplex, and neighbor cache entries for the next hop. This chapter gives you the vocabulary and evidence sources that anchor every other networking tool.

Deep Dive

A Linux interface is a convergence of hardware, driver, kernel state, and optional user-space control planes. The kernel tracks administrative state (UP/DOWN), operational state (e.g., LOWER_UP), MTU, and per-queue statistics. Administrative UP means the kernel will attempt to transmit; operational state indicates whether the link is actually usable. The driver determines whether a carrier is present and negotiates speed and duplex. This is why ethtool matters so much: it is the only tool that asks the driver what the hardware actually negotiated, which can reveal subtle failure modes such as auto-negotiation mismatches, disabled offloads, or a link that flaps under load. Many performance “mysteries” are rooted here, not in routing or DNS.

Layer 2 is where IP becomes deliverable. On IPv4, ARP is the protocol that resolves an IP address to a MAC address. The kernel maintains a neighbor cache; when it needs to transmit and no mapping exists, it broadcasts an ARP request and waits for a response. If the response is missing, packets may be queued or dropped. IPv6 uses Neighbor Discovery (NDP) instead of ARP, but the logic is similar: resolve a next-hop link-layer address before transmitting. The neighbor cache has states like REACHABLE, STALE, DELAY, and FAILED. These states explain intermittent outages: a STALE entry works until a probe fails; a FAILED entry means the kernel has given up and won’t transmit until a new resolution attempt succeeds.

Modern Linux is saturated with virtual interfaces. Bridges, veth pairs, VLANs, and tunnels are software constructs that behave like physical interfaces but represent logical connectivity. Containers and Kubernetes rely on veth pairs to connect isolated namespaces to bridges. That means the same “interface truth” applies in virtual environments: you still need to check link state, addresses, and neighbor resolution, but the physical meaning is different. A veth “carrier down” can mean a peer namespace isn’t up. A bridge can mask multiple endpoints behind a single MAC. The interpretation changes, but the tools do not.

Configuration ownership is another hidden complexity. On many systems, NetworkManager or systemd-networkd owns interface configuration, and manual changes can be overwritten. nmcli shows the manager’s view: which connection profiles exist, which interface they bind to, and which IPs and DNS servers are in effect. If ip addr and nmcli disagree, that is evidence that the kernel state and the manager’s intended state are diverging. That mismatch is often the cause of “it worked, then it reverted” incidents. The correct troubleshooting practice is to identify the owner, inspect both perspectives, and then decide whether you are diagnosing a kernel state problem (carrier, driver, ARP) or a control-plane problem (configuration drift).

Finally, interface metrics are not just numbers; they are diagnostics. RX/TX errors, dropped packets, or increasing queue drops indicate link issues or overload. Seeing these counters rise while higher-layer tools show intermittent loss is a strong signal that the fault is at or below the interface layer. In other words, before you chase a routing bug, you must prove the interface is physically and logically healthy. This is why interface and neighbor checks are always the first steps in a serious network investigation.

MTU and tagging details add another dimension. If a VLAN tag or tunnel reduces effective MTU, packets larger than the path can be dropped or fragmented, which manifests as “some connections work, others hang.” Likewise, checksum and segmentation offloads can change how packet captures look: tcpdump may show incorrect checksums because the NIC computes them later. Knowing that offloads exist helps you interpret evidence correctly, so you do not misdiagnose a healthy link as faulty. The interface layer is where these physical and logical constraints converge, making it the foundation for everything else you will observe.

How this fit on projects

  • Network Interface Inspector (Project 1)
  • Routing Table Explorer (Project 7)
  • Network Namespace Laboratory (Project 11)

Definitions & key terms

  • MAC address: Link-layer hardware address used to deliver Ethernet frames.
  • Carrier: Physical link presence as reported by the driver.
  • Neighbor cache: Kernel table mapping IP addresses to link-layer addresses.

Mental model diagram

IP packet -> need next hop -> neighbor cache lookup
   |                   |
   |                   +-- hit -> MAC known
   |                   +-- miss -> ARP/NDP query
   v
Ethernet frame -> driver -> NIC -> wire

How it works (step-by-step, invariants, failure modes)

  1. Interface administratively UP.
  2. Driver reports carrier and negotiated link.
  3. Kernel chooses next hop.
  4. Neighbor cache resolves MAC.
  5. Frame transmitted. Invariants: MAC resolution required for L2 delivery; carrier must be present to transmit. Failure modes: link down, wrong VLAN, ARP/ND failure, manager overwriting manual config.

Minimal concrete example Protocol transcript (ARP):

Host: Who has 192.168.1.1? Tell 192.168.1.100
Gateway: 192.168.1.1 is at 00:11:22:33:44:55

Common misconceptions

  • “UP means the cable is fine.” (Carrier state matters.)
  • “ARP is only for the default gateway.” (ARP is for any same-subnet destination.)

Check-your-understanding questions

  1. What is the difference between administrative state and carrier state?
  2. Why does a missing neighbor entry cause packets to be dropped?
  3. When would ethtool show no speed even if the interface is UP?

Check-your-understanding answers

  1. Admin state is a software flag; carrier is physical link presence.
  2. The kernel cannot build an Ethernet frame without a MAC.
  3. Virtual interfaces or link-down conditions often show no speed.

Real-world applications

  • Diagnosing link flaps, ARP storms, and NIC driver issues.

Where you’ll apply it Projects 1, 7, 11.

References

  • ethtool description (driver/hardware settings).
  • nmcli description (NetworkManager control and status).

Key insights Physical truth (carrier, speed, ARP) is the foundation for every higher-layer fix.

Summary Interfaces and neighbors determine whether packets can leave the host at all; validate them before blaming routes or DNS.

Homework/Exercises to practice the concept

  • Draw the neighbor cache state transitions for a host that goes idle and then becomes active again.
  • Label where carrier loss would appear in the data path.

Solutions to the homework/exercises

  • Idle host moves to STALE, then probes on use; if no reply, becomes FAILED.
  • Carrier loss is reported by the driver and visible before any routing decision.

Legacy Tool Translation and iproute2 Model

Fundamentals

The historical net-tools suite (ifconfig, route, netstat, arp) is deprecated on many systems, but legacy scripts still use it. iproute2 replaced net-tools with a consistent object model: links (interfaces), addresses, routes, neighbors, and rules. Instead of many unrelated commands, iproute2 provides a single ip tool with subcommands and a consistent syntax. This makes scripting more reliable, especially with JSON output. Translating legacy commands requires understanding both the old semantics and the modern object model, not just swapping command names.

Deep Dive

Legacy tools evolved separately, so they expose overlapping but inconsistent views. ifconfig mixes link state and address assignment; route manipulates routing tables but with different syntax; netstat displays sockets and routes but often reads /proc in ways that are slower and less consistent than modern tools. iproute2 unifies these concepts: you manage link state with ip link, addresses with ip addr, routes with ip route, and socket statistics with ss. This object model is more aligned with how the kernel stores networking data.

Translation is not always one-to-one. Some legacy commands combine multiple actions into one line (e.g., ifconfig setting address and bringing the link up). iproute2 separates those concerns, which makes scripts more explicit but also longer. Another common mismatch is output format: net-tools output is designed for humans, while iproute2 supports JSON output for scripts. The best practice is to migrate to ip -j and parse JSON to avoid brittle text parsing.

Default behaviors differ. netstat may hide certain sockets unless invoked with specific flags; ss shows more by default. ifconfig may omit secondary addresses that ip addr will show. route may display only the main table, while ip route can show multiple tables and policy rules. These differences matter during migration: a script that “worked” under net-tools might have been relying on hidden defaults. A proper migration includes functional validation, not just command replacement.

Modern iproute2 also exposes advanced features that net-tools never supported well: namespaces, policy routing, and detailed neighbor state. This means a migrated script can be improved, not just translated. For example, a script that used arp -n to list neighbors can be updated to use ip neigh and capture state (REACHABLE, STALE), which is more diagnostic. Likewise, replacing netstat with ss can reveal TCP state and queue metrics that were not previously visible.

Finally, migration is an opportunity to improve safety. iproute2 commands tend to be more explicit and can be wrapped in idempotent checks. Because the object model is consistent, it is easier to validate state before making changes. This reduces the risk of scripts that partially apply changes or misinterpret output. The Legacy to Modern Tool Migration project teaches you to treat migration as a reliability upgrade, not just a compatibility fix.

How this fit on projects

  • Legacy to Modern Tool Migration Guide (Project 14)
  • Network Interface Inspector (Project 1)

Definitions & key terms

  • net-tools: Legacy suite including ifconfig, route, netstat, arp.
  • iproute2: Modern suite using the ip command and ss.
  • Object model: Consistent representation of links, addresses, routes, neighbors.

Mental model diagram

Legacy: ifconfig/route/netstat/arp (separate views)
Modern: ip link / ip addr / ip route / ip neigh (single model)

How it works (step-by-step, invariants, failure modes)

  1. Identify legacy command intent.
  2. Map to iproute2 subcommands.
  3. Validate output differences.
  4. Update scripts to parse JSON where possible. Invariants: iproute2 reflects kernel objects directly. Failure modes: relying on legacy defaults, missing secondary addresses, parsing brittle output.

Minimal concrete example Command mapping (simplified):

ifconfig eth0 192.168.1.10 netmask 255.255.255.0 up
-> ip addr add 192.168.1.10/24 dev eth0
-> ip link set eth0 up

Common misconceptions

  • “ip is just a replacement for ifconfig.” (It replaces the entire net-tools suite.)
  • “Output differences mean the data is wrong.” (They reflect different defaults and scopes.)

Check-your-understanding questions

  1. Why is iproute2 better for scripting?
  2. Which iproute2 command replaces netstat -r?
  3. Why might ip addr show more addresses than ifconfig?

Check-your-understanding answers

  1. It has a consistent object model and JSON output.
  2. ip route show.
  3. ifconfig often omits secondary addresses by default.

Real-world applications

  • Modernizing legacy scripts and maintaining compatibility across distros.

Where you’ll apply it Projects 1 and 14.

References

  • iproute2 documentation
  • net-tools deprecation notes

Key insights Migration is about semantics, not just syntax.

Summary You can now map legacy net-tools commands to iproute2 and understand the behavioral differences.

Homework/Exercises to practice the concept

  • Translate five net-tools commands into iproute2 equivalents.
  • Identify one case where iproute2 reveals more data.

Solutions to the homework/exercises

  • Example translations should use ip link/addr/route/neigh.
  • ip addr often reveals secondary addresses hidden by ifconfig.

3. Project Specification

3.1 What You Will Build

A network interface audit tool that reports interface state, addresses, link speed, driver, and DNS/gateway context.

3.2 Functional Requirements

  1. Core data collection: Gather the required system/network data reliably.
  2. Interpretation layer: Translate raw outputs into human-readable insights.
  3. Deterministic output: Produce stable, comparable results across runs.
  4. Error handling: Detect missing privileges, tools, or unsupported interfaces.

3.3 Non-Functional Requirements

  • Performance: Runs in under 5 seconds for baseline mode.
  • Reliability: Handles missing data sources gracefully.
  • Usability: Output is readable without post-processing.

3.4 Example Usage / Output

$ sudo ./netaudit.sh

NETWORK INTERFACE AUDIT
Host: devserver01
Time: 2026-01-03 14:32:01 UTC

Interface: eth0 [UP, LOWER_UP]
  MAC: 52:54:00:12:34:56
  IPv4: 192.168.1.100/24
  IPv6: fe80::5054:ff:fe12:3456/64
  Gateway: 192.168.1.1
  DNS: 8.8.8.8, 8.8.4.4
  Driver: virtio_net
  Speed: 1000Mb/s Full Duplex
  Link: detected
  RX: 2345678 packets, 1.2 GB
  TX: 1234567 packets, 523 MB

Interface: lo [UP]
  IPv4: 127.0.0.1/8
  IPv6: ::1/128

Summary:
  Interfaces: 5 total (3 UP, 2 DOWN)
  Errors: 0
  NetworkManager: running

3.5 Data Formats / Schemas / Protocols

  • Input: CLI tool output, kernel state, or service logs.
  • Output: A structured report with sections and summarized metrics.

3.6 Edge Cases

  • Missing tool binaries or insufficient permissions.
  • Interfaces or hosts that return no data.
  • Transient states (link flaps, intermittent loss).

3.7 Real World Outcome

$ sudo ./netaudit.sh

NETWORK INTERFACE AUDIT
Host: devserver01
Time: 2026-01-03 14:32:01 UTC

Interface: eth0 [UP, LOWER_UP]
  MAC: 52:54:00:12:34:56
  IPv4: 192.168.1.100/24
  IPv6: fe80::5054:ff:fe12:3456/64
  Gateway: 192.168.1.1
  DNS: 8.8.8.8, 8.8.4.4
  Driver: virtio_net
  Speed: 1000Mb/s Full Duplex
  Link: detected
  RX: 2345678 packets, 1.2 GB
  TX: 1234567 packets, 523 MB

Interface: lo [UP]
  IPv4: 127.0.0.1/8
  IPv6: ::1/128

Summary:
  Interfaces: 5 total (3 UP, 2 DOWN)
  Errors: 0
  NetworkManager: running

3.7.1 How to Run (Copy/Paste)

$ ./run-project.sh [options]

3.7.2 Golden Path Demo (Deterministic)

Run the tool against a known-good target and verify every section of the output matches the expected format.

3.7.3 If CLI: provide an exact terminal transcript

$ sudo ./netaudit.sh

NETWORK INTERFACE AUDIT
Host: devserver01
Time: 2026-01-03 14:32:01 UTC

Interface: eth0 [UP, LOWER_UP]
  MAC: 52:54:00:12:34:56
  IPv4: 192.168.1.100/24
  IPv6: fe80::5054:ff:fe12:3456/64
  Gateway: 192.168.1.1
  DNS: 8.8.8.8, 8.8.4.4
  Driver: virtio_net
  Speed: 1000Mb/s Full Duplex
  Link: detected
  RX: 2345678 packets, 1.2 GB
  TX: 1234567 packets, 523 MB

Interface: lo [UP]
  IPv4: 127.0.0.1/8
  IPv6: ::1/128

Summary:
  Interfaces: 5 total (3 UP, 2 DOWN)
  Errors: 0
  NetworkManager: running

4. Solution Architecture

4.1 High-Level Design

[Collector] -> [Parser] -> [Analyzer] -> [Reporter]

4.2 Key Components

Component Responsibility Key Decisions
Collector Gather raw tool output Which tools to call and with what flags
Parser Normalize raw text/JSON Text vs JSON parsing strategy
Analyzer Compute insights Thresholds and heuristics
Reporter Format output Stable layout and readability

4.3 Data Structures (No Full Code)

  • InterfaceRecord: name, state, addresses, stats
  • RouteRecord: prefix, gateway, interface, metric
  • Observation: timestamp, source, severity, message

4.4 Algorithm Overview

Key Algorithm: Evidence Aggregation

  1. Collect raw outputs from tools.
  2. Parse into normalized records.
  3. Apply interpretation rules and thresholds.
  4. Render the final report.

Complexity Analysis:

  • Time: O(n) over number of records
  • Space: O(n) to hold parsed records

5. Implementation Guide

5.1 Development Environment Setup

# Install required tools with your distro package manager

5.2 Project Structure

project-root/
├── src/
│   ├── main
│   ├── collectors/
│   └── formatters/
├── tests/
└── README.md

5.3 The Core Question You’re Answering

“What is the actual, ground-truth state of every network interface on this host?”

5.4 Concepts You Must Understand First

  1. Interface State vs Carrier
    • What does UP mean vs LOWER_UP?
    • Book Reference: “How Linux Works” - Ch. 9
  2. Link-Layer Addressing
    • Why does a MAC address matter for L2 delivery?
    • Book Reference: “TCP/IP Illustrated, Vol 1” - Ch. 3
  3. Driver/Hardware Diagnostics
    • What does ethtool report that ip does not?
    • Book Reference: “Linux Firewalls” - Ch. 1 (context)

5.5 Questions to Guide Your Design

  1. Data Sources
    • Which command is authoritative for link speed?
    • How will you detect if NetworkManager is the owner?
  2. Parsing Strategy
    • Will you parse text or use JSON output (ip -j)?
    • How will you handle multiple IP addresses per interface?
  3. Presentation
    • What fields are essential for troubleshooting vs noise?

5.6 Thinking Exercise

Trace the Source of Each Field

  • Interface list: ip link
  • IP addresses: ip addr
  • Link speed: ethtool
  • Driver: ethtool -i
  • DNS/gateway: resolvectl or /etc/resolv.conf

Questions:

  • Which of these requires root?
  • Which fails on a minimal system without NetworkManager?

5.7 The Interview Questions They’ll Ask

  1. “How do you verify a link is physically up on Linux?”
  2. “Why might an interface show UP but still not pass traffic?”
  3. “How do you find the driver for a NIC?”
  4. “How do you see all IPs assigned to an interface?”
  5. “What is the difference between ip and ifconfig?”

5.8 Hints in Layers

Hint 1: Start with ip

  • Use ip link for state and ip addr for addresses.

Hint 2: Use JSON when possible

  • ip -j is easier to parse safely.

Hint 3: ethtool requires a real device

  • Expect virtual interfaces to lack speed/duplex info.

Hint 4: DNS is system-wide

  • DNS and default route are not always per-interface.

5.9 Books That Will Help

Topic Book Chapter
Interfaces “How Linux Works” Ch. 9
Link layer “TCP/IP Illustrated, Vol 1” Ch. 3
Diagnostics mindset “The Practice of System Administration” Ch. 5

5.10 Implementation Phases

Phase 1: Foundation (1-2 days)

  • Define outputs and parse a single tool.
  • Produce a minimal report.

Phase 2: Core Functionality (3-5 days)

  • Add remaining tools and interpretation logic.
  • Implement stable formatting and summaries.

Phase 3: Polish & Edge Cases (2-3 days)

  • Handle missing data and failure modes.
  • Add thresholds and validation checks.

5.11 Key Implementation Decisions

Decision Options Recommendation Rationale
Parsing format Text vs JSON JSON where available More stable parsing
Output layout Table vs sections Sections Readability for humans
Sampling One-shot vs periodic One-shot + optional loop Predictable runtime

6. Testing Strategy

6.1 Test Categories

Category Purpose Examples
Unit Tests Validate parsing Parse fixed tool output samples
Integration Tests Validate tool calls Run against a lab host
Edge Case Tests Handle failures Missing tool, no permissions

6.2 Critical Test Cases

  1. Reference run: Output matches golden transcript.
  2. Missing tool: Proper error message and partial report.
  3. Permission denied: Clear guidance for sudo or capabilities.

6.3 Test Data

Input: captured command output
Expected: normalized report with correct totals

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall Symptom Solution
Wrong interface Empty output Verify interface names
Missing privileges Permission errors Use sudo or capabilities
Misparsed output Wrong stats Prefer JSON parsing

7.2 Debugging Strategies

  • Re-run each tool independently to compare raw output.
  • Add a verbose mode that dumps raw data sources.

7.3 Performance Traps

  • Avoid tight loops without sleep intervals.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add colored status markers.
  • Export report to a file.

8.2 Intermediate Extensions

  • Add JSON output mode.
  • Add baseline comparison.

8.3 Advanced Extensions

  • Add multi-host aggregation.
  • Add alerting thresholds.

9. Real-World Connections

9.1 Industry Applications

  • SRE runbooks and on-call diagnostics.
  • Network operations monitoring.
  • tcpdump / iproute2 / nftables
  • mtr / iperf3

9.3 Interview Relevance

  • Demonstrates evidence-based debugging and tool mastery.

10. Resources

10.1 Essential Reading

  • Primary book listed in the main guide.
  • Relevant RFCs and tool manuals.

10.2 Video Resources

  • Conference talks on Linux networking and troubleshooting.