fs,sched: add chroot() filesystem jail by Abhishekmishra2808 · Pull Request #19900 · apache/nuttx

Abhishekmishra2808 · 2026-08-19T08:27:00Z

Summary

CONFIG_FS_CHROOT adds POSIX chroot() so a task group can pin a directory as its filesystem root. Absolute lookups start at that inode, children inherit the jail, and PWD is rewritten so relative paths cannot walk out. This is a filesystem jail, not a container: descriptors opened before chroot() that already point outside the tree remain usable.

Impact

The option is off by default. When enabled, chroot() is a new syscall and, with SCHED_USER_IDENTITY, requires effective UID 0. On CONFIG_BUILD_FLAT the euid == 0 gate and tg_root share the same trust boundary as credentials. Companion apps change: apache/nuttx-apps#3735.

Testing

Host: WSL2 x86_64. Board: sim (CONFIG_FS_CHROOT=y). Companion apps PR: apache/nuttx-apps#3735.

$ ./tools/checkpatch.sh -f fs/inode/fs_inodesearch.c fs/vfs/fs_chroot.c \
    include/nuttx/sched.h include/unistd.h sched/group/group_create.c \
    sched/group/group_leave.c include/nuttx/fs/fs.h syscall/syscall.csv \
    fs/Kconfig fs/vfs/Make.defs fs/vfs/CMakeLists.txt \
    Documentation/implementation/chroot.rst \
    Documentation/implementation/user_identity.rst \
    Documentation/applications/nsh/commands.rst
✔️ All checks pass.

$ cd Documentation && make html
build succeeded.

The HTML pages are in _build/html.

NSH no-command form (syscall from userspace; chroot builtin is in apache/nuttx-apps#3735):

login: root
User Logged-in!
nsh> mkdir /tmp/jail
nsh> echo hello > /tmp/jail/marker
nsh> echo secret > /tmp/secret
nsh> chroot /tmp/jail
nsh> pwd
/
nsh> cat /marker
hello
nsh> ls /dev
nsh: ls: stat failed: 2
nsh> cat /tmp/secret
nsh: cat: open failed: 2

ostest (kernel jail, leftover fd, inheritance):

nsh> ostest
...
user_main: chroot test
chroot_test: Starting test
chroot_test: /marker is visible inside the jail
chroot_test: host paths are not visible inside the jail
chroot_test: pre-opened host fd still usable after chroot
chroot_test: grandchild still sees the jail
chroot_test: PASSED

acassis · 2026-08-19T12:36:59Z

Nice work @Abhishekmishra2808 !
@xiaoxiang781216 @raiden00pl maybe we could use it to create separated jails/arenas to use with telnet / ssh to avoid user to damage the original root filesystems. But I think in this case we need to be able to mount a limited /dev, /proc, etc

github-actions · 2026-08-19T13:33:48Z

MemBrowse Memory Report

s698pm-dkit

Code: .text +32 B (+0.0%, 363,856 B)
No memory changes detected for:
arduino-mega2560
esp32-devkitc
hifive1-revb
mirtoo
qemu-armv8a
qemu-intel64
rx65n-rsk2mb
stm32-nucleo-f103rb

Store the jail as an absolute path on the task group, copy it to children, and free it when the last member leaves. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

Add CONFIG_FS_CHROOT and POSIX chroot(). Store the jail as an absolute path on the task group, and require euid 0 when user identity is enabled. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

Prepend tg_root to absolute paths, normalize, and keep the result under the jail, then walk from g_root_inode. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

Describe the jail, leftover pre-opened fds, the NSH command-form scrub, and the flat-build trust boundary shared with credentials. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

Abhishekmishra2808 · 2026-08-24T15:58:55Z

@acassis PTAL !

acassis · 2026-08-24T16:29:08Z

@xiaoxiang781216 @raiden00pl @cederom PTAL

xiaoxiang781216 · 2026-08-24T17:10:41Z

+
+  /* chroot("/") from the global root is a no-op (tg_root stays NULL). */
+
+  if (strcmp(abspath, "/") == 0)


but caller may change to no root before

xiaoxiang781216 · 2026-08-24T17:10:58Z

+      return ERROR;
+    }
+
+  SETUP_SEARCH(&desc, path, false);


why need search

xiaoxiang781216 · 2026-08-24T17:19:54Z

+          out[len] = '\0';
+        }
+
+      strlcat(out, relpath, outlen);


strlcpy by len offset

xiaoxiang781216 · 2026-08-24T17:22:16Z

+          in++;
+        }
+
+      seglen = (size_t)(in - seg);


remove the cast

xiaoxiang781216 · 2026-08-24T17:23:08Z

+        }
+      else
+        {
+          size_t used = (size_t)(dst - out);


Abhishekmishra2808 requested review from Donny9, anchao, btashton, jerpelea, masayuki2009, pkarashchenko, pussuw, raiden00pl and xiaoxiang781216 as code owners August 19, 2026 08:27

Abhishekmishra2808 mentioned this pull request Aug 19, 2026

nshlib,testing: add chroot command and ostest apache/nuttx-apps#3735

Merged

github-actions Bot added Area: Documentation Improvements or additions to documentation Size: L The size of the change in this PR is large labels Aug 19, 2026

acassis reviewed Aug 19, 2026

View reviewed changes

xiaoxiang781216 reviewed Aug 22, 2026

View reviewed changes

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from f3fbd17 to 5b250cc Compare August 23, 2026 07:15

Abhishekmishra2808 added 4 commits August 23, 2026 17:43

sched: add per-group filesystem jail root

dc7c54d

Store the jail as an absolute path on the task group, copy it to children, and free it when the last member leaves. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

fs: add chroot() syscall

fe5eddd

Add CONFIG_FS_CHROOT and POSIX chroot(). Store the jail as an absolute path on the task group, and require euid 0 when user identity is enabled. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

fs: start absolute lookups at the jail root

dff5d5c

Prepend tg_root to absolute paths, normalize, and keep the result under the jail, then walk from g_root_inode. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

docs: document chroot jail root

d3ea539

Describe the jail, leftover pre-opened fds, the NSH command-form scrub, and the flat-build trust boundary shared with credentials. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from 5b250cc to d3ea539 Compare August 24, 2026 03:39

xiaoxiang781216 reviewed Aug 24, 2026

View reviewed changes

Comment thread sched/group/group_create.c Outdated

Comment thread sched/group/group_create.c Outdated

acassis approved these changes Aug 24, 2026

View reviewed changes

xiaoxiang781216 reviewed Aug 24, 2026

View reviewed changes


		/* chroot("/") from the global root is a no-op (tg_root stays NULL). */

		if (strcmp(abspath, "/") == 0)

Uh oh!

Conversation

Abhishekmishra2808 commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Impact

Testing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

acassis commented Aug 19, 2026

Uh oh!

github-actions Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

MemBrowse Memory Report

s698pm-dkit

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Abhishekmishra2808 commented Aug 24, 2026

Uh oh!

acassis commented Aug 24, 2026

Uh oh!

xiaoxiang781216 Aug 24, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Aug 24, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Aug 24, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Aug 24, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Aug 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Abhishekmishra2808 commented Aug 19, 2026 •

edited

Loading

github-actions Bot commented Aug 19, 2026 •

edited

Loading