XBPS-UCHROOT(1)

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

💖 NAME 💖

okay so bestie, this is xbps-uchroot(1) from the General Commands Manual, and it's literally the XBPS utility to chroot and bind mount with Linux namespaces. iconic behavior, no cap.

🦋 SYNOPSIS 🦋

xbps-uchroot [OPTIONS] CHROOTDIR COMMAND [ARGS]

That's the whole vibe: options first, then CHROOTDIR, then COMMAND, then ARGS. Slay.

✨ DESCRIPTION ✨

The xbps-uchroot utility allows users to chroot and automatically bind mount required pseudo-filesystems (/dev, /dev/shm, /proc and /sys) as well as user specified directories in the target CHROOTDIR to execute COMMAND. it's giving very "set up the whole little world for me" energy.

By default, xbps-uchroot uses Linux namespaces to isolate IPC, PIDs and mounts to the calling process. If you're running in a OpenVZ container, those namespace features are simply disabled. lowkey important, bestie.

🎀 OPTIONS 🎀

  • -B src:dest — Bind mounts src into CHROOTDIR/dest in read-only mode. This option may be specified multiple times. Please note that both src and dest must be absolute paths and must exist. don't skip the absolute-path part, fr fr.
  • -b src:dest — Bind mounts src into CHROOTDIR/dest. This option may be specified multiple times. Please note that both src and dest must be absolute paths and must exist. same rules, just not read-only.
  • -O — Setups a temporary directory and then creates an overlay layer (via overlayfs) with the lowerdir set to CHROOTDIR. Useful to create a temporary tree that does not preserve changes in CHROOTDIR. temporary tree, no permanence, we love a clean exit.
  • -o opts — Arguments passed to the tmpfs mount, if the -O and -t options are specified. This expects the same arguments that are accepted as options in tmpfs, as explained in mount(1). iykyk.
  • -t — This makes the temporary directory to be mounted in tmpfs, so that everything is stored in RAM. Note that this is only useful if used with the -O option (overlayfs). RAM girlies rise.
  • -- — Stop interpreting following arguments as options. This option is useful if some of ARGS are options passed to COMMAND. very "don't talk to me, talk to my COMMAND" of it.

💀 EXIT STATUS 💀

A descriptive error message will be printed to stderr if the error originates from xbps-uchroot. Otherwise, the error comes from COMMAND. so check who's actually throwing the error before you spiral.

🔒 SECURITY 🔒

The xbps-uchroot executable must be setgid to function properly and shall only be executable by a specific group to avoid security issues (4750). bestie, this is not a vibe check, this is a security note — do not play with it.

🧚 NOTES 🧚

The xbps-uchroot utility uses Linux specific features (namespaces) and it's not meant to be portable to other Operating Systems. The following kernel options must be enabled:

CONFIG_NAMESPACES
CONFIG_IPC_NS
CONFIG_PID_NS
CONFIG_UTS_NS
CONFIG_OVERLAY_FS

no cap, that list is mandatory.

🌈 SEE ALSO 🌈

the whole friend group, honestly.

👑 AUTHORS 👑

Juan Romero Pardines <xtraeme@gmail.com> — the author, the moment, the icon.

🙈 BUGS 🙈

Probably, but I try to make this not happen. Use it under your own responsibility and enjoy your life. cute, chaotic, responsible-ish.

Report bugs at https://github.com/void-linux/xbps/issues

Source/version/date cute sign-off: Debian, Feb 9, 2023, XBPS-UCHROOT(1). That's the tea, bestie — go chroot something iconic 💅✨

📦 where this page comes from