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

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
> 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 <IMAGE>
```
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