netshoot README

The project's README from github.com/nicolaka/netshoot. As one markdown file: README.md.

netshoot: a Docker + Kubernetes network trouble-shooting swiss-army container

                    dP            dP                           dP
                    88            88                           88
88d888b. .d8888b. d8888P .d8888b. 88d888b. .d8888b. .d8888b. d8888P
88'  `88 88ooood8   88   Y8ooooo. 88'  `88 88'  `88 88'  `88   88
88    88 88.  ...   88         88 88    88 88.  .88 88.  .88   88
dP    dP `88888P'   dP   `88888P' dP    dP `88888P' `88888P'   dP

Quick Start

# Share a running container's network namespace
docker run -it --net container:<container_name> nicolaka/netshoot

# Use the host's network namespace
docker run -it --net host nicolaka/netshoot

# Ephemeral debug container in Kubernetes
kubectl debug <pod> -it --image=nicolaka/netshoot

Why netshoot

Docker and Kubernetes isolate every container in its own network namespace — its own interfaces, routes, and IP stack. netshoot exploits the fact that you can enter any namespace without modifying what's running inside it.

Launch Options

Docker

# Enter a specific container's namespace
docker run -it --net container:<container_name> nicolaka/netshoot

# Enter the host's namespace
docker run -it --net host nicolaka/netshoot

# Enter a Docker bridge network's namespace via nsenter
docker run -it --rm \
  -v /var/run/docker/netns:/var/run/docker/netns \
  --privileged \
  nicolaka/netshoot
# then: nsenter --net=/var/run/docker/netns/<id> sh

Docker Compose

version: "3.6"
services:
  netshoot:
    image: nicolaka/netshoot
    depends_on:
      - nginx
    command: tcpdump -i eth0 -w /data/nginx.pcap
    network_mode: service:nginx        # shares nginx's network namespace
    volumes:
      - $PWD/data:/data

  nginx:
    image: nginx:alpine
    ports:
      - 80:80

Kubernetes

# Ephemeral container in a running pod (non-destructive)
kubectl debug <pod> -it --image=nicolaka/netshoot

# Throwaway pod
kubectl run tmp-shell --rm -i --tty --image nicolaka/netshoot

# Throwaway pod on the host's network namespace
kubectl run tmp-shell --rm -i --tty \
  --overrides='{"spec": {"hostNetwork": true}}' \
  --image nicolaka/netshoot

# Sidecar in a Deployment — see configs/netshoot-sidecar.yaml
kubectl apply -f configs/netshoot-sidecar.yaml
kubectl exec -it <pod> -c netshoot -- zsh

kubectl plugin

The kubectl-netshoot plugin wraps the above into ergonomic subcommands:

kubectl netshoot run tmp-shell          # throwaway pod
kubectl netshoot debug my-pod           # ephemeral container
kubectl netshoot debug node/my-node     # node debug session

Troubleshooting Scenarios

DNS resolution failures

Pod can't reach a service by name, or DNS lookups are slow/timing out.

# 1. Check what DNS server the container is using
cat /etc/resolv.conf

# 2. Resolve a Kubernetes service name
drill kubernetes.default.svc.cluster.local

# 3. Query the cluster DNS directly (bypass resolv.conf)
drill @10.96.0.10 kubernetes.default.svc.cluster.local

# 4. Capture DNS traffic to see what's actually going over the wire
tcpdump -i eth0 -n port 53

# 5. Check for NXDOMAIN vs timeout — different root causes
drill -V 5 my-service.my-namespace.svc.cluster.local

Latency, packet loss, and throughput

Intermittent timeouts, high p99, or slow transfers between pods or nodes.

# Visual traceroute with latency per hop
mtr --report --report-cycles 10 <destination>

# Or use trippy for an interactive TUI traceroute
trip <destination>

# Measure raw TCP throughput between two pods:
# On pod A (server):
iperf3 -s

# On pod B (client):
iperf3 -c <pod-A-ip> -t 30

# Measure UDP throughput and jitter
iperf3 -c <pod-A-ip> -u -b 1G

Service reachability and firewall rules

Can pod A reach pod B on port X? Is something blocking traffic?

# Quick TCP connectivity check
nc -vz <host> <port>

# Scan a port range across a host
nmap -p 8080-8090 <host>

# Trace the full TCP path to a port (combines traceroute + TCP)
tcptraceroute <host> <port>

# Send a single TCP/UDP packet with custom payload
nping --tcp -p 443 <host>

# Check active connections and listening ports
ss -tulnp

Packet capture and deep inspection

Need to see the actual bytes — wrong headers, unexpected resets, TLS issues.

# Capture traffic on eth0 to a file
tcpdump -i eth0 -w /tmp/capture.pcap

# Live capture filtered by host and port
tcpdump -i eth0 -nn host <ip> and port 80

# Grep for a string in live traffic (e.g. HTTP Host headers)
ngrep -q -W byline "Host:" port 80

# Interactive TUI for live capture or reading a pcap
termshark -i eth0
termshark -r /tmp/capture.pcap

# Full protocol dissection with tshark
tshark -i eth0 -Y "http.request" -T fields -e http.host -e http.request.uri

gRPC and HTTP load testing

Validate a gRPC endpoint, hammer an HTTP service, check TLS.

# List gRPC services on a server
grpcurl <host>:<port> list

# Call a gRPC method
grpcurl -d '{"key":"value"}' <host>:<port> my.Service/Method

# Make an HTTP request with verbose output
http GET https://<host>/api/v1/items

# Load test: 100 QPS for 30s
fortio load -qps 100 -t 30s http://<host>/api/v1/items

# Check TLS certificate details
openssl s_client -connect <host>:443 </dev/null | openssl x509 -noout -text

Routing and ARP

Wrong route selected, ARP table stale, traffic going out the wrong interface.

# Show routing table
ip route show

# Show ARP/neighbour table
ip neigh show

# Trace which route a packet would take
ip route get <destination-ip>

# Show interface stats (drops, errors)
ip -s link show eth0

# Test ICMP reachability to multiple hosts at once
fping -a -g 10.0.0.1 10.0.0.254

SMTP testing

Validate mail relay, test TLS, confirm AUTH works.

swaks \
  --to [email protected] \
  --from [email protected] \
  --server mail.example.com:587 \
  --tls \
  --auth PLAIN \
  --auth-user [email protected] \
  --auth-password s3cr3t \
  --header "Subject: netshoot probe" \
  --body "SMTP connectivity test"

Container and network performance overview

# Top-like view of container CPU, memory, net, and I/O
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nicolaka/netshoot ctop

Included Tools

Network analysis

Tool Purpose
tcpdump Packet capture
tshark Protocol dissection
termshark TUI for tshark / pcap files
ngrep Grep over live network traffic
wireshark (tshark) Deep protocol analysis
iftop Bandwidth by host pair
iptraf-ng Real-time network stats
netcat TCP/UDP read/write
socat Multipurpose relay
conntrack-tools Connection tracking
nftables nftables ruleset inspection

DNS

Tool Purpose
drill DNS query tool
bind-tools dig, nslookup, host

Performance

Tool Purpose
iperf / iperf3 TCP/UDP throughput
mtr Traceroute + ping combined
trippy TUI traceroute
fping Parallel ICMP probing
iputils ping, arping
speedtest-cli Internet speed test
ethtool NIC settings and stats

Security & scanning

Tool Purpose
nmap Port scanning
nmap-nping Packet crafting
openssl TLS inspection
scapy Python packet crafting
dhcping DHCP probe

HTTP / gRPC / SMTP

Tool Purpose
httpie Human-friendly HTTP client
curl HTTP client
grpcurl gRPC client
fortio HTTP load testing
websocat WebSocket client
swaks SMTP testing
apache2-utils ab HTTP benchmarking

Routing & interfaces

Tool Purpose
iproute2 ip route, ip link, ip neigh
bridge-utils Bridge management
ipset IP set management
iptables Firewall rules
ipvsadm IPVS table inspection
tcptraceroute Traceroute over TCP

Kubernetes / Calico

Tool Purpose
calicoctl Calico resource management
ctop Container metrics TUI

Debug & tracing

Tool Purpose
strace Syscall tracing
ltrace Library call tracing
net-snmp-tools SNMP queries
bird BGP/OSPF routing daemon

Contributing

PRs are welcome. Before opening one:

netshoot (nicolaka/netshoot)

Searching Database…

11K ·GitHub
Netshoot
What is this?netshoot is a Docker and Kubernetes network troubleshooting container, a 'swiss-army' image packed with networking, DNS, performance, and security tools for debugging container and host network issues.
Is this a library I install, or a container image I run?It is a prebuilt Docker image, not a library. It works by exploiting the fact that you can enter any container's or host's network namespace without installing anything inside it.
How do I actually use netshoot to debug something?Launch it with Docker (optionally sharing a target container's network namespace), Docker Compose, or in Kubernetes as an ephemeral container, throwaway pod, or sidecar; the 'kubectl-netshoot' plugin wraps these into convenient subcommands.
Do I need anything besides Docker or kubectl?You just need Docker or a Kubernetes cluster to run the image; the optional 'kubectl-netshoot' plugin simply wraps the kubectl commands into ergonomic subcommands.
Does it include the full Wireshark GUI for packet analysis?No, it ships 'tshark' for protocol dissection and 'termshark' as a terminal UI for pcap files instead of the graphical Wireshark app, so deep inspection happens over CLI/TUI rather than a desktop GUI.
Who is this built for?It's aimed at DevOps engineers and SREs who need to diagnose DNS, latency, firewall, routing, or protocol problems inside Docker and Kubernetes environments.
Does it run on both Intel and ARM nodes?Contributors are required to confirm new tools work on both linux/amd64 and linux/arm64, so the image targets both architectures.
What troubleshooting scenarios does it cover out of the box?It has ready-made workflows for DNS resolution failures, latency/packet loss/throughput issues, pod-to-pod reachability and firewall checks, packet capture, gRPC/HTTP load testing, routing/ARP problems, and SMTP testing.
Can I attach it as a Kubernetes sidecar instead of a separate pod?Yes, the README explicitly lists running netshoot in Kubernetes as an ephemeral container, a throwaway pod, or a sidecar container.
What security and scanning tools come bundled?It includes nmap and nmap-nping for port scanning and packet crafting, openssl for TLS inspection, scapy for custom packet crafting in Python, and dhcping for DHCP probing.
Why not just install debugging tools into the container image I want to inspect?netshoot lets you enter the network namespace of any running container or host without modifying its image, so you avoid bloating production images just to debug a network issue.
What are similar projects?cilium, scapy, vps-security-enhancement-scripts, ProxmoxVE, witr, coredns, ecapture, ingress-nginx
Which topics is it in?kubectl, packet-capture, troubleshooting, network, grpc, network-security, dns, debugging, containers, http, security-tools, shell
Creator
nicolaka
Size
0.3 MB
Stars
11K
Updated
CommitJul 01
Age
10y
Commits · 90 Days