coreutils: chroot invocation

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