CHROOT(8) System Manager's Manual CHROOT(8)

chrootexecute with alternate filesystem root

chroot [--userspec=user[:group]] [-u ser] [-g roup] [-G roup[,group]…] root [program [argument]…]
chroot --skip-chdir [--userspec=user[:group]] [-u ser] [-g roup] [-G roup[,group]…] / [program [argument]…]

Sets the filesystem root to root, alters credentials as specified, then executes program arguments (SHELL -i if not specified).

User and group names are first sought in the initial root, then overriden from the alternate root. Numeric IDs are used verbatim.

=user[:group]
Become user and group (or the user's primary group if omitted).
user
Become user.
group
Become group.
, --groups=group[,group]…
Set the supplementary group list to groups.
Don't move to the root after switching root directories. Only valid when switching to the current root directory.

In which program is searched when requested, confer execvp(3).
The shell to execute for an interactive session instead of the default /bin/sh.

program wasn't found.
program exists, but couldn't be executed for a different reason.
an error occurred in chroot.
All others
returned by program.

chroot(2)

Conforms to X/Open Portability Guide Issue 2 (“XPG2”) (CB-UNIX), compatible with 4.3BSD-Reno. Long options and name resolution scheme compatible with the GNU system. Short options compatible with NetBSD 1.4.

The chroot() system call appeared in Version 7 AT&T UNIX as part of chdir(2) — "change default directory" — noting it to not be unlike that of today:

sets the root directory, the starting point for path names beginning with '/'.

chroot first appeared in CB-UNIX at or before version 2.1 as chroot(1M) — "change root directory for a command":

chroot newroot command
The page hints at special handling of " shellfile"-style commands and newroot being always relative to the real root. This is inconsistent with the Version 7 AT&T UNIX version of the chroot system call, and potentially inconsistent with CB-UNIX's own chroot(2), which says
Arguments to chroot are always absolute: no special meaning is given to inital slashes even if a chroot is currently in effect
. Which is unclear so as to meaning "path resolution is unaffected" (like in Version 7 AT&T UNIX) or "paths are always resolved from the real root". It's impossible to truly tell, but the documented behaviour is likely wrong and both are compatible with Version 7 AT&T UNIX.

CB-UNIX was, among others, the basis for AT&T System III UNIX, where it first saw light outside of AT&T with an incorrect

chroot newroot command
SYNOPSIS; — the usage string properly shows that arguments are forwarded:
chroot rootdir command arg ...
No special handling of any sort is found, and the system call resolves the names normally.

chroot(8) appears in 4.3BSD-Reno, as

chroot newroot [ command ]
With the familiar SHELL (/bin/sh) -i default.

A specification for a CB-UNIX-style(? possibly, no digital copies seem to be extant) chroot appears in X/Open Portability Guide Issue 2 (“XPG2”), but was removed in X/Open Portability Guide Issue 4 (“XPG4”).

October 26, 2022 voreutils pre-v0.0.0-latest