Skip to main content

Module mount

hexz_cli::cmd::vm

Module mount 

Source
Expand description

Mount Hexz snapshots as FUSE filesystems or NBD block devices.

This command exposes Hexz snapshots to the host operating system by mounting them as either FUSE filesystems (default) or NBD (Network Block Device) devices. The mount provides read-only or read-write access with optional overlay support for copy-on-write semantics, cache configuration, and permission mapping.

§Mount Mechanisms

§FUSE (Filesystem in Userspace) - Default

Characteristics:

  • No root/sudo required (uses user-space FUSE)
  • Exposes disk and memory files at mount point
  • Supports overlay for read-write mounts
  • Can run as daemon for background mounting

File Structure:

/mnt/snapshot/
├── disk       # Disk image (raw format)
└── memory     # Memory dump (if present in snapshot)

Use Cases:

  • Mount disk images for file extraction without VM
  • Read-write mounts with overlay for ephemeral changes
  • Development and debugging (inspect snapshot contents)
  • Backup and archival access

§NBD (Network Block Device) - Optional

Characteristics:

  • Requires root/sudo and nbd kernel module
  • Creates /dev/nbdN block device
  • Supports standard filesystem mounting (ext4, xfs, etc.)
  • Better performance for large sequential I/O

Workflow:

  1. Start internal NBD server on localhost
  2. Connect nbd-client to server
  3. Mount resulting /dev/nbdN device
  4. Wait for Ctrl+C, then cleanup

Use Cases:

  • Native filesystem mounting without FUSE overhead
  • Integration with existing block device tooling
  • Performance-critical applications

§Overlay Behavior

When mounted read-write (--rw), an overlay file tracks modifications:

Overlay Mechanism:

  • Reads: Served from base snapshot (fast, cached)
  • Writes: Captured in overlay file at 4 KiB granularity
  • Metadata: .meta file tracks modified block indices

Overlay Storage:

  • Ephemeral (default): Temporary file deleted on unmount
  • Persistent (--overlay <path>): Saved for later commit

Commit Workflow:

# Mount with persistent overlay
hexz mount snapshot.st /mnt --rw --overlay changes.overlay

# Make changes inside /mnt
# ...

# Unmount
hexz unmount /mnt

# Commit changes to new snapshot
hexz vm commit --base snapshot.st --overlay changes.overlay --output new.st

§Cache Size Semantics

The --cache-size parameter controls in-memory block caching:

Cache Behavior:

  • Stores recently accessed compressed blocks in memory
  • LRU (Least Recently Used) eviction policy
  • Reduces decompression overhead for repeated reads

Size Guidelines:

  • Default: No cache (every read decompresses from storage)
  • --cache-size 256M: 256 MB cache (good for development VMs)
  • --cache-size 1G: 1 GB cache (good for production workloads)
  • --cache-size 4G: 4 GB cache (maximum benefit for most workloads)

Performance Impact:

  • Cache hit: ~10 GB/s (memcpy from cache)
  • Cache miss: ~500 MB/s (LZ4) or ~200 MB/s (Zstd)
  • Working set > cache size: Performance degrades to uncached speed

§UID/GID Implications

The --uid and --gid parameters control file ownership inside the mount:

Ownership Mapping:

  • All files inside the mount appear owned by uid:gid
  • Does not modify actual data in snapshot (metadata-only)
  • Affects permission checks for file access

Common Values:

  • --uid 1000 --gid 1000: Default user (typical for desktop Linux)
  • --uid 0 --gid 0: Root ownership (for system images)
  • Custom values: Match specific user requirements

Use Cases:

  • Allow non-root users to access mounted disk images
  • Match ownership to container or VM user mappings
  • Control write permissions in read-write mounts

§FUSE Integration Details

The FUSE implementation uses the fuser crate to implement:

FUSE Operations:

  • lookup(): Resolves disk and memory file entries
  • getattr(): Returns file metadata (size, permissions, ownership)
  • read(): Reads data from snapshot at specified offset
  • write(): Writes data to overlay (read-write mode only)
  • release(): Syncs overlay metadata on file close

Mount Options:

  • FSName=hexz: Identifies mount in /proc/mounts
  • DefaultPermissions: Enables kernel permission checks
  • RO or RW: Read-only or read-write mode

§Common Usage Patterns

# Read-only FUSE mount
hexz mount snapshot.st /mnt

# Read-write mount with ephemeral overlay
hexz mount snapshot.st /mnt --rw

# Read-write mount with persistent overlay
hexz mount snapshot.st /mnt --rw --overlay changes.overlay

# Mount as daemon with cache
hexz mount snapshot.st /mnt --daemon --cache-size 512M

# NBD mount (requires root)
sudo hexz mount snapshot.st /mnt --nbd

# Custom ownership
hexz mount snapshot.st /mnt --uid 1000 --gid 1000

Functions§

run
Executes the mount command to expose a snapshot via FUSE or NBD.