Debian Codegraph @

upstream/debian-trixie/man2/chroot.2

raw
1 .\" Copyright (c) 1992 Drew Eckhardt ([email protected]), March 28, 1992
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" Modified by Michael Haardt <[email protected]>
6 .\" Modified 1993-07-21 by Rik Faith <[email protected]>
7 .\" Modified 1994-08-21 by Michael Chastain <[email protected]>
8 .\" Modified 1996-06-13 by aeb
9 .\" Modified 1996-11-06 by Eric S. Raymond <[email protected]>
10 .\" Modified 1997-08-21 by Joseph S. Myers <[email protected]>
11 .\" Modified 2004-06-23 by Michael Kerrisk <[email protected]>
12 .\"
13 .TH chroot 2 2024-05-02 "Linux man-pages 6.9.1"
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 .P
23 .BI "int chroot(const char *" path );
24 .fi
25 .P
26 .RS -4
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
29 .RE
30 .P
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 .P
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 .P
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 .P
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 .P
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 .P
86 .in +4n
87 .EX
88 mkdir foo; chroot foo; cd ..
89 .EE
90 .in
91 .P
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 None.
140 .SH HISTORY
141 SVr4, 4.4BSD, SUSv2 (marked LEGACY).
142 This function is not part of POSIX.1-2001.
143 .\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions.
144 .\" X/OPEN does not document EIO, ENOMEM or EFAULT error conditions.
145 .SH NOTES
146 A child process created via
147 .BR fork (2)
148 inherits its parent's root directory.
149 The root directory is left unchanged by
150 .BR execve (2).
151 .P
152 The magic symbolic link,
153 .IR /proc/ pid /root ,
154 can be used to discover a process's root directory; see
155 .BR proc (5)
156 for details.
157 .P
158 FreeBSD has a stronger
159 .BR jail ()
160 system call.
161 .SH SEE ALSO
162 .BR chroot (1),
163 .BR chdir (2),
164 .BR pivot_root (2),
165 .BR path_resolution (7),
166 .BR switch_root (8)