# jamesbarlow/icmptunnel architecture

> Architecture diagram of the GitHub repository jamesbarlow/icmptunnel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamesbarlow/icmptunnel
- Repository: https://github.com/jamesbarlow/icmptunnel

## Overview

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: [`src/forwarder.c`](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/forwarder.c) (Forwarder), [`src/icmptunnel.c`](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/icmptunnel.c) (icmptunnel), [`src/client.c`](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/client.c) (Client), [`src/protocol.h`](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/protocol.h) (Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_n_entry["icmptunnel<br/>cli entrypoint<br/>[icmptunnel.c]"]
  node_n_client["Client<br/>mode control<br/>[client.c]"]
  node_n_server["Server<br/>mode control<br/>[server.c]"]
  node_n_opts["Options<br/>config API<br/>[options.h]"]
  node_n_conf["Config<br/>[config.h]"]
end

subgraph group_group_data["Data path"]
  node_n_forward["Forwarder<br/>bridge<br/>[forwarder.c]"]
  node_n_tun[("TUN device<br/>network adapter<br/>[tun-device.c]")]
  node_n_echo[("ICMP socket<br/>transport adapter<br/>[echo-skt.c]")]
end

subgraph group_group_proto["Protocol"]
  node_n_proto["Protocol<br/>wire format<br/>[protocol.h]"]
  node_n_peer["Peer<br/>session state<br/>[peer.h]"]
  node_n_chand["Client handlers<br/>handler set<br/>[client-handlers.c]"]
  node_n_shand["Server handlers<br/>handler set<br/>[server-handlers.c]"]
end

subgraph group_group_util["Utilities"]
  node_n_resolve["Resolve<br/>name lookup<br/>[resolve.c]"]
  node_n_checksum["Checksum<br/>integrity<br/>[checksum.c]"]
  node_n_daemon["Daemon<br/>process mgmt<br/>[daemon.c]"]
end

node_n_kernel(("Kernel stack<br/>external boundary"))

node_n_entry -->|"selects"| node_n_client
node_n_entry -->|"selects"| node_n_server
node_n_entry -->|"reads"| node_n_opts
node_n_entry -->|"uses"| node_n_conf
node_n_client -->|"resolves"| node_n_resolve
node_n_client -->|"drives"| node_n_forward
node_n_server -->|"drives"| node_n_forward
node_n_client -->|"uses"| node_n_chand
node_n_server -->|"uses"| node_n_shand
node_n_forward -->|"reads/writes"| node_n_tun
node_n_forward -->|"reads/writes"| node_n_echo
node_n_forward -->|"frames"| node_n_proto
node_n_forward -->|"tracks"| node_n_peer
node_n_chand -->|"uses"| node_n_proto
node_n_shand -->|"uses"| node_n_proto
node_n_chand -->|"manages"| node_n_peer
node_n_shand -->|"manages"| node_n_peer
node_n_echo -->|"verifies"| node_n_checksum
node_n_proto -->|"uses"| node_n_checksum
node_n_tun -->|"exchanges packets"| node_n_kernel
node_n_echo -->|"exchanges packets"| node_n_kernel
node_n_daemon -->|"supports"| node_n_entry

click node_n_entry "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/icmptunnel.c"
click node_n_client "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/client.c"
click node_n_server "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/server.c"
click node_n_opts "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/options.h"
click node_n_conf "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/config.h"
click node_n_forward "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/forwarder.c"
click node_n_tun "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/tun-device.c"
click node_n_echo "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/echo-skt.c"
click node_n_proto "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/protocol.h"
click node_n_peer "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/peer.h"
click node_n_chand "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/client-handlers.c"
click node_n_shand "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/server-handlers.c"
click node_n_resolve "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/resolve.c"
click node_n_checksum "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/checksum.c"
click node_n_daemon "https://github.com/jamesbarlow/icmptunnel/blob/dev/src/daemon.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_entry,node_n_client,node_n_server,node_n_opts,node_n_conf toneBlue
class node_n_forward,node_n_tun,node_n_echo toneAmber
class node_n_proto,node_n_peer,node_n_chand,node_n_shand toneMint
class node_n_resolve,node_n_checksum,node_n_daemon toneRose
class node_n_kernel toneNeutral
```

## Components

### Runtime

Command-line entrypoint and mode-specific control flow

- [icmptunnel](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/icmptunnel.c): cli entrypoint · Main binary entrypoint and option dispatcher · `src/icmptunnel.c`
- [Client](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/client.c): mode control · Client-mode setup and execution loop · `src/client.c`
- [Server](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/server.c): mode control · Server-mode setup and execution loop · `src/server.c`
- [Options](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/options.h): config API · Shared runtime options and CLI configuration · `src/options.h`
- [Config](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/config.h): build config · Compile-time parameters and defaults · `src/config.h`

### Data path

Tunnel adapters and packet forwarding

- [Forwarder](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/forwarder.c): bridge · Moves packets between TUN and ICMP transport · `src/forwarder.c`
- [TUN device](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/tun-device.c): network adapter · Virtual interface carrying IP packets to and from the kernel · `src/tun-device.c`
- [ICMP socket](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/echo-skt.c): transport adapter · Echo-request/reply socket used as the tunnel carrier · `src/echo-skt.c`

### Protocol

Tunnel framing, peers, and mode-specific handlers

- [Protocol](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/protocol.h): wire format · On-the-wire tunnel framing and reliability layer · `src/protocol.h`
- [Peer](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/peer.h): session state · Remote endpoint and tunnel session state · `src/peer.h`
- [Client handlers](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/client-handlers.c): handler set · Client-side control and packet handling logic · `src/client-handlers.c`
- [Server handlers](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/server-handlers.c): handler set · Server-side control and packet handling logic · `src/server-handlers.c`

### Utilities

Shared support code for deployment and reachability

- [Resolve](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/resolve.c): name lookup · Resolves server hostnames or addresses for the client · `src/resolve.c`
- [Checksum](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/checksum.c): integrity · Packet checksum and integrity helpers · `src/checksum.c`
- [Daemon](https://github.com/jamesbarlow/icmptunnel/blob/dev/src/daemon.c): process mgmt · Backgrounding and daemonization support · `src/daemon.c`

### Other components

- **Kernel stack**: external boundary · Host network stack and ICMP behavior outside the process

## Connections

- 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
