git: 763f6cc92910 - main - chroot.2: document chaltroot(2)
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 20 Nov 2026 15:10:55 UTC
The branch main has been updated by kib:
URL: https://cgit.FreeBSD.org/src/commit/?id=763f6cc92910cb740a508762d3cc8c1b2bf50408
commit 763f6cc92910cb740a508762d3cc8c1b2bf50408
Author: Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2026-09-27 20:35:05 +0000
Commit: Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2026-11-20 15:10:26 +0000
chroot.2: document chaltroot(2)
Reviewed by: markj
Sponsored by: The FreeBSD Foundation
MFC after: 1 week
Differential revision: https://reviews.freebsd.org/D60035
---
lib/libsys/Makefile.sys | 4 +-
lib/libsys/chroot.2 | 128 +++++++++++++++++++++++++++++++++++++++++-------
2 files changed, 114 insertions(+), 18 deletions(-)
diff --git a/lib/libsys/Makefile.sys b/lib/libsys/Makefile.sys
index 5924abb43a39..7e3c03f0fea4 100644
--- a/lib/libsys/Makefile.sys
+++ b/lib/libsys/Makefile.sys
@@ -416,7 +416,9 @@ MLINKS+=chmod.2 fchmod.2 \
MLINKS+=chown.2 fchown.2 \
chown.2 fchownat.2 \
chown.2 lchown.2
-MLINKS+=chroot.2 fchroot.2
+MLINKS+=chroot.2 fchroot.2 \
+ chroot.2 chaltroot.2 \
+ chroot.2 fchaltroot.2
MLINKS+=clock_gettime.2 clock_getres.2 \
clock_gettime.2 clock_settime.2
MLINKS+=closefrom.2 close_range.2
diff --git a/lib/libsys/chroot.2 b/lib/libsys/chroot.2
index 6dd93d28033a..024c22af7b8f 100644
--- a/lib/libsys/chroot.2
+++ b/lib/libsys/chroot.2
@@ -25,13 +25,15 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd April 27, 2026
+.Dd October 24, 2026
.Dt CHROOT 2
.Os
.Sh NAME
.Nm chroot ,
-.Nm fchroot
-.Nd change root directory
+.Nm fchroot ,
+.Nm chaltroot ,
+.Nm fchaltroot
+.Nd change root or alternative root directory
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
@@ -40,6 +42,10 @@
.Fn chroot "const char *dirname"
.Ft int
.Fn fchroot "int fd"
+.Ft int
+.Fn chaltroot "const char *dirname"
+.Ft int
+.Fn fchaltroot "int fd"
.Sh DESCRIPTION
The
.Fa dirname
@@ -61,13 +67,6 @@ It should be noted that
.Fn chroot
has no effect on the process's current directory.
.Pp
-This call is restricted to the super-user, unless the
-.Ql Va security.bsd.unprivileged_chroot
-sysctl variable is set to 1
-and the process has enabled the
-.Dv PROC_NO_NEW_PRIVS_CTL
-.Xr procctl 2 .
-.Pp
Depending on the setting of the
.Ql kern.chroot_allow_open_directories
sysctl variable, open file descriptors which reference directories
@@ -106,15 +105,97 @@ The
system call is identical to
.Fn chroot
except it takes a file descriptor instead of path.
+.Pp
+The
+.Fn chaltroot
+system call sets or changes the
+.Dq alternative root
+directory.
+If set to a directory for which the process has
+search permission, that directory is used as a root for
+absolute path lookups.
+If the lookup succeeds, the result is used.
+If the lookup fails with
+.Er ENOENT ,
+a second lookup is automatically initiated,
+starting from the process' true root directory,
+and the result of that lookup is returned.
+.Pp
+Calling the
+.Fn chaltroot
+system call with the
+.Fa dirname
+argument set to
+.Dv NULL
+disables the alternative root for the process.
+.Pp
+As with the normal root directory, the alternative root directory is
+inherited by child processes created by
+.Xr fork 2 ,
+and preserved across image activations on
+.Xr execve 2 ,
+except as described below.
+.Pp
+The alternative root facility is used by ABI emulators to
+provide a parallel installation of foreign system files
+while still providing seamless access to the file hierarchy
+of the host system.
+Upon activation of the executable image branded for the ABI
+emulator, the kernel automatically resets the alternative root to
+the value assigned to the ABI.
+When a process running under the ABI emulator activates a native
+image, the alternative root is disabled.
+.Pp
+Activation of a set-user-ID or set-group-ID image for the native ABI
+disables the alternative root, unless the set-ID bits are ignored,
+for instance because the process has enabled the
+.Dv PROC_NO_NEW_PRIVS_CTL
+.Xr procctl 2
+setting.
+Entering capability mode with
+.Xr cap_enter 2
+also disables the alternative root.
+.Pp
+Lookups which are restricted to stay beneath their starting directory,
+see the
+.Dv O_RESOLVE_BENEATH
+flag of
+.Xr open 2 ,
+do not use the alternative root.
+.Pp
+The
+.Fn fchaltroot
+system call is similar to
+.Fn chaltroot
+but takes a file descriptor to designate the new alternative root
+instead of a path.
+Calling the
+.Fn fchaltroot
+system call with the
+.Fa fd
+argument of
+.Dv FCHALTROOT_DISABLE
+disables the alternative root for the process.
+.Pp
+All functions described in this page are restricted to the super-user,
+unless the
+.Ql Va security.bsd.unprivileged_chroot
+sysctl variable is set to 1
+and the process has enabled the
+.Dv PROC_NO_NEW_PRIVS_CTL
+.Xr procctl 2
+setting.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
The
-.Fn chroot
+.Fn chroot ,
+.Fn fchroot ,
+.Fn chaltroot ,
and
-.Fn fchroot
+.Fn fchaltroot
system calls
-will fail and the root directory will be unchanged if:
+will fail and the root or alternative root directory will be unchanged if:
.Bl -tag -width Er
.It Bq Er EPERM
The effective user ID is not the super-user and the
@@ -142,8 +223,11 @@ Corrupted data was detected while reading from the file system.
.Pp
The
.Fn chroot
-system call
-will fail and the root directory will be unchanged if:
+and
+.Fn chaltroot
+system calls
+will fail and the root or alternative root directory
+will be unchanged if:
.Bl -tag -width Er
.It Bq Er ENOTDIR
A component of the path name is not a directory.
@@ -165,8 +249,11 @@ points outside the process's allocated address space.
.Pp
The
.Fn fchroot
-system call
-will fail and the root directory will be unchanged if:
+and
+.Fn fchaltroot
+system calls
+will fail and the root or alternative root directory
+will be unchanged if:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for the directory referenced by the
@@ -179,6 +266,7 @@ is not a valid file descriptor.
The file descriptor does not reference a directory.
.El
.Sh SEE ALSO
+.Xr cap_enter 2 ,
.Xr chdir 2 ,
.Xr jail 2
.Sh HISTORY
@@ -195,6 +283,12 @@ The
.Fn fchroot
system call first appeared in
.Fx 15.0 .
+The
+.Fn chaltroot
+and
+.Fn fchaltroot
+system calls first appeared in
+.Fx 16.0 .
.Sh 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