Merge pull request #15666 from vdemeester/3519-configurable-escape

Implement configurable escape key for attach/exec Upstream-commit: db738dd77f699e93f976441d5fc11ab48a2d6c68 Component: engine
2016-01-04 00:49:07 +01:00
parent 90d9d53d0f 5582f5eb83
commit 1162375d21
27 changed files with 583 additions and 61 deletions
--- a/components/engine/docs/reference/api/docker_remote_api_v1.22.md
+++ b/components/engine/docs/reference/api/docker_remote_api_v1.22.md
@ -862,10 +862,9 @@ This endpoint returns a live stream of a container's resource usage statistics.
               "total_usage" : 36488948,
               "usage_in_kernelmode" : 20000000
            },
-            "system_cpu_usage" : 20091722000000000,
+            "system_cpu_usage" : 20091722000000000,
            "throttling_data" : {}
-         }
-      }
+         }      }

 Query Parameters:

@ -922,6 +921,12 @@ Start the container `id`

    HTTP/1.1 204 No Content

+Query Parameters:
+
+-   **detacheys** – Override the key sequence for detaching a
+        container. Format is a single character `[a-Z]` or `ctrl-<value>`
+        where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
+
 Status Codes:

 -   **204** – no error
@ -1133,6 +1138,9 @@ Attach to the container `id`

 Query Parameters:

+-   **detacheys** – Override the key sequence for detaching a
+        container. Format is a single character `[a-Z]` or `ctrl-<value>`
+        where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
 -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
 -   **stream** – 1/True/true or 0/False/false, return stream.
        Default `false`.
@ -1213,6 +1221,9 @@ Implements websocket protocol handshake according to [RFC 6455](http://tools.iet

 Query Parameters:

+-   **detacheys** – Override the key sequence for detaching a
+        container. Format is a single character `[a-Z]` or `ctrl-<value>`
+        where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
 -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
 -   **stream** – 1/True/true or 0/False/false, return stream.
        Default `false`.
@ -2420,6 +2431,7 @@ Sets up an exec instance in a running container `id`
       "AttachStdin": false,
       "AttachStdout": true,
       "AttachStderr": true,
+       "DetachKeys": "ctrl-p,ctrl-q",
       "Tty": false,
       "Cmd": [
                     "date"
@ -2441,6 +2453,9 @@ Json Parameters:
 -   **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command.
 -   **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command.
 -   **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command.
+-   **Detacheys** – Override the key sequence for detaching a
+        container. Format is a single character `[a-Z]` or `ctrl-<value>`
+        where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
 -   **Tty** - Boolean value to allocate a pseudo-TTY.
 -   **Cmd** - Command to run specified as a string or an array of strings.

--- a/components/engine/docs/reference/commandline/attach.md
+++ b/components/engine/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="<sequence>"       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="<sequence>"` flag with the `docker attach` command. The format of
+the `<sequence>` 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
--- a/components/engine/docs/reference/commandline/cli.md
+++ b/components/engine/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 `<sequence>` value for the
+property. The format of the `<sequence>` 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
--- a/components/engine/docs/reference/commandline/exec.md
+++ b/components/engine/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
--- a/components/engine/docs/reference/commandline/run.md
+++ b/components/engine/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)
--- a/components/engine/docs/reference/commandline/start.md
+++ b/components/engine/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