git.gag.com Git - debian/amanda/blob - docs/INDEXING

   1 This file describes how the index files are generated and how amrecover
   2 is used.
   3
   4
   5 Database Format
   6 ---------------
   7
   8 The database consists of a directory tree of the format:
   9   $host/$disk/$date_$level.gz
  10
  11 The host and disk are those listed in the disklist file, the "$host/$disk/"
  12 is like the curinfo database, '/' are changed for '_'.
  13 There is an index file for each dump, the name of the file is made
  14 of the date and the level, they will have the .gz suffix if they are
  15 compressed with gzip.
  16
  17 ex. The file foo/_usr/19991231_0.gz is the index of the level 0 made on
  18     19991231 of the disk /usr of the host foo.
  19
  20 The files are ASCII text files containing a list of the directory
  21 and files of the dump, one per line.  Each entry is the filename
  22 relative to the mount point, starting with a /, e.g., /home/user1/data
  23 from the disk mounted on /home would generate the entry /user1/data.
  24 The index files are stored in compressed format (eg gzip or compress).
  25
  26
  27 Database Browsing
  28 -----------------
  29
  30 The client is called amrecover and is loosely based on the
  31 functionality of the program "recover" from Backup Copilot.  A user
  32 starts up amrecover.  This requires specifying the index server and the
  33 amanda config name (defaults for both are compiled in as part of the
  34 installation).  Then the user has to specify the name of the host
  35 information is wanted about, the disk name, and (optionally) the disk
  36 mount point.  Finally a date needs to be specified.  Given all this,
  37 the user can then roam around a virtual file system using "ls" and "cd"
  38 much like in a FTP client.  The file system contains all files backed
  39 up on the specified date, or before that date, back to the last level 0
  40 backup.  Only the most recent version of any file is shown.
  41
  42 As the file system is traversed, the user can add and delete files to a
  43 "shopping list", and print the list out.
  44
  45
  46 File Extraction
  47 ---------------
  48
  49 When a user has built up a list of files to extract, they can be
  50 extracted by issuing the command "extract" within amrecover.
  51
  52 Files are extracted by the following, for each different tape needed.
  53
  54 As part of the installation, a "tape server" daemon amidxtaped is
  55 installed on one or more designated hosts, which have an attached tape
  56 drive.  This is used to read the tapes.  See the config files for the
  57 options for specifying a default.
  58
  59 Amrecover contacts amidxtaped on the tape server host specifying which
  60 tape device to use, which host and disk files are needed for.  On the
  61 tape server host, amidxtaped exec's amrestore to get the dump image
  62 file off the tape, and returns the data to amrecover.
  63
  64 If dumps are stored compressed for the client, then amrecover pipes the
  65 data through the appropriate uncompression routine to uncompress it
  66 before piping it into restore, which then extracts the required files
  67 from the dump image.
  68
  69 Note that a user can only extract files from a host running the same
  70 operating system as he/she is executing amrecover on, since the native
  71 dump/restore tools are used - unless gnutar is used.
  72
  73
  74 Protocol Between amindexd and amrecover
  75 ---------------------------------------
  76
  77 The protocol talked between amindexd and amrecover is a simple ASCII
  78 chat protocol based on that used in FTP.  Amrecover sends a 1 line
  79 command, and amindexd replies with a 1 line or multi-line reply.  Each
  80 line of the reply starts with a three digit code, starting with a '5'
  81 if an error occurred.  For 1 line replies, and the last line of a
  82 multi-line reply, the 4th character is a space.  For all but the last
  83 line of a multi-line reply, the 4th character is a '-'.
  84
  85 The commands and replies other than acknowledgments are:
  86
  87 QUIT - finish up and close connection
  88
  89 HOST <host> - set host to host
  90
  91 DISK <disk> - set disk to disk
  92
  93 LISTDISK [<device>] - list the disks for the current host
  94
  95 SCNF <config> - set amanda configuration to config
  96
  97 DATE <date> - set date to date
  98
  99 DHST - return dump history of current disk
 100
 101 OISD <dir> - Opaque is directory? query.  Is the directory <dir>
 102              present in the backups of the current disk back to and
 103              including the last level 0 dump.
 104
 105 OLSD <dir> - Opaque list directory.  Give all filenames present in
 106              <dir> in the backups of the current disk back to and
 107              including the last level 0 dump.
 108
 109 ORLD <dir> - Opaque recursive list directory.  Give all filenames
 110              present in <dir> and subdir in the backups of the current
 111              disk back to and including the last level 0 dump.
 112
 113 TAPE - return value of tapedev from amanda.conf if set.
 114
 115 DCMP - returns "YES" if dumps for disk are compressed, "NO" if dumps
 116              aren't.
 117
 118
 119
 120 INSTALLATION NOTES
 121 ------------------
 122
 123
 124 1) Whether or not an index is created for a disk is controlled by a
 125 disk configuration option "index".  So, in amanda.conf you need to
 126 define a disktype with this option, e.g.,
 127
 128 define dumptype comp-user-index {
 129     comment "Non-root partitions on reasonably fast machines"
 130     compress client fast
 131     index yes
 132     priority medium
 133 }
 134
 135 2) You need to define disks that you want to generate an index for to
 136 be of one of the disktypes you defined which contain the index option.
 137 This cause sendbackup-dump on the client machine to generate an index
 138 file which is stored local to the client, for later recovery by
 139 amgetidx (which is called by amdump).
 140
 141 3) Amanda saves all the index files under a directory specified by
 142 "indexdir" in amanda.conf.  You need to create this directory by hand.
 143 It needs to have read/write permissions set for the user you defined
 144 to run Amanda.
 145
 146 If you are using the "text database" option you may set indexdir and
 147 infofile to be the same directory.
 148
 149 4) The index browser, amrecover, currently gets installed as part of
 150 the client software.  Its location may not be appropriate for your
 151 system and you may need to move it to a more accessible place such as
 152 /usr/local/bin.  See its man page for how to use it.
 153
 154
 155 Note that amindexd, amgetidx, amidxtaped, and amtrmidx all write debug
 156 files on the server in /tmp (unless this feature is disabled in the
 157 source code), which are useful for diagnosing problems.  Amrecover
 158 writes a debug file in /tmp on the machine it is invoked.
 159
 160
 161 PERMISSIONS
 162 -----------
 163
 164 The userid chosen to run the amanda client code must have permission to
 165 run restore since this is used by createindex-dump to generate the
 166 index files.
 167
 168 For a user to be able to restore files from within amrecover, that user
 169 must have permission to run restore.
 170
 171
 172 CHANGES FROM AMINDEX-1.0
 173 ------------------------
 174
 175 Get index directory from amanda.conf
 176
 177 Integration into amanda-2.3.0.4.
 178
 179 Rewriting of amgetidx to use amandad instead of using rsh/rcp.
 180
 181
 182
 183 CHANGES FROM AMINDEX-0.3
 184 ------------------------
 185
 186 Support for index generation using gnutar
 187
 188 Support for restoring files from within amrecover.
 189
 190 Bug fixes:
 191
 192         * index/client/amrecover.c (guess_disk):
 193         Removed inclusion of mntent.h and use of MAXMNTSTR since this
 194         was non-portable, as pointed out by Izzy Ergas
 195         <erga00@nbhd.org>.
 196
 197         * index/client/display_commands.c (list_directory):
 198         Removed point where list_directory() could sleep for ever
 199         waiting for input that wasn't going to come.
 200
 201         * index/server/amindexd.c
 202           index/client/uscan.l
 203         Installed patches from Les Gondor <les@trigraph.on.ca> to make
 204         amrecover handle spaces in file names.
 205
 206         * server-src/amcontrol.sh:
 207         As pointed out by Neal Becker <neal@ctd.comsat.com> there were
 208         still a few sh-style comments that needed conversion to
 209         c-style.
 210
 211
 212
 213
 214 CHANGES FROM AMINDEX-0.2
 215 ------------------------
 216
 217         * index/client/Makefile.in
 218         * index/client/help.c
 219         * index/client/amrecover.h
 220         * index/client/uparse.y
 221         * index/client/uscan.l
 222         Added a help command.
 223
 224         * index/client/set_commands.c:
 225         set_disk() and set_host() now check for empty extract list.
 226
 227         * index/client/extract_list.c:
 228         * index/client/amrecover.h:
 229         * index/client/uparse.y:
 230         * index/client/uscan.l:
 231         Added clear extract list command.
 232
 233         * index/client/set_commands.c (set_disk):
 234         Added code so working directory set to mount point.
 235
 236         * index/client/extract_list.c:
 237         If the last item on a tape list is deleted, the tape list
 238         itself is now deleted from the extract list.
 239
 240         * index/client/amrecover.c:
 241         * index/server/amindex.c:
 242         If the server started up and found that the index dir doesn't
 243         exist, then it exited immediately and the client got
 244         informative message.  Corrected this so it is obvious what is
 245         wrong to the user, since this is most likely to occur when
 246         somebody is setting up for the first time and needs all the
 247         help they can get.
 248
 249         * server-src/amgetidx.c
 250         Added patch from Pete Geenhuizen
 251         (pete@gasbuggy.rockledge.fl.us) so that it works even when
 252         remote shell is csh.
 253
 254         * server-src/amcontrol.sh
 255         * server-src/Makefile.in
 256         Amcontrol is now parameterized like other scripts and run
 257         through munge to generate installable version.
 258
 259         * index/server/amindexd.c (main):
 260         Added code to set userid if FORCE_USERID set.
 261
 262         * index/server/amindexd.c
 263         Removed #define for full path of grep.  Assumed now to be on
 264         path.
 265
 266         * client-src/createindex-dump.c
 267         * client-src/sendbackup-dump.c
 268         * man/Makefile.in
 269         Added patch from Philippe Charnier (charnier@lirmm.fr) so they
 270         work when things are installed with version numbers.  This was
 271         also reported by Neal Becker (neal@ctd.comsat.com).  Also patch
 272         to set installed man page modes and create directory if
 273         needed.
 274
 275         * config/options.h-sunos4
 276         Corrected definition for flex library.
 277
 278         * server-src/amtrmidx.c
 279         Added some pclose() commands, used remove() instead of
 280         system("rm ..").  Problems reported by Pete Geenhuizen
 281         (pete@gasbuggy.rockledge.fl.us) on a system with small ulimits
 282         set.
 283
 284         * index/server/amindexd.[ch]
 285         * index/server/list_dir.c
 286         * index/client/amrecover.c
 287         * index/client/set_commands.c
 288         * index/client/uparse.y
 289         Changes developed with the help of Pete Geenhuizen
 290         (pete@gasbuggy.rockledge.fl.us) to support disks specified by
 291         logical names.  Also, now debug files generated by amrecover
 292         include PID so multiple users can use amrecover simultaneously
 293         and without file deletion permission problems.
 294
 295         * config/config.h-hpux:
 296         * config/config-common.h:
 297         * server-src/amgetidx.c:
 298         Changes from Neal Becker re remote shell, making it a
 299         configuration parameter.
 300
 301         * config/options.h-sunos4
 302         Had -Lfl instead of -lfl
 303
 304
 305
 306 CHANGES FROM AMINDEX-0.1
 307 ------------------------
 308
 309         * index/client/uscan.l:
 310         added support for abbreviated date specs
 311
 312         * index/client/amrecover.c (guess_disk):
 313         guess_disk got disk_path wrong if mount point other than / (as
 314         subsequently pointed out by Eir Doutreleau <ed@cti.ecp.fr>)
 315
 316         * server-src/amtrmidx:
 317         Added amtrmidx which removes old index files.
 318
 319         * index/client:
 320         Added a pwd command
 321
 322         * server-src/amgetidx.c (main):
 323         Added use of CLIENT_LOGIN username on r commands.  (as pointed
 324         out by Eric Payan <Eric.Payan@ufrima.imag.fr>)
 325
 326         * server-src/amgetidx.c:
 327         Bug: It was copying from all clients irrespective of whether
 328         the client was configured for indices.  A '}' in the wrong
 329         place.
 330
 331         * server-src/amgetidx.c:
 332         Removed user configuration section.  Instead include amindexd.h
 333         to get information.
 334
 335
 336
 337 CHANGES/ADDITIONS TO 2.3.0
 338 --------------------------
 339
 340 common-src/conffile.[ch]
 341
 342 - added "index" as a valid option
 343
 344
 345 server-src/driverio.c
 346
 347 - added code to optionstr() to write "index" into option string
 348
 349
 350 client-src/sendback-dump.c
 351
 352 - added code to generate index if requested.
 353
 354 client-src/indexfilename.[ch]
 355 client-src/createindex-dump.c
 356
 357 - code to generate index.
 358
 359 client-src/Makefile.in
 360
 361 - a new target.  Another file for sendbackup-dump
 362
 363 config/config-common.h
 364
 365 - added def of restore.
 366
 367
 368
 369
 370 KNOWN BUGS
 371 ----------
 372
 373 - Empty directories don't get into the listing for a dump (at all dump
 374 levels).
 375
 376 - When amrecover starts up, it tries to guess the disk and mount point
 377 from the current directory of the working system.  This doesn't work
 378 for disks specified by logical names, nor when an automounter is being
 379 used, or a link is in the path.
 380
 381
 382 Alan M. McIvor
 383 11 March 1997