Netshoot — Container Network Troubleshooting Toolkit

Introduction

Netshoot is a purpose-built container image loaded with every networking diagnostic tool you might need when troubleshooting containerized applications. Instead of installing tools into production images, you spin up netshoot alongside the target and diagnose from a fully equipped environment.

What Netshoot Does

• Provides 40+ pre-installed networking utilities in a single image
• Joins the network namespace of any Docker container or Kubernetes pod
• Supports ephemeral debug containers in Kubernetes 1.23+
• Includes tools for DNS, HTTP, packet capture, bandwidth, and TLS debugging
• Works across Docker, Kubernetes, Docker Compose, and containerd environments

Architecture Overview

Netshoot is an Alpine-based container image with network diagnostic packages pre-installed. It has no running daemon; you launch it interactively and run tools manually. When attached via --net container: or kubectl debug, it shares the target's network namespace, seeing the same interfaces, routes, and iptables rules.

Self-Hosting & Configuration

• Pull the image with docker pull nicolaka/netshoot
• No configuration files needed; all tools are ready at launch
• Use --net host to diagnose the host network stack directly
• In Kubernetes, use kubectl debug with --target to share the pod's process namespace
• Pin a specific tag (e.g., nicolaka/netshoot:v0.13) for reproducible environments

Key Features

• Includes tcpdump, tshark, nmap, iperf3, mtr, dig, nslookup, curl, wget, and openssl
• Ships termshark for TUI-based packet analysis
• Contains ctop, calicoctl, and etcdctl for container and cluster inspection
• Supports both amd64 and arm64 architectures
• Minimal base image keeps the download under 200 MB

Comparison with Similar Tools

• busybox — much smaller but lacks advanced tools like tcpdump, nmap, and iperf
• alpine — requires manual package installation for each debugging session
• kubectl exec — limited to tools already in the target container
• nixery — builds custom images on demand but requires a registry and build step

FAQ

Q: Does netshoot affect the target container? A: No. It runs as a separate process sharing only the network namespace. It cannot modify the target's filesystem or processes unless you also share the PID namespace.

Q: Can I use netshoot in production clusters? A: Yes. Ephemeral debug containers are the recommended approach in Kubernetes. They leave no trace after the session ends.

Q: How do I capture packets and save them locally? A: Run tcpdump -w /tmp/capture.pcap inside netshoot, then copy the file out with kubectl cp or docker cp.

Q: Is netshoot available for ARM? A: Yes. Multi-architecture images are published for both amd64 and arm64.

Sources

• https://github.com/nicolaka/netshoot
• https://hub.docker.com/r/nicolaka/netshoot