Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Keep a secret out of the environment

By updated

Improve this page

Logo Docker

A database password passed to a container with docker run -e can then be read in docker inspect, in the environment of the main process and on the host's disk. This lesson teaches you to provide the same secret as a read-only mounted file, to check that it has disappeared from the container's configuration and environment, to use the _FILE convention of official images and a Compose secret of type file, and then to name what this mount still does not protect. The measurements described come from a Debian 13 host with Docker Engine 29.9.2 and Compose 5.6.1.

A secret is here any value whose reading grants power: a password, an API key, a token. An environment variable is a name and value pair that Docker places in the environment of the container's main process (PID 1). The Docker daemon is the service that creates containers and keeps their configuration, and docker inspect is the command that displays that complete configuration.

What you will learn

  • You show where a secret passed with -e stays readable: docker inspect, /proc/1/environ and the host's disk.
  • You provide the same secret as a read-only mounted file, and you prove that it no longer appears in the container's configuration or environment.
  • You use the _FILE convention of an official image so that the application reads the file itself.
  • You declare a Compose secret of type file and you say what it really creates in the container.
  • You diagnose an unreadable secret (permissions, missing source) and you name the readers this method does not stop.

Prerequisites

The examples use fictitious values (ambre-7731-cobalt) and a pinned Alpine image. Every object created carries the sec- prefix and lives in ~/essai-secret, so that the cleanup touches nothing else.

Terminal window
ALP="alpine:3.24.3@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a"
mkdir -p ~/essai-secret && cd ~/essai-secret
printf 'ambre-7731-cobalt' > cle-api.txt
chmod 0400 cle-api.txt

The cle-api.txt file contains only the value, with no trailing newline, and only its owner can read it (0400).

Where does a secret passed with -e stay readable?

A secret passed with -e stays readable in three places: in docker inspect, in the environment of PID 1 and on the host's disk. Start a container with the secret in a variable, then run the three commands below. They bring out the first two places; the disk comes right after.

Terminal window
docker run -d --name sec-env -e CLE_API=ambre-7731-cobalt "$ALP" sleep 600
docker inspect -f '{{json .Config.Env}}' sec-env
docker exec sec-env sh -c 'tr "\0" "\n" < /proc/1/environ | grep CLE_API'
docker exec sec-env env | grep CLE_API

The first command must display the Env list with the line CLE_API=ambre-7731-cobalt in clear text: any account that talks to the daemon reads it without entering the container. The second reads /proc/1/environ, the file where the kernel exposes the environment of process 1; its values are separated by null bytes, hence the tr. The third shows that every process started by docker exec also receives the variable in its own environment.

Keep in mind that /proc/1/environ can be read from any container process running under the same user as PID 1, not only from the application: the kernel grants this read according to the identity of the reading process (see man 5 proc_pid_environ). Another user of the container, even root, gets Permission denied. Docker indeed removes by default the CAP_SYS_PTRACE capability from containers (a capability is a root privilege that Docker grants or removes separately), and it would be needed to read the environment of a process belonging to another user.

The third place is the host's disk: the daemon records the container's configuration, variables included, in /var/lib/docker/containers/<identifier>/config.v2.json. A secret passed with -e is therefore also data written to disk, which any backup of /var/lib/docker takes along with it.

This is not a flaw in Docker. An environment variable is there to configure: it gets displayed, it gets recorded, and docker inspect must be able to return it. A secret needs the opposite: a value that only the application reads, at the moment it needs it.

How do you provide the same secret through a file?

You provide it with a read-only bind mount: the host's file appears in the container, its value enters no variable, and the daemon records only its path. Start a second container with the same secret, this time through the file.

Terminal window
docker run -d --name sec-fic \
--mount type=bind,source="$PWD/cle-api.txt",target=/run/secrets/cle-api,readonly \
"$ALP" sleep 600
docker inspect -f '{{json .Config.Env}}' sec-fic
docker inspect -f '{{json .Mounts}}' sec-fic

The first command must display only PATH: no more CLE_API. The second displays the mount with "Type":"bind", the source on the host, the destination /run/secrets/cle-api and "RW":false. Look at what the daemon kept: a path, never the content of the file. The /run/secrets directory is Docker's convention for these files, but nothing forces you to use it: any destination path works.

Now check the two properties you are after: the secret is not in the environment of PID 1, and the application can read it without being able to modify it.

Terminal window
docker exec sec-fic sh -c 'tr "\0" "\n" < /proc/1/environ | grep -c ambre'
docker exec sec-fic cat /run/secrets/cle-api; echo
docker exec sec-fic sh -c 'echo autre > /run/secrets/cle-api'

The first command must display 0 (no line contains the value, even though grep then returns a non-zero exit code). The second displays the value: the container reads its secret, which is the point. The third fails with Read-only file system: the readonly option forbids rewriting the host's source file, even for an attacker who controls the application.

Why --mount rather than -v?

Because --mount refuses a missing source, whereas -v creates it. With -v ~/essai-secret/absent.txt:/x:ro, Docker creates a directory with that name on the host (as root) and starts the container anyway: the secret does not exist, and nobody tells you. With --mount, the daemon refuses to create the container, with a message that starts with invalid mount config for type "bind": bind source path does not exist, followed by the path, and the return code is 125. A clean failure is better than a container that starts without its secret.

What if the container does not run as root?

The file keeps the permissions it has on the host, and a container user who is not its owner cannot read it. Try with an arbitrary numeric user identifier (uid), here 1234:

Terminal window
docker exec --user 1234 sec-fic cat /run/secrets/cle-api

The command fails with Permission denied: the file is 0400 and belongs to a uid other than 1234. Root, for its part, reads the file without owning it, thanks to the DAC_OVERRIDE capability that Docker grants by default: in a container started with --cap-drop ALL, root is refused in turn. Two fixes are clean. You can give the file to the application's uid (sudo chown 1234 cle-api.txt), or start the container with --user set to the owner's uid. Avoid chmod 0444, which makes the secret readable by every account on the host. The lesson Docker volume permissions: three common causes of an access denied details this case for volumes.

What does the _FILE convention of official images do?

An image that follows the _FILE convention reads the value in the file you point to, instead of reading it in a variable. The official PostgreSQL image, for example, accepts POSTGRES_PASSWORD_FILE in place of POSTGRES_PASSWORD: the variable then contains only a path, and the image's startup script reads the content of the file. Try it with the fictitious password of a throwaway database.

Terminal window
printf 'lagune-5520-quartz' > mdp-base.txt && chmod 0400 mdp-base.txt
PG="postgres:18@sha256:3a4264520e121176619f54ff867d12774bc81e95e7b84db58d63bccdb6144b81"
docker run -d --name sec-pg \
--mount type=bind,source="$PWD/mdp-base.txt",target=/run/secrets/mdp-base,readonly \
-e POSTGRES_PASSWORD_FILE=/run/secrets/mdp-base "$PG"
sleep 8
docker logs sec-pg 2>&1 | tail -1
docker inspect -f '{{json .Config.Env}}' sec-pg

The log must end with database system is ready to accept connections, and Env must show POSTGRES_PASSWORD_FILE=/run/secrets/mdp-base without the value lagune-5520-quartz. On an empty data directory, this image refuses to start without a password, unless you set POSTGRES_HOST_AUTH_METHOD=trust, which this lesson does not use: the successful startup therefore proves that the file was read.

Env, however, only says what the daemon recorded: you still need to know whether the server process carries the value. The startup script of this image exports it while the database is initialized, then runs unset "${!POSTGRES_@}" just before launching PostgreSQL. Check it in the environment of PID 1, read by its own user:

Terminal window
docker exec -u postgres sec-pg sh -c 'tr "\0" "\n" </proc/1/environ | grep -c lagune-5520-quartz'

The command must display 0: the value is absent from the daemon's configuration and from the server's environment. This second property comes from this image's script, not from the convention itself: a script that exports the value without removing it leaves it in /proc/1/environ.

This convention belongs to each image, not to Docker. The official PostgreSQL, MySQL and MariaDB images apply it to their password variables, other images do not know it, and Alpine or nginx read no file on their own. Even for PostgreSQL, the Docker Hub page limits the convention to four variables: POSTGRES_PASSWORD, POSTGRES_USER, POSTGRES_DB and POSTGRES_INITDB_ARGS. To know whether an image follows it, read the variables section of its Docker Hub page: the list of _FILE variables appears there. When the image does not support it, two routes remain: a startup script that reads the file and launches the application, or the application itself configured to read a file.

How do you declare this secret in Compose?

A Compose secret of type file is a read-only bind mount, placed under /run/secrets/<name>: Compose does for you what you have just written with --mount. The root secrets: block says where the value comes from, and the service's secrets: key says who is entitled to it. Save the file below under the name compose.yaml in ~/essai-secret, next to cle-api.txt.

services:
api:
image: alpine:3.24.3@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
command: ["sleep", "600"]
secrets:
- cle-api
secrets:
cle-api:
file: ./cle-api.txt

Once the container is started with docker compose up -d, run docker inspect on its identifier (docker compose ps -q api gives it): you get the same result as with --mount. Env does not carry the secret, and a "Type":"bind" mount with "RW":false leads to /run/secrets/cle-api. A Compose secret of type file is therefore neither encrypted nor stored elsewhere: it is the host's file, with its permissions, seen read-only. The permissions in the container are those of the source, and the Permission denied trap from the previous section applies as is.

The root block also accepts a value read from a host environment variable (environment:), and the long form of a secret granted to a service. The page Inject secrets, and know their limits measures them and details how to replace a secret; this lesson stops at the common mechanism, the mounted file.

What does a mounted file not protect on a single host?

A read-only mounted file removes the secret from the container's environment and configuration, but it does not stop the readers that the container or the host already allow. The table says, for each reader, what changes compared with -e.

ReaderWith -eWith a mounted file
docker inspect (any account in the docker group)reads the valuesees only the path of the file
A container process running as the same user as PID 1, through /proc/1/environreads the valuefinds nothing
A container process that reads the filenot applicablereads the value
An account in the docker group that starts another container with the same mountreads the valuereads the value
Root on the hostreads the valuereads the value
A backup of /var/lib/dockercontains the valuedoes not contain the value

Read the lines that do not change. The file stays in clear text on the host's disk, and an account in the docker group is equivalent to root on that host: it can mount that same file in another container. A mounted secret therefore protects against leaks through the configuration and the environment, but not against a compromised host. Keeping a value encrypted at rest, distributing it to several machines or renewing it automatically calls for a secrets manager or an orchestrator; the page Docker Swarm (in French) presents the secrets of that orchestrator.

One last leak depends on no method: if the application writes its value into its logs, it comes out through docker logs, whether the secret arrived through a file or through a variable.

What about a secret needed at build time?

This lesson deals with the secret at run time. A secret needed to build the image never goes through ARG or ENV, whose values stay readable in the image (docker history --no-trunc). BuildKit's RUN --mount=type=secret mount provides it to a single instruction without writing it into a layer, provided the command neither copies nor prints it: the lesson BuildKit: build secrets and private access measures these two leaks.

How do you diagnose a secret that does not get through?

Start from the symptom you observe, then read what the daemon and the host know. The table gives the five cases met in this lesson, with the check and the fix for each.

SymptomLikely causeCheck and fix
invalid mount config for type "bind": bind source path does not existThe source file does not exist (with --mount)ls -l on the host path, then create the file
A directory named after the secret appears on the host, the application does not find its valueMount with -v of a missing sourcels -ld on the source; delete the directory, create the file, switch to --mount
Permission denied when reading /run/secrets/...The container user does not own a 0400 file, or root has lost DAC_OVERRIDE (--cap-drop ALL)docker exec <c> id -u, then ls -l: adjust the owner or the container user
Read-only file system when writing to the secretreadonly mount (intended behavior)Write elsewhere; never remove readonly to work around it
The secret still appears in docker inspectA -e variable or a Compose environment: carries it toodocker inspect -f '{{json .Config.Env}}'; remove the variable

When none of this matches, check the order again: does the image support the _FILE convention, is the variable's path really the mount's destination, and was the container recreated after the change (a mount cannot be modified on an existing container)?

How do you clean up what the lesson left behind?

Delete only your own objects: the sec-* containers, the Compose project of the previous section and the working directory. Do not run a global cleanup (docker system prune), which would touch the objects of the other users of a shared machine. The Compose project is removed from ~/essai-secret, before the directory is deleted; its container does not carry the sec- prefix.

Terminal window
docker compose down
docker rm -fv sec-env sec-fic sec-pg
cd ~ && rm -rf ~/essai-secret
docker ps -a --format '{{.Names}}' | grep -c '^sec-'

The PostgreSQL container creates an anonymous volume for its data: the -v option of docker rm deletes it along with the container. The last command must display 0. The test file contains only a fictitious value, but this is where the habit is formed: a real secret is deleted from its working directory at the end.

Putting it into practice

In the lab, a disposable random token is kept in a private directory of the host, and a Compose service must be able to read it. This service's command writes only a digest of the token, and only when it succeeds in reading it. You must make the token readable in the container without it appearing in the environment, in the configuration, in the logs, in the image or in a project file.

The validation reads the service's mount (type, private source, read-only), then looks for the token's value in the configuration, the logs, the image and the project files. It then checks that the application did read the secret again, thanks to the digest it writes, and requires that a real write from the container be refused without modifying the source. It checks neither the _FILE convention nor the permissions of a non-root user: these two points are practiced with the lesson, not with the lab.

Key takeaways

  • A secret passed with -e is readable in docker inspect, in /proc/1/environ for the container processes running as the same user as PID 1, and in the daemon's files on the host.
  • A file mounted with --mount type=bind,...,readonly leaves only its path in the configuration: check it with docker inspect -f '{{json .Config.Env}}' then {{json .Mounts}}.
  • Prefer --mount to -v: a missing source makes --mount fail, whereas -v creates a directory in its place.
  • A user who does not own a 0400 file gets Permission denied: adjust the owner or the container user, never 0444.
  • The _FILE convention (POSTGRES_PASSWORD_FILE) is a property of the image, not of Docker: it holds only if the image's page lists it, and it is the image's script that decides whether the value stays in the server's environment.
  • A Compose secret of type file is this same read-only bind mount under /run/secrets/<name>, with the permissions of the source file.
  • On a single host, the file stays in clear text on the disk and readable by root and by the docker group: the mount closes the leaks through the environment, not the compromise of the host.
  • A build secret goes through neither ARG nor ENV: see BuildKit.

Knowledge check

Check that you have grasped the essentials of this lesson. The questions cover the gesture and its reasoning, with cases to predict and to diagnose.

Knowledge check

Check what you have learned with this interactive quiz

8 questions
8 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer