1.\" $OpenBSD: chroot.2,v 1.24 2022/03/31 17:27:16 naddy Exp $ 2.\" $NetBSD: chroot.2,v 1.7 1995/02/27 12:32:12 cgd Exp $ 3.\" 4.\" Copyright (c) 1983, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)chroot.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: March 31 2022 $ 34.Dt CHROOT 2 35.Os 36.Sh NAME 37.Nm chroot 38.Nd change root directory 39.Sh SYNOPSIS 40.In unistd.h 41.Ft int 42.Fn chroot "const char *dirname" 43.Sh DESCRIPTION 44.Fa dirname 45is the address of the pathname of a directory, terminated by an ASCII NUL. 46.Fn chroot 47causes 48.Fa dirname 49to become the root directory, that is, the starting point for path 50searches of pathnames beginning with 51.Ql / . 52.Pp 53In order for a directory to become the root directory, 54a process must have execute (search) access for that directory. 55.Pp 56If the program is not currently running with an altered root directory, 57it should be noted that 58.Fn chroot 59has no effect on the process's current directory. 60.Pp 61If the program is already running with an altered root directory, the 62process's current directory is changed to the same new root directory. 63This prevents the current directory from being further up the directory 64tree than the altered root directory. 65.Pp 66This call is restricted to the superuser. 67.Sh RETURN VALUES 68.Rv -std 69.Sh EXAMPLES 70The following example changes the root directory to 71.Va newroot , 72sets the current directory to the new root, and drops some 73setuid privileges. 74There may be other privileges which need to be dropped as well. 75.Bd -literal -offset indent 76#include <err.h> 77#include <unistd.h> 78 79if (chroot(newroot) != 0 || chdir("/") != 0) 80 err(1, "%s", newroot); 81setresuid(getuid(), getuid(), getuid()); 82.Ed 83.Sh ERRORS 84.Fn chroot 85will fail and the root directory will be unchanged if: 86.Bl -tag -width Er 87.It Bq Er ENOTDIR 88A component of the pathname is not a directory. 89.It Bq Er ENAMETOOLONG 90A component of a pathname exceeded 91.Dv NAME_MAX 92characters, or an entire pathname (including the terminating NUL) 93exceeded 94.Dv PATH_MAX 95bytes. 96.It Bq Er ENOENT 97The named directory does not exist. 98.It Bq Er EACCES 99Search permission is denied for any component of the pathname. 100.It Bq Er ELOOP 101Too many symbolic links were encountered in translating the pathname. 102.It Bq Er EFAULT 103.Fa dirname 104points outside the process's allocated address space. 105.It Bq Er EIO 106An I/O error occurred while reading from or writing to the file system. 107.It Bq Er EPERM 108The caller is not the superuser. 109.El 110.Sh SEE ALSO 111.Xr chdir 2 112.Sh HISTORY 113The 114.Fn chroot 115system call first appeared in 116.At v7 . 117.Sh CAVEATS 118There are ways for a root process to escape from the chroot jail. 119Changes to the directory hierarchy made from outside the chroot jail 120may allow a restricted process to escape, even if it is unprivileged. 121Passing directory file descriptors via 122.Xr recvmsg 2 123from outside the chroot jail may also allow a process to escape. 124