buildah-unshare(1)

💖 buildah-unshare — from the buildah manual 💖

okay bestie, sit down, hydrate, and let me tell you about the most underrated little glow-up in the whole buildah family: buildah-unshare. she runs a command inside a modified user namespace and honestly? she's iconic for it. 🫶

---

✨ NAME ✨

buildah-unshare — run a command inside of a modified user namespace. that's it, that's the whole job. slay. 💅

---

✨ SYNOPSIS ✨

buildah unshare [options] [--] [command]

---

✨ DESCRIPTION ✨

so what she does is launch a process — by default it's $SHELL, no cap — inside a brand new user namespace. 🌈 and here's the cute part: the namespace is configured so that the invoking user's UID and primary GID show up as UID 0 and GID 0 respectively. like, you're literally root in there, bestie. main character energy. 👑

and any ranges that match that user and group over in /etc/subuid and /etc/subgid also get mapped in as themselves, with a lil assist from the newuidmap(1) and newgidmap(1) helpers. teamwork makes the dream work fr fr. 🧚

now, why do you care? buildah unshare is your girl for troubleshooting unprivileged operations, and for manually clearing storage and other data related to images and containers. very "let me just clean up my room" of her. 🎀

she's also the move if you wanna use the buildah mount command. like — if an unprivileged user wants to mount and work with a container, they need to execute buildah unshare first. periodt. running buildah mount just fails for unprivileged users unless they're already inside a buildah unshare session. no session, no mount. that's the vibe check. 💀

---

✨ OPTIONS ✨

• --mount, -m [VARIABLE=]containerNameOrID — mounts the containerNameOrID container while your command runs, and sets the environment variable VARIABLE to the path of the mountpoint. if you don't give her a VARIABLE, it defaults to containerNameOrID — which, heads up, might not actually be a valid name for an environment variable. so like, name it yourself if you're feeling fancy. 🙈

---

✨ EXAMPLE ✨

here's the cute stuff, copy-paste away bestie:

buildah unshare id

buildah unshare pwd

buildah unshare cat /proc/self/uid_map /proc/self/gid_map

buildah unshare rm -fr $HOME/.local/share/containers/storage
/run/user/`id -u`/run

buildah unshare --mount containerID sh -c 'cat ${containerID}/etc/os-
release'

buildah unshare --mount root=containerID sh -c 'cat ${root}/etc/os-
release'

and if you wanna use buildah with a mount command, you can create a script that looks something like this:

cat > buildah-script.sh << _EOF
#!/bin/bash
ctr=$(buildah from scratch)
mnt=$(buildah mount $ctr)
dnf -y install --installroot=$mnt --use-host-config --setopt "*.countme=false" PACKAGES
dnf -y clean all --installroot=$mnt
buildah config --entrypoint="/bin/PACKAGE" --env "FOO=BAR" $ctr
buildah commit $ctr imagename
buildah unmount $ctr
_EOF
chmod +x buildah-script.sh

then execute it with:

buildah unshare ./buildah-script.sh

---

✨ SEE ALSO ✨

buildah(1), buildah-mount(1), namespaces(7), newuidmap(1), newgidmap(1), user_namespaces(7)

---

and that's the whole page, bestie!! 💜 go forth and unshare responsibly. this lil number comes to you from the buildah crew, dated June 2018 — yeah she's an elder but she still eats. 🍓 bye bb, ily, go mount something. ✨🦋💖