Tutorial: wheezy live iso-hybrid with persistence on USB

As of wheezy, Debian no longer offers for download any prebuilt hdd (formerly known as usb-hdd) live images, which, in squeeze, were necessary if you wanted to use persistence. The good news is, since the new wheezy iso-hybrid images use xorisso, you can copy an image to a USB key and repartition it to add a persistence partition. Unfortunately, the filesystem itself is read-only, so you have to manually append the persistence boot parameter each time you boot the image. If that doesn’t bother you, you can skip this whole tutorial and just follow the instructions in live-manual for adding a persistence partition and you’re all set.

This tutorial explains how to extract the contents of a wheezy iso-hybrid live image to a USB key and modify it to boot with this parameter permanently enabled. I am writing it solely as a workaround and do not endorse this as a means to customize Debian Live images in general. I would love to help make a more convenient, supported way to accomplish the same thing for a future release. Meanwhile, the supported and recommended way to make any change to a Debian Live image is to build it from scratch using live-build, as described in live-manual. A simplified Debian Live Images Autobuilder web service is available that works well for many common customizations, if you prefer. Please use one of these methods if you want to do this, or other customizations in the supported way. Otherwise, read on.


  • You need to download a Debian iso-hybrid live image. For this tutorial, I will use the Debian live wheezy amd64 LXDE image:
  • Note the size of the image. With ls -lh debian-live-7.0.0-amd64-lxde-desktop.iso you can see the image size for this example is 854M. Later, you will use this size plus 5% for the size of the partition to receive its contents.
  • You need a USB key large enough for both the image itself and your persistence partition. For this image, you could even use a 1G key, although that would leave very little space for persistence. In this tutorial, the test key is 8G, leaving lots of room on the key for growth.
  • I assume for this example you are preparing the key on a Debian or other Linux system that automounts media when they are plugged in, a fairly normal configuration.
  • This tutorial also uses the following tools, which you will need to install if you don’t have them already:
    • parted
    • mbr
    • dosfstools
    • p7zip
    • syslinux

Identify the USB key device

Caution: Always double-check the device you are writing to is the correct one to avoid losing precious data. There are two things to do to protect yourself. The first is, don’t write the USB key as root. The second is, first use ls -l /dev/disk/by-id to identify which device is the target USB key.

lrwxrwxrwx 1 root root  9 Jun 22 11:58 
usb-SanDisk_Cruzer_Contour_0000184CA87406BC-0:0 -> ../../sdb

As you can see, my SanDisk Cruzer Countour is /dev/sdb. For the rest of the tutorial, I’ll be referring to this device as /dev/sdX to avoid unfortunate cut-and-paste disasters. When you follow along, make sure you substitute the correct device for your USB key on your system.

Initialize the USB key

Start by plugging in the key and unmounting any automounted partitions to ensure nothing is accessing the device, e.g.

$ umount /dev/sdX1

Now make changes to the partition table. Use parted because it may be run as an ordinary user and has some advanced capabilities beyond more basic tools like fdisk.

$ /sbin/parted
WARNING: You are not superuser.  Watch out for permissions.
GNU Parted 2.3
Using /dev/sdX
Welcome to GNU Parted! Type 'help' to view a list of commands.
(parted) print devices
/dev/sdX (8221MB)
(parted) select                                                           
New device?  [/dev/sdX]?                                                  
Using /dev/sdX

Note that when run as an ordinary user, if you only have one removable drive (which may include mp3 players, cameras, e-readers) plugged in, parted immediately selects that device. But just to be sure, use print devices to list the devices and select to if you need to select a different one, as shown above.

Repartition the USB key

Once you’ve verified you have the correct device, start repartitioning. Write a new partition table with mklabel msdos to wipe out all of the old partitions on it. You may skip this step and adapt the remaining instructions if there are partitions you need to keep. This is your last chance to bail if the device is wrong, so make sure it is the correct one before proceeding.

(parted) mklabel msdos
Warning: The existing disk label on /dev/sdX will be destroyed and all data
on this disk will be lost. Do you want to continue?
Yes/No? y
Error: Partition(s) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 on
/dev/sdX have been written, but we have been unable to inform the kernel of
the change, probably because it/they are in use.  As a result, the old
partition(s) will remain in use.  You should reboot now before making further
Ignore/Cancel? i

The error is normal, and appears when you run parted as an ordinary user, so it is OK each time it appears to press “i” to ignore it. For the rest of this tutorial I will omit these errors from the output for brevity.

Make three partitions, a fat32 partition for the image itself that is 5% larger than the size of the ISO, a 1G ext4 partition for persistence, and an extra fat32 partition for the rest of the space. Put the extra partition first so that other OSes you might use the key with will be able to use it. Use relative positioning from the end of the device to make it easy to put all of the rest of the space in the first partition. Finally, flag the live image partition bootable.

(parted) mkpart primary fat32 1 -1897M
(parted) mkpart primary ext4 -1897M -897M
(parted) mkpart primary fat32 -897M -0
(parted) set 3 boot on
(parted) quit
Information: You may need to update /etc/fstab.

Unplug the USB key and plug it in again so that the kernel will re-read the updated partition table. If there were old filesystems on the key that were automounted, unmount them again. Now we’re ready to make the new filesystems.

$ umount /dev/sdX1
$ /sbin/mkdosfs -nEXTRA /dev/sdX1
mkdosfs 3.0.16 (01 Mar 2013)
$ /sbin/mkfs.ext4 -q -Lpersistence /dev/sdX2
$ /sbin/mkdosfs -nLXDE /dev/sdX3
mkdosfs 3.0.16 (01 Mar 2013)

Make the USB key bootable

Use install-mbr to install an MBR on the key and syslinux to install the bootloader to boot into your live image partition.

$ /sbin/install-mbr /dev/sdX
$ syslinux -i /dev/sdX3

Mount the partitions

Unplug the key and plug it in again so the new partitions will be automounted.

Observe where the partitions are mounted with df.

$ df
/dev/sdX1        6204568         4   6204564   1% /media/EXTRA
/dev/sdX3         831888         4    831884   1% /media/LXDE
/dev/sdX2         944120      1204    894124   1% /media/persistence

Extract the ISO contents to the key

To continue preparing this key as an unprivileged user, use p7zip to extract the ISO. You may alternatively mount the ISO loopback and extract it that way, but you must be root to do that.

$ cd /media/LXDE
$ 7z x ~/debian-live-7.0.0-amd64-lxde-desktop.iso
Extracting  live/filesystem.packages-remove

When live/filesystem.squashfs is extracted (right after live/filesystem.packages-remove) it will take the longest time of all of the files to extract, as it contains the whole live filesystem. Be patient and eventually it and all other files on the image will finish extracting.

Everything is Ok

Folders: 245
Files: 370
Size:       892183367
Compressed: 895483904

Modify the bootloader configuration files

The syslinux bootloader configuration directory and files within it are named isolinux when installed on an ISO. You need to rename the directory and two files changing isolinux to syslinux so the bootloader will find them on your fat32 live image partition.

$ mv isolinux syslinux
$ mv syslinux/isolinux.cfg syslinux/syslinux.cfg
$ mv syslinux/isolinux.bin syslinux/syslinux.bin

Enable full persistence

Next, append “ persistence” to the live boot parameters and turn on full persistence by putting “/ union” in a persistence.conf file in the persistence partition.

$ sed -i 's/\(append boot=.*\)$/\1 persistence/' syslinux/live.cfg
$ cd /media/persistence
$ echo / union > persistence.conf

Reboot into the live system

Now your USB key is ready to boot with full persistence enabled. Have fun!