Subuid subgid

Resources

subuid

subgid

SubUID/GIDs are a range subordinate user/group IDs that a user is allowed to use. These are commonly used by containerization software, such as LXD and Podman, for creating privilege separated containers.

This article outlines a default configuration of subuid/subgid that should work for most user workloads.

Overview of subuid/subgid

For setting up the various container software, proper configuration of subuid and subgid is vital. Keep in mind that after an initial configuration, it is not easily possible to change the subuid/gid mappings without starting from scratch and losing existing containers.

In most modern systems with sys-libs/glibc, UID/GIDs can be in the range 0-4,294,967,295 (2^32 - 1), which is the maximum unsigned integer. In the default LXD configuration (in the absence of /etc/subuid and /etc/subgid), it is assumed that the range 1,000,000-1,000,999,999 is available for LXD to use. It is best to ensure this configuration manually, even when not using LXD, so that it is easier to manage subuids/gids for use with other programs such as podman and docker.

If using LXD, it is vital that the subuid/gid ranges for the users lxd and root are kept in sync. Additionally, for each user on the system, it is best to keep their available subuid/gid ranges distinct and non-overlapping. Creating such a configuration will also help podman in running rootless containers.

Manual configuration

Note
The commands and lines for lxd can be omitted if LXD is not installed on the system

Available ranges for subuid/gid can be configured by editing the files /etc/subuid and /etc/subgid in a text editor.

FILE /etc/subuidsubuid ranges for LXD

root:1000000:1000000000
lxd:1000000:1000000000
larry:1001000000:1000000
cow:1002000000:1000000
developer:1003000000:1000000

FILE /etc/subgidsubgid ranges for LXD

root:1000000:1000000000
lxd:1000000:1000000000
larry:1001000000:1000000
cow:1002000000:1000000
developer:1003000000:1000000

usermod

usermod (from sys-apps/shadow) can also be used to programmatically configure ranges for users. For example, the above configuration can also be achieved by a series of commands:

root #usermod --add-subuids 1000000-1000999999 root

root #usermod --add-subgids 1000000-1000999999 root

root #usermod --add-subuids 1001000000-1001999999 larry

root #usermod --add-subgids 1001000000-1001999999 larry

root #usermod --add-subuids 1002000000-1002999999 cow

root #usermod --add-subgids 1002000000-1002999999 cow

root #usermod --add-subuids 1003000000-1003999999 developer

root #usermod --add-subgids 1003000000-1003999999 developer

See also

• subuid(5)
• subgid(5)
• LXC — a virtualization system making use of Linux's namespaces and cgroups.
• LXD — is a next generation system container manager.
• Podman — a daemonless container engine for developing, managing, and running OCI Containers on Linux.
• Docker — a container virtualization environment