### Setup virtiofsd with QEMU

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Start `virtiofsd` on the host, configure QEMU with a vhost-user-fs device connected to the socket, and then mount the filesystem in the guest using `virtiofs`.

```bash
# Host: Start virtiofsd
virtiofsd --shared-dir=/shared --socket-path=/tmp/vfsd.sock &

# Host: Configure QEMU
qemu-system-x86_64 \
    -m 4G \
    -object memory-backend-memfd,id=mem,size=4G,share=on \
    -numa node,memdev=mem \
    -chardev socket,id=char0,path=/tmp/vfsd.sock \
    -device vhost-user-fs-pci,queue-size=1024,chardev=char0,tag=myfs \
    ...
```

```bash
# Guest: Mount filesystem
mount -t virtiofs myfs /mnt
```

--------------------------------

### Build Vhost-User Daemon Example

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Example demonstrating how to construct a vhost-user daemon using the VhostUserFsBackendBuilder. It initializes a PassthroughFs and sets the thread pool size.

```rust
let fs = PassthroughFs::new(config)?;
let daemon = VhostUserFsBackendBuilder::new(fs)
    .thread_pool_size(4)
    .build()?;
```

--------------------------------

### Example virtiofsd Configuration for UID/GID Translation

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

This example demonstrates a complex UID and GID mapping scenario for virtiofsd, allowing unprivileged operation while mapping guest UIDs/GIDs to specific host values and vice-versa.

```shell
virtiofsd [...] \
    --translate-uid squash-guest:0:1001:4294967295 \
    --translate-gid squash-guest:0:100:4294967295 \
    --translate-uid host:1001:1000:1 \
    --translate-gid host:100:1000:1
```

--------------------------------

### Create and Run Vhost-User Filesystem Backend

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

This snippet shows how to create a filesystem, build a vhost-user backend with a thread pool, and start the daemon to listen for connections.

```rust
let config = Config::default();
let fs = PassthroughFs::new(config)?;

let backend = VhostUserFsBackendBuilder::new(fs)
    .thread_pool_size(4)
    .build()?;

let listener = Listener::new("/tmp/vfsd.sock", true)?;
let daemon = VhostUserDaemon::new(
    "/tmp/vfsd.sock",
    backend,
);

daemon.run()?;
```

--------------------------------

### Duration Creation Examples

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/07-types-reference.md

Illustrates various methods for creating Duration instances from seconds, milliseconds, and nanoseconds.

```rust
Duration::from_secs(3600)                    // 1 hour
Duration::from_millis(100)                   // 100 ms
Duration::from_nanos(1_000_000)              // 1 ms
Duration::ZERO                                // 0 seconds

```

--------------------------------

### Install Development Packages (Fedora/CentOS/RHEL)

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Installs the development packages for libcap-ng and libseccomp on Fedora, CentOS, or RHEL systems.

```shell
dnf install libcap-ng-devel libseccomp-devel
```

--------------------------------

### Install Development Packages (Debian/Ubuntu)

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Installs the development packages for libcap-ng and libseccomp on Debian or Ubuntu systems.

```shell
apt install libcap-ng-dev libseccomp-dev
```

--------------------------------

### PassthroughFs Usage Example

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/03-passthrough-config.md

Demonstrates how to create a PassthroughFs instance with custom configuration and integrate it with a vhost-user backend. Ensure the root directory is correctly specified and cache policies are set according to your needs.

```rust
// Create configuration
let mut config = Config::default();
config.root_dir = "/shared/directory".to_string();
config.cache_policy = CachePolicy::Auto;
config.xattr = true;
config.writeback = true;  // Only if exclusive access
config.entry_timeout = Duration::from_secs(3600);  // Cache for 1 hour
config.attr_timeout = Duration::from_secs(3600);

// Create PassthroughFs instance
let fs = PassthroughFs::new(config)?;

// Use with vhost-user backend
let backend = VhostUserFsBackendBuilder::new()
    .filesystem(fs)
    .thread_pool_size(4)
    .build()?;
```

--------------------------------

### Check virtiofsd Version

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Use this command to display the installed virtiofsd version. This is useful for verifying installation and compatibility.

```bash
virtiofsd --version
```

--------------------------------

### Minimal virtiofsd Usage

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

This is the most basic command to start the virtiofsd daemon, sharing a specified directory over a socket. Ensure the shared directory and socket path are valid.

```bash
virtiofsd --shared-dir=/path/to/share --socket-path=/tmp/vfsd.sock
```

--------------------------------

### enable_seccomp()

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/06-key-modules.md

Installs seccomp BPF rules to restrict allowed syscalls, enhancing security by limiting the kernel operations a process can perform.

```APIDOC
## enable_seccomp()

### Description
Installs seccomp BPF rules restricting syscalls to safe subset.

### Method
`enable_seccomp(action: SeccompAction)`

### Parameters
- **action** (SeccompAction) - Required - Determines kernel action when filtered syscall is invoked.

### SeccompAction Enum
```rust
pub enum SeccompAction {
    Allow,  // No seccomp (same as libseccomp-sys value None)
    Kill,   // Kill process on violation
    Trap,   // Send SIGSYS signal
    Log,    // Log violation but allow
}
```

### Allowed syscalls
File I/O: open, read, write, lseek, etc.
Filesystem metadata: stat, getattr, setattr
Directory operations: getdents, mkdir, unlink, etc.
Memory operations: mmap, mprotect
Basic syscalls: read, write, close, exit

### Filtered syscalls
ptrace, process_vm_*
execve, execveat
clone with NS flags (already in sandbox namespace)
mount, umount
And many others depending on configuration
```

--------------------------------

### Enable Debug Logging for virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Starts virtiofsd with debug logging enabled. Specify the shared directory, socket path, and set the log level to debug.

```bash
virtiofsd --shared-dir=/data --socket-path=/tmp/vfsd.sock \
          --log-level=debug
```

--------------------------------

### Inode Type Conversions in Rust

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Demonstrates converting between u64 and Inode types in Rust. No specific setup is required beyond having the Inode type available.

```rust
let inode_u64: u64 = inode.into();
let inode_from_u64 = Inode::from(42u64);
```

--------------------------------

### Getxattr Operation Example

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/07-types-reference.md

Demonstrates how to query the required buffer size for an extended attribute using `GetxattrReply::Count`, and then retrieve the attribute's value using `GetxattrReply::Value`.

```rust
// Query size first
match fs.getxattr(ctx, inode, b"user.test", 0)? {
    GetxattrReply::Count(size) => println!("Need {} bytes", size),
    _ => unreachable!(),
}

// Then read actual value
match fs.getxattr(ctx, inode, b"user.test", 1024)? {
    GetxattrReply::Value(val) => println!("Value: {:?}", val),
    _ => unreachable!(),
}

```

--------------------------------

### Enable Extended Attributes with virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Start `virtiofsd` with the `--xattr` flag to enable extended attribute support. In the guest, use `setfattr`, `getfattr`, and `getfattr -d` to manage extended attributes.

```bash
virtiofsd --shared-dir=/data --socket-path=/tmp/vfsd.sock --xattr
```

```bash
# Set xattr
setfattr -n user.test -v "value" /mnt/file

# Get xattr
getfattr -n user.test /mnt/file

# List xattrs
getfattr -d /mnt/file
```

--------------------------------

### GID Mapping Option for Non-Root

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Maps a range of GIDs from host to namespace when running virtiofsd as non-root. Requires subgid setup and uses newgidmap. If not provided, a 1-to-1 mapping for the current GID is used.

```shell
--gid-map=:namespace_gid:host_gid:count:
```

--------------------------------

### Server Creation

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Provides a constructor for creating a new Server instance with an initial FileSystem implementation and empty options.

```APIDOC
## Server::new

### Description
Creates a new server with empty initial options. Options are negotiated during `init()`.

### Signature
```rust
pub fn new(fs: F) -> Server<F>
```

### Parameters
- **fs** (F): The FileSystem implementation to be used by the server.
```

--------------------------------

### Server Creation

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Implements a constructor for the Server struct, initializing it with a given FileSystem and default empty options.

```rust
impl<F: FileSystem + Sync> Server<F> {
    pub fn new(fs: F) -> Server<F> {
        Server {
            fs,
            options: AtomicU64::new(FsOptions::empty().bits()),
        }
    }
}
```

--------------------------------

### Extended Attributes Operations

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Operations for managing extended attributes on inodes, including getting, setting, listing, and removing them.

```APIDOC
## getxattr

### Description
Get an extended attribute value.

### Method
`getxattr`

### Parameters
- **ctx** (Context) - Request context
- **inode** (Self::Inode) - Target inode
- **name** (&CStr) - Attribute name
- **size** (u32) - Buffer size (0 = query size)

### Returns
- `io::Result<GetxattrReply>`: GetxattrReply::Value or GetxattrReply::Count
```

```APIDOC
## setxattr

### Description
Set an extended attribute.

### Method
`setxattr`

### Parameters
- **ctx** (Context) - Request context
- **inode** (Self::Inode) - Target inode
- **name** (&CStr) - Attribute name
- **value** (&[u8]) - Attribute value
- **flags** (SetxattrFlags) - XATTR_CREATE, XATTR_REPLACE
- **extra_flags** (SetxattrFlags) - Additional flags

### Returns
- `io::Result<()>`
```

```APIDOC
## listxattr

### Description
List all extended attributes on an inode.

### Method
`listxattr`

### Parameters
- **ctx** (Context) - Request context
- **inode** (Self::Inode) - Target inode
- **size** (u32) - Buffer size

### Returns
- `io::Result<ListxattrReply>`: ListxattrReply::Names or ListxattrReply::Count
```

```APIDOC
## removexattr

### Description
Remove an extended attribute.

### Method
`removexattr`

### Parameters
- **ctx** (Context) - Request context
- **inode** (Self::Inode) - Target inode
- **name** (&CStr) - Attribute name

### Returns
- `io::Result<()>`
```

--------------------------------

### init

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Initializes the filesystem when a FUSE connection is established. It takes the kernel's capabilities and returns the negotiated filesystem options.

```APIDOC
## init

```rust
fn init(&self, capable: FsOptions) -> io::Result<FsOptions>
```

Initialize the filesystem when FUSE connection is established.

| Parameter | Type      | Description                     |
|-----------|-----------|---------------------------------|
| capable   | FsOptions | Features supported by kernel    |

Returns negotiated `FsOptions` combining implementation capabilities with kernel support.

**Default**: Returns empty options

**Source**: `filesystem.rs:269-271`
```

--------------------------------

### Get Filesystem Statistics (statfs)

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Retrieves filesystem statistics such as disk space and inode counts. This function is part of the Filesystem trait.

```rust
fn statfs(&self, ctx: Context, inode: Self::Inode) -> io::Result<libc::statvfs64>
```

--------------------------------

### Implement FileSystem Trait in Rust

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/README.md

Demonstrates how to implement the FileSystem trait for a custom filesystem and create a VhostUserFsBackend. Requires implementing approximately 40 methods.

```rust
// Define a filesystem
struct MyFS { /* ... */ }

// Implement the trait
impl FileSystem for MyFS {
    type Inode = u64;
    type Handle = u64;
    type DirIter = MyDirIter;
    
    fn lookup(&self, ctx: Context, parent: Self::Inode, name: &CStr) 
        -> io::Result<Entry> {
        // Implement lookup
    }
    
    fn read<W: ZeroCopyWriter>(
        &self, ctx: Context, inode: Self::Inode, handle: Self::Handle,
        w: W, size: u32, offset: u64, lock_owner: Option<u64>, flags: u32
    ) -> io::Result<usize> {
        // Implement read
    }
    
    // ... ~40 more methods
}

// Create and run backend
let fs = MyFS::new();
let backend = VhostUserFsBackendBuilder::new(fs)
    .thread_pool_size(4)
    .build()?;
```

--------------------------------

### Define xattr mapping rules

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/doc/xattr-mapping.md

Examples of various xattr mapping rules used to control attribute visibility and naming between client and server.

```text
:prefix:client:trusted.:user.virtiofs.:
```

```text
:prefix:server::user.virtiofs.:
```

```text
:prefix:all:trusted.:user.virtiofs.:
```

```text
:ok:client:user.::
```

```text
:ok:server::security.:
```

```text
:ok:all:::
```

```text
:bad:server::security.:
```

--------------------------------

### Add virtiofs Devices to QEMU Command-Line

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Integrate virtiofs devices into an existing QEMU command-line. Ensure the memory backend is configured with `memory-backend-memfd`, `share=on`, and the correct size. Add character device and filesystem device arguments for each mount.

```shell
-object memory-backend-memfd,id=mem,share=on,size=${MEMORY_SIZE}
-numa node,memdev=mem
-chardev socket,id=${MATCHING_ID},path=${VIRTIOFSD_SOCKET_PATH}
-device vhost-user-fs-pci,queue-size=1024,chardev=${MATCHING_ID},tag=${VIRTIOFS_TAG}
```

--------------------------------

### create

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Atomically creates and opens a new file. Returns the Entry for the new file, an optional handle, and the OpenOptions.

```APIDOC
## create

### Description
Create and open a file atomically.

### Method
create

### Parameters
#### Path Parameters
- **ctx** (Context) - Required - Request context
- **parent** (Self::Inode) - Required - Parent inode
- **name** (&CStr) - Required - File name
- **mode** (u32) - Required - File mode
- **kill_priv** (bool) - Required - Clear setuid/setgid bits
- **flags** (u32) - Required - Open flags
- **umask** (u32) - Required - Umask
- **extensions** (Extensions) - Required - File extensions

### Returns
- **Entry** - Entry for new file
- **Option<Self::Handle>** - Optional handle
- **OpenOptions** - OpenOptions

### Notes
- Return ENOSYS to fall back to mknod + open
- Increments Lookup count by 1
```

--------------------------------

### Check SetattrValid Flags in Rust

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/07-types-reference.md

Example usage of checking if specific attributes are valid for modification using SetattrValid bitflags. This is useful for validating setattr requests.

```rust
if valid.contains(SetattrValid::SIZE) {
    // size field is valid, can truncate file
}
if valid.contains(SetattrValid::ATIME_NOW) {
    // Set atime to current time
}
```

--------------------------------

### init - Filesystem Initialization

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Initializes the filesystem when a FUSE connection is established. It negotiates capabilities with the kernel and returns the negotiated FsOptions.

```rust
fn init(&self, capable: FsOptions) -> io::Result<FsOptions>
```

--------------------------------

### virtiofsd Execution Flow

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/01-overview.md

Illustrates the sequence of operations from command-line argument processing to guest request handling in virtiofsd.

```text
1. main() processes command-line arguments
2. Creates PassthroughFs (or PassthroughFsRo for readonly mode)
3. Initializes VhostUserFsBackend with the filesystem
4. Enters vhost-user message loop
5. For each guest request:
   - Reads FUSE message from guest via vhost-user
   - Processes in Server::handle_message()
   - Delegates to FileSystem trait implementation
   - Writes response back to guest
```

--------------------------------

### Get Extended Attribute Value

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Retrieve the value of an extended attribute associated with an inode. Provide the attribute name and buffer size; a size of 0 queries the attribute's size.

```rust
fn getxattr(&self, ctx: Context, inode: Self::Inode, name: &CStr, size: u32) -> io::Result<GetxattrReply>
```

--------------------------------

### Print virtiofsd Capabilities

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

This command outputs the capabilities supported by the virtiofsd binary. It helps in understanding the features available for use.

```bash
virtiofsd --print-capabilities
```

--------------------------------

### VhostUserFsBackendBuilder Methods

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Provides methods to configure the filesystem implementation and thread pool size for the vhost-user backend builder.

```rust
pub fn filesystem(mut self, fs: F) -> Self>
```

```rust
pub fn thread_pool_size(mut self, size: usize) -> Self>
```

```rust
pub fn build(self) -> Result<VhostUserDaemon<F>>
```

--------------------------------

### Create File - Rust

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Atomically creates and opens a file. Returns the new file's entry, an optional handle, and open options.

```rust
fn create(
    &self,
    ctx: Context,
    parent: Self::Inode,
    name: &CStr,
    mode: u32,
    kill_priv: bool,
    flags: u32,
    umask: u32,
    extensions: Extensions,
) -> io::Result<(Entry, Option<Self::Handle>, OpenOptions)>
```

--------------------------------

### UID Mapping Option for Non-Root

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Maps a range of UIDs from host to namespace when running virtiofsd as non-root. Requires subuid setup and uses newuidmap. If not provided, a 1-to-1 mapping for the current UID is used.

```shell
--uid-map=:namespace_uid:host_uid:count:
```

--------------------------------

### Get File Attributes (getattr)

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Retrieves file or directory attributes. Use when the kernel needs to read metadata like size, permissions, or timestamps. Note that with writeback caching, the kernel might override the st_size attribute.

```rust
fn getattr(
    &self,
    ctx: Context,
    inode: Self::Inode,
    handle: Option<Self::Handle>,
) -> io::Result<(fuse::Attr, Duration)>
```

--------------------------------

### open

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Opens a file for reading or writing with specified flags. It returns an optional handle for future I/O operations and the resolved OpenOptions.

```APIDOC
## open

### Description
Open a file for reading/writing.

### Method
open

### Parameters
#### Path Parameters
- **ctx** (Context) - Required - Request context
- **inode** (Self::Inode) - Required - File inode
- **kill_priv** (bool) - Required - Clear setuid/setgid bits
- **flags** (u32) - Required - Open flags (O_RDONLY, O_WRONLY, O_DIRECT, etc.)

### Returns
- **Option<Self::Handle>** - Optional handle for future I/O
- **OpenOptions** - OpenOptions flags

### Notes
- Creation flags (O_CREAT, O_EXCL) are filtered by kernel
- If FsOptions::ZERO_MESSAGE_OPEN enabled, returning ENOSYS disables open/release calls
- If writeback caching, kernel may send reads for O_WRONLY files
```

--------------------------------

### virtiofsd Architecture Overview

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/01-overview.md

This diagram illustrates the interconnected modules of the virtiofsd architecture, showing the flow from the vhost-user backend to the PassthroughFs implementation.

```text
┌─────────────────────────────────────────────────────────────┐
│                   vhost-user Backend                        │
│            (vhost_user.rs, VhostUserFsBackend)             │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│                   FUSE Server                               │
│              (server.rs, Server trait)                      │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│              FileSystem Trait                               │
│  (filesystem.rs - abstract interface for FS operations)    │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│           PassthroughFs Implementation                      │
│  (passthrough/mod.rs - host filesystem access)            │
└──────────────────────────────────────────────────────────────┘
```

--------------------------------

### Implement Custom Filesystem with Rust

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Define a custom filesystem by implementing the `FileSystem` trait in Rust. This involves creating a struct and implementing methods like `init`, `lookup`, `getattr`, `read`, and `write`. Use `VhostUserFsBackendBuilder` to create an instance and connect via a vhost-user socket.

```rust
struct MyFS { /* ... */ }

impl FileSystem for MyFS {
    type Inode = u64;
    type Handle = u64;
    type DirIter = MyDirIter;
    
    fn lookup(&self, ctx: Context, parent: Self::Inode, name: &CStr) 
        -> io::Result<Entry> {
        // Implement lookup logic
    }
    // ... implement other methods
}

// Create daemon
let fs = MyFS::new();
let backend = VhostUserFsBackendBuilder::new(fs)
    .thread_pool_size(4)
    .build()?;
```

--------------------------------

### Exporting a Shared Directory with virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

This snippet shows how to export the /mnt directory using virtiofsd on a vhost-user UNIX domain socket. It also includes the corresponding QEMU command line to mount the shared filesystem in the guest.

```shell
host# virtiofsd --socket-path=/tmp/vfsd.sock --shared-dir /mnt \
        --inode-file-handles=mandatory &
```

```shell
host# qemu-system \
        -blockdev file,node-name=hdd,filename=<your image> \
        -device virtio-blk,drive=hdd \
        -chardev socket,id=char0,path=/tmp/vfsd.sock \
        -device vhost-user-fs-pci,queue-size=1024,chardev=char0,tag=myfs \
        -object memory-backend-memfd,id=mem,size=4G,share=on \
        -numa node,memdev=mem \
        -accel kvm -m 4G
```

```shell
guest# mount -t virtiofs myfs /mnt
```

--------------------------------

### Verify Migration File Handles

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Ensures that the migration destination opens the same inodes as the source by verifying file handles. This requires both source and destination to use the same shared directory on the same filesystem. It is recommended when external processes have write access to the shared directory.

```shell
--migration-verify-handles
```

--------------------------------

### Build Release Binary for virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Build the release binary for the virtiofsd project using Cargo. The executable will be located in target/release/virtiofsd.

```bash
# Build release binary
cargo build --release

# Binary at target/release/virtiofsd
./target/release/virtiofsd --help
```

--------------------------------

### Virtiofsd Documentation Files

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

List of documentation files within the virtiofsd project and their respective content.

```markdown
| File | Contains |
|------|----------|
| `INDEX.md` | Master index and navigation |
| `01-overview.md` | Architecture and project info |
| `02-filesystem-trait.md` | FileSystem API reference |
| `03-passthrough-config.md` | Configuration types and options |
| `04-errors-and-types.md` | Error types and CLI options |
| `05-vhost-user-backend.md` | Protocol implementation |
| `06-key-modules.md` | Submodule APIs |
| `07-types-reference.md` | Complete type definitions |

```

--------------------------------

### Sandbox Implementation

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/06-key-modules.md

Details on how sandboxing is implemented, including namespace and chroot isolation.

```APIDOC
## Sandbox Implementation

### Namespace Isolation

Creates:
- New filesystem namespace (mount ns)
- New PID namespace
- New network namespace
- pivot_root into shared directory root

Advantages: Full isolation, prevents filesystem escapes

### Chroot Isolation

- Calls chroot(2) into shared directory
- Assumes container runtime set up namespaces
- Lighter-weight than namespace mode
```

--------------------------------

### Share Multiple Directories with virtiofsd using Submounts

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Achieve sharing of multiple directories by using submounts. Mount individual directories into subdirectories of a shared parent directory, then export the parent. Announce-submounts is enabled by default.

```shell
mkdir -p share/{sh0,sh1}
mount -o bind share0 share/sh0
mount -o bind share1 share/sh1
virtiofsd --shared-dir share ...
```

--------------------------------

### Test Read-Only Mode in virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Launches virtiofsd in read-only mode and includes a comment on how to test write operations from the guest. Any write attempt should fail.

```bash
virtiofsd --shared-dir=/data --socket-path=/tmp/vfsd.sock --readonly
# In guest: touch /mnt/file  # Should fail
```

--------------------------------

### ZeroCopyWriter

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Wraps a descriptor Writer to read file data directly into guest memory, leveraging zero-copy for performance.

```APIDOC
## ZeroCopyWriter

### Description
Wraps a descriptor Writer to read file data directly into guest memory.

### Method Signature
```rust
struct ZcWriter<'a>(Writer<'a>);

impl ZeroCopyWriter for ZcWriter<'_> {
    fn read_from_file_at(
        &mut self,
        f: &File,
        count: usize,
        off: u64,
        flags: Option<oslib::ReadvFlags>,
    ) -> io::Result<usize>
}
```

### Parameters
#### Path Parameters
- **f** (*&File*) - Required - Source file to read from
- **count** (*usize*) - Required - Bytes to read
- **off** (*u64*) - Required - File offset
- **flags** (*Option<oslib::ReadvFlags>*) - Optional - Vectored read flags

### Returns
Actual bytes read
```

--------------------------------

### virtiofsd Command Line Usage

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

The basic command structure for running the virtiofsd daemon. Requires either a file descriptor or socket path, and a shared directory.

```shell
virtiofsd [FLAGS] [OPTIONS] --fd <fd>|--socket-path <socket-path> --shared-dir <shared-dir>
```

--------------------------------

### virtiofsd Secure Minimal Configuration

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/INDEX.md

This configuration prioritizes security by disabling caching, enabling read-only access, and utilizing namespace sandboxing with seccomp.

```bash
virtiofsd --shared-dir=/data \
          --socket-path=/tmp/vfsd.sock \
          --cache=never \
          --readonly \
          --sandbox=namespace \
          --seccomp=kill
```

--------------------------------

### mkdir - Create Directory

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Creates a new directory. This operation increments the inode lookup count by 1. If FsOptions::DONT_MASK is set, the provided mode must be masked with the umask.

```rust
fn mkdir(
    &self,
    ctx: Context,
    parent: Self::Inode,
    name: &CStr,
    mode: u32,
    umask: u32,
    extensions: Extensions,
) -> io::Result<Entry>
```

--------------------------------

### Lifecycle Management

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/INDEX.md

APIs for initializing, cleaning up, and managing the lifecycle of file system resources.

```APIDOC
## FileSystem::init()

### Description
Initialize the file system interface.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::destroy()

### Description
Clean up and release resources.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::forget()

### Description
Release an inode reference.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::batch_forget()

### Description
Batch release of inode references.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

--------------------------------

### ZeroCopyWriter Implementation

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Wraps a descriptor Writer to enable reading file data directly into guest memory using zero-copy. Ideal for efficient data retrieval from files.

```rust
struct ZcWriter<'a>(Writer<'a>);

impl ZeroCopyWriter for ZcWriter<'_> {
    fn read_from_file_at(
        &mut self,
        f: &File,
        count: usize,
        off: u64,
        flags: Option<oslib::ReadvFlags>,
    ) -> io::Result<usize>
}
```

--------------------------------

### Open Directory for Reading

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Open a directory to read its entries. This function returns an optional directory handle and open options. It requires the directory inode and flags.

```rust
fn opendir(
    &self,
    ctx: Context,
    inode: Self::Inode,
    flags: u32,
) -> io::Result<(Option<Self::Handle>, OpenOptions)>
```

--------------------------------

### File Creation and Deletion

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/INDEX.md

APIs for creating and deleting various file system objects.

```APIDOC
## FileSystem::create()

### Description
Create and open a file.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::mkdir()

### Description
Create a directory.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::symlink()

### Description
Create a symbolic link.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::mknod()

### Description
Create a special file (e.g., device file).

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::unlink()

### Description
Delete a file.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::rmdir()

### Description
Delete a directory.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::link()

### Description
Create a hard link.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::rename()

### Description
Rename or move a file system entry.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

--------------------------------

### mkdir

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Creates a new directory with specified mode and permissions. This operation increments the lookup count for the newly created directory.

```APIDOC
## mkdir

```rust
fn mkdir(
    &self,
    ctx: Context,
    parent: Self::Inode,
    name: &CStr,
    mode: u32,
    umask: u32,
    extensions: Extensions,
) -> io::Result<Entry>
```

Create a directory.

| Parameter  | Type       | Description                                  |
|------------|------------|----------------------------------------------|
| ctx        | Context    | Request context                              |
| parent     | Inode      | Parent directory inode                       |
| name       | &CStr      | New directory name                           |
| mode       | u32        | Permission bits (S_IFDIR \| perms)           |
| umask      | u32        | Umask for permission calculation             |
| extensions | Extensions | Additional context (secctx, sup_gids)        |

**Returns**: Entry for the new directory
**Increments**: Lookup count by 1

**Note**: If FsOptions::DONT_MASK is set, must apply `mode & !umask`

**Source**: `filesystem.rs:414-424`
```

--------------------------------

### Vhost-User Backend Event Loop Flow

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Illustrates the sequence of events in the vhost-user backend's event handling. This flow describes how requests are received, processed, and responded to.

```text
Guest sends request
    ↓
vhost-user transport delivers to server
    ↓
epoll in VhostUserFsThread::handle_event()
    ↓
Dequeue descriptor chains from virtio queue
    ↓
For each request:
  - Parse FUSE message
  - Call Server::handle_message()
  - Write response
  - Return descriptor to ring
    ↓
Signal guest via eventfd
```

--------------------------------

### MigrationMode Enum for Live VM Migration

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/03-passthrough-config.md

Specifies how to migrate internal state during live VM migration. 'FindPaths' resolves inodes via /proc/self/fd or directory traversal, while 'FileHandles' uses file handles for faster but more restrictive migration.

```rust
pub enum MigrationMode {
    #[default]
    FindPaths,
    FileHandles,
}
```

--------------------------------

### VirtioFS Source File Structure

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/INDEX.md

Illustrates the directory and file organization of the virtiofsd project's source code.

```text
src/
├── lib.rs                           # Public API, Error type
├── main.rs                          # Binary entry point, CLI parsing
├── server.rs                        # FUSE request handler
├── vhost_user.rs                    # Vhost-user protocol backend
├── filesystem.rs                    # FileSystem trait definition
├── fuse.rs                          # FUSE protocol structures
├── sandbox.rs                       # Process sandboxing
├── seccomp.rs                       # Seccomp filtering
├── idmap.rs                         # Namespace UID/GID mapping
├── soft_idmap.rs                    # Software UID/GID translation
├── descriptor_utils.rs              # Guest memory access
├── oslib.rs                         # OS-specific syscalls
├── util.rs                          # General utilities
├── limits.rs                        # Resource limit management
├── read_dir.rs                      # Directory iteration
├── macros.rs                        # Utility macros
└── passthrough/
    ├── mod.rs                       # PassthroughFs main impl, Config
    ├── inode_store.rs               # Inode lifecycle management
    ├── credentials.rs               # Capability management
    ├── file_handle.rs               # File handle operations
    ├── xattrmap.rs                  # Xattr name translation
    ├── stat.rs                      # Efficient stat operations
    ├── util.rs                      # FS operation utilities
    ├── read_only.rs                 # Read-only wrapper
    ├── mount_fd.rs                  # Mount point tracking
    ├── guest_fd_limit.rs            # FD quota management
    └── device_state/                # Migration serialization
        ├── mod.rs
        ├── serialized.rs
        ├── serialization.rs
        ├── deserialization.rs
        └── preserialization/
```

--------------------------------

### File Lookup and Navigation

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/INDEX.md

APIs for looking up file system entries and checking access permissions.

```APIDOC
## FileSystem::lookup()

### Description
Look up a directory entry.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::readlink()

### Description
Read the target of a symbolic link.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

```APIDOC
## FileSystem::access()

### Description
Check access permissions for a file or directory.

### Method
Not specified (internal API)

### Endpoint
Not specified (internal API)
```

--------------------------------

### Prefix all attributes with user.virtiofs.

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/doc/xattr-mapping.md

Remaps all xattrs to a fixed prefix and hides non-prefixed attributes.

```shell
--xattrmap=":prefix:all::user.virtiofs.::bad:all:::"
```

```shell
--xattrmap=":map::user.virtiofs.:"
```

--------------------------------

### VhostUserFsBackendBuilder

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Builder for creating a vhost-user filesystem backend. It allows configuration of the filesystem implementation and the worker thread pool size.

```APIDOC
## VhostUserFsBackendBuilder

### Description
Builder for creating a vhost-user filesystem backend. It allows configuration of the filesystem implementation and the worker thread pool size.

### Fields
- **fs** (F) - Required - FileSystem implementation
- **thread_pool_size** (usize) - Optional - Number of worker threads (0 = disabled)

### Methods
#### filesystem()

Set the filesystem implementation.

#### thread_pool_size()

Set worker thread pool size. A value of 0 disables the thread pool and processes requests synchronously.

#### build()

Construct the vhost-user daemon.

**Returns**: VhostUserDaemon ready to accept connections

**Errors**: Can fail if:
- Thread pool creation fails
- unshare(CLONE_FS) syscall fails

**Example**:
```rust
let fs = PassthroughFs::new(config)?;
let daemon = VhostUserFsBackendBuilder::new(fs)
    .thread_pool_size(4)
    .build()?;
```
```

--------------------------------

### Running virtiofsd with lxc-usernsexec (User Mapping 1)

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

This command uses lxc-usernsexec to map the root user inside the user namespace to a specific host user and group (100000). This is an alternative method for managing user namespaces.

```shell
host$ lxc-usernsexec -m b:0:100000:65536 -- virtiofsd --socket-path=/tmp/vfsd.sock \
        --shared-dir /mnt --sandbox chroot &
```

--------------------------------

### Duration Conversions in Rust

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/QUICK-START.md

Shows how to create Duration objects from seconds and milliseconds, and how to use the Duration::ZERO constant. These are standard library functions.

```rust
Duration::from_secs(5)
Duration::from_millis(100)
Duration::ZERO
```

--------------------------------

### Allow mmap Option

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Enables memory mapping for files when using metadata or never cache policies. Should only be enabled if the file system has exclusive access.

```shell
--allow-mmap
```

--------------------------------

### Share Directory Read-Only with virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Use the `--readonly` switch with virtiofsd to prevent write accesses from the guest. Ensure the directory is exported correctly.

```shell
virtiofsd --shared-dir share --readonly ...
```

--------------------------------

### Running virtiofsd with unshare for User Namespaces

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

This command uses the unshare utility from util-linux to configure user namespaces for virtiofsd, similar to podman-unshare. This allows virtiofsd to use subordinate UIDs/GIDs for guest users.

```shell
host$ unshare -r --map-auto -- virtiofsd --socket-path=/tmp/vfsd.sock --shared-dir /mnt \
        --sandbox chroot &
```

--------------------------------

### OS-Specific System Call Wrappers (Rust)

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/06-key-modules.md

Provides OS-specific system call wrappers and utilities. Key functions include changing directories, extended stat operations, and file attribute manipulation.

```rust
pub fn fchdir(fd) -> io::Result<()>
pub fn statx(fd: i32, path: &str, flags: u32) -> io::Result<StatxResult>
pub fn openat_cloexec(fd: i32, path: &str, flags: i32) -> io::Result<i32>
pub fn write_perm_cap(fd: i32) -> io::Result<()>
pub fn getxattr(fd: i32, name: &str) -> io::Result<Vec<u8>>
pub fn setxattr(fd: i32, name: &str, value: &[u8], flags: u32) -> io::Result<()>
pub fn listxattr(fd: i32) -> io::Result<Vec<String>>
pub fn removexattr(fd: i32, name: &str) -> io::Result<()>
```

--------------------------------

### Sync Filesystem Data (syncfs)

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Synchronizes all filesystem data mounted at the current point to persistent storage.

```rust
fn syncfs(&self, ctx: Context, inode: Self::Inode) -> io::Result<()>
```

--------------------------------

### Implement statx Function

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/06-key-modules.md

Queries file metadata using the statx(2) syscall when available. Supports more precise timestamps and better performance than stat64. Requires a directory file descriptor, a relative path, and statx flags.

```rust
pub fn statx(fd: RawFd, path: &CStr, flags: i32) -> io::Result<(libc::stat64, u32, u64)>

```

--------------------------------

### Configure Migration Error Handling

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Controls how virtiofsd responds to errors during migration. Use 'abort' to stop migration on any error, or 'guest-error' to allow migration to complete with affected inodes marked as invalid.

```shell
--migration-on-error=<abort|guest-error>
```

--------------------------------

### Entry

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/02-filesystem-trait.md

Information about a path in the filesystem, including inode, generation, attributes, and cache timeouts.

```APIDOC
## Entry

### Description
Information about a path in the filesystem.

### Fields
- **inode** (u64) - Inode identifier; set to 0 for negative entries
- **generation** (u64) - Generation number (required for NFS/network filesystems)
- **attr** (fuse::Attr) - File attributes (mode, size, uid, gid, etc.)
- **attr_timeout** (Duration) - How long attributes should be cached
- **entry_timeout** (Duration) - How long directory entry names should be cached
```

--------------------------------

### virtiofsd UID/GID Mapping Configuration

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/INDEX.md

Configure UID and GID translation to map user and group IDs between the host and the guest for access control.

```bash
virtiofsd --shared-dir=/data \
          --socket-path=/tmp/vfsd.sock \
          --translate-uid=map:1000:1001:1 \
          --translate-gid=map:1000:101:1
```

--------------------------------

### VhostUserFsBackendBuilder Structure

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Defines the builder for creating a vhost-user filesystem backend. It holds the FileSystem implementation and thread pool size.

```rust
pub struct VhostUserFsBackendBuilder<F: FileSystem + Send + Sync + 'static> {
    fs: F,
    thread_pool_size: usize,
}
```

--------------------------------

### Mapping Guest UID to Host UID with virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

This option translates a specific guest UID to a host UID when running virtiofsd. It's useful when the guest UID differs from the host UID but only a single user is expected to access files.

```shell
--translate-uid=map:<guest UID>:<host UID>:1
```

--------------------------------

### virtiofsd Project Directory Structure

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/README.md

This snippet shows the directory structure of the virtiofsd project. It helps in understanding the organization of different documentation files and modules.

```text
.
├── README.md                      ← You are here
├── INDEX.md                       ← Master index
├── QUICK-START.md                 ← Essential guide
├── 01-overview.md                 ← Architecture
├── 02-filesystem-trait.md         ← FileSystem API
├── 03-passthrough-config.md       ← Configuration
├── 04-errors-and-types.md         ← Errors & types
├── 05-vhost-user-backend.md       ← Backend details
├── 06-key-modules.md              ← Module APIs
└── 07-types-reference.md          ← Type definitions
```

--------------------------------

### ZeroCopyReader Implementation

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Wraps a descriptor Reader to enable writing guest data directly to files using zero-copy. Useful for high-performance file I/O operations.

```rust
struct ZcReader<'a>(Reader<'a>);

impl ZeroCopyReader for ZcReader<'_> {
    fn write_to_file_at(
        &mut self,
        f: &File,
        count: usize,
        off: u64,
        flags: Option<oslib::WritevFlags>,
    ) -> io::Result<usize>
}
```

--------------------------------

### Migration Mode Option for virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

Defines how virtiofsd performs migration by specifying how its internal state is represented to the destination instance. Requires QEMU version 8.2 or newer.

```shell
--migration-mode=<find-paths|file-handles>
```

--------------------------------

### Translate UID Options for virtiofsd

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/README.md

These options set up maps for virtiofsd to translate between host and guest UIDs without requiring a user namespace. They can be used regardless of whether virtiofsd runs as root.

```shell
--translate-uid=guest:<guest base UID>:<host base UID>:<count>
--translate-uid=host:<host base UID>:<guest base UID>:<count>
--translate-uid=squash-guest:<guest base UID>:<host UID>:<count>
--translate-uid=squash-host:<host base UID>:<guest UID>:<count>
--translate-uid=forbid-guest:<guest base UID>:<count>
--translate-uid=map:<guest base UID>:<host base UID>:<count>
```

--------------------------------

### Vhost-User Configuration Constants

Source: https://gitlab.com/virtio-fs/virtiofsd/-/blob/main/_autodocs/05-vhost-user-backend.md

Defines essential configuration constants for the vhost-user backend, including queue sizes, queue counts, event indices, and maximum tag length. These constants dictate operational parameters.

```rust
const QUEUE_SIZE: usize = 32768;          // Max entries per virtio queue
const REQUEST_QUEUES: u32 = 1;            // Number of request queues
const NUM_QUEUES: usize = 2;              // Request + high-priority queue
const HIPRIO_QUEUE_EVENT: u16 = 0;        // High-priority queue event index
const REQ_QUEUE_EVENT: u16 = 1;           // Request queue event index
const MAX_TAG_LEN: usize = 36;            // Max device tag length
```