Creating and Mounting a Linux persistence.dat File for Ventoy: Complete Technical Guide

Creating a Linux persistence.dat file for Ventoy requires generating a non-sparse disk image with an ext4 filesystem labeled casper-rw using the CreatePersistentImg.sh script, placing it on the USB drive, and configuring the path through Ventoy's web UI so the live system mounts it automatically during boot.

Ventoy's persistence plugin enables Linux live distributions to retain user data and system modifications across reboots by utilizing a writable disk image file. This guide details the complete process of creating and mounting a Linux persistence.dat file for Ventoy, referencing the actual implementation in the ventoy/Ventoy repository source code. Understanding these technical requirements ensures your persistent storage functions correctly with Ubuntu, Debian, and other supported distributions.

Understanding Ventoy Persistence Requirements

Before creating the file, you must understand the specific technical requirements Ventoy enforces for persistence images. These specifications are hard-coded into the Ventoy source and validated during the boot process.

File Naming and Location Conventions

Ventoy accepts two naming patterns for persistence files. The system first looks for a distribution-specific file named <os_name>_persistence.dat (for example, ubuntu_persistence.dat or debian_persistence.dat). Alternatively, if you place a file named exactly persistence.dat at the root of the USB drive, Ventoy recognizes it as a generic persistence image. According to the UI strings in Plugson/www/plugson_persistence.html, valid paths include both Windows-style (\ventoy\ubuntu_persistence.dat) and Linux-style (/ventoy/ubuntu_persistence.dat) syntax, though the path is stored verbatim in the configuration.

Filesystem and Label Specifications

The disk image must contain a valid ext2, ext3, ext4, or xfs filesystem. The filesystem label is critical: it defaults to casper-rw, which matches the default expectation of Ubuntu and Debian live systems. You can specify a custom label using the -l option when creating the image, but you must ensure the boot parameters match this label exactly. The filesystem creation logic resides in CreatePersistentImg.sh, which invokes mkfs with the appropriate label flag.

Optional Configuration and Encryption

For distributions that require explicit persistence configuration, you can embed a configuration file (default name persistence.conf) inside the image containing the line / union. This is enabled via the -c option in the creation script. Additionally, LUKS encryption is supported for select distributions using the -e flag, which invokes cryptsetup during image creation. However, encryption only functions if the target distribution's initramfs includes the necessary cryptsetup hooks to unlock the device during boot.

Creating a Linux persistence.dat File Using Official Scripts

Ventoy provides two Bash helper scripts in the INSTALL directory to manage persistence images without manual partitioning.

Using CreatePersistentImg.sh

The CreatePersistentImg.sh script generates a fresh, non-sparse file with a formatted filesystem. This script is located at INSTALL/CreatePersistentImg.sh in the Ventoy repository. The script forces a non-sparse file by piping dd output through tr '\000' '\377' to fill the entire allocated space with 0xFF bytes. This is essential because sparse files would break the loop-device mount that Ventoy performs during boot.

The script accepts the following key parameters:

• -s <size-MB>: Specifies the image size in megabytes (default 1024). Minimum requirements vary by filesystem: xfs requires at least 16 MB, while ext filesystems require at least 1 MB.
• -t <fstype>: Selects the filesystem type (ext4, ext2, ext3, or xfs).
• -l <label>: Sets the filesystem label (default casper-rw).
• -c <config-file>: Copies a configuration file into the image (typically containing / union).
• -o <output-file>: Names the output file (default persistence.dat).
• -e: Enables LUKS encryption (requires cryptsetup).

To create a 4 GB ext4 persistence file for Ubuntu:

sudo ./CreatePersistentImg.sh -s 4096 -t ext4 -l casper-rw -c persistence.conf -o ubuntu_persistence.dat

Extending Existing Images with ExtendPersistentImg.sh

If you need to resize an existing persistence file without losing data, use INSTALL/ExtendPersistentImg.sh. This script grows or shrinks the file while preserving the underlying filesystem structure. You specify the target size in MB, which can be negative to shrink the image, though shrinking requires sufficient free space within the filesystem.

sudo ./ExtendPersistentImg.sh ubuntu_persistence.dat 8192

Manually Mounting and Verifying a persistence.dat File

For troubleshooting or data recovery, you can manually mount the persistence file on a Linux host to verify its contents or label. Ventoy itself does not use these commands during boot—it passes the file directly to the kernel as a block device—but manual mounting validates that the image was created correctly.

First, associate the file with a loop device:

LOOP=$(losetup -f --show ubuntu_persistence.dat)

Verify the filesystem label matches expectations:

sudo blkid ${LOOP}

# Expected output: LABEL="casper-rw"

Mount the filesystem read-write to inspect or modify contents:

sudo mkdir -p /mnt/persist
sudo mount ${LOOP} /mnt/persist
df -h /mnt/persist

When finished, unmount and detach the loop device:

sudo umount /mnt/persist
sudo losetup -d ${LOOP}

Ventoy Persistence Plugin Architecture

Understanding the internal data flow helps diagnose configuration issues. The persistence plugin implementation spans multiple source files in the Plugson directory.

Core Data Structures and API Functions

The file Plugson/src/Web/ventoy_http.h defines the plugin_type_persistence constant and the persistence_node structure, which forms a linked list stored in g_data_persistence[bios_max+1]. Each node contains the file path, label, and optional configuration data.

In Plugson/src/Web/ventoy_http.c, several functions manage persistence state:

• ventoy_data_default_persistence(): Initializes and clears the persistence node list.
• ventoy_data_save_persistence(): Serializes the linked list into Ventoy's internal JSON format, storing the path exactly as specified in the web UI.
• ventoy_api_get_persistence(): Exposes current persistence entries to the web interface.
• ventoy_api_save_persistence(): Receives JSON payloads from the web UI, updates the persistence_node list, and writes the configuration to ventoy.json.

Web UI Configuration Flow

The file Plugson/www/plugson_persistence.html renders the persistence management interface. When you add a persistence entry through the web UI, the path is captured (supporting both Windows and Linux path syntaxes) and passed to ventoy_api_save_persistence(). At the next boot, Ventoy reads ventoy.json, constructs the appropriate kernel command line parameters (persistent, persistent-path=..., persistent-label=...), and appends them to the live OS boot options. The live system's initramfs then locates the file by label and mounts it as the writable layer (typically at /cow for Ubuntu-based systems).

Critical Considerations for Ventoy Persistence

Several technical constraints can cause persistence to fail silently if ignored. The Ventoy source code enforces these requirements strictly.

Filesystem Compatibility: Not all distributions support xfs persistence. Ubuntu and Debian expect ext2/3/4 with the casper-rw label. Using xfs without explicit distro support results in a read-only live environment.

Non-Sparse File Requirement: The image must be a fully allocated, non-sparse file. The CreatePersistentImg.sh script enforces this by writing 0xFF bytes across the entire file size. Sparse files appear smaller to the kernel and break loop-mounting during boot.

Size Alignment: Ventoy expects the image size to be an exact multiple of 1 MiB. The script handles this alignment automatically when you use the -s parameter. Manual creation with dd must respect this alignment constraint.

Label Mismatch Risks: If the kernel boot parameters specify a label that differs from the actual filesystem label created with -l, the live system will fail to locate the persistence device and boot without write support. Always verify with blkid before deployment.

Multi-Distro USBs: When running multiple Linux distributions from one USB drive, you must either use separate files (ubuntu_persistence.dat, debian_persistence.dat) or ensure all distros share the same persistence label and configuration. The web UI allows configuring separate paths for each ISO.

Encryption Limitations: LUKS-encrypted persistence (enabled with -e) requires that the target distribution's initramfs includes cryptsetup and knows how to prompt for the passphrase during early boot. Only specific distributions support this workflow.

Complete Workflow: From Creation to Boot

Follow this verified sequence to deploy persistence on your Ventoy USB drive:

1. Prepare the USB device by installing Ventoy using the official installer, ensuring the partition table is correct for your boot mode (MBR or GPT).

2. Generate the persistence image using the official script with appropriate size and label:

   sudo ./CreatePersistentImg.sh -s 4096 -t ext4 -l casper-rw -o ubuntu_persistence.dat

3. Copy the file to the USB in either the root directory or the ventoy/ subdirectory:

   sudo cp ubuntu_persistence.dat /media/username/Ventoy/ventoy/

4. Configure via Web UI: Boot any computer from the Ventoy USB, press F2 (or access the Plugson interface), navigate to the Persistence tab, and add the path /ventoy/ubuntu_persistence.dat to the appropriate ISO entry.

5. Save configuration: Click Save in the web UI. This invokes ventoy_api_save_persistence() in ventoy_http.c to write the updated ventoy.json file.

6. Boot the target system: Select your Linux ISO from the Ventoy menu. The kernel will receive the persistent parameter and automatically mount the file as the writable overlay.

7. Verify operation: Once booted, run mount | grep casper to confirm a mount point like /cow exists, indicating the persistence layer is active.

Summary

• Use CreatePersistentImg.sh to generate non-sparse persistence images with proper alignment and filesystem labels.
• Ensure the label matches the default casper-rw or your custom boot parameter configuration.
• Place the file at the USB root as persistence.dat or in the ventoy/ folder as <distro>_persistence.dat.
• Configure paths through the Ventoy web UI, which stores data via ventoy_data_save_persistence() in ventoy.json.
• Avoid sparse files and ensure size multiples of 1 MiB to prevent loop-mount failures.
• Verify manually using losetup and mount before deployment to confirm filesystem integrity.

Frequently Asked Questions

Can I use the same persistence.dat file for multiple Linux distributions on one USB?

You can share a persistence file only if all distributions use the same persistence label (default casper-rw) and compatible filesystem types. However, separate files are recommended (e.g., ubuntu_persistence.dat and debian_persistence.dat) to avoid configuration conflicts. The Ventoy web UI in plugson_persistence.html allows you to map specific files to specific ISOs in the ventoy.json configuration.

What happens if I create a sparse persistence image instead of a non-sparse one?

Ventoy requires a fully allocated, non-sparse file because the kernel treats the image as a raw block device. Sparse files break the loop-mount mechanism and cause the live system to boot without persistence enabled. The official CreatePersistentImg.sh script prevents this by writing 0xFF bytes across the entire file using tr '\000' '\377', ensuring the file occupies its full declared size on disk.

How do I resize an existing Ventoy persistence file without losing data?

Use the ExtendPersistentImg.sh script provided in the INSTALL directory. This utility safely expands or shrinks the file while preserving the existing filesystem. Specify the new size in MB as the second argument; for example, sudo ./ExtendPersistentImg.sh persistence.dat 2048 grows the file to 2 GB. The script handles the underlying filesystem resize operations automatically.

Is LUKS encryption supported for Ventoy persistence files?

Yes, but with limitations. You can create an encrypted persistence image using the -e flag in CreatePersistentImg.sh, which invokes cryptsetup to encrypt the container. However, only specific distributions (such as Ubuntu with full disk encryption support in the initramfs) can unlock the device during boot. Ventoy passes the encrypted block device to the kernel, but the live OS must handle the decryption prompt and mounting logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}