Whenever you install Docker on the Ubuntu or Debian system using the following command:
curl -sSL https://get.docker.com/ | sh
You might encounter the following message at the end of the command that says “To install Docker in a non-privileged user, consider setting up Docker daemon in rootless mode for your user”. What does it mean?
By default, Docker requires root privileges to run, as it interacts with system-level components such as the Docker daemon and system resources like networking and storage. However, running Docker as root can pose security risks, as any compromise of the Docker daemon could potentially lead to broader system compromise.
To mitigate these risks and allow non-privileged users to run Docker without granting them root access, Docker introduced a feature called “rootless mode.” In rootless mode, the Docker daemon and containers run entirely within the user’s own namespace, without needing root privileges. In this guide, we’ll explore how Rootless mode works, its prerequisites, installation steps, known limitations, and best practices.
Understanding Rootless Mode
Rootless mode operates by executing the Docker daemon and containers within a user namespace. This means that both the daemon and the containers run without root privileges, thus reducing potential security vulnerabilities. Unlike userns-remap mode, where the daemon runs with root privileges, Rootless mode ensures that all components operate within the confines of user permissions.
Prerequisites
Before setting up Docker in Rootless mode, there are several prerequisites to consider:
- Installation of newuidmap and newgidmap: These commands, typically provided by the uidmap package, are necessary to manage user and group ID mappings within the user namespace.
Debian/Ubuntu:
sudo apt-get install uidmap
Red Hat/CentOS:
sudo yum install uidmap
Fedora:
sudo dnf install uidmap
Arch Linux:
sudo pacman -S uidmap
Choose the appropriate command based on your distribution, and it will install the uidmap package, thereby providing the newuidmap and newgidmap commands required for Docker’s Rootless mode.
- Configuration of subordinate UIDs/GIDs: Ensure that
/etc/subuidand/etc/subgidcontain a sufficient number of subordinate UIDs/GIDs for the user who will be running Docker in Rootless mode.
To configure subordinate UIDs/GIDs for the user who will be running Docker in Rootless mode, you need to ensure that the /etc/subuid and /etc/subgid files contain a sufficient number of subordinate UIDs/GIDs allocated for that user. Here’s how you can do it:
1. Check Current User’s UID/GID:
First, determine the UID and GID of the user who will be running Docker in Rootless mode. You can do this using the id command:
id -u <username>
id -g <username>
2. Allocate Subordinate UIDs/GIDs:
Edit the /etc/subuid and /etc/subgid files to allocate a range of subordinate UIDs/GIDs for the user. You’ll typically use a text editor like nano or vim to modify these files:
sudo nano /etc/subuid
sudo nano /etc/subgid
3. Add Entries for the User:
Add an entry for the user in both files specifying the UID/GID range. The format is <username>:<start_uid>:<count>. For example:
<username>:<start_uid>:<count>
Replace <username> with the actual username, <start_uid> with the starting UID, and <count> with the number of UIDs/GIDs to allocate. Here’s an example entry:
testuser:100000:65536
This example allocates 65536 subordinate UIDs/GIDs starting from UID/GID 100000 for the user testuser.
4. Save and Exit:
Save the changes and exit the text editor.
5. Verify:
Verify that the changes have been applied correctly:
grep ^<username> /etc/subuid
grep ^<username> /etc/subgid
Replace with the actual username.
By completing these steps, you ensure that the user running Docker in Rootless mode has a sufficient number of subordinate UIDs/GIDs allocated for proper operation.
- Additional considerations for specific distributions: Depending on the Linux distribution being used, additional steps may be required. For example, on Ubuntu, it’s recommended to use the Ubuntu kernel and install the dbus-user-session package.
It’s recommended to use the Ubuntu kernel for optimal compatibility and performance with Docker in Rootless mode. Ubuntu kernels are typically well-supported and include necessary patches and configurations.
Install the dbus-user-session Package:
On Ubuntu, installing the dbus-user-session package is recommended for proper functioning of certain system services and components. This package provides the D-Bus session bus for user sessions, which can be crucial for running services like Docker.
To install dbus-user-session, you can use the following command:
sudo apt-get install dbus-user-session
This will ensure that the necessary D-Bus session bus is available for user sessions, which can be essential for applications like Docker to communicate with other system services.
Installation Steps
With Packages (RPM/DEB)
If you’re using Docker version 20.10 or later and have installed it using RPM or DEB packages, setting up Docker in Rootless mode is straightforward:
Run the below command as a non-root user to set up the daemon.
dockerd-rootless-setuptool.sh install
Ensure that the required environment variables (PATH and DOCKER_HOST) are correctly configured.
Without Packages
If you’re installing Docker without using packages, you may need to follow slightly different steps:
- Install the docker-ce-rootless-extras package manually, if necessary.
- Set up the required environment variables (PATH and DOCKER_HOST) manually.
If you’re installing Docker without using packages, such as using the binary installation method, you may need to take additional steps to configure Docker in Rootless mode. Here’s how you can do it:
Install the docker-ce-rootless-extras Package Manually:
The docker-ce-rootless-extras package contains additional tools and configurations specifically for running Docker in Rootless mode. You can download and install this package manually if it’s not included in your installation. Here’s how you can do it:
sudo apt-get install -y docker-ce-rootless-extras
If you’re using a different package manager or distribution, adjust the command accordingly.
Set Up Environment Variables (PATH and DOCKER_HOST) Manually:
After installing the necessary package, you’ll need to set up the required environment variables manually. This ensures that your shell knows where to find the Docker binaries and how to connect to the Docker daemon.
Open your shell configuration file (e.g., ~/.bashrc, ~/.bash_profile, or ~/.zshrc) in a text editor:
nano ~/.bashrc
Add the following lines to set up the PATH and DOCKER_HOST environment variables:
export PATH="/usr/bin:$PATH" # Adjust the path if Docker binaries are located elsewhere
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
Save the file and exit the text editor. Then, reload your shell configuration to apply the changes:
source ~/.bashrc
Replace /usr/bin with the actual path to the Docker binaries if it’s different on your system.
By following these steps, you can manually install the necessary Docker package for Rootless mode and configure the required environment variables to ensure proper operation. Make sure to adjust the commands and paths according to your system configuration.
Usage and Best Practices
Once Docker is configured in Rootless mode, you can manage the daemon and containers using standard Docker commands. However, there are some best practices to keep in mind:
- Managing Daemon: Use systemctl –user commands to manage the Docker daemon’s lifecycle. Enabling lingering ensures that the daemon starts automatically on system boot.
- Managing Client: Specify either the socket path or the CLI context explicitly when interacting with the Docker client.
- Rootless Docker in Docker: To run Rootless Docker inside another Docker container, use the appropriate Docker image and ensure that necessary privileges are granted.
- Exposing Docker API Socket: If you need to expose the Docker API socket through TCP or SSH, follow the recommended configurations.
Troubleshooting
In case of errors or unexpected behavior, refer to the troubleshooting section for common issues and their solutions. This includes addressing errors during Docker daemon startup, issues with Docker pull or run commands, networking problems, and more.
Conclusion
Running the Docker daemon and containers in Rootless mode offers a more secure alternative to the traditional root-based setup. By following the steps outlined in this guide and adhering to best practices, users can enjoy the benefits of Docker while mitigating potential security risks associated with root access. Whether you’re a developer testing applications locally or a system administrator managing production deployments, Rootless mode provides a safer environment for container operations.
