From 18eb9f2e64d7393f318188e09c4a472cb5c97f54 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Sun, 3 Jan 2016 23:03:39 +0100 Subject: [PATCH] Implement configurable detach key Implement configurable detach keys (for `attach`, exec`, `run` and `start`) using the client-side configuration - Adds a `--detach-keys` flag to `attach`, `exec`, `run` and `start` commands. - Adds a new configuration field (in `~/.docker/config.json`) to configure the default escape keys for docker client. Signed-off-by: Vincent Demeester --- docs/reference/commandline/attach.md | 41 ++++++++++++++++++++++------ docs/reference/commandline/cli.md | 26 ++++++++++++++++-- docs/reference/commandline/exec.md | 1 + docs/reference/commandline/run.md | 1 + docs/reference/commandline/start.md | 1 + man/docker-attach.1.md | 37 ++++++++++++++++++++++--- man/docker-exec.1.md | 6 +++- man/docker-run.1.md | 10 +++++-- man/docker-start.1.md | 7 ++++- man/docker.1.md | 1 + 10 files changed, 112 insertions(+), 19 deletions(-) diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md index 5712c92f51..124474bef2 100644 --- a/docs/reference/commandline/attach.md +++ b/docs/reference/commandline/attach.md @@ -14,9 +14,10 @@ parent = "smn_cli" Attach to a running container - --help Print usage - --no-stdin Do not attach STDIN - --sig-proxy=true Proxy all received signals to the process + --detach-keys="" Set up escape key sequence + --help Print usage + --no-stdin Do not attach STDIN + --sig-proxy=true Proxy all received signals to the process The `docker attach` command allows you to attach to a running container using the container's ID or name, either to view its ongoing output or to control it @@ -24,11 +25,10 @@ interactively. You can attach to the same contained process multiple times simultaneously, screen sharing style, or quickly view the progress of your detached process. -You can detach from the container and leave it running with `CTRL-p CTRL-q` -(for a quiet exit) or with `CTRL-c` if `--sig-proxy` is false. - -If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to the -container. +To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the +container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to +the container. You can detach from a container and leave it running using the +using `CTRL-p CTRL-q` key sequence. > **Note:** > A process running as PID 1 inside a container is treated specially by @@ -39,6 +39,31 @@ container. 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`). + +## Override the detach sequence + +If you want, you can configure a override the Docker key sequence for detach. +This is is useful if the Docker default sequence conflicts with key squence you +use for other applications. There are two ways to defines a 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 ) +* `@` (ampersand) +* `[` (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 $ docker run -d --name topdemo ubuntu /usr/bin/top -b diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md index 608cb1275a..e3773f7d63 100644 --- a/docs/reference/commandline/cli.md +++ b/docs/reference/commandline/cli.md @@ -101,7 +101,26 @@ The property `psFormat` specifies the default format for `docker ps` output. When the `--format` flag is not provided with the `docker ps` command, Docker's client uses this property. If this property is not set, the client falls back to the default table format. For a list of supported formatting -directives, see the [**Formatting** section in the `docker ps` documentation](ps.md) +directives, see the +[**Formatting** section in the `docker ps` documentation](ps.md) + +Once attached to a container, users detach from it and leave it running using +the using `CTRL-p CTRL-q` key sequence. This detach key sequence is customizable +using the `detachKeys` property. Specify a `` value for the +property. 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 ) +* `@` (ampersand) +* `[` (left bracket) +* `\\` (two backward slashes) +* `_` (underscore) +* `^` (caret) + +Your customization applies to all containers started in with your Docker client. +Users can override your custom or the default key sequence on a per-container +basis. To do this, the user specifies the `--detach-keys` flag with the `docker +attach`, `docker exec`, `docker run` or `docker start` command. The property `imagesFormat` specifies the default format for `docker images` output. When the `--format` flag is not provided with the `docker images` command, @@ -115,8 +134,9 @@ Following is a sample `config.json` file: "HttpHeaders": { "MyHeader": "MyValue" }, - "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}" - "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}" + "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}", + "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}", + "detachKeys": "ctrl-e,e" } ### Notary diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md index 971a2f2d67..80796a59c9 100644 --- a/docs/reference/commandline/exec.md +++ b/docs/reference/commandline/exec.md @@ -15,6 +15,7 @@ parent = "smn_cli" Run a command in a running container -d, --detach Detached mode: run command in the background + --detach-keys Specify the escape key sequence used to detach a container --help Print usage -i, --interactive Keep STDIN open even if not attached --privileged Give extended Linux capabilities to the command diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index c42ca23e58..3ea6ae5415 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -28,6 +28,7 @@ parent = "smn_cli" --cpuset-cpus="" CPUs in which to allow execution (0-3, 0,1) --cpuset-mems="" Memory nodes (MEMs) in which to allow execution (0-3, 0,1) -d, --detach Run container in background and print container ID + --detach-keys Specify the escape key sequence used to detach a container --device=[] Add a host device to the container --device-read-bps=[] Limit read rate (bytes per second) from a device (e.g., --device-read-bps=/dev/sda:1mb) --device-read-iops=[] Limit read rate (IO per second) from a device (e.g., --device-read-iops=/dev/sda:1000) diff --git a/docs/reference/commandline/start.md b/docs/reference/commandline/start.md index 6e1b1d67ba..156a2aae08 100644 --- a/docs/reference/commandline/start.md +++ b/docs/reference/commandline/start.md @@ -15,5 +15,6 @@ parent = "smn_cli" Start one or more containers -a, --attach Attach STDOUT/STDERR and forward signals + --detach-keys Specify the escape key sequence used to detach a container --help Print usage -i, --interactive Attach container's STDIN diff --git a/man/docker-attach.1.md b/man/docker-attach.1.md index 260593201f..adecceb37f 100644 --- a/man/docker-attach.1.md +++ b/man/docker-attach.1.md @@ -6,6 +6,7 @@ docker-attach - Attach to a running container # SYNOPSIS **docker attach** +[**--detach-keys**[=*[]*]] [**--help**] [**--no-stdin**] [**--sig-proxy**[=*true*]] @@ -18,15 +19,19 @@ interactively. You can attach to the same contained process multiple times simultaneously, screen sharing style, or quickly view the progress of your detached process. -You can detach from the container (and leave it running) with `CTRL-p CTRL-q` -(for a quiet exit) or `CTRL-c` which will send a `SIGKILL` to the container. -When you are attached to a container, and exit its main process, the process's -exit code will be returned to the client. +To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the +container. You can detach from the container (and leave it running) using a +configurable key sequence. The default sequence is `CTRL-p CTRL-q`. You +configure the key sequence using the **--detach-keys** option or a configuration +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 `-t`). # OPTIONS +**--detach-keys**="" + Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-` where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. + **--help** Print usage statement @@ -36,6 +41,30 @@ attaching to a tty-enabled container (i.e.: launched with `-t`). **--sig-proxy**=*true*|*false* Proxy all received signals to the process (non-TTY mode only). SIGCHLD, SIGKILL, and SIGSTOP are not proxied. The default is *true*. +# Override the detach sequence + +If you want, you can configure a override the Docker key sequence for detach. +This is is useful if the Docker default sequence conflicts with key squence you +use for other applications. There are two ways to defines a 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 ) +* `@` (ampersand) +* `[` (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 **docker(1)**. + # EXAMPLES ## Attaching to a container diff --git a/man/docker-exec.1.md b/man/docker-exec.1.md index 388fe81b2c..49f6dbc286 100644 --- a/man/docker-exec.1.md +++ b/man/docker-exec.1.md @@ -7,6 +7,7 @@ docker-exec - Run a command in a running container # SYNOPSIS **docker exec** [**-d**|**--detach**] +[**--detach-keys**[=*[]*]] [**--help**] [**-i**|**--interactive**] [**--privileged**] @@ -26,7 +27,10 @@ container is unpaused, and then run # OPTIONS **-d**, **--detach**=*true*|*false* - Detached mode: run command in the background. The default is *false*. + Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-` where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. + +**--detach-keys**="" + Define the key sequence which detaches the container. **--help** Print usage statement diff --git a/man/docker-run.1.md b/man/docker-run.1.md index 6d787295ec..71790d0aa6 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -20,6 +20,7 @@ docker-run - Run a command in a new container [**--cpuset-cpus**[=*CPUSET-CPUS*]] [**--cpuset-mems**[=*CPUSET-MEMS*]] [**-d**|**--detach**] +[**--detach-keys**[=*[]*]] [**--device**[=*[]*]] [**--device-read-bps**[=*[]*]] [**--device-read-iops**[=*[]*]] @@ -190,8 +191,13 @@ the other shell to view a list of the running containers. You can reattach to a detached container with **docker attach**. If you choose to run a container in the detached mode, then you cannot use the **-rm** option. - When attached in the tty mode, you can detach from a running container without -stopping the process by pressing the keys CTRL-P CTRL-Q. + When attached in the tty mode, you can detach from the container (and leave it +running) using a configurable key sequence. The default sequence is `CTRL-p CTRL-q`. +You configure the key sequence using the **--detach-keys** option or a configuration file. +See **config-json(5)** for documentation on using a configuration file. + +**--detach-keys**="" + Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-` where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. **--device**=[] Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) diff --git a/man/docker-start.1.md b/man/docker-start.1.md index 678f687f86..c00b0a1668 100644 --- a/man/docker-start.1.md +++ b/man/docker-start.1.md @@ -7,6 +7,7 @@ docker-start - Start one or more containers # SYNOPSIS **docker start** [**-a**|**--attach**] +[**--detach-keys**[=*[]*]] [**--help**] [**-i**|**--interactive**] CONTAINER [CONTAINER...] @@ -17,7 +18,11 @@ Start one or more containers. # OPTIONS **-a**, **--attach**=*true*|*false* - Attach container's STDOUT and STDERR and forward all signals to the process. The default is *false*. + Attach container's STDOUT and STDERR and forward all signals to the + process. The default is *false*. + +**--detach-keys**="" + Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-` where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. **--help** Print usage statement diff --git a/man/docker.1.md b/man/docker.1.md index fc7cd58a65..83e57affa2 100644 --- a/man/docker.1.md +++ b/man/docker.1.md @@ -223,6 +223,7 @@ inside it) Block until a container stops, then print its exit code See **docker-wait(1)** for full documentation on the **wait** command. + # EXEC DRIVER OPTIONS Use the **--exec-opt** flags to specify options to the execution driver. The only