Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       chroot -- change	root directory

LIBRARY
       Standard	C Library (libc, -lc)

SYNOPSIS
       #include	<unistd.h>

       int
       chroot(const char *dirname);

DESCRIPTION
       The  dirname  argument  is  the address of the pathname of a directory,
       terminated by an	ASCII NUL.  The	chroot() system	call causes dirname to
       become the root	directory,  that  is,  the  starting  point  for  path
       searches	of pathnames 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
       directory.

       This call is restricted to the super-user.

       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
       always fail with	EPERM if there are any directories open.

       If  `kern.chroot_allow_open_directories'	 is  set to one	(the default),
       chroot()	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	behav-
       ior of chroot() still present on	other systems.

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() system call	will fail and the root directory will  be  un-
       changed if:

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

       [EPERM]		  The  effective user ID is not	the super-user,	or one
			  or more filedescriptors are open directories.

       [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	trans-
			  lating the pathname.

       [EFAULT]		  The dirname argument points  outside	the  process's
			  allocated address space.

       [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.

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.

BUGS
       If  the	process	 is able to change its working directory to the	target
       directory, but another access control check fails (such as a check  for
       open directories, 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 im-
       mediately  after	a successful chroot call, and restrict write access to
       a limited subtree of the	chroot root.  For instance, setup the  sandbox
       so  that	the sandboxed user will	have no	write access to	any well-known
       system directories.

       For complete isolation from the rest of the  system,  use  jail(2)  in-
       stead.

FreeBSD	13.2		      September	29, 2020		     CHROOT(2)

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | BUGS | SECURITY CONSIDERATIONS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=chroot&sektion=2&manpath=FreeBSD+14.0-RELEASE+and+Ports>

home | help