# the-tcpdump-group/tcpdump architecture

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

- Interactive diagram: https://gitdiagram.com/the-tcpdump-group/tcpdump
- Repository: https://github.com/the-tcpdump-group/tcpdump

## Overview

1. **What this repository is**
   This is the source tree for **tcpdump**, a native C command-line packet analyzer. Its core job is to read captured packets from **libpcap** and render human-readable protocol dissections. The repo is mostly one executable plus a large set of protocol decoder modules.

2. **Primary runtime flow**
   The main data path is: **packet capture source → libpcap → tcpdump core → protocol dispatch → protocol-specific printers → text output**. tcpdump does not own packet capture itself; it relies on libpcap for capture file reading, live capture, link-layer decoding support, and platform-specific capture APIs.

3. **Entry point and orchestration**
   `tcpdump.c` is the program entry and command-line driver. It handles option parsing, capture source setup, snapshot/verbosity/filter behavior, and overall packet-processing loop. It coordinates the session and delegates the actual decoding of each packet to lower-level dissection code.

4. **Dissection framework**
   The architectural center is the **netdissect** layer: `netdissect.h`, `netdissect.c`, `print.c`, `print.h`, `util-print.c`, and related support files. This layer defines the packet-dissection context, output helpers, bounds checking, and common formatting utilities that every protocol printer uses.

5. **Protocol decoder subsystem**
   Most of the tree consists of `print-*.c` modules, each responsible for one protocol, encapsulation, or link type. Examples include Ethernet, IPv4/IPv6, TCP/UDP, MPLS, PPP, VLAN, VXLAN, BGP, OSPF, DNS, NFS, and many more. These modules are selected by the dispatch layer based on link type and protocol headers, then recursively decode nested encapsulations.

6. **Shared protocol definitions**
   The many `.h` files at the top level provide shared packet structure definitions, constants, and helper declarations for protocol families such as IP, TCP, UDP, GRE, MPLS, NTP, SMB, RPC, and link-layer types. These headers form the shared contract between the generic dissection engine and the individual printers.

7. **Safety and parsing boundaries**
   A major architectural concern is **defensive parsing of untrusted packet data**. Files like `netdissect-alloc.c`, `signature.c`, `checksum.c`, `in_cksum.c`, and numerous bounds- and formatting-related helpers support careful length checks and safe output. The many regression tests with names like `oobr`, `heapoverflow`, `seg-fault`, and `invalid-length` reflect that robustness is a first-class boundary.

8. **Portability layer**
   The tree includes portability shims under `missing/` and platform notes under `doc/`. These compatibility sources replace or normalize libc/platform functions such as `getopt_long`, `strlcpy`, `strlcat`, and `strsep` when the host OS lacks them. This makes the same decoder code build across Unix variants, macOS, Windows, and others.

9. **Build and configuration architecture**
   The project supports both **Autotools** and **CMake**-based builds. Files like `configure.ac`, `Makefile.in`, `CMakeLists.txt`, and `cmake/Modules/Find*.cmake` define feature detection for dependencies such as **libpcap**, **OpenSSL/crypto**, and **SMI**. This is a classic native-system build, not an application framework stack.

10. **Test and verification subsystem**
   The `tests/` directory is a large golden-output suite: packet captures (`.pcap`/`.pcapng`) paired with expected text outputs (`.out`). The tests verify decoding correctness across many protocols, link types, and malformed inputs. Architecturally, this is a regression harness around the dissection engine rather than a unit-test-per-function design.

11. **Generated and release-support files**
   Files such as `VERSION`, `CHANGES`, `INSTALL.md`, and various `*.in`, `*.awk`, and helper scripts support packaging, release engineering, and ancillary trace-processing tasks. They are not part of the packet-processing runtime path, but they influence how the binary is produced and validated.

12. **External boundary and operational context**
   The only major external runtime dependency is **libpcap**; everything else is largely self-contained C code. The tool is designed for offline analysis of capture files and live packet monitoring on supported OSes, with platform integration handled through the build system and libpcap rather than through internal service components.

Main entry points: [`netdissect.c`](https://github.com/the-tcpdump-group/tcpdump/blob/master/netdissect.c) (netdissect), [`print-ip.c`](https://github.com/the-tcpdump-group/tcpdump/blob/master/print-ip.c) (IP stack), [`print.c`](https://github.com/the-tcpdump-group/tcpdump/blob/master/print.c) (dispatch), [`tcpdump.c`](https://github.com/the-tcpdump-group/tcpdump/blob/master/tcpdump.c) (tcpdump)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime path"]
  node_tcpdump_main["tcpdump<br/>cli driver<br/>[tcpdump.c]"]
  node_libpcap_boundary[("libpcap<br/>external dependency")]
end

subgraph group_protocols["Protocol decoders"]
  node_core_dispatch["dispatch<br/>decoder router<br/>[print.c]"]
  node_link_layer_prints["link types<br/>L2 printers<br/>[print-ether.c]"]
  node_ip_prints["IP stack<br/>L3/L4 printers<br/>[print-ip.c]"]
  node_tunnel_prints["tunnels<br/>encapsulation printers<br/>[print-gre.c]"]
  node_routing_prints["routing<br/>control-plane printers<br/>[print-bgp.c]"]
  node_service_prints["services<br/>application printers<br/>[print-domain.c]"]
end

subgraph group_support["Shared support"]
  node_netdissect_core["netdissect<br/>dissection core<br/>[netdissect.c]"]
  node_print_framework["print core<br/>output layer<br/>[print.c]"]
  node_util_print["util print<br/>format helpers<br/>[util-print.c]"]
  node_netdissect_alloc["alloc/safety<br/>safety support<br/>[netdissect-alloc.c]"]
  node_checksum_utils["checksums<br/>validation utils<br/>[checksum.c]"]
  node_shared_headers["protocol headers<br/>shared definitions<br/>[ip.h]"]
  node_shared_helpers["helper sources<br/>shared helpers<br/>[addrtoname.c]"]
end

subgraph group_tooling["Build and verification"]
  node_portability["missing shims<br/>compat layer<br/>[getopt_long.c]"]
  node_build_system["build system<br/>build config<br/>[CMakeLists.txt]"]
  node_tests["tests<br/>golden suite"]
end

node_tcpdump_main -->|"uses"| node_libpcap_boundary
node_tcpdump_main -->|"initializes"| node_netdissect_core
node_tcpdump_main -->|"drives"| node_core_dispatch
node_core_dispatch -->|"selects"| node_link_layer_prints
node_link_layer_prints -->|"nests into"| node_ip_prints
node_ip_prints -->|"unwraps"| node_tunnel_prints
node_ip_prints -->|"decodes"| node_routing_prints
node_ip_prints -->|"decodes"| node_service_prints
node_core_dispatch -->|"formats via"| node_print_framework
node_print_framework -->|"calls"| node_util_print
node_print_framework -->|"uses"| node_shared_helpers
node_netdissect_core -->|"uses"| node_netdissect_alloc
node_netdissect_core -->|"uses"| node_checksum_utils
node_netdissect_core -->|"declares"| node_shared_headers
node_shared_helpers -->|"depends on"| node_shared_headers
node_portability -->|"enabled by"| node_build_system
node_build_system -->|"finds"| node_libpcap_boundary
node_build_system -->|"verifies"| node_tests
node_tests -->|"checks"| node_core_dispatch
node_tests -->|"stresses"| node_netdissect_core

click node_tcpdump_main "https://github.com/the-tcpdump-group/tcpdump/blob/master/tcpdump.c"
click node_netdissect_core "https://github.com/the-tcpdump-group/tcpdump/blob/master/netdissect.c"
click node_print_framework "https://github.com/the-tcpdump-group/tcpdump/blob/master/print.c"
click node_util_print "https://github.com/the-tcpdump-group/tcpdump/blob/master/util-print.c"
click node_netdissect_alloc "https://github.com/the-tcpdump-group/tcpdump/blob/master/netdissect-alloc.c"
click node_checksum_utils "https://github.com/the-tcpdump-group/tcpdump/blob/master/checksum.c"
click node_core_dispatch "https://github.com/the-tcpdump-group/tcpdump/blob/master/print.c"
click node_link_layer_prints "https://github.com/the-tcpdump-group/tcpdump/blob/master/print-ether.c"
click node_ip_prints "https://github.com/the-tcpdump-group/tcpdump/blob/master/print-ip.c"
click node_tunnel_prints "https://github.com/the-tcpdump-group/tcpdump/blob/master/print-gre.c"
click node_routing_prints "https://github.com/the-tcpdump-group/tcpdump/blob/master/print-bgp.c"
click node_service_prints "https://github.com/the-tcpdump-group/tcpdump/blob/master/print-domain.c"
click node_shared_headers "https://github.com/the-tcpdump-group/tcpdump/blob/master/ip.h"
click node_shared_helpers "https://github.com/the-tcpdump-group/tcpdump/blob/master/addrtoname.c"
click node_portability "https://github.com/the-tcpdump-group/tcpdump/blob/master/missing/getopt_long.c"
click node_build_system "https://github.com/the-tcpdump-group/tcpdump/blob/master/CMakeLists.txt"
click node_tests "https://github.com/the-tcpdump-group/tcpdump/tree/master/tests/TESTLIST"

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_tcpdump_main,node_libpcap_boundary toneBlue
class node_core_dispatch,node_link_layer_prints,node_ip_prints,node_tunnel_prints,node_routing_prints,node_service_prints toneAmber
class node_netdissect_core,node_print_framework,node_util_print,node_netdissect_alloc,node_checksum_utils,node_shared_headers,node_shared_helpers toneMint
class node_portability,node_build_system,node_tests toneRose
```

## Components

### Runtime path

Packet capture, dispatch, decoding, and text rendering

- [tcpdump](https://github.com/the-tcpdump-group/tcpdump/blob/master/tcpdump.c): cli driver · Program entry point, option handling, capture setup, and packet-processing loop · `tcpdump.c`
- **libpcap**: external dependency · Capture-file and live-capture backend relied on by tcpdump

### Protocol decoders

Representative protocol printer modules and dispatch helpers

- [dispatch](https://github.com/the-tcpdump-group/tcpdump/blob/master/print.c): decoder router · Selects link-type and protocol-specific printers, then recurses into nested encapsulations · `print.c`
- [link types](https://github.com/the-tcpdump-group/tcpdump/blob/master/print-ether.c): L2 printers · Representative link-layer decoders such as Ethernet, PPP, VLAN, MPLS, and loopback · `print-ether.c`
- [IP stack](https://github.com/the-tcpdump-group/tcpdump/blob/master/print-ip.c): L3/L4 printers · IPv4, IPv6, TCP, UDP, ICMP, fragments, and related protocol demuxing · `print-ip.c`
- [tunnels](https://github.com/the-tcpdump-group/tcpdump/blob/master/print-gre.c): encapsulation printers · GRE, VXLAN, Geneve, ERSPAN, L2TP, and similar encapsulation decoders · `print-gre.c`
- [routing](https://github.com/the-tcpdump-group/tcpdump/blob/master/print-bgp.c): control-plane printers · BGP, OSPF, IS-IS, RIP, PIM, RSVP, LDP, and other routing protocol decoders · `print-bgp.c`
- [services](https://github.com/the-tcpdump-group/tcpdump/blob/master/print-domain.c): application printers · DNS, DHCP, HTTP, NFS, SMB, SNMP, RADIUS, SIP, SSH, TFTP, and similar service decoders · `print-domain.c`

### Shared support

Common parsing, safety, portability, and shared definitions

- [netdissect](https://github.com/the-tcpdump-group/tcpdump/blob/master/netdissect.c): dissection core · Dissection context, bounds checks, and shared output helpers · `netdissect.c`
- [print core](https://github.com/the-tcpdump-group/tcpdump/blob/master/print.c): output layer · Common formatting and printer orchestration used by protocol modules · `print.c`
- [util print](https://github.com/the-tcpdump-group/tcpdump/blob/master/util-print.c): format helpers · Shared text-rendering helpers for protocol printers · `util-print.c`
- [alloc/safety](https://github.com/the-tcpdump-group/tcpdump/blob/master/netdissect-alloc.c): safety support · Memory and parsing support for defensive handling of packet data · `netdissect-alloc.c`
- [checksums](https://github.com/the-tcpdump-group/tcpdump/blob/master/checksum.c): validation utils · Checksum and integrity helpers used by several decoders · `checksum.c`
- [protocol headers](https://github.com/the-tcpdump-group/tcpdump/blob/master/ip.h): shared definitions · Top-level .h files defining packet structures, constants, and printer contracts · `ip.h`
- [helper sources](https://github.com/the-tcpdump-group/tcpdump/blob/master/addrtoname.c): shared helpers · Common address conversion, string formatting, name lookup, and protocol utility code · `addrtoname.c`

### Build and verification

Build systems, portability shims, and regression assets

- [missing shims](https://github.com/the-tcpdump-group/tcpdump/blob/master/missing/getopt_long.c): compat layer · Portable replacements for libc and OS-specific functions · `missing/getopt_long.c`
- [build system](https://github.com/the-tcpdump-group/tcpdump/blob/master/CMakeLists.txt): build config · Autotools and CMake configuration, feature detection, and packaging support · `CMakeLists.txt`
- [tests](https://github.com/the-tcpdump-group/tcpdump/tree/master/tests/TESTLIST): golden suite · Capture fixtures and expected outputs for regression and malformed-input coverage · `tests/TESTLIST`

## Connections

- tcpdump → libpcap: uses · Reads packets and capture files through libpcap
- tcpdump → netdissect: initializes · Creates and configures the dissection context
- tcpdump → dispatch: drives · Feeds captured packets into decoder dispatch
- dispatch → link types: selects · Dispatches by link type and framing
- link types → IP stack: nests into · Hands off to network and transport decoders
- IP stack → tunnels: unwraps · Decodes tunneled or encapsulated payloads
- IP stack → routing: decodes · Prints routing and control-plane protocols
- IP stack → services: decodes · Prints application and service protocols
- dispatch → print core: formats via · Uses the shared output pipeline
- print core → util print: calls · Relies on common text-formatting helpers
- print core → helper sources: uses · Depends on address and name formatting utilities
- netdissect → alloc/safety: uses · Shares safe allocation and parsing support
- netdissect → checksums: uses · Performs integrity checks while decoding packets
- netdissect → protocol headers: declares · Defines shared packet and context interfaces
- helper sources → protocol headers: depends on · Uses protocol and address-family definitions
- missing shims → build system: enabled by · Selected through platform feature detection
- build system → libpcap: finds · Locates required external capture library
- build system → tests: verifies · Builds and runs regression coverage
- tests → dispatch: checks · Validates decoder behavior against captures and expected text
- tests → netdissect: stresses · Exercises bounds checks and malformed-input handling
