Module idmap 

Deciding whether a sandbox needs raw.idmap.

The requirement is only ever that a host uid/gid lands on a guest uid/gid so a bind mount is writable. Three hosts, three answers:

• A host whose /etc/subuid gives root a range that does NOT contain the uid (plus a root:1000:1 delegation): the default map puts the container elsewhere, and raw.idmap is what pulls the id through.
• A nested box where root’s range starts at 0: the default map is already the identity, and asking for raw.idmap is refused (“Host ID is in the range of subids”).
• macOS and its isb machine VM: bind sources are the Mac home over Apple’s virtiofs, which reports every file as owned by whoever asks and writes as the Mac user, so every guest uid can already write them.

Only a real RANGE (count > 1) counts. A root:1000:1 line is the delegation that permits raw.idmap to map 1000 at all, not a range the default map draws from; treating it as one answers “not needed” on exactly the host that needs it.

Structs

SubIds

Host facts that decide the idmap. Read from /etc/subuid and /etc/subgid (empty where those do not exist).

Constants

CALLER_OWNED_ENV

Set in the isb machine VM, whose bind sources are the shared Mac home.

VM_IDMAP_MIN_INCUS

The oldest incus verified to hand a VM’s raw.idmap to virtiofsd as --translate-uid/--translate-gid (7.5.1). An older or unreadable version may ignore the key and share the host directory untranslated, so isb refuses rather than guess.

Functions

in_subid_range

Whether id falls inside a subordinate id RANGE (count > 1) owned by owner (root or 0) in subuid/subgid file content.

incus_translates_vm_shares

Whether server_version (environment.server_version, e.g. 7.5.1) is at least VM_IDMAP_MIN_INCUS.

invoking_ids

The (uid, gid) of the user running isb.

plan_container

What a container spec decides about raw.idmap: the mode (for the plan’s “unset by hand” note, none for {raw: ...}) and the value to set.

plan_vm

What a VM spec decides about raw.idmap: the mode that applies (for the plan’s “unset by hand” note) and the value to set. A VM with no host bind mount needs neither. An incus that may not translate VM shares is an error unless the spec opts out with idmap: none, which warns.

resolve

The raw.idmap value for a spec on this host, or None if it should not be set.

resolve_vm

The raw.idmap value for a VM that bind-mounts host directories, or None when the spec opts out (idmap: none).

vm_service_ids

The guest (uid, gid) a VM’s host shares map to by default: the service user’s numeric user: (1000 or 1000:1000), root when it is unset or root, and 1000 for a named user (the dev user of dev-base).