git: 763f6cc92910 - main - chroot.2: document chaltroot(2)

From: Konstantin Belousov <kib_at_FreeBSD.org>
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