<?xml version="1.0"?>
<article id="index" lang="en"><articleinfo><title>Linux Complete Backup and Recovery HOWTO</title><date>   2002 January 20
  </date><author><firstname>Charles</firstname><surname>Curley</surname><affiliation><address format="linespecific">           <email><ulink url="ccurley at trib dot com">ccurley at trib dot com</ulink></email>
        </address></affiliation></author><revhistory><revision><revnumber>1.2</revnumber><date>2003-02-12</date><authorinitials>c^2</authorinitials><revremark>Added Red Hat 8.0 notes, support for FAT32, split the first stage restore scripts, and other minor changes. Notes on <link linkend="amanda">Amanda</link>.</revremark></revision><revision><revnumber>1.1</revnumber><date>2002-09-10</date><authorinitials>c^2</authorinitials><revremark>New code to handle ext3 partitions in <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link>, and a note on <link linkend="initrd"><filename moreinfo="none">initrd</filename></link>.</revremark></revision><revision><revnumber>1.0</revnumber><date>2002-07-24</date><authorinitials>c^2</authorinitials><revremark>We now use bz2 compression in the first stage, have the run time option to check for bad blocks, and have a script that runs the entire first stage.</revremark></revision><revision><revnumber>0.05</revnumber><date>2002-07-04</date><authorinitials>c^2</authorinitials><revremark>Added another variation, other minor fixes.</revremark></revision><revision><revnumber>0.04</revnumber><date>2002-05-09</date><authorinitials>c^2</authorinitials><revremark>Added Theme ent Variations section, a variation; also some minor reorganization.</revremark></revision><revision><revnumber>0.03</revnumber><date>2002-04-09</date><authorinitials>c^2</authorinitials><revremark>Added the Beeblebrox Project to resources.</revremark></revision><revision><revnumber>0.02</revnumber><date>2002-01-27</date><authorinitials>c^2</authorinitials><revremark>Added Mondo to resources</revremark></revision><revision><revnumber>0.01</revnumber><date>2001-10-25</date><authorinitials>c^2</authorinitials><revremark>Initial version for LDP release</revremark></revision></revhistory><abstract><para>Imagine your disk drive has just become a very expensive hockey puck. Imagine you have had a fire, and your computer case now looks like something Salvador Dalent would like to paint. Now what?</para><para>Total restore, sometimes called bare metal recovery, is the process of rebuilding a computer after a catastrophic failure. In order to make a total restoration, you must have complete backups, not only of your file system, but of partition information and other data. This HOWTO is a step-by-step tutorial on how to back up a Linux computer so as to be able to make a bare metal recovery, and how to make that bare metal recovery. It includes some related scripts.</para></abstract></articleinfo><sect1 id="intro"><title>Introduction</title><para>The normal bare metal restoration process is: install the operating system from the product disks. Install the backup software, so you can restore your data. Restore your data. Then you get to restore functionality by verifying your configuration files, permissions, etc.</para><para>   The process and scripts explained in this HOWTO will save re-installing the operating system. The process explained here will restore only files that were backed up from the production computer. Your configuration will be intact when you restore the system, which should save you hours of verifying configurations and data.</para><sect2 id="copyright"><title>Copyright Information</title><para>Copyright ent 2001, 2002 Charles Curley and distributed under the terms of the GNU Free Documentation License (GFDL) license, stated below. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled <link linkend="appendix1gfdl"><quote>GNU Free Documentation License</quote></link>. </para><para>If you have any questions, please contact <email>linux-howto at metalab.unc.edu</email>. </para></sect2><sect2 id="disclaimers"><title>Disclaimers</title><para> No liability for the contents of this documents can be accepted by the author, the <ulink url="http://www.tldp.org/">Linux Documentation Project</ulink> or anyone else. Use the concepts, examples and other content at your own risk. There may be errors and inaccuracies that may be damaging to your system. Proceed with caution, and although errors are unlikely, the author(s) take no responsibility for them. </para><para> All copyrights are held by their by their respective owners, unless specifically noted otherwise.  Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. </para><para>    Naming of particular products or brands should not be seen 
    as endorsements.
   </para><para>    You are strongly recommended to take a backup of your system 
    before major installation and backups at regular intervals.
   </para><para>In addition, you are strongly recommended to use a sacrificial experimental computer when mucking with the material, espcially the scripts, in this HOWTO.</para></sect2><sect2 id="newversions"><title>New Versions</title><para>You can find this document at its <ulink url="http://w3.trib.com/~ccurley/Linux-Complete-Backup-and-Recovery-HOWTO.html">home page</ulink> or at the <ulink url="http://www.tldp.org/">Linux Documentation Project</ulink> homepage in many formats. Please comment to <email>ccurley at trib dot com</email></para><itemizedlist><listitem><para>      <ulink url="http://w3.trib.com/~ccurley/Linux-Complete-Backup-and-Recovery-HOWTO/Linux-Complete-Backup-and-Recovery-HOWTO.chunky.html.tar.bz2">bzip2 compressed chunky (lots of small pages. Faster reading.) HTML</ulink>.
     </para></listitem><listitem><para>      <ulink url="http://w3.trib.com/~ccurley/Linux-Complete-Backup-and-Recovery-HOWTO/Linux-Complete-Backup-and-Recovery-HOWTO.smooth.html.tar.bz2">bzip2 compressed smooth (one monster page -- no chunks. Easier to search.) HTML</ulink>.
     </para></listitem><listitem><para>       <ulink url="http://w3.trib.com/~ccurley/Linux-Complete-Backup-and-Recovery-HOWTO/Linux-Complete-Backup-and-Recovery-HOWTO.ps.bz2">bzip2 compressed postscript (US letter format)</ulink>.
      </para></listitem><listitem><para>       <ulink url="http://w3.trib.com/~ccurley/Linux-Complete-Backup-and-Recovery-HOWTO/Linux-Complete-Backup-and-Recovery-HOWTO.pdf.bz2">bzip2 compressed PDF (US letter format)</ulink>.
      </para></listitem><listitem><para>       <ulink url="http://w3.trib.com/~ccurley/Linux-Complete-Backup-and-Recovery-HOWTO/Linux-Complete-Backup-and-Recovery-HOWTO.txt.bz2">bzip2 compressed raw ASCII text</ulink>.
      </para></listitem><listitem><para>Use the <ulink url="http://w3.trib.com/~ccurley/Linux-Complete-Backup-and-Recovery-HOWTO/Linux-Complete-Backup-and-Recovery-HOWTO.tar.bz2">source</ulink>, Luke.</para></listitem></itemizedlist></sect2><sect2 id="credits"><title>Credits</title><para>This document is derived from two articles originally published in
<ulink url="http://www.linuxjournal.com/"><citetitle pubwork="journal">Linux Journal</citetitle></ulink>. My thanks to
<citetitle pubwork="journal">Linux Journal</citetitle> for reverting the rights to those articles, thereby helping make this HOWTO possible.
   </para><para>Thanks to Joy Y Goodreau for excellent HOWTO editing.</para></sect2><sect2 id="feedback"><title>Feedback</title><para>    Feedback is most certainly welcome for this document. Without your corrections, suggestions and other input, this document wouldn't exist. Please send your additions, comments and criticisms to me at: <email>ccurley at trib.com</email>.</para></sect2><sect2 id="translations"><title>Translations</title><para>    Not everyone speaks English. Volunteers are welcome.
   </para></sect2></sect1><sect1 id="overview"><title>Overview</title><para>   The process shown below is not easy, and can be hazardous to your data. Practice it before you need it! Do as I did, and <emphasis>practice on a sacrificial computer</emphasis>!
  </para><para>   The target computer for this HOWTO is a Pentium computer with a <ulink url="http://www.redhat.com">Red Hat</ulink> 7.1 Linux server or workstation installation on one IDE hard drive. The target computer does not have vast amounts of data because the computer was set up as a <quote>sacrificial</quote> test bed. That is, I did not want to test this process with a production computer and production data. Also, I did a fresh installation before I started the testing so that I could always re-install if I needed to revert to a known configuration.
  </para><note><title>NOTE</title><para>The sample commands will show, in most cases, what I had to type to recover the target system. You may have to use similar commands, but with different parameters. It is up to you to be sure you duplicate your setup, and not the test computer's setup.</para></note><para>   The basic procedure is set out in W. Curtis Preston, <ulink url="http://www.oreilly.com/catalog/unixbr/"><citetitle pubwork="book">Unix Backup ent Recovery</citetitle></ulink>, O'Reilly ent Associates, 1999, which I have favorably reviewed in <ulink url="http://www2.linuxjournal.com/lj-issues/issue78/3839.html"><citetitle pubwork="journal">Linux Journal</citetitle></ulink>. However, the book is a bit thin on specific, real-time questions. For example, exactly which files do you back up? What metadata do you need to preserve, and how?
  </para><para>   Before beginning the process set forth in this HOWTO you will need to back up your system with a typical backup tool such as Amanda, <trademark class="trade">BRU</trademark>, tar, <trademark class="registered">Arkeia</trademark> or cpio. The question, then, is how to get from toasted hardware to the point where you can run the restoration tool that will restore your data.
  </para><para>   Users of Red Hat Package Manager (RPM) based Linux distributions should also save RPM metadata as part of their normal backups. Something like:
  </para><programlisting format="linespecific">bash# <command moreinfo="none">rpm -Va ent /etc/rpmVa.txt</command></programlisting><para>   in your backup script will give you a basis for comparison after a bare metal restoration.
  </para><para>   To get to this point, you need to have:
  </para><itemizedlist><listitem><para>   Your hardware up and running again, with replacement components as needed. The BIOS should be correctly configured, including time and date, and hard drive parameters. At the moment, there is no provision for using a different hard drive.
   </para></listitem><listitem><para>   A parallel port <ulink url="http://www.iomega.com/"><trademark class="registered">Iomega</trademark></ulink> <ulink url="http://www.iomega.com/zip/products/par100_250.html"><trademark class="registered">ZIP</trademark> drive</ulink> or equivalent. You will need at least 30 MB of space.</para></listitem><listitem><para>   Your backup media.
   </para></listitem><listitem><para>   A minimal Linux system that will allow you to run the restoration software.
   </para></listitem></itemizedlist><para>   To get there, you need at least two stages of backup, and possibly three. Exactly what you back up and in which stage you back it up is determined by your restoration process. For example, if you are restoring a tape server, you may not need networking during the restoration process. So only back up networking in your regular backups.
  </para><para>   You will restore in stages as well. In stage one, we build partitions, file systems, etc. and restore a minimal file system from the ZIP disk. The goal of stage one is to be able to boot to a running computer with a network connection, tape drives, restoration software, or whatever we need for stage two.
  </para><para>   The second stage, if it is necessary, consists of restoring backup software and any relevant databases. For example, suppose you use Arkeia and you are building a bare metal recovery ZIP disk for your backup server. Arkeia keeps a huge database on the server's hard drives. You can recover the database from the tapes, if you want. Instead, why not tar and gzip the whole arkeia directory (at /usr/knox), and save that to another computer over nfs or ssh? Stage one, as we have defined it below, does not include X, so you will have some experimenting to do if you wish to back up X as well as your backup program. Some restore programs require X.
  </para><para>   Of course, if you are using some other backup program, you may have some detective work to do to. You will have to find out the directories and files it needs to run. If you use tar, gzip, cpio, mt or dd for your backup and recovery tools, they will be saved to and restored from our ZIP disk as part of the stage one process describe below.
  </para><para>   The last stage is a total restoration from tape or other media. After you have done that last stage, you should be able to boot to a fully restored and operational system.
  </para><sect2 id="limitations"><title>Limitations</title><para>This HOWTO is restricted to making a minimal backup such that, having then restored that backup to new hardware (<quote>bare metal</quote>), you can then use your regular backups to restore a completely working system. This HOWTO does not deal with your regular backups at all.</para><para>Even within that narrow brief, this HOWTO is not exhaustive. You still have some research, script editing, and testing to do.</para><para>The scripts here restore the partition data exactly as found on the source hard drive. This is nice if you are restoring on an identical computer or at least and identical hard drive, but that is often not the case. For now, there are two remedies (which will make more sense after you've read the rest of the HOWTO):</para><itemizedlist><listitem><para>Edit the partition table input file. I've done that a few times. You can also do this to add new partitions or delete existing ones (but edit the scripts that use the partition table input file as well).</para></listitem><listitem><para>Hand build a new partition table and go from there. That is one reason why <link linkend="restore.metadata"><filename moreinfo="none">restore.metadata</filename></link> does not call the hard drive rebuilding script. Use the <link linkend="mount.dev.hda">rebuilding script</link>.</para></listitem></itemizedlist><para>The scripts shown here only handle ext2fs, FAT12, FAT16 and FAT32. Until some eager volunteer supplies code for doing so in these scripts, you will need other tools for backing up and restoring file systems we haven't covered. <ulink url="http://www.partimage.org/">Partition Image</ulink> looks like a useful candidate here.</para></sect2></sect1><sect1 id="preparation"><title>Preparation</title><note><title>WARNING</title><para>   Do your normal backups on their regular schedule. This HOWTO is useless if you don't do that.
  </para></note><para>   Build yourself a rescue disk. I use <ulink url="http://www.toms.net/rb">tomsrtbt</ulink>. It is well documented and packs a lot of useful tools onto one floppy diskette. There is an active list for it, and the few questions I've had were quickly and accurately answered. I like that in a product my shop may depend on one day.
  </para><para>   Next, figure out how to do the operating system backup you will need so that you can restore your normal backup. I followed Preston's advice and used an Iomega parallel port ZIP drive. The drives get approximately 90 MB of useful storage to a disk. I need about 85 MB to back up my desktop, so a 100MB ZIP drive may be pushing your luck.
  </para><sect2 id="installingzipdrive"><title>Installing the ZIP Drive</title><para>    Installing the ZIP drive is covered in the <ulink url="http://www.tldp.org/HOWTO/mini/ZIP-Drive.html">ZIP Drive HOWTO</ulink>, available at <ulink url="http://www.tldp.org/">the Linux Documentation Project</ulink> and at its home page, <ulink url="http://www.njtcom.com/dansie/zip-drive.html">http://www.njtcom.com/dansie/zip-drive.html</ulink>.
   </para></sect2></sect1><sect1 id="creatingthestage1backup"><title>Creating the Stage 1 Back Up</title><para>   Having made your production backups, you need to preserve your partition information so that you can rebuild your partitions.
  </para><para>   The script <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link> scans a hard drive for partition information, and saves it in three files. The first is an executable script, called <link linkend="make.dev.hda"><filename moreinfo="none">make.dev.x</filename></link> (where <quote>x</quote> is the name of the device file, e.g. hda). Second is <link linkend="mount.dev.hda"><filename moreinfo="none">mount.dev.x</filename></link>, which creates mount points and mounts the newly created partitions on them. The last, <link linkend="dev.hda"><filename moreinfo="none">dev.x</filename></link>, is the commands necessary for <command moreinfo="none">fdisk</command> to build the partitions. You specify which hard drive you want to build scripts for (and thus the file names) by naming the associated device file as the argument to <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link>. For example, on a typical IDE system,
  </para><programlisting format="linespecific">bash# <command moreinfo="none">make.fdisk /dev/hda</command></programlisting><para>   spits out the scripts <link linkend="make.dev.hda"><filename moreinfo="none">make.dev.hda</filename></link>, <link linkend="mount.dev.hda"><filename moreinfo="none">mount.dev.hda</filename></link> and the input file for <command moreinfo="none">fdisk</command>, <link linkend="dev.hda"><filename moreinfo="none">dev.hda</filename></link>.</para><para>In addition, if <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link> encounters a FAT partition, it preserves the partition's boot sector in a file named <filename moreinfo="none">dev.xy</filename>, where x is the drive's device name (e.g. sdc, hda) and y is the partition number. The boot sector is the first sector, 512 bytes, of the partition. This sector is restored at the same time the partitions are rebuilt, in the script <filename moreinfo="none">make.dev.hda</filename></para><para>   Fortunately, the price of hard drives is plummeting almost as fast as the public's trust in politicians after an election. So it is good that the output files are text, and allow hand editing. Right now, that's the only way to rebuild on a larger replacement drive. (See the <link linkend="todo">To Do list</link>.)
  </para><para>   Other metadata are preserved in the script <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link>. The script saves the partition information in the file <filename moreinfo="none">fdisk.hda</filename> in the root of the ZIP disk. It is a good idea to print this file and your <filename moreinfo="none">/etc/fstab</filename> so that you have hard copy should you ever have to restore the partition data manually. You can save a tree by toggling between two virtual consoles, running <command moreinfo="none">fdisk</command> in one and catting <filename moreinfo="none">/etc/fstab</filename> or <filename moreinfo="none">/fdisk.hda</filename> as needed. However, doing so is error prone.
  </para><para>   You will also want to preserve files relevant to your restoration method. For example, if you use nfs to save your data, you will need to preserve hosts.allow, hosts.deny, exports, etc. Also, if you are using any network-backed restoration process, such as Amanda or Quick Restore, you will need to preserve networking files like HOSTNAME, hosts, etc. and the relevant software tree.
  </para><para>   The simplest way to handle these and similar questions is to preserve the entire etc directory.
  </para><para>   There is no way a 100 MB ZIP drive is going to hold a server installation of a modern distribution of Linux. We have to be much more selective than simply preserving the whole kazoo. What files do we need?
  </para><itemizedlist><listitem><para>   The boot directory.
  </para></listitem><listitem><para>   The /etc directory and subdirectories.
  </para></listitem><listitem><para>   Directories needed at boot time.
  </para></listitem><listitem><para>   Device files in /dev.
  </para></listitem></itemizedlist><para>   To determine the directories needed at boot, we look at the boot initialization file <filename moreinfo="none">/etc/rc.sysinit</filename>. It sets its own path like so:
  </para><programlisting format="linespecific">PATH=/bin:/sbin:/usr/bin:/usr/sbin
export PATH</programlisting><para>   Trial and error indicated that we needed some other directories as well, such as /dev. In Linux, you can't do much without device files.
  </para><para>   In reading the script <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link>, note that we aren't necessarily saving files that are called with absolute paths.
  </para><para>   We may require several iterations of back up, test the bare metal restore, re-install from CD and try again, before we have a working backup script. While I worked on this HOWTO, I made five such iterations before I had a successful restoration. That is one reason why it is essential to use scripts whenever possible. Test thoroughly!
  </para><para>One thing you can do on an RPM based system is use the <command moreinfo="none">rpm</command> program to determine which files are where. For example, to get a complete list of the files used by the openssh package, run:</para><programlisting format="linespecific">bash# <command moreinfo="none">rpm -ql openssh</command></programlisting><para>There are somethings you don't need. like the man pages. You can inspect each one and decide whether to back it up or not.</para><sect2 id="themeandvariations"><title>Theme And Variations</title><sect3><title>No ZIP drive</title><para>This backup process requires you to have the ZIP disk drive present at each backup. You could, given a large enough hard drive, create the ZIP disk's contents in a directory, and back that up over the net. Then you only need to build a ZIP disk (with <command moreinfo="none">cp -rp</command>) on the backup server when you need to restore.</para><para>The backup process will be faster, but you should check that the resulting directory will fit on your ZIP disk (with <command moreinfo="none">du -hs $target.zip</command>)! You will have to edit the definition of the variable <varname>zip</varname> in <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link>.</para><para>My laptop has problems running both a network card and a ZIP drive, so this is the process I use to back it up.</para><para>Alternatively, you could build several ZIP disks' worth of backup on the hard drive, and feed them to the system on restore.</para></sect3><sect3><title>Multiple ZIP disks</title><para>By splitting up the two first stage scripts, <link linkend="restore.metadata"><filename moreinfo="none">restore.metadata</filename></link> and <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link>, you could spread the first stage metadata across multiple ZIP disks.</para></sect3><sect3><title>Excluding From First Stage Saving</title><para>There are time when you need to squeeze a few megabytes from the first stage data, expecially when you are pushing the limit of your ZIP disk. The function <command moreinfo="none">crunch</command> in the script <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link> takes multiple parameters to feed to <command moreinfo="none">tar</command>. It can also take the <command moreinfo="none">--exclude</command> parameter. So, for example, you can exclude <command moreinfo="none">emacs</command> and <command moreinfo="none">gs</command> like so:</para><programlisting format="linespecific">crunch etc etc --exclude etc/samba --exclude X11</programlisting><para>Why those two? Because they're hard drive space hogs and we don't need them at boot time.</para><para>How to find good candidates for exclusion? List the target directories with <command moreinfo="none">ls -alSr</command> for individual files, and <command moreinfo="none">du | sort -n</command> for directories.</para></sect3><sect3 id="initrd"><title>Initrd</title><para>If your system uses an initial RAM disk, or initrd, to boot, make sure that <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link> creates the directory <filename moreinfo="none">/initrd</filename>. The easiest way to do this is to ensure that it is included in the list of directories used in the directory creating loop toward the end.</para><para>Your system will probably use an initrd if it boots from a SCSI drive or has root on an ext3fs partition. Check <filename moreinfo="none">/etc/lilo.conf</filename> to see if it calls for one.</para></sect3></sect2></sect1><sect1 id="firststagerestore"><title>First Stage Restore</title><sect2 id="bootingtomsrtbt"><title>Booting tomsrtbt</title><para>   The first thing to do before starting the restoration process is to verify that the hardware time is set correctly. Use the BIOS setup for this. How close to exact you have to set the time depends on your applications. For restoration, within a few minutes of exact time should be accurate enough. This will allow time-critical events to pick up where they left off when you finally launch the restored system.
  </para><para>   Before booting <ulink url="http://www.toms.net/rb">tomsrtbt</ulink>, make sure your ZIP drive is placed on a parallel port, either /dev/lp0 or /dev/lp1. The start-up software will load the parallel port ZIP drive driver for you.
  </para><para>   The next step is to set the video mode. I usually like to see as much on the screen as I can. When the option to select a video mode comes, I use mode 6, 80 columns by 60 lines. Your hardware may or may not be able to handle high resolutions like that, so experiment with it.
  </para></sect2><sect2 id="restoration"><title>Restoration</title><para>   Once <ulink url="http://www.toms.net/rb">tomsrtbt</ulink> has booted and you have a console, mount the ZIP drive. It is probably a good idea to mount it read only:
  </para><programlisting format="linespecific"># <command moreinfo="none">mount /dev/sda1 /mnt -o ro</command></programlisting><para>   Check to be sure it is there:
  </para><programlisting format="linespecific"># <command moreinfo="none">ls -l /mnt</command></programlisting><para>At this point, you can run the restoration automatically or manually. Use the automated restore if you don't need to make any changes as you go along.</para><para>One consideration here is whether you have multiple hard drives. If your Linux installation mounts partitions on multiple hard drives, you must mount the root partition first. This is to ensure that mount point directories are created on the partition where they belong. The script <filename moreinfo="none">first.stage</filename> will run the scripts to mount the drives in the order in which they are created. If you have created them (in the script <filename moreinfo="none">save.metadata</filename>) in the order in which they cascade from root, the mounting process should work just fine.</para><para>If you have multiple hard drives, and they cross-mount, you are on your own. Either combine and edit the scripts to mount them in the correct order, or do it manually.</para><sect3><title>Automated</title><para>To run the first stage restore completely automated, enter the command:</para><programlisting format="linespecific"># <command moreinfo="none">/mnt/root.bin/first.stage</command></programlisting><para>If you want to check for back blocks, add the <command moreinfo="none">-c</command> option.</para></sect3><sect3><title>Manually</title><para>   To run the process manually, change to the directory where the scripts are on the ZIP drive.
  </para><programlisting format="linespecific"># <command moreinfo="none">cd /mnt/root.bin</command></programlisting><para>   Now run the script(s) that will restore the partition information and create file systems. You may run them in any order. e.g.:
  </para><programlisting format="linespecific"># <command moreinfo="none">./make.dev.hda</command></programlisting><para>If you want to check for back blocks, add the <command moreinfo="none">-c</command> option.</para><para>   This script will:
  </para><itemizedlist><listitem><para>   Clean out the first 1024 bytes of the hard drive, killing off any existing partition table and master boot record (MBR).
   </para></listitem><listitem><para>   Recreate the partitions from the information gathered when you ran <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link>.
   </para></listitem><listitem><para>   Make ext2 and ext3 file system partitions and Linux swap partitions as appropriate. If you provide the <command moreinfo="none">-c</command> option to the script, it will also check for bad blocks.
   </para></listitem><listitem><para>   Make some types of FAT partitions.
   </para></listitem></itemizedlist><note><title>NOTE</title><para>If you have other operating systems to restore, now is a good time to do so. When you've done that, reboot to <ulink url="http://www.toms.net/rb">tomsrtbt</ulink> and continue restoring Linux.</para></note><para>Now run the script(s) that create mount points and mount the partitions to them.</para><programlisting format="linespecific"># <command moreinfo="none">./mount.dev.hda</command></programlisting><para>   Once you have created all your directories and mounted partitions to them, you can run the script <link linkend="restore.metadata"><filename moreinfo="none">restore.metadata</filename></link>. This will restore the contents of the ZIP drive to the hard drive.
  </para><para>   You should see a directory of the ZIP disk's root directory, then a list of the archive files as they are restored. Tar on <ulink url="http://www.toms.net/rb">tomsrtbt</ulink> will tell you that tar's block size is 20, and that's fine. You can ignore it. Be sure that lilo prints out its results:
  </para><screen format="linespecific">Added linux *</screen><para>   That will be followed by the output from a <quote><command moreinfo="none">df -m</command></quote> command.
  </para></sect3><sect3><title>Finishing Touches</title><para>   If you normally boot directly to X, you could have some problems. To be safe, change your boot run level temporarily. In <filename moreinfo="none">/target/etc/inittab</filename>, find the line that looks like this:
  </para><programlisting format="linespecific">id:5:initdefault:</programlisting><para>   and change it to this:
  </para><programlisting format="linespecific">id:3:initdefault:</programlisting><para>   Now, you can gracefully reboot. Remove the <ulink url="http://www.toms.net/rb">tomsrtbt</ulink> floppy from your floppy drive if you haven't already done so, and give the computer the three fingered salute, or its equivalent:</para><programlisting format="linespecific">reboot</programlisting><para>The computer will shut down and reboot.</para></sect3></sect2></sect1><sect1 id="secondstagerestoration"><title>Second Stage Restoration</title><para>   As the computer reboots, go back to the BIOS and verify that the clock is more or less correct.
  </para><para>   Once you have verified the clock is correct, exit the BIOS and reboot to the hard drive. You can simply let the computer boot in its normal sequence. You will see a lot of error messages, mostly along the lines of <quote>I can't find blah! Waahhh!</quote> If you have done your homework correctly up until now, those error messages won't matter. You don't need linuxconf or apache to do what you need to do.
  </para><note><title>NOTE</title><para>As an alternative, you can boot to single user mode (at the lilo prompt, enter <command moreinfo="none">linux single</command>), but you will have to configure your network manually and fire up sshd or whatever daemons you need to restore your system. How you do those things is very system specific.</para></note><para>   You should be able to log into a root console (no X -- no users, sorry). You should now be able to use the network, for example to nfs mount the backup of your system.
  </para><para>   If you did the two stage backup I suggested for Arkeia, you can now restore Arkeia's database and executables. You should be able to run </para><programlisting format="linespecific">/etc/rc.d/init.d/arkeia start</programlisting><para> and start the server. If you have the GUI installed on another computer with X installed, you should now be able to log in to Arkeia on your tape server, and prepare your restoration.
  </para><note><title>NOTE</title><para>When you restore, read the documentation for your restoration programs carefully. For example, tar does not normally restore certain characteristics of files, like suid bits. File permissions are set by the user's umask. To restore your files exactly as you saved them, use tar's p option. Similarly, make sure your restoration software will restore everything exactly as you saved it.
    </para></note><para>   To restore the test computer:
  </para><programlisting format="linespecific">bash# <command moreinfo="none">restore.all</command></programlisting><para>   If you used tar for your backup and restoration, and used the -k (keep old files, don't overwrite) option, you will see a lot of this:
  </para><screen format="linespecific">tar: usr/sbin/rpcinfo: Could not create file: File exists
tar: usr/sbin/zdump: Could not create file: File exists
tar: usr/sbin/zic: Could not create file: File exists
tar: usr/sbin/ab: Could not create file: File exists</screen><para>   This is normal, as tar is refusing to overwrite files you restored during the first stage of restoration.
  </para><para>   Then reboot. On the way down, you will see a lot of error messages, such as <quote>no such pid.</quote> This is a normal part of the process. The shutdown code is using the pid files from daemons that were running when the backup was made to shut down daemons that were not started on the last boot. Of course there's no such pid.
  </para><para>   Your system should come up normally, with a lot fewer errors than it had before, ideally no errors. The acid test of how well your restore works on an RPM based system is to verify all packages:
  </para><programlisting format="linespecific">bash# <command moreinfo="none">rpm -Va</command></programlisting><para>   Some files, such as configuration and log files, will have changed in the normal course of things, and you should be able to mentally filter those out of the report. You can redirect the output to a file, and diff it against the one that was made at backup time (/etc/rpmVa.txt), thereby speeding up this step considerably. Emacs users should check out its diff facilities.
  </para><para>   Now you should be up and running. It is time to test your applications, especially those that run as daemons. The more sophisticated the application, the more testing you may need to do. If you have remote users, disable them from using the system, or make it <quote>read only</quote> while you test it. This is especially important for databases, to prevent making any corruption or data loss worse than it already might be.
  </para><para>   If you normally boot to X, and disabled it above, test X before you re-enable it. Re-enable it by changing that one line in /etc/inittab back to:
  </para><programlisting format="linespecific">id:5:initdefault:</programlisting><para>   You should now be ready for rock and roll -- and some aspirin and a couch.
  </para></sect1><sect1 id="distributionspecificnotes"><title>Distribution Specific Notes</title><para>  Below are distribution notes from past experiences. If you have additional notes that you would like to add for other distributions, please forward them to me. 
  </para><sect2 id="redhat80"><title>Red Hat 8.0</title><para>Red Hat 8.0 requires changes only if you log in via ssh to your computer after the first stage restore. If, say, you perform the second state restore over ssh. If so, make the following changes:</para><itemizedlist><listitem><para>In the file <filename moreinfo="none">save.metadata</filename>, add the kerberos libraries to the first stage backup.</para><programlisting format="linespecific">crunch  kerberos usr/kerberos/lib/</programlisting></listitem><listitem><para>In the file <filename moreinfo="none">restore.metadata</filename>, there is a loop that builds several directories. First, add these two directory names to the list: <filename moreinfo="none">/var/empty/sshd</filename> and <filename moreinfo="none">/var/lock/subsys</filename>. As Red Hat 8.0 defaults to ext3fs, it requires an inital RAM disk at boot time. So make sure <filename moreinfo="none">initrd</filename> is in the list. Then, if it isn't already there, add the <command moreinfo="none">-p</command> switch to the makdir command.</para><para>The directory <filename moreinfo="none">/var/lock/subsys</filename> is owned by group lock, so change its owner.</para><programlisting format="linespecific">chroot $target /bin/chown root:lock /var/lock</programlisting><para>Finally, <filename moreinfo="none">usr/lib/libcrypto*</filename> has gone away, so you can remove that from the line that crunches <filename moreinfo="none">usr/lib</filename>. </para></listitem></itemizedlist></sect2><sect2 id="redhat71"><title>Red Hat 7.1</title><para>    This distribution is the one I used originally on my test computer. I have had no problems with it.
   </para></sect2><sect2 id="redhat70"><title>Red Hat 7.0</title><para>    This version seems to require libcrack (in /usr/lib) and its attendant files in order to authenticate users. So in <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link>, add to the line that saves /usr/lib the following: /usr/lib/*crack* and enable that line.
   </para></sect2></sect1><sect1 id="applicationspecificnotes"><title>Application Specific Notes</title><para>   I have listed below notes about backing up particular applications. 
  </para><sect2 id="squid"><title>Squid</title><para>Squid is a http proxy and cache. As such it keeps a lot of temporary data on the hard drive. There is no point in backing that up. Insert <quote>--exclude /var/spool/squid</quote> into the appropriate tar command in your second stage backup script. Then, get squid to rebuild its directory structure for you. Tack onto the tail end of the second stage restore script a command for squid to initialize itself. Here is how I did it over ssh in <link linkend="restore.tester"><filename moreinfo="none">restore.tester</filename></link>:</para><programlisting format="linespecific">ssh $target "mkdir /var/spool/squid ; chown squid:squid /var/spool/squid;\
      /usr/sbin/squid -z;touch /var/spool/squid/.OPB_NOBACKUP"</programlisting><para>The last command creates a file of length 0 called .OPB_NOBACKUP. This is for the benefit of <link linkend="arkeia">Arkeia</link>, and tells Arkeia not to back up below this directory</para></sect2><sect2 id="arkeia"><title>Arkeia</title><para>These notes are based on testing with Arkeia 4.2.</para><para><ulink url="http://www.arkeia.com/">Arkeia</ulink> is a backup and restore program that runs on a wide variety of platforms. You can use Arkeia as part of a bare metal restoration scheme, but there are two caveats.</para><para>The first is probably the most problematic, as absent any more elegant solution you have to hand select the directories to restore in the navigator at restoration time. The reason is that, apparently, Arkeia has no mechanism for not restoring files already present on the disk, nothing anlogous to <command moreinfo="none">tar</command>'s -p option. If you simply allow a full restore, the restore will crash as Arkeia over-writes a library which is in use at restore time, e.g. lib/libc-2.1.1.so. Hand selection of directories to restore is at best dicy, so I recommend against it.</para><para>The second caveat is that you have to back up the Arkeia data dictionary and/or programs. To do that, modify the <filename moreinfo="none">save.metatdata</filename> script by adding Arkeia to the list of directories to save:</para><programlisting format="linespecific"># arkeia specific:
tar cf - usr/knox | gzip -c ent $zip/arkeia.tar.gz</programlisting><para>You <emphasis>must</emphasis> back up the data dictionary this way because Arkeia does not back up the data dictionary. This is one of my complaints about Arkeia, and I solve it on my own computer by saving the data dictionary to tape with <ulink url="http://www.estinc.com/">The TOLIS Group's BRU</ulink>.</para><para>The data dictionary will be restored in the script <filename moreinfo="none">restore.metadata</filename> automatically.</para></sect2><sect2 id="amanda"><title>Amanda</title><para><ulink url="http://www.amanda.org/">Amanda</ulink> (The Advanced Maryland Automatic Network Disk Archiver) works quite well with this set of scripts. Use the normal Amanda back-up process, and build your first stage data as usual. Amanda stores the data on tape in GNU tar or cpio format, and you can recover from individual files to entire backup images. The nice thing about recovering entire images is that you can then use variants on the scripts in this HOWTO to restore from the images, or direct from tape. I was able to restore my test machine with the directions from W. Curtis Preston's <ulink url="http://www.oreilly.com/catalog/unixbr/"><citetitle pubwork="book">Unix Backup ent Recovery</citetitle></ulink>. For more information on it, see the <link linkend="resources">Resources</link>. The Amanda chapter from the book is <ulink url="http://www.backupcentral.com/amanda.html">on line</ulink>.</para><para>I made two changes to the script <link linkend="restore.tester"><filename moreinfo="none">restore.tester</filename></link>. First, I changed it to accept a file name as an argument. Then, since Amanda's <command moreinfo="none">amrestore</command> decompresses the data as it restores it, I rewrote it to cat the file into the pipe instead of decompressing it.</para><para>The resulting line looks like this:</para><programlisting format="linespecific">cat $file | ssh $target "umask 000 ; cd / ; tar -xpkf - "</programlisting><para>where <command moreinfo="none">$file</command> is the script's argument, the image recovered from the tape by <command moreinfo="none">amrestore</command>.</para><para>Since the command line arguments to <command moreinfo="none">tar</command> prohibit over-writing, restore from images in the <emphasis>reverse</emphasis> of the order in which they were made. Restore most recent first.</para></sect2></sect1><sect1 id="someadvicefordisasterrecovery"><title>Some Advice for Disaster Recovery</title><para>   You should take your ZIP disk for each computer and the printouts you made, and place them in a secure location in your shop. You should store copies of these in your off-site backup storage location. The major purpose of off-site backup storage is to enable disaster recovery, and restoring each host onto replacement hardware is a part of disaster recovery.
  </para><para>   You should also have several <ulink url="http://www.toms.net/rb">tomsrtbt</ulink> floppies and possibly some ZIP drives in your off-site storage as well. Also, have copies of the <ulink url="http://www.toms.net/rb">tomsrtbt</ulink> distribution on several of your computers so that they back each other up.
  </para><para>   You should probably have copies of this HOWTO, with your site-specific annotations on it, with your backups and in your off-site backup storage.
  </para></sect1><sect1 id="whatnow"><title>What Now?</title><para>   This HOWTO results from experiments on one computer. No doubt you will find some directories or files you need to back up in your first stage backup. I have not dealt with saving and restoring X on the first stage, nor have I touched at all on processors other than Intel.
  </para><para>   I would appreciate your feedback as you test and improve these scripts on your own computers. I also encourage vendors of backup software to document how to do a minimal backup of their products. I'd like to see the whole Linux community sleep just a little better at night.
  </para><sect2 id="todo"><title>To Do</title><para>    Volunteers are most welcome. Check with me before you start on one of these in case someone else is working on it already.
   </para><itemizedlist><listitem><para>    A partition editor to adjust partition boundaries for a different hard drive, or the same one with different geometry, or to adjust partition sizes within the same hard drive. A GUI would probably be a good idea here. On the other tentacle, the FSF's <ulink url="http://www.gnu.org/software/parted"><filename moreinfo="none">parted</filename></ulink> looks like it will fill part of the bill. It does re-size existing partitions, but with restrictions.
    </para></listitem><listitem><para>    <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link> currently only recognizes some FAT partitions, not all. Add code to <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link> to recognize others and make appropriate instructions to rebuild them in the output files.
    </para></listitem><listitem><para>For FAT12 or FAT16 partitions we do not format, write zeros into the partition so that Mess-DOS 6.x does not get confused. See the notes on <command moreinfo="none">fdisk</command> for an explanation of the problem.</para></listitem><listitem><para>    Make a script for putting ext2/3 file systems on ZIP disks.
    </para></listitem><listitem><para>    Translations into other (human) languages.
    </para></listitem><listitem><para>Find out how loadlin or similar programs affect this process.</para></listitem><listitem><para>Changes for GRUB</para></listitem><listitem><para>Change the scripts to use a CD-ROM. A CD-ROM that would boot to <ulink url="http://www.toms.net/rb">tomsrtbt</ulink>, with the first stage restore data on the rest of it, would be just the ticket.</para></listitem><listitem><para>I've referred to Red Hat Package Manager (rpm) from time to time. What are the equivalent deb commands?</para></listitem></itemizedlist></sect2></sect1><sect1 id="thescripts"><title>The Scripts</title><para>   See the notes in the beginning of each script for a summary of what it does.
  </para><sect2 id="firststage"><title>First Stage</title><sect3 id="make.fdisk"><title><filename moreinfo="none">make.fdisk</filename></title><para>     This script, run at backup time, creates scripts similar to <link linkend="make.dev.hda"><filename moreinfo="none">make.dev.hda</filename></link> and <link linkend="mount.dev.hda"><filename moreinfo="none">mount.dev.x</filename></link>, below, for you to run at restore time. It also produces data files similar to <link linkend="dev.hda"><filename moreinfo="none">dev.hda</filename></link>, below. The name of the script and data file produced depends on the device given this script as a a parameter. That script, run at restore time, builds the partitions on the hard drive. <filename moreinfo="none">make.fdisk</filename> is called from <link linkend="save.metadata"><filename moreinfo="none">save.metadata</filename></link>, below.
    </para><programlisting format="linespecific"></programlisting></sect3><sect3 id="make.dev.hda"><title><filename moreinfo="none">make.dev.hda</filename></title><para>This script is a sample of the sort produced by <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link>, above. It uses data files like <link linkend="dev.hda"><filename moreinfo="none">dev.hda</filename></link>, below. It builds partitions and puts file systems on some of them. This is the first script run at restore time.</para><para>If you are brave enough to edit <link linkend="dev.hda"><filename moreinfo="none">dev.hda</filename></link> (q.v.), say, to add a new partition, you may need to edit this script as well.</para><para>If you want make.dev.hda to check for bad blocks when it puts a file system on the partitions, use a ent-cent command line option.</para><programlisting format="linespecific"></programlisting></sect3><sect3 id="mount.dev.hda"><title><filename moreinfo="none">mount.dev.hda</filename></title><para>This script is a sample of the sort produced by <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link>, above. It builds mount points and mounts partitions on them, making the target file system ready for restoring files. This is the second script run at restore time.</para><para>If you are brave enough to edit <link linkend="dev.hda"><filename moreinfo="none">dev.hda</filename></link> (q.v.), say, to add a new partition, you may need to edit this script as well.</para><programlisting format="linespecific"></programlisting></sect3><sect3 id="dev.hda"><title><filename moreinfo="none">dev.hda</filename></title><para>This data file is used at restore time. It is fed to <command moreinfo="none">fdisk</command> by the script <link linkend="make.dev.hda"><filename moreinfo="none">make.dev.hda</filename></link>. It is produced at backup time by <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link>. Those familiar with <command moreinfo="none">fdisk</command> will recognize that each line is an <command moreinfo="none">fdisk</command> command or value, such as a cylinder number. Thus, it is possible to change the partition sizes and add new partitions by editing this file. That's why the penultimate command is <command moreinfo="none">v</command>, to verify the partition table before it is written.</para><programlisting format="linespecific"></programlisting></sect3><sect3 id="save.metadata"><title><filename moreinfo="none">save.metadata</filename></title><para>     This is the first script to run as part of the backup process. It calls <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link>, above. If you have a SCSI hard drive or multiple hard drives to back up, edit the call to <link linkend="make.fdisk"><filename moreinfo="none">make.fdisk</filename></link> appropriately.
    </para><programlisting format="linespecific"></programlisting></sect3><sect3 id="restore.metadata"><title><filename moreinfo="none">restore.metadata</filename></title><para>     This script restores metadata from the ZIP disk as a first stage restore.
    </para><programlisting format="linespecific"></programlisting></sect3><sect3 id="first.stage"><title><filename moreinfo="none">first.stage</filename></title><para>This script runs the entire first stage restore with no operator intervention.</para><para>If you want to check for bad blocks when it puts a file system on the partitions, use a ent-cent command line option.</para><programlisting format="linespecific"></programlisting></sect3></sect2><sect2 id="secondstage"><title>Second Stage</title><para>    These scripts run on the computer being backed up or restored.
   </para><sect3 id="back.up.all"><title><filename moreinfo="none">back.up.all</filename></title><para>     This script saves to another computer via an NFS mount. You can adapt it to save to tape drives or other media.
    </para><programlisting format="linespecific"></programlisting></sect3><sect3 id="back.up.all.ssh"><title><filename moreinfo="none">back.up.all.ssh</filename></title><para>     This script does exactly what <link linkend="back.up.all"><filename moreinfo="none">back.up.all</filename></link> does, but it uses ssh instead of nfs.
    </para><programlisting format="linespecific"></programlisting></sect3><sect3 id="restore.all"><title><filename moreinfo="none">restore.all</filename></title><para>     This is the restore script to use if you backed up using <link linkend="back.up.all"><filename moreinfo="none">back.up.all</filename></link>.
    </para><programlisting format="linespecific"></programlisting></sect3><sect3 id="restore.all.ssh"><title><filename moreinfo="none">restore.all.ssh</filename></title><para>     This is the restoration script to use if you used <link linkend="back.up.all.ssh"><filename moreinfo="none">back.up.all.ssh</filename></link> to back up.
    </para><programlisting format="linespecific"></programlisting></sect3></sect2><sect2 id="backupserverscripts"><title>Backup Server Scripts</title><para>The ssh scripts above have a possible security problem. If you run them on a firewall, the firewall has to have access via ssh to the backup server. In that case, a clever cracker might also be able to crack the backup server. It would be more secure to run backup and restore scripts on the backup server, and let the backup server have access to the firewall. That is what these scripts are for. Rename them to <filename moreinfo="none">get.x</filename> and <filename moreinfo="none">restore.x</filename> where <filename moreinfo="none">x</filename> is the name of the target computer. Edit them (the variable enttarget's initialization) to use the target computer's host name, or rewrite them to use a command line argument.</para><para>These scripts backup and restore the target completely, not just the stage one backup and restore. Also, note that <filename moreinfo="none">get.tester</filename> backs up the ZIP disk as well, in case you need to replace a faulty ZIP disk.</para><para>I use these scripts routinely.</para><sect3 id="get.tester"><title><filename moreinfo="none">get.tester</filename></title><programlisting format="linespecific"></programlisting></sect3><sect3 id="restore.tester"><title><filename moreinfo="none">restore.tester</filename></title><programlisting format="linespecific"></programlisting></sect3></sect2></sect1><sect1 id="resources"><title>Resources</title><para>In no particular order. These are things you might want to investigate for yourself. A listing here should not be taken as an endorsement. In fact, in many case I have not used the product and cannot comment on it.</para><itemizedlist><listitem><para><ulink url="http://www.oreilly.com/catalog/unixbr/author.html">W. Curtis Preston</ulink>'s excellent <ulink url="http://www.oreilly.com/catalog/unixbr/"><citetitle pubwork="book">Unix Backup ent Recovery</citetitle></ulink>. This is the book that got me started on this bare metal recovery stuff. I highly recommend it; <ulink url="http://www2.linuxjournal.com/lj-issues/issue78/3839.html">read my review</ulink>.</para></listitem><listitem><para>A list of <ulink url="http://www.fokus.gmd.de/linux/linux-distrib-small.html">small Linux disties.</ulink></para></listitem><listitem><para><ulink url="http://www.toms.net/rb">tomsrtbt</ulink>, <quote>The most Linux on 1 floppy disk.</quote> Tom also has links to other small disties.</para></listitem><listitem><para>The <ulink url="http://www.tldp.org/">Linux Documentation Project</ulink>. See particularly the <quote><citetitle pubwork="article">LILO, Linux Crash Rescue HOW-TO</citetitle></quote></para></listitem><listitem><para>The Free Software Foundation's <ulink url="http://www.gnu.org/software/parted"><filename moreinfo="none">parted</filename></ulink> for editing (enlarging, shrinking, moving) partitions.</para></listitem><listitem><para><ulink url="http://www.partimage.org/">Partition Image</ulink> for backing up partitions.</para><para>From the web page: <quote>Partition Image is a Linux/UNIX utility which saves partitions in many formats (see below) to an image file. The image file can be compressed in the GZIP/BZIP2 formats to save disk space, and split into multiple files to be copied on removable floppies (ZIP for example), .... The partition can be saved across the network since version 0.6.0.</quote></para></listitem><listitem><para>Hugo Rabson's <ulink url="http://www.microwerks.net/~hugo/">Mondo</ulink> <quote>... creates one or more bootable Rescue CD's (or tape+floppies) containing some or all of your filesystem. In the event of catastrophic data loss, you will be able to restore from bare metal.</quote></para></listitem><listitem><para><ulink url="http://sourceforge.net/projects/bacula">Bacula</ulink> is a GLPled backup product which has bare metal recovery code inspired in part by this HOWTO.</para></listitem><listitem><para>The <ulink url="http://crashrecovery.org/">Crash Recovery Kit for Linux</ulink></para></listitem><listitem><para>The <ulink url="http://beeblebrox.sourceforge.net/">Beeblebrox Project</ulink> looks promising.</para></listitem></itemizedlist></sect1><appendix id="appendix1gfdl"><title>GNU Free Documentation License</title><para>Version 1.1, March 2000</para><blockquote><para>Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.</para></blockquote><sect1 label="0" id="gfdl02"><title>PREAMBLE</title><para>The purpose of this License is to make a manual, textbook,
    or other written document "free" in the sense of freedom: to
    assure everyone the effective freedom to copy and redistribute it,
    with or without modifying it, either commercially or
    noncommercially.  Secondarily, this License preserves for the
    author and publisher a way to get credit for their work, while not
    being considered responsible for modifications made by
    others.</para><para>This License is a kind of "copyleft", which means that
    derivative works of the document must themselves be free in the
    same sense.  It complements the GNU General Public License, which
    is a copyleft license designed for free software.</para><para>We have designed this License in order to use it for manuals
    for free software, because free software needs free documentation:
    a free program should come with manuals providing the same
    freedoms that the software does.  But this License is not limited
    to software manuals; it can be used for any textual work,
    regardless of subject matter or whether it is published as a
    printed book.  We recommend this License principally for works
    whose purpose is instruction or reference.</para></sect1><sect1 label="1" id="gfdl03"><title>APPLICABILITY AND DEFINITIONS</title><para>This License applies to any manual or other work that
    contains a notice placed by the copyright holder saying it can be
    distributed under the terms of this License.  The "Document",
    below, refers to any such manual or work.  Any member of the
    public is a licensee, and is addressed as "you".</para><para>A "Modified Version" of the Document means any work
    containing the Document or a portion of it, either copied
    verbatim, or with modifications and/or translated into another
    language.</para><para>A "Secondary Section" is a named appendix or a front-matter
    section of the Document that deals exclusively with the
    relationship of the publishers or authors of the Document to the
    Document's overall subject (or to related matters) and contains
    nothing that could fall directly within that overall subject.
    (For example, if the Document is in part a textbook of
    mathematics, a Secondary Section may not explain any mathematics.)
    The relationship could be a matter of historical connection with
    the subject or with related matters, or of legal, commercial,
    philosophical, ethical or political position regarding
    them.</para><para>The "Invariant Sections" are certain Secondary Sections
    whose titles are designated, as being those of Invariant Sections,
    in the notice that says that the Document is released under this
    License.</para><para>The "Cover Texts" are certain short passages of text that
    are listed, as Front-Cover Texts or Back-Cover Texts, in the
    notice that says that the Document is released under this
    License.</para><para>A "Transparent" copy of the Document means a
    machine-readable copy, represented in a format whose specification
    is available to the general public, whose contents can be viewed
    and edited directly and straightforwardly with generic text
    editors or (for images composed of pixels) generic paint programs
    or (for drawings) some widely available drawing editor, and that
    is suitable for input to text formatters or for automatic
    translation to a variety of formats suitable for input to text
    formatters.  A copy made in an otherwise Transparent file format
    whose markup has been designed to thwart or discourage subsequent
    modification by readers is not Transparent.  A copy that is not
    "Transparent" is called "Opaque".</para><para>Examples of suitable formats for Transparent copies include
    plain ASCII without markup, Texinfo input format, LaTeX input
    format, SGML or XML using a publicly available DTD, and
    standard-conforming simple HTML designed for human modification.
    Opaque formats include PostScript, PDF, proprietary formats that
    can be read and edited only by proprietary word processors, SGML
    or XML for which the DTD and/or processing tools are not generally
    available, and the machine-generated HTML produced by some word
    processors for output purposes only.</para><para>The "Title Page" means, for a printed book, the title page
    itself, plus such following pages as are needed to hold, legibly,
    the material this License requires to appear in the title page.
    For works in formats which do not have any title page as such,
    "Title Page" means the text near the most prominent appearance of
    the work's title, preceding the beginning of the body of the
    text.</para></sect1><sect1 label="2" id="gfdl04"><title>VERBATIM COPYING</title><para>You may copy and distribute the Document in any medium,
    either commercially or noncommercially, provided that this
    License, the copyright notices, and the license notice saying this
    License applies to the Document are reproduced in all copies, and
    that you add no other conditions whatsoever to those of this
    License.  You may not use technical measures to obstruct or
    control the reading or further copying of the copies you make or
    distribute.  However, you may accept compensation in exchange for
    copies.  If you distribute a large enough number of copies you
    must also follow the conditions in section 3.</para><para>You may also lend copies, under the same conditions stated
    above, and you may publicly display copies.</para></sect1><sect1 label="3" id="gfdl05"><title>COPYING IN QUANTITY</title><para>If you publish printed copies of the Document numbering more
    than 100, and the Document's license notice requires Cover Texts,
    you must enclose the copies in covers that carry, clearly and
    legibly, all these Cover Texts: Front-Cover Texts on the front
    cover, and Back-Cover Texts on the back cover.  Both covers must
    also clearly and legibly identify you as the publisher of these
    copies.  The front cover must present the full title with all
    words of the title equally prominent and visible.  You may add
    other material on the covers in addition.  Copying with changes
    limited to the covers, as long as they preserve the title of the
    Document and satisfy these conditions, can be treated as verbatim
    copying in other respects.</para><para>If the required texts for either cover are too voluminous to
    fit legibly, you should put the first ones listed (as many as fit
    reasonably) on the actual cover, and continue the rest onto
    adjacent pages.</para><para>If you publish or distribute Opaque copies of the Document
    numbering more than 100, you must either include a
    machine-readable Transparent copy along with each Opaque copy, or
    state in or with each Opaque copy a publicly-accessible
    computer-network location containing a complete Transparent copy
    of the Document, free of added material, which the general
    network-using public has access to download anonymously at no
    charge using public-standard network protocols.  If you use the
    latter option, you must take reasonably prudent steps, when you
    begin distribution of Opaque copies in quantity, to ensure that
    this Transparent copy will remain thus accessible at the stated
    location until at least one year after the last time you
    distribute an Opaque copy (directly or through your agents or
    retailers) of that edition to the public.</para><para>It is requested, but not required, that you contact the
    authors of the Document well before redistributing any large
    number of copies, to give them a chance to provide you with an
    updated version of the Document.</para></sect1><sect1 label="4" id="gfdl06"><title>MODIFICATIONS</title><para>You may copy and distribute a Modified Version of the
    Document under the conditions of sections 2 and 3 above, provided
    that you release the Modified Version under precisely this
    License, with the Modified Version filling the role of the
    Document, thus licensing distribution and modification of the
    Modified Version to whoever possesses a copy of it.  In addition,
    you must do these things in the Modified Version:</para><orderedlist numeration="upperalpha" inheritnum="ignore" continuation="restarts"><listitem><para>Use in the Title Page
      (and on the covers, if any) a title distinct from that of the
      Document, and from those of previous versions (which should, if
      there were any, be listed in the History section of the
      Document).  You may use the same title as a previous version if
      the original publisher of that version gives permission.</para></listitem><listitem><para>List on the Title Page,
      as authors, one or more persons or entities responsible for
      authorship of the modifications in the Modified Version,
      together with at least five of the principal authors of the
      Document (all of its principal authors, if it has less than
      five).</para></listitem><listitem><para>State on the Title page
      the name of the publisher of the Modified Version, as the
      publisher.</para></listitem><listitem><para>Preserve all the
      copyright notices of the Document.</para></listitem><listitem><para>Add an appropriate
      copyright notice for your modifications adjacent to the other
      copyright notices.</para></listitem><listitem><para>Include, immediately
      after the copyright notices, a license notice giving the public
      permission to use the Modified Version under the terms of this
      License, in the form shown in the Addendum below.</para></listitem><listitem><para>Preserve in that license
      notice the full lists of Invariant Sections and required Cover
      Texts given in the Document's license notice.</para></listitem><listitem><para>Include an unaltered
      copy of this License.</para></listitem><listitem><para>Preserve the section
      entitled "History", and its title, and add to it an item stating
      at least the title, year, new authors, and publisher of the
      Modified Version as given on the Title Page.  If there is no
      section entitled "History" in the Document, create one stating
      the title, year, authors, and publisher of the Document as given
      on its Title Page, then add an item describing the Modified
      Version as stated in the previous sentence.</para></listitem><listitem><para>Preserve the network
      location, if any, given in the Document for public access to a
      Transparent copy of the Document, and likewise the network
      locations given in the Document for previous versions it was
      based on.  These may be placed in the "History" section.  You
      may omit a network location for a work that was published at
      least four years before the Document itself, or if the original
      publisher of the version it refers to gives permission.</para></listitem><listitem><para>In any section entitled
      "Acknowledgements" or "Dedications", preserve the section's
      title, and preserve in the section all the substance and tone of
      each of the contributor acknowledgements and/or dedications
      given therein.</para></listitem><listitem><para>Preserve all the
      Invariant Sections of the Document, unaltered in their text and
      in their titles.  Section numbers or the equivalent are not
      considered part of the section titles.</para></listitem><listitem><para>Delete any section
      entitled "Endorsements".  Such a section may not be included in
      the Modified Version.</para></listitem><listitem><para>Do not retitle any
      existing section as "Endorsements" or to conflict in title with
      any Invariant Section.</para></listitem></orderedlist><para>If the Modified Version includes new front-matter sections
    or appendices that qualify as Secondary Sections and contain no
    material copied from the Document, you may at your option
    designate some or all of these sections as invariant.  To do this,
    add their titles to the list of Invariant Sections in the Modified
    Version's license notice.  These titles must be distinct from any
    other section titles.</para><para>You may add a section entitled "Endorsements", provided it
    contains nothing but endorsements of your Modified Version by
    various parties--for example, statements of peer review or that
    the text has been approved by an organization as the authoritative
    definition of a standard.</para><para>You may add a passage of up to five words as a Front-Cover
    Text, and a passage of up to 25 words as a Back-Cover Text, to the
    end of the list of Cover Texts in the Modified Version.  Only one
    passage of Front-Cover Text and one of Back-Cover Text may be
    added by (or through arrangements made by) any one entity.  If the
    Document already includes a cover text for the same cover,
    previously added by you or by arrangement made by the same entity
    you are acting on behalf of, you may not add another; but you may
    replace the old one, on explicit permission from the previous
    publisher that added the old one.</para><para>The author(s) and publisher(s) of the Document do not by
    this License give permission to use their names for publicity for
    or to assert or imply endorsement of any Modified Version.</para></sect1><sect1 label="5" id="gfdl07"><title>COMBINING DOCUMENTS</title><para>You may combine the Document with other documents released
    under this License, under the terms defined in section 4 above for
    modified versions, provided that you include in the combination
    all of the Invariant Sections of all of the original documents,
    unmodified, and list them all as Invariant Sections of your
    combined work in its license notice.</para><para>The combined work need only contain one copy of this
    License, and multiple identical Invariant Sections may be replaced
    with a single copy.  If there are multiple Invariant Sections with
    the same name but different contents, make the title of each such
    section unique by adding at the end of it, in parentheses, the
    name of the original author or publisher of that section if known,
    or else a unique number.  Make the same adjustment to the section
    titles in the list of Invariant Sections in the license notice of
    the combined work.</para><para>In the combination, you must combine any sections entitled
    "History" in the various original documents, forming one section
    entitled "History"; likewise combine any sections entitled
    "Acknowledgements", and any sections entitled "Dedications".  You
    must delete all sections entitled "Endorsements."</para></sect1><sect1 label="6" id="gfdl08"><title>COLLECTIONS OF DOCUMENTS</title><para>You may make a collection consisting of the Document and
    other documents released under this License, and replace the
    individual copies of this License in the various documents with a
    single copy that is included in the collection, provided that you
    follow the rules of this License for verbatim copying of each of
    the documents in all other respects.</para><para>You may extract a single document from such a collection,
    and distribute it individually under this License, provided you
    insert a copy of this License into the extracted document, and
    follow this License in all other respects regarding verbatim
    copying of that document.</para></sect1><sect1 label="7" id="gfdl09"><title>AGGREGATION WITH INDEPENDENT WORKS</title><para>A compilation of the Document or its derivatives with other
    separate and independent documents or works, in or on a volume of
    a storage or distribution medium, does not as a whole count as a
    Modified Version of the Document, provided no compilation
    copyright is claimed for the compilation.  Such a compilation is
    called an "aggregate", and this License does not apply to the
    other self-contained works thus compiled with the Document, on
    account of their being thus compiled, if they are not themselves
    derivative works of the Document.</para><para>If the Cover Text requirement of section 3 is applicable to
    these copies of the Document, then if the Document is less than
    one quarter of the entire aggregate, the Document's Cover Texts
    may be placed on covers that surround only the Document within the
    aggregate.  Otherwise they must appear on covers around the whole
    aggregate.</para></sect1><sect1 label="8" id="gfdl10"><title>TRANSLATION</title><para>Translation is considered a kind of modification, so you may
    distribute translations of the Document under the terms of section
    4.  Replacing Invariant Sections with translations requires
    special permission from their copyright holders, but you may
    include translations of some or all Invariant Sections in addition
    to the original versions of these Invariant Sections.  You may
    include a translation of this License provided that you also
    include the original English version of this License.  In case of
    a disagreement between the translation and the original English
    version of this License, the original English version will
    prevail.</para></sect1><sect1 label="9" id="gfdl11"><title>TERMINATION</title><para>You may not copy, modify, sublicense, or distribute the
    Document except as expressly provided for under this License.  Any
    other attempt to copy, modify, sublicense or distribute the
    Document is void, and will automatically terminate your rights
    under this License.  However, parties who have received copies, or
    rights, from you under this License will not have their licenses
    terminated so long as such parties remain in full
    compliance.</para></sect1><sect1 label="10" id="gfdl12"><title>FUTURE REVISIONS OF THIS LICENSE</title><para>The Free Software Foundation may publish new, revised
    versions of the GNU Free Documentation License from time to time.
    Such new versions will be similar in spirit to the present
    version, but may differ in detail to address new problems or
    concerns.  See <ulink url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para><para>Each version of the License is given a distinguishing
    version number.  If the Document specifies that a particular
    numbered version of this License "or any later version" applies to
    it, you have the option of following the terms and conditions
    either of that specified version or of any later version that has
    been published (not as a draft) by the Free Software Foundation.
    If the Document does not specify a version number of this License,
    you may choose any version ever published (not as a draft) by the
    Free Software Foundation.</para></sect1><sect1 label="11" id="gfdl13"><title>How to use this License for your documents</title><para>To use this License in a document you have written, include
    a copy of the License in the document and put the following
    copyright and license notices just after the title page:</para><blockquote><para>      Copyright (c)  YEAR  YOUR NAME.
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with the Invariant Sections being LIST THEIR TITLES, with the
      Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
      A copy of the license is included in the section entitled "GNU
      Free Documentation License".</para></blockquote><para>If you have no Invariant Sections, write "with no Invariant
    Sections" instead of saying which ones are invariant.  If you have
    no Front-Cover Texts, write "no Front-Cover Texts" instead of
    "Front-Cover Texts being LIST"; likewise for Back-Cover
    Texts.</para><para>If your document contains nontrivial examples of program
    code, we recommend releasing these examples in parallel under your
    choice of free software license, such as the GNU General Public
    License, to permit their use in free software.</para></sect1></appendix></article>

