13 Selective restore

Contents of this section

In a selective restore of a backup, not all files in the archive are extracted, but only those whose names match a particular pattern.

Some examples of patterns are

*/Xconfig
for extracting all files named Xconfig from the archive and
usr/src/gzip-0.7/*
for extracting the source tree of an old gzip version stored in the archive.

The first step to making up selection patterns is knowing what files are in the archive. Tbackup has the capability to make index files that supply this information.

13.1 Potential problems Creating index files

If you are making an archive with tbackup and are planning to do selective restores on it later, you should switch on the `Make a backup index file' option of tbackup. Here is a sample transcript:

#tbackup
 ^^^^^^^
   ...entering parameters for a full backup of directory set `ext'...
 
Make a backup index file ---> (y/n) [n] y
                                        ^
Tbackup will suggest an appropriate name for the index file. Assuming there already is an index file named /root/idx/ext.idx.1, we get

backup index file name---> [/root/idx/ext.idx.2] 
                                                 ^(pressed enter)
By default, tbackup will suggest making an index file in your home directory (/root on my machine), but this can be changed to a more appropriate place by editing the file /etc/tbackup/Config. Change the line

export indexdir=~/idx
to something else, e.g.

export indexdir=/var/index
Tbackup tries to ensure that there is enough room to write the index file by watching the available disk space:
[Note: the backup will be paused if the free disk space for
 /root/idx/ext.idx.2 drops below 50Kb. If this happens, free some
 disk space to continue the backup.]
Note however that this protection mechanism isn't failsafe: while tbackup is working another program may fill up the hard disk so fast that tbackup doesn't notice it until it is too late. If you don't plan to do selective restores, the is no real need for making an index file. If you change your mind later, you can create an index of an existing archive by running the tlist command.

13.2 Interpreting index files

An index file contains a description of the backup, the values you entered for the parameters, and a list of all files in the archive. Here is what a backup index file looks like:

Full backup of directory set ext.
(Filenames in archive relative to /)
Made with tbackup (V0.7 beta)
by root@noodle, on Mon Dec 27 12:47:50  1993
----parameters:-----
export pre_choosemethod=set
export dea_setname=ext

[....part deleted...]

export dea_indexfilename=/root/ext.idx.2
-------------backup index---------------------
ext -- okay
ext/tmp -- okay
ext/X386 -- okay
ext/X386/bin -- okay
********** Approx. start of part 1 **********
ext/X386/bin/listres.z -- (26%)

[....part deleted...]

ext/src/txt/megastruct.z -- (38%)
ext/src/txt/fscomp.z -- (43%)
********** Approx. start of part 8 **********
ext/src/txt/khg.taz -- okay
ext/src/txt/lsm-05SEP93.z -- okay
ext/src/txt/tls.z -- (37%)
ext/src/txt/happynet.z -- (48%)

[....etc....]
The file list itself is actually just the `backup progress' output made by the pack method (in this case the afio archiver), interspersed with **Approx. start of part ..** messages that tell you on which disk a particular file can be found.

Note that afio puts a .z after the filename when it stores the compressed version of a file in the archive. For example, the last index line shown above means that the archive contains the file /ext/src/txt/happynet in a compressed form, not that it contains the compressed file /ext/src/txt/happynet.z.

However, the .z in /ext/src/txt/lsm-05SEP93.z above was not added by afio, this file had a .z already (is was gzipped with an older gzip version). Notice that afio shows no compression percentage after this file.

The **Approx. start of part** messages usually appear a little too late in the index; for the index above the exact start of part 8 is probably somewhere in the middle of the file ext/src/txt/fscomp or even ext/src/txt/megastruct.

13.3 Performing a partial restore

Suppose that the file /ext/src/txt/happynet was accidentally deleted. Below is a transcript of the partial restore operation for this file.

# trestore
  ^^^^^^^^
Available read methods:
   1 filedev    -- read archive from file or device.
   2 floppy     -- read from msdos floppy disks with mtools.
   3 floppypart -- read a part of a floppy archive
Enter method name or number ---> [floppy] floppypart
                                          ^^^^^^^^^^
From reading the index file we know we can start at part 8.
Number of first part to read from the backup set ---> 8
                                                      ^
  [Note: you can end the partial read by entering `o'
   and then `e!' when asked to insert the next part.]
 
Read from floppy drive number (0/1) ---> [1] 
                                             ^(pressed enter)
Insert a disk from the backup set in drive 1 and press enter.
 
Backup description:
 
  Full backup of directory set ext.
  (Filenames in archive relative to /)
  Made with tbackup (V0.7 beta)
  by root@noodle, on Mon Dec 27 12:47:50  1993

[..text deleted..] 
Note that this backup description is also at the top of the index file listing our ext/src/txt/happynet file. This way we can verify that we got the right floppies.
This archive specifies `afio' as the default unpack method.
 
Available unpack methods:
   1 afio     -- unpack files with afio, uncompress files with gzip
   2 afio0    -- unpack files with afio. (no uncompress)
   3 selafio  -- selectively unpack files with afio, uncompress with gzip
   4 selafio0 -- selectively unpack files with afio. (no uncompress)
   5 seltar   -- selectively unpack files with tar (no uncompress)
   6 tar      -- unpack files with tar (no uncompress)
We're using a selective unpacking method here:
Enter method name or number ---> [selafio] 
                                           ^(pressed enter)
This archive was packed relative to the directory /.
Selectively unpack archive in directory ---> [/] 
                                                 ^(pressed enter)
We need only one pattern to select the ext/src/txt/happynet file, but in general you can supply as many patterns as you want for a selective restore.

If you want to use many complicated patterns, it is best to put them in a file beforehand. Simple patterns can also be entered directly, which is what we will do now:

Read selection patterns from file?---> (y/n) [y] n
                                                 ^
Enter patterns (one per line), end with a "." on a line.
Examples:   /usr/src/linux/*
            usr/src/linux/*
             (a leading / is ignored in pattern matches)
            *Xconfig
 
---> ext/src/txt/happynet
     ^^^^^^^^^^^^^^^^^^^^
---> .
     ^
Protect newer files from overwriting?---> (y/n) [y] 
                                                    ^(pressed enter)
A restore index file will (among other things) list all files that were selectively restored. This information can be useful for checking if a complicated selective restore actually worked. There's not much sense in making an index of this restore:
Make a restore index file ---> (y/n) [n] 
                                         ^(pressed enter)
  [Creating restore progress window]
 
Restore in progress...
 
--Insert the disk with part 8 in drive 1
  and press enter. (Type o for options.)
                                         ^(pressed enter)
Reading part 8 from floppy 1..........
Finished reading part 8.  [you can remove the floppy]
Watching the backup progress messages on virtual console 6 (or in the progress window if we're running X), we see that the archiver produces some warnings about not being at the start of an archive. Here is what it looks like:

afio: "/tmp/tbup/archive" [offset 0]: Bad magic number
afio: "/tmp/tbup/archive" [offset 6k+396]: Bad swapped pathname length
afio: "/tmp/tbup/archive" [offset 49k+410]: Bad swapped pathname length
afio: "/tmp/tbup/archive" [offset 124k+56]: Apparently resynchronized
afio: "ext/src/txt/lsm-05SEP93.z": Continuing
After that it extracts the happynet file:
ext/src/txt/happynet -- uncompressed
Tbackup has no way of knowing that all selected files are restored from the archive; it just prompts for the next floppy, leaving it up to the user to end the restore when the last selected file has been extracted.

The progress messages tell us that ext/src/txt/happynet has been restored, so we end the restore via the options menu:

--Insert the disk with part 9 in drive 1
  and press enter. (Type o for options.) o
                                         ^
 Enter one of the following commands:
                           (You may want to insert a new disk first.)
 r  : retry reading part 9 from drive 1
 s  : salvage readable data for part 9 from drive 1
 q! : quit trying to read this part, continue with the next part
 e! : indicate end of archive
-->e!
   ^^
Indicate end of archive? (y/n) ---> y
                                    ^
End of archive indicated.
Watch the restore log for possible archiver errors.

Cleaning up...
 
Restore completed.
# 
Since the archive ended prematurely, we get two archiver errors:
afio: "/tmp/tbup/archive" [offset 710k+0]: Input EOF
afio: "/dev/tty": Unavailable

13.4 Managing index files

Apart from suggesting an appropriate name, tbackup provides no mechanism for managing, archiving or searching index files. In particular, the selective restore methods do not read or interpret index files directly: they leave this task to to the user. (Future versions of tbackup may provide some specialized tools for searching index files.)

Index files can easily be managed with standard unix tools. Index files compress (gzip) very well, so there is usually no problem in keeping a collection on your hard disk.

Index files (compressed or not) can be searched with the zgrep command, e.g.

# cd ~/idx
# zgrep frommel.tex *idx*
  ^^^^^^^^^^^^^^^^^^^^^^^
mystuff.idx.1.gz:/root/tex/wuxta/frommel.tex.z -- (32%)
mystuff.idx.2:/root/tex/wuxta/frommel.tex.z -- (31%)
mystuff.idx.3.gz:/root/tex/wuxta/frommel.tex.z -- (38%)
tells you that there are three index files containing frommel.tex. Assuming that the last one is from the most recent backup, the following command tells us which floppies we need:

# zcat mystuff.idx.2.gz |head -4
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Incremental (on full) backup of directory set mystuff.
(Filenames in archive relative to /)
Made with tbackup (V0.7 beta)
by root@noodle, on Fri Dec 10 13:21:45  1993
Broken pipe
So we should look for the floppies labeled mystuff inc 10 dec 1993 or somesuch.

By looking at mystuff.idx.2.gz with zmore, we can also determine the part number of the floppy disk containing frommel.tex.

13.5 Complicated patterns

Usually these tree kinds of patterns are all what you need:

For completeness, here are the rules for pattern matching:

13.6 Pattern files

If you want to use many complicated selection patterns for a restore, it is best to put them in a file beforehand and use the `Read selection patterns from file' option of trestore.

Such pattern files may contain:

An example of a valid pattern file:

#a valid pattern file

*/Xconfig
   usr/src/xlife/*[Mm]akefile

 usr/bin/?roff
*emacs*
Trestore will warn you if you supply suspicious patterns. It can produce the following warnings:

Regex in stead of selection pattern

if you use a pattern beginning with ˆ or ending in $

Leading / in tar pattern

if you use a leading slash in a pattern with the seltar unpack method

Control character in line n

usually caused by an editing error in a pattern file

Text after pattern on line n

usually caused by an editing error in a pattern file.

Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter