tcpdump: Usage, Options & Common CI Errors

tcpdump captures packets on an interface and filters them with BPF.

tcpdump is the packet-capture workhorse for debugging connectivity in CI. The traps are needing privileges to open the interface and using a bounded capture so it actually exits.

What it does

tcpdump captures packets on a network interface, applies a BPF filter, and prints a decoded summary (or writes a .pcap with -w). It is the first tool reached for when "is traffic even leaving this box?".

Common usage

Terminal

tcpdump -i any -n port 443
tcpdump -i eth0 -c 100 -w capture.pcap          # 100 packets to a file
tcpdump -i any -n 'host 10.0.0.5 and tcp port 5432'
tcpdump -i any -nn -A port 80                   # print ASCII payload
tcpdump -r capture.pcap                          # read a saved capture

Options

Flag	What it does
-i <iface>	Interface to capture on (any = all)
-n / -nn	Do not resolve hosts / hosts and ports
-c <N>	Stop after N packets
-w <file> / -r <file>	Write / read a pcap file
-A / -X	Print payload as ASCII / hex+ASCII
<BPF filter>	e.g. "tcp port 443 and host X"

Common errors in CI

"tcpdump: <iface>: You don't have permission to capture on that device (socket: Operation not permitted)" - capturing needs root or CAP_NET_RAW; unprivileged containers cannot do it. "tcpdump: <iface>: No such device exists" means the interface name is wrong (use -i any or check ip link). Without -c (or a timeout) tcpdump runs until killed and hangs the step - always bound it. A bad BPF filter yields "syntax error" before capture starts. On Alpine, install tcpdump and libpcap.