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

arduino-mega2560

flash: .text +166 B (+0.3%, 65,258 B / 262,144 B, total: 25% used)

hifive1-revb

flash: .text +104 B (+0.1%, 83,820 B / 4,194,304 B, total: 2% used)

mirtoo

kseg0_progmem: .text +96 B (+0.1%, 67,848 B / 131,072 B, total: 52% used)

qemu-armv8a

Code: .text.file_mq_unlink -4 B, .text.file_mq_vopen -8 B, .text.file_vopen -4 B, .text.inode_find +12 B, .text.inode_reserve +8 B, .text.inode_search -496 B, .text.mkdir -4 B, .text.nx_stat -4 B, .text.nx_umount2 +16 B, .text.nx_unlink -20 B, .text.rmdir -20 B (+0.0%, 319,936 B)

qemu-intel64

Code: .text -316 B (-0.0%, 8,659,398 B)
Data: .rodata +64 B (+0.1%, 120,209 B)

rx65n-rsk2mb

ROM: .text -32 B (-0.0%, 86,848 B / 2,097,152 B, total: 4% used)

s698pm-dkit

Code: .text +336 B (+0.1%, 365,504 B)

stm32-nucleo-f103rb

flash: .text +64 B (+0.2%, 34,464 B / 131,072 B, total: 26% used)
No memory changes detected for:
esp32-devkitc

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

@acassis PTAL !

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

@xiaoxiang781216 @raiden00pl @cederom PTAL

xiaoxiang781216 · 2026-08-27T11:06:51Z

ci was fixed, please rebase your change to the last master. @Abhishekmishra2808, many code can be simplified with #19991.

Abhishekmishra2808 · 2026-08-27T19:23:30Z

@xiaoxiang781216 done

xiaoxiang781216 · 2026-08-28T15:09:17Z

@xiaoxiang781216 done

@Abhishekmishra2808 please fix the conflict.

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>

Prepare paths in inode_search_setup(): prepend tg_root, canonicalize with a jail-floor dst_min, then walk from g_root_inode. Replace SETUP_SEARCH / RELEASE_SEARCH with inode_search_setup() / inode_search_release(). 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>

xiaoxiang781216 · 2026-08-31T01:22:37Z

  if (ret < 0)
    {
      ferr("ERROR: Failed to find %s\n", pathname);
      ret = -ENOENT;


xiaoxiang781216 · 2026-08-31T01:23:41Z

  if (ret < 0)
    {
      ferr("ERROR: Failed to find %s\n", pathname);
      ret = -ENOENT;


xiaoxiang781216 · 2026-08-31T01:28:02Z

  inode_rlock();
-  ret = inode_search(desc);
+  ret = inode_search(desc, inode);
  if (ret >= 0)


need check inode isnot NULL

xiaoxiang781216 · 2026-08-31T01:38:22Z

+  ret = inode_search_setup(&desc, path2, false);
+  if (ret < 0)
+    {
+      errcode = -ret;


remove errcode too

xiaoxiang781216 · 2026-08-31T01:39:08Z

-              ret = desc.node->u.i_mops->symlink(desc.node, path1,
-                                                 desc.relpath);
+              ret = inode->u.i_mops->symlink(inode, path1,
+                                            desc.relpath);


add one space

xiaoxiang781216 · 2026-08-31T01:47:24Z

+    }
+
+  ret = inode_search(&olddesc, &oldfound);
+  inode_search_release(&olddesc);


release oldfound

xiaoxiang781216 · 2026-08-31T01:53:00Z

@@ -155,7 +157,8 @@ static int _inode_compare(FAR const char *fname, FAR struct inode *inode)

 #ifdef CONFIG_FS_LINKS
 static int _inode_linktarget(FAR struct inode *inode,


let change inode to ** directly

xiaoxiang781216 · 2026-08-31T01:57:02Z

 ****************************************************************************/

-int inode_search(FAR struct inode_search_s *desc)
+int inode_search_setup(FAR struct inode_search_s *desc,


Move before inode_search to reduce the difference

xiaoxiang781216 · 2026-08-31T01:59:07Z

+
+              if (inodep != NULL)
+                {
+                  *inodep = inode;


why update in the fail path

xiaoxiang781216 · 2026-08-31T02:00:23Z

+ *
+ ****************************************************************************/
+
+void inode_search_release(FAR struct inode_search_s *desc)


Move before inode_search_setup

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 2 times, most recently 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 previously approved these changes Aug 24, 2026

View reviewed changes

xiaoxiang781216 reviewed Aug 24, 2026

View reviewed changes

Comment thread fs/vfs/fs_chroot.c Outdated

Comment thread fs/vfs/fs_chroot.c Outdated

Comment thread fs/vfs/fs_chroot.c Outdated

Comment thread fs/inode/fs_inodesearch.c Outdated

Comment thread fs/inode/fs_inodesearch.c Outdated

Abhishekmishra2808 dismissed acassis’s stale review via 1dbd097 August 26, 2026 19:23

Abhishekmishra2808 force-pushed the feature/fs-chroot branch 2 times, most recently from 1dbd097 to 82821d6 Compare August 26, 2026 19:48

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from 82821d6 to 3f75a6c Compare August 27, 2026 13:01

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from 3f75a6c to 0647bd2 Compare August 29, 2026 07:50

xiaoxiang781216 reviewed Aug 29, 2026

View reviewed changes

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from 0647bd2 to 330134a Compare August 29, 2026 19:28

Abhishekmishra2808 requested review from GUIDINGLI, Ouss4, gustavonihei, hartmannathan and yamt as code owners August 29, 2026 19:28

github-actions Bot added Size: XL The size of the change in this PR is very large. Consider breaking down the PR into smaller pieces. and removed Size: L The size of the change in this PR is large labels Aug 29, 2026

xiaoxiang781216 reviewed Aug 30, 2026

View reviewed changes

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from 330134a to 8a93d1f Compare August 30, 2026 09:01

Abhishekmishra2808 added 4 commits August 30, 2026 18:57

sched: add per-group filesystem jail root

8071c96

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

d6e72b0

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>

docs: document chroot jail root

62982eb

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 8a93d1f to 62982eb Compare August 30, 2026 19:00

xiaoxiang781216 reviewed Aug 31, 2026

View reviewed changes

		@@ -155,7 +157,8 @@ static int _inode_compare(FAR const char fname, FAR struct inode inode)

		#ifdef CONFIG_FS_LINKS
		static int _inode_linktarget(FAR struct inode *inode,

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

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Abhishekmishra2808 commented Aug 27, 2026

Uh oh!

xiaoxiang781216 commented Aug 28, 2026

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhishekmishra2808 commented Aug 19, 2026 •

edited

Loading

github-actions Bot commented Aug 19, 2026 •

edited

Loading

xiaoxiang781216 commented Aug 27, 2026 •

edited

Loading