The Docker engine enables you to start
, stop
, and restart
a container with a set of docker
subcommands. Let's begin with the docker container stop
subcommand, which stops a running container. When a user issues this command, the Docker engine sends SIGTERM (-15)
to the main process, which is running inside the container. The SIGTERM signal requests the process to terminate itself gracefully.
Most of the processes would handle this signal and facilitate a graceful exit. However, if this process fails to do so, then the Docker engine will wait for a grace period. Even after the grace period, if the process has not been terminated, then the Docker engine will forcefully terminate the process. The forceful termination is achieved by sending SIGKILL (-9)
.
The SIGKILL signal cannot be caught or ignored and hence, it will result in an abrupt termination of the process without a proper cleanup.
Now, let's launch our container and experiment with the docker container stop
subcommand, as shown here:
dockercontainer run -i -t ubuntu:16.04 /bin/bash
Having launched the container, let's run the docker container stop
subcommand on this container by using the container ID
that was taken from the prompt. Of course, we have to use a second screen/terminal to run this command, and the command will always echo back to the container ID
, as shown here:
docker container stop 3 de97cc32051
Now, if you switch to the screen/terminal where you were running the container, you will notice that the container is being terminated. If you observe a little more keenly, then you will also notice the text exit
next to the container prompt. This happened due to the SIGTERM handling mechanism of the bash shell, as shown here:
If we take it one step further and run the docker container ps
subcommand, then we will not find this container anywhere in the list. The fact is that the docker container ps
subcommand, by default, always lists the container that is in the running state. Since our container is in the stopped state, it was comfortably left out of the list. Now, you might ask, how do we see the container that is in the stopped state? Well, the docker container ps
subcommand takes an additional argument -a
, which will list all the containers in that Docker host irrespective of its status.
This can be done by running the following command:
docker container ps -a
Next, let's look at the docker container start
subcommand, which is used for starting one or more stopped containers. A container could be moved to the stopped state either by the docker container stop
subcommand or by terminating the main process in the container either normally or abnormally. On a running container, this subcommand has no effect.
Let's start the previously stopped container by using the docker container start
subcommand, as follows:
docker start 3de97cc32051
By default, the docker container start
subcommand will not attach to the container. You can attach it to the container either by using the -a
option in the docker container start
subcommand or by explicitly using the docker container attach
subcommand, as shown here:
docker container attach 3de97cc32051
Now, let's run the docker containerps
command and verify the container's running status, as shown here:
docker container ps
The restart
command is a combination of the stop
and the start
functionality. In other words, the restart
command will stop
a running container by following the precise steps followed by the docker conatiner stop
subcommand and then it will initiate the start
process. This functionality will be executed by default through the docker conatiner restart
subcommand.
The next important set of container controlling subcommands are the following:
docker container pause
docker container unpause
The docker container pause
subcommands will essentially freeze the execution of all the processes within that container. Conversely, the docker container unpause
subcommand will unfreeze the execution of all the processes within that container and resume the execution from the point where it was frozen.
Having seen the technical explanation of pause
/unpause
, let's see a detailed example for illustrating how this feature works. We have used two screen/terminal scenarios. On one terminal, we have launched our container and used an infinite while loop for displaying the date and time, sleeping for 5 seconds, and then continuing the loop. We will run the following commands:
docker container run -i -t ubuntu:16.04 /bin/bash
Once you are within the container, run the following:
while true; do date; sleep 5; done
Our little script has very faithfully printed the date and time every 5
seconds apart from when it was paused:
As you can see from the terminal output above, we encountered a delay of around 30 seconds, because this is when we initiated the docker container pause
subcommand on our container on the second terminal screen, as shown here:
docker container pause 9724f4e0e444
When we paused our container, we looked at the process status by using the docker containerps
subcommand on our container, which was on the same screen, and it clearly indicated that the container had been paused, as shown in this command result:
docker container ps
We continued onto issuing the docker conatiner unpause
subcommand, which unfroze our container, continued its execution, and then started printing the date and time, as we saw in the preceding command, shown here:
docker container unpause 9724f4e0e444
We explained the pause
and the unpause
commands at the beginning of this section.
Lastly, the container and the script running within it had been stopped by using the docker container stop
subcommand, as shown here:
docker container stop 9724f4e0e444
You can see everything we ran in our second terminal below:
3.139.87.61