{
    "mode": "info",
    "parameter": "chroot",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/chroot/json",
    "generated": "2026-09-24T06:23:06Z",
    "sections": {
        "File: coreutils.info,  Node: chroot invocation,  Next: env invocation,  Up: Modified command invocation": {
            "content": "",
            "subsections": [
                {
                    "name": "23.1 'chroot': Run a command with a different root directory",
                    "content": "'chroot' runs a command with a specified root directory.  On many\nsystems, only the super-user can do this.(1).  Synopses:\n\nchroot OPTION NEWROOT [COMMAND [ARGS]...]\nchroot OPTION\n\nOrdinarily, file names are looked up starting at the root of the\ndirectory structure, i.e., '/'.  'chroot' changes the root to the\ndirectory NEWROOT (which must exist), then changes the working directory\nto '/', and finally runs COMMAND with optional ARGS.  If COMMAND is not\nspecified, the default is the value of the 'SHELL' environment variable\nor '/bin/sh' if not set, invoked with the '-i' option.  COMMAND must not\nbe a special built-in utility (*note Special built-in utilities::).\n\nThe program accepts the following options.  Also see *note Common\noptions::.  Options must precede operands.\n\n'--groups=GROUPS'\nUse this option to override the supplementary GROUPS to be used by\nthe new process.  The items in the list (names or numeric IDs) must\nbe separated by commas.  Use '--groups=''' to disable the\nsupplementary group look-up implicit in the '--userspec' option.\n\n'--userspec=USER[:GROUP]'\nBy default, COMMAND is run with the same credentials as the\ninvoking process.  Use this option to run it as a different USER\nand/or with a different primary GROUP.  If a USER is specified then\nthe supplementary groups are set according to the system defined\nlist for that user, unless overridden with the '--groups' option.\n\n'--skip-chdir'\nUse this option to not change the working directory to '/' after\nchanging the root directory to NEWROOT, i.e., inside the chroot.\nThis option is only permitted when NEWROOT is the old '/'\ndirectory, and therefore is mostly useful together with the\n'--groups' and '--userspec' options to retain the previous working\ndirectory.\n\nThe user and group name look-up performed by the '--userspec' and\n'--groups' options, is done both outside and inside the chroot, with\nsuccessful look-ups inside the chroot taking precedence.  If the\nspecified user or group items are intended to represent a numeric ID,\nthen a name to ID resolving step is avoided by specifying a leading '+'.\n*Note Disambiguating names and IDs::.\n\nHere are a few tips to help avoid common problems in using chroot."
                }
            ]
        },
        "To start with a simple example, make COMMAND refer to a statically": {
            "content": "linked binary.  If you were to use a dynamically linked executable, then\nyou'd have to arrange to have the shared libraries in the right place\nunder your new root directory.\n\nFor example, if you create a statically linked 'ls' executable, and\nput it in '/tmp/empty', you can run this command as root:\n\n$ chroot /tmp/empty /ls -Rl /\n\nThen you'll see output like this:\n\n/:\ntotal 1023\n-rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls\n\nIf you want to use a dynamically linked executable, say 'bash', then\nfirst run 'ldd bash' to see what shared objects it needs.  Then, in\naddition to copying the actual binary, also copy the listed files to the\nrequired positions under your intended new root directory.  Finally, if\nthe executable requires any other files (e.g., data, state, device\nfiles), copy them into place, too.\n\n'chroot' is installed only on systems that have the 'chroot'\nfunction, so portable scripts should not rely on its existence.\n\nExit status:\n\n125 if 'chroot' itself fails\n126 if COMMAND is found but cannot be invoked\n127 if COMMAND cannot be found\nthe exit status of COMMAND otherwise\n\n---------- Footnotes ----------\n\n(1) However, some systems (e.g., FreeBSD) can be configured to allow\ncertain regular users to use the 'chroot' system call, and hence to run\nthis program.  Also, on Cygwin, anyone can run the 'chroot' command,\nbecause the underlying function is non-privileged due to lack of support\nin MS-Windows.  Furthermore, the 'chroot' command avoids the 'chroot'\nsystem call when NEWROOT is identical to the old '/' directory for\nconsistency with systems where this is allowed for non-privileged users.\n",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": []
}