├── examples ├── net-debug.yaml ├── net-debug-host.yaml └── net-debug-daemonset.yaml ├── LICENSE ├── .github └── workflows │ └── publish.yml ├── Dockerfile └── README.md /examples/net-debug.yaml: -------------------------------------------------------------------------------- 1 | apiVersion: apps/v1 2 | kind: Deployment 3 | metadata: 4 | name: net-debug 5 | spec: 6 | selector: 7 | matchLabels: 8 | app: net-debug 9 | replicas: 1 10 | template: 11 | metadata: 12 | labels: 13 | app: net-debug 14 | spec: 15 | containers: 16 | - name: net-debug 17 | image: docker.io/l7mp/net-debug 18 | -------------------------------------------------------------------------------- /examples/net-debug-host.yaml: -------------------------------------------------------------------------------- 1 | apiVersion: apps/v1 2 | kind: Deployment 3 | metadata: 4 | name: net-debug-host 5 | spec: 6 | selector: 7 | matchLabels: 8 | app: net-debug-host 9 | replicas: 1 10 | template: 11 | metadata: 12 | labels: 13 | app: net-debug-host 14 | spec: 15 | hostNetwork: true 16 | containers: 17 | - name: net-debug 18 | image: docker.io/l7mp/net-debug 19 | securityContext: 20 | privileged: true 21 | -------------------------------------------------------------------------------- /examples/net-debug-daemonset.yaml: -------------------------------------------------------------------------------- 1 | apiVersion: apps/v1 2 | kind: DaemonSet 3 | metadata: 4 | name: net-debug-host 5 | spec: 6 | selector: 7 | matchLabels: 8 | app: net-debug-host 9 | template: 10 | metadata: 11 | labels: 12 | app: net-debug-host 13 | spec: 14 | tolerations: 15 | # these tolerations are to have the daemonset runnable on control plane nodes 16 | # remove them if your control plane nodes should not run pods 17 | - key: node-role.kubernetes.io/control-plane 18 | operator: Exists 19 | effect: NoSchedule 20 | - key: node-role.kubernetes.io/master 21 | operator: Exists 22 | effect: NoSchedule 23 | hostNetwork: true 24 | containers: 25 | - name: net-debug 26 | image: docker.io/l7mp/net-debug 27 | securityContext: 28 | privileged: true 29 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 l7mp 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: "release" 2 | 3 | on: 4 | push: 5 | tags: 6 | - '*' 7 | 8 | jobs: 9 | push_to_registry: 10 | name: Push Docker image to Docker Hub 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Checkout 14 | uses: actions/checkout@v4 15 | 16 | - name: Docker meta 17 | id: meta 18 | uses: docker/metadata-action@v5 19 | with: 20 | images: l7mp/net-debug 21 | tags: | 22 | type=semver,pattern={{version}} 23 | type=raw,value=latest 24 | type=raw,value=alpine 25 | 26 | - name: Set up QEMU 27 | uses: docker/setup-qemu-action@v3 28 | 29 | - name: Set up Docker Buildx 30 | uses: docker/setup-buildx-action@v3 31 | 32 | - name: Login to Docker Hub 33 | uses: docker/login-action@v3 34 | with: 35 | username: ${{ secrets.DOCKER_USER }} 36 | password: ${{ secrets.DOCKER_TOKEN }} 37 | 38 | - name: Build and Push 39 | uses: docker/build-push-action@v5 40 | with: 41 | context: . 42 | platforms: linux/amd64,linux/arm64 43 | push: true 44 | tags: ${{ steps.meta.outputs.tags }} 45 | labels: ${{ steps.meta.outputs.labels }} 46 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | ########### 2 | # BUILD 3 | # Download and compress external binaries 4 | FROM alpine:3.23 AS builder 5 | 6 | ENV TURNCAT_VERSION=v1.1.0 7 | ENV WEBSOCAT_VERSION=v1.14.0 8 | 9 | WORKDIR /app 10 | RUN apk add --no-cache curl upx 11 | 12 | RUN apkArch="$(apk --print-arch)"; \ 13 | case "$apkArch" in \ 14 | aarch64) export FILENAME='websocat_max' ;; \ 15 | *) export FILENAME='websocat' ;; \ 16 | esac; \ 17 | curl -Lo websocat \ 18 | https://github.com/vi/websocat/releases/download/$WEBSOCAT_VERSION/$FILENAME.$(apk --print-arch)-unknown-linux-musl \ 19 | && chmod a+x websocat \ 20 | && upx --best --lzma websocat 21 | 22 | RUN apkArch="$(apk --print-arch)"; \ 23 | case "$apkArch" in \ 24 | aarch64) export ARCH='arm64' ;; \ 25 | *) export ARCH='amd64' ;; \ 26 | esac; \ 27 | curl -Lo turncat \ 28 | https://github.com/l7mp/stunner/releases/download/$TURNCAT_VERSION/turncat-$TURNCAT_VERSION-linux-$ARCH \ 29 | && chmod a+x turncat \ 30 | && upx --best --lzma turncat 31 | 32 | #### 33 | # NET-DEBUG 34 | FROM alpine:3.23 35 | 36 | RUN apk add --no-cache \ 37 | bash \ 38 | bmon \ 39 | bridge-utils \ 40 | curl \ 41 | bind-tools \ 42 | ebtables \ 43 | ethtool \ 44 | iftop \ 45 | iperf \ 46 | iproute2 \ 47 | iptables \ 48 | iputils \ 49 | less \ 50 | nano \ 51 | net-tools \ 52 | nmap \ 53 | procps \ 54 | socat \ 55 | tcpdump \ 56 | traceroute \ 57 | tar \ 58 | wget \ 59 | tcpreplay 60 | 61 | COPY --from=builder /app/websocat /usr/bin/ 62 | COPY --from=builder /app/turncat /usr/bin/ 63 | 64 | CMD exec /bin/bash -c "trap : TERM INT; sleep infinity & wait" 65 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 | Discord 6 |

7 | 8 | # net-debug 9 | 10 | ## Description 11 | 12 | Assorted network debugging goodies, like `tcpdump`, `socat`/`websocat`, `iperf`, `nmap`, `nslookup`, `dig`, `tcpreplay`, and `ping`/`traceroute`, all packaged in a self-contained Docker image. The intended use is to sideload the container as a sidecar to Kubernetes pods in order to debug network reachability and performance issues. 13 | 14 | ## Usage examples 15 | 16 | ### Create a Deployment 17 | 18 | Config: [yaml](examples/net-debug.yaml) 19 | 20 | Usage: 21 | ```console 22 | kubectl apply -f examples/net-debug.yaml 23 | ``` 24 | or 25 | ```console 26 | kubectl apply -f https://raw.githubusercontent.com/l7mp/net-debug/refs/heads/main/examples/net-debug.yaml 27 | ``` 28 | 29 | ### Create a Deployment in host network 30 | Config: [yaml](examples/net-debug-host.yaml) 31 | 32 | Usage: 33 | ```console 34 | kubectl apply -f examples/net-debug-host.yaml 35 | ``` 36 | or 37 | ```console 38 | kubectl apply -f https://raw.githubusercontent.com/l7mp/net-debug/refs/heads/main/examples/net-debug-host.yaml 39 | ``` 40 | 41 | ### Create a DeamonSet in host network 42 | 43 | Config: [yaml](examples/net-debug-daemonset.yaml) 44 | 45 | Usage: 46 | ```console 47 | kubectl apply -f examples/net-debug-dameonset.yaml 48 | ``` 49 | or 50 | ```console 51 | kubectl apply -f https://raw.githubusercontent.com/l7mp/net-debug/refs/heads/main/examples/net-debug-daemonset.yaml 52 | ``` 53 | 54 | ### Attach to a pod as debug container 55 | 56 | To attach net-debug to an existing pod as a [debug container](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_debug/): 57 | ```console 58 | kubectl debug -it --image=docker.io/l7mp/net-debug -- bash 59 | ``` 60 | 61 | ## Help 62 | 63 | Development is coordinated in Discord, feel free to [join](https://discord.gg/DyPgEsbwzc). 64 | 65 | ## License 66 | 67 | MIT License - see [LICENSE](LICENSE) for full text. 68 | --------------------------------------------------------------------------------