mirror of https://github.com/docker/cli.git
doc/reference: update attach reference
Some touch-ups in the attach reference and man-page;
- remove uses of old images (ubuntu 14.04)
- adds some more wording about `-i` and `-t` to use the detach sequence.
- use `--filter` instead of `grep` to list the container, to make the
example more portable.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit 74086bc93b
)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
parent
22bbb73a12
commit
ba33d2f29a
|
@ -45,12 +45,12 @@ a container and leave it running using the `CTRL-p CTRL-q` key sequence.
|
||||||
> so.
|
> so.
|
||||||
|
|
||||||
It is forbidden to redirect the standard input of a `docker attach` command
|
It is forbidden to redirect the standard input of a `docker attach` command
|
||||||
while attaching to a tty-enabled container (i.e.: launched with `-t`).
|
while attaching to a TTY-enabled container (using the `-i` and `-t` options).
|
||||||
|
|
||||||
While a client is connected to container's stdio using `docker attach`, Docker
|
While a client is connected to container's `stdio` using `docker attach`, Docker
|
||||||
uses a ~1MB memory buffer to maximize the throughput of the application. If
|
uses a ~1MB memory buffer to maximize the throughput of the application.
|
||||||
this buffer is filled, the speed of the API connection will start to have an
|
Once this buffer is full, the speed of the API connection is affected, and so
|
||||||
effect on the process output writing speed. This is similar to other
|
this impacts the output process' writing speed. This is similar to other
|
||||||
applications like SSH. Because of this, it is not recommended to run
|
applications like SSH. Because of this, it is not recommended to run
|
||||||
performance critical applications that generate a lot of output in the
|
performance critical applications that generate a lot of output in the
|
||||||
foreground over a slow client connection. Instead, users should use the
|
foreground over a slow client connection. Instead, users should use the
|
||||||
|
@ -84,45 +84,68 @@ containers, see [**Configuration file** section](cli.md#configuration-files).
|
||||||
|
|
||||||
### Attach to and detach from a running container
|
### Attach to and detach from a running container
|
||||||
|
|
||||||
|
The following example starts an ubuntu container running `top` in detached mode,
|
||||||
|
then attaches to the container;
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ docker run -d --name topdemo ubuntu /usr/bin/top -b
|
$ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b
|
||||||
|
|
||||||
$ docker attach topdemo
|
$ docker attach topdemo
|
||||||
|
|
||||||
top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05
|
top - 12:27:44 up 3 days, 21:54, 0 users, load average: 0.00, 0.00, 0.00
|
||||||
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
||||||
Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st
|
%Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.8 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st
|
||||||
Mem: 373572k total, 355560k used, 18012k free, 27872k buffers
|
MiB Mem : 3934.3 total, 770.1 free, 674.2 used, 2490.1 buff/cache
|
||||||
Swap: 786428k total, 0k used, 786428k free, 221740k cached
|
MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2814.0 avail Mem
|
||||||
|
|
||||||
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
|
||||||
1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top
|
|
||||||
|
|
||||||
top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05
|
|
||||||
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
|
||||||
Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st
|
|
||||||
Mem: 373572k total, 355244k used, 18328k free, 27872k buffers
|
|
||||||
Swap: 786428k total, 0k used, 786428k free, 221776k cached
|
|
||||||
|
|
||||||
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
||||||
1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top
|
1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top
|
||||||
|
```
|
||||||
|
|
||||||
|
As the container was started without the `-i`, and `-t` options, signals are
|
||||||
|
forwarded to the attached process, which means that the default `CTRL-p CTRL-q`
|
||||||
|
detach key sequence produces no effect, but pressing `CTRL-c` terminates the
|
||||||
|
container:
|
||||||
|
|
||||||
top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05
|
```console
|
||||||
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
<...>
|
||||||
Cpu(s): 0.2%us, 0.3%sy, 0.0%ni, 99.5%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st
|
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
||||||
Mem: 373572k total, 355780k used, 17792k free, 27880k buffers
|
1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top^P^Q
|
||||||
Swap: 786428k total, 0k used, 786428k free, 221776k cached
|
^C
|
||||||
|
|
||||||
|
$ docker ps -a --filter name=topdemo
|
||||||
|
|
||||||
|
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||||
|
4cf0d0ebb079 ubuntu:22.04 "/usr/bin/top -b" About a minute ago Exited (0) About a minute ago topdemo
|
||||||
|
```
|
||||||
|
|
||||||
|
Repeating the example above, but this time with the `-i` and `-t` options set;
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b
|
||||||
|
```
|
||||||
|
|
||||||
|
Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read
|
||||||
|
escape sequence"), the Docker CLI is handling the detach sequence, and the
|
||||||
|
`attach` command is detached from the container. Checking the container's status
|
||||||
|
with `docker ps` shows that the container is still running in the background:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ docker attach topdemo2
|
||||||
|
|
||||||
|
top - 12:44:32 up 3 days, 22:11, 0 users, load average: 0.00, 0.00, 0.00
|
||||||
|
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
||||||
|
%Cpu(s): 50.0 us, 0.0 sy, 0.0 ni, 50.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st
|
||||||
|
MiB Mem : 3934.3 total, 770.6 free, 672.4 used, 2491.4 buff/cache
|
||||||
|
MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2815.8 avail Mem
|
||||||
|
|
||||||
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
||||||
1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top
|
1 root 20 0 7180 2776 2452 R 0.0 0.1 0:00.02 topread escape sequence
|
||||||
^C$
|
|
||||||
|
|
||||||
$ echo $?
|
$ docker ps -a --filter name=topdemo2
|
||||||
0
|
|
||||||
$ docker ps -a | grep topdemo
|
|
||||||
|
|
||||||
7998ac8581f9 ubuntu:14.04 "/usr/bin/top -b" 38 seconds ago Exited (0) 21 seconds ago topdemo
|
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||||
|
b1661dce0fc2 ubuntu:22.04 "/usr/bin/top -b" 2 minutes ago Up 2 minutes topdemo2
|
||||||
```
|
```
|
||||||
|
|
||||||
### Get the exit code of the container's command
|
### Get the exit code of the container's command
|
||||||
|
@ -131,18 +154,17 @@ And in this second example, you can see the exit code returned by the `bash`
|
||||||
process is returned by the `docker attach` command to its caller too:
|
process is returned by the `docker attach` command to its caller too:
|
||||||
|
|
||||||
```console
|
```console
|
||||||
$ docker run --name test -d -it debian
|
$ docker run --name test -dit alpine
|
||||||
275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab
|
275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab
|
||||||
|
|
||||||
$ docker attach test
|
$ docker attach test
|
||||||
root@f38c87f2a42d:/# exit 13
|
/# exit 13
|
||||||
|
|
||||||
exit
|
|
||||||
|
|
||||||
$ echo $?
|
$ echo $?
|
||||||
13
|
13
|
||||||
|
|
||||||
$ docker ps -a | grep test
|
$ docker ps -a --filter name=test
|
||||||
|
|
||||||
275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test
|
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||||
|
a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test
|
||||||
```
|
```
|
||||||
|
|
|
@ -11,7 +11,7 @@ configure the key sequence using the **--detach-keys** option or a configuration
|
||||||
file. See **config-json(5)** for documentation on using a configuration file.
|
file. See **config-json(5)** for documentation on using a configuration file.
|
||||||
|
|
||||||
It is forbidden to redirect the standard input of a **docker attach** command while
|
It is forbidden to redirect the standard input of a **docker attach** command while
|
||||||
attaching to a tty-enabled container (i.e.: launched with `-t`).
|
attaching to a TTY-enabled container (i.e., launched with `-i` and `-t`).
|
||||||
|
|
||||||
# Override the detach sequence
|
# Override the detach sequence
|
||||||
|
|
||||||
|
@ -41,12 +41,12 @@ containers, see **docker(1)**.
|
||||||
|
|
||||||
## Attaching to a container
|
## Attaching to a container
|
||||||
|
|
||||||
In this example the top command is run inside a container, from an image called
|
In this example the top command is run inside a container from an ubuntu image,
|
||||||
fedora, in detached mode. The ID from the container is passed into the **docker
|
in detached mode, then attaches to it, and then terminates the container
|
||||||
attach** command:
|
with `CTRL-c`:
|
||||||
|
|
||||||
$ ID=$(sudo docker run -d ubuntu:20.04 /usr/bin/top -b)
|
$ docker run -d --name topdemo ubuntu:20.04 /usr/bin/top -b
|
||||||
$ sudo docker attach $ID
|
$ docker attach topdemo
|
||||||
top - 00:07:01 up 4:54, 0 users, load average: 0.83, 0.91, 0.82
|
top - 00:07:01 up 4:54, 0 users, load average: 0.83, 0.91, 0.82
|
||||||
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
||||||
%Cpu(s): 2.3 us, 1.6 sy, 0.0 ni, 95.9 id, 0.0 wa, 0.1 hi, 0.1 si, 0.0 st
|
%Cpu(s): 2.3 us, 1.6 sy, 0.0 ni, 95.9 id, 0.0 wa, 0.1 hi, 0.1 si, 0.0 st
|
||||||
|
@ -55,12 +55,4 @@ attach** command:
|
||||||
|
|
||||||
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
||||||
1 root 20 0 5976 3256 2828 R 0.0 0.0 0:00.04 top
|
1 root 20 0 5976 3256 2828 R 0.0 0.0 0:00.04 top
|
||||||
|
^C
|
||||||
top - 00:07:04 up 4:54, 0 users, load average: 0.76, 0.89, 0.81
|
|
||||||
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie
|
|
||||||
%Cpu(s): 2.0 us, 1.4 sy, 0.0 ni, 96.5 id, 0.0 wa, 0.1 hi, 0.0 si, 0.0 st
|
|
||||||
MiB Mem : 15846.2 total, 5727.5 free, 2594.4 used, 7524.3 buff/cache
|
|
||||||
MiB Swap: 16384.0 total, 16384.0 free, 0.0 used. 12095.6 avail Mem
|
|
||||||
|
|
||||||
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
|
|
||||||
1 root 20 0 5976 3256 2828 R 0.0 0.0 0:00.04 top
|
|
||||||
|
|
Loading…
Reference in New Issue