chroot(8)chroot(8)NAMEchroot - Changes the root directory of a command
SYNOPSIS
/usr/sbin/chroot directory command
DESCRIPTION
Only root can use the chroot command. The chroot command changes the
root directory from / to the specified directory when the command exe‐
cutes. (The command specified includes both the command name as well as
any arguments.) Consequently, the root of any path (as indicated by the
first / (slash) in the pathname) changes to directory and is always
relative to the current root. Even if the chroot command is in effect,
directory is relative to the current root of the running process.
Several programs may not operate properly after chroot executes. You
must ensure that all vital files are present in the new root file sys‐
tem and the relevant pathnames for the files map correctly in the new
root file system.
For example, the ls -l command fails to give user and group names if
the new root file system does not have a copy of the /etc/passwd and
/etc/group files. If the /etc/passwd and /etc/group files in the new
root file system represent different user and group names, then the
output from the ls -l command will be based on those names, not the
ones for the system's own name database. Utilities that depend on
description files produced by the ctab command may also fail if the
required description files are not present in the new root file system.
The chroot program uses the execv() function to invoke the specified
command. As a consequence, the command specified must be an executable
binary, not a shell script. Further, if the program requires indirect
loading (for example, due to unresolved symbols requiring use of a
shared library), then /sbin/loader as well as any files it requires
(for example, shared libraries) must be present in the new root file
system in the appropriate locations.
CAUTIONS
If special files in the new root have different major and minor device
numbers than the initial root directory, it is possible to overwrite
the file system.
EXAMPLES
To run a subshell with another file system as the root, enter a command
similar to the following. Note in this example, the file system is on
the /dev/disk/dsk13a device and is mounted to /mnt/dsk13a:
chroot /mnt/dsk13a /sbin/sh
The command shown in the previous example specifies a change
from the current root file system to the one mounted on
/mnt/dsk13a while /sbin/sh (which itself is relative to the new
root file system) executes. When /bin/sh executes, the original
root file system is inaccessible. The file system mounted on
/mnt/dsk13a must contain the standard directories of a root file
system. In particular, the shell looks for commands in /sbin,
/bin, and /usr/bin (among others) on the new root file system.
Running the /sbin/sh command creates a subshell that runs as a
separate process from the original shell. Press Ctrl-d to exit
the subshell and return to the original shell. This restores
the environment of the original shell, including the meanings of
the current directory (.) and the root directory (/). To run a
command in another root file system and save the output on the
initial root file system, enter a command similar to the follow‐
ing. Note in this example, the file system is on the
/dev/disk/dsk13a device and is mounted to /mnt/dsk13a:
chroot /mnt/dsk13a /bin/cc -E /u/bob/prog.c > prep.out
The previous command runs the /bin/cc command with /mnt/dsk13a
as the specified root file system. It compiles the
/mnt/dsk13a/u/bob/prog.c file, reads the #include files from the
/mnt/dsk13a/usr/include directory, and puts the compiled text in
the prep.out file on the initial root file system. To create a
file relative to the original root rather than the new one, use
this syntax and enter:
chroot directory command > file
FILES
Specifies the command path.
SEE ALSO
Commands: cc(1), cpp(1), ls(1), sh(1)
Functions: chdir(2), chroot(2)exec(2)chroot(8)