LiveCD/USB Guide
Persistence Options

## What is Persistence?

[top]

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

[top]

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

[top]

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

[top]

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

[top]

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

[top]

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

## Persistence/Remaster System Resources

[top]

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

## How it Works

[top]

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

[top]

### 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

[top]

### The Main Persistence Option

[top]

#### 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

[top]

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

[top]

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

[top]

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

[top]

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

[top]

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

[top]

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.