FreeIPA subordinate IDs for rootless containers

What FreeIPA subordinate IDs do for rootless containers

Rootless Podman needs every user who runs containers to hold a subordinate UID and GID range, and on a fleet those ranges are often kept in per-host /etc/subuid and /etc/subgid files that drift apart over time. FreeIPA can hold these ranges centrally, so every enrolled host sees the same assignments for the same user. The result is that a container image, volume or shared storage path that carries numeric IDs means the same thing on every machine. According to the FreeIPA design page on subordinate IDs, the feature adds central management on top of the Linux kernel mechanism, which grants a user additional user and group ID ranges and which container runtimes use for rootless containers. The design page is the natural next read for the exact object model and how assignments are published to clients.

Teams usually need central management when they operate many hosts that run rootless containers, when they share images, home directories or storage between those hosts, or when the same users move between machines and expect identical ID mappings. Without central assignment, a user can receive different ranges on different hosts, and files written under one range may appear as foreign owners elsewhere. A single host with a few local accounts rarely needs this, because /etc/subuid and /etc/subgid are simpler to manage there and no shared state is at stake. Confirm with your platform team whether any host outside FreeIPA enrollment will run rootless containers, since those hosts still read local files and can drift from the central assignments.

Before you adopt the feature, confirm three things in your own environment: which SSSD and Podman versions your distributions ship, whether your container runtime reads the ID ranges through the path your clients provide, and who owns range assignment when a new user is created. Plan a test with two enrolled hosts and one shared test user, then compare the resulting ranges and the ownership of files written inside a container on each host. That check shows whether central assignment actually removes drift in your fleet, and it gives you a baseline before you change any existing host.

Choosing between per-host files and central FreeIPA ranges

This table compares managing subordinate ID ranges in per-host /etc/subuid and /etc/subgid files with managing them centrally in FreeIPA. Read each row as a question you need answered for your fleet, then check the exact range and allocation behavior against the design page and the FreeIPA version you run.

Question	Per-host files managed by configuration tools	Central FreeIPA management
How assignments are created	Each host's files are written by a configuration tool or by hand, so ranges depend on the tool's logic and run order	Ranges are defined once in IPA and applied to enrolled hosts, so the server holds the assignment record
How drift is detected	You compare files across hosts with your configuration management reports or audit scripts	Mismatches show up as differences from the central record, but confirm which checks your version exposes
What happens to existing hosts	Hosts that already hold ranges keep them until someone changes the files, which can conflict with new assignments	Existing hosts need a deliberate review before they follow central ranges, so plan a migration step rather than assume it
Small fleet (illustrative: a handful of hosts)	Low overhead if one tool owns the files and you rarely add users	Adds an IPA dependency for a small benefit, so weigh it against the enrollment you already run
Large enrolled estate	Ranges drift as hosts are rebuilt, and tracing a UID collision across hosts takes manual work	Consistent ranges across many hosts are easier to verify, provided enrollment and the central record stay healthy
Who owns range changes	The team that owns the configuration tool, through change requests to each host group	The IPA administrators, with delegation rules you define in advance
Recovery and backups	Files are backed up with each host, and rebuilt hosts need the file restored or regenerated	Ranges live in the IPA data, so IPA backup and restore practice covers them; confirm restore behavior for your version
What to confirm before choosing	Which tool writes the files, and whether it can preserve existing ranges on rebuild	Exact range allocation settings and behavior in your FreeIPA version, as described on the subordinate IDs design page

Design decisions to settle before rollout

Subordinate ID ranges look like a small configuration detail, but every host that runs rootless containers inherits the choices made here. The decisions below cover who gets a range, how ranges stay consistent, and how existing local entries and other identity sources are handled. Settle them in writing before the first host is enrolled.

Which user populations need ranges

Not every account needs a subordinate ID range. List the groups that will run rootless Podman containers, such as developers, CI service accounts and application runtimes, and separate them from interactive administrators and system accounts. If you assign ranges to everyone, you spend the ID space on accounts that never use it and make later audits harder to read. Skipping this step usually means ranges are issued ad hoc, with no record of which account owns which block.

Matching ranges across hosts

Decide whether a given user must receive the same range on every host, or whether ranges only need to be consistent within a host group. Identical ranges everywhere make container storage, copied volumes and backups portable between machines. Per-group ranges are easier to reason about when hosts are isolated by environment. If this is left open, a user can receive different ranges on different hosts, and files written in one place will show the wrong owners in another.

Existing entries in local subuid files

Many hosts already have ranges in /etc/subuid and /etc/subgid that were created by hand or by a previous tool. Before central management takes over, inventory these files on every host and compare them with the planned FreeIPA values. Any user with a local entry that conflicts with a central range needs a decision: keep the local range, reissue it, or move the files. Skipping the inventory can leave two sources disagreeing about the same user, and the one a host reads first wins.

Overlap with other identity sources

Subordinate ranges are numeric, so they can collide with UID and GID ranges already in use. Check the ID ranges used by FreeIPA users, groups, trusted Active Directory domains and local system accounts before choosing new blocks. Confirm how your ID views and trust mappings assign UIDs, because a range that overlaps a mapped AD user can give that user unexpected container privileges on Linux. Verify the layout on a test host before any broad rollout.

Stability of container storage and ownership

Rootless container images, volumes and bind-mounted files are owned by numbers inside the user's range. If a range changes after data is written, the files appear owned by unfamiliar IDs, and containers may fail to read their own data. Decide that ranges are stable for the life of the account, and plan how existing storage would be re-owned if a change is ever unavoidable. Ask your platform team to test a range change on a copy of real container storage before approving any change.

Ownership of range changes

Name one team that approves, records and applies changes to subordinate ID ranges, and state who may request them. Without a named owner, administrators fix problems locally with edits to /etc/subuid, and FreeIPA and the host drift apart. Set out a change record format that includes the user, host group, old and new values, and the reason. Review the record during access reviews so that range assignments are checked along with other identity changes.

Setup sequence for central subordinate ID ranges

This sequence moves subordinate UID and GID ranges from scattered per-host files into FreeIPA, then proves on pilot hosts that the same user gets the same range and can run rootless Podman. Each step ends with a check you can record before expanding the rollout.

Confirm FreeIPA and client versions
Before any change, record the FreeIPA server version on every IdM server and the SSSD version on each pilot host. Confirm that the subordinate ID design is supported in the versions you run by reading the FreeIPA subordinate IDs design page and the release notes for your installed server version. Also confirm the Podman and shadow-utils versions on the pilot hosts with your distribution's documentation. The step is done when you have a written version matrix and every component you need is listed as supported in the documentation you checked. If any component is missing from that documentation, stop and ask the FreeIPA project or your vendor before continuing.
Inventory local subuid and subgid entries
On each pilot host, record the contents of /etc/subuid and /etc/subgid, and note which local users own ranges and whether any ranges overlap. Run getent passwd for the users who run rootless containers so you can map each account to its range. Save the output with the host name and date. This inventory is the baseline for comparison later, and it shows which ranges must be retired or reassigned so they do not collide with central ranges. The step is done when every pilot host has a saved inventory and you have listed every overlap or conflict that needs a decision.
Define the central range plan
Write down the subordinate ID ranges you intend to assign centrally, including the start, size and the user or group each range belongs to. Check the range plan against the existing inventory and against the ID ranges already used by FreeIPA for user and group IDs, so that no subordinate range overlaps another domain's IDs. Decide how ranges will be assigned to users and groups, and who approves changes. Use the range management commands described in the FreeIPA subordinate IDs design page and the installed version's command help, and confirm exact syntax there rather than copying from older examples. The step is done when the plan is reviewed, and the commands you will run are checked against the installed version.
Enroll or confirm pilot hosts with SSSD
Enroll each pilot host as a FreeIPA client, or confirm that an existing enrollment is healthy. Enrollment and SSSD configuration follow your installed version's client documentation. Then confirm that SSSD answers identity lookups for an IdM user on the host. The check is a successful identity lookup for a test user, along with a clean SSSD status and no errors in its logs. If the host is not enrolled correctly, subordinate ID lookups will not reflect central data, so do not proceed until this check passes.
Create the central ranges for the test user
Using the commands in the design page and the installed version's documentation, create the central subordinate ID range for a dedicated test user in FreeIPA and apply it according to your range plan. Record the exact command, the output and the time of the change. The check is that FreeIPA reports the range you planned for that user and no other user's range overlaps it. Keep the test user limited to the pilot group so that a mistake does not affect production accounts.
Verify the test user receives the expected range
On each pilot host, log in as the test user through SSSD and query the subordinate ranges the system reports for that user. Compare the results with the range recorded in FreeIPA and with the local inventory from step two. The check is an exact match on every pilot host, with no local /etc/subuid entry shadowing or conflicting with the central range. Repeat the lookup from a second pilot host so that the same range is confirmed across machines, since consistency across hosts is the purpose of this design.
Run a rootless Podman test container
As the test user on each pilot host, run a small test container with rootless Podman, using an image your organization already approves. Confirm the container starts, that the user namespace mapping uses the expected range, and that files written from inside the container are owned by the mapped IDs on the host. Check the Podman documentation for your installed version for the commands that show the namespace mapping. The step is done when the container runs on every pilot host with the same mapping, and you have saved the output as evidence before expanding to more users or hosts.

Why stable ranges matter for file ownership and container storage

A user's subordinate ID range should be identical on every host where that user runs containers. Rootless Podman maps a range of host UIDs and GIDs into each container's user namespace, so the numeric ownership of files depends on which range was in effect when the files were written. If alice owns the range 200000 to 265535 on one host and 300000 to 365535 on another, a file created inside a container on the first host is stored on disk as UID 200000 plus an offset. On the second host, the same offset lands on a different number, and the file appears owned by an unexpected or unmapped ID. Central management in FreeIPA exists to prevent this drift across the fleet, because the range is assigned once rather than set independently in each host's /etc/subuid and /etc/subgid files.

The problem shows up in places that are easy to miss. Home directories that follow a user between hosts, shared volumes mounted on several machines, and container images or layers copied between hosts can all carry files whose on-disk owners were computed under an old range. Inside the container, those files may show up as nobody, as root-owned, or as permission denied errors, while the same container works on the host where it was first built. Treat any change to a range as a storage change, not only an identity change. Before moving a user to a new range, list the storage paths they touch, record current ownership from the host side, and plan how existing data will be re-owned or left under the old mapping.

After any range change, verify the result on each affected host rather than assuming it. Confirm the user's entries in /etc/subuid and /etc/subgid match the central value, confirm the SSSD cache has refreshed on the hosts that matter, then start a test container as the user, create a file in a bind-mounted directory, and compare its owner on the host and inside the container. Repeat the test on a second host that shares the same storage. Your own storage layout, including NFS export options, volume drivers and how your images are rebuilt, decides whether this check passes. Confirm those behaviors in your environment with a test before you schedule a change across production hosts.

How the approach changes by environment

A small group running rootless Podman on a handful of enrolled hosts usually has one range plan that fits everyone. The work is mostly deciding who gets which range, documenting it and confirming that every host resolves the same ranges through SSSD. Because few hosts are involved, changes are easy to track by hand, but informal habits tend to creep in as the team grows.

Range ownership: Decide who approves new ranges and record the owner of each user or group assignment.
Main risk: A range copied by hand onto one host that differs from central data, causing container file ownership to look wrong on that host only.
Host reach: Confirm every host can reach the FreeIPA servers and that SSSD caches are refreshed after a change.
Ranges per user: Ask how many ranges a user needs and whether any user already has local entries in /etc/subuid that would conflict.
Rollback: Agree how a bad range assignment is removed before containers depend on it.

Before committing, confirm that your team will not keep editing /etc/subuid locally once central management is live.

Some hosts cannot use SSSD, or sit outside the FreeIPA domain, such as legacy systems, appliances or machines managed by another directory. Central range management does not reach these hosts automatically, so the team must decide whether to keep local files, bring the host into the domain, or exclude it from rootless container use. The design choice is about consistency, since a host with its own ranges can produce ownership mismatches on shared storage.

Exclusion decision: Decide whether these hosts run rootless containers at all, and document the answer.
Local ranges: If local /etc/subuid files stay, record which ranges they use and confirm they do not overlap central ranges.
Main risk: Container file ownership that differs on shared volumes between a centrally managed host and an isolated one.
Enrollment path: Check whether the host can be enrolled with SSSD at all, and what the supported client distributions are.
Name resolution: Confirm how the host finds the FreeIPA servers if it sits outside the domain.

Before committing, confirm the host's operating system, its SSSD support status and whether any volume it shares with domain hosts relies on consistent numeric IDs.

Security and operational considerations for central ID ranges

Central subordinate ID ranges change who controls container user mappings across every enrolled host. The cards below cover the decisions that follow from that: who can change ranges, how changes reach running workloads, how wide a mapping becomes, and how to recover. Confirm the behavior described for your FreeIPA version in its release notes before you rely on it.

Who may change ranges

Range assignments are identity data, so the people who can edit them can change which UIDs and GIDs a container user maps to on many hosts at once. Decide in advance which IPA administrative roles may create or modify ID ranges, and keep that set small and separate from general host administration. Confirm in your version's documentation how changes are recorded, and check that your audit log captures them before go-live.

Effect of changes on running containers

A range change does not rewrite files already owned by mapped IDs. If a user's range moves, files written inside containers can end up owned by numbers that no longer map to that user, and running containers may keep the old mapping until restarted. Ask the vendor or your test results how a change propagates to hosts with active containers, and plan a maintenance window for any range edit that affects users with running workloads.

Wider mapping surface

Each subordinate range gives a container user a block of host UIDs and GIDs to map into its namespace. A large or shared range widens what a process inside a container can claim on the host filesystem, so review range size against the workloads each user runs. Overlapping or unnecessarily large ranges are harder to reason about during an incident, so keep allocations to the size the workload requires.

Impact of a bad range across hosts

Because the same range is delivered to every enrolled host, a misconfigured or compromised range affects all of them, not one machine. An overlap with another allocation, or a range that includes IDs used by local or service accounts, can cause file ownership confusion on several hosts simultaneously. Before rollout, check for overlaps with existing ID ranges and local accounts on each host class.

Fit within the IPA access model

Subordinate ranges are one part of the access picture alongside host-based access control, sudo rules, and group membership. A user who can run containers on a host is still limited by the access rules that govern that host, so do not treat range assignment as an access grant. Map which groups receive ranges and confirm that those groups match your existing host access and delegation policy.

Rehearsing recovery

Test how you restore ID range data before you need it. FreeIPA backups protect directory data, but restoring an outdated backup into an active replica topology can break replication, so rehearse restores in an isolated environment. Confirm how ID range data is included in backup and restore for your version, and record the steps for reverting an incorrect range change on a host set you have chosen to test.

Limits to confirm in your environment before you commit

Before you commit to central subordinate ID ranges, confirm the feature's behavior against your exact versions. Record the installed FreeIPA server version, the SSSD version on every client, and the container runtime and version you run, then check each against the FreeIPA subordinate IDs design page linked from the topic sources. The design page describes the intended model, but the behavior you depend on for rootless Podman must be verified with the project and in a pilot on the same distribution and package set you will run in production.

Next, establish which runtimes actually read the central ranges. Ask the project and your runtime maintainers whether Podman, and any other engine you use, resolves subordinate ranges through SSSD and the FreeIPA data path, or whether it still reads /etc/subuid and /etc/subgid first. Then test whether existing local entries can coexist with centrally managed ranges on the same host, including overlapping ranges, duplicate entries and what happens to containers already running when a range changes. Treat any overlap you cannot explain as a blocker for the pilot.

Finally, confirm the allocation and scope questions and the support position. Ask how ranges are allocated for new users, whether allocation is deterministic or assigned on request, and what happens to ranges for users removed from the directory. Ask whether the feature covers service accounts and CI runners, not only interactive users, because many rootless workloads run under non-human identities. Finally, confirm with your distribution vendor and the FreeIPA project which platforms and SSSD releases support this behavior, and write the answers into your design record before the pilot begins.

Questions teams ask before running central subordinate IDs

Can our team set up central subordinate IDs for rootless containers on its own?

Yes, if you have people who already run FreeIPA and understand how Linux user namespaces map container users to host IDs. The core work is defining one ID policy, assigning non-overlapping ranges, and enrolling hosts so SSSD serves those ranges consistently. The harder part is the surrounding work: testing each distribution's Podman and shadow-utils behavior, checking that existing /etc/subuid and /etc/subgid entries do not conflict with central ranges, and proving that a rootless container on one host gets the same mapping as on another. A team without FreeIPA operations experience usually benefits from a partner for the design and pilot, then keeps the steady-state work in-house. DeployOpen can take on that split in writing.

What makes the effort larger or smaller in our environment?

Four factors matter most, and you can measure each one before asking for a quote:

Host count and diversity: more hosts and more distributions mean more test matrix, especially where container tooling or SSSD versions differ.
Existing local files: hosts that already carry hand-edited /etc/subuid entries, or ranges assigned by configuration management, need an inventory and a cutover plan so no user's mapping silently changes.
Storage layout: container image and volume storage on shared or network file systems can behave differently with user namespaces, so it needs its own verification.
Workload ownership: if many teams run rootless workloads that depend on specific IDs, the coordination effort grows even when the technical change is small.

Ask for each of these to be named in the scope so the quote reflects your actual estate.

What work recurs after central subordinate IDs go live?

Several tasks continue after rollout. Range changes are the most sensitive, because a changed range can make existing container files owned by IDs that no longer map correctly, so any change needs a plan for re-mapping or migrating affected storage. New hosts must be enrolled and checked against the policy, which is ongoing work in any growing estate. Version upgrades of FreeIPA servers and of the client packages matter too, since the subordinate ID design depends on how SSSD and the FreeIPA server handle the feature in each release. Plan for a recurring owner who reviews upgrade notes, tests a pilot host before wider rollout, and records each range decision. Recurring support can be handled through a retainer if you prefer not to staff that role.

What do we need to provide before the work starts?

Three inputs make the biggest difference. First, an inventory of every host that runs or may run rootless containers, with its distribution, container runtime, and any existing /etc/subuid or /etc/subgid content. Second, a small set of pilot hosts that represent your distributions and workloads, including at least one host that currently works well with rootless containers, so you have a baseline to compare against. Third, a named owner for ID policy who can decide range sizes, allocation rules for new hosts, and how exceptions are handled. Without that owner, technical decisions stall at the first conflict between teams. Ask the partner to list these inputs in the written scope so gaps are visible before the build starts.

Does a single host or a small lab need central subordinate ID ranges?

Usually not. Central management pays off when many hosts must use consistent ranges, so that a user, a shared volume, or a backup restored to another machine maps to the same IDs everywhere. A single host with local users and no enrolled clients can keep /etc/subuid and /etc/subgid as they are, provided the ranges do not overlap with anything else on that machine. If you already run FreeIPA for logins and that host is enrolled, adding it to the central policy costs little and avoids a second source of truth. The decision depends less on host count alone and more on whether anything else needs to predict those IDs in advance.

How does DeployOpen define the scope of this work in writing?

DeployOpen works on fixed scope where possible. Before work starts, the written scope should name the FreeIPA servers and clients in the engagement, the distributions and container runtimes covered, the pilot hosts and the acceptance checks that prove a rootless container maps the same way on each pilot host. It should also list what is excluded, such as application changes inside containers or migration of workloads owned by other teams. Deliverables, such as the ID policy document, the enrollment runbook, and the handover notes for the owner, belong in the same document, along with what happens if a pilot finds a conflict. Ongoing upgrades and recurring checks can be scoped separately as a retainer. A quote follows from that written scope, and DeployOpen does not publish a price list.

How DeployOpen scopes and delivers FreeIPA subordinate ID work

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, so subordinate ID management is designed for the hosts and FreeIPA servers you already run. The work is agreed as a fixed scope in writing before any change is made to your identity estate.

How we scope

Inventory which hosts run rootless Podman and which users need subordinate ID ranges.
Confirm the existing FreeIPA version, server layout and any local /etc/subuid entries that must be reconciled.
Agree in writing the range plan, rollout waves, test hosts and what the fixed scope excludes.

How we build

Define the central ID range assignments and the rules that map users and groups to them.
Test range allocation and rootless container startup on a non-production host before any wide rollout.
Apply the change in staged waves, checking each host against the agreed verification steps.

How we hand over

Document the range model, the management commands, and the checks used to confirm consistency across hosts.
Walk your platform and security teams through the procedure for adding users and hosts later.
Record known limits, such as hosts with local subuid entries, so your team can decide how to handle them.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Retainer work can cover FreeIPA upgrades that affect subordinate ID behavior, reviewed before rollout.
Confirm response expectations and the support boundary in the written scope before work starts.