docker/cli
1
0
Fork 0
mirror of https://github.com/docker/cli.git synced 2025-07-30 17:03:07 +03:00
Code Activity

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

Browse Source 
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
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
| 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)<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 |
| `--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: <name\|uid>[:<group\|gid>]) |
| `--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)<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 |
| `--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: <name\|uid>[:<group\|gid>]) |
| `--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 |
<!---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.
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
`STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output
and input as needed.
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.
Don't pass a `service x start` command to a detached container. For example,
this command attempts to start the `nginx` service.
```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
only to the container's `STDIN`.
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
$ 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
is only attached to the `STDERR` of the container. The container's logs
still store what's written to `STDERR` and `STDOUT`.
```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).
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.
### <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,
> 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)
Docker assigns devices available to a container at creation time. The