diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/chroot.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/chroot.2 | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/chroot.2 b/upstream/debian-bookworm/man2/chroot.2 new file mode 100644 index 00000000..88a1dff3 --- /dev/null +++ b/upstream/debian-bookworm/man2/chroot.2 @@ -0,0 +1,164 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt <michael@moria.de> +.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1994-08-21 by Michael Chastain <mec@shell.portal.com> +.\" Modified 1996-06-13 by aeb +.\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 1997-08-21 by Joseph S. Myers <jsm28@cam.ac.uk> +.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH chroot 2 2023-02-05 "Linux man-pages 6.03" +.SH NAME +chroot \- change root directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.PP +.BI "int chroot(const char *" path ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR chroot (): +.nf + Since glibc 2.2.2: + _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || /* Since glibc 2.20: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.2.2: + none +.fi +.SH DESCRIPTION +.BR chroot () +changes the root directory of the calling process to that specified in +.IR path . +This directory will be used for pathnames beginning with \fI/\fP. +The root directory is inherited by all children of the calling process. +.PP +Only a privileged process (Linux: one with the +.B CAP_SYS_CHROOT +capability in its user namespace) may call +.BR chroot (). +.PP +This call changes an ingredient in the pathname resolution process +and does nothing else. +In particular, it is not intended to be used +for any kind of security purpose, neither to fully sandbox a process nor +to restrict filesystem system calls. +In the past, +.BR chroot () +has been used by daemons to restrict themselves prior to passing paths +supplied by untrusted users to system calls such as +.BR open (2). +However, if a folder is moved out of the chroot directory, an attacker +can exploit that to get out of the chroot directory as well. +The easiest way to do that is to +.BR chdir (2) +to the to-be-moved directory, wait for it to be moved out, then open a +path like ../../../etc/passwd. +.PP +.\" This is how the "slightly trickier variation" works: +.\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142 +A slightly +trickier variation also works under some circumstances if +.BR chdir (2) +is not permitted. +If a daemon allows a "chroot directory" to be specified, +that usually means that if you want to prevent remote users from accessing +files outside the chroot directory, you must ensure that folders are never +moved out of it. +.PP +This call does not change the current working directory, +so that after the call \[aq]\fI.\fP\[aq] can +be outside the tree rooted at \[aq]\fI/\fP\[aq]. +In particular, the superuser can escape from a "chroot jail" +by doing: +.PP +.in +4n +.EX +mkdir foo; chroot foo; cd .. +.EE +.in +.PP +This call does not close open file descriptors, and such file +descriptors may allow access to files outside the chroot tree. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Depending on the filesystem, other errors can be returned. +The more general errors are listed below: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.\" Also search permission is required on the final component, +.\" maybe just to guarantee that it is a directory? +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of +.I path +is not a directory. +.TP +.B EPERM +The caller has insufficient privilege. +.SH STANDARDS +SVr4, 4.4BSD, SUSv2 (marked LEGACY). +This function is not part of POSIX.1-2001. +.\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions. +.\" X/OPEN does not document EIO, ENOMEM or EFAULT error conditions. +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's root directory. +The root directory is left unchanged by +.BR execve (2). +.PP +The magic symbolic link, +.IR /proc/[pid]/root , +can be used to discover a process's root directory; see +.BR proc (5) +for details. +.PP +FreeBSD has a stronger +.BR jail () +system call. +.SH SEE ALSO +.BR chroot (1), +.BR chdir (2), +.BR pivot_root (2), +.BR path_resolution (7), +.BR switch_root (8) |