| 1 |
## Output |
| 2 |
|
| 3 |
```text |
| 4 |
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals |
| 5 |
``` |
| 6 |
|
| 7 |
## Description |
| 8 |
|
| 9 |
`ENTRYPOINT` and `CMD` instructions both support two different syntaxes for |
| 10 |
arguments: |
| 11 |
|
| 12 |
- Shell form: `CMD my-cmd start` |
| 13 |
- Exec form: `CMD ["my-cmd", "start"]` |
| 14 |
|
| 15 |
When you use shell form, the executable runs as a child process to a shell, |
| 16 |
which doesn't pass signals. This means that the program running in the |
| 17 |
container can't detect OS signals like `SIGTERM` and `SIGKILL` and respond to |
| 18 |
them correctly. |
| 19 |
|
| 20 |
## Examples |
| 21 |
|
| 22 |
❌ Bad: the `ENTRYPOINT` command doesn't receive OS signals. |
| 23 |
|
| 24 |
```dockerfile |
| 25 |
FROM alpine |
| 26 |
ENTRYPOINT my-program start |
| 27 |
# entrypoint becomes: /bin/sh -c my-program start |
| 28 |
``` |
| 29 |
|
| 30 |
To make sure the executable can receive OS signals, use the exec form for `CMD` |
| 31 |
and `ENTRYPOINT`, which lets you run the executable as the main process (`PID |
| 32 |
1`) in the container, avoiding a shell parent process. |
| 33 |
|
| 34 |
✅ Good: the `ENTRYPOINT` receives OS signals. |
| 35 |
|
| 36 |
```dockerfile |
| 37 |
FROM alpine |
| 38 |
ENTRYPOINT ["my-program", "start"] |
| 39 |
# entrypoint becomes: my-program start |
| 40 |
``` |
| 41 |
|
| 42 |
Note that running programs as PID 1 means the program now has the special |
| 43 |
responsibilities and behaviors associated with PID 1 in Linux, such as reaping |
| 44 |
child processes. |
| 45 |
|
| 46 |
### Workarounds |
| 47 |
|
| 48 |
There might still be cases when you want to run your containers under a shell. |
| 49 |
When using exec form, shell features such as variable expansion, piping (`|`) |
| 50 |
and command chaining (`&&`, `||`, `;`), are not available. To use such |
| 51 |
features, you need to use shell form. |
| 52 |
|
| 53 |
Here are some ways you can achieve that. Note that this still means that |
| 54 |
executables run as child-processes of a shell. |
| 55 |
|
| 56 |
#### Create a wrapper script |
| 57 |
|
| 58 |
You can create an entrypoint script that wraps your startup commands, and |
| 59 |
execute that script with a JSON-formatted `ENTRYPOINT` command. |
| 60 |
|
| 61 |
✅ Good: the `ENTRYPOINT` uses JSON format. |
| 62 |
|
| 63 |
```dockerfile |
| 64 |
FROM alpine |
| 65 |
RUN apk add bash |
| 66 |
COPY --chmod=755 <<EOT /entrypoint.sh |
| 67 |
#!/usr/bin/env bash |
| 68 |
set -e |
| 69 |
my-background-process & |
| 70 |
my-program start |
| 71 |
EOT |
| 72 |
ENTRYPOINT ["/entrypoint.sh"] |
| 73 |
``` |
| 74 |
|
| 75 |
#### Explicitly specify the shell |
| 76 |
|
| 77 |
You can use the [`SHELL`](https://docs.docker.com/reference/dockerfile/#shell) |
| 78 |
Dockerfile instruction to explicitly specify a shell to use. This will suppress |
| 79 |
the warning since setting the `SHELL` instruction indicates that using shell |
| 80 |
form is a conscious decision. |
| 81 |
|
| 82 |
✅ Good: shell is explicitly defined. |
| 83 |
|
| 84 |
```dockerfile |
| 85 |
FROM alpine |
| 86 |
RUN apk add bash |
| 87 |
SHELL ["/bin/bash", "-c"] |
| 88 |
ENTRYPOINT echo "hello world" |
| 89 |
``` |