netshoot

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

10,938

1,095

10,938

View on GitHub

Top Related Projects

pumba

3,090

Chaos testing, network emulation, and stress testing tool for containers

scope

5,908

Monitoring, visualisation & management for Docker & Kubernetes

cilium

24,708

eBPF-based Networking, Security, and Observability

kubeshark

12,051

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

kubeshark

12,009

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

linkerd

5,310

Old repo for Linkerd 1.x. See the linkerd2 repo for Linkerd 2.x.

Quick Overview

The nicolaka/netshoot repository is a collection of network debugging tools and utilities packaged in a Docker container. It provides a convenient way to troubleshoot and analyze network issues without the need to install various tools on the host system.

Pros

Portability: The Docker container can be easily deployed and used on any system with Docker installed, making it platform-independent.
Comprehensive Tools: The repository includes a wide range of network debugging tools, such as tcpdump, ngrep, dig, curl, and netcat, among others.
Easy to Use: The container can be quickly launched with a single Docker command, providing a self-contained environment for network analysis.
Reproducibility: The Docker image ensures a consistent and reproducible environment for network troubleshooting, making it easier to share and collaborate on network issues.

Cons

Requires Docker: Users must have Docker installed on their system to take advantage of the nicolaka/netshoot container, which may not be suitable for all environments.
Limited to Container Networking: The tools within the container are limited to analyzing network traffic within the container itself, and may not provide a complete view of the overall network.
Potential Performance Impact: Running network debugging tools within a container may have a slight performance impact compared to running them directly on the host system.
Dependency on Docker Image Updates: Users are dependent on the maintainers of the nicolaka/netshoot Docker image to keep the tools up-to-date and secure.

Getting Started

To use the nicolaka/netshoot container, follow these steps:

Ensure you have Docker installed on your system.
Pull the latest nicolaka/netshoot Docker image:
```
docker pull nicolaka/netshoot
```
Launch the container with the desired network interface and options:
```
docker run -it --rm --network host nicolaka/netshoot
```
This command will start the container in interactive mode, attach it to the host network, and remove the container when you exit.
Once inside the container, you can use the various network debugging tools as needed. For example, to capture network traffic using tcpdump:
```
tcpdump -i eth0 -n
```
This will start capturing network traffic on the eth0 interface and display the packets in a human-readable format.
Explore the other tools available in the container, such as ngrep, dig, curl, and netcat, to diagnose and troubleshoot network issues.

Remember, the nicolaka/netshoot container is a self-contained environment, so any changes or data within the container will not persist beyond the container's lifetime. Use it as a temporary tool for network analysis and debugging.

Competitor Comparisons

pumba

3,090

Chaos testing, network emulation, and stress testing tool for containers

Pros of Pumba

Focused on chaos testing and network emulation for Docker containers
Provides a CLI tool for easy integration into CI/CD pipelines
Supports advanced network emulation scenarios like packet loss and latency

Cons of Pumba

Limited to Docker environments, not as versatile for general networking tasks
Requires more setup and configuration compared to Netshoot's ready-to-use container
Less comprehensive set of networking tools for general troubleshooting

Code Comparison

Netshoot usage:

docker run -it --net container:<container_name> nicolaka/netshoot

Pumba usage:

pumba netem --duration 5m delay --time 3000 re2:^web

Summary

Netshoot is a versatile networking troubleshooting toolkit container, while Pumba focuses on chaos testing and network emulation for Docker environments. Netshoot offers a wide range of pre-installed networking tools, making it ideal for quick diagnostics and general-purpose networking tasks. Pumba, on the other hand, excels in creating controlled chaos scenarios and network disruptions for testing container resilience.

Netshoot is more user-friendly for ad-hoc troubleshooting, whereas Pumba is better suited for automated testing and CI/CD integration. The choice between the two depends on the specific use case: general networking diagnostics (Netshoot) or targeted chaos testing in Docker environments (Pumba).

scope

5,908

Monitoring, visualisation & management for Docker & Kubernetes

Pros of Scope

Provides a comprehensive visualization of container networks and applications
Offers real-time monitoring and troubleshooting capabilities
Integrates well with Kubernetes and other container orchestration platforms

Cons of Scope

Requires more setup and resources to run compared to Netshoot
May be overkill for simple network diagnostics tasks
Has a steeper learning curve for users new to container networking

Code Comparison

Netshoot usage:

docker run -it --net container:<container_name> nicolaka/netshoot

Scope usage:

scope launch

Summary

Netshoot is a lightweight, container-based network troubleshooting toolkit, while Scope is a more comprehensive monitoring and visualization tool for container environments. Netshoot excels in quick, targeted diagnostics, whereas Scope provides a broader view of network topology and application performance. The choice between the two depends on the specific needs of the user and the complexity of the environment being monitored or troubleshooted.

cilium

24,708

eBPF-based Networking, Security, and Observability

Pros of Cilium

Comprehensive network security and observability solution for cloud-native environments
Advanced eBPF-based networking, security, and visibility features
Scalable and performant for large Kubernetes clusters

Cons of Cilium

Steeper learning curve due to its complexity and advanced features
Requires more resources and setup compared to lightweight tools
May be overkill for simple networking diagnostics tasks

Code Comparison

Netshoot (Dockerfile excerpt):

FROM alpine:latest
RUN apk update && apk add --no-cache \
    bash tcpdump curl iperf3 mtr nmap

Cilium (Helm chart values example):

cilium:
  enabled: true
  hubble:
    enabled: true
  nodePort:
    enabled: true
  kubeProxyReplacement: strict

Summary

Netshoot is a lightweight, container-based networking troubleshooting toolkit, while Cilium is a full-featured, eBPF-powered networking solution for Kubernetes. Netshoot excels in quick diagnostics and debugging, whereas Cilium provides comprehensive network security, observability, and advanced features for cloud-native environments. Choose Netshoot for simple troubleshooting tasks and Cilium for robust, scalable networking in complex Kubernetes deployments.

kubeshark

12,051

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

Pros of Kubeshark

Specialized for Kubernetes environments, offering deep insights into cluster traffic
Provides a user-friendly web interface for real-time traffic analysis
Supports protocol-aware API traffic inspection for various services

Cons of Kubeshark

More complex setup and resource-intensive compared to Netshoot
Limited to Kubernetes environments, less versatile for general networking tasks
Steeper learning curve for users not familiar with Kubernetes concepts

Code Comparison

Netshoot usage:

docker run -it --net container:<container_name> nicolaka/netshoot

Kubeshark usage:

kubeshark tap

Key Differences

Netshoot is a lightweight, versatile networking troubleshooting toolkit that can be used in various container environments. It's ideal for quick diagnostics and general-purpose networking tasks.

Kubeshark, on the other hand, is a specialized tool for Kubernetes environments, offering deep packet inspection and API-level traffic analysis. It provides a more comprehensive view of cluster communications but requires more resources and setup.

While Netshoot is better suited for quick, ad-hoc troubleshooting across different container platforms, Kubeshark excels in providing detailed, continuous monitoring and analysis specifically for Kubernetes clusters.

kubeshark

12,009

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

Pros of Kubeshark

Specialized for Kubernetes environments, offering deep insights into cluster traffic
Provides a user-friendly web interface for real-time traffic analysis
Supports protocol-aware API traffic inspection for various services

Cons of Kubeshark

More complex setup and resource-intensive compared to Netshoot
Limited to Kubernetes environments, less versatile for general networking tasks
Steeper learning curve for users not familiar with Kubernetes concepts

Code Comparison

Netshoot usage:

docker run -it --net container:<container_name> nicolaka/netshoot

Kubeshark usage:

kubeshark tap

Key Differences

Netshoot is a lightweight, versatile networking troubleshooting toolkit that can be used in various container environments. It's ideal for quick diagnostics and general-purpose networking tasks.

linkerd

5,310

Old repo for Linkerd 1.x. See the linkerd2 repo for Linkerd 2.x.

Pros of Linkerd

Full-featured service mesh for Kubernetes with advanced traffic management
Provides automatic mTLS, observability, and load balancing
Lightweight and easy to install with minimal configuration

Cons of Linkerd

More complex setup and learning curve compared to Netshoot
Focused on Kubernetes environments, less versatile for general networking tasks
Requires cluster-wide installation and management

Code Comparison

Linkerd (Kubernetes deployment):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    linkerd.io/inject: enabled

Netshoot (Docker run command):

docker run -it --net container:<container_name> nicolaka/netshoot

Summary

Linkerd is a comprehensive service mesh solution for Kubernetes, offering advanced networking features and observability. Netshoot, on the other hand, is a versatile networking troubleshooting toolkit that can be used in various environments.

Linkerd excels in managing complex microservices architectures, providing automatic security and observability. However, it has a steeper learning curve and is primarily designed for Kubernetes.

Netshoot is more flexible and easier to use for general networking diagnostics across different platforms. It's ideal for quick troubleshooting but lacks the advanced features of a full service mesh.

Choose Linkerd for comprehensive Kubernetes networking management, or Netshoot for versatile, on-demand networking diagnostics and troubleshooting.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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.

Debug a container without installing tools into its image
Debug a host without installing anything on it
Debug in Kubernetes as an ephemeral container, throwaway pod, or sidecar

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 user@example.com \
  --from probe@example.com \
  --server mail.example.com:587 \
  --tls \
  --auth PLAIN \
  --auth-user user@example.com \
  --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:

Explain why the tool isn't redundant with something already in the image
Update the Dockerfile to add the package, or add a get_<tool>() function to build/fetch_binaries.sh for pre-built binaries
Add the tool to the Included Tools table and a Troubleshooting Scenarios block with a real workflow
For multi-platform tools, confirm linux/amd64 and linux/arm64 both work

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot