Index for Section 8

Alphabetical listing for C

Bottom of page

chroot(8)
NAME
  chroot - 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 executes. (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 system 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
   1.  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 (/).

   2.  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
       following.  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.

   3.  To create a file relative to the original root rather than the new
       one, use this syntax and enter:

	    chroot  directory command > file

FILES
  /usr/sbin/chroot
      Specifies the command path.

SEE ALSO
  Commands: cc(1), cpp(1), ls(1), sh(1)

  Functions: chdir(2), chroot(2) exec(2)

Index for Section 8

Alphabetical listing for C

Top of page