home | help 
CHROOT(2)		       System Calls Manual		       CHROOT(2)

NAME
     chroot, fchroot -- change root directory

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <unistd.h>

     int
     chroot(const char *dirname);

     int
     fchroot(int fd);

DESCRIPTION
     The  dirname argument is the address of the pathname of a directory, termi-
     nated by an ASCII NUL.  The chroot() system call causes dirname  to  become
     the  root directory, that is, the starting point for path searches of path-
     names beginning with `/'.

     In order for a directory to become the root directory a process  must  have
     execute (search) access for that directory.

     It should be noted that chroot() has no effect on the process's current di-
     rectory.

     This    call    is    restricted	 to    the    super-user,   unless   the
     `security.bsd.unprivileged_chroot' sysctl variable is  set  to  1	and  the
     process has enabled the PROC_NO_NEW_PRIVS_CTL procctl(2).

     Depending on the setting of the `kern.chroot_allow_open_directories' sysctl
     variable,	open  filedescriptors  which reference directories will make the
     chroot() fail as follows:

     If `kern.chroot_allow_open_directories' is set to zero, chroot()  will  al-
     ways fail with EPERM if there are any directories open.

     If  `kern.chroot_allow_open_directories'  is  set to one (the default), ch-
     root() will fail with EPERM if there  are	any  directories  open	and  the
     process is already subject to the chroot() system call.

     Any  other  value	for `kern.chroot_allow_open_directories' will bypass the
     check for open directories, mimicking the historic insecure behavior of ch-
     root() still present on other systems.

     The fchroot() system call is identical to chroot() except it takes  a  file
     descriptor instead of path.

RETURN VALUES
     Upon successful completion, the value 0 is returned; otherwise the value -1
     is returned and the global variable errno is set to indicate the error.

ERRORS
     The  chroot()  and  fchroot() system calls will fail and the root directory
     will be unchanged if:

     [EPERM]		The effective user ID is  not  the  super-user	and  the
			`security.bsd.unprivileged_chroot' sysctl is 0.

     [EPERM]		The  effective	user  ID  is  not the super-user and the
			process has not enabled the PROC_NO_NEW_PRIVS_CTL  proc-
			ctl(2).

     [EPERM]		One or more filedescriptors are open directories and the
			`kern.chroot_allow_open_directories'  sysctl  is not set
			to permit this.

     [EIO]		An I/O error occurred while reading from or  writing  to
			the file system.

     [EINTEGRITY]	Corrupted  data was detected while reading from the file
			system.

     The chroot() system call will fail and the root directory will be unchanged
     if:

     [ENOTDIR]		A component of the path name is not a directory.

     [ENAMETOOLONG]	A component of a pathname exceeded 255 characters, or an
			entire path name exceeded 1023 characters.

     [ENOENT]		The named directory does not exist.

     [EACCES]		Search permission is denied for  any  component  of  the
			path name.

     [ELOOP]		Too  many symbolic links were encountered in translating
			the pathname.

     [EFAULT]		The dirname argument points outside the process's  allo-
			cated address space.

     The  fchroot()  system  call  will  fail and the root directory will be un-
     changed if:

     [EACCES]		Search permission is denied for the directory referenced
			by the file descriptor.

     [EBADF]		The argument fd is not a valid file descriptor.

     [ENOTDIR]		The file descriptor does not reference a directory.

SEE ALSO
     chdir(2), jail(2)

HISTORY
     The chroot() system call appeared in Version 7 AT&T UNIX.	It was marked as
     "legacy" in Version 2 of the Single UNIX Specification ("SUSv2"),	and  was
     removed  in subsequent standards.	The fchroot() system call first appeared
     in FreeBSD 15.0.

BUGS
     If the process is able to change its working directory to the target direc-
     tory, but another access control check fails (such as a check for open  di-
     rectories, or a MAC check), it is possible that this system call may return
     an error, with the working directory of the process left changed.

SECURITY CONSIDERATIONS
     The  system  has  many hardcoded paths to files which it may load after the
     process starts.  It is generally recommended to drop privileges immediately
     after a successful chroot call, and restrict write access to a limited sub-
     tree of the chroot root.  For instance, setup the sandbox so that the sand-
     boxed user will have no write access to any well-known system directories.

     For complete isolation from the rest of the system, use jail(2) instead.

FreeBSD 15.0			 August 2, 2025 		       CHROOT(2)
home | help