From 0d1582ea56effa5e3a70c325041035757e0e4a22 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] 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 247e60a17eff..9e396c76a7ce 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 020701fae0d0..9d34031d4767 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -51,78 +51,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