ID-Mapped Mounts

Overview

BeeGFS supports ID-mapped mounts, a Linux kernel feature introduced in kernel 5.12 that provides per-mount user and group ID translation at the VFS (Virtual File System) layer. This feature allows you to attach ID mapping information to a mount, enabling flexible translation between different user/group ID spaces without modifying the actual files stored on BeeGFS storage servers.

Unlike user namespaces which provide broad ID isolation for processes, ID-mapped mounts offer a more granular, mount-specific solution for ID translation. This makes them particularly useful for containerized environments and multi-tenant systems where different hosts may have incompatible UID/GID mappings for the same logical users.

Note

ID-mapped mounts work by intercepting and translating user/group IDs at the mount point level. The translation is bidirectional: existing files are shown with translated ownership, and newly created files have their creator IDs reverse-mapped before being stored.

Note

ID-mapped mounts require Linux kernel 5.12 or higher. While the core functionality was introduced in 5.12, kernel 6.3 added support for tmpfs ID-mapped mounts, which is important for containerized environments that need to share tmpfs between sandboxes. Kernels 6.3+ are recommended for full container integration support.

Use Cases

Container Workflows

ID-mapped mounts allow containers to access shared BeeGFS storage with translated file ownership. For example, files owned by a host user (UID 1001) can appear as owned by a different user (UID 0) through mount-level translation, enabling containers to work with files they wouldn’t otherwise have access to.

Multi-tenant Environments

Multiple hosts or environments with different /etc/passwd layouts can access the same files with appropriate ownership translation.

Portable Storage

Storage devices can be mounted with different ID mappings across different systems without changing on-disk ownership.

User Migration

Large filesets can have their apparent ownership changed instantly without modifying actual file ownership on metadata or storage servers.

Configuration

Enabling ID-Mapped Mount Support

ID-mapped mount support is determined at compile time. When the BeeGFS client kernel module is built on a kernel that provides FS_ALLOW_IDMAP (Linux 5.12+), ID-mapped mount support is enabled by default — no runtime configuration is required.

To disable ID-mapped mount support at compile time, pass the BEEGFS_DISABLE_IDMAPPING=1 flag when building the client module:

# Build with ID-mapped mount support disabled
make client BEEGFS_DISABLE_IDMAPPING=1

When BEEGFS_DISABLE_IDMAPPING=1 is set, all idmapping code paths are removed from the compiled module and the FS_ALLOW_IDMAP flag is not set on the filesystem type. This means ID-mapped bind mounts cannot be created on any BeeGFS mount served by that module.

Configuration Details:

  • Default: Enabled (when kernel supports FS_ALLOW_IDMAP)

  • Required kernel: 5.12 or higher

  • Recommended kernel: 6.3 or higher for full container integration support, where each mount can define its own per-mount ID mapping via struct mnt_idmap

  • Rebuild required: A module rebuild and reload is required to change this setting, since it is a compile-time option

Verifying Configuration

You can verify the current ID-mapping build configuration through the build_config procfs entry:

# Check the ID-mapping build configuration
cat /proc/fs/beegfs/*/build_config

# Example output when enabled (kernel supports FS_ALLOW_IDMAP, idmapping not disabled):
KERNEL_HAS_FS_ALLOW_IDMAP = 1
BEEGFS_DISABLE_IDMAPPING = 0
FS_ALLOW_IDMAP = 1

# Example output when disabled at compile time:
KERNEL_HAS_FS_ALLOW_IDMAP = 1
BEEGFS_DISABLE_IDMAPPING = 1
FS_ALLOW_IDMAP = 0

# Example output on a kernel without FS_ALLOW_IDMAP support (< 5.12):
KERNEL_HAS_FS_ALLOW_IDMAP = 0
BEEGFS_DISABLE_IDMAPPING = 0
FS_ALLOW_IDMAP = 0

Fields:

  • KERNEL_HAS_FS_ALLOW_IDMAP: Whether the kernel provides FS_ALLOW_IDMAP (requires Linux 5.12+)

  • BEEGFS_DISABLE_IDMAPPING: Whether the module was built with BEEGFS_DISABLE_IDMAPPING=1

  • FS_ALLOW_IDMAP: The effective ID-mapping capability — 1 only when the kernel supports it and it was not disabled at compile time

Creating ID-Mapped Mounts

ID-Mapped Bind Mounts

The most common way to create ID-mapped views is using bind mounts. Modern mount utilities provide two syntax options:

Modern Syntax

# Create an ID-mapped bind mount using --map-users and --map-groups
# Maps host UID/GID 1001 to UID/GID 0 in the new mount
mount --bind --map-users 1001:0:1 --map-groups 1001:0:1 /mnt/beegfs /mnt/beegfs_mapped

Alternative Syntax

# Create an ID-mapped bind mount using X-mount.idmap option
# Maps host UID/GID 1001 to UID/GID 0 in the new mount (equivalent to above)
mount --bind -o X-mount.idmap="b:1001:0:1" /mnt/beegfs /mnt/beegfs_mapped

ID-mapping syntax options:

  1. –map-users and –map-groups: <outer_id>:<inner_id>:<range> - <outer_id>: User/group ID on the host system - <inner_id>: User/group ID inside the mapped mount - <range>: Number of consecutive IDs to map

  2. X-mount.idmap: "<type>:<upper_id>:<lower_id>:<range>" - <type>: Mapping type - u (UIDs only), g (GIDs only), or b (both UIDs and GIDs) - <upper_id>: First ID in the “upper” ID space (typically the host/original filesystem) - <lower_id>: First ID in the “lower” ID space (the mapped/translated view) - <range>: Number of consecutive IDs to map (starting from the specified IDs)

Bidirectional Translation:

  • Forward mapping: Files with upper_id ownership appear as lower_id in the ID-mapped mount

  • Reverse mapping: Files created in the mapped mount with lower_id are stored as upper_id on disk

Mapping Examples

Single User Mapping

# Modern syntax: Map host UID 1001 to container root (UID 0)
# Files owned by UID 1001 appear as owned by UID 0 in the mapped view
mount --bind --map-users=1001:0:1 --map-groups=1001:0:1 /mnt/beegfs /mnt/container_view

# Alternative syntax (equivalent)
mount --bind -o X-mount.idmap="b:1001:0:1" /mnt/beegfs /mnt/container_view

# X-mount.idmap: map UIDs and GIDs separately
mount --bind -o X-mount.idmap="u:1001:0:1,g:1001:0:1" /mnt/beegfs /mnt/container_view

Range Mapping

# Modern syntax: Map host UIDs 1000-1099 to container UIDs 0-99
# This creates a 100-user mapping: 1000->0, 1001->1, 1002->2, etc.
mount --bind --map-users=1000:0:100 --map-groups=1000:0:100 /mnt/beegfs /mnt/container_range

# Alternative syntax (equivalent)
mount --bind -o X-mount.idmap="b:1000:0:100" /mnt/beegfs /mnt/container_range

Example Container Integration

Podman Integration

Podman natively supports ID-mapped mounts for bind mounts:

# Run container with ID-mapped BeeGFS mount
podman run -it --rm \
  --mount "type=bind,src=/mnt/beegfs,target=/mnt/data,idmap=uids=1001-0-1;gids=1001-0-1" \
  ubuntu:24.04 bash

Inside the container, files owned by host UID 1001 will appear as owned by root (UID 0) and files created by root (UID 0) in the container will be stored as owned by UID 1001 on the file system.

File System Operations

Ownership Translation

When using ID-mapped mounts, file ownership is translated on-the-fly:

Example Scenario: - Host user alice (UID 1001) owns files on BeeGFS - ID-mapped mount: b:1001:0:1

# On the base mount
ls -l /mnt/beegfs/testfile
# -rw-r--r-- 1 alice alice 1024 Jan 15 10:30 testfile

# On the ID-mapped mount
ls -l /mnt/beegfs_mapped/testfile
# -rw-r--r-- 1 root root 1024 Jan 15 10:30 testfile

Cross-Client Consistency

ID-mapped mounts only affect the view of ownership on the specific mount point. The actual on-disk UID/GID stored on BeeGFS storage servers remains unchanged:

  • Files created through an ID-mapped mount store the correct filesystem UID/GID

  • Multiple clients accessing the same files see consistent on-disk ownership

  • Different ID-mapped views can coexist without conflicts

Permission Enforcement

BeeGFS correctly enforces permissions based on the mapped IDs:

# User with UID 1001 creates file through ID-mapped mount (appears as root)
echo "test" > /mnt/beegfs_mapped/rootfile

# Permission checks work correctly for both views:
# - On base mount: accessible to UID 1001 (alice)
# - On mapped mount: accessible to UID 0 (root)

Unmapped ID Handling

When IDs don’t have a mapping defined, they are handled specially:

# File owned by UID 2000 (not in the mapping b:1001:0:1)
ls -l /mnt/beegfs/unmapped_file
# -rw-r--r-- 1 2000 2000 1024 Jan 15 10:30 unmapped_file

# Same file in the ID-mapped mount shows as "nobody" (overflow UID)
ls -l /mnt/beegfs_mapped/unmapped_file
# -rw-r--r-- 1 nobody nobody 1024 Jan 15 10:30 unmapped_file

Overflow ID Behavior:

  • Unmapped UIDs/GIDs appear as the system overflow UID/GID (typically 65534/”nobody”)

  • Operations by unmapped users may fail with EOVERFLOW errors

  • Plan your ID mappings to cover all necessary users and groups

Limitations

Technical Limitations

Mapping Constraints

  • Maximum of 340 mapping ranges per mount (kernel limitation)

  • Mappings cannot be changed after mount creation

  • Requires CAP_SYS_ADMIN capability to create

Performance Considerations

  • Extensive mappings may have minor performance impact

  • Translation overhead is minimal for typical use cases

  • VFS-level implementation ensures efficient operation

Configuration Scope

  • ID-mapping capability is determined at compile time and applies globally to all BeeGFS mounts served by the module

  • All BeeGFS mount points on a client node share the same ID-mapping capability (either all enabled or all disabled)

  • Individual mounts can still have different ID mappings applied via X-mount.idmap or --map-users/--map-groups, but the underlying capability must be compiled into the module

  • To change the ID-mapping capability, the module must be rebuilt with or without BEEGFS_DISABLE_IDMAPPING=1 and reloaded