man2/chroot.2

   1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified by Michael Haardt <michael@moria.de>
   6 .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
   7 .\" Modified 1994-08-21 by Michael Chastain <mec@shell.portal.com>
   8 .\" Modified 1996-06-13 by aeb
   9 .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
  10 .\" Modified 1997-08-21 by Joseph S. Myers <jsm28@cam.ac.uk>
  11 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  12 .\"
  13 .TH CHROOT 2 2021-03-22 "Linux man-pages (unreleased)"
  14 .SH NAME
  15 chroot \- change root directory
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <unistd.h>
  22 .PP
  23 .BI "int chroot(const char *" path );
  24 .fi
  25 .PP
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .PP
  31 .BR chroot ():
  32 .nf
  33     Since glibc 2.2.2:
  34         _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
  35             || /* Since glibc 2.20: */ _DEFAULT_SOURCE
  36             || /* Glibc <= 2.19: */ _BSD_SOURCE
  37     Before glibc 2.2.2:
  38         none
  39 .fi
  40 .SH DESCRIPTION
  41 .BR chroot ()
  42 changes the root directory of the calling process to that specified in
  43 .IR path .
  44 This directory will be used for pathnames beginning with \fI/\fP.
  45 The root directory is inherited by all children of the calling process.
  46 .PP
  47 Only a privileged process (Linux: one with the
  48 .B CAP_SYS_CHROOT
  49 capability in its user namespace) may call
  50 .BR chroot ().
  51 .PP
  52 This call changes an ingredient in the pathname resolution process
  53 and does nothing else.
  54 In particular, it is not intended to be used
  55 for any kind of security purpose, neither to fully sandbox a process nor
  56 to restrict filesystem system calls.
  57 In the past,
  58 .BR chroot ()
  59 has been used by daemons to restrict themselves prior to passing paths
  60 supplied by untrusted users to system calls such as
  61 .BR open (2).
  62 However, if a folder is moved out of the chroot directory, an attacker
  63 can exploit that to get out of the chroot directory as well.
  64 The easiest way to do that is to
  65 .BR chdir (2)
  66 to the to-be-moved directory, wait for it to be moved out, then open a
  67 path like ../../../etc/passwd.
  68 .PP
  69 .\" This is how the "slightly trickier variation" works:
  70 .\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142
  71 A slightly
  72 trickier variation also works under some circumstances if
  73 .BR chdir (2)
  74 is not permitted.
  75 If a daemon allows a "chroot directory" to be specified,
  76 that usually means that if you want to prevent remote users from accessing
  77 files outside the chroot directory, you must ensure that folders are never
  78 moved out of it.
  79 .PP
  80 This call does not change the current working directory,
  81 so that after the call \(aq\fI.\fP\(aq can
  82 be outside the tree rooted at \(aq\fI/\fP\(aq.
  83 In particular, the superuser can escape from a "chroot jail"
  84 by doing:
  85 .PP
  86 .in +4n
  87 .EX
  88 mkdir foo; chroot foo; cd ..
  89 .EE
  90 .in
  91 .PP
  92 This call does not close open file descriptors, and such file
  93 descriptors may allow access to files outside the chroot tree.
  94 .SH RETURN VALUE
  95 On success, zero is returned.
  96 On error, \-1 is returned, and
  97 .I errno
  98 is set to indicate the error.
  99 .SH ERRORS
 100 Depending on the filesystem, other errors can be returned.
 101 The more general errors are listed below:
 102 .TP
 103 .B EACCES
 104 Search permission is denied on a component of the path prefix.
 105 (See also
 106 .BR path_resolution (7).)
 107 .\" Also search permission is required on the final component,
 108 .\" maybe just to guarantee that it is a directory?
 109 .TP
 110 .B EFAULT
 111 .I path
 112 points outside your accessible address space.
 113 .TP
 114 .B EIO
 115 An I/O error occurred.
 116 .TP
 117 .B ELOOP
 118 Too many symbolic links were encountered in resolving
 119 .IR path .
 120 .TP
 121 .B ENAMETOOLONG
 122 .I path
 123 is too long.
 124 .TP
 125 .B ENOENT
 126 The file does not exist.
 127 .TP
 128 .B ENOMEM
 129 Insufficient kernel memory was available.
 130 .TP
 131 .B ENOTDIR
 132 A component of
 133 .I path
 134 is not a directory.
 135 .TP
 136 .B EPERM
 137 The caller has insufficient privilege.
 138 .SH STANDARDS
 139 SVr4, 4.4BSD, SUSv2 (marked LEGACY).
 140 This function is not part of POSIX.1-2001.
 141 .\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions.
 142 .\" X/OPEN does not document EIO, ENOMEM or EFAULT error conditions.
 143 .SH NOTES
 144 A child process created via
 145 .BR fork (2)
 146 inherits its parent's root directory.
 147 The root directory is left unchanged by
 148 .BR execve (2).
 149 .PP
 150 The magic symbolic link,
 151 .IR /proc/[pid]/root ,
 152 can be used to discover a process's root directory; see
 153 .BR proc (5)
 154 for details.
 155 .PP
 156 FreeBSD has a stronger
 157 .BR jail ()
 158 system call.
 159 .SH SEE ALSO
 160 .BR chroot (1),
 161 .BR chdir (2),
 162 .BR pivot_root (2),
 163 .BR path_resolution (7),
 164 .BR switch_root (8)