======Persistence for Dummies, or "Why can't I find my apps and settings after booting?"======
**This document is valid for Tiny Core Linux 3.6.**
=====Overview=====

//Note: You can skip reading anything in parentheses, which are included for clarification.//

When you boot Tinycorelinux (tcl) for the first time, such as from CD, the default mode of operation is "cloud mode", meaning all extensions are downloaded from the web for each session. (//Extensions can be apps such as a browser, or hardware drivers, modules, firmware or shared libraries. The extensions are compressed and packaged in files with .tcz extension.//) They are not permanently stored anywhere unless you specifically instruct tcl to do so. Same with settings changes you make - these are not permanently stored by default.

One way of understanding tcl is it consists of just 2 files, one file called vmlinuz containing all the Linux kernel stuff and the other the tcl-specific stuff, named core.gz. At each boot, these 2 files are unpacked and loaded into your PC's memory (RAM). So at each boot, it boils down to a fresh (lightning fast) install. Goodbye, system rot! 

Likewise with extensions, these are each [[http://en.wikipedia.org/wiki/Loop_device|loop mounted]] into a temporary location (///tmp/tcloop//), and linked into the main Linux file system, at each boot. So //everything// is installed at every boot. No corruption, ever! Uninstalling apps is rendered completely obsolete - just delete the packed app file, (//xxx.tcz//), and goodbye! No more useless left-behind files cluttering up the OS, ever! Upgrading to newer versions becomes dead simple - replace the older tcz package with the newer one. This is truly a new, unique concept. 

When you shut it down, all of the contents of your PC's RAM is lost, and therefore everything in the entire Linux file system as well. At next boot, everything is freshly created from the compressed files again. You can quickly see that tcl is utterly impervious to things like viruses or accidental file deletion - any damage is completely restored with a boot. Goodbye anti-virus!

This basic cloud mode is of course a problem once you decide to keep tcl - you hardly want to download your favourite extensions each time you boot, not to mention lose your own personal preferences and settings such as wifi stuff. Don't despair - tcl has been cleverly designed to save all your settings and extensions while retaining its bullet-proofness. You just have to tell it to do so. This ability to have your stuff saved for a next session is called "persistence." There are a number of entries on "persistence" in the wiki for further explanation. Another name commonly used is "backup".

So how does persistence work? Well it boils down to telling tcl to store your settings and extensions in a location on a permanent storage medium, instead of throwing everything in the volatile RAM away when you shut it down. This permanent location is the /tce directory. It is a central part of a persistent tcl installation.

**In Appbrowser, simply use the Set button to tell tcl where you want to store your stuff, and automatically all your stuff becomes persistent.**

An easy way to install Tiny Core from CD is using the built in installer. During installation, persistence is taken care of so you no longer have to worry about anything. See the [[wiki:start|installation guides]] in the wiki.
=====Getting tinycore to save your extensions=====

If you are not using persistence, all downloaded extensions are stored in a temporary directory called ''/tmp/tce/optional''. (//tce stands for Tiny Core Extensions.//) The ''/tmp'' directory is always lost at shutdown and freshly created at next boot, so you lose everything in it. 

When you use Appbrowser to download extensions, the target location for downloaded extensions is shown in the Appbrowser's status bar, bottom right. When that location is the ''/tmp/tce/optional'' directory, there is also a Set button available, so that you can easily select a persistent location. When you specify a location for a ''/tce'' directory on a storage medium, then that directory will be created there (//if it doesn't already exist//) and all extensions will be stored there permanently, in a subdirectory called ''/tce/optional'', instead of in the volatile ''/tmp/tce/optional''. 

===The /tce Directory===

If you are not familiar with the Linux file system, things may seem a bit confusing. This is not the place to explain all that, but it is handy to know that in Tiny Core Linux, the basic Linux file system is used, with all drives with partitions on them and other media that are found by tcl, as subdirectories in ''/mnt''.

The ''/tce'' directory is not a part of the Linux file system; instead it is typically in the root of a partition. So if you want to look at the contents, you have to look for it under ''/mnt''. For example, if tcl found a hard drive partition ''sda1'', it is shown as ''/mnt/sda1''. And if ''/tce'' was created on ''sda1'', then you would look for ''/mnt/sda1/tce''.

(//Note: Partitions are not necessarily mounted by default - you have to mount them using the ''mount'' command, eg ''sudo mount /dev/sda1'', which will result in the device ''sda1'' to be mounted in the default directory of ''/mnt/sda1''. tcl will do this automatically when creating /tce.//)

===Ways to specify the location of /tce===

  * **Using the Set button in AppBrowser**

By far the simplest way is by use of the Set button which becomes active in AppBrowser whenever a permanent storage has not been set. ''/tce'' will be created in the root of the selected suitable partition as found previously by tcl. Press the Set button, and select a partition from the list. That will now be the location where ''/tce'' is created and all your stuff will be stored from that point on. 

  * **Using a boot option "''tce=xxx''"**

Alternatively, you can specify the ''/tce'' directory's location as a boot option, "''tce=xxx''", where xxx is a suitable partition. (//Not a Windows NTFS partition - this is a proprietary Windows format and not supported by default.//) This boot option (also called boot codes) can also be specified in the boot stanza of the boot loader you are using (see [[wiki:boot_codes_explained|Boot codes explained]]). If you do it this way, you can place it anywhere you like on your PC - another partition, another hard disk altogether, even a usb stick that you plug in for the session, or inside another directory. 

//**Note: If you decide to use a USB device, you have to use a boot code of ''waitusb=5'' to tell tcl to wait 5s, or longer if required, for the usb file system to be mounted, or it will not find ''/tce'' and you will be running in cloud mode instead.**//

If you created ''/tce'' in the root of a partition, then the boot option is not required afterwards - tcl will scan all found partitions and use the first found ''/tce''. If you want to use another location, for example inside another directory, you have to continue using the boot option to ensure the correct location is found. 

It is not a bad idea to keep using the boot code afterwards, to avoid puzzling results where tcl found a different /tce than the one you were expecting to be used. This will also save some booting time as tcl won't be doing any scanning.

You can have more than one ''/tce'' location for different purposes, and set up a multi-boot scenario where you can choose which /tce to use for a particular session.

  * **Creating ''/tce'' manually**

You can also elect to create this directory manually yourself, in the root of a suitable partition. At the next boot tcl will scan all found partitions to find this directory and use it. It will use the first one found. You can create it while in cloud mode, and use the Shutdown dialog to tell tcl the location of this directory. tcl will then use this ''/tce'' to store all your stuff. (//Note that your extensions will not be moved automatically from ''/tmp/tce/optional'' when you do this for the first time, you either have to move them to ''/tce/optional'' manually, or reboot after ''/tce'' has been set, so that they will be stored in ''/tce/optional''.//)

  * **Installing tcl with built-in installer**

You can use the built-in installer to install tcl, and during this process, the location of ''/tce'' is also handled. Since you probably have to install tcl somewhere anyway, this becomes the easy way out for most cases. See the wiki [[wiki:start|index]] for installation guides.

=====Getting tinycore to save your documents and settings=====

Many settings, and all documents, are stored in your home directory called ''/home/tc'' (//also called ''$HOME'' or "~" //), and ''/opt''. (//''$HOME'' is roughly equivalent to "''Documents and Settings\USER\My Documents''" in Windows.//) If you are not using persistence, by default, these directories are lost at shutdown, so you lose everything. Tiny Core is very flexible and there are several ways to save your documents and settings for a next session. 

===By using the Backup Utility===

The default mode of saving your docs and settings is via the backup utility, which comes up when you do a shutdown. This backup utility creates a file called by default ''mydata.tgz'' (//if it doesn't already exist//), which contains your entire ''$HOME'' directory contents, and the ''/opt'' directory, both compressed. The file ''mydata.tgz'' is stored in ''/tce''. So, once you start using the ''/tce'' directory, automatically all your stuff becomes persistent.

When booting, tcl will first look for ''mydata.tgz'' in ''/tce'' and then scan partitions until found. If it is not found, an empty default will be created in ''/tce''. You can optionally specify a different location for the backup file with the boot code "''restore=xxx/any/storage/directory''", where xxx is a valid partition, and ''/any/storage/directory'' already exists.

You can optionally specify an alternatively named backup file by using the boot code "''mydata=xxx''", where xxx is the file name without extension.

The list of stuff saved in ''mydata.tgz'' is found in a file called ''/opt/.filetool.lst'', while the exclusions are in ''/opt/.xfiletool.lst''. Excluded items take precedence over included ones, so you can include a whole directory and exclude some bulky items from it.

''$HOME'' can quickly become quite large, and the backup during shutdown and subsequent restore at the next boot can take some time. You can reduce backup times by carefully excluding stuff you don't require to be restored - look for large directories and files to put in the exclude list. There is a utility ''BigHomeFiles'' in the Control Panel to aid in this. There are already some default exclusions from the ''$HOME'' directory such as cache files, to prevent saving any unecessary stuff.  

There are further ways to optimize boot times; static files and directories in ''$HOME'' can be made into extensions - see the wiki for more information on [[wiki:extension_for_settings|creating extensions for settings]].

===By specifying permanent directories for /home and /opt===

Another way of saving your stuff, is to tell tcl to use permanent directories for ''/opt'' and ''/home'' located on a storage medium. This is also done via boot codes, with "''opt=sda1''" and "''home=sda1''". These boot codes tell tcl not to create and restore ''/home'' and ''/opt'' at boot time from ''mydata.tgz'' as it would otherwise do, but rather to take these directories on the specified permanent storage medium and mount them into the linux file system instead. 

If they don't already exist in the specified locations, they will be freshly created there and populated with all the default files. The effect is that these two directories are now located on permanent storage, and anything you change and save there via the normal way is therefore saved immediately, permanently. Since they now exist on permanent storage, you no longer have to backup everything, so you can edit ''.filetool.lst'' and remove these entries from the list to prevent them from being backed up into mydata every time. 

Since ''/home'' and ''/opt'' locations are specified individually, you can have them anywhere on your PC - another partition, another hard disk altogether, even a usb stick that you plug in for the session. So you can save all your personal stuff in one place, easily backed up, and when your boot disk crashes or something, you still have all your personal stuff safely somewhere else. You can safely reformat your boot partition should something terrible happen without losing your personal data. Compare this to having your Windows disk crash!

The limitation - if you can even call it that - is these directories cannot exist in partitions other than linux ones; Windows file systems do not support file permissions which are a crucial part of this to work. To operate tcl entirely from a FAT partition, for example, you are forced to use the backup system. The ''/tce'' and all its contents do not require file permission information, so can be stored on a FAT partition if required.

Some more advanced settings are stored in the linux file system, and these cases have to be individually entered into the ''.filetool.lst'' to have them restored at the next boot. One such example is when you use the Xorg extension for improved graphics performance - its configuration file is ''/etc/X11/xorg.conf'', so to have any Xorg graphics settings permanent, you have to add ''etc/X11/xorg.conf'' to ''/opt/.filetool.lst''. (//Note the lack of leading forward slash!//) tcl will unpack all extensions and afterwards, will add any files you specified in this way to the linux file system.

=====Choosing a different Wallpaper/Desktop background=====

See [[wiki:wallpaper_desktop_background|Setting Up - Wallpaper]].
=====Executive summary===== 

  * To make everything persistent, use the Set button in Appbrowser to set a location for /tce. If using the built-in installer, this is taken care of.

  * To create permanent ''/home'' and ''/opt'' directories and reduce backup and restore times, use the boot option "''home=xxx''" and optionally, "''opt=xxx''" where "xxx" are any valid linux partitions. Manually edit ''/opt/.filetool.lst'' to remove the home entry and most ''/opt'' entries.

======Advanced Topics======
=====Using multiple /tce locations for a multi-boot scenario=====

When you specify the ''/tce'' directory's location as a boot option, you can place it anywhere you like on your PC - another partition, another hard disk altogether, even a usb stick that you plug in for the session, or inside another directory. 

**//Note: If you decide to use a USB device, you have to use a boot code of// ''waitusb=5'' //to tell tcl to wait 5s, or longer if required, for the usb file system to be mounted, or it will not find ''/tce'' and you will be running in cloud mode instead.//**

Because you can place a given boot case's /tce in any location, you can have more than one ''/tce'' location for different purposes, and set up a multi-boot scenario where you can choose which /tce to use for a particular session.

===Example: Grub boot stanzas===

<code>title tinycore (tce on USB)
root (hd0,0)
kernel /boot/bzImage quiet waitusb=5 tce=UUID="F0BC-3CAF"
initrd /boot/tinycore.gz</code> 
<code>title tinycore (tce on first hard drive partition)
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1 
initrd /boot/tinycore.gz</code> 
<code>title tinycore (tce for development)
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1/tce_storage/development
initrd /boot/tinycore.gz</code> 
<code>title tinycore (tce for just playing)
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1/tce_storage/playing
initrd /boot/tinycore.gz</code> 

=====Using multiple backup files for a multi-boot scenario=====
Having multiple /tce directories creates a lot of duplication in the extensions. This can suck up a lot of disc space. So instead, it is possible to have just one central /tce but with many backup files, one for each boot. This is done with boot codes. 

You can also mix the various methods.

====Method 1: Having multiple backup files in one /tce====
==Example: GRUB stanzas==
<code>title jack's development stuff
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1 mydata=develop
initrd /boot/tinycore.gz</code> 
<code>title jack's play stuff
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1 mydata=playing
initrd /boot/tinycore.gz</code> 
<code>title jill's stuff
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1 mydata=jill
initrd /boot/tinycore.gz</code> 
This method creates a separate backup file for each boot case (eg develop.tgz) and stores them in /tce. Specify only the file name, not the extension.
====Method 2: Having multiple locations for backup files====
==Example: GRUB stanzas==
<code>title jack's development stuff
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1 restore=sda1/tce/development
initrd /boot/tinycore.gz</code> 
<code>title jack's play stuff
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1 restore=sda1/tce/play
initrd /boot/tinycore.gz</code> 
<code>title jill's stuff
root (hd0,0)
kernel /boot/bzImage quiet tce=sda1 restore=sda1/tce/jill
initrd /boot/tinycore.gz</code>
<code>title kids
root (hd0,0)
kernel /boot/bzImage quiet tce=sda2 restore=sda2/tce/kids
initrd /boot/tinycore.gz</code>
This method creates a mydata.tgz file in separate locations for each boot case. The locations must be created prior to specifying them.
=====Selective restoring of extensions======

All your extensions don't have to be loaded each time you boot, which could be very time-consuming, especially if you have a lot of extensions stored in ''/tce/optional''. Instead, you can choose to restore non-essential ones only when you actually want to run them. So, essential extensions such as drivers and so on, are loaded at boot time, while non-essential ones are loaded on demand. These two different loading settings are called "''OnBoot''" and "''OnDemand''". 

For example, any extensions to do with getting your desktop up and running, and connecting you with the internet, would be loaded on boot. When downloading these extensions with AppBrowser for the first time, you can select the OnBoot method in the dropdown box. They will then be automatically loaded during the next boot. 

For other apps such as a calculator or a browser which are non-essential for the desktop operation, you can elect to have them either as ''OnBoot'' (//which will cause an increase in booting time//) or as ''OnDemand'' (//which will cause a small delay the very first time they are invoked in each session//).

For extensions which are very seldomly used, you can use the "''Download + load''" setting in AppBrowser which will download and load the app, but will not include it in either of the OnBoot or OnDemand lists. You can also load these ones later again by using the "''Local''" button in AppBrowser, which then looks in ''/tce'' for all your downloaded extensions.

You can play around with which extensions to load where in the AppsAudit utility. If you are unsure if a particular app is essential or not, just put it in ''OnBoot'' - you can change later. (//The ''OnBoot'' and ''OnDemand'' lists are also to be found in ''/tce''. They are maintained by AppsAudit.//) 

If you are running text mode only, and want to change an extension to ondemand, remove it from onboot.lst then run "ondemand appname". This will add a script to the ondemand directory (in your path) that will mount the tcz when you need them.  To change it back to onboot, add it back to onboot.lst