mirror/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-06-19 07:35:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

dhi: refresh troubleshoot & debug (#24658)

Browse Source 
<!--Delete sections as needed -->

## Description

Merged how-to/debug into troubleshoot to reduce left nav sprawl. Kept
troubleshoot at top-level to align with other manuals.

https://deploy-preview-24658--docsdocker.netlify.app/dhi/troubleshoot/

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Editorial review

---------

Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
This commit is contained in:
Craig Osterhout
2026-04-08 08:44:59 -07:00
committed by GitHub
parent 2c74da90db
commit fa88f5d2e8
5 changed files with 129 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/guides/dhi-backstage.md
+2 -2
View File
@@ -430,7 +430,7 @@ docker exec -it <container-id> sh
OCI runtime exec failed: exec failed: unable to start container process: ...
```
Use [Docker Debug](/dhi/how-to/debug/) if you need to troubleshoot a running distroless container.
Use [Docker Debug](/dhi/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container.
> [!NOTE]
>
@@ -480,4 +480,4 @@ Different scanners detect different issues. Running all three gives you the most
- [Use the DHI CLI](/dhi/how-to/cli/) — manage DHI images, mirrors, and customizations from the command line.
- [Migrate to DHI](/dhi/migration/) — for applications that work with standard DHI images without additional packages.
- [Compare images](/dhi/how-to/explore/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images.
- [Docker Debug](/dhi/how-to/debug/) — troubleshoot distroless containers that have no shell.
- [Docker Debug](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell.
content/guides/dhi-openshift.md
+1 -1
View File
@@ -620,6 +620,6 @@ and use `COPY --chown` to transfer results.
- [Use an image in Kubernetes](/dhi/how-to/k8s/) — general DHI Kubernetes deployment guide.
- [Customize an image](/dhi/how-to/customize/) — add packages to DHI images using Enterprise customization.
- [Debug a container](/dhi/how-to/debug/) — troubleshoot distroless containers with Docker Debug (local development).
- [Debug a container](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development).
- [Managing SCCs](https://docs.openshift.com/container-platform/4.14/authentication/managing-security-context-constraints.html) — Red Hat’s reference documentation on Security Context Constraints.
- [Creating images for OpenShift](https://docs.openshift.com/container-platform/4.14/openshift_images/create-images.html) — Red Hat’s guidelines for building OpenShift-compatible container images.
content/manuals/dhi/how-to/_index.md
+2 -15
View File
@@ -1,6 +1,6 @@
---
title: How-tos
description: Step-by-step guidance for working with Docker Hardened Images, from discovery to debugging.
description: Step-by-step guidance for working with Docker Hardened Images, from discovery to governance.
weight: 20
params:
grid_discover:
@@ -63,17 +63,12 @@ params:
description: Learn how to use image policies with Docker Scout for Docker Hardened Images.
icon: policy
link: /dhi/how-to/policies/
grid_troubleshoot:
- title: Debug a Docker Hardened Image
description: Use Docker Debug to inspect a running container based on a hardened image without modifying it.
icon: terminal
link: /dhi/how-to/debug/
---
This section provides practical, task-based guidance for working with Docker
Hardened Images (DHIs). Whether you're evaluating DHIs for the first time or
integrating them into a production CI/CD pipeline, these topics cover the key
tasks across the adoption journey, from discovery to debugging.
tasks across the adoption journey: discover, adopt, verify, and govern.
The topics are organized around the typical lifecycle of working with DHIs, but
you can use them as needed based on your specific workflow.
@@ -111,11 +106,3 @@ Enforce policies to maintain security and compliance.
{{< grid
items="grid_govern"
>}}
## Troubleshoot
Debug containers based on DHIs without modifying the image.
{{< grid
items="grid_troubleshoot"
>}}
content/manuals/dhi/how-to/debug.md
-133
View File
@@ -1,133 +0,0 @@
---
title: Debug a Docker Hardened Image container
linkTitle: Debug a container
weight: 60
keywords: debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container
description: Learn how to use Docker Debug to troubleshoot Docker Hardened Images (DHI) locally or in production.
---
Docker Hardened Images (DHI) prioritize minimalism and security, which means
they intentionally leave out many common debugging tools (like shells or package
managers). This makes direct troubleshooting difficult without introducing risk.
To address this, you can use [Docker
Debug](/reference/cli/docker/debug/), 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.
With Docker Debug, you can also debug containers remotely using the `--host`
option.
## Use Docker Debug
### Step 1: Run a container from a Hardened Image
Start with a DHI-based container that simulates an issue:
```console
$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"
```
This container doesn't include a shell or tools like `ps`, `top`, or `cat`.
If you try:
```console
$ docker exec -it myapp sh
```
You'll see:
```console
exec: "sh": executable file not found in $PATH
```
### 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.
```console
$ docker debug myapp
```
From here, you can inspect running processes, network status, or mounted files.
For example, to check running processes:
```console
$ ps aux
```
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
$ 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
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)
for recommended solutions and workarounds.
content/manuals/dhi/troubleshoot.md
+124 -19
View File
@@ -3,27 +3,132 @@ title: Troubleshoot
description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access.
weight: 40
tags: [Troubleshooting]
keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager
keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager, debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container
aliases:
- /dhi/how-to/debug/
---
The following are common issues you may encounter while migrating to or using
Docker Hardened Images (DHIs), along with recommended solutions.
This page covers debugging techniques and common issues you may encounter while
migrating to or using Docker Hardened Images (DHIs).
## General debugging
Docker Hardened Images are optimized for security and runtime performance. As
such, they typically don't include a shell or standard debugging tools. The
recommended way to troubleshoot containers built on DHIs is by using [Docker
Debug](./how-to/debug.md).
Docker Hardened Images prioritize minimalism and security, which means
they intentionally leave out many common debugging tools (like shells or package
managers). This makes direct troubleshooting difficult without introducing risk.
To address this, you can use [Docker
Debug](/reference/cli/docker/debug/), a secure workflow that
temporarily attaches an ephemeral debug container to a running service or image
without modifying the original image.
Docker Debug allows you to:
This section shows how to debug Docker Hardened Images locally during development.
With Docker Debug, you can also debug containers remotely using the `--host`
option.
- Attach a temporary debug container to your existing container.
- Use a shell and familiar tools such as `curl`, `ps`, `netstat`, and `strace`.
- Install additional tools as needed in a writable, ephemeral layer that
disappears after the session.
### Use Docker Debug
## Permissions
#### Step 1: Run a container from a Hardened Image
Start with a DHI-based container that simulates an issue:
```console
$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"
```
This container doesn't include a shell or tools like `ps`, `top`, or `cat`.
If you try:
```console
$ docker exec -it myapp sh
```
You'll see:
```console
exec: "sh": executable file not found in $PATH
```
#### 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.
```console
$ docker debug myapp
```
From here, you can inspect running processes, network status, or mounted files.
For example, to check running processes:
```console
$ ps aux
```
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
$ 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.
## Common issues
The following are specific issues you may encounter when working with Docker
Hardened Images, along with recommended solutions.
### Permissions
DHIs run as a nonroot user by default for enhanced security. This can result in
permission issues when accessing files or directories. Ensure your application
@@ -34,7 +139,7 @@ To find out which user a DHI runs as, check the repository page for the image on
Docker Hub. See [View image variant
details](./how-to/explore.md#image-variant-details) for more information.
## Privileged ports
### Privileged ports
Nonroot containers cannot bind to ports below 1024 by default. This is enforced
by both the container runtime and the kernel (especially in Kubernetes and
@@ -45,7 +150,7 @@ port (1025 or higher). For example `docker run -p 80:8080 my-image` maps
port 8080 in the container to port 80 on the host, allowing you to access it
without needing root privileges.
## No shell
### No shell
Runtime DHIs omit interactive shells like `sh` or `bash`. If your build or
tooling assumes a shell is present (e.g., for `RUN` instructions), use a `dev`
@@ -56,10 +161,10 @@ To find out which shell, if any, a DHI has, check the repository page for the
image on Docker Hub. See [View image variant
details](./how-to/explore.md#image-variant-details) for more information.
Also, use [Docker Debug](./how-to/debug.md) when you need shell
access to a running container.
Also, use Docker Debug when you need shell access to a running container. For
more details, see [General debugging](#general-debugging).
## Entry point differences
### Entry point differences
DHIs may define different entry points compared to Docker Official Images (DOIs)
or other community images.
@@ -68,7 +173,7 @@ To find out the ENTRYPOINT or CMD for a DHI, check the repository page for the
image on Docker Hub. See [View image variant
details](./how-to/explore.md#image-variant-details) for more information.
## No package manager
### No package manager
Runtime Docker Hardened Images are stripped down for security and minimal attack
surface. As a result, they don't include a package manager such as `apk` or