How jamesbarlow/icmptunnel works
1. Project shape
- This repository builds a single C networking tool, icmptunnel, whose purpose is to carry IP traffic inside ICMP echo request/reply packets.
- The codebase is organized as a small set of runtime modules plus a thin CLI entrypoint, rather than as a framework or multi-service application.
2. Top-level runtime roles
- The program has two primary operating modes: client and server.
- src/icmptunnel.c is the likely main entrypoint and option dispatcher.
- src/client.c and src/server.c implement the mode-specific control loops and setup.
- src/options.h and src/config.h define shared runtime configuration and compile-time parameters.
3. Core tunnel data path
- The fundamental architecture is a bridge between a TUN device and an ICMP transport.
- src/tun-device.c handles the virtual network interface where IP packets appear and are injected back into the local kernel.
- src/echo-skt.c encapsulates the ICMP echo socket used to send and receive tunnel frames over the network.
- The tunnel therefore has two ends: kernel IP stack ↔ TUN device ↔ icmptunnel process ↔ ICMP socket ↔ remote icmptunnel process ↔ remote TUN device ↔ remote kernel IP stack.
4. Forwarding and packet movement
- src/forwarder.c is the likely glue layer that moves data between the TUN side and the network side.
- It probably multiplexes reads/writes, preserves packet framing, and coordinates send/receive flow so that IP packets read from TUN become ICMP payloads, and ICMP payloads received from the wire are written back into TUN.
- This is the main “transport adapter” boundary in the system.
5. Protocol layer
- src/protocol.h defines the on-the-wire format used inside ICMP payloads.
- The README notes a “more reliable protocol” and support for traversal through stateful firewalls and NAT, so this layer likely handles sequencing, acknowledgements, or session management beyond raw payload copying.
- This is the key abstraction separating packet transport from the ICMP carrier itself.
6. Stateful session and peer handling
- src/peer.h suggests there is an explicit peer/session model, likely representing the remote endpoint and its tunnel state.
- src/client-handlers.c/.h and src/server-handlers.c/.h indicate separate control-path logic for the two roles, probably including handshake, validation, and per-packet response behavior.
- src/handlers.h provides shared handler interfaces to keep the client/server implementations aligned.
7. Naming and reachability
- src/resolve.c/.h likely resolves the server hostname or address supplied to the client.
- This is a small but important boundary: the client can target a hostname, while the transport layer expects a concrete address/endpoint for ICMP communication.
8. Checksum and packet integrity
- src/checksum.c/.h provides packet integrity calculations needed for ICMP and/or the tunnel protocol.
- This module is a low-level utility shared by both client and server paths and sits close to the transport boundary.
9. Daemon/process management
- src/daemon.c/.h suggests support for backgrounding or running as a daemon, which matches the README’s quickstart showing the process being suspended and continued in the background.
- This is operational infrastructure rather than protocol logic, but it matters for deployment and how the tool is used in practice.
10. Server-side vs client-side responsibilities
- The server listens for inbound ICMP tunnel traffic, creates/owns the local TUN endpoint, and responds to the client’s packets.
- The client initiates the tunnel toward a configured server, drives the outbound ICMP traffic, and maps local TUN traffic into the remote endpoint.
- The split is reflected directly in file organization, which keeps the two control planes separate while sharing the same transport primitives.
11. External kernel boundary
- A major architectural boundary is the Linux kernel network stack.
- The tool depends on a TUN interface and the kernel’s ICMP behavior; the README explicitly requires disabling normal ICMP echo responses so the kernel does not interfere with tunnel packets.
- That means the process operates partly as a user-space network endpoint, not just a normal socket client/server.
12. Build and packaging
- The repository uses a plain Makefile, with no heavier build system.
- man/.keep and man indicate packaging for a manual page, which suggests the repo is intended as a small standalone Unix utility rather than a library.
- CHANGES and LICENSE reinforce the “single-purpose tool” shape.
13. Architecture diagram summary
- The main components to show are: command-line entrypoint, client/server control paths, TUN device adapter, ICMP echo socket adapter, protocol/state layer, and utility modules for checksum, name resolution, and daemonization.
- The most important data flow is bidirectional packet forwarding between the kernel’s TUN interface and remote ICMP packets, with protocol framing in the middle.
Main entry points: forwarder.c Forwarder · icmptunnel.c icmptunnel · client.c Client · protocol.h Protocol
Components 16
Runtime
Command-line entrypoint and mode-specific control flow
- icmptunnel · Main binary entrypoint and option dispatcher
src/icmptunnel.c - Client · Client-mode setup and execution loop
src/client.c - Server · Server-mode setup and execution loop
src/server.c - Options · Shared runtime options and CLI configuration
src/options.h - Config · Compile-time parameters and defaults
src/config.h
Data path
Tunnel adapters and packet forwarding
- Forwarder · Moves packets between TUN and ICMP transport
src/forwarder.c - TUN device · Virtual interface carrying IP packets to and from the kernel
src/tun-device.c - ICMP socket · Echo-request/reply socket used as the tunnel carrier
src/echo-skt.c
Protocol
Tunnel framing, peers, and mode-specific handlers
- Protocol · On-the-wire tunnel framing and reliability layer
src/protocol.h - Peer · Remote endpoint and tunnel session state
src/peer.h - Client handlers · Client-side control and packet handling logic
src/client-handlers.c - Server handlers · Server-side control and packet handling logic
src/server-handlers.c
Utilities
Shared support code for deployment and reachability
Other components
- Kernel stack · Host network stack and ICMP behavior outside the process
Connections 22
- icmptunnel → Client: selects · Dispatches into client mode
- icmptunnel → Server: selects · Dispatches into server mode
- icmptunnel → Options: reads · Uses shared runtime options
- icmptunnel → Config: uses · Applies compile-time configuration
- Client → Resolve: resolves · Turns configured target name into an address
- Client → Forwarder: drives · Runs the client-side forwarding loop
- Server → Forwarder: drives · Runs the server-side forwarding loop
- Client → Client handlers: uses · Delegates client control-path handling
- Server → Server handlers: uses · Delegates server control-path handling
- Forwarder → TUN device: reads/writes · Moves IP packets to and from the TUN device
- Forwarder → ICMP socket: reads/writes · Carries tunnel frames over ICMP echo traffic
- Forwarder → Protocol: frames · Encodes and decodes tunnel payloads
- Forwarder → Peer: tracks · Associates traffic with remote peer state
- Client handlers → Protocol: uses · Implements client-side protocol behavior
- Server handlers → Protocol: uses · Implements server-side protocol behavior
- Client handlers → Peer: manages · Maintains client peer/session state
- Server handlers → Peer: manages · Maintains server peer/session state
- ICMP socket → Checksum: verifies · Relies on checksum helpers for packet integrity
- Protocol → Checksum: uses · Needs integrity helpers for protocol framing
- TUN device → Kernel stack: exchanges packets · Interfaces with the host network stack
- ICMP socket → Kernel stack: exchanges packets · Sends and receives ICMP through the host stack
- Daemon → icmptunnel: supports · Provides optional background execution