1. Overview

Managing users and permissions is important to maintaining a secure and organized Linux system. Further, this is especially important in multi-user and containerized environments. In traditional Linux systems, each user is assigned a unique user ID (UID) and group ID (GID) to control access to files, processes, and system resources. However, as the number of users and applications increases, the risk of UID or GID conflicts and security vulnerabilities also increases.

To address these challenges, Linux introduced the concept of subordinate user and group ID ranges, commonly known as subuid and subgid ranges. The /etc/subuid file is an important component of this user and group management system enabling administrators to allocate and manage UID ranges for individual users or processes.

In this tutorial, we’ll understand the /etc/subuid file and how we can use it in a Linux system.

2. User Namespace in Linux

In Linux, namespaces are a kernel feature that provides process isolation, enabling processes to have an isolated view of system resources such as process IDs, network interfaces, and file systems.

There are different types of namespaces, one of which is the user namespace.

User namespaces are specifically designed to isolate user and group IDs with each process having its own set of UIDs and GIDs independent from the host system or other user namespaces. This distinction is useful for resource management and containerization.

Now, let’s discuss how the user namespace is related to the the /etc/subuid file.

3. The /etc/subuid File

The /etc/subuid file defines the subordinate user ID (UID) ranges that we can assign to individual users or processes. Thus, it enables them to create and operate within an isolated user namespaces.

3.1. Location and Purpose

The subuid file is typically located in the /etc directory on Linux systems. Further, its primary purpose is to allocate and manage subordinate UID ranges for users or processes. As a result, users can operate in separate user namespaces without conflicting with the host system or other user namespaces.

3.2. File Format and Structure

This file follows a specific format:


Each line represents a single entry that defines a subordinate UID range for a user or process:

  • username: username or system account to which the subordinate UID range is assigned
  • start_uid: starting UID value of the range
  • uid_count: number of subordinate UIDs in the range

Thus, we can define the subordinate UID range as the range of UIDs from start_uid and spanning uid_count UIDs.

3.3. Subordinate UID Range

It’s important to note that the subordinate UIDs defined in the /etc/subuid file are separate from the traditional UID assignments in /etc/passwd. Basically, subordinate UID ranges are additional UIDs assigned to users for use in user namespaces. This way, subordinate UIDs enable users to operate as different users within a container or a virtualized environment, providing a layer of isolation and security.

Let’s see a typical output displaying the content of the /etc/subuid file:

$ cat /etc/subuid

In this example, the root user is assigned a subordinate UID range starting from 231,072 with a total of 512 UIDs. Moreover, the user1 user is assigned a subordinate UID range starting from 100,000 with a total of 65,536 UIDs.

3.4. Managing the /etc/subuid File

Typically, it’s the root user that controls and owns this file. We usually set the permissions for the file to 0644:

  • read and write for the owner
  • read for the group and others

These permissions are necessary to prevent unauthorized modifications.

To add or modify entries in the /etc/subuid file, we can employ usermod:

$ sudo usermod --add-subuids 100000-165535 user1

This command assigns the subordinate UID range from 100,000 to 165,535 to the user user1.

However, it’s essential to exercise caution when making changes to the /etc/subuid file as incorrect entries or unintended overlapping between UID ranges can lead to conflicts and security vulnerabilities.

3.5. Relationship With /etc/passwd

The /etc/passwd file is the primary user database on Linux systems containing information about user accounts:

  • usernames
  • UIDs
  • GIDs
  • home directories
  • shell programs

While the /etc/passwd file defines the primary UIDs and GIDs for user accounts, the /etc/subuid file specifies the subordinate UID ranges that users can have within respective user namespaces.

When a user creates a new user namespace or runs a process within one, the Linux kernel maps the subordinate UID range in /etc/subuid to the user’s UID within a user namespace. Therefore, this enables the user to operate within the confines of that namespace with access to resources specified by the mapped UIDs.

3.6. Interaction With Pluggable Authentication Modules

The Pluggable Authentication Modules (PAM) framework is a suite of shared libraries that provide authentication and authorization services for applications and system services on Linux systems.

Generally, the /etc/subuid file interacts with PAM through the pam_subuid module. In particular, this module is responsible for managing subordinate UID ranges for user sessions. When a user logs in or starts a session, the pam_subuid module reads the user’s subordinate UID range from the /etc/subuid file and sets up the appropriate user namespace for that session.

4. Applications

Now, let’s explore some scenarios where the /etc/subuid file is essential.

4.1. Container Orchestration and Management

One of the most prominent application categories that leverage the /etc/subuid file is container orchestration and management systems like Docker and Kubernetes.

Docker relies on user namespaces and subordinate UID ranges to provide secure and isolated environments for running containers. When we run a Docker container, the container process is assigned a subordinate UID range from the /etc/subuid file of the user running the container.

Similarly, Kubernetes assigns a unique subordinate UID range to each pod, ensuring that its processes run with their own isolated user and group identities.

4.2. Virtualization and Cloud Computing Environments

Subordinate UID ranges and the /etc/subuid file are also essential in virtualization where multiple virtual machines or instances may need to run with their own isolated user and group namespaces.

For instance, in an OpenStack environment, we can configure each Nova compute node with a range of subordinate UIDs for VM instances. When we launch a new VM, it’s assigned a subordinate UID range from the available pool.

5. Conclusion

The /etc/subuid file is an essential component of user and group management in Linux systems, particularly in multi-user and containerized environments. By defining subordinate user ID ranges for individual users or processes, this file enables the creation of isolated user namespaces. Therefore, this process enhances security, prevents conflicts, and enables efficient resource management.

In this article, we explored the purpose, structure, and management of the /etc/subuid file and its relationship with /etc/passwd. We also discussed its interaction with the Pluggable Authentication Modules (PAM).

Notify of
Inline Feedbacks
View all comments