Add READMEHEADmain

1 files changed, 116 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3e9a05b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# packeteer
+
+Terminal packet capture and analysis for Linux. Captures live traffic or
+replays a saved file, decodes it from Ethernet up to the application
+layer, and shows the result in a plain-text log, an interactive TUI, or a
+graphical window.
+
+Capture files are pcapng, so Wireshark reads them and interface metadata
+survives the round trip.
+
+## Build
+
+Requires a C++20 compiler, CMake 3.20 or later, and libpcap. FTXUI,
+doctest, SDL3 and Dear ImGui are fetched during configuration, so no
+system packages are needed for them.
+
+```
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+```
+
+The binaries are `build/packeteer` (command line and TUI),
+`build/packeteer_gui` (graphical), and `build/packeteer_tests`.
+
+## Use
+
+```
+packeteer [options] [interface]
+```
+
+With no interface, the first available device is used.
+
+| Option | Effect |
+| --- | --- |
+| `-t`, `--tui` | Interactive TUI instead of plain-text output |
+| `-x` | Hex dump under each summary, plain-text mode only |
+| `-c` | Show IPv4/TCP/UDP checksum validity |
+| `-a` | Reassemble TCP streams and re-run HTTP parsing on the joined bytes |
+| `-w <file>` | Write the capture to a pcapng file |
+| `-r <file>` | Replay a pcapng file instead of a live device |
+| `-f <expr>` | Capture filter in tcpdump/BPF syntax |
+| `-g <term>` | Display filter: show only summaries containing `term` |
+| `-h`, `--help` | Show usage |
+
+In the TUI, press `/` to search interactively.
+
+### Filters
+
+`-f` is a kernel-level BPF filter. The kernel discards what does not
+match, so those packets never reach the process, and `-w` writes only
+what passed. Use it to cut volume at the source.
+
+`-g` is a display filter applied after decoding. It changes what you see,
+not what is captured, and does not affect `-w`.
+
+`-f` cannot be combined with `-r`, because a saved file has already been
+filtered at capture time.
+
+### Checksums
+
+Checksum validation is off by default. Most network cards compute the
+real checksum in hardware, after the point where capture taps the packet.
+Outbound and loopback packets therefore read as invalid even when nothing
+is wrong. Turn it on with `-c` when you are looking at received traffic
+and the distinction matters.
+
+### TCP reassembly
+
+`-a` joins TCP segments and parses the result, which catches an HTTP
+request or response split across several packets that single-packet
+dissection misses. In-order segments only. Out-of-order and retransmitted
+segments are dropped rather than buffered.
+
+## Protocol support
+
+Link and network layers: Ethernet, ARP, IPv4, IPv6, ICMP, IGMP, LLDP.
+
+Transport: TCP with stream reassembly, UDP, RTP, RTCP.
+
+Application: DHCP, DNS, mDNS, HTTP, FTP, SMTP, SSH, TLS, QUIC, NTP, SNMP,
+TFTP.
+
+Fragmented IPv4 and IPv6 packets are reported as fragments. A non-first
+fragment carries no transport header, so its payload is not decoded as
+one.
+
+## Capture backends
+
+libpcap is the default and works on any interface it supports.
+
+A second path uses a raw `AF_PACKET` socket with an mmap'd ring buffer,
+which avoids libpcap's copies. It is Linux-only and built as
+`packeteer_afpacket_demo`.
+
+## Privileges
+
+Packet capture needs `CAP_NET_RAW`. Grant it to the binary rather than
+running as root:
+
+```
+sudo setcap cap_net_raw,cap_net_admin=eip build/packeteer
+```
+
+The capture handle is opened first and privileges are dropped immediately
+afterwards, so the decoders never run with them.
+
+## Tests
+
+```
+cmake --build build -j && ./build/packeteer_tests
+```
+
+Unit tests cover the decoders, the byte reader, the capture queue and the
+filters. Twelve libFuzzer targets under `fuzz/` exercise the parsers
+against malformed input; build them with
+`-DPACKETEER_ENABLE_FUZZING=ON` and a Clang toolchain.