docker change Ctrl+p to something else?

Customizing Docker's Detach Key Sequence (Ctrl+p, Ctrl+q)

Learn how to change the default Ctrl+p, Ctrl+q key sequence used to detach from a Docker container's console, preventing conflicts with terminal shortcuts.

When working with Docker containers interactively, you often attach to their console using docker attach or docker exec -it. By default, Docker uses the key sequence Ctrl+p followed by Ctrl+q to detach from the container without stopping it. This allows the container to continue running in the background while you regain control of your terminal.

However, this default sequence can sometimes conflict with other terminal shortcuts or personal preferences. For instance, Ctrl+p is commonly used for 'previous command' in many shells. This article will guide you through the process of customizing this detach key sequence to something more convenient for your workflow.

Understanding the Detach Key Sequence

The Ctrl+p, Ctrl+q sequence is a special escape sequence interpreted by the Docker client, not the container itself. When you press Ctrl+p, Docker enters a 'prefix' state, waiting for the next key press. If the next key is Ctrl+q, it triggers the detach action. If it's another key, Docker typically sends that key to the container and exits the prefix state. This mechanism is designed to avoid accidental detaching.

While this default is generally robust, conflicts can arise, especially if you use terminal multiplexers like tmux or screen, which also rely on similar Ctrl key combinations for their own commands. Changing Docker's detach keys can prevent these conflicts and improve your interactive container experience.

flowchart TD
    A[User attaches to container] --> B{Interactive session starts}
    B --> C{User presses Ctrl+p}
    C --> D{Docker enters 'prefix' state}
    D --> E{User presses Ctrl+q}
    E --> F[Docker detaches from container]
    D --> G{User presses other key}
    G --> H[Key sent to container, prefix state exits]
    F --> I[Container continues running in background]

Flowchart of Docker's default detach sequence

Methods to Change the Detach Key Sequence

There are two primary ways to modify Docker's detach key sequence: temporarily via command-line flags or permanently via the Docker client configuration file.

Method 1: Command-Line Flag (Temporary)

You can specify a custom detach key sequence directly when running docker attach or docker exec using the --detach-keys flag. This is useful for one-off situations or testing new key combinations without altering your global configuration.

docker attach --detach-keys="ctrl-e,e" my_container
docker exec -it --detach-keys="ctrl-e,e" my_container bash

Using --detach-keys with docker attach and docker exec

In the example above, "ctrl-e,e" sets the new detach sequence to Ctrl+e followed by e. You can use various key combinations. Common key names include ctrl-a, ctrl-b, ctrl-c, ctrl-d, ctrl-e, ctrl-f, ctrl-g, ctrl-h, ctrl-i, ctrl-j, ctrl-k, ctrl-l, ctrl-m, ctrl-n, ctrl-o, ctrl-p, ctrl-q, ctrl-r, ctrl-s, ctrl-t, ctrl-u, ctrl-v, ctrl-w, ctrl-x, ctrl-y, ctrl-z, \, ], ^, _, space, enter, tab, backspace, delete, escape, insert, home, end, pageup, pagedown, up, down, left, right, f1 through f12.

Method 2: Docker Client Configuration File (Permanent)

For a permanent change that applies to all your Docker commands, you can modify the Docker client configuration file, typically located at ~/.docker/config.json.

1. Locate or Create config.json

Open your terminal and navigate to your home directory. The configuration file is usually at ~/.docker/config.json. If the .docker directory or the config.json file doesn't exist, you can create them.

2. Edit config.json

Open config.json with your preferred text editor. Add or modify the detachKeys field. The value should be a string representing your desired key sequence, similar to the --detach-keys flag.

3. Example config.json

Here's how your config.json might look after adding the detachKeys field. This example sets the detach sequence to Ctrl+\.

{
  "auths": {
    "https://index.docker.io/v1/": {}
  },
  "detachKeys": "ctrl-\\"
}

Example ~/.docker/config.json with custom detach keys

After saving the config.json file, the new detach key sequence will be active for all subsequent docker attach and docker exec -it commands without needing to specify the --detach-keys flag.

Testing Your New Detach Key Sequence

To verify your changes, start a simple container and attach to it. Then, try your new detach sequence.

docker run -it --name my_test_container alpine sh
# Inside the container, press your new detach sequence (e.g., Ctrl+\)
# You should be returned to your host terminal, and the container should still be running
docker ps

Testing the custom detach key sequence

If the container detaches successfully and remains running, your configuration is correct. If it doesn't work, double-check your config.json syntax or the key sequence you're using.