.Dd Feb 9, 2023
.Dt XBPS-UCHROOT 1
.Os
.Sh NAME
.Nm xbps-uchroot
.Nd XBPS utility to chroot and bind mount with Linux namespaces
.Sh SYNOPSIS
.Nm
.Op OPTIONS
.Ar CHROOTDIR
.Ar COMMAND
.Op ARGS
.Sh DESCRIPTION
The
.Nm
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
.Ar CHROOTDIR
to execute
.Ar COMMAND .
.Pp
The
.Nm
utility uses by default Linux namespaces to isolate IPC, PIDs and mounts to
the calling process. If running in a OpenVZ container, these namespace features
are simply disabled.
.Sh OPTIONS
.Bl -tag -width -x
.It Fl B Ar src:dest
Bind mounts
.Ar src
into
.Ar CHROOTDIR/dest
in read-only mode.
This option may be specified multiple times.
Please note that both
.Ar src
and
.Ar dest
must be absolute paths and must exist.
.It Fl b Ar src:dest
Bind mounts
.Ar src
into
.Ar CHROOTDIR/dest .
This option may be specified multiple times.
Please note that both
.Ar src
and
.Ar dest
must be absolute paths and must exist.
.It Fl 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.
.It Fl o Ar opts
Arguments passed to the tmpfs mount, if the
.Fl O
and
.Fl t
options are specified.
This expects the same arguments that are accepted as options in tmpfs, as explained in
.Xr mount 1 .
.It Fl 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
.Fl O
option (overlayfs).
.It Fl -
Stop interpreting following arguments as options.
This option is useful if some of
.Ar ARGS
are options passed to
.Ar COMMAND .
.El
.Sh SECURITY
The
.Nm
executable must be setgid to function properly and shall only be executable by a specific
group to avoid security issues (4750).
.Sh NOTES
The
.Nm
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:
.Pp
.Bl -tag -width CONFIG_NAMESPACES -compact -offset indent
.It Sy CONFIG_NAMESPACES
.It Sy CONFIG_IPC_NS
.It Sy CONFIG_PID_NS
.It Sy CONFIG_UTS_NS
.It Sy CONFIG_OVERLAY_FS
.El
.Sh SEE ALSO
.Xr xbps-alternatives 1 ,
.Xr xbps-checkvers 1 ,
.Xr xbps-create 1 ,
.Xr xbps-dgraph 1 ,
.Xr xbps-digest 1 ,
.Xr xbps-fbulk 1 ,
.Xr xbps-fetch 1 ,
.Xr xbps-install 1 ,
.Xr xbps-pkgdb 1 ,
.Xr xbps-query 1 ,
.Xr xbps-reconfigure 1 ,
.Xr xbps-rindex 1 ,
.Xr xbps-uunshare 1 ,
.Xr xbps.d 5
.Sh AUTHORS
.An Juan Romero Pardines Aq Mt xtraeme@gmail.com
.Sh BUGS
Probably, but I try to make this not happen. Use it under your own
responsibility and enjoy your life.
.Pp
Report bugs at
.Lk https://github.com/void-linux/xbps/issues