Debian Codegraph @

upstream/debian-unstable/man2/chroot.2

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