How do I actually run this thing?

Just run the damn thing: `docker run -it --rm nicolaka/netshoot`. If this fails, Docker itself is fucked and you have bigger problems. For Kubernetes: `kubectl debug your-broken-pod -it --image=nicolaka/netshoot`. If you're still on Kubernetes < 1.25, I'm sorry for your loss - you'll need [workarounds](https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/).

Why can't I capture packets with tcpdump?

Docker security defaults. You need `--cap-add=NET_ADMIN --cap-add=NET_RAW` or tcpdump just sits there returning nothing. Wasted 2 hours on this once thinking the network was fine. Tried everything - different interfaces, different filters. Finally found some random Stack Overflow post mentioning capabilities. Classic Friday debugging session.Pro tip: Always check if your container is actually listening on 0.0.0.0, not 127.0.0.1. Ask me how I know - spent 4 hours debugging "network issues" when the app was only binding to localhost.```bash# This fails silently (you'll waste time)docker run -it --net container:broken-app nicolaka/netshoot tcpdump -i eth0# This actually worksdocker run -it --cap-add=NET_ADMIN --cap-add=NET_RAW --net container:broken-app nicolaka/netshoot tcpdump -i eth0```

DNS works from host but fails in netshoot. What fresh hell is this?

Welcome to the wonderful world of container networking where nothing makes sense. Container DNS != host DNS. Your container might be using some janky internal DNS server, or Kubernetes DNS is being its usual shitty self. First thing: check what DNS servers you're actually hitting.```bash# See what DNS servers you're actually usingcat /etc/resolv.conf# Test with different DNS serversdig @8.8.8.8 your-service.default.svc.cluster.localdig @1.1.1.1 your-service.default.svc.cluster.local```

Can I use this in production without getting fired?

That's literally why this thing exists. Netshoot doesn't touch your containers - it just borrows their network namespace for debugging. Your security team will have a meltdown about 200MB and demand you use a 5MB Alpine container that has zero useful tools, but you can tell them to calculate the revenue loss from a 2-hour outage vs downloading 150MB once. Math usually wins.

Why does my container say "network namespace not found"?

Your target container probably died. Check if it's still running with `docker ps` or `kubectl get pods`. If it's in CrashLoopBackOff, you can't attach to a dead container's network namespace. Fix the crashing first, then debug.

How do I capture traffic and actually save it somewhere useful?

Mount a volume to persist the capture files, otherwise they disappear when the container exits:```bash# Save captures to host filesystemdocker run -it --cap-add=NET_ADMIN --cap-add=NET_RAW --net container:app -v /tmp:/tmp nicolaka/netshoot# Then inside netshoottcpdump -i eth0 -w /tmp/capture.pcap```

Does this work with Istio/service mesh bullshit?

Yes, but service mesh makes everything more complicated. You can debug both the app container and the sidecar proxy. For Istio, you'll be debugging Envoy proxy behavior, which is its own special kind of hell. Good luck with that.

My tcpdump shows traffic but my app still can't connect. Now what?

Packets reaching the interface doesn't mean they're getting to your application. Check if your app is actually listening on the right port:```bash# See what's actually listeningss -tulpn | grep :5432# Test if your app is respondingtelnet localhost 5432```

Can I add my own tools to netshoot?

Fork [the repo](https://github.com/nicolaka/netshoot) and build your own. But honestly, it already has most things you need.

Why is netshoot better than just installing tools when I need them?

Because installing tcpdump during a production outage is how you get fired. Security best practices say keep your production containers minimal, and netshoot lets you debug without modifying anything permanently.

My team lead says BusyBox is "good enough" for debugging.

Your team lead said this while sipping coffee at 2pm. Ask them again during the next outage when production is down and customers are screaming. BusyBox is fine for toy examples, but try running tcpdump on it during an actual incident. I'll wait. Show them this: netshoot gets you debugging in 30 seconds, BusyBox gets you fired after you spend 27 minutes figuring out how to install tcpdump while revenue bleeds at $50k/minute. *Each container gets its own network namespace - completely isolated from other containers until you explicitly connect them*

How do I debug Kubernetes networking when everything is "Running" but broken?

This is the classic Kubernetes networking problem where everything looks fine but nothing works. Start with:```bash# Attach netshoot to the broken podkubectl debug broken-pod -it --image=nicolaka/netshoot# Test basic connectivityping google.comcurl -v https://httpbin.org/status/200# Check DNSnslookup other-service.same-namespace.svc.cluster.local```Most of the time it's DNS being weird, service discovery failing, or network policies blocking traffic. ![Kubernetes Architecture](https://kubernetes.io/images/docs/kubernetes-cluster-architecture.svg) *Kubernetes cluster architecture - lots of places where networking can break*

Currently viewing the AI version

Switch to human version

Netshoot: Container Network Debugging Tool - AI-Optimized Reference

Overview

Netshoot is a 200MB Docker container with comprehensive networking debugging tools for troubleshooting container connectivity issues. Built by Nicola Kabar to eliminate the need to install debugging tools during production outages.

Critical Use Cases

Production Outages: When containers can't communicate and debugging tools aren't installed on hosts
Connection Refused Errors: API connectivity failures, database connection issues
DNS Resolution Problems: Service discovery failures in Kubernetes environments
Network Performance Issues: Bandwidth testing and traffic analysis

Resource Requirements

Time Costs

Netshoot deployment: 30 seconds
Alternative tool installation: 10-20 minutes during outages
Custom debugging setup: 2+ hours

Expertise Requirements

Basic usage: Docker/Kubernetes command knowledge
Advanced debugging: Network troubleshooting experience, packet analysis skills
Packet capture: Understanding of tcpdump, Wireshark, network protocols

Financial Impact

Outage cost: $50k/minute revenue loss (typical enterprise)
Tool download cost: $0.03 bandwidth
Image size concern: 200MB (security teams object, but cost-benefit favors usage)

Configuration

Working Production Commands

Basic Container Attachment

# Attach to broken container's network namespace
docker run -it --net container:broken-app nicolaka/netshoot

# Test basic connectivity
curl -v https://httpbin.org/get

Kubernetes Debugging

# Modern Kubernetes (1.25+) - ephemeral containers
kubectl debug broken-pod -it --image=nicolaka/netshoot

# Legacy Kubernetes (<1.25) - workaround required
kubectl run netshoot --rm -i --tty --image nicolaka/netshoot

Packet Capture (Requires Capabilities)

# CRITICAL: Must include capabilities or tcpdump fails silently
docker run -it --cap-add=NET_ADMIN --cap-add=NET_RAW --net container:app nicolaka/netshoot tcpdump -i eth0

# Save packet captures
docker run -it --cap-add=NET_ADMIN --cap-add=NET_RAW --net container:app -v /tmp:/tmp nicolaka/netshoot
tcpdump -i eth0 -w /tmp/capture.pcap

Host Network Debugging

# Debug Docker daemon networking issues
docker run -it --net host nicolaka/netshoot
ip addr show docker0

Critical Warnings

Failure Modes That Will Waste Time

Silent tcpdump Failure

Problem: tcpdump returns no output without error messages
Root Cause: Missing NET_ADMIN and NET_RAW capabilities
Time Lost: 17-20 minutes typical
Solution: Always include --cap-add=NET_ADMIN --cap-add=NET_RAW

DNS Resolution Inconsistency

Problem: DNS works on host but fails in container
Root Cause: Container DNS != host DNS configuration
Debugging: Check /etc/resolv.conf inside container
Test multiple DNS servers: dig @8.8.8.8 vs dig @1.1.1.1

Network Namespace Attachment Failure

Problem: "network namespace not found" error
Root Cause: Target container crashed or restarted
Check: Verify container status with docker ps or kubectl get pods
Note: Cannot attach to dead container's network namespace

Container Binding Issues

Problem: tcpdump shows traffic but app can't connect
Root Cause: Application binding to 127.0.0.1 instead of 0.0.0.0
Verification: ss -tulpn | grep :PORT to check listening addresses

Tool Inventory

Packet Analysis Tools

tcpdump: Command-line packet capture
termshark: Terminal-based Wireshark interface
tshark: Command-line packet inspection
Use cases: MTU issues, load balancer connection drops, service mesh debugging

Connectivity Testing Tools

curl: HTTP/HTTPS testing
telnet: Port connectivity testing
nc (netcat): Network connection testing
nmap: Port scanning and service discovery
ping/traceroute: Layer 3 connectivity testing

DNS Debugging Tools

dig: Primary DNS lookup tool
nslookup: Basic DNS queries
host: Simple DNS lookups
drill: Advanced DNS testing
Critical: DNS is the most common failure point in container environments

Performance Testing Tools

iperf3: Bandwidth testing between containers
fortio: HTTP load testing
Use case: Distinguish network issues from application performance problems

Version-Specific Issues

Kubernetes Compatibility

1.25+: Full ephemeral container support with kubectl debug
1.24 and earlier: No ephemeral containers, requires sidecar workarounds
1.23: Random 30-second DNS timeout bug affecting API performance

Container Runtime Issues

Docker 20.10.8: Breaks volume mounts on SELinux systems
Recommendation: Use 20.10.7 or 20.10.9
Alpine Linux: Some eBPF tools incompatible with certain kernel versions
CRI-O/gVisor: Limited tool compatibility compared to Docker/containerd

Comparison Matrix

Tool	Deployment Time	Tools Included	Production Ready	Size	tcpdump Ready
Netshoot	30 seconds	Everything needed	✅ Yes	200MB	✅ Yes
BusyBox	20 min setup	Minimal	❌ No	5MB	❌ No
Alpine	10 min setup	Install required	❌ Maybe	15MB	❌ No
Ubuntu Debug	15 min setup	Install required	❌ Slow	200MB	❌ No

Common Debugging Workflows

Connection Refused Troubleshooting

Attach netshoot to broken container
Test basic connectivity: curl -v target-service
Check DNS resolution: nslookup target-service
Verify port accessibility: telnet target-service port
Check listening services: ss -tulpn

DNS Debugging Workflow

# Check DNS configuration
cat /etc/resolv.conf

# Test multiple DNS servers
dig @8.8.8.8 service.namespace.svc.cluster.local
dig @1.1.1.1 service.namespace.svc.cluster.local

# Verify service discovery
nslookup service.namespace.svc.cluster.local

Packet Capture Analysis

# Real-time HTTP traffic monitoring
tcpdump -i eth0 -A -s 0 'tcp port 80'

# Comprehensive traffic capture
tcpdump -i eth0 -w /tmp/capture.pcap

# Bandwidth testing
iperf3 -s    # Server mode
iperf3 -c target-ip    # Client mode

Security Considerations

Image size objections: Security teams resist 200MB images
Capability requirements: NET_ADMIN and NET_RAW needed for packet capture
Network namespace isolation: Debugging doesn't modify target containers
Production deployment: Designed for production use, not development convenience

Integration Points

GitHub Stars: 9,800+ (indicates wide adoption)
Platform Support: AMD64 and ARM64 architectures
Documentation: Referenced in Kubernetes official troubleshooting guides
Cloud Provider Support: Mentioned in AWS, GCP, Azure troubleshooting documentation

Failure Recovery Strategies

Outage scenario: Deploy netshoot immediately, debug while fixing
DNS issues: Always check DNS first (despite being counter-intuitive)
Service mesh problems: Debug both application and sidecar proxy containers
Network policies: Use netshoot to test connectivity between specific pods

Alternative Tools Assessment

kubectl-sniff: Kubernetes-specific packet capture plugin
BusyBox: Insufficient for production debugging
Custom debugging containers: Time-intensive to build and maintain
Host-based tools: Risk installing on production systems during outages

This reference provides the operational intelligence needed for rapid container network debugging during production incidents, with emphasis on avoiding common time-wasting pitfalls and configuration errors.

Useful Links for Further Investigation

Essential Netshoot Resources

Link	Description
Netshoot GitHub Repository	Where the magic happens. Nicola actually maintains this unlike 90% of GitHub repos.
Netshoot Docker Hub	Where you actually pull this from.
kubectl-netshoot Plugin	Someone built a kubectl plugin for this. Saves you from typing the full debug command every time.
Kubernetes Ephemeral Containers Documentation	Boring as hell but you need this if you want to understand what kubectl debug actually does.
kubectl debug Command Reference	All the kubectl debug flags explained. Bookmark this because you'll forget the syntax.
Krew Plugin Manager	Kubectl plugin manager. Install this if you want the netshoot plugin or other kubectl extensions.
Network Troubleshooting in Kubernetes with Netshoot	Actually useful tutorial. Luca shows real debugging scenarios instead of the usual 'hello world' garbage.
Kubernetes Ephemeral Containers: Debugging on the Fly	This resource provides insights into Kubernetes ephemeral containers, explaining how to use them for debugging applications and services directly within your cluster on the fly.
Docker Networking Deep Dive	Official Docker networking docs. One of the few Docker docs that doesn't completely suck and actually explains networking.
Brendan Gregg's Linux Performance Tools	This diagram illustrates Brendan Gregg's comprehensive set of Linux performance observability tools, explaining why netshoot includes a wide array of utilities beyond just tcpdump.
Wireshark Documentation	Official Wireshark documentation, essential for analyzing the detailed packet captures generated by netshoot. This resource is dense but provides comprehensive information.
iperf3 Documentation	Official iperf3 documentation, useful for understanding how to perform bandwidth testing. Netshoot integrates iperf3 to help prove whether network performance is a bottleneck.
BusyBox	A minimalist set of Unix utilities often used in embedded systems. While lightweight, it's generally insufficient for debugging complex production networking issues.
kubectl-sniff	A kubectl plugin designed for sniffing network traffic directly within Kubernetes pods. It provides a convenient way to capture and analyze network packets in your cluster.
Polaris	A Kubernetes configuration validator that helps identify and prevent common misconfigurations, including those related to networking, before they cause issues in production environments.
Cloud Native Computing Foundation (CNCF)	The official CNCF landscape, providing an overview of the vast ecosystem of cloud-native projects. It highlights the numerous components that netshoot can help debug.
Kubernetes Slack #troubleshooting	The official Kubernetes Slack workspace, offering a dedicated #troubleshooting channel where users can seek assistance and discuss solutions for Kubernetes-related issues.
Docker Community Forums	Official Docker community forums, a platform for users to ask questions, share knowledge, and find solutions. Netshoot is frequently recommended for networking problems here.
Cilium	An open-source, eBPF-based networking, security, and observability solution for cloud-native environments. It integrates effectively with netshoot for advanced debugging scenarios.
Calico	A widely used open-source networking and network security solution for containers, virtual machines, and native host-based workloads. Its documentation often includes netshoot for debugging network policies.
Istio Service Mesh	An open-source service mesh that provides traffic management, security, and observability for microservices. Netshoot is valuable for debugging the complex Envoy proxy issues often encountered with Istio.

When your containers can't find each other and everything goes to shit

Docker Swarm

/troubleshoot/docker-swarm-production-failures/service-discovery-routing-mesh-failures

56%

Recommendations combine user behavior, content similarity, research intelligence, and SEO optimization