## 1. Project Overview & Quickstart (nicolaka/netshoot)

## 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

```bash
# 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  -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

```bash
# 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/ sh
```

### Docker Compose

```yaml
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

```bash
# Ephemeral container in a running pod (non-destructive)
kubectl debug  -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  -c netshoot -- zsh
```

#### kubectl plugin

The [kubectl-netshoot plugin](https://github.com/nilic/kubectl-netshoot) wraps the above into ergonomic subcommands:

```bash
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._

```bash
# 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._

```bash
# 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  -t 30

# Measure UDP throughput and jitter
iperf3 -c  -u -b 1G
```

---

### Service reachability and firewall rules

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

```bash
# Quick TCP connectivity check
nc -vz <host> 

# 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> 

# 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._

```bash
# 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  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._

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

# Call a gRPC method
grpcurl -d '{"key":"value"}' <host>: 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._

```bash
# 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._

```bash
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

```bash
# 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

## 2. Official Technical Reference & Guides (nicolaka/docs)

Rancher Docs
------------

## Running for development/editing

The `rancher/docs:dev` docker image runs a live-updating server.  To run on your workstation, run:

Linux
```bash
  ./scripts/dev
```

Windows
```powershell
./scripts/dev-windows.ps1
```

and then navigate to http://localhost:9001/.  You can customize the port by passing it as an argument:

Linux
```bash
  ./scripts/dev 8080
```

Windows
```powershell
./scripts/dev-windows.ps1 -port 8080
```

License
=======
Copyright (c) 2014-2019 [Rancher Labs, Inc.](https://rancher.com)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.