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:

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:

Let's look at doing something a little more complex now.