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
这是什么？netshoot 是一个用于排查 Docker 和 Kubernetes 网络问题的容器，相当于一个“瑞士军刀”式镜像，内置了网络、DNS、性能和安全等工具，用来调试容器和主机的网络故障。
这是需要安装的库，还是需要运行的容器镜像？它是一个预构建的 Docker 镜像，而不是库。它的工作原理是利用了这样一个特点：无需在任何容器或主机里安装东西，就能进入其网络命名空间。
我到底要怎样用 netshoot 来排查问题？可以用 Docker 启动（可选择共享目标容器的网络命名空间）、用 Docker Compose 启动，或在 Kubernetes 中以临时容器、一次性 Pod 或边车容器的方式启动；kubectl-netshoot 插件则把这些操作封装成了便捷的子命令。
除了 Docker 或 kubectl，我还需要别的东西吗？运行该镜像只需要 Docker 或一个 Kubernetes 集群；可选的 kubectl-netshoot 插件只是把 kubectl 命令封装成更易用的子命令。
它是否包含用于抓包分析的完整 Wireshark 图形界面？不包含。它自带 tshark 用于协议解析，并提供 termshark 作为处理 pcap 文件的终端界面，而不是图形化的 Wireshark 应用，因此深入分析需要通过命令行或终端界面（CLI/TUI）完成，而不是桌面图形界面。
这是为谁设计的？它面向需要在 Docker 和 Kubernetes 环境中诊断 DNS、延迟、防火墙、路由或协议问题的 DevOps 工程师和 SRE（站点可靠性工程师）。
它能在 Intel 和 ARM 节点上运行吗？贡献者必须确认新工具同时适用于 linux/amd64 和 linux/arm64，因此该镜像面向两种架构。
开箱即用，它覆盖了哪些排障场景？它内置了现成的工作流程，涵盖 DNS 解析失败、延迟/丢包/吞吐量问题、Pod 之间的连通性和防火墙检查、抓包、gRPC/HTTP 负载测试、路由/ARP 问题以及 SMTP 测试。
我能否把它作为 Kubernetes 边车容器来用，而不是单独建一个 Pod？可以。README 中明确列出了在 Kubernetes 中以临时容器、一次性 Pod 或边车容器的方式运行 netshoot。
它自带了哪些安全和扫描工具？它包含用于端口扫描和数据包构造的 nmap 与 nmap-nping，用于 TLS 检查的 openssl，用于在 Python 中自定义构造数据包的 scapy，以及用于 DHCP 探测的 dhcping。
为什么不直接把调试工具装进我要检查的容器镜像里？netshoot 让你无需修改任何运行中容器或主机的镜像，就能进入其网络命名空间，从而避免为了排查一个网络问题而让生产环境镜像变得臃肿。
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