Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: move info about fg/bg flags to run reference 

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2023-10-20 16:38:17 +02:00
parent 2f48f41fcb
commit fad227d3fd
2 changed files with 270 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

364
docs/reference/commandline/run.md
View File

@ -9,111 +9,111 @@ Create and run a new container from an image
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:------------------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host:ip) | | [`--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) | | `--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 | | [`-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` | `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) | | `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) |
| `--cap-add` | `list` | | Add Linux capabilities | | `--cap-add` | `list` | | Add Linux capabilities |
| `--cap-drop` | `list` | | Drop Linux capabilities | | `--cap-drop` | `list` | | Drop Linux capabilities |
| `--cgroup-parent` | `string` | | Optional parent cgroup for the container | | `--cgroup-parent` | `string` | | Optional parent cgroup for the container |
| `--cgroupns` | `string` | | Cgroup namespace to use (host\|private)<br>'host': Run the container in the Docker host's cgroup namespace<br>'private': Run the container in its own private cgroup namespace<br>'': Use the cgroup namespace as configured by the<br> default-cgroupns-mode option on the daemon (default) | | `--cgroupns` | `string` | | Cgroup namespace to use (host\|private)<br>'host': Run the container in the Docker host's cgroup namespace<br>'private': Run the container in its own private cgroup namespace<br>'': Use the cgroup namespace as configured by the<br> default-cgroupns-mode option on the daemon (default) |
| [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file | | [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file |
| `--cpu-count` | `int64` | `0` | CPU count (Windows only) | | `--cpu-count` | `int64` | `0` | CPU count (Windows only) |
| `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | | `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) |
| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | | `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period |
| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | | `--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-period` | `int64` | `0` | Limit CPU real-time period in microseconds |
| `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | | `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds |
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | | `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
| `--cpus` | `decimal` | | Number of CPUs | | `--cpus` | `decimal` | | Number of CPUs |
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | | `--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) | | `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
| `-d`, `--detach` | | | Run container in background and print container ID | | [`-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 | | [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container |
| [`--device`](#device) | `list` | | Add a host device to the 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-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-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-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-bps` | `list` | | Limit write rate (bytes per second) to a device |
| `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | | `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device |
| `--disable-content-trust` | | | Skip image verification | | `--disable-content-trust` | | | Skip image verification |
| `--dns` | `list` | | Set custom DNS servers | | `--dns` | `list` | | Set custom DNS servers |
| `--dns-option` | `list` | | Set DNS options | | `--dns-option` | `list` | | Set DNS options |
| `--dns-search` | `list` | | Set custom DNS search domains | | `--dns-search` | `list` | | Set custom DNS search domains |
| `--domainname` | `string` | | Container NIS domain name | | `--domainname` | `string` | | Container NIS domain name |
| `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | | `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image |
| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | | [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables |
| `--env-file` | `list` | | Read in a file of environment variables | | `--env-file` | `list` | | Read in a file of environment variables |
| `--expose` | `list` | | Expose a port or a range of ports | | `--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) | | [`--gpus`](#gpus) | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) |
| `--group-add` | `list` | | Add additional groups to join | | `--group-add` | `list` | | Add additional groups to join |
| `--health-cmd` | `string` | | Command to run to check health | | `--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-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-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-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-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) | | `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) |
| `--help` | | | Print usage | | `--help` | | | Print usage |
| `-h`, `--hostname` | `string` | | Container host name | | `-h`, `--hostname` | `string` | | Container host name |
| `--init` | | | Run an init inside the container that forwards signals and reaps processes | | `--init` | | | Run an init inside the container that forwards signals and reaps processes |
| `-i`, `--interactive` | | | Keep STDIN open even if not attached | | [`-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-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) | | `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) |
| `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | | `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) |
| `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | | `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) |
| `--ipc` | `string` | | IPC mode to use | | `--ipc` | `string` | | IPC mode to use |
| [`--isolation`](#isolation) | `string` | | Container isolation technology | | [`--isolation`](#isolation) | `string` | | Container isolation technology |
| `--kernel-memory` | `bytes` | `0` | Kernel memory limit | | `--kernel-memory` | `bytes` | `0` | Kernel memory limit |
| [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container | | [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container |
| `--label-file` | `list` | | Read in a line delimited file of labels | | `--label-file` | `list` | | Read in a line delimited file of labels |
| `--link` | `list` | | Add link to another container | | `--link` | `list` | | Add link to another container |
| `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | | `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses |
| `--log-driver` | `string` | | Logging driver for the container | | `--log-driver` | `string` | | Logging driver for the container |
| `--log-opt` | `list` | | Log driver options | | `--log-opt` | `list` | | Log driver options |
| `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | | `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) |
| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | | [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit |
| `--memory-reservation` | `bytes` | `0` | Memory soft 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-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) | | `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) |
| [`--mount`](#mount) | `mount` | | Attach a filesystem mount to the container | | [`--mount`](#mount) | `mount` | | Attach a filesystem mount to the container |
| [`--name`](#name) | `string` | | Assign a name to the container | | [`--name`](#name) | `string` | | Assign a name to the container |
| [`--network`](#network) | `network` | | Connect a container to a network | | [`--network`](#network) | `network` | | Connect a container to a network |
| `--network-alias` | `list` | | Add network-scoped alias for the container | | `--network-alias` | `list` | | Add network-scoped alias for the container |
| `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | | `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK |
| `--oom-kill-disable` | | | Disable OOM Killer | | `--oom-kill-disable` | | | Disable OOM Killer |
| `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | | `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) |
| `--pid` | `string` | | PID namespace to use | | `--pid` | `string` | | PID namespace to use |
| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | | `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) |
| `--platform` | `string` | | Set platform if server is multi-platform capable | | `--platform` | `string` | | Set platform if server is multi-platform capable |
| [`--privileged`](#privileged) | | | Give extended privileges to this container | | [`--privileged`](#privileged) | | | Give extended privileges to this container |
| [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host | | [`-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 exposed ports to random ports |
| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | | [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) |
| `-q`, `--quiet` | | | Suppress the pull output | | `-q`, `--quiet` | | | Suppress the pull output |
| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only | | [`--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 | | [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits |
| `--rm` | | | Automatically remove the container when it exits | | `--rm` | | | Automatically remove the container when it exits |
| `--runtime` | `string` | | Runtime to use for this container | | `--runtime` | `string` | | Runtime to use for this container |
| [`--security-opt`](#security-opt) | `list` | | Security Options | | [`--security-opt`](#security-opt) | `list` | | Security Options |
| `--shm-size` | `bytes` | `0` | Size of /dev/shm | | `--shm-size` | `bytes` | `0` | Size of /dev/shm |
| `--sig-proxy` | | | Proxy received signals to the process | | `--sig-proxy` | | | Proxy received signals to the process |
| [`--stop-signal`](#stop-signal) | `string` | | Signal to stop the container | | [`--stop-signal`](#stop-signal) | `string` | | Signal to stop the container |
| [`--stop-timeout`](#stop-timeout) | `int` | `0` | Timeout (in seconds) to stop a 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 | | [`--storage-opt`](#storage-opt) | `list` | | Storage driver options for the container |
| [`--sysctl`](#sysctl) | `map` | `map[]` | Sysctl options | | [`--sysctl`](#sysctl) | `map` | `map[]` | Sysctl options |
| [`--tmpfs`](#tmpfs) | `list` | | Mount a tmpfs directory | | [`--tmpfs`](#tmpfs) | `list` | | Mount a tmpfs directory |
| `-t`, `--tty` | | | Allocate a pseudo-TTY | | [`-t`](#tty), [`--tty`](#tty) | | | Allocate a pseudo-TTY |
| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | | [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options |
| `-u`, `--user` | `string` | | Username or UID (format: <name\|uid>[:<group\|gid>]) | | `-u`, `--user` | `string` | | Username or UID (format: <name\|uid>[:<group\|gid>]) |
| `--userns` | `string` | | User namespace to use | | `--userns` | `string` | | User namespace to use |
| `--uts` | `string` | | UTS namespace to use | | `--uts` | `string` | | UTS namespace to use |
| [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume | | [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume |
| `--volume-driver` | `string` | | Optional volume driver for the container | | `--volume-driver` | `string` | | Optional volume driver for the container |
| [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) | | [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) |
| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | | [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
@ -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. The `Z` option tells Docker to label the content with a private unshared label.
Only the current container can use a private volume. Only the current container can use a private volume.
### <a name="attach"></a> Attach to STDIN/STDOUT/STDERR (-a, --attach) ### <a name="detach"></a> Detached mode (-d, --detach)
The `--attach` (or `-a`) flag tells `docker run` to bind to the container's The `--detach` (or `-d`) flag starts a container as a background process that
`STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output doesn't occupy your terminal window. By design, containers started in detached
and input as needed. 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.
Don't pass a `service x start` command to a detached container. For example,
this command attempts to start the `nginx` service.
```console ```console
$ echo "test" | docker run -i -a stdin ubuntu cat - $ docker run -d -p 80:80 my_image service nginx start
``` ```
This pipes data into a container and prints the container's ID by attaching This succeeds in starting the `nginx` service inside the container. However, it
only to the container's `STDIN`. 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 ```console
$ docker run -a stderr ubuntu echo test $ docker run -d -p 80:80 my_image nginx -g 'daemon off;'
``` ```
This isn't going to print anything to the console unless there's an error because output To do input/output with a detached container use network connections or shared
is only attached to the `STDERR` of the container. The container's logs volumes. These are required because the container is no longer listening to the
still store what's written to `STDERR` and `STDOUT`. command line where `docker run` was run.
```console
$ cat somefile | docker run -i -a stdin mybuilder dobuild
```
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).
### <a name="detach-keys"></a> Override the detach sequence (--detach-keys) ### <a name="detach-keys"></a> 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, > The `--device` option is only supported on process-isolated Windows containers,
> and produces an error if the container isolation is `hyperv`. > and produces an error if the container isolation is `hyperv`.
### <a name="attach"></a> 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).
### <a name="interactive"></a> 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
```
### <a name="tty"></a> 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.
### <a name="device-cgroup-rule"></a> Using dynamically created devices (--device-cgroup-rule) ### <a name="device-cgroup-rule"></a> Using dynamically created devices (--device-cgroup-rule)
Docker assigns devices available to a container at creation time. The Docker assigns devices available to a container at creation time. The

97
docs/reference/run.md
View File

@ -49,78 +49,49 @@ $ docker run -it IMAGE sh
> it. For more information about this configuration, refer to the Docker > it. For more information about this configuration, refer to the Docker
> installation documentation for your operating system. > 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 When you start a container, the container runs in the foreground by default.
run the container in the background in a "detached" mode or in the If you want to run the container in the background instead, you can use the
default foreground mode: `--detach` (or `-d`) flag. This starts the container without occupying your
terminal window.
-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:
```console ```console
$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash $ docker run -d <IMAGE>
``` ```
For interactive processes (like a shell), you must use `-i -t` together in While the container runs in the background, you can interact with the container
order to allocate a tty for the container process. `-i -t` is often written `-it` using other CLI commands. For example, `docker logs` lets you view the logs for
as you'll see in later examples. Specifying `-t` is forbidden when the client the container, and `docker attach` brings it to the foreground.
is receiving its standard input from a pipe, as in:
```console ```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** For more information about `docker run` flags related to foreground and
> background modes, see:
> 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 - [`docker run --detach`](commandline/run.md#detach): run container in background
> not terminate on `SIGINT` or `SIGTERM` unless it is coded to do so. - [`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 ## Container identification