https://github.com/fermitools/static-subid
Assign deterministic subordinate UID/GID ranges
https://github.com/fermitools/static-subid
user-namespaces
Last synced: about 2 months ago
JSON representation
Assign deterministic subordinate UID/GID ranges
- Host: GitHub
- URL: https://github.com/fermitools/static-subid
- Owner: fermitools
- License: other
- Created: 2026-02-06T18:53:21.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T18:21:32.000Z (3 months ago)
- Last Synced: 2026-03-05T21:39:34.516Z (3 months ago)
- Topics: user-namespaces
- Language: C
- Homepage:
- Size: 55.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: docs/README.md
- License: LICENSE
Awesome Lists containing this project
README
# static-subid
Deterministic subordinate UID/GID assignment for unprivileged containers.
## Overview
`static-subid` calculates **predictable** subordinate UID and GID ranges for Linux users based on their UID, ensuring consistent ID mappings across multiple systems.
Unlike shadow-utils' sequential allocation (which depends on creation order), `static-subid` uses a deterministic formula that guarantees the same user UID always receives the same subordinate ID range.
Subordinate IDs enable user namespaces for unprivileged container runtimes (Podman, Docker rootless mode, LXC) by mapping container UIDs/GIDs to host subordinate IDs without requiring root privileges.
## Features
- **Deterministic allocation**: Same UID → same subordinate ID range on every system
- **Idempotent**: Safe to run multiple times, no duplicate ranges
- **Fleet-friendly**: Consistent mappings across centrally managed systems
- **Configurable**: Flexible range sizing and allocation policies
## Important Warnings
### Do Not Mix with shadow-utils
**WARNING**: `static-subid` uses a different allocation algorithm than shadow-utils `useradd` auto-assignment.
**DO NOT MIX** `static-subid` with shadow-utils auto-assignment on the same system or across systems sharing `/etc/subuid`/`/etc/subgid` via network storage (NFS, etc.). Mixing allocation methods **will cause subordinate ID range conflicts and overlaps**!
Choose one method and use it consistently across your environment.
To disable shadow-utils auto-assignment, set `SUB_UID_COUNT` and `SUB_GID_COUNT` to `0` in `/etc/login.defs`.
### Security Considerations
- Configuration files must be root-owned and not world-writable
- Range overlaps can lead to container escapes and privilege escalation
- The `ALLOW_SUBID_WRAP` option is a security risk - use **only** in controlled environments
## Quick Start
```bash
# Assign subordinate UIDs and GIDs to user alice
static-subid --subuid --subgid alice
# Dry-run to preview assignments
static-subid --subuid --subgid --noop alice
# View current configuration
static-subid --help --dump-config
```
## Documentation
See the `doc/` directory for detailed documentation:
- `static-subid(8)` - Command usage and options
- `static-subid.conf(5)` - Configuration file format and settings
- Architecture and deployment guides
## Requirements
- shadow-utils with subid support
- Root privileges for execution
- systemd-based system (for integration)
## Contributing
Report bugs and submit patches via https://github.com/fermitools/static-subid/