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