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

docs/reference: exec: update some examples 

Use /bin/sh in the examples, as it's more likely to be present in a
container than bash (some users got confused by this, so using plain
"sh" in the examples could lead to less confusion).

Also added some extra wording around defaults, and how they're inherited
by the exec'd process.

It's definitely not "perfect" yet (lots to do in this document to improve
it), but it's a start :)

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2022-06-06 15:23:30 +02:00
parent cac78c237f
commit 60833d2046
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 51 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
docs/reference/commandline/exec.md
View File

@ -35,13 +35,13 @@ The command started using `docker exec` only runs while the container's primary
process (`PID 1`) is running, and it is not restarted if the container is process (`PID 1`) is running, and it is not restarted if the container is
restarted. restarted.
COMMAND will run in the default directory of the container. If the COMMAND runs in the default directory of the container. If the underlying image
underlying image has a custom directory specified with the WORKDIR directive has a custom directory specified with the WORKDIR directive in its Dockerfile,
in its Dockerfile, this will be used instead. this directory is used instead.
COMMAND should be an executable, a chained or a quoted command COMMAND must be an executable. A chained or a quoted command does not work.
will not work. Example: `docker exec -ti my_container "echo a && echo b"` will For example, `docker exec -it my_container sh -c "echo a && echo b"` works,
not work, but `docker exec -ti my_container sh -c "echo a && echo b"` will. work, but `docker exec -it my_container "echo a && echo b"` does not.
## Examples ## Examples
@ -50,70 +50,91 @@ not work, but `docker exec -ti my_container sh -c "echo a && echo b"` will.
First, start a container. First, start a container.
```console ```console
$ docker run --name ubuntu_bash --rm -i -t ubuntu bash $ docker run --name mycontainer -d -i -t alpine /bin/sh
``` ```
This will create a container named `ubuntu_bash` and start a Bash session. This creates and starts a container named `mycontainer` from an `alpine` image
with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`)
sets the container to run in the background, in detached mode, with a pseudo-TTY
attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which
prevents the `sh` process from exiting immediately.
Next, execute a command on the container. Next, execute a command on the container.
```console ```console
$ docker exec -d ubuntu_bash touch /tmp/execWorks $ docker exec -d mycontainer touch /tmp/execWorks
``` ```
This will create a new file `/tmp/execWorks` inside the running container This creates a new file `/tmp/execWorks` inside the running container
`ubuntu_bash`, in the background. `mycontainer`, in the background.
Next, execute an interactive `bash` shell on the container. Next, execute an interactive `sh` shell on the container.
```console ```console
$ docker exec -it ubuntu_bash bash $ docker exec -it mycontainer sh
``` ```
This will create a new Bash session in the container `ubuntu_bash`. This starts a new shell session in the container `mycontainer`.
### <a name=env></a> Set environment variables for the exec process (--env, -e)
Next, set environment variables in the current bash session. Next, set environment variables in the current bash session.
By default, the `docker exec` command, inherits the environment variables that
are set at the time the container is created. Use the `--env` (or the `-e` shorthand)
to override global environment variables, or to set additional environment variables
for the process started by `docker exec`.
The example below creates a new shell session in the container `mycontainer` with
environment variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively.
These environment variables are only valid for the `sh` process started by that
`docker exec` command, and are not available to other processes running inside
the container.
```console ```console
$ docker exec -it -e VAR_A=1 -e VAR_B=2 ubuntu_bash bash $ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=f64a4851eb71
VAR_A=1
VAR_B=2
HOME=/root
``` ```
This will create a new Bash session in the container `ubuntu_bash` with environment ### <a name=workdir></a> Set the working directory for the exec process (--workdir, -w)
variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively. Note that these
environment variables will only be valid on the current Bash session.
By default `docker exec` command runs in the same working directory set when container was created. By default `docker exec` command runs in the same working directory set when
the container was created.
```console ```console
$ docker exec -it ubuntu_bash pwd $ docker exec -it mycontainer pwd
/ /
``` ```
You can select working directory for the command to execute into You can specify an alternative working directory for the command to execute
using the `--workdir` option (or the `-w` shorthand):
```console ```console
$ docker exec -it -w /root ubuntu_bash pwd $ docker exec -it -w /root mycontainer pwd
/root /root
``` ```
### Try to run `docker exec` on a paused container ### Try to run `docker exec` on a paused container
If the container is paused, then the `docker exec` command will fail with an error: If the container is paused, then the `docker exec` command fails with an error:
```console ```console
$ docker pause test $ docker pause mycontainer
mycontainer
test
$ docker ps $ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
1ae3b36715d2 ubuntu:latest "bash" 17 seconds ago Up 16 seconds (Paused) test 482efdf39fac alpine "/bin/sh" 17 seconds ago Up 16 seconds (Paused) mycontainer
$ docker exec test ls $ docker exec mycontainer sh
FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec Error response from daemon: Container mycontainer is paused, unpause the container before exec
$ echo $? $ echo $?
1 1