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. The jail is stored as tg_root (an absolute host path, or NULL if none). Children inherit a copy via strdup; leaving the group frees it.

Lookups stay inside the jail in inode_search_setup(): join $PWD for relative paths, prepend tg_root, then canonicalize with a jail-floor dst_min so .. cannot climb out. chroot() does not rewrite PWD. chroot("/") from the host root clears the jail; from inside a jail, / is still the jail, so it cannot be used to escape.

This is a filesystem jail, not a container: descriptors opened before chroot() that already point outside the tree remain usable, and the new root is not populated with /dev or /proc.

Impact

The option is off by default. When enabled, chroot() is a new syscall and, with SCHED_USER_IDENTITY, requires effective UID 0. Companion apps change: apache/nuttx-apps#3735 (merged).

Testing

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

$ ./tools/checkpatch.sh -c -u -m -g HEAD~4...HEAD
✔️ All checks pass.

$ make -j$(nproc)
LD:  nuttx

NSH jail session (syscall from userspace; chroot builtin from apache/nuttx-apps#3735):

nsh> mkdir /tmp/jail
nsh> echo hello > /tmp/jail/marker
nsh> chroot /tmp/jail
nsh> pwd
/
nsh> ls /
/:
 marker
nsh> cat /marker
hello
nsh> ls /dev
nsh: ls: stat failed: 2
nsh> cd ..
nsh> pwd
/
nsh> ls /../etc
nsh: ls: stat failed: 2
nsh> chroot /
nsh> ls /
/:
 marker

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 +182 B (+0.3%, 65,286 B / 262,144 B, total: 25% used)

esp32-devkitc

ROM: .flash.text +80 B (+0.1%, 124,992 B / 4,194,272 B, total: 3% used)
irom0_0_seg: .flash.text +80 B (+0.1%, 89,196 B / 3,342,304 B, total: 3% used)

hifive1-revb

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

mirtoo

kseg0_progmem: .text +132 B (+0.2%, 67,888 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.find_blockdriver -4 B, .text.inode_find +20 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.rename +64 B, .text.rmdir -20 B (+0.1%, 338,628 B)

qemu-intel64

Code: .text -233 B (-0.0%, 8,659,491 B)
Data: .rodata +32 B (+0.0%, 120,177 B)

rx65n-rsk2mb

ROM: .text +48 B (+0.1%, 86,928 B / 2,097,152 B, total: 4% used)

s698pm-dkit

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

stm32-nucleo-f103rb

flash: .text +76 B (+0.2%, 34,632 B / 131,072 B, total: 26% used)

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.

xiaoxiang781216 · 2026-09-03T14:48:39Z

    fs_truncate.c
    fs_link.c)

+if(CONFIG_FS_CHROOT)


move this patch after fs: start absolute lookups at the jail root

not fix yet, @Abhishekmishra2808

xiaoxiang781216 · 2026-09-03T16:46:37Z

@@ -440,7 +446,7 @@ static int automount_findinode(FAR const char *path)
  /* Relinquish our exclusive access to the inode try and return the result */

  inode_runlock();


need release inode

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>

Abhishekmishra2808 · 2026-09-06T10:07:51Z

@xiaoxiang781216, PTAL

xiaoxiang781216 · 2026-09-06T18:16:09Z

 #include <nuttx/fs/fs.h>
 #include <nuttx/fs/ioctl.h>
 #include <nuttx/kmalloc.h>
+#include <nuttx/lib/lib.h>


revert change in this file

xiaoxiang781216 · 2026-09-06T18:17:51Z

 #include <assert.h>
 #include <stdio.h>

+#include <nuttx/lib/lib.h>


revert the change

xiaoxiang781216 · 2026-09-06T18:19:01Z

    fs_link.c)

+if(CONFIG_FS_CHROOT)
+  list(APPEND SRCS fs_chroot.c)


move to chroot patch

xiaoxiang781216 · 2026-09-06T18:19:26Z


 #include <nuttx/cancelpt.h>
 #include <nuttx/fs/fs.h>
+#include <nuttx/lib/lib.h>


xiaoxiang781216 · 2026-09-06T18:22:11Z

 CSRCS += fs_syncfs.c fs_truncate.c fs_link.c

+ifeq ($(CONFIG_FS_CHROOT),y)
+CSRCS += fs_chroot.c


move to chroot patch

xiaoxiang781216 · 2026-09-06T18:25:47Z

+  inode_search_release(&olddesc);
+  if (ret >= 0)
+    {
+      inode_addref(oldfound);


why add ref

xiaoxiang781216 · 2026-09-06T18:33:10Z

   */

+  inode_release(newinode);
+  newinode = NULL;


why need zero

xiaoxiang781216 · 2026-09-06T18:37:16Z


  /* Re-resolve the source under the same lock before unlinking it. */

-  SETUP_SEARCH(&olddesc, oldpath, true);


why need re-resolve? let's remove it

xiaoxiang781216 · 2026-09-06T18:37:36Z

  switch (ret)
    {
-    case OK_EXIST:
+      case OK_EXIST:


move the format to new patch

xiaoxiang781216 · 2026-09-06T18:38:08Z

    }
+  else
+    {
+      inode_addref(inode);


why add ref

xiaoxiang781216 · 2026-09-06T18:43:49Z

 #include "tls/tls.h"

+#ifdef CONFIG_FS_CHROOT
+#  include "../../fs/fs_heap.h"


should we continue use kmm_malloc/free instead?

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

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

xiaoxiang781216 reviewed Aug 31, 2026

View reviewed changes

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from 62982eb to 83df4a9 Compare September 2, 2026 21:48

acassis previously approved these changes Sep 2, 2026

View reviewed changes

Abhishekmishra2808 dismissed acassis’s stale review via c3d257b September 3, 2026 07:46

Abhishekmishra2808 force-pushed the feature/fs-chroot branch from 83df4a9 to c3d257b Compare September 3, 2026 07:46

Abhishekmishra2808 requested a review from michallenc as a code owner September 3, 2026 07:46

Abhishekmishra2808 requested review from acassis and xiaoxiang781216 September 3, 2026 13:15

xiaoxiang781216 reviewed Sep 3, 2026

View reviewed changes

Abhishekmishra2808 added 4 commits September 5, 2026 08:12

sched: add per-group filesystem jail root

d634f86

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

abdfc73

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

4323e0c

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 c3d257b to 4323e0c Compare September 5, 2026 08:15

acassis approved these changes Sep 6, 2026

View reviewed changes

xiaoxiang781216 reviewed Sep 6, 2026

View reviewed changes

		@@ -440,7 +446,7 @@ static int automount_findinode(FAR const char *path)
		/* Relinquish our exclusive access to the inode try and return the result */

		inode_runlock();


		/* Re-resolve the source under the same lock before unlinking it. */

		SETUP_SEARCH(&olddesc, oldpath, true);

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!

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!

Abhishekmishra2808 commented Aug 19, 2026 •

edited

Loading

github-actions Bot commented Aug 19, 2026 •

edited

Loading

xiaoxiang781216 commented Aug 27, 2026 •

edited

Loading

xiaoxiang781216 Sep 6, 2026 •

edited

Loading