Function run 

pub fn run(
    hexz_path: String,
    mountpoint: PathBuf,
    overlay: Option<PathBuf>,
    daemon: bool,
    rw: bool,
    cache_size: Option<String>,
    uid: u32,
    gid: u32,
    nbd: bool,
) -> Result<()>

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

Mounts a Hexz snapshot at the specified mountpoint using either FUSE (default) or NBD (if --nbd flag is set). Supports read-only and read-write modes, optional overlay for copy-on-write, caching, and daemon mode.

Arguments

• hexz_path - Path to the .st snapshot file
• mountpoint - Directory where snapshot will be mounted
• overlay - Optional overlay file path for read-write mounts (persistent)
• daemon - If true, daemonize the process and run in background
• rw - If true, mount read-write with overlay; otherwise read-only
• cache_size - Optional cache size (e.g., “256M”, “1G”)
• uid - User ID for file ownership inside mount
• gid - Group ID for file ownership inside mount
• nbd - If true, use NBD instead of FUSE (requires root)

FUSE Mode (Default)

Creates a FUSE filesystem at mountpoint with:

• disk file containing disk image
• memory file containing memory dump (if present in snapshot)

Read-Only Mode:

• All writes are rejected with EROFS error
• No overlay file created
• Safe for concurrent mounts of same snapshot

Read-Write Mode:

• Writes captured in overlay file (4 KiB granularity)
• Metadata tracked in .meta file
• Overlay can be persistent (specified path) or ephemeral (temp file)

Daemon Mode:

• Process detaches and runs in background
• Logs redirected to /tmp/hexz.log and /tmp/hexz.err
• Working directory changed to /
• Useful for long-running mounts

NBD Mode (--nbd)

Creates an NBD block device and mounts it:

1. Starts internal NBD server on ephemeral port (localhost only)
2. Runs nbd-client to connect to server and create /dev/nbdN
3. Runs mount to mount the NBD device at mountpoint
4. Waits for Ctrl+C
5. Unmounts and cleans up NBD device

Requirements:

• Root privileges (uses sudo for nbd-client and mount)
• nbd kernel module loaded (sudo modprobe nbd)
• nbd-client utility installed

NBD Server:

• Binds to 127.0.0.1 (localhost only, not exposed to network)
• Automatically selects free ephemeral port
• Serves disk stream only (memory not exposed via NBD)

Overlay File Paths

If overlay is specified:

• Absolute path: Used as-is
• Relative path: Resolved relative to current working directory
• Path does not need to exist (will be created)

If overlay is None and rw is true:

• Creates temporary file that is deleted on unmount
• Useful for ephemeral changes (testing, development)

Errors

Returns an error if:

• Snapshot file cannot be opened
• Mountpoint does not exist or is not a directory
• FUSE mount fails (permissions, already mounted)
• NBD server fails to start (port unavailable, feature not compiled)
• NBD client/mount commands fail (not installed, wrong permissions)
• Daemonization fails (resource limits, permissions)

Examples

use std::path::PathBuf;
use hexz_cli::cmd::vm::mount;

// Read-only FUSE mount
mount::run(
    "snapshot.hxz".to_string(),
    PathBuf::from("/mnt"),
    None,
    false, // not daemon
    false, // read-only
    None,  // no cache
    1000,  // uid
    1000,  // gid
    false, // FUSE mode
)?;

// Read-write mount with persistent overlay
mount::run(
    "snapshot.hxz".to_string(),
    PathBuf::from("/mnt"),
    Some(PathBuf::from("changes.overlay")),
    false,
    true,  // read-write
    Some("512M".to_string()), // 512 MB cache
    1000,
    1000,
    false,
)?;