From 2f48f41fcb4248dd884c4ee2734f132b5bba23fb Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Oct 2023 11:27:56 +0200 Subject: [PATCH 01/24] docs: improve introduction to docker run Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 77 ++++++++++++++----------------------------- 1 file changed, 24 insertions(+), 53 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index e1687d0aa837..e182fea12e97 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1,54 +1,44 @@ --- -description: "Configure containers at runtime" -keywords: "docker, run, configure, runtime" +description: "Running and configuring containers with the Docker CLI" +keywords: "docker, run, cli" aliases: - /reference/run/ +title: Running containers --- - - -# Docker run reference - Docker runs processes in isolated containers. A container is a process -which runs on a host. The host may be local or remote. When an operator -executes `docker run`, the container process that runs is isolated in +which runs on a host. The host may be local or remote. When an you +execute `docker run`, the container process that runs is isolated in that it has its own file system, its own networking, and its own isolated process tree separate from the host. -This page details how to use the `docker run` command to define the -container's resources at runtime. +This page details how to use the `docker run` command to run containers. ## General form -The basic `docker run` command takes this form: +A `docker run` command takes the following form: - $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] +```console +$ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] +``` -The `docker run` command must specify an [*IMAGE*](https://docs.docker.com/glossary/#image) -to derive the container from. An image developer can define image -defaults related to: +The `docker run` command must specify an [image](https://docs.docker.com/glossary/#image) +to create the container from. - * detached or foreground running - * container identification - * network settings - * runtime constraints on CPU and memory +`[OPTIONS]` let you configure options for the container. For example, you can +give the container a name (`--name`), or run it as a background process (`-d`). +You can also set options to control things like resource constraints and +networking. -With the `docker run [OPTIONS]` an operator can add to or override the -image defaults set by a developer. And, additionally, operators can -override nearly all the defaults set by the Docker runtime itself. The -operator's ability to override image and Docker runtime defaults is why -[*run*](commandline/run.md) has more options than any -other `docker` command. +You can use the `[COMMAND]` and `[ARG...]` positional arguments to specify +commands and arguments for the container to run when it starts up. For example, +you can specify `sh` as the `[COMMAND]`, combined with the `-i` and `-t` flags, +to start an interactive shell in the container (if the image you select has an +`sh` executable on `PATH`). -To learn how to interpret the types of `[OPTIONS]`, see -[*Option types*](commandline/cli.md#option-types). +```console +$ docker run -it IMAGE sh +``` > **Note** > @@ -59,25 +49,6 @@ To learn how to interpret the types of `[OPTIONS]`, see > it. For more information about this configuration, refer to the Docker > installation documentation for your operating system. - -## Operator exclusive options - -Only the operator (the person executing `docker run`) can set the -following options. - - - [Detached vs foreground](#detached-vs-foreground) - - [Detached (-d)](#detached--d) - - [Foreground](#foreground) - - [Container identification](#container-identification) - - [Name (--name)](#name---name) - - [PID equivalent](#pid-equivalent) - - [IPC settings (--ipc)](#ipc-settings---ipc) - - [Network settings](#network-settings) - - [Restart policies (--restart)](#restart-policies---restart) - - [Clean up (--rm)](#clean-up---rm) - - [Runtime constraints on resources](#runtime-constraints-on-resources) - - [Runtime privilege and Linux capabilities](#runtime-privilege-and-linux-capabilities) - ## Detached vs foreground When starting a Docker container, you must first decide if you want to From fad227d3fd756020e3af4a95dc6a08b528d21f36 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Oct 2023 16:38:17 +0200 Subject: [PATCH 02/24] docs: move info about fg/bg flags to run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 362 +++++++++++++++++++----------- docs/reference/run.md | 97 +++----- 2 files changed, 269 insertions(+), 190 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 9bb96ad45f50..0585294f4d41 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -9,111 +9,111 @@ Create and run a new container from an image ### Options -| Name | Type | Default | Description | -|:----------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host:ip) | -| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) | -| [`-a`](#attach), [`--attach`](#attach) | `list` | | Attach to STDIN, STDOUT or STDERR | -| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | -| `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | -| `--cap-add` | `list` | | Add Linux capabilities | -| `--cap-drop` | `list` | | Drop Linux capabilities | -| `--cgroup-parent` | `string` | | Optional parent cgroup for the container | -| `--cgroupns` | `string` | | Cgroup namespace to use (host\|private)
'host': Run the container in the Docker host's cgroup namespace
'private': Run the container in its own private cgroup namespace
'': Use the cgroup namespace as configured by the
default-cgroupns-mode option on the daemon (default) | -| [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file | -| `--cpu-count` | `int64` | `0` | CPU count (Windows only) | -| `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | -| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | -| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | -| `--cpu-rt-period` | `int64` | `0` | Limit CPU real-time period in microseconds | -| `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | -| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | -| `--cpus` | `decimal` | | Number of CPUs | -| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | -| `-d`, `--detach` | | | Run container in background and print container ID | -| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | -| [`--device`](#device) | `list` | | Add a host device to the container | -| [`--device-cgroup-rule`](#device-cgroup-rule) | `list` | | Add a rule to the cgroup allowed devices list | -| `--device-read-bps` | `list` | | Limit read rate (bytes per second) from a device | -| `--device-read-iops` | `list` | | Limit read rate (IO per second) from a device | -| `--device-write-bps` | `list` | | Limit write rate (bytes per second) to a device | -| `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | -| `--disable-content-trust` | | | Skip image verification | -| `--dns` | `list` | | Set custom DNS servers | -| `--dns-option` | `list` | | Set DNS options | -| `--dns-search` | `list` | | Set custom DNS search domains | -| `--domainname` | `string` | | Container NIS domain name | -| `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | -| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | -| `--env-file` | `list` | | Read in a file of environment variables | -| `--expose` | `list` | | Expose a port or a range of ports | -| [`--gpus`](#gpus) | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) | -| `--group-add` | `list` | | Add additional groups to join | -| `--health-cmd` | `string` | | Command to run to check health | -| `--health-interval` | `duration` | `0s` | Time between running the check (ms\|s\|m\|h) (default 0s) | -| `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | -| `--health-start-interval` | `duration` | `0s` | Time between running the check during the start period (ms\|s\|m\|h) (default 0s) | -| `--health-start-period` | `duration` | `0s` | Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s) | -| `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | -| `--help` | | | Print usage | -| `-h`, `--hostname` | `string` | | Container host name | -| `--init` | | | Run an init inside the container that forwards signals and reaps processes | -| `-i`, `--interactive` | | | Keep STDIN open even if not attached | -| `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | -| `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | -| `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | -| `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | -| `--ipc` | `string` | | IPC mode to use | -| [`--isolation`](#isolation) | `string` | | Container isolation technology | -| `--kernel-memory` | `bytes` | `0` | Kernel memory limit | -| [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container | -| `--label-file` | `list` | | Read in a line delimited file of labels | -| `--link` | `list` | | Add link to another container | -| `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | -| `--log-driver` | `string` | | Logging driver for the container | -| `--log-opt` | `list` | | Log driver options | -| `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | -| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | -| `--memory-reservation` | `bytes` | `0` | Memory soft limit | -| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: '-1' to enable unlimited swap | -| `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) | -| [`--mount`](#mount) | `mount` | | Attach a filesystem mount to the container | -| [`--name`](#name) | `string` | | Assign a name to the container | -| [`--network`](#network) | `network` | | Connect a container to a network | -| `--network-alias` | `list` | | Add network-scoped alias for the container | -| `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | -| `--oom-kill-disable` | | | Disable OOM Killer | -| `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | -| `--pid` | `string` | | PID namespace to use | -| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | -| `--platform` | `string` | | Set platform if server is multi-platform capable | -| [`--privileged`](#privileged) | | | Give extended privileges to this container | -| [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host | -| `-P`, `--publish-all` | | | Publish all exposed ports to random ports | -| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | -| `-q`, `--quiet` | | | Suppress the pull output | -| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only | -| [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits | -| `--rm` | | | Automatically remove the container when it exits | -| `--runtime` | `string` | | Runtime to use for this container | -| [`--security-opt`](#security-opt) | `list` | | Security Options | -| `--shm-size` | `bytes` | `0` | Size of /dev/shm | -| `--sig-proxy` | | | Proxy received signals to the process | -| [`--stop-signal`](#stop-signal) | `string` | | Signal to stop the container | -| [`--stop-timeout`](#stop-timeout) | `int` | `0` | Timeout (in seconds) to stop a container | -| [`--storage-opt`](#storage-opt) | `list` | | Storage driver options for the container | -| [`--sysctl`](#sysctl) | `map` | `map[]` | Sysctl options | -| [`--tmpfs`](#tmpfs) | `list` | | Mount a tmpfs directory | -| `-t`, `--tty` | | | Allocate a pseudo-TTY | -| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | -| `-u`, `--user` | `string` | | Username or UID (format: [:]) | -| `--userns` | `string` | | User namespace to use | -| `--uts` | `string` | | UTS namespace to use | -| [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume | -| `--volume-driver` | `string` | | Optional volume driver for the container | -| [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) | -| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | +| Name | Type | Default | Description | +|:------------------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host:ip) | +| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) | +| [`-a`](#attach), [`--attach`](#attach) | `list` | | Attach to STDIN, STDOUT or STDERR | +| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | +| `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | +| `--cap-add` | `list` | | Add Linux capabilities | +| `--cap-drop` | `list` | | Drop Linux capabilities | +| `--cgroup-parent` | `string` | | Optional parent cgroup for the container | +| `--cgroupns` | `string` | | Cgroup namespace to use (host\|private)
'host': Run the container in the Docker host's cgroup namespace
'private': Run the container in its own private cgroup namespace
'': Use the cgroup namespace as configured by the
default-cgroupns-mode option on the daemon (default) | +| [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file | +| `--cpu-count` | `int64` | `0` | CPU count (Windows only) | +| `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | +| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | +| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | +| `--cpu-rt-period` | `int64` | `0` | Limit CPU real-time period in microseconds | +| `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | +| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | +| `--cpus` | `decimal` | | Number of CPUs | +| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | +| [`-d`](#detach), [`--detach`](#detach) | | | Run container in background and print container ID | +| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | +| [`--device`](#device) | `list` | | Add a host device to the container | +| [`--device-cgroup-rule`](#device-cgroup-rule) | `list` | | Add a rule to the cgroup allowed devices list | +| `--device-read-bps` | `list` | | Limit read rate (bytes per second) from a device | +| `--device-read-iops` | `list` | | Limit read rate (IO per second) from a device | +| `--device-write-bps` | `list` | | Limit write rate (bytes per second) to a device | +| `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | +| `--disable-content-trust` | | | Skip image verification | +| `--dns` | `list` | | Set custom DNS servers | +| `--dns-option` | `list` | | Set DNS options | +| `--dns-search` | `list` | | Set custom DNS search domains | +| `--domainname` | `string` | | Container NIS domain name | +| `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | +| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | +| `--env-file` | `list` | | Read in a file of environment variables | +| `--expose` | `list` | | Expose a port or a range of ports | +| [`--gpus`](#gpus) | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) | +| `--group-add` | `list` | | Add additional groups to join | +| `--health-cmd` | `string` | | Command to run to check health | +| `--health-interval` | `duration` | `0s` | Time between running the check (ms\|s\|m\|h) (default 0s) | +| `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | +| `--health-start-interval` | `duration` | `0s` | Time between running the check during the start period (ms\|s\|m\|h) (default 0s) | +| `--health-start-period` | `duration` | `0s` | Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s) | +| `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | +| `--help` | | | Print usage | +| `-h`, `--hostname` | `string` | | Container host name | +| `--init` | | | Run an init inside the container that forwards signals and reaps processes | +| [`-i`](#interactive), [`--interactive`](#interactive) | | | Keep STDIN open even if not attached | +| `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | +| `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | +| `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | +| `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | +| `--ipc` | `string` | | IPC mode to use | +| [`--isolation`](#isolation) | `string` | | Container isolation technology | +| `--kernel-memory` | `bytes` | `0` | Kernel memory limit | +| [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container | +| `--label-file` | `list` | | Read in a line delimited file of labels | +| `--link` | `list` | | Add link to another container | +| `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | +| `--log-driver` | `string` | | Logging driver for the container | +| `--log-opt` | `list` | | Log driver options | +| `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | +| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | +| `--memory-reservation` | `bytes` | `0` | Memory soft limit | +| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: '-1' to enable unlimited swap | +| `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) | +| [`--mount`](#mount) | `mount` | | Attach a filesystem mount to the container | +| [`--name`](#name) | `string` | | Assign a name to the container | +| [`--network`](#network) | `network` | | Connect a container to a network | +| `--network-alias` | `list` | | Add network-scoped alias for the container | +| `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | +| `--oom-kill-disable` | | | Disable OOM Killer | +| `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | +| `--pid` | `string` | | PID namespace to use | +| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | +| `--platform` | `string` | | Set platform if server is multi-platform capable | +| [`--privileged`](#privileged) | | | Give extended privileges to this container | +| [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host | +| `-P`, `--publish-all` | | | Publish all exposed ports to random ports | +| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | +| `-q`, `--quiet` | | | Suppress the pull output | +| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only | +| [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits | +| `--rm` | | | Automatically remove the container when it exits | +| `--runtime` | `string` | | Runtime to use for this container | +| [`--security-opt`](#security-opt) | `list` | | Security Options | +| `--shm-size` | `bytes` | `0` | Size of /dev/shm | +| `--sig-proxy` | | | Proxy received signals to the process | +| [`--stop-signal`](#stop-signal) | `string` | | Signal to stop the container | +| [`--stop-timeout`](#stop-timeout) | `int` | `0` | Timeout (in seconds) to stop a container | +| [`--storage-opt`](#storage-opt) | `list` | | Storage driver options for the container | +| [`--sysctl`](#sysctl) | `map` | `map[]` | Sysctl options | +| [`--tmpfs`](#tmpfs) | `list` | | Mount a tmpfs directory | +| [`-t`](#tty), [`--tty`](#tty) | | | Allocate a pseudo-TTY | +| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | +| `-u`, `--user` | `string` | | Username or UID (format: [:]) | +| `--userns` | `string` | | User namespace to use | +| `--uts` | `string` | | UTS namespace to use | +| [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume | +| `--volume-driver` | `string` | | Optional volume driver for the container | +| [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) | +| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | @@ -541,38 +541,34 @@ content label. Shared volume labels allow all containers to read/write content. The `Z` option tells Docker to label the content with a private unshared label. Only the current container can use a private volume. -### Attach to STDIN/STDOUT/STDERR (-a, --attach) - -The `--attach` (or `-a`) flag tells `docker run` to bind to the container's -`STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output -and input as needed. +### Detached mode (-d, --detach) -```console -$ echo "test" | docker run -i -a stdin ubuntu cat - -``` +The `--detach` (or `-d`) flag starts a container as a background process that +doesn't occupy your terminal window. By design, containers started in detached +mode exit when the root process used to run the container exits, unless you +also specify the `--rm` option. If you use `-d` with `--rm`, the container is +removed when it exits or when the daemon exits, whichever happens first. -This pipes data into a container and prints the container's ID by attaching -only to the container's `STDIN`. +Don't pass a `service x start` command to a detached container. For example, +this command attempts to start the `nginx` service. ```console -$ docker run -a stderr ubuntu echo test +$ docker run -d -p 80:80 my_image service nginx start ``` -This isn't going to print anything to the console unless there's an error because output -is only attached to the `STDERR` of the container. The container's logs -still store what's written to `STDERR` and `STDOUT`. +This succeeds in starting the `nginx` service inside the container. However, it +fails the detached container paradigm in that, the root process (`service nginx +start`) returns and the detached container stops as designed. As a result, the +`nginx` service starts but can't be used. Instead, to start a process such as +the `nginx` web server do the following: ```console -$ cat somefile | docker run -i -a stdin mybuilder dobuild +$ docker run -d -p 80:80 my_image nginx -g 'daemon off;' ``` -This example shows a way of using `--attach` to pipe a file into a container. -The command prints the container's ID after the build completes and you can retrieve -the build logs using `docker logs`. This is -useful if you need to pipe a file or something else into a container and -retrieve the container's ID once the container has finished running. - -See also [the `docker cp` command](cp.md). +To do input/output with a detached container use network connections or shared +volumes. These are required because the container is no longer listening to the +command line where `docker run` was run. ### Override the detach sequence (--detach-keys) @@ -667,6 +663,118 @@ PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.micro > The `--device` option is only supported on process-isolated Windows containers, > and produces an error if the container isolation is `hyperv`. +### Attach to STDIN/STDOUT/STDERR (-a, --attach) + +The `--attach` (or `-a`) flag tells `docker run` to bind to the container's +`STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output +and input as needed. You can specify to which of the three standard streams +(`STDIN`, `STDOUT`, `STDERR`) you'd like to connect instead, as in: + +```console +$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash +``` + +The following example pipes data into a container and prints the container's ID +by attaching only to the container's `STDIN`. + +```console +$ echo "test" | docker run -i -a stdin ubuntu cat - +``` + +The following example doesn't print anything to the console unless there's an +error because output is only attached to the `STDERR` of the container. The +container's logs still store what's written to `STDERR` and `STDOUT`. + +```console +$ docker run -a stderr ubuntu echo test +``` + +The following example shows a way of using `--attach` to pipe a file into a +container. The command prints the container's ID after the build completes and +you can retrieve the build logs using `docker logs`. This is useful if you need +to pipe a file or something else into a container and retrieve the container's +ID once the container has finished running. + +```console +$ cat somefile | docker run -i -a stdin mybuilder dobuild +``` + +> **Note** +> +> A process running as PID 1 inside a container is treated specially by Linux: +> it ignores any signal with the default action. As a result, the process will +> not terminate on `SIGINT` or `SIGTERM` unless it is coded to do so. + +See also [the `docker cp` command](cp.md). + +### Keep STDIN open (-i, --interactive) + +The `--interactive` (or `-i`) flag keeps the container's `STDIN` open, and lets +you send input to the container through standard input. + +```console +$ echo hello | docker run --rm -i busybox cat +hello +``` + +The `-i` flag is most often used together with the `--tty` flag to bind the I/O +streams of the container to a pseudo terminal, creating an interactive terminal +session for the container. See [Allocate a pseudo-TTY](#tty) for more examples. + +```console +$ docker run -it debian +root@10a3e71492b0:/# factor 90 +90: 2 3 3 5 +root@10a3e71492b0:/# exit +exit +``` + +Using the `-i` flag on its own allows for composition, such as piping input to +containers: + +```console +$ docker run --rm -i busybox echo "foo bar baz" \ + | docker run --rm -i busybox awk '{ print $2 }' \ + | docker run --rm -i busybox rev +rab +``` + +### Allocate a pseudo-TTY (-t, --tty) + +The `--tty` (or `-t`) flag attaches a pseudo-TTY to the container, connecting +your terminal to the I/O streams of the container. Allocating a pseudo-TTY to +the container means that you get access to input and output feature that TTY +devices provide. + +For example, the following command runs the `passwd` command in a `debian` +container, to set a new password for the `root` user. + +```console +$ docker run -i debian passwd root +New password: karjalanpiirakka9 +Retype new password: karjalanpiirakka9 +passwd: password updated successfully +``` + +If you run this command with only the `-i` flag (which lets you send text to +`STDIN` of the container), the `passwd` prompt displays the password in plain +text. However, if you try the same thing but also adding the `-t` flag, the +password is hidden: + +```console +$ docker run -i debian passwd root +New password: +Retype new password: +passwd: password updated successfully +``` + +This is because `passwd` can suppress the output of characters to the terminal +using the echo-off TTY feature. + +You can use the `-t` flag without `-i` flag. This still allocates a pseudo-TTY +to the container, but with no way of writing to `STDIN`. The only time this +might be useful is if the output of the container requires a TTY environment. + ### Using dynamically created devices (--device-cgroup-rule) Docker assigns devices available to a container at creation time. The diff --git a/docs/reference/run.md b/docs/reference/run.md index e182fea12e97..db298c86c34a 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -49,78 +49,49 @@ $ docker run -it IMAGE sh > it. For more information about this configuration, refer to the Docker > installation documentation for your operating system. -## Detached vs foreground +## Foreground and background -When starting a Docker container, you must first decide if you want to -run the container in the background in a "detached" mode or in the -default foreground mode: - - -d=false: Detached mode: Run container in the background, print new container id - -### Detached (-d) - -To start a container in detached mode, you use `-d=true` or just `-d` option. By -design, containers started in detached mode exit when the root process used to -run the container exits, unless you also specify the `--rm` option. If you use -`-d` with `--rm`, the container is removed when it exits **or** when the daemon -exits, whichever happens first. - -Do not pass a `service x start` command to a detached container. For example, this -command attempts to start the `nginx` service. - - $ docker run -d -p 80:80 my_image service nginx start - -This succeeds in starting the `nginx` service inside the container. However, it -fails the detached container paradigm in that, the root process (`service nginx -start`) returns and the detached container stops as designed. As a result, the -`nginx` service is started but could not be used. Instead, to start a process -such as the `nginx` web server do the following: - - $ docker run -d -p 80:80 my_image nginx -g 'daemon off;' - -To do input/output with a detached container use network connections or shared -volumes. These are required because the container is no longer listening to the -command line where `docker run` was run. - -To reattach to a detached container, use `docker` -[*attach*](commandline/attach.md) command. - -### Foreground - -In foreground mode (the default when `-d` is not specified), `docker -run` can start the process in the container and attach the console to -the process's standard input, output, and standard error. It can even -pretend to be a TTY (this is what most command line executables expect) -and pass along signals. All of that is configurable: - - -a=[] : Attach to `STDIN`, `STDOUT` and/or `STDERR` - -t : Allocate a pseudo-tty - --sig-proxy=true: Proxy all received signals to the process (non-TTY mode only) - -i : Keep STDIN open even if not attached - -If you do not specify `-a` then Docker will [attach to both stdout and stderr -]( https://github.com/docker/docker/blob/4118e0c9eebda2412a09ae66e90c34b85fae3275/runconfig/opts/parse.go#L267). -You can specify to which of the three standard streams (`STDIN`, `STDOUT`, -`STDERR`) you'd like to connect instead, as in: +When you start a container, the container runs in the foreground by default. +If you want to run the container in the background instead, you can use the +`--detach` (or `-d`) flag. This starts the container without occupying your +terminal window. ```console -$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash +$ docker run -d ``` -For interactive processes (like a shell), you must use `-i -t` together in -order to allocate a tty for the container process. `-i -t` is often written `-it` -as you'll see in later examples. Specifying `-t` is forbidden when the client -is receiving its standard input from a pipe, as in: +While the container runs in the background, you can interact with the container +using other CLI commands. For example, `docker logs` lets you view the logs for +the container, and `docker attach` brings it to the foreground. ```console -$ echo test | docker run -i busybox cat +$ docker run -d nginx +0246aa4d1448a401cabd2ce8f242192b6e7af721527e48a810463366c7ff54f1 +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +0246aa4d1448 nginx "/docker-entrypoint.…" 2 seconds ago Up 1 second 80/tcp pedantic_liskov +$ docker logs -n 5 0246aa4d1448 +2023/11/06 15:58:23 [notice] 1#1: start worker process 33 +2023/11/06 15:58:23 [notice] 1#1: start worker process 34 +2023/11/06 15:58:23 [notice] 1#1: start worker process 35 +2023/11/06 15:58:23 [notice] 1#1: start worker process 36 +2023/11/06 15:58:23 [notice] 1#1: start worker process 37 +$ docker attach 0246aa4d1448 +^C +2023/11/06 15:58:40 [notice] 1#1: signal 2 (SIGINT) received, exiting +... ``` -> **Note** -> -> A process running as PID 1 inside a container is treated specially by Linux: -> it ignores any signal with the default action. As a result, the process will -> not terminate on `SIGINT` or `SIGTERM` unless it is coded to do so. +For more information about `docker run` flags related to foreground and +background modes, see: + +- [`docker run --detach`](commandline/run.md#detach): run container in background +- [`docker run --attach`](commandline/run.md#attach): attach to `stdin`, `stdout`, and `stderr` +- [`docker run --tty`](commandline/run.md#tty): allocate a pseudo-tty +- [`docker run --interactive`](commandline/run.md#interactive): keep `stdin` open even if not attached + +For more information about re-attaching to a background container, see +[`docker attach`](commandline/attach.md). ## Container identification From 03dc8832ed04c339a6483ea8abe1a486eab23fd3 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 8 Nov 2023 17:13:44 +0100 Subject: [PATCH 03/24] docs: improve docs on container identification Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 57 ++++++++++++++----- docs/reference/run.md | 93 ++++++++++++++++++------------- 2 files changed, 98 insertions(+), 52 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 0585294f4d41..5a374afa8d72 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -128,27 +128,58 @@ Use `docker ps -a` to view a list of all containers, including those that are st ## Examples -### Assign name and allocate pseudo-TTY (--name, -it) +### Assign name (--name) + +The `--name` flag lets you specify a custom identifier for a container. The +following example runs a container named `test` using the `nginx:alpine` image +in [detached mode](#detach). ```console -$ docker run --name test -it debian +$ docker run --name test -d nginx:alpine +4bed76d3ad428b889c56c1ecc2bf2ed95cb08256db22dc5ef5863e1d03252a19 +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +4bed76d3ad42 nginx:alpine "/docker-entrypoint.…" 1 second ago Up Less than a second 80/tcp test +``` + +You can reference the container by name with other commands. For example, the +following commands stop and remove a container named `test`: -root@d6c0fe130dba:/# exit 13 -$ echo $? -13 -$ docker ps -a | grep test -d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test +```console +$ docker stop test +test +$ docker rm test +test ``` -This example runs a container named `test` using the `debian:latest` -image. The `-it` instructs Docker to allocate a pseudo-TTY connected to -the container's stdin; creating an interactive `bash` shell in the container. -The example quits the `bash` shell by entering -`exit 13`, passing the exit code on to the caller of -`docker run`, and recording it in the `test` container's metadata. +If you don't specify a custom name using the `--name` flag, the daemon assigns +a randomly generated name, such as `vibrant_cannon`, to the container. Using a +custom-defined name provides the benefit of having an easy-to-remember ID for a +container. + +Moreover, if you connect the container to a user-defined bridge network, other +containers on the same network can refer to the container by name via DNS. + +```console +$ docker network create mynet +cb79f45948d87e389e12013fa4d969689ed2c3316985dd832a43aaec9a0fe394 +$ docker run --name test --net mynet -d nginx:alpine +58df6ecfbc2ad7c42d088ed028d367f9e22a5f834d7c74c66c0ab0485626c32a +$ docker run --net mynet busybox:latest ping test +PING test (172.18.0.2): 56 data bytes +64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.073 ms +64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.411 ms +64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.319 ms +64 bytes from 172.18.0.2: seq=3 ttl=64 time=0.383 ms +... +``` ### Capture container ID (--cidfile) +To help with automation, you can have Docker write the container ID out to a +file of your choosing. This is similar to how some programs might write out +their process ID to a file (you might've seen them as PID files): + ```console $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" ``` diff --git a/docs/reference/run.md b/docs/reference/run.md index db298c86c34a..4f43d7eba7e0 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -22,14 +22,43 @@ A `docker run` command takes the following form: $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] ``` -The `docker run` command must specify an [image](https://docs.docker.com/glossary/#image) +The `docker run` command must specify an [image reference](#image-references) to create the container from. +### Image references + +The image reference is the name and version of the image. You can use the image +reference to create or run a container based on an image. + +- `docker run IMAGE[:TAG][@DIGEST]` +- `docker create IMAGE[:TAG][@DIGEST]` + +An image tag is the image version, which defaults to `latest` when omitted. Use +the tag to run a container from specific version of an image. For example, to +run version `23.10` of the `ubuntu` image: `docker run ubuntu:23.10`. + +#### Image digests + +Images using the v2 or later image format have a content-addressable identifier +called a digest. As long as the input used to generate the image is unchanged, +the digest value is predictable. + +The following example runs a container from the `alpine` image with the +`sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest: + +```console +$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date +``` + +### Options + `[OPTIONS]` let you configure options for the container. For example, you can give the container a name (`--name`), or run it as a background process (`-d`). You can also set options to control things like resource constraints and networking. +### Commands and arguments + You can use the `[COMMAND]` and `[ARG...]` positional arguments to specify commands and arguments for the container to run when it starts up. For example, you can specify `sh` as the `[COMMAND]`, combined with the `-i` and `-t` flags, @@ -95,55 +124,41 @@ For more information about re-attaching to a background container, see ## Container identification -### Name (--name) - -The operator can identify a container in three ways: +You can identify a container in three ways: | Identifier type | Example value | |:----------------------|:-------------------------------------------------------------------| -| UUID long identifier | "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" | -| UUID short identifier | "f78375b1c487" | -| Name | "evil_ptolemy" | - -The UUID identifiers come from the Docker daemon. If you do not assign a -container name with the `--name` option, then the daemon generates a random -string name for you. Defining a `name` can be a handy way to add meaning to a -container. If you specify a `name`, you can use it when referencing the -container within a Docker network. This works for both background and foreground -Docker containers. - -> **Note** -> -> Containers on the default bridge network must be linked to communicate by name. - -### PID equivalent - -Finally, to help with automation, you can have Docker write the -container ID out to a file of your choosing. This is similar to how some -programs might write out their process ID to a file (you've seen them as -PID files): +| UUID long identifier | `f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778` | +| UUID short identifier | `f78375b1c487` | +| Name | `evil_ptolemy` | - --cidfile="": Write the container ID to the file +The UUID identifier is a random ID assigned to the container by the daemon. -### Image[:tag] +The daemon generates a random string name for containers automatically. You can +also defined a custom name using [the `--name` flag](./commandline/run.md#name). +Defining a `name` can be a handy way to add meaning to a container. If you +specify a `name`, you can use it when referring to the container in a +user-defined network. This works for both background and foreground Docker +containers. -While not strictly a means of identifying a container, you can specify a version of an -image you'd like to run the container with by adding `image[:tag]` to the command. For -example, `docker run ubuntu:22.04`. +A container identifier is not the same thing as an image reference. The image +reference specifies which image to use when you run a container. You can't run +`docker exec nginx:alpine sh` to open a shell in a container based on the +`nginx:alpine` image, because `docker exec` expects a container identifier +(name or ID), not an image. -### Image[@digest] - -Images using the v2 or later image format have a content-addressable identifier -called a digest. As long as the input used to generate the image is unchanged, -the digest value is predictable and referenceable. - -The following example runs a container from the `alpine` image with the -`sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest: +While the image used by a container is not an identifier for the container, you +find out the IDs of containers using an image by using the `--filter` flag. For +example, the following `docker ps` command gets the IDs of all running +containers based on the `nginx:alpine` image: ```console -$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date +$ docker ps -q --filter ancestor=nginx:alpine ``` +For more information about using filters, see +[Filtering](https://docs.docker.com/config/filter/). + ## PID settings (--pid) --pid="" : Set the PID (Process) Namespace mode for the container, From d66fe788103ccbbd9776645a88298c2aba6b935a Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 22 Nov 2023 09:26:17 +0100 Subject: [PATCH 04/24] docs: move --pid to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 85 ++++++++++++++++++++++++++++++- docs/reference/run.md | 57 --------------------- 2 files changed, 84 insertions(+), 58 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 5a374afa8d72..2688d3b59b32 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -85,7 +85,7 @@ Create and run a new container from an image | `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | | `--oom-kill-disable` | | | Disable OOM Killer | | `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | -| `--pid` | `string` | | PID namespace to use | +| [`--pid`](#pid) | `string` | | PID namespace to use | | `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | | `--platform` | `string` | | Set platform if server is multi-platform capable | | [`--privileged`](#privileged) | | | Give extended privileges to this container | @@ -189,6 +189,89 @@ flag makes Docker attempt to create a new file and write the container ID to it. If the file exists already, Docker returns an error. Docker closes this file when `docker run` exits. +### PID settings (--pid) + +```text +--pid="" : Set the PID (Process) Namespace mode for the container, + 'container:': joins another container's PID namespace + 'host': use the host's PID namespace inside the container +``` + +By default, all containers have the PID namespace enabled. + +PID namespace provides separation of processes. The PID Namespace removes the +view of the system processes, and allows process ids to be reused including +PID 1. + +In certain cases you want your container to share the host's process namespace, +allowing processes within the container to see all of the processes on the +system. For example, you could build a container with debugging tools like +`strace` or `gdb`, but want to use these tools when debugging processes within +the container. + +#### Example: run htop inside a container + +To run `htop` in a container that shares the process namespac of the host: + +1. Run an alpine container with the `--pid=host` option: + + ```console + $ docker run --rm -it --pid=host alpine + ``` + +2. Install `htop` in the container: + + ```console + / # apk add htop + fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/main/aarch64/APKINDEX.tar.gz + fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/community/aarch64/APKINDEX.tar.gz + (1/3) Installing ncurses-terminfo-base (6.4_p20230506-r0) + (2/3) Installing libncursesw (6.4_p20230506-r0) + (3/3) Installing htop (3.2.2-r1) + Executing busybox-1.36.1-r2.trigger + OK: 9 MiB in 18 packages + ``` + +3. Invoke the `htop` command. + + ```console + / # htop + ``` + +#### Example, join another container's PID namespace + +Joining another container's PID namespace can be useful for debugging that +container. + +1. Start a container running a Redis server: + + ```console + $ docker run --rm --name my-nginx -d nginx:alpine + ``` + +2. Run an Alpine container that attaches the `--pid` namespace to the + `my-nginx` container: + + ```console + $ docker run --rm -it --pid=container:my-nginx \ + --cap-add SYS_PTRACE \ + --security-opt seccomp=unconfined \ + alpine + ``` + +3. Install `strace` in the Alpine container: + + ```console + / # apk add strace + ``` + +4. Attach to process 1, the process ID of the `my-nginx` container: + + ```console + / # strace -p 1 + strace: Process 1 attached + ``` + ### Full container capabilities (--privileged) ```console diff --git a/docs/reference/run.md b/docs/reference/run.md index 4f43d7eba7e0..bd9aa7c93347 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -159,63 +159,6 @@ $ docker ps -q --filter ancestor=nginx:alpine For more information about using filters, see [Filtering](https://docs.docker.com/config/filter/). -## PID settings (--pid) - - --pid="" : Set the PID (Process) Namespace mode for the container, - 'container:': joins another container's PID namespace - 'host': use the host's PID namespace inside the container - -By default, all containers have the PID namespace enabled. - -PID namespace provides separation of processes. The PID Namespace removes the -view of the system processes, and allows process ids to be reused including -pid 1. - -In certain cases you want your container to share the host's process namespace, -basically allowing processes within the container to see all of the processes -on the system. For example, you could build a container with debugging tools -like `strace` or `gdb`, but want to use these tools when debugging processes -within the container. - -### Example: run htop inside a container - -Create this Dockerfile: - -```dockerfile -FROM alpine:latest -RUN apk add --update htop && rm -rf /var/cache/apk/* -CMD ["htop"] -``` - -Build the Dockerfile and tag the image as `myhtop`: - -```console -$ docker build -t myhtop . -``` - -Use the following command to run `htop` inside a container: - -```console -$ docker run -it --rm --pid=host myhtop -``` - -Joining another container's pid namespace can be used for debugging that container. - -### Example - -Start a container running a redis server: - -```console -$ docker run --name my-redis -d redis -``` - -Debug the redis container by running another container that has strace in it: - -```console -$ docker run -it --pid=container:my-redis my_strace_docker_image bash -$ strace -p 1 -``` - ## UTS settings (--uts) --uts="" : Set the UTS namespace mode for the container, From ff62bf47b02d7efd67819d635a05ff8af11b2f37 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 22 Nov 2023 09:29:53 +0100 Subject: [PATCH 05/24] docs: move --uts to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 19 ++++++++++++++++++- docs/reference/run.md | 15 --------------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 2688d3b59b32..8111f40fbff1 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -109,7 +109,7 @@ Create and run a new container from an image | [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | | `-u`, `--user` | `string` | | Username or UID (format: [:]) | | `--userns` | `string` | | User namespace to use | -| `--uts` | `string` | | UTS namespace to use | +| [`--uts`](#uts) | `string` | | UTS namespace to use | | [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume | | `--volume-driver` | `string` | | Optional volume driver for the container | | [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) | @@ -272,6 +272,23 @@ container. strace: Process 1 attached ``` +### UTS settings (--uts) + +```text +--uts="" : Set the UTS namespace mode for the container + 'host': use the host's UTS namespace inside the container +``` + +The UTS namespace is for setting the hostname and the domain that's visible to +running processes in that namespace. By default, all containers, including +those with `--network=host`, have their own UTS namespace. The `host` setting +will result in the container using the same UTS namespace as the host. Note +that `--hostname` and `--domainname` are invalid in `host` UTS mode. + +You may wish to share the UTS namespace with the host if you would like the +hostname of the container to change as the hostname of the host changes. A more +advanced use case would be changing the host's hostname from a container. + ### Full container capabilities (--privileged) ```console diff --git a/docs/reference/run.md b/docs/reference/run.md index bd9aa7c93347..4eed05b2c072 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -159,21 +159,6 @@ $ docker ps -q --filter ancestor=nginx:alpine For more information about using filters, see [Filtering](https://docs.docker.com/config/filter/). -## UTS settings (--uts) - - --uts="" : Set the UTS namespace mode for the container, - 'host': use the host's UTS namespace inside the container - -The UTS namespace is for setting the hostname and the domain that is visible -to running processes in that namespace. By default, all containers, including -those with `--network=host`, have their own UTS namespace. The `host` setting will -result in the container using the same UTS namespace as the host. Note that -`--hostname` and `--domainname` are invalid in `host` UTS mode. - -You may wish to share the UTS namespace with the host if you would like the -hostname of the container to change as the hostname of the host changes. A -more advanced use case would be changing the host's hostname from a container. - ## IPC settings (--ipc) --ipc="MODE" : Set the IPC mode for the container From 5dd6e9a4d4a7b41c2feb02b023a1e624426c937b Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 22 Nov 2023 09:31:30 +0100 Subject: [PATCH 06/24] docs: move --ipc to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 34 ++++++++++++++++++++++++++++++- docs/reference/run.md | 30 --------------------------- 2 files changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 8111f40fbff1..7a478fdccdd1 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -64,7 +64,7 @@ Create and run a new container from an image | `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | | `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | | `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | -| `--ipc` | `string` | | IPC mode to use | +| [`--ipc`](#ipc) | `string` | | IPC mode to use | | [`--isolation`](#isolation) | `string` | | Container isolation technology | | `--kernel-memory` | `bytes` | `0` | Kernel memory limit | | [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container | @@ -289,6 +289,38 @@ You may wish to share the UTS namespace with the host if you would like the hostname of the container to change as the hostname of the host changes. A more advanced use case would be changing the host's hostname from a container. +## IPC settings (--ipc) + +```text +--ipc="MODE" : Set the IPC mode for the container +``` + +The `--ipc` flag accepts the following values: + +| Value | Description | +|:---------------------------|:----------------------------------------------------------------------------------| +| "" | Use daemon's default. | +| "none" | Own private IPC namespace, with /dev/shm not mounted. | +| "private" | Own private IPC namespace. | +| "shareable" | Own private IPC namespace, with a possibility to share it with other containers. | +| "container:<_name-or-ID_>" | Join another ("shareable") container's IPC namespace. | +| "host" | Use the host system's IPC namespace. | + +If not specified, daemon default is used, which can either be `"private"` +or `"shareable"`, depending on the daemon version and configuration. + +IPC (POSIX/SysV IPC) namespace provides separation of named shared memory +segments, semaphores and message queues. + +Shared memory segments are used to accelerate inter-process communication at +memory speed, rather than through pipes or through the network stack. Shared +memory is commonly used by databases and custom-built (typically C/OpenMPI, +C++/using boost libraries) high performance applications for scientific +computing and financial services industries. If these types of applications +are broken into multiple containers, you might need to share the IPC mechanisms +of the containers, using `"shareable"` mode for the main (i.e. "donor") +container, and `"container:"` for other containers. + ### Full container capabilities (--privileged) ```console diff --git a/docs/reference/run.md b/docs/reference/run.md index 4eed05b2c072..7b341e675555 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -159,36 +159,6 @@ $ docker ps -q --filter ancestor=nginx:alpine For more information about using filters, see [Filtering](https://docs.docker.com/config/filter/). -## IPC settings (--ipc) - - --ipc="MODE" : Set the IPC mode for the container - -The following values are accepted: - -| Value | Description | -|:---------------------------|:----------------------------------------------------------------------------------| -| "" | Use daemon's default. | -| "none" | Own private IPC namespace, with /dev/shm not mounted. | -| "private" | Own private IPC namespace. | -| "shareable" | Own private IPC namespace, with a possibility to share it with other containers. | -| "container:<_name-or-ID_>" | Join another ("shareable") container's IPC namespace. | -| "host" | Use the host system's IPC namespace. | - -If not specified, daemon default is used, which can either be `"private"` -or `"shareable"`, depending on the daemon version and configuration. - -IPC (POSIX/SysV IPC) namespace provides separation of named shared memory -segments, semaphores and message queues. - -Shared memory segments are used to accelerate inter-process communication at -memory speed, rather than through pipes or through the network stack. Shared -memory is commonly used by databases and custom-built (typically C/OpenMPI, -C++/using boost libraries) high performance applications for scientific -computing and financial services industries. If these types of applications -are broken into multiple containers, you might need to share the IPC mechanisms -of the containers, using `"shareable"` mode for the main (i.e. "donor") -container, and `"container:"` for other containers. - ## Network settings --dns=[] : Set custom dns servers for the container From 73620975d0429b6404f0e1922781437bac130185 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 22 Nov 2023 10:50:47 +0100 Subject: [PATCH 07/24] docs: simplify container networking intro Create an easier to digest introduction to container networking, move the bulk of information to the networking overview page. Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 207 +++++------------------------------------- 1 file changed, 23 insertions(+), 184 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 7b341e675555..a4643ac0c80e 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -159,196 +159,35 @@ $ docker ps -q --filter ancestor=nginx:alpine For more information about using filters, see [Filtering](https://docs.docker.com/config/filter/). -## Network settings - - --dns=[] : Set custom dns servers for the container - --network="bridge" : Connect a container to a network - 'bridge': create a network stack on the default Docker bridge - 'none': no networking - 'container:': reuse another container's network stack - 'host': use the Docker host network stack - '|': connect to a user-defined network - --network-alias=[] : Add network-scoped alias for the container - --add-host="" : Add a line to /etc/hosts (host:IP) - --mac-address="" : Sets the container's Ethernet device's MAC address - --ip="" : Sets the container's Ethernet device's IPv4 address - --ip6="" : Sets the container's Ethernet device's IPv6 address - --link-local-ip=[] : Sets one or more container's Ethernet device's link local IPv4/IPv6 addresses - -By default, all containers have networking enabled and they can make any -outgoing connections. The operator can completely disable networking -with `docker run --network none` which disables all incoming and outgoing -networking. In cases like this, you would perform I/O through files or -`STDIN` and `STDOUT` only. - -Publishing ports and linking to other containers only works with the default (bridge). The linking feature is a legacy feature. You should always prefer using Docker network drivers over linking. - -Your container will use the same DNS servers as the host by default, but -you can override this with `--dns`. - -By default, the MAC address is generated using the IP address allocated to the -container. You can set the container's MAC address explicitly by providing a -MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`).Be -aware that Docker does not check if manually specified MAC addresses are unique. - -Supported networks : +## Container networking - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NetworkDescription
none - No networking in the container. -
bridge (default) - Connect the container to the bridge via veth interfaces. -
host - Use the host's network stack inside the container. -
container:<name|id> - Use the network stack of another container, specified via - its name or id. -
NETWORK - Connects the container to a user created network (using docker network create command) -
- -#### Network: none - -With the network is `none` a container will not have -access to any external routes. The container will still have a -`loopback` interface enabled in the container but it does not have any -routes to external traffic. - -#### Network: bridge - -With the network set to `bridge` a container will use docker's -default networking setup. A bridge is setup on the host, commonly named -`docker0`, and a pair of `veth` interfaces will be created for the -container. One side of the `veth` pair will remain on the host attached -to the bridge while the other side of the pair will be placed inside the -container's namespaces in addition to the `loopback` interface. An IP -address will be allocated for containers on the bridge's network and -traffic will be routed though this bridge to the container. - -Containers can communicate via their IP addresses by default. To communicate by -name, they must be linked. - -#### Network: host - -With the network set to `host` a container will share the host's -network stack and all interfaces from the host will be available to the -container. The container's hostname will match the hostname on the host -system. Note that `--mac-address` is invalid in `host` netmode. Even in `host` -network mode a container has its own UTS namespace by default. As such -`--hostname` and `--domainname` are allowed in `host` network mode and will -only change the hostname and domain name inside the container. -Similar to `--hostname`, the `--add-host`, `--dns`, `--dns-search`, and -`--dns-option` options can be used in `host` network mode. These options update -`/etc/hosts` or `/etc/resolv.conf` inside the container. No change are made to -`/etc/hosts` and `/etc/resolv.conf` on the host. - -Compared to the default `bridge` mode, the `host` mode gives *significantly* -better networking performance since it uses the host's native networking stack -whereas the bridge has to go through one level of virtualization through the -docker daemon. It is recommended to run containers in this mode when their -networking performance is critical, for example, a production Load Balancer -or a High Performance Web Server. - -> **Note** -> -> `--network="host"` gives the container full access to local system services -> such as D-bus and is therefore considered insecure. +Containers have networking enabled by default, and they can make outgoing +connections. If you're running multiple containers that need to communicate +with each other, you can create a custom network and attach the containers to +the network. -#### Network: container - -With the network set to `container` a container will share the -network stack of another container. The other container's name must be -provided in the format of `--network container:`. Note that `--add-host` -`--hostname` `--dns` `--dns-search` `--dns-option` and `--mac-address` are -invalid in `container` netmode, and `--publish` `--publish-all` `--expose` are -also invalid in `container` netmode. - -Example running a Redis container with Redis binding to `localhost` then -running the `redis-cli` command and connecting to the Redis server over the -`localhost` interface. +When multiple containers are attached to the same custom network, they can +communicate with each other using the container names as a DNS hostname. The +following example creates a custom network named `my-net`, and runs two +containers that attach to the network. ```console -$ docker run -d --name redis example/redis --bind 127.0.0.1 -$ # use the redis container's network stack to access localhost -$ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1 -``` - -#### User-defined network - -You can create a network using a Docker network driver or an external network -driver plugin. You can connect multiple containers to the same network. Once -connected to a user-defined network, the containers can communicate easily using -only another container's IP address or name. - -For `overlay` networks or custom plugins that support multi-host connectivity, -containers connected to the same multi-host network but launched from different -Engines can also communicate in this way. - -The following example creates a network using the built-in `bridge` network -driver and running a container in the created network - -```console -$ docker network create -d bridge my-net -$ docker run --network=my-net -itd --name=container3 busybox -``` - -### Managing /etc/hosts - -Your container will have lines in `/etc/hosts` which define the hostname of the -container itself as well as `localhost` and a few other common things. The -`--add-host` flag can be used to add additional lines to `/etc/hosts`. - -```console -$ docker run -it --add-host db-static:86.75.30.9 ubuntu cat /etc/hosts - -172.17.0.22 09d03f76bf2c -fe00::0 ip6-localnet -ff00::0 ip6-mcastprefix -ff02::1 ip6-allnodes -ff02::2 ip6-allrouters -127.0.0.1 localhost -::1 localhost ip6-localhost ip6-loopback -86.75.30.9 db-static +$ docker network create my-net +$ docker run -d --name web --network my-net nginx:alpine +$ docker run --rm -it --network my-net busybox +/ # ping web +PING web (172.18.0.2): 56 data bytes +64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.326 ms +64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.257 ms +64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.281 ms +^C +--- web ping statistics --- +3 packets transmitted, 3 packets received, 0% packet loss +round-trip min/avg/max = 0.257/0.288/0.326 ms ``` -If a container is connected to the default bridge network and `linked` -with other containers, then the container's `/etc/hosts` file is updated -with the linked container's name. - -> **Note** -> -> Since Docker may live update the container’s `/etc/hosts` file, there -> may be situations when processes inside the container can end up reading an -> empty or incomplete `/etc/hosts` file. In most cases, retrying the read again -> should fix the problem. +For more information about container networking, see [Networking +overview](https://docs.docker.com/network/) ## Restart policies (--restart) From dbffa0d121571742302a75c7eda484b7ab7219a4 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 13:43:16 +0100 Subject: [PATCH 08/24] docs: move --restart to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 53 ++++++++++++++- docs/reference/run.md | 109 ------------------------------ 2 files changed, 50 insertions(+), 112 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 7a478fdccdd1..e190bbd52847 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -1009,9 +1009,56 @@ $ docker run --restart=always redis This will run the `redis` container with a restart policy of **always** so that if the container exits, Docker restarts it. -You can find more detailed information on restart policies in the -[Restart Policies (--restart)](../run.md#restart-policies---restart) -section of the Docker run reference page. +When a restart policy is active on a container, it shows as either `Up` or +`Restarting` in [`docker ps`](ps.md). It can also be useful to use [`docker +events`](events.md) to see the restart policy in effect. + +An increasing delay (double the previous delay, starting at 100 milliseconds) +is added before each restart to prevent flooding the server. This means the +daemon waits for 100 ms, then 200 ms, 400, 800, 1600, and so on until either +the `on-failure` limit, the maximum delay of 1 minute is hit, or when you +`docker stop` or `docker rm -f` the container. + +If a container is successfully restarted (the container is started and runs +for at least 10 seconds), the delay is reset to its default value of 100 ms. + +#### Specify a limit for restart attempts + +You can specify the maximum amount of times Docker attempts to restart the +container when using the **on-failure** policy. By default, Docker never stops +attempting to restart the container. + +The following example runs the `redis` container with a restart policy of +**on-failure** and a maximum restart count of 10. + +```console +$ docker run --restart=on-failure:10 redis +``` + +If the `redis` container exits with a non-zero exit status more than 10 times +in a row, Docker stops trying to restart the container. Providing a maximum +restart limit is only valid for the **on-failure** policy. + +#### Inspect container restarts + +The number of (attempted) restarts for a container can be obtained using the +[`docker inspect`](commandline/inspect.md) command. For example, to get the +number of restarts for container "my-container"; + +```console +$ docker inspect -f "{{ .RestartCount }}" my-container +2 +``` + +Or, to get the last time the container was (re)started; + +```console +$ docker inspect -f "{{ .State.StartedAt }}" my-container +2015-03-04T23:47:07.691840179Z +``` + +Combining `--restart` (restart policy) with the `--rm` (clean up) flag results +in an error. On container restart, attached clients are disconnected. ### Add entries to container hosts file (--add-host) diff --git a/docs/reference/run.md b/docs/reference/run.md index a4643ac0c80e..c8194dc834c7 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -189,115 +189,6 @@ round-trip min/avg/max = 0.257/0.288/0.326 ms For more information about container networking, see [Networking overview](https://docs.docker.com/network/) -## Restart policies (--restart) - -Using the `--restart` flag on Docker run you can specify a restart policy for -how a container should or should not be restarted on exit. - -When a restart policy is active on a container, it will be shown as either `Up` -or `Restarting` in [`docker ps`](commandline/ps.md). It can also be -useful to use [`docker events`](commandline/events.md) to see the -restart policy in effect. - -Docker supports the following restart policies: - - - - - - - - - - - - - - - - - - - - - - - - - - -
PolicyResult
no - Do not automatically restart the container when it exits. This is the - default. -
- - on-failure[:max-retries] - - - Restart only if the container exits with a non-zero exit status. - Optionally, limit the number of restart retries the Docker - daemon attempts. -
always - Always restart the container regardless of the exit status. - When you specify always, the Docker daemon will try to restart - the container indefinitely. The container will also always start - on daemon startup, regardless of the current state of the container. -
unless-stopped - Always restart the container regardless of the exit status, - including on daemon startup, except if the container was put - into a stopped state before the Docker daemon was stopped. -
- -An increasing delay (double the previous delay, starting at 100 milliseconds) -is added before each restart to prevent flooding the server. -This means the daemon will wait for 100 ms, then 200 ms, 400, 800, 1600, -and so on until either the `on-failure` limit, the maximum delay of 1 minute is -hit, or when you `docker stop` or `docker rm -f` the container. - -If a container is successfully restarted (the container is started and runs -for at least 10 seconds), the delay is reset to its default value of 100 ms. - -You can specify the maximum amount of times Docker will try to restart the -container when using the **on-failure** policy. The default is that Docker -will try forever to restart the container. The number of (attempted) restarts -for a container can be obtained via [`docker inspect`](commandline/inspect.md). For example, to get the number of restarts -for container "my-container"; - -```console -$ docker inspect -f "{{ .RestartCount }}" my-container -# 2 -``` - -Or, to get the last time the container was (re)started; - -```console -$ docker inspect -f "{{ .State.StartedAt }}" my-container -# 2015-03-04T23:47:07.691840179Z -``` - -Combining `--restart` (restart policy) with the `--rm` (clean up) flag results -in an error. On container restart, attached clients are disconnected. See the -examples on using the [`--rm` (clean up)](#clean-up---rm) flag later in this page. - -### Examples - -```console -$ docker run --restart=always redis -``` - -This will run the `redis` container with a restart policy of **always** -so that if the container exits, Docker will restart it. - -```console -$ docker run --restart=on-failure:10 redis -``` - -This will run the `redis` container with a restart policy of **on-failure** -and a maximum restart count of 10. If the `redis` container exits with a -non-zero exit status more than 10 times in a row Docker will abort trying to -restart the container. Providing a maximum restart limit is only valid for the -**on-failure** policy. - ## Exit Status The exit code from `docker run` gives information about why the container From 32189ca273d7457c064eed7a9e8e310402c000f3 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 13:49:06 +0100 Subject: [PATCH 09/24] docs: improve description about container exit codes Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index c8194dc834c7..268a36c2a2c1 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -189,13 +189,15 @@ round-trip min/avg/max = 0.257/0.288/0.326 ms For more information about container networking, see [Networking overview](https://docs.docker.com/network/) -## Exit Status +## Exit status The exit code from `docker run` gives information about why the container -failed to run or why it exited. When `docker run` exits with a non-zero code, -the exit codes follow the `chroot` standard, see below: +failed to run or why it exited. The following sections describe the meanings of +different container exit codes values. -**_125_** if the error is with Docker daemon **_itself_** +### 125 + +Exit code `125` indicates that the error is with Docker daemon itself. ```console $ docker run --foo busybox; echo $? @@ -205,7 +207,10 @@ See 'docker run --help'. 125 ``` -**_126_** if the **_contained command_** cannot be invoked +### 126 + +Exit code `126` indicates that the specified contained command can't be invoked. +The container command in the following example is: `/etc; echo $?`. ```console $ docker run busybox /etc; echo $? @@ -214,7 +219,9 @@ docker: Error response from daemon: Container command '/etc' could not be invoke 126 ``` -**_127_** if the **_contained command_** cannot be found +### 127 + +Exit code `127` indicates that the contained command can't be found. ```console $ docker run busybox foo; echo $? @@ -223,7 +230,10 @@ docker: Error response from daemon: Container command 'foo' not found or does no 127 ``` -**_Exit code_** of **_contained command_** otherwise +### Other exit codes + +Any exit code other than `125`, `126`, and `127` represent the exit code of the +provided container command. ```console $ docker run busybox /bin/sh -c 'exit 3' From f98444490f673b8e60bd0be676a012c868e551dd Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 13:52:55 +0100 Subject: [PATCH 10/24] docs: move --rm to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 32 ++++++++++++++++++++++++++++++- docs/reference/run.md | 27 -------------------------- 2 files changed, 31 insertions(+), 28 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index e190bbd52847..5e905e273082 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -95,7 +95,7 @@ Create and run a new container from an image | `-q`, `--quiet` | | | Suppress the pull output | | [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only | | [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits | -| `--rm` | | | Automatically remove the container when it exits | +| [`--rm`](#rm) | | | Automatically remove the container when it exits | | `--runtime` | `string` | | Runtime to use for this container | | [`--security-opt`](#security-opt) | `list` | | Security Options | | `--shm-size` | `bytes` | `0` | Size of /dev/shm | @@ -1060,6 +1060,36 @@ $ docker inspect -f "{{ .State.StartedAt }}" my-container Combining `--restart` (restart policy) with the `--rm` (clean up) flag results in an error. On container restart, attached clients are disconnected. +### Clean up (--rm) + +By default, a container's file system persists even after the container exits. +This makes debugging a lot easier, since you can inspect the container's final +state and you retain all your data. + +If you are running short-term **foreground** processes, these container file +systems can start to pile up. If you'd like Docker to automatically clean up +the container and remove the file system when the container exits, use the +`--rm` flag: + +```text +--rm=false: Automatically remove the container when it exits +``` + +> **Note** +> +> If you set the `--rm` flag, Docker also removes the anonymous volumes +> associated with the container when the container is removed. This is similar +> to running `docker rm -v my-container`. Only volumes that are specified without +> a name are removed. For example, when running: +> +> ```console +> $ docker run --rm -v /foo -v awesome:/bar busybox top +> ``` +> +> the volume for `/foo` will be removed, but the volume for `/bar` will not. +> Volumes inherited via `--volumes-from` will be removed with the same logic: if +> the original volume was specified with a name it will **not** be removed. + ### Add entries to container hosts file (--add-host) You can add other hosts into a container's `/etc/hosts` file by using one or diff --git a/docs/reference/run.md b/docs/reference/run.md index 268a36c2a2c1..b460e714ef31 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -241,33 +241,6 @@ $ echo $? 3 ``` -## Clean up (--rm) - -By default a container's file system persists even after the container -exits. This makes debugging a lot easier (since you can inspect the -final state) and you retain all your data by default. But if you are -running short-term **foreground** processes, these container file -systems can really pile up. If instead you'd like Docker to -**automatically clean up the container and remove the file system when -the container exits**, you can add the `--rm` flag: - - --rm=false: Automatically remove the container when it exits - -> **Note** -> -> If you set the `--rm` flag, Docker also removes the anonymous volumes -> associated with the container when the container is removed. This is similar -> to running `docker rm -v my-container`. Only volumes that are specified without -> a name are removed. For example, when running: -> -> ```console -> $ docker run --rm -v /foo -v awesome:/bar busybox top -> ``` -> -> the volume for `/foo` will be removed, but the volume for `/bar` will not. -> Volumes inherited via `--volumes-from` will be removed with the same logic: if -> the original volume was specified with a name it will **not** be removed. - ## Security configuration | Option | Description | From 92c664b0dc1f8c644f09a6d6f56b0753c5b4186f Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 14:13:24 +0100 Subject: [PATCH 11/24] docs: move info about --security-opt to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 57 ++++++++++++++++++++++++++++- docs/reference/run.md | 59 ------------------------------- 2 files changed, 56 insertions(+), 60 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 5e905e273082..3deaf5fd606b 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -1206,7 +1206,62 @@ in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined. ### Optional security options (--security-opt) -On Windows, you can use this flag to specify the `credentialspec` option. +| Option | Description | +|:------------------------------------------|:--------------------------------------------------------------------------| +| `--security-opt="label=user:USER"` | Set the label user for the container | +| `--security-opt="label=role:ROLE"` | Set the label role for the container | +| `--security-opt="label=type:TYPE"` | Set the label type for the container | +| `--security-opt="label=level:LEVEL"` | Set the label level for the container | +| `--security-opt="label=disable"` | Turn off label confinement for the container | +| `--security-opt="apparmor=PROFILE"` | Set the apparmor profile to be applied to the container | +| `--security-opt="no-new-privileges=true"` | Disable container processes from gaining new privileges | +| `--security-opt="seccomp=unconfined"` | Turn off seccomp confinement for the container | +| `--security-opt="seccomp=profile.json"` | White-listed syscalls seccomp Json file to be used as a seccomp filter | + +The `--security-opt` flag lets you override the default labeling scheme for a +container. Specifying the level in the following command allows you to share +the same content between containers. + +```console +$ docker run --security-opt label=level:s0:c100,c200 -it fedora bash +``` + +> **Note** +> +> Automatic translation of MLS labels isn't supported. + +To disable the security labeling for a container entirely, you can use +`label=disable`: + +```console +$ docker run --security-opt label=disable -it ubuntu bash +``` + +If you want a tighter security policy on the processes within a container, you +can specify a custom `type` label. The following example runs a container +that's only allowed to listen on Apache ports: + +```console +$ docker run --security-opt label=type:svirt_apache_t -it ubuntu bash +``` + +> **Note** +> +> You would have to write policy defining a `svirt_apache_t` type. + +To prevent your container processes from gaining additional privileges, you can +use the following command: + +```console +$ docker run --security-opt no-new-privileges -it ubuntu bash +``` + +This means that commands that raise privileges such as `su` or `sudo` will no longer work. +It also causes any seccomp filters to be applied later, after privileges have been dropped +which may mean you can have a more restrictive set of filters. +For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt). + +On Windows, you can use the `--security-opt` flag to specify the `credentialspec` option. The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. ### Stop container with timeout (--stop-timeout) diff --git a/docs/reference/run.md b/docs/reference/run.md index b460e714ef31..5f2356d90f65 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -241,65 +241,6 @@ $ echo $? 3 ``` -## Security configuration - -| Option | Description | -|:------------------------------------------|:--------------------------------------------------------------------------| -| `--security-opt="label=user:USER"` | Set the label user for the container | -| `--security-opt="label=role:ROLE"` | Set the label role for the container | -| `--security-opt="label=type:TYPE"` | Set the label type for the container | -| `--security-opt="label=level:LEVEL"` | Set the label level for the container | -| `--security-opt="label=disable"` | Turn off label confinement for the container | -| `--security-opt="apparmor=PROFILE"` | Set the apparmor profile to be applied to the container | -| `--security-opt="no-new-privileges=true"` | Disable container processes from gaining new privileges | -| `--security-opt="seccomp=unconfined"` | Turn off seccomp confinement for the container | -| `--security-opt="seccomp=profile.json"` | White-listed syscalls seccomp Json file to be used as a seccomp filter | - - -You can override the default labeling scheme for each container by specifying -the `--security-opt` flag. Specifying the level in the following command -allows you to share the same content between containers. - -```console -$ docker run --security-opt label=level:s0:c100,c200 -it fedora bash -``` - -> **Note** -> -> Automatic translation of MLS labels is not currently supported. - -To disable the security labeling for this container versus running with the -`--privileged` flag, use the following command: - -```console -$ docker run --security-opt label=disable -it fedora bash -``` - -If you want a tighter security policy on the processes within a container, -you can specify an alternate type for the container. You could run a container -that is only allowed to listen on Apache ports by executing the following -command: - -```console -$ docker run --security-opt label=type:svirt_apache_t -it centos bash -``` - -> **Note** -> -> You would have to write policy defining a `svirt_apache_t` type. - -If you want to prevent your container processes from gaining additional -privileges, you can execute the following command: - -```console -$ docker run --security-opt no-new-privileges -it centos bash -``` - -This means that commands that raise privileges such as `su` or `sudo` will no longer work. -It also causes any seccomp filters to be applied later, after privileges have been dropped -which may mean you can have a more restrictive set of filters. -For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt). - ## Specify an init process You can use the `--init` flag to indicate that an init process should be used as From 9e75a4cf610de22c05f1740333b240cc2ac2efda Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 14:15:17 +0100 Subject: [PATCH 12/24] docs: move --init to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 13 ++++++++++++- docs/reference/run.md | 11 ----------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 3deaf5fd606b..445111bd988e 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -58,7 +58,7 @@ Create and run a new container from an image | `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | | `--help` | | | Print usage | | `-h`, `--hostname` | `string` | | Container host name | -| `--init` | | | Run an init inside the container that forwards signals and reaps processes | +| [`--init`](#init) | | | Run an init inside the container that forwards signals and reaps processes | | [`-i`](#interactive), [`--interactive`](#interactive) | | | Keep STDIN open even if not attached | | `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | | `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | @@ -902,6 +902,17 @@ $ docker run --rm -i busybox echo "foo bar baz" \ rab ``` +## Specify an init process + +You can use the `--init` flag to indicate that an init process should be used as +the PID 1 in the container. Specifying an init process ensures the usual +responsibilities of an init system, such as reaping zombie processes, are +performed inside the created container. + +The default init process used is the first `docker-init` executable found in the +system path of the Docker daemon process. This `docker-init` binary, included in +the default installation, is backed by [tini](https://github.com/krallin/tini). + ### Allocate a pseudo-TTY (-t, --tty) The `--tty` (or `-t`) flag attaches a pseudo-TTY to the container, connecting diff --git a/docs/reference/run.md b/docs/reference/run.md index 5f2356d90f65..52a99eb611ad 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -241,17 +241,6 @@ $ echo $? 3 ``` -## Specify an init process - -You can use the `--init` flag to indicate that an init process should be used as -the PID 1 in the container. Specifying an init process ensures the usual -responsibilities of an init system, such as reaping zombie processes, are -performed inside the created container. - -The default init process used is the first `docker-init` executable found in the -system path of the Docker daemon process. This `docker-init` binary, included in -the default installation, is backed by [tini](https://github.com/krallin/tini). - ## Specify custom cgroups Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a From 72df1960e153f7841957ac74f80208a7fe6327b9 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 14:17:19 +0100 Subject: [PATCH 13/24] docs: move --cgroup-parent to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 9 ++++++++- docs/reference/run.md | 7 ------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 445111bd988e..1100aa4ecefa 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -18,7 +18,7 @@ Create and run a new container from an image | `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | | `--cap-add` | `list` | | Add Linux capabilities | | `--cap-drop` | `list` | | Drop Linux capabilities | -| `--cgroup-parent` | `string` | | Optional parent cgroup for the container | +| [`--cgroup-parent`](#cgroup-parent) | `string` | | Optional parent cgroup for the container | | `--cgroupns` | `string` | | Cgroup namespace to use (host\|private)
'host': Run the container in the Docker host's cgroup namespace
'private': Run the container in its own private cgroup namespace
'': Use the cgroup namespace as configured by the
default-cgroupns-mode option on the daemon (default) | | [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file | | `--cpu-count` | `int64` | `0` | CPU count (Windows only) | @@ -949,6 +949,13 @@ You can use the `-t` flag without `-i` flag. This still allocates a pseudo-TTY to the container, but with no way of writing to `STDIN`. The only time this might be useful is if the output of the container requires a TTY environment. +## Specify custom cgroups + +Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a +container in. This allows you to create and manage cgroups on their own. You can +define custom resources for those cgroups and put containers under a common +parent group. + ### Using dynamically created devices (--device-cgroup-rule) Docker assigns devices available to a container at creation time. The diff --git a/docs/reference/run.md b/docs/reference/run.md index 52a99eb611ad..0653c26c5eb1 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -241,13 +241,6 @@ $ echo $? 3 ``` -## Specify custom cgroups - -Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a -container in. This allows you to create and manage cgroups on their own. You can -define custom resources for those cgroups and put containers under a common -parent group. - ## Runtime constraints on resources The operator can also adjust the performance parameters of the From 4a6cde88599aafec7b1a6d048d0747fe4b3e5c33 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 14:25:06 +0100 Subject: [PATCH 14/24] docs: move --log-driver to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 20 +++++++++++++++++++- docs/reference/run.md | 26 -------------------------- 2 files changed, 19 insertions(+), 27 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 1100aa4ecefa..c0f19c2c7a04 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -71,7 +71,7 @@ Create and run a new container from an image | `--label-file` | `list` | | Read in a line delimited file of labels | | `--link` | `list` | | Add link to another container | | `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | -| `--log-driver` | `string` | | Logging driver for the container | +| [`--log-driver`](#log-driver) | `string` | | Logging driver for the container | | `--log-opt` | `list` | | Log driver options | | `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | | [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | @@ -1162,6 +1162,24 @@ The `--add-host` flag also accepts a `:` separator, for example: $ docker run --add-host=my-hostname:8.8.8.8 --rm -it alpine ``` +## Logging drivers (--log-driver) + +The container can have a different logging driver than the Docker daemon. Use +the `--log-driver=` with the `docker run` command to configure the +container's logging driver. + +To learn about the supported logging drivers and how to use them, refer to +[Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). + +To disable logging for a container, set the `--log-driver` flag to `none`: + +```console +$ docker run --log-driver=none -d nginx:alpine +5101d3b7fe931c27c2ba0e65fd989654d297393ad65ae238f20b97a020e7295b +$ docker logs 5101d3b +Error response from daemon: configured logging driver does not support reading +``` + ### Set ulimits in container (--ulimit) Since setting `ulimit` settings in a container requires extra privileges not diff --git a/docs/reference/run.md b/docs/reference/run.md index 0653c26c5eb1..98931c462965 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -888,32 +888,6 @@ drwxrwxr-x 1 1000 1000 4096 Dec 4 06:11 .git The default seccomp profile will adjust to the selected capabilities, in order to allow use of facilities allowed by the capabilities, so you should not have to adjust this. -## Logging drivers (--log-driver) - -The container can have a different logging driver than the Docker daemon. Use -the `--log-driver=VALUE` with the `docker run` command to configure the -container's logging driver. The following options are supported: - -| Driver | Description | -|:-------------|:-------------------------------------------------------------------------------------------------------------------------------| -| `none` | Disables any logging for the container. `docker logs` won't be available with this driver. | -| `local` | Logs are stored in a custom format designed for minimal overhead. | -| `json-file` | Default logging driver for Docker. Writes JSON messages to file. No logging options are supported for this driver. | -| `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. | -| `journald` | Journald logging driver for Docker. Writes log messages to `journald`. | -| `gelf` | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. | -| `fluentd` | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input). | -| `awslogs` | Amazon CloudWatch Logs logging driver for Docker. Writes log messages to Amazon CloudWatch Logs. | -| `splunk` | Splunk logging driver for Docker. Writes log messages to `splunk` using Event Http Collector. | -| `etwlogs` | Event Tracing for Windows (ETW) events. Writes log messages as Event Tracing for Windows (ETW) events. Only Windows platforms. | -| `gcplogs` | Google Cloud Platform (GCP) Logging. Writes log messages to Google Cloud Platform (GCP) Logging. | -| `logentries` | Rapid7 Logentries. Writes log messages to Rapid7 Logentries. | - -The `docker logs` command is available only for the `json-file` and `journald` -logging drivers. For detailed information on working with logging drivers, see -[Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). - - ## Overriding Dockerfile image defaults When a developer builds an image from a [*Dockerfile*](https://docs.docker.com/engine/reference/builder/) From c695ad9d74a9c9fb05888b6062832335874a5875 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 23 Nov 2023 15:47:03 +0100 Subject: [PATCH 15/24] docs: rewrite section on overriding image defaults Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 61 ++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 33 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 98931c462965..016977523d75 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -888,46 +888,41 @@ drwxrwxr-x 1 1000 1000 4096 Dec 4 06:11 .git The default seccomp profile will adjust to the selected capabilities, in order to allow use of facilities allowed by the capabilities, so you should not have to adjust this. -## Overriding Dockerfile image defaults +## Overriding image defaults -When a developer builds an image from a [*Dockerfile*](https://docs.docker.com/engine/reference/builder/) -or when committing it, the developer can set a number of default parameters -that take effect when the image starts up as a container. +When you build an image from a [Dockerfile](https://docs.docker.com/engine/reference/builder/), +or when committing it, you can set a number of default parameters that take +effect when the image starts up as a container. When you run an image, you can +override those defaults using flags for the `docker run` command. -Four of the Dockerfile commands cannot be overridden at runtime: `FROM`, -`MAINTAINER`, `RUN`, and `ADD`. Everything else has a corresponding override -in `docker run`. We'll go through what the developer might have set in each -Dockerfile instruction and how the operator can override that setting. +- [Default entrypoint](#default-entrypoint) +- [Default command and options](#default-command-and-options) +- [Expose ports](#exposed-ports) +- [Environment variables](#environment-variables) +- [Healthcheck](#healthchecks) +- [Filesystem mounts](#filesystem-mounts) +- [User](#user) +- [Working directory](#working-directory) - - [CMD (Default Command or Options)](#cmd-default-command-or-options) - - [ENTRYPOINT (Default Command to Execute at Runtime)]( - #entrypoint-default-command-to-execute-at-runtime) - - [EXPOSE (Incoming Ports)](#expose-incoming-ports) - - [ENV (Environment Variables)](#env-environment-variables) - - [HEALTHCHECK](#healthcheck) - - [VOLUME (Shared Filesystems)](#volume-shared-filesystems) - - [USER](#user) - - [WORKDIR](#workdir) +### Default command and options -### CMD (default command or options) - -Recall the optional `COMMAND` in the Docker -commandline: +The command syntax for `docker run` supports optionally specifying commands and +arguments to the container's entrypoint, represented as `[COMMAND]` and +`[ARG...]` in the following synopsis example: ```console $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] ``` -This command is optional because the person who created the `IMAGE` may -have already provided a default `COMMAND` using the Dockerfile `CMD` -instruction. As the operator (the person running a container from the -image), you can override that `CMD` instruction just by specifying a new -`COMMAND`. +This command is optional because whoever created the `IMAGE` may have already +provided a default `COMMAND`, using the Dockerfile `CMD` instruction. When you +run a container, you can override that `CMD` instruction just by specifying a +new `COMMAND`. If the image also specifies an `ENTRYPOINT` then the `CMD` or `COMMAND` get appended as arguments to the `ENTRYPOINT`. -### ENTRYPOINT (default command to execute at runtime) +### Default entrypoint ```console --entrypoint="": Overwrite the default entrypoint set by the image @@ -967,7 +962,7 @@ $ docker run -it --entrypoint="" mysql bash > Passing `--entrypoint` will clear out any default command set on the > image (i.e. any `CMD` instruction in the Dockerfile used to build it). -### EXPOSE (incoming ports) +### Exposed ports The following `run` command options work with container networking: @@ -1023,7 +1018,7 @@ If `--link` is used when starting a container in a user-defined network as described in [*Networking overview*](https://docs.docker.com/network/), it will provide a named alias for the container being linked to. -### ENV (environment variables) +### Environment variables Docker automatically sets some environment variables when creating a Linux container. Docker does not set any environment variables when creating a Windows @@ -1093,7 +1088,7 @@ windir=C:\Windows Similarly the operator can set the **HOSTNAME** (Linux) or **COMPUTERNAME** (Windows) with `-h`. -### HEALTHCHECK +### Healthchecks ``` --health-cmd Command to run to check health @@ -1171,7 +1166,7 @@ The example below mounts an empty tmpfs into the container with the `rw`, $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image ``` -### VOLUME (shared filesystems) +### Filesystem mounts -v, --volume=[host-src:]container-dest[:]: Bind mount a volume. The comma-delimited `options` are [rw|ro], [z|Z], @@ -1216,7 +1211,7 @@ For example, you can specify either `/foo` or `foo` for a `host-src` value. If you supply the `/foo` value, Docker creates a bind mount. If you supply the `foo` specification, Docker creates a named volume. -### USER +### User `root` (id = 0) is the default user within a container. The image developer can create additional users. Those users are accessible by name. When passing a numeric @@ -1234,7 +1229,7 @@ the `USER` instruction by passing the `-u` option. > **Note:** if you pass a numeric uid, it must be in the range of 0-2147483647. > If you pass a username, the user must exist in the container. -### WORKDIR +### Working directory The default working directory for running binaries within a container is the root directory (`/`). It is possible to set a different working directory with the From b01e28752752cfd61e804428d40af14efa536594 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 11:24:42 +0100 Subject: [PATCH 16/24] docs: rewrite section on default entrypoint Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 016977523d75..0c16be6c8456 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -924,27 +924,33 @@ get appended as arguments to the `ENTRYPOINT`. ### Default entrypoint -```console - --entrypoint="": Overwrite the default entrypoint set by the image +```text +--entrypoint="": Overwrite the default entrypoint set by the image ``` -The `ENTRYPOINT` of an image is similar to a `COMMAND` because it -specifies what executable to run when the container starts, but it is -(purposely) more difficult to override. The `ENTRYPOINT` gives a -container its default nature or behavior, so that when you set an -`ENTRYPOINT` you can run the container *as if it were that binary*, -complete with default options, and you can pass in more options via the -`COMMAND`. But, sometimes an operator may want to run something else -inside the container, so you can override the default `ENTRYPOINT` at -runtime by using a string to specify the new `ENTRYPOINT`. Here is an -example of how to run a shell in a container that has been set up to -automatically run something else (like `/usr/bin/redis-server`): +The entrypoint refers to the default executable that's invoked when you run a +container. A container's entrypoint is defined using the Dockerfile +`ENTRYPOINT` instruction. It's similar to specifying a default command because +it specifies, but the difference is that you need to pass an explicit flag to +override the entrypoint, whereas you can override default commands with +positional arguments. The defines a container's default behavior, with the idea +that when you set an entrypoint you can run the container *as if it were that +binary*, complete with default options, and you can pass in more options as +commands. But there are cases where you may want to run something else inside +the container. This is when overriding the default entrypoint at runtime comes +in handy, using the `--entrypoint` flag for the `docker run` command. + +The `--entrypoint` flag expects a string value, representing the name or path +of the binary that you want to invoke when the container starts. The following +example shows you how to run a Bash shell in a container that has been set up +to automatically run some other binary (like `/usr/bin/redis-server`): ```console $ docker run -it --entrypoint /bin/bash example/redis ``` -or two examples of how to pass more parameters to that ENTRYPOINT: +The following examples show how to pass additional parameters to the custom +entrypoint, using the positional command arguments: ```console $ docker run -it --entrypoint /bin/bash example/redis -c ls -l @@ -959,8 +965,8 @@ $ docker run -it --entrypoint="" mysql bash > **Note** > -> Passing `--entrypoint` will clear out any default command set on the -> image (i.e. any `CMD` instruction in the Dockerfile used to build it). +> Passing `--entrypoint` clears out any default command set on the image. That +> is, any `CMD` instruction in the Dockerfile used to build it. ### Exposed ports From 3eeac20593e7cd12a30aff512f770741b5ba1b0d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 13:57:22 +0100 Subject: [PATCH 17/24] docs: rewrite section on exposing ports Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 76 +++++++++++++------------------------------ 1 file changed, 23 insertions(+), 53 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 0c16be6c8456..f66e5c363361 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -970,59 +970,29 @@ $ docker run -it --entrypoint="" mysql bash ### Exposed ports -The following `run` command options work with container networking: - - --expose=[]: Expose a port or a range of ports inside the container. - These are additional to those exposed by the `EXPOSE` instruction - -P : Publish all exposed ports to the host interfaces - -p=[] : Publish a container's port or a range of ports to the host - format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort - Both hostPort and containerPort can be specified as a - range of ports. When specifying ranges for both, the - number of container ports in the range must match the - number of host ports in the range, for example: - -p 1234-1236:1234-1236/tcp - - When specifying a range for hostPort only, the - containerPort must not be a range. In this case the - container port is published somewhere within the - specified hostPort range. (e.g., `-p 1234-1236:1234/tcp`) - - (use 'docker port' to see the actual mapping) - - --link="" : Add link to another container (:alias or ) - -With the exception of the `EXPOSE` directive, an image developer hasn't -got much control over networking. The `EXPOSE` instruction defines the -initial incoming ports that provide services. These ports are available -to processes inside the container. An operator can use the `--expose` -option to add to the exposed ports. - -To expose a container's internal port, an operator can start the -container with the `-P` or `-p` flag. The exposed port is accessible on -the host and the ports are available to any client that can reach the -host. - -The `-P` option publishes all the ports to the host interfaces. Docker -binds each exposed port to a random port on the host. The range of -ports are within an *ephemeral port range* defined by -`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to -explicitly map a single port or range of ports. - -The port number inside the container (where the service listens) does -not need to match the port number exposed on the outside of the -container (where clients connect). For example, inside the container an -HTTP service is listening on port 80 (and so the image developer -specifies `EXPOSE 80` in the Dockerfile). At runtime, the port might be -bound to 42800 on the host. To find the mapping between the host ports -and the exposed ports, use `docker port`. - -If the operator uses `--link` when starting a new client container in the -default bridge network, then the client container can access the exposed -port via a private networking interface. -If `--link` is used when starting a container in a user-defined network as -described in [*Networking overview*](https://docs.docker.com/network/), -it will provide a named alias for the container being linked to. +By default, when you run a container, none of the container's ports are exposed +to the host. This means you won't be able to access any ports that the +container might be listening on. To make a container's ports accessible from +the host, you need to publish the ports. + +You can start the container with the `-P` or `-p` flags to expose its ports: + +- The `-P` (or `--publish-all`) flag publishes all the exposed ports to the + host. Docker binds each exposed port to a random port on the host. + + The `-P` flag only publishes port numbers that are explicitly flagged as + exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose` + flag for the `docker run` command. + +- The `-p` (or `--publish`) flag lets you explicitly map a single port or range + of ports in the container to the host. + +The port number inside the container (where the service listens) doesn't need +to match the port number published on the outside of the container (where +clients connect). For example, inside the container an HTTP service might be +listening on port 80. At runtime, the port might be bound to 42800 on the host. +To find the mapping between the host ports and the exposed ports, use the +`docker port` command. ### Environment variables From 7585d66a079998bf1fb179e5d07f1ff6c536e215 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 14:02:18 +0100 Subject: [PATCH 18/24] docs: rewrite section on overriding environment variables Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index f66e5c363361..d7e3b23898bb 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -997,7 +997,7 @@ To find the mapping between the host ports and the exposed ports, use the ### Environment variables Docker automatically sets some environment variables when creating a Linux -container. Docker does not set any environment variables when creating a Windows +container. Docker doesn't set any environment variables when creating a Windows container. The following environment variables are set for Linux containers: @@ -1010,11 +1010,13 @@ The following environment variables are set for Linux containers: | `TERM` | `xterm` if the container is allocated a pseudo-TTY | -Additionally, the operator can **set any environment variable** in the -container by using one or more `-e` flags, even overriding those mentioned -above, or already defined by the developer with a Dockerfile `ENV`. If the -operator names an environment variable without specifying a value, then the -current value of the named variable is propagated into the container's environment: +Additionally, you can set any environment variable in the container by using +one or more `-e` flags. You can even override the variables mentioned above, or +variables defined using a Dockerfile `ENV` instruction when building the image. + +If the you name an environment variable without specifying a value, the current +value of the named variable on the host is propagated into the container's +environment: ```console $ export today=Wednesday @@ -1062,8 +1064,6 @@ USERPROFILE=C:\Users\ContainerAdministrator windir=C:\Windows ``` -Similarly the operator can set the **HOSTNAME** (Linux) or **COMPUTERNAME** (Windows) with `-h`. - ### Healthchecks ``` From 5ede4c82ace2301d10e9cbd7202fc8c612667f71 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 14:08:17 +0100 Subject: [PATCH 19/24] docs: minor improvements to the healthcheck section Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index d7e3b23898bb..a15240c2d94d 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1066,14 +1066,17 @@ windir=C:\Windows ### Healthchecks -``` - --health-cmd Command to run to check health - --health-interval Time between running the check - --health-retries Consecutive failures needed to report unhealthy - --health-timeout Maximum time to allow one check to run - --health-start-period Start period for the container to initialize before starting health-retries countdown - --health-start-interval Time between running the check during the start period - --no-healthcheck Disable any container-specified HEALTHCHECK +The following flags for the `docker run` command let you control the parameters +for container healthchecks: + +```text +--health-cmd Command to run to check health +--health-interval Time between running the check +--health-retries Consecutive failures needed to report unhealthy +--health-timeout Maximum time to allow one check to run +--health-start-period Start period for the container to initialize before starting health-retries countdown +--health-start-interval Time between running the check during the start period +--no-healthcheck Disable any container-specified HEALTHCHECK ``` Example: From 52716c813bd96376a4324de09c3c903a2aca1852 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 14:11:38 +0100 Subject: [PATCH 20/24] docs: move --tmpfs to docker run reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 10 ++++++---- docs/reference/run.md | 15 --------------- 2 files changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index c0f19c2c7a04..092204f6684a 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -372,16 +372,18 @@ Under these conditions, you can pass any size less than the backing filesystem s For the `windowsfilter`, `btrfs`, and `zfs` storage drivers, you cannot pass a size less than the Default BaseFS Size. - ### Mount tmpfs (--tmpfs) +The `--tmpfs` flag lets you create a `tmpfs` mount. + +The options that you can pass to `--tmpfs` are identical to the Linux `mount -t +tmpfs -o` command. The following example mounts an empty `tmpfs` into the +container with the `rw`, `noexec`, `nosuid`, `size=65536k` options. + ```console $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image ``` -The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, -`noexec`, `nosuid`, `size=65536k` options. - ### Mount volume (-v) ```console diff --git a/docs/reference/run.md b/docs/reference/run.md index a15240c2d94d..3b6afa284857 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1130,21 +1130,6 @@ $ sleep 2; docker inspect --format='{{json .State.Health}}' test The health status is also displayed in the `docker ps` output. -### TMPFS (mount tmpfs filesystems) - -```console ---tmpfs=[]: Create a tmpfs mount with: container-dir[:], - where the options are identical to the Linux - 'mount -t tmpfs -o' command. -``` - -The example below mounts an empty tmpfs into the container with the `rw`, -`noexec`, `nosuid`, and `size=65536k` options. - -```console -$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image -``` - ### Filesystem mounts -v, --volume=[host-src:]container-dest[:]: Bind mount a volume. From 259aa9005916ccb2395e448ad2f309ca4dff527c Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 21:42:03 +0100 Subject: [PATCH 21/24] docs: rewrite section on filesystem mounts Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 122 ++++++++++++++++++++++++++---------------- 1 file changed, 76 insertions(+), 46 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 3b6afa284857..3db59d79973e 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -189,6 +189,82 @@ round-trip min/avg/max = 0.257/0.288/0.326 ms For more information about container networking, see [Networking overview](https://docs.docker.com/network/) +## Filesystem mounts + +By default, the data in a container is stored in an ephemeral, writable +container layer. Removing the container also removes its data. If you want to +use persistent data with containers, you can use filesystem mounts to store the +data persistently on the host system. Filesystem mounts can also let you share +data between containers and the host. + +Docker supports two main categories of mounts: + +- Volume mounts +- Bind mounts + +Volume mounts are great for persistently storing data for containers, and for +sharing data between containers. Bind mounts, on the other hand, are for +sharing data between a container and the host. + +You can add a filesystem mount to a container using the `--mount` flag for the +`docker run` command. + +The following sections show basic examples of how to create volumes and bind +mounts. For more in-depth examples and descriptions, refer to the section of +the [storage section](https://docs.docker.com/storage/) in the documentation. + +### Volume mounts + +To create a volume mount: + +```console +$ docker run --mount source=,target=[PATH] [IMAGE] [COMMAND...] +``` + +The `--mount` flag takes two parameters in this case: `source` and `target`. +The value for the `source` parameter is the name of the volume. The value of +`target` is the mount location of the volume inside the container. Once you've +created the volume, any data you write to the volume is persisted, even if you +stop or remove the container: + +```console +$ docker run --rm --mount source=my_volume,target=/foo busybox \ + echo "hello, volume!" > /foo/hello.txt +$ docker run --mount source=my_volume,target=/bar busybox + cat /bar/hello.txt +hello, volume! +``` + +The `target` must always be an absolute path, such as `/src/docs`. An absolute +path starts with a `/` (forward slash). Volume names must start with an +alphanumeric character, followed by `a-z0-9`, `_` (underscore), `.` (period) or +`-` (hyphen). + +### Bind mounts + +To create a bind mount: + +```console +$ docker run -it --mount type=bind,source=[PATH],target=[PATH] busybox +``` + +In this case, the `--mount` flag takes three parameters. A type (`bind`), and +two paths. The `source` path is a the location on the host that you want to +bind mount into the container. The `target` path is the mount destination +inside the container. + +Bind mounts are read-write by default, meaning that you can both read and write +files to and from the mounted location from the container. Changes that you +make, such as adding or editing files, are reflected on the host filesystem: + +```console +$ docker run -it --mount type=bind,source=.,target=/foo busybox +/ # echo "hello from container" > /foo/hello.txt +/ # exit +$ cat hello.txt +hello from container +``` + ## Exit status The exit code from `docker run` gives information about why the container @@ -900,7 +976,6 @@ override those defaults using flags for the `docker run` command. - [Expose ports](#exposed-ports) - [Environment variables](#environment-variables) - [Healthcheck](#healthchecks) -- [Filesystem mounts](#filesystem-mounts) - [User](#user) - [Working directory](#working-directory) @@ -1130,51 +1205,6 @@ $ sleep 2; docker inspect --format='{{json .State.Health}}' test The health status is also displayed in the `docker ps` output. -### Filesystem mounts - - -v, --volume=[host-src:]container-dest[:]: Bind mount a volume. - The comma-delimited `options` are [rw|ro], [z|Z], - [[r]shared|[r]slave|[r]private], and [nocopy]. - The 'host-src' is an absolute path or a name value. - - If neither 'rw' or 'ro' is specified then the volume is mounted in - read-write mode. - - The `nocopy` mode is used to disable automatically copying the requested volume - path in the container to the volume storage location. - For named volumes, `copy` is the default mode. Copy modes are not supported - for bind-mounted volumes. - - --volumes-from="": Mount all volumes from the given container(s) - -> **Note** -> -> When using systemd to manage the Docker daemon's start and stop, in the systemd -> unit file there is an option to control mount propagation for the Docker daemon -> itself, called `MountFlags`. The value of this setting may cause Docker to not -> see mount propagation changes made on the mount point. For example, if this value -> is `slave`, you may not be able to use the `shared` or `rshared` propagation on -> a volume. - -The volumes commands are complex enough to have their own documentation -in section [*Use volumes*](https://docs.docker.com/storage/volumes/). A developer can define -one or more `VOLUME`'s associated with an image, but only the operator -can give access from one container to another (or from a container to a -volume mounted on the host). - -The `container-dest` must always be an absolute path such as `/src/docs`. -The `host-src` can either be an absolute path or a `name` value. If you -supply an absolute path for the `host-src`, Docker bind-mounts to the path -you specify. If you supply a `name`, Docker creates a named volume by that `name`. - -A `name` value must start with an alphanumeric character, -followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen). -An absolute path starts with a `/` (forward slash). - -For example, you can specify either `/foo` or `foo` for a `host-src` value. -If you supply the `/foo` value, Docker creates a bind mount. If you supply -the `foo` specification, Docker creates a named volume. - ### User `root` (id = 0) is the default user within a container. The image developer can From 4a845145526a5e54825b99d061f90fcb1385ab68 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 27 Nov 2023 21:51:02 +0100 Subject: [PATCH 22/24] docs: rewrite section on setting user id Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 3db59d79973e..a9044bf38d15 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1207,21 +1207,25 @@ The health status is also displayed in the `docker ps` output. ### User -`root` (id = 0) is the default user within a container. The image developer can -create additional users. Those users are accessible by name. When passing a numeric -ID, the user does not have to exist in the container. +The default user within a container is `root` (id = 0). You can set a default +user to run the first process with the Dockerfile `USER` instruction. When +starting a container, you can override the `USER` instruction by passing the +`-u` option. -The developer can set a default user to run the first process with the -Dockerfile `USER` instruction. When starting a container, the operator can override -the `USER` instruction by passing the `-u` option. +```text +-u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command. +``` - -u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command. +The followings examples are all valid: - The followings examples are all valid: - --user=[ user | user:group | uid | uid:gid | user:gid | uid:group ] +```text +--user=[ user | user:group | uid | uid:gid | user:gid | uid:group ] +``` -> **Note:** if you pass a numeric uid, it must be in the range of 0-2147483647. -> If you pass a username, the user must exist in the container. +> **Note** +> +> If you pass a numeric user ID, it must be in the range of 0-2147483647. If +> you pass a username, the user must exist in the container. ### Working directory From 2e394eb5f48fc338749a27da6463cd82d4058617 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 28 Nov 2023 11:22:01 +0100 Subject: [PATCH 23/24] docs: rewrite section on working directory Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/run.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index a9044bf38d15..1dfb55936b5b 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1230,7 +1230,14 @@ The followings examples are all valid: ### Working directory The default working directory for running binaries within a container is the -root directory (`/`). It is possible to set a different working directory with the -Dockerfile `WORKDIR` command. The operator can override this with: +root directory (`/`). The default working directory of an image is set using +the Dockerfile `WORKDIR` command. You can override the default working +directory for an image using the `-w` (or `--workdir`) flag for the `docker +run` command: - -w="", --workdir="": Working directory inside the container +```text +$ docker run --rm -w /my/workdir alpine pwd +/my/workdir +``` + +If the directory doesn't already exist in the container, it will be created. From f8dd8f074def2448519dd7af3f4beabd6c09ae61 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 12 Dec 2023 22:36:26 +0100 Subject: [PATCH 24/24] docs: refresh --publish, add --publish-all Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/run.md | 43 +++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 092204f6684a..46e46db56148 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -90,7 +90,7 @@ Create and run a new container from an image | `--platform` | `string` | | Set platform if server is multi-platform capable | | [`--privileged`](#privileged) | | | Give extended privileges to this container | | [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host | -| `-P`, `--publish-all` | | | Publish all exposed ports to random ports | +| [`-P`](#publish-all), [`--publish-all`](#publish-all) | | | Publish all exposed ports to random ports | | [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | | `-q`, `--quiet` | | | Suppress the pull output | | [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only | @@ -483,26 +483,47 @@ $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh ### Publish or expose port (-p, --expose) ```console -$ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash +$ docker run -p 127.0.0.1:80:8080/tcp nginx:alpine ``` -This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host -machine. You can also specify `udp` and `sctp` ports. -The [Docker User Guide](https://docs.docker.com/network/links/) -explains in detail how to use ports in Docker. +This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the +host. You can also specify `udp` and `sctp` ports. The [Networking overview +page](https://docs.docker.com/network/) explains in detail how to publish ports +with Docker. -Note that ports which are not bound to the host (i.e., `-p 80:80` instead of -`-p 127.0.0.1:80:80`) are externally accessible. This also applies if -you configured UFW to block this specific port, as Docker manages its -own iptables rules. [Read more](https://docs.docker.com/network/iptables/) +> **Note** +> +> If you don't specify an IP address (i.e., `-p 80:80` instead of `-p +> 127.0.0.1:80:80`) when publishing a container's ports, Docker publishes the +> port on all interfaces (address `0.0.0.0`) by default. These ports are +> externally accessible. This also applies if you configured UFW to block this +> specific port, as Docker manages its own iptables rules. [Read +> more](https://docs.docker.com/network/packet-filtering-firewalls/) ```console -$ docker run --expose 80 ubuntu bash +$ docker run --expose 80 nginx:alpine ``` This exposes port `80` of the container without publishing the port to the host system's interfaces. +### Publish all exposed ports (-P, --publish-all) + +```console +$ docker run -P nginx:alpine +``` + +The `-P`, or `--publish-all`, flag publishes all the exposed ports to the host. +Docker binds each exposed port to a random port on the host. + +The `-P` flag only publishes port numbers that are explicitly flagged as +exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose` +flag for the `docker run` command. + +The range of ports are within an *ephemeral port range* defined by +`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to explicitly map a +single port or range of ports. + ### Set the pull policy (--pull) Use the `--pull` flag to set the image pull policy when creating (and running)