antiX LiveCD/USB Persistence Options

On this page:

What is Persistence?
Three Kinds of Persistence
Persistence/Remaster Features
Persistence/Remaster System Resources
How it Works
- How Home Persistence Works
- How Root Persistence Works
Persistence Options
Details for Developers
- When to Synchronize the root.fs File
- Creating Persistence Files

What is Persistence?

Persistence is a hybrid between a LiveCD/USB and a full install. One of the beauties of a LiveCD is that it allows you to boot Linux without touching any hard drives so you can have a "test-drive" without fear of altering your current system. Another feature of a LiveCD is that once it is burned, it is close to impossible for it to get infected with a virus or a Trojan horse. Every time you boot it, you start off with a system that is clean and pristine.

Persistence gives you a way of remembering things between boots. In order to do so, it needs access to a read-write device, typically either a hard drive or a USB stick. If you are only using one machine that is yours then you can put the persistence file(s)s on one of your hard drives.

one more paragraph here

Three Kinds of Persistence

The antiX distribution offers up to three different forms of persistence on our Live Media (LiveCD/DVD/USB, etc). Remastering is only available on writable media such as a LiveUSB or a LiveHD (frugal install) not a CD or DVD. All three forms can be used together if desired. They each have different strengths and weakness which are important to understand in order choose the right method or methods for your purposes.

Home Persistence

Home persistence is the simplest and safest. The homefs persistence file is mounted at /home. Any changes made to files under /home are (nearly) instantly stored on homefs filesystem. It is good if you want to save settings (such as bookmarks or changes to your desktop) but it doesn’t save changes made to the system (such as installing packages). Generally, if you need the root password to do it then it is not saved. Home persistence is also ideal if you want to download and save a lot of data. It is the safest precisely because you can’t save any system changes with it. Even if your system gets compromised, it will be very difficult for the bad guys to make any permanent changes to your system.

Root Persistence

Root persistence allows you to save changes to the system in addition to saving personal settings. It has two significant limitations. These limitations are due to the fact that as the system is running the changes are stored in RAM and will be lost unless they are specifically copied back to the rootfs file. If your computer crashes before the changes are copied back then your changes will be lost. The other limitation is that the amount of new information you can store is limited by how much free RAM you have.

Remastering

We include remastering as a form of persistence for purposes of comparison. The Remastering page contains implementation details. If root persistence is like using a piton while climbing up a cliff, remastering is more like setting up a camp or bivouac site.

Persistence/Remaster Features

Blah, blah, blah.

	Persistent Home	Persistent Root	Remaster
Large Storage	Yes	No	Yes
Save Personal Info	Yes	Yes	No
Save System Settings	No	Yes	Yes
Save Packages	No	Yes	Yes
Snapshot/Rollback	No	Yes	Yes
Changes stored Instantly	Yes	No	No
Easy Redistribution	No	No	Yes

Persistence/Remaster System Resources

Blah, blah, blah.

	Persistent Home	Persistent Root	Remaster
Extra RAM	None	Varies	None
Extra Disk Space	Varies	Varies	Large
CPU @ Creation	Tiny	Tiny	Large
CPU @ Startup	None	Varies	None
CPU @ Shutdown	None	Varies	None

How it Works

The information for both root and home persistence is stored in two files called rootfs and homefs. Unlike previous versions of antiX, there is no longer an option to use a entire partition for root or home persistence. The default location for these files is right next to the squashfs file, on the same device and in the same directory. We suggest that you use this default location whenever possible, but sometimes it is not possible (such as when booting from a LiveCD or LiveDVD). For these cases you can specify which device the persistence files are on. You can also specify a different directory.

How Home Persistence Works

How Root Persistence Works

Note for Developers

In order to prevent mysterious breakage down the road, It is strongly suggested that you always put the full antiX version information (or a reasonable abbreviation of the version information) in the path leading to these files. The version information should always be in the VERSION file in the top directory of official antiX ISO files. This means that if you add persistence to a LiveCD, you will need to specify a persistdir since the directory that holds the linuxfs file on a LiveCD is simply /antiX.

Persistence Options

The Main Persistence Option

persist

This is the main persistence option. It controls which type of persistence to use (home or root or both) and whether failure to find and mount a persistence file generates a fatal error. Without any values, the persist option by itself enables "optional" root and home persistence. The term "optional" means that if a persistence file is found and can be mounted then persistence is enabled but if the file can’t be found we boot anyway but without that form of persistence. This default behavior can be fine-tuned with the following values. Multiple values can be concatenated with commas.

persist=home

Use optional home persistence.

persist=home!

Require home persistence. In other words, don’t boot if we can’t enable home persistence.

persist=root

Use optional root persistence.

persist=root!

Require root persistence. In other words, don’t boot if root persistence can’t be enabled.

persist=scan

Scan for all read-write devices to find the persistence files. The default is for the persistence files to be on the same device and in the same directory as the linuxfs file. You can also use persistdev or persistlabel or cheat persistuuid: to specify a different device for the persistence files. If none of those three options are given but scan is one of the values in the persist option then all read-write devices will be scanned to find the persistence files. The scan stops as soon as a directory holding at least one of the requested persistence files is found.

This option should not be used for LiveUSBs or LiveHDs where the device holding the persistence files is known. It is intended to be used in LiveCDs so the user only needs to make a persistence files somewhere in the correct directory for persistence to be enabled. Without this option, the user would either have to specify the device holding the the persistence file(s) on every boot or change the disk label of the device holding the persistence file(s).

Examples of using the persist Option

A few examples might be more clear than a long winded explanation.

persist

The default. Optional root persistence and optional home persistence.

persist=root!

Required root persistence. No home persistence.

persist=root!,home

Required root persistence. Optional home persistence.

persist=scan,root

Scan for a rootfs persistence file. Optional root persistence. Any homefs file will be ignored because home persistence is disabled.

persist=scan

Scan for rootfs and homefs persistence files. Both root and home persistence are optional.

The Persistence Device

The default persistence device is the same device the linuxfs file was found on. We suggest that you always use this default when possible. For cases where that is not possible, you have to same options for specifying the persistence device as are available for specify the boot device. They abbreviate in the same way too, with "persist" collapsing to "p".

persistdev

The name of the device holding the persistence file(s). Abbreviation: pdev.

persistlabel

The label of the device holding the persistence file(s). Abbreviations: plabel and plab.

persistuuid

The UUID of the device holding the persistence file(s). Abbreviation: puuid.

The Persistence Directory

The default persistence directory is the same directory that holds the linuxfs file even if it is on a different device. We suggest that you stick with this default except when that directory does not include the antiX version (or a reasonable abbreviation).

persistdir

The directory in which the rootfs and/or homefs files can be found. The default is to use the same directory that the linuxfs file was found in even if it is on a different device. Abbreviation: pdir.

persistretry

The number of times to retry mounting the persistent files device. Abbreviation: pretry.

Details for Developers

The only work that needs to be done for home persistence is the creation of the homefs file and the addition of the appropriate boot parameters to Grub menu entries. This is probably best done at LiveUSB creation time, but it can also be done after the fact from within antiX.

In contrast, root persistence requires that a program be run in order to save changes made in RAM back to the file system in the rootfs file. The best tool for this job is the rsync program which update the rootfs file system as efficiently as possible. At its core, this saving back to rootfs requires just one command:

# rsync -a --delete --exclude tmp --exclude var/tmp /aufs-ram /persist-root

But as with the remastering, there are many details to take care of. If persistent root was successfully enabled then a persistent-root.conf configuration file should show up in the /live-config directory. This file should supply all the information needed to sync changes back to the rootfs file.

Example /live-config/persistent-root.conf file

PERSIST_MP="/boot-dev"
ROOTFS_MP="/persist-root"
AUFS_RAM_MP="/aufs-ram"
PERSIST_FILE="/boot-dev/antiX-12/rootfs"
PERSIST_DEV="/dev/sdb2"

Here is a bare-bones script for saving persistent root changes:

#!/bin/bash

conf_file=/live-config/persistent-root.conf

#--- Read variables from conf_file
[-f $conf_file ] || exit
source $conf_file

#--- Mount device holding rootfs file if needed
mountpoint -q $PERSIST_MP || mount $PERSIST_DEV $PERSIST_MP

#--- remount read-write if needed
mnt_opts=$(grep "^$PERSIST_DEV " /proc/mounts | cut -d" " -f4)
case ",$mnt_opts," in
    ,rw,) ;;
       *) mount -o remount,rw $PERSIST_MP;;
esac

#--- Mount the rootfs file if needed
mountpoint -q $ROOTFS_MP || mount -o loop $PERSIST_FILE $ROOTFS_MP

#--- now do the rsync
rsync -a --delete --exclude tmp --exclude var/tmp $AUFS_RAM_MP $ROOTFS_MP

umount $ROOTFS_MP

Of course, a real-world script will need more error checking and more verbose output (at least for testing). For example, a simple check of the size of the rootfs file system and the amount of space used on the /aufs-ram file system should be made to make sure there is enough space on rootfs before starting the rsync. If there is not enough space then a larger rootfs file could be created. The old rootfs could either be deleted or saved as a backup or snapshot.

When to Synchronize the `root.fs` File

The most obvious time to synchronize the rootfs file is during shutdown. This should probably be the default, but it’s not the only option. Users might want to manual sync before shutdown or they might want to be asked whether they want to sync at shutdown. These three options can be thought of as: "automatic", "manual", and "semi-automatic". Both the manual and semi-automatic synchronization should be implemented with a GUI. Even the automatic saving could be done in a GUI before X windows is shut down and before the user is logged out of their desktop session. A GUI would remind the user that their changes are being saved and would also make it easier for the user to deal with error conditions such as not having enough room on the rootfs device for saving all the changes.

Peristent root and Remastering Issues

This has not been implemented yet

Creating Persistence Files

The homefs and rootfs persistence files are straightforward to create once you know the trick. You just need to decide how large you want to make the file and what file system you want to use on it. We suggest using ext2, ext3, or ext4. If file(s) will be on a USB stick then you should consider turning journaling off if using ext3 or ext4 to prevent shortening the life of the USB stick. Enabling extents in ext4 might increase efficacy, especially on USB sticks. Here we will show how to create a 500 Meg rootfs file:

$ SIZE=500
$ dd if=/dev/zero of=rootfs bs=1M count=0 seek=$SIZE
$ mkfs.ext4 -q -m 0 -O ^has_journal -F rootfs

You need root privileges in order to mount this for testing:

$ sudo mkdir -p /mnt/loop
$ sudo mount -o loop rootfs /mnt/loop
$ df -h /mnt/loop
Filesystem            Size  Used Avail Use% Mounted on
/home/work/rootfs    485M  2.3M  482M   1% /mnt/loop
$ sudo umount /mnt/loop

Note that even with journaling disabled and with the reserved block percentage (-m) set to zero, not all of the space in the file is available. That’s because there is inevitable overhead in the filesystem.