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
-estays readable:docker inspect,/proc/1/environand 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
_FILEconvention of an official image so that the application reads the file itself. - You declare a Compose secret of type
fileand 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
- Describe an application with Compose: a first stack:
the
compose.yamlfile anddocker compose up, which the Compose section of this lesson reuses. - Docker volumes: keep your data and mount files
for the notion of a bind mount (a file or a directory of the host visible in
the container), and the lesson
Inspect a running container with Docker
for the
-fformat ofdocker inspect. - A Linux host with Docker Engine 29.9.2 and a user who is a member of the
dockergroup. The commands are written for bash.
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.
ALP="alpine:3.24.3@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a"mkdir -p ~/essai-secret && cd ~/essai-secretprintf 'ambre-7731-cobalt' > cle-api.txtchmod 0400 cle-api.txtThe 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.
docker run -d --name sec-env -e CLE_API=ambre-7731-cobalt "$ALP" sleep 600docker inspect -f '{{json .Config.Env}}' sec-envdocker exec sec-env sh -c 'tr "\0" "\n" < /proc/1/environ | grep CLE_API'docker exec sec-env env | grep CLE_APIThe 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.
docker run -d --name sec-fic \ --mount type=bind,source="$PWD/cle-api.txt",target=/run/secrets/cle-api,readonly \ "$ALP" sleep 600docker inspect -f '{{json .Config.Env}}' sec-ficdocker inspect -f '{{json .Mounts}}' sec-ficThe 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.
docker exec sec-fic sh -c 'tr "\0" "\n" < /proc/1/environ | grep -c ambre'docker exec sec-fic cat /run/secrets/cle-api; echodocker 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:
docker exec --user 1234 sec-fic cat /run/secrets/cle-apiThe 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.
printf 'lagune-5520-quartz' > mdp-base.txt && chmod 0400 mdp-base.txtPG="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 8docker logs sec-pg 2>&1 | tail -1docker inspect -f '{{json .Config.Env}}' sec-pgThe 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:
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.txtOnce 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.
| Reader | With -e | With a mounted file |
|---|---|---|
docker inspect (any account in the docker group) | reads the value | sees only the path of the file |
A container process running as the same user as PID 1, through /proc/1/environ | reads the value | finds nothing |
| A container process that reads the file | not applicable | reads the value |
An account in the docker group that starts another container with the same mount | reads the value | reads the value |
| Root on the host | reads the value | reads the value |
A backup of /var/lib/docker | contains the value | does 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.
| Symptom | Likely cause | Check and fix |
|---|---|---|
invalid mount config for type "bind": bind source path does not exist | The 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 value | Mount with -v of a missing source | ls -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 secret | readonly mount (intended behavior) | Write elsewhere; never remove readonly to work around it |
The secret still appears in docker inspect | A -e variable or a Compose environment: carries it too | docker 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.
docker compose downdocker rm -fv sec-env sec-fic sec-pgcd ~ && rm -rf ~/essai-secretdocker 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
-eis readable indocker inspect, in/proc/1/environfor 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,...,readonlyleaves only its path in the configuration: check it withdocker inspect -f '{{json .Config.Env}}'then{{json .Mounts}}. - Prefer
--mountto-v: a missing source makes--mountfail, whereas-vcreates a directory in its place. - A user who does not own a
0400file getsPermission denied: adjust the owner or the container user, never0444. - The
_FILEconvention (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
fileis 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
dockergroup: the mount closes the leaks through the environment, not the compromise of the host. - A build secret goes through neither
ARGnorENV: 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
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
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Find orphan Docker volumes without deleting everything
A new full quiz with random questions
Work again only on the questions you missed