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

chroot() holds a directory inode in the task group, so sched needs the existing refcount helpers instead of duplicating them. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

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

xiaoxiang781216 · 2026-08-19T09:51:53Z

 void fs_initialize(void);

+/****************************************************************************
+ * Name: inode_addref


do you need remove the prototype from the internal header file

Dropped the public prototypes; they stay in fs/inode/inode.h

xiaoxiang781216 · 2026-08-19T09:52:48Z

 #  define group_inherit_identity(group)
 #endif

+#ifdef CONFIG_FS_CHROOT


where we define this config

xiaoxiang781216 · 2026-08-22T03:53:14Z

+      FAR const char *end = src;
+      size_t seglen;
+
+      while (*end != '\0' && *end != '/')


why not assign to out directly? we should touch in only once in the loop

Should we copy into out in one pass without walking in again?

xiaoxiang781216 · 2026-08-22T04:13:36Z

+  /* chroot() jail **********************************************************/
+
+  FAR struct inode *tg_root;        /* NULL means global pseudo-root        */
+  FAR char *tg_rootrel;             /* Relpath prefix if tg_root is a mount */


why not save the absolute path directly? it's complex to handle tg_root and tg_rootrel in the late patch.
BTW, the same path may remount to other file system, the current implementation can't handle it correctly.

Store the jail as an absolute path and re-resolve it on lookup instead of tg_root / tg_rootrel?

Yes, this make the code simpler and handle the mount point destroy/create correctly

xiaoxiang781216 · 2026-08-22T04:17:41Z

  FAR struct inode *above   = NULL;
  FAR const char   *relpath = NULL;
+#ifdef CONFIG_FS_CHROOT
+  FAR struct inode *search_root = g_root_inode;


it's more simple to:

prepend the root to the path

normalize the new path

ensure the result is under the root

continue the original flow

Prepend jail path, normalize, check still under root, then keep the original walk?

Store tg_root / tg_rootrel on the task group, copy them to children, and drop the inode when the last member leaves. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

Add CONFIG_FS_CHROOT and POSIX chroot(). Pin a directory as the group root, rewrite PWD, and require euid 0 when user identity is enabled. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

Walk from tg_root instead of the global pseudo-root, clamp ".." at the jail, and normalize absolute paths so chroot(".") under a mount does not pass a leftover "." as relpath. 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>

fs: export inode_addref and inode_release

58c9ac4

chroot() holds a directory inode in the task group, so sched needs the existing refcount helpers instead of duplicating them. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

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 added 4 commits August 23, 2026 06:32

sched: add per-group filesystem jail root

db4c05a

Store tg_root / tg_rootrel on the task group, copy them to children, and drop the inode when the last member leaves. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

fs: add chroot() syscall

dcc2b8c

Add CONFIG_FS_CHROOT and POSIX chroot(). Pin a directory as the group root, rewrite PWD, 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

6e58682

Walk from tg_root instead of the global pseudo-root, clamp ".." at the jail, and normalize absolute paths so chroot(".") under a mount does not pass a leftover "." as relpath. Signed-off-by: Abhishek Mishra <mishra.abhishek2808@gmail.com>

docs: document chroot jail root

5b250cc

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 f3fbd17 to 5b250cc Compare August 23, 2026 07:15

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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