XBPS-UUNSHARE(1)

📦 version 0.60.6, in alpine 3.24, nixos 26.05, nixpkgs unstable

💅 XBPS-UUNSHARE(1) — General Commands Manual 💅

okay so bestie, this is the manual page for xbps-uunshare — a General Commands Manual entry, no cap. Let's get into it 🫶

🌸 NAME 🌸

xbps-uunshare — the XBPS utility that chroots and bind mounts using Linux user namespaces. literally her whole personality 💖

✨ SYNOPSIS ✨

xbps-uunshare [OPTIONS] CHROOTDIR COMMAND [ARGS]

🦋 DESCRIPTION 🦋

So xbps-uunshare lets you chroot into CHROOTDIR and bind mount the pseudo-filesystems it needs — that's /dev, /proc and /sys, the holy trinity — and then run COMMAND in there. it's giving "tiny container but make it effortless" 💅

By default it uses Linux namespaces to isolate IPC, PIDs and mounts to the calling process. And the iconic part? Thanks to user_namespaces(7), you don't need any privilege to spin up an isolated lightweight container. no root, no drama, just vibes ✨

🎀 OPTIONS 🎀

  • -b src:dest — bind mounts src into CHROOTDIR/dest. you can pass this option as many times as you want, she's not jealous 🫶 but heads up: both src and dest must be absolute paths, and both must exist. non-negotiable, bestie.
  • -- — stops interpreting the following arguments as options. super useful when some of your ARGS are actually options meant for COMMAND. the way it just says "ok these are for her, not for me" 😌

⭐ EXIT STATUS ⭐

If the error originates from xbps-uunshare itself, you get a descriptive error message printed to stderr. she tells you what went wrong, she's communicative 💖

  • 99 — failed to unshare from the current namespace (see NOTES). yeah… that one.

Otherwise, whatever error you see came from COMMAND. not her fault, blame the child 😭

💀 NOTES 💀

xbps-uunshare uses Linux specific features (namespaces) and is not meant to be portable to other Operating Systems. so like, don't ask her to run on macOS, she will simply pass away 🙈

The following kernel options must be enabled:

CONFIG_NAMESPACES
CONFIG_IPC_NS
CONFIG_USER_NS
CONFIG_UTS_NS

if those aren't on bestie, it's not happening. check your config, slay responsibly 👑

🌈 SEE ALSO 🌈

xbps-alternatives(1), xbps-checkvers(1), xbps-create(1), xbps-dgraph(1), xbps-digest(1), xbps-fbulk(1), xbps-fetch(1), xbps-install(1), xbps-pkgdb(1), xbps-query(1), xbps-reconfigure(1), xbps-rindex(1), xbps-uchroot(1), xbps.d(5)

the whole friend group fr fr 🫶

👑 AUTHORS 👑

Juan Romero Pardines <xtraeme@gmail.com> — the main character who made this happen 💜

🍓 BUGS 🍓

Probably, but I try to make this not happen. Use it under your own responsibility and enjoy your life. (yes that's the actual energy of the original and honestly? iconic.)

Report bugs at https://github.com/void-linux/xbps/issues — she reads them, fr fr 🧚

and that's the whole page bestie, mwah 💋

sign-off: this gorgeous piece of documentation shipped with Debian, dated Feb 9, 2023, and she ate every single time ⭐🔥

📦 where this page comes from