From f118c05e879001edd9bdf2cacc179bbaaffc12a9 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 8 Jun 2023 14:33:18 +0200 Subject: [PATCH 1/2] docs: move "--detach-keys" example to examples section Also adds a named anchor, so that the section gets linked from the options table. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit c17b0df2a57dd885a11ffed22583084c91d5a719) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/attach.md | 58 ++++++++++++++-------------- man/src/container/attach.md | 43 +++++++++++---------- 2 files changed, 51 insertions(+), 50 deletions(-) diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md index 370cc7d86f..e3b0e338a6 100644 --- a/docs/reference/commandline/attach.md +++ b/docs/reference/commandline/attach.md @@ -9,11 +9,11 @@ Attach local standard input, output, and error streams to a running container ### Options -| Name | Type | Default | Description | -|:----------------|:---------|:--------|:----------------------------------------------------| -| `--detach-keys` | `string` | | Override the key sequence for detaching a container | -| `--no-stdin` | | | Do not attach STDIN | -| `--sig-proxy` | | | Proxy all received signals to the process | +| Name | Type | Default | Description | +|:--------------------------------|:---------|:--------|:----------------------------------------------------| +| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | +| `--no-stdin` | | | Do not attach STDIN | +| `--sig-proxy` | | | Proxy all received signals to the process | @@ -56,30 +56,6 @@ performance critical applications that generate a lot of output in the foreground over a slow client connection. Instead, users should use the `docker logs` command to get access to the logs. -### Override the detach sequence - -If you want, you can configure an override the Docker key sequence for detach. -This is useful if the Docker default sequence conflicts with key sequence you -use for other applications. There are two ways to define your own detach key -sequence, as a per-container override or as a configuration property on your -entire configuration. - -To override the sequence for an individual container, use the -`--detach-keys=""` flag with the `docker attach` command. The format of -the `` is either a letter [a-Z], or the `ctrl-` combined with any of -the following: - -* `a-z` (a single lowercase alpha character ) -* `@` (at sign) -* `[` (left bracket) -* `\\` (two backward slashes) -* `_` (underscore) -* `^` (caret) - -These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key -sequences. To configure a different configuration default key sequence for all -containers, see [**Configuration file** section](cli.md#configuration-files). - ## Examples ### Attach to and detach from a running container @@ -168,3 +144,27 @@ $ docker ps -a --filter name=test CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test ``` + +### Override the detach sequence (--detach-keys) + +Use the `--detach-keys` option to override the Docker key sequence for detach. +This is useful if the Docker default sequence conflicts with key sequence you +use for other applications. There are two ways to define your own detach key +sequence, as a per-container override or as a configuration property on your +entire configuration. + +To override the sequence for an individual container, use the +`--detach-keys=""` flag with the `docker attach` command. The format of +the `` is either a letter [a-Z], or the `ctrl-` combined with any of +the following: + +* `a-z` (a single lowercase alpha character ) +* `@` (at sign) +* `[` (left bracket) +* `\\` (two backward slashes) +* `_` (underscore) +* `^` (caret) + +These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key +sequences. To configure a different configuration default key sequence for all +containers, see [**Configuration file** section](cli.md#configuration-files). diff --git a/man/src/container/attach.md b/man/src/container/attach.md index eb850fd068..acd5376d1c 100644 --- a/man/src/container/attach.md +++ b/man/src/container/attach.md @@ -13,9 +13,29 @@ 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 attaching to a TTY-enabled container (i.e., launched with `-i` and `-t`). -# Override the detach sequence +# EXAMPLES -If you want, you can configure an override the Docker key sequence for detach. +## Attaching to a container + +In this example the top command is run inside a container from an ubuntu image, +in detached mode, then attaches to it, and then terminates the container +with `CTRL-c`: + + $ docker run -d --name topdemo ubuntu:20.04 /usr/bin/top -b + $ docker attach topdemo + 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 + %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 + MiB Mem : 15846.2 total, 5729.2 free, 2592.5 used, 7524.4 buff/cache + MiB Swap: 16384.0 total, 16384.0 free, 0.0 used. 12097.3 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 + ^C + +## Override the detach sequence + +Use the **--detach-keys** option to override the Docker key sequence for detach. This is useful if the Docker default sequence conflicts with key sequence you use for other applications. There are two ways to define your own detach key sequence, as a per-container override or as a configuration property on your @@ -37,22 +57,3 @@ These **a**, **ctrl-a**, **X**, or **ctrl-\\** values are all examples of valid sequences. To configure a different configuration default key sequence for all containers, see **docker(1)**. -# EXAMPLES - -## Attaching to a container - -In this example the top command is run inside a container from an ubuntu image, -in detached mode, then attaches to it, and then terminates the container -with `CTRL-c`: - - $ docker run -d --name topdemo ubuntu:20.04 /usr/bin/top -b - $ docker attach topdemo - 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 - %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 - MiB Mem : 15846.2 total, 5729.2 free, 2592.5 used, 7524.4 buff/cache - MiB Swap: 16384.0 total, 16384.0 free, 0.0 used. 12097.3 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 - ^C From 11af1189d70ab6c97434517e4044b917a184813c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 8 Jun 2023 14:37:21 +0200 Subject: [PATCH 2/2] docs: add "--detach-keys" example to docker run reference This is a copy of the section we have on the "docker attach" reference page. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 47951ff446d849d28093797482ec3206fc9074e8) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/run.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index e9afe51371..5df7a2b24e 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -32,7 +32,7 @@ Create and run a new container from an image | `--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` | `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-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 | @@ -569,6 +569,30 @@ retrieve the container's ID once the container has finished running. See also [the `docker cp` command](cp.md). +### Override the detach sequence (--detach-keys) + +Use the `--detach-keys` option to override the Docker key sequence for detach. +This is useful if the Docker default sequence conflicts with key sequence you +use for other applications. There are two ways to define your own detach key +sequence, as a per-container override or as a configuration property on your +entire configuration. + +To override the sequence for an individual container, use the +`--detach-keys=""` flag with the `docker attach` command. The format of +the `` is either a letter [a-Z], or the `ctrl-` combined with any of +the following: + +* `a-z` (a single lowercase alpha character ) +* `@` (at sign) +* `[` (left bracket) +* `\\` (two backward slashes) +* `_` (underscore) +* `^` (caret) + +These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key +sequences. To configure a different configuration default key sequence for all +containers, see [**Configuration file** section](cli.md#configuration-files). + ### Add host device to container (--device) ```console