diff --git a/content/manuals/dhi/how-to/debug.md b/content/manuals/dhi/how-to/debug.md index a05d29428490..8c277cc620df 100644 --- a/content/manuals/dhi/how-to/debug.md +++ b/content/manuals/dhi/how-to/debug.md @@ -14,12 +14,13 @@ Debug](../../../reference/cli/docker/debug.md), a secure workflow that temporarily attaches an ephemeral debug container to a running service or image without modifying the original image. -This guide shows how to debug Docker Hardened Images locally during -development. You can also debug containers remotely using the `--host` option. +This guide shows how to debug Docker Hardened Images locally during development. +With Docker Debug, you can also debug containers remotely using the `--host` +option. -The following example uses a mirrored `python:3.13` image, but the same steps apply to any image. +## Use Docker Debug -## Step 1: Run a container from a Hardened Image +### Step 1: Run a container from a Hardened Image Start with a DHI-based container that simulates an issue: @@ -41,7 +42,7 @@ You'll see: exec: "sh": executable file not found in $PATH ``` -## Step 2: Use Docker Debug to inspect the container +### Step 2: Use Docker Debug to inspect the container Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance. @@ -57,17 +58,75 @@ For example, to check running processes: $ ps aux ``` -Exit the debug session with: +Type `exit` to leave the container when done. + +## Alternative debugging approaches + +In addition to using Docker Debug, you can also use the following approaches for +debugging DHI containers. + +### Use the -dev variant + +Docker Hardened Images offer a `-dev` variant that includes a shell +and a package manager to install debugging tools. Simply replace the image tag +with `-dev`: + +```console +$ docker run -it --rm dhi.io/python:3.13-dev sh +``` + +Type `exit` to leave the container when done. Note that using the `-dev` variant +increases the attack surface and it is not recommended as a runtime for +production environments. + +### Mount debugging tools with image mounts + +You can use the image mount feature to mount debugging tools into your container +without modifying the base image. + +#### Step 1: Run a container from a Hardened Image + +Start with a DHI-based container that simulates an issue: ```console -$ exit +$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" ``` +#### Step 2: Mount debugging tools into the container + +Run a new container that mounts a tool-rich image (like `busybox`) into +the running container's namespace: + +```console +$ docker run --rm -it --pid container:myapp \ + --mount type=image,source=busybox,destination=/dbg,ro \ + dhi.io/python:3.13 /dbg/bin/sh +``` + +This mounts the BusyBox image at `/dbg`, giving you access to its tools while +keeping your original container image unchanged. Since the hardened Python image +doesn't include standard utilities, you need to use the full path to the mounted +tools: + +```console +$ /dbg/bin/ls / +$ /dbg/bin/ps aux +$ /dbg/bin/cat /etc/os-release +``` + +Type `exit` to leave the container when done. + ## What's next -Docker Debug helps you troubleshoot hardened containers without compromising the -integrity of the original image. Because the debug container is ephemeral and -separate, it avoids introducing security risks into production environments. +This guide covered three approaches for debugging Docker Hardened Images: + +- Docker Debug: Attach an ephemeral debug container without modifying the original image +- `-dev` variants: Use development images that include debugging tools +- Image mount: Mount tool-rich images like BusyBox to access debugging utilities + +Each method helps you troubleshoot hardened containers while maintaining +security. Docker Debug and image mounts avoid modifying your production images, +while `-dev` variants provide convenience during development. If you encounter issues related to permissions, ports, missing shells, or package managers, see [Troubleshoot Docker Hardened Images](../troubleshoot.md)