Skip to content

Persistence

Jump to bottom
madkoding edited this page Mar 19, 2026 · 1 revision

Persistence Configuration Guide

This guide explains how to set up persistence on a USB drive to save your changes between boots.

Quick Start

After booting madOS from USB, run:

mados-persistence status   # Check current persistence status
mados-persistence info     # Show setup instructions
mados-persistence sync     # Force sync (rsync mode only)

Supported Methods

1. USB with Persistence Partition (Recommended)

Requirements:

  • USB drive with at least 8GB (4GB for system + 4GB for persistence)
  • Another Linux computer (or partitioning tool)

Steps:

  1. Write the ISO to USB:

    sudo dd if=madOS.iso of=/dev/sdX bs=4M status=progress

  2. Create an ext4 partition for persistence:

    sudo fdisk /dev/sdX    # Create new partition
sudo mkfs.ext4 -L mados-persist /dev/sdX3

  3. Boot from USB and select "madOS Live with Persistence"

  4. The system automatically detects the partition via cow_label=mados-persist

What's saved:

  • Home directory (/home)
  • System configurations (/etc)
  • Installed packages
  • All changes made to the system

2. Ventoy USB with Persistence

Ventoy is a boot loader that allows multiple ISOs on one USB.

Requirements:

  • USB drive (8GB+)
  • Another computer with Linux

Steps:

Step 1: Install Ventoy

Download Ventoy from https://ventoy.net and create a bootable USB:

# Download Ventoy
wget https://github.com/Ventoy/Ventoy/releases/download/1.0.99/ventoy-1.0.99-linux.tar.gz
tar -xzf ventoy-1.0.99-linux.tar.gz

# Install to USB (replace X with your USB drive letter)
sudo sh ventoy-1.0.99/Linux/ventoy -i /dev/sdX

Step 2: Copy madOS ISO

Mount the Ventoy USB and copy madOS.iso to the root directory.

Step 3: Create Persistence Image

Download the Ventoy persistence creation script:

wget https://github.com/Ventoy/Ventoy/releases/download/1.0.99/Ventoy2Disk.sh
chmod +x Ventoy2Disk.sh

# Create 4GB persistence image
sudo sh Ventoy2Disk.sh -i -s 4096 -l mados-persist /dev/sdX

This creates a persistence.dat file.

Step 4: Configure ventoy.json

Create or edit /ventoy/ventoy.json on the USB:

{
  "persistence": [
    {
      "image": "/madOS.iso",
      "backend": "/ventoy/persistence/mados-persist.dat"
    }
  ]
}

Step 5: Boot and Enjoy

Select "madOS.iso" from the Ventoy menu. The system will boot with full persistence.

Note: For more details, see https://ventoy.net/en/plugin_persistence.html

3. No Persistence (Default)

If you boot without persistence, all changes stay in RAM and are lost on reboot.

  • Select "madOS Live" from the boot menu
  • Uses cow_spacesize=256M for temporary storage
  • Good for testing or quick tryouts

Understanding Persistence Modes

Mode Description Use Case
cow_device Native Archiso overlay Direct USB (dd)
cow_label Overlay on labeled partition USB with extra partition
partition rsync to separate partition Ventoy or advanced
file rsync to image file Ventoy with .dat file
none No persistence Testing only

Troubleshooting

Persistence not detected

  1. Check if partition has the correct label:

    sudo e2label /dev/sdX3
# Should show: mados-persist

  2. Verify boot parameters:

    cat /proc/cmdline
# Look for: cow_label=mados-persist

Changes lost after reboot

  1. Run mados-persistence status to check mode
  2. For rsync mode, ensure sync completed: 
    sudo mados-persistence sync

Slow performance

  • Use a fast USB 3.0+ drive
  • For Ventoy, use a dedicated partition instead of .dat file
  • Consider installing to internal storage

Commands Reference

mados-persistence status   # Show current persistence status
mados-persistence info     # Display this help guide
mados-persistence sync     # Force manual sync (rsync mode only)

Additional Resources

Clone this wiki locally