Skip to content

add FUSE_OVFS_IOC_REFRESH_DIR ioctl to refresh directory cache - #462

Open
wangjia184 wants to merge 1 commit into
containers:mainfrom
wangjia184:main
Open

add FUSE_OVFS_IOC_REFRESH_DIR ioctl to refresh directory cache#462
wangjia184 wants to merge 1 commit into
containers:mainfrom
wangjia184:main

Conversation

@wangjia184

Copy link
Copy Markdown

Summary

Add a custom FUSE ioctl (FUSE_OVFS_IOC_REFRESH_DIR) that clears and re-scans a directory's cached children on demand, so that externally created .wh.* whiteout files and other changes to the backing directories become visible
without remounting.

Motivation

When fuse-overlayfs scans a directory for the first time, it caches the child entries and marks the directory as "loaded." Subsequent reads skip the disk scan and return cached results. This means:

  • A .wh.* whiteout file created directly in the upper layer after the scan won't hide the corresponding file.
  • A file added directly to the lower layer won't appear.
  • A file removed from the lower layer won't disappear.

The ioctl gives users a way to explicitly refresh a directory when external modifications have been made.

@giuseppe

giuseppe commented May 8, 2026

Copy link
Copy Markdown
Member

you need to sign off your commit, and please use a real name for that

Comment thread src/node.rs

/// Clear all children and whiteouts. Used by cache invalidation to
/// force a full re-scan of the directory.
pub fn clear_children(&mut self) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can't we just use mark_unloaded?

@wangjia184 wangjia184 May 11, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In fact, I tried mark_unloaded but that does not work for .wh.* changes. And I dont want to change the load part.

Comment thread src/overlay.rs
let is_get = cmd_ioctl == libc::FS_IOC_GETVERSION || cmd_ioctl == libc::FS_IOC_GETFLAGS;

// Custom command: clear and re-scan a directory's children.
if cmd_ioctl == FUSE_OVFS_IOC_REFRESH_DIR {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we need to make sure the caller has appropriate permissions, can a process without privileges call the ioctl?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is no special permission required by FUSE_OVFS_IOC_REFRESH_DIR.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it can be abused by an unprivileged user (e.g. uid != 0 inside the container), to cause a lot of load on the file system as it invalidates the entire directory.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants