What does Docker STOPSIGNAL do?

Question

I am trying to understand what exactly the STOPSIGNAL command in a dockerfile does. So according to the Docker Docs:

The STOPSIGNAL instruction sets the system call signal that will be sent to the container to exit. This signal can be a valid unsigned number that matches a position in the kernel’s syscall table, for instance 9, or a signal name in the format SIGNAME, for instance SIGKILL.

With this explanation I understand that there is some signal that is sent to the docker container to tell inside applications to stop. But when I shutdown a running container with sudo docker stop container-name, doesn't it then automatically also stops everything that runs inside? I can type this command without getting any errors. Isn't it then redundant to explicitly define STOPSIGNAL inside a dockerfile?

Looking at how Nginx is built with a dockerfile, the command STOPSIGNAL SIGTERM is used. But what does that exaclty mean? Would it break something to not define STOPSIGNAL?

Answer 1

SIGTERM is the default signal sent to containers to stop them: https://docs.docker.com/engine/reference/commandline/stop/

STOPSIGNAL does allow you to override the default signal sent to the container. Leaving it out of the Dockerfile causes no harm - it will remain the default of SIGTERM.

This being said, it is unclear why the author has explicitly defined the STOPSIGNAL as SIGTERM.

Looking at this commit, we can see that the STOPSIGNAL used to be set to SIGQUIT.

My guess is that they left it in explicitly for documentation's sake after making the change.

Discussion of the change here: https://github.com/nginxinc/docker-nginx/issues/167