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!

, , , , , ,

21 responses to “Tutorial: wheezy live iso-hybrid with persistence on USB”

  1. I’d be interested to know how to get the persistent partition encrypted.

  2. Hi,

    $ mv syslinux/isolinux.bin syslinux/syslinux.bin
    There is no reason for renaming isolinux.bin since it is no longer used.

    The new bootloader code (the part outside of VBR) is located in /ldlinux.sys after issuing:
    $ syslinux -i /dev/sdX3

    If you want to put it under /syslinux use -d option
    -d, –directory subdirectory
    Install the SYSLINUX control files in a subdirectory with the
    specified name (relative to the root directory on the device).

    $ syslinux -i /dev/sdX3 -d /syslinux

  3. Many thanks for your great tutorial. It was the only one that was working for me. I tried Unetbootin, live usb creator and many more.
    Your tut rocks!
    One thing is left and maybe your genius can help: I need to install specific software on that usbstick. Also drivers for network and graphic cards. Of course I see how to store them persistently, but how can I keep them in an installed state so I do not have to install them on every boot?

  4. Jamba, I’m glad it worked for you. I’m not sure what your issue about installing drivers is, but rather than doing support here in the comments, please post your issue to the mailing list: http://lists.debian.org/debian-live or join us on irc at irc://irc.debian.org/debian-live . If it’s simply a matter of including non-free drivers, the unofficial non-free images here may be what you’re looking for: http://live.debian.net/cdimage/release/7.3+nonfree/

  5. A BIG thanks for your tuto !

    It helped me a lot as i was trying to make a custom debian wheezy iso but i couldn’t boot on it on usb key. I’d rather using simple command line tools than something like unetbootin (which one day may be not working anymore, who knows ?)

    Thanks again !

  6. That version of the manual applies to the versions of live-build in testing/unstable, so some details may differ. Until we get the stable manual up on the new site, please use the live-manual package in Debian itself.

  7. Hey, could you install virtualbox on a persistent debian live stick? Or is that not possible due to some kernel stuff (im not that familiar with that)

    The basic idea is just to travel with a usb stick with multiple virtual OSes on it and a live OS to host them.

  8. While I think I followed every step of this guide exactly, the result does not seem to work. No persistence.
    One thing differed from the guide:
    “Unplug the key and plug it in again so the new partitions will be automounted. Observe where the partitions are mounted with df”.
    When I plugged the key in, no partitions where automounted. I should mention that I tried to create the key from *another* live system on another key. So I mounted them myself, /dev/sdb2 to /media/user/persistence.
    I think something went wrong with mount/automount.
    When I df after reboot, I see:
    /dev/sdb3 /lib/live/mount/persistence/sdb3
    /dev/sdb2 /media/user/persistence
    Trying to write persistence.conf to /media/user/persistence has no effect, after reboot the folder is empty.
    I am pretty sure I never mounted sdb3 the way it is now in df.
    So my question is:
    Where are those mounts / automounts configured? /etc/fstab has no entries for /dev/sdbX.
    Can I change the mounts now, after install? From the running live instance, or from another linux instance with the key plugged in?
    Thanks for any help…

  9. Othmar, I think you should try asking on the debian-live mailing list, as I have retired from the project and am no longer involved. Please take care to fully describe your problem so it can be reproduced by anyone who might want to help, and don’t merely link back to my unofficial blog article (which is for oldstable, not current stable, anyway, though it should work with current stable).

    Best of luck!

  10. @Othmar Found that the command

    `$ sed -i ‘s/\(append boot=.*\)$/\1 persistence/’ syslinux/live.cfg`

    (at least for Debian 9 Stretch) is not effective anymore.`live.cfg` doesn’t exist anymore. I’ve found that `menu.cfg` under the same directory (`syslinux/`) seems to do the job now. So try to add the term `persistence` in every line which begins with `APPEND` precisely after

    `boot=live components`
    resulting in
    `boot=live components persistence`

    If you are not accommodated with sed, as me, you might do it manually, or use something like Vim macros. You should at least do it for the first occurrence and/or the occurrence of your locales. Because the above `$ sed` command appends the term `persistence` at the end of the line where it is ineffective anymore –because now the `locales=…` setting is at the end of the line.

    E.g. The first locale specific entry should look like this in the end:
    `MENU begin advanced
    MENU title Debian Live with Localisation Support
    LABEL Albanian (sq)
    SAY “Booting Albanian (sq)…”
    linux /live/vmlinuz-4.9.0-3-amd64
    APPEND initrd=/live/initrd.img-4.9.0-3-amd64 boot=live components persistence locales=sq_AL.UTF-8`

    I’m not an expert and I deduced this more by inferencing than by knowledge on how this things work, but the USB-drive i’ve made with this (best I’ve ever found) tutorial is persistent now.

  11. @Ben Armstrong Thank you for this wonderful tutorial.

    Actually after I’ve successfully installed Debian 8 Jessie on a USB-drive more than a year ago with it, I’ve re-searched for more than an hour for this precise tutorial.

    Is it possible to add an alternative sed command for the new `menu.cfg` file? See my post above with all the details.

    Also the `mklabel msdos` error doesn’t seem occur anymore.

  12. @Ben Armstrong … continuation to the my post before:

    The **automount** is not working like described in the tutorial —similar to @Othmar’s comment. But for me persistence was working after the `menu.cfg` issue was resolved like discussed before.

  13. Alex,

    Since the tutorial was written for Wheezy, two releases back from the current stable, Stretch, I’m not surprised people are having trouble with it. Unfortunately, I am no longer working on the Debian Live project, so you should contact them to sort out the trouble you’re having. Perhaps some soul who gets it all working again would like to blog about it themselves? I won’t be doing that. Good luck!


Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: