How to Fix the “Docker Permission Denied” Error

Docker is a framework for downloading and easily installing applications on your server. If you don’t use Docker and install an application directly on your system, it can change your system files, and you may need to resolve dependencies, among other things. Uninstalling the application can leave stuff on your server as well. But with docker, you create “containers” that run isolated, self-contained versions of these applications containing all their dependencies. Installing and removing these applications is easy. Because of the power of docker, many operations require special permissions and without them, you get a “Permission Denied” error.

Let’s look at the various ways this error shows up, starting right from installing docker.

Installing Docker on Linux

If you don’t have docker currently installed on Linux, then run the following command:

sudo apt install docker.io

There are two docker packages – docker.io and docker-ce. Docker.io is provided through the Debian infrastructure, and if you’re using Ubuntu, I suggest you use this one. It’s guaranteed to be stable. If you want, you can use docker-ce for the community edition, which contains the latest features and updates. Particularly if you’re just getting started, then docker.io is a better choice. If you’re using CentOS, then you should use docker-ce.

Once you’ve installed docker, you can check to see if it’s working with:

docker --version

You’ll see something like this:

Since I’m using a test Ubuntu system, I’ve used the docker.io package.

Generating the “Docker Permission Denied” Error

To see how docker requires the right permissions, just try running this off the bat and see what happens:

docker ps

You’ll see something like this:

To avoid this error, you need one of two things:

1. Either have root privileges (via sudo, for example)
2. Belong to the “docker” group

The “docker ps” command shows all the existing running containers in docker in a table format. If you use”

docker ps -a

Then it shows you all the containers, including the stopped ones. For example, to test my docker installation, I downloaded the “hello-world” image from the public repository and ran it. It generated its output and quit. So running “docker ps -a” shows the following:

You can see that I ran the docker container 45 minutes ago and it exited. Note that for the command to work, I had to use “sudo” with root privileges. If you don’t know how to assign sudo privileges to your user, I suggest you read my earlier tutorial on how to do just that.

Adding the User to the “docker” Group

It can be annoying to constantly use “sudo” for docker commands. Eventually, the permissions will time out, and you’ll have to re-enter your password, which can interrupt your workflow, particularly if you have a complex password with special characters – as you should!

The sudo alternative then, is to add your user to the “docker” group. This is easy. Just use the following command:

sudo usermod -aG docker $USER

Replace “$USER” with the name of the user to whom you’re trying to give permission. Note that you need sudo permissions to run this command. Once done, log in and log in again to apply the permissions. I just rebooted my server. When you’re logged in again, you can see that the “docker ps -a” command works without any “sudo” permissions:

docker ps -a

Here’s what I get:

As you can see, no sudo is required! You can get a list of all users in the “docker” user group using the following command:

getent group docker

Here’s my output:

As you can see, there’s just one member in the group – myself, who I added just now. If you’re a frequent docker user, then I suggest adding yourself to the docker group instead of relying on sudo. If you don’t foresee yourself using docker a lot, then just stick to using sudo for simplicity.

Why Does Docker Need root Privileges?

When you install docker on Linux, it creates a docker daemon with elevated privileges, allowing it to make all kinds of changes to the system. When you run docker commands, you interact with this daemon, and so you also need elevated privileges, otherwise you can wreak all kinds of havoc on a system, either intentionally or unintentionally.

Socket Communication System

The docker daemon communicates with the docker CLI through a Unix Domain Socket. This is a file located at /var/run/docker.sock. Sockets are used by Linux for Interprocess Communications (IPC). The client sends messages to the receiving process by writing directly into the memory of the listening process. It’s not a traditional file, which is slow. Instead, the processes communicate directly through memory.

This docker socket file requires root permissions to access it, because without it, docker can create privileged containers, mount all kinds of sensitive folders, and more.

Mounting a Restricted Folder

One of the things docker can do is mount folders within a container to a new destination, and then access the files from within that container. If a user doesn’t have root permissions, you don’t want them to be able to access every location on the server.

Let’s test this. First, I create a restricted folder:

sudo mkdir ./restricted
sudo chmod 700 ./restricted

Next, after making sure that you’re not part of the “docker” group, run the following command:

docker run -v /restricted:/data alpine ls /data

You can see below, that not only do I not have access to the ./restricted directory, I can’t even use the docker command to mount it:

This is another example of how I can get the “docker permission denied” error.

Dangers of Using Docker without Sudo

So what exactly can happen if we decide to use docker without root privileges? Let’s say I include every Linux user in the “docker” group, what’s the worst that could happen? Well, a lot!

Mounting the Whole File System

Anyone who can use docker, gains root access to the entire system, because the docker daemon can access the entire system. So for example, with docker, you could mount the entire file system in a container and access it from there. There are sensitive folders in Linux such as /etc/passwd, and by running a privileged container, any user could just access any file or directory.

For example, the command:

docker run --rm -v /:/host -it ubuntu bash

Creates a new container, mounts the root directory (/) to the “/host” directory inside the container, loads Linux, and runs the bash command. Imagine you can now access every single file on the system! This is why those running docker commands need root privileges.

This is just one example of the damage an attacker can do with docker if they’re not authorized to have root privileges. That’s why adding users to the docker group is a little too easy and can be dangerous.

Conclusion

As you can see, the “docker permission denied” error message isn’t just an annoyance to fix. It’s a core component of docker’s framework. Docker is such a powerful system, that you need to circumscribe it properly, otherwise it can cause untold damage. If you don’t want to keep using “sudo”, then just adding users to the “docker” group is enough after you log out and log in again. Just make sure you know what you’re doing!