Gnu/coreutils/chroot-invocation
Next: env invocation, Up: Modified command invocation [Contents][Index]
23.1 chroot
: Run a command with a different root directory
chroot
runs a command with a specified root directory.
On many systems, only the super-user can do this.5.
Synopses:
chroot option newroot [command [args]…] chroot option
Ordinarily, file names are looked up starting at the root of the
directory structure, i.e., /
. chroot
changes the root to
the directory newroot
(which must exist), then changes the working
directory to /
, and finally runs command
with optional args
.
If command
is not specified, the default is the value of the SHELL
environment variable or /bin/sh
if not set, invoked with the
-i
option.
command
must not be a special built-in utility
(see Special built-in utilities).
The program accepts the following options. Also see Common options. Options must precede operands.
- ‘
--groups=groups
’ Use this option to override the supplementary
groups
to be used by the new process. The items in the list (names or numeric IDs) must be separated by commas. Use ‘--groups=
’ to disable the supplementary group look-up implicit in the--userspec
option.- ‘
--userspec=user[:group]
’ By default,
command
is run with the same credentials as the invoking process. Use this option to run it as a differentuser
and/or with a different primarygroup
. If auser
is specified then the supplementary groups are set according to the system defined list for that user, unless overridden with the--groups
option.- ‘
--skip-chdir
’ Use this option to not change the working directory to
/
after changing the root directory tonewroot
, i.e., inside the chroot. This option is only permitted whennewroot
is the old/
directory, and therefore is mostly useful together with the--groups
and--userspec
options to retain the previous working directory.
The user and group name look-up performed by the --userspec
and --groups
options, is done both outside and inside
the chroot, with successful look-ups inside the chroot taking precedence.
If the specified user or group items are intended to represent a numeric ID,
then a name to ID resolving step is avoided by specifying a leading ‘+
’.
See Disambiguating names and IDs.
Here are a few tips to help avoid common problems in using chroot.
To start with a simple example, make command
refer to a statically
linked binary. If you were to use a dynamically linked executable, then
you’d have to arrange to have the shared libraries in the right place under
your new root directory.
For example, if you create a statically linked ls
executable,
and put it in /tmp/empty
, you can run this command as root:
$ chroot /tmp/empty /ls -Rl /
Then you’ll see output like this:
/: total 1023 -rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls
If you want to use a dynamically linked executable, say bash
,
then first run ‘ldd bash
’ to see what shared objects it needs.
Then, in addition to copying the actual binary, also copy the listed
files to the required positions under your intended new root directory.
Finally, if the executable requires any other files (e.g., data, state,
device files), copy them into place, too.
chroot
is installed only on systems that have the
chroot
function, so portable scripts should not rely on its
existence.
Exit status:
125 if chroot itself fails 126 if command is found but cannot be invoked 127 if command cannot be found the exit status of command otherwise
Footnotes
(5)
However,
some systems (e.g., FreeBSD) can be configured to allow certain regular
users to use the chroot
system call, and hence to run this program.
Also, on Cygwin, anyone can run the chroot
command, because the
underlying function is non-privileged due to lack of support in MS-Windows.
Furthermore, the chroot
command avoids the chroot
system call
when newroot
is identical to the old /
directory for consistency
with systems where this is allowed for non-privileged users.
Next: env invocation, Up: Modified command invocation [Contents][Index]