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

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

@ -10,7 +10,7 @@ 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 |
@ -31,7 +31,7 @@ Create and run a new container from an image
| `--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 |
@ -59,7 +59,7 @@ Create and run a new container from an image
| `--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) |
@ -105,7 +105,7 @@ Create and run a new container from an image
| [`--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 |
@ -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