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

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>
This commit is contained in:
Sebastiaan van Stijn 2022-06-06 14:57:50 +02:00
parent 82805ad71f
commit 74086bc93b
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
2 changed files with 66 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/reference/commandline/attach.md
View File

@ -48,12 +48,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
@ -87,45 +87,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 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 1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top
```
top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 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:
```console
<...>
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top^P^Q
^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 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 %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
Mem: 373572k total, 355244k used, 18328k free, 27872k buffers MiB Mem : 3934.3 total, 770.6 free, 672.4 used, 2491.4 buff/cache
Swap: 786428k total, 0k used, 786428k free, 221776k cached 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
$ docker ps -a --filter name=topdemo2
top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie b1661dce0fc2 ubuntu:22.04 "/usr/bin/top -b" 2 minutes ago Up 2 minutes topdemo2
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
Mem: 373572k total, 355780k used, 17792k free, 27880k buffers
Swap: 786428k total, 0k used, 786428k free, 221776k cached
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
^C$
$ echo $?
0
$ docker ps -a | grep topdemo
7998ac8581f9 ubuntu:14.04 "/usr/bin/top -b" 38 seconds ago Exited (0) 21 seconds ago topdemo
``` ```
### Get the exit code of the container's command ### Get the exit code of the container's command
@ -134,18 +157,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
``` ```

22
man/src/container/attach.md
View File

@ -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