Struct PassthroughFs 

pub struct PassthroughFs<S: BitmapSlice + Send + Sync = ()> { /* private fields */ }

A file system that simply “passes through” all requests it receives to the underlying file system.

To keep the implementation simple it servers the contents of its root directory. Users that wish to serve only a specific directory should set up the environment so that that directory ends up as the root of the file system process. One way to accomplish this is via a combination of mount namespaces and the pivot_root system call.

Implementations

impl<S: BitmapSlice + Send + Sync> PassthroughFs<S>

pub async fn do_getattr_helper( &self, inode: Inode, handle: Option<u64>, ) -> Result<(stat64, Duration)>

Internal getattr helper that skips ID mapping.

This helper is specifically designed for internal use by overlayfs. It calls do_getattr_inner with mapping: false to retrieve the raw, unmodified host attributes of a file. This is essential for the copy_up process to correctly preserve the original file ownership.

pub async fn do_create_helper( &self, req: Request, parent: Inode, name: &OsStr, mode: u32, flags: u32, uid: u32, gid: u32, ) -> Result<ReplyCreated>

A wrapper for create, used by copy_regfile_up.

This helper is called during a copy-up operation to create a file in the upper layer while preserving the original host UID/GID from the lower layer file.

pub async fn do_mkdir_helper( &self, req: Request, parent: Inode, name: &OsStr, mode: u32, umask: u32, uid: u32, gid: u32, ) -> Result<ReplyEntry>

A wrapper for mkdir, used by [create_upper_dir][crate::overlayfs::OverlayInode::create_upper_dir] function.

This helper is called during a copy-up operation when a parent directory needs to be created in the upper layer, preserving the original host UID/GID.

pub async fn do_symlink_helper( &self, req: Request, parent: Inode, name: &OsStr, link: &OsStr, uid: u32, gid: u32, ) -> Result<ReplyEntry>

A wrapper for symlink, used by copy_symlink_up function.

This helper is called during a copy-up operation to create a symbolic link in the upper layer while preserving the original host UID/GID from the lower layer link.

impl<S: BitmapSlice + Send + Sync> PassthroughFs<S>

pub fn new(cfg: Config) -> Result<PassthroughFs<S>>

Create a Passthrough file system instance.

pub async fn import(&self) -> Result<()>

Initialize the Passthrough file system.

pub fn keep_fds(&self) -> Vec<RawFd>

Get the list of file descriptors which should be reserved across live upgrade.

pub async fn readlinkat_proc_file(&self, inode: u64) -> Result<PathBuf>

Get the file pathname corresponding to the Inode This function is used by Nydus blobfs

Trait Implementations

impl Filesystem for PassthroughFs

async fn init(&self, _req: Request) -> Result<ReplyInit>

initialize filesystem. Called before any other filesystem method.

async fn destroy(&self, _req: Request)

clean up filesystem. Called on filesystem exit which is fuseblk, in normal fuse filesystem, kernel may call forget for root. There is some discuss for this https://github.com/bazil/fuse/issues/82#issuecomment-88126886, https://sourceforge.net/p/fuse/mailman/message/31995737/

async fn lookup( &self, _req: Request, parent: Inode, name: &OsStr, ) -> Result<ReplyEntry>

look up a directory entry by name and get its attributes.

async fn forget(&self, _req: Request, inode: Inode, nlookup: u64)

forget an inode. The nlookup parameter indicates the number of lookups previously performed on this inode. If the filesystem implements inode lifetimes, it is recommended that inodes acquire a single reference on each lookup, and lose nlookup references on each forget. The filesystem may ignore forget calls, if the inodes don’t need to have a limited lifetime. On unmount it is not guaranteed, that all referenced inodes will receive a forget message. When filesystem is normal(not fuseblk) and unmounting, kernel may send forget request for root and this library will stop session after call forget. There is some discussion for this https://github.com/bazil/fuse/issues/82#issuecomment-88126886, https://sourceforge.net/p/fuse/mailman/message/31995737/

async fn getattr( &self, _req: Request, inode: Inode, fh: Option<u64>, _flags: u32, ) -> Result<ReplyAttr>

get file attributes. If fh is None, means fh is not set.

async fn setattr( &self, req: Request, inode: Inode, fh: Option<u64>, set_attr: SetAttr, ) -> Result<ReplyAttr>

set file attributes. If fh is None, means fh is not set.

async fn readlink(&self, _req: Request, inode: Inode) -> Result<ReplyData>

read symbolic link.

async fn symlink( &self, req: Request, parent: Inode, name: &OsStr, link: &OsStr, ) -> Result<ReplyEntry>

create a symbolic link.

async fn mknod( &self, req: Request, parent: Inode, name: &OsStr, mode: u32, rdev: u32, ) -> Result<ReplyEntry>

create file node. Create a regular file, character device, block device, fifo or socket node. When creating file, most cases user only need to implement create.

async fn mkdir( &self, req: Request, parent: Inode, name: &OsStr, mode: u32, umask: u32, ) -> Result<ReplyEntry>

create a directory.

async fn unlink(&self, _req: Request, parent: Inode, name: &OsStr) -> Result<()>

remove a file.

async fn rmdir(&self, _req: Request, parent: Inode, name: &OsStr) -> Result<()>

remove a directory.

async fn link( &self, _req: Request, inode: Inode, new_parent: Inode, new_name: &OsStr, ) -> Result<ReplyEntry>

create a hard link.

async fn open( &self, _req: Request, inode: Inode, flags: u32, ) -> Result<ReplyOpen>

open a file. Open flags (with the exception of O_CREAT, O_EXCL and O_NOCTTY) are available in flags. Filesystem may store an arbitrary file handle (pointer, index, etc) in fh, and use this in other all other file operations (read, write, flush, release, fsync). Filesystem may also implement stateless file I/O and not store anything in fh. There are also some flags (direct_io, keep_cache) which the filesystem may set, to change the way the file is opened. A filesystem need not implement this method if it sets MountOptions::no_open_support and if the kernel supports FUSE_NO_OPEN_SUPPORT.

Notes:

See fuse_file_info structure in fuse_common.h for more details.

async fn read( &self, _req: Request, inode: Inode, fh: u64, offset: u64, size: u32, ) -> Result<ReplyData>

read data. Read should send exactly the number of bytes requested except on EOF or error, otherwise the rest of the data will be substituted with zeroes. An exception to this is when the file has been opened in direct_io mode, in which case the return value of the read system call will reflect the return value of this operation. fh will contain the value set by the open method, or will be undefined if the open method didn’t set any value.

async fn write( &self, _req: Request, inode: Inode, fh: u64, offset: u64, data: &[u8], _write_flags: u32, flags: u32, ) -> Result<ReplyWrite>

write data. Write should return exactly the number of bytes requested except on error. An exception to this is when the file has been opened in direct_io mode, in which case the return value of the write system call will reflect the return value of this operation. fh will contain the value set by the open method, or will be undefined if the open method didn’t set any value. When write_flags contains FUSE_WRITE_CACHE, means the write operation is a delay write.

async fn statfs(&self, _req: Request, inode: Inode) -> Result<ReplyStatFs>

get filesystem statistics.

async fn release( &self, _req: Request, inode: Inode, fh: u64, _flags: u32, _lock_owner: u64, _flush: bool, ) -> Result<()>

release an open file. Release is called when there are no more references to an open file: all file descriptors are closed and all memory mappings are unmapped. For every open call there will be exactly one release call. The filesystem may reply with an error, but error values are not returned to close() or munmap() which triggered the release. fh will contain the value set by the open method, or will be undefined if the open method didn’t set any value. flags will contain the same flags as for open. flush means flush the data or not when closing file.

async fn fsync( &self, _req: Request, inode: Inode, fh: u64, datasync: bool, ) -> Result<()>

synchronize file contents. If the datasync is true, then only the user data should be flushed, not the metadata.

async fn setxattr( &self, _req: Request, inode: Inode, name: &OsStr, value: &[u8], flags: u32, _position: u32, ) -> Result<()>

set an extended attribute.

async fn getxattr( &self, _req: Request, inode: Inode, name: &OsStr, size: u32, ) -> Result<ReplyXAttr>

Get an extended attribute. If size is too small, return Err<ERANGE>. Otherwise, use ReplyXAttr::Data to send the attribute data, or return an error.

async fn listxattr( &self, _req: Request, inode: Inode, size: u32, ) -> Result<ReplyXAttr>

List extended attribute names.

If size is too small, return Err<ERANGE>. Otherwise, use ReplyXAttr::Data to send the attribute list, or return an error.

async fn removexattr( &self, _req: Request, inode: Inode, name: &OsStr, ) -> Result<()>

remove an extended attribute.

async fn flush( &self, _req: Request, inode: Inode, fh: u64, _lock_owner: u64, ) -> Result<()>

flush method. This is called on each close() of the opened file. Since file descriptors can be duplicated (dup, dup2, fork), for one open call there may be many flush calls. Filesystems shouldn’t assume that flush will always be called after some writes, or that if will be called at all. fh will contain the value set by the open method, or will be undefined if the open method didn’t set any value.

Notes:

the name of the method is misleading, since (unlike fsync) the filesystem is not forced to flush pending writes. One reason to flush data, is if the filesystem wants to return write errors. If the filesystem supports file locking operations ([setlk][Filesystem::setlk], [getlk][Filesystem::getlk]) it should remove all locks belonging to lock_owner.

async fn opendir( &self, _req: Request, inode: Inode, flags: u32, ) -> Result<ReplyOpen>

open a directory. Filesystem may store an arbitrary file handle (pointer, index, etc) in fh, and use this in other all other directory stream operations (readdir, releasedir, fsyncdir). Filesystem may also implement stateless directory I/O and not store anything in fh. A file system need not implement this method if it sets MountOptions::no_open_dir_support and if the kernel supports FUSE_NO_OPENDIR_SUPPORT.

async fn readdir<'a>( &'a self, _req: Request, parent: Inode, fh: u64, offset: i64, ) -> Result<ReplyDirectory<impl Stream<Item = Result<DirectoryEntry>> + Send + 'a>>

read directory. offset is used to track the offset of the directory entries. fh will contain the value set by the opendir method, or will be undefined if the opendir method didn’t set any value.

async fn readdirplus<'a>( &'a self, _req: Request, parent: Inode, fh: u64, offset: u64, _lock_owner: u64, ) -> Result<ReplyDirectoryPlus<impl Stream<Item = Result<DirectoryEntryPlus>> + Send + 'a>>

read directory entries, but with their attribute, like readdir

• lookup at the same time.

async fn releasedir( &self, _req: Request, inode: Inode, fh: u64, _flags: u32, ) -> Result<()>

release an open directory. For every opendir call there will be exactly one releasedir call. fh will contain the value set by the opendir method, or will be undefined if the opendir method didn’t set any value.

async fn fsyncdir( &self, req: Request, inode: Inode, fh: u64, datasync: bool, ) -> Result<()>

synchronize directory contents. If the datasync is true, then only the directory contents should be flushed, not the metadata. fh will contain the value set by the opendir method, or will be undefined if the opendir method didn’t set any value.

async fn access(&self, req: Request, inode: Inode, mask: u32) -> Result<()>

check file access permissions. This will be called for the access() system call. If the default_permissions mount option is given, this method is not be called. This method is not called under Linux kernel versions 2.4.x.

async fn create( &self, req: Request, parent: Inode, name: &OsStr, mode: u32, flags: u32, ) -> Result<ReplyCreated>

create and open a file. If the file does not exist, first create it with the specified mode, and then open it. Open flags (with the exception of O_NOCTTY) are available in flags. Filesystem may store an arbitrary file handle (pointer, index, etc) in fh, and use this in other all other file operations (read, write, flush, release, fsync). There are also some flags (direct_io, keep_cache) which the filesystem may set, to change the way the file is opened. If this method is not implemented or under Linux kernel versions earlier than 2.6.15, the mknod and open methods will be called instead.

Notes:

See fuse_file_info structure in fuse_common.h for more details.

async fn interrupt(&self, _req: Request, _unique: u64) -> Result<()>

handle interrupt. When a operation is interrupted, an interrupt request will send to fuse server with the unique id of the operation.

async fn batch_forget(&self, _req: Request, inodes: &[(Inode, u64)])

forget more than one inode. This is a batch version forget

async fn fallocate( &self, _req: Request, inode: Inode, fh: u64, offset: u64, length: u64, mode: u32, ) -> Result<()>

allocate space for an open file. This function ensures that required space is allocated for specified file.

Notes:

more information about fallocate, please see man 2 fallocate

async fn rename( &self, _req: Request, parent: Inode, name: &OsStr, new_parent: Inode, new_name: &OsStr, ) -> Result<()>

rename a file or directory.

async fn rename2( &self, _req: Request, parent: Inode, name: &OsStr, new_parent: Inode, new_name: &OsStr, flags: u32, ) -> Result<()>

rename a file or directory with flags.

async fn lseek( &self, _req: Request, inode: Inode, fh: u64, offset: u64, whence: u32, ) -> Result<ReplyLSeek>

find next data or hole after the specified offset.

async fn copy_file_range( &self, _req: Request, inode_in: Inode, fh_in: u64, offset_in: u64, inode_out: Inode, fh_out: u64, offset_out: u64, length: u64, flags: u64, ) -> Result<ReplyCopyFileRange>

Copy a range of data from one file to another using the copy_file_range system call. This can improve performance by reducing data copying between userspace and kernel.

fn bmap( &self, req: Request, inode: u64, blocksize: u32, idx: u64, ) -> impl Future<Output = Result<ReplyBmap, Errno>> + Send

map block index within file to block index within device.

fn poll( &self, req: Request, inode: u64, fh: u64, kh: Option<u64>, flags: u32, events: u32, notify: &Notify, ) -> impl Future<Output = Result<ReplyPoll, Errno>> + Send

poll for IO readiness events.

fn notify_reply( &self, req: Request, inode: u64, offset: u64, data: Bytes, ) -> impl Future<Output = Result<(), Errno>> + Send

receive notify reply from kernel.

impl Layer for PassthroughFs

fn root_inode(&self) -> Inode

Return the root inode number

fn create_with_context<'life0, 'life1, 'async_trait>( &'life0 self, ctx: OperationContext, parent: Inode, name: &'life1 OsStr, mode: u32, flags: u32, ) -> Pin<Box<dyn Future<Output = Result<ReplyCreated>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create a file with explicit ownership context. Uses OperationContext to allow overriding UID/GID for internal operations like copy-up.

fn mkdir_with_context<'life0, 'life1, 'async_trait>( &'life0 self, ctx: OperationContext, parent: Inode, name: &'life1 OsStr, mode: u32, umask: u32, ) -> Pin<Box<dyn Future<Output = Result<ReplyEntry>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create a directory with explicit ownership context. Uses OperationContext to allow overriding UID/GID for internal operations like copy-up.

fn symlink_with_context<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ctx: OperationContext, parent: Inode, name: &'life1 OsStr, link: &'life2 OsStr, ) -> Pin<Box<dyn Future<Output = Result<ReplyEntry>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Create a symbolic link with explicit ownership context. Uses OperationContext to allow overriding UID/GID for internal operations like copy-up.

fn do_getattr_helper<'life0, 'async_trait>( &'life0 self, inode: Inode, handle: Option<u64>, ) -> Pin<Box<dyn Future<Output = Result<(stat64, Duration)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Retrieve host-side metadata bypassing ID mapping. This is used internally by overlay operations to get raw stat information.

fn create_whiteout<'life0, 'life1, 'async_trait>( &'life0 self, ctx: Request, parent: Inode, name: &'life1 OsStr, ) -> Pin<Box<dyn Future<Output = Result<ReplyEntry>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create whiteout file with name .

fn delete_whiteout<'life0, 'life1, 'async_trait>( &'life0 self, ctx: Request, parent: Inode, name: &'life1 OsStr, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete whiteout file with name .

fn is_whiteout<'life0, 'async_trait>( &'life0 self, ctx: Request, inode: Inode, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

Check if the Inode is a whiteout file

fn set_opaque<'life0, 'async_trait>( &'life0 self, ctx: Request, inode: Inode, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

Set the directory to opaque.

fn is_opaque<'life0, 'async_trait>( &'life0 self, ctx: Request, inode: Inode, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: Sync + 'async_trait, 'life0: 'async_trait,

Check if the directory is opaque.