Debugging Container Networking Without Entering the Shell

You’re troubleshooting a "connection refused" or timeout error inside a container, but the image is minimal (Alpine, Distroless, or scratch-based) and lacks standard networking tools like curl, ping, or ip. You cannot install packages to save the day, and entering the container via docker exec fails because there is no shell to spawn. You need to inspect the network stack of the running process from the host perspective without modifying the container image.

The Quick Host-Side Inspection

Instead of trying to hack the container, use nsenter to attach to the specific network namespace of the running container process from the host. This allows you to run standard host networking tools against the container’s isolated network stack.

First, find the PID of the container’s main process:

docker inspect -f '{{.State.Pid}}' <container_name_or_id>

Then, use nsenter to jump into that process’s network namespace. For example, to check the routing table and interfaces:

sudo nsenter -n -t <PID> ip route
sudo nsenter -n -t <PID> ip addr

To test connectivity without needing curl inside the container, use netcat (nc) or ping from the host but bound to the container’s network namespace:

# Check if a port is open inside the container's netns
sudo nsenter -n -t <PID> nc -zv 127.0.0.1 <port>

# Ping a gateway to verify outbound connectivity
sudo nsenter -n -t <PID> ping -c 3 <gateway_ip>

If you need to see which processes are listening on ports within that namespace:

sudo nsenter -n -t <PID> netstat -tulpn
# Or for newer systems using ss:
sudo nsenter -n -t <PID> ss -tulpn

Why It Works

Linux containers share the kernel with the host but isolate resources using namespaces. Network interfaces, routing tables, and firewall rules are isolated within a specific network namespace. By using nsenter -n -t <PID>, you temporarily switch your current shell’s context into that specific network namespace. This means any command you run (like ping or ss) operates with the visibility and permissions of the container’s network stack, while still using the robust, pre-installed tools available on your host OS. This bypasses the need for the container to have any debugging tools installed.

Pro Tip

Create a simple alias for quick access to any container’s network namespace. Add this to your ~/.bashrc or ~/.zshrc:

netns() {
  local pid=$(docker inspect -f '{{.State.Pid}}' "$1")
  if [ -z "$pid" ]; then echo "Container not found" >&2; return 1; fi
  sudo nsenter -n -t "$pid" "${@:2}"
}

Now you can run netns my-container ip addr or netns my-container ss -tulpn instantly. Note that this requires sudo privileges and nsenter installed on the host (part of util-linux on most distros). Always verify the PID belongs to the container process, not a sidecar, by checking docker inspect output for the specific container ID.