doc/man-pages/pod1/restorevol.pod

   1 =head1 NAME
   2
   3 restorevol - Restore a volume from vos dump to the local file system
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<restorevol> S<<< [B<-file> <I<dump file>>] >>> S<<< [B<-dir> <I<restore dir>> ] >>>
  11     S<<< [B<-extension> <I<name extension>>] >>>
  12     S<<< [B<-mountpoint> <I<mount point root>>] >>>
  13     S<<< [B<-umask> <I<mode mask>>] >>> [B<-help>]
  14
  15 =for html
  16 </div>
  17
  18 =head1 DESCRIPTION
  19
  20 B<restorevol> takes an AFS volume in the format produced by B<vos dump>
  21 and restores it to the local file system.  Normally, the contents of a
  22 volume are maintained by the AFS File Server in an opaque format and
  23 copying a volume's raw data does not make it easily accessible.  This
  24 utility will produce a directory tree that is equivalent to that seen via
  25 an AFS client, but without preserving the AFS-specific Access Control
  26 Lists (ACLs).  It's primary use is to recover data from a volume dump or
  27 backup and make it available via a filesystem other than AFS.
  28
  29 The dump output will read from standard input, or from a file if B<-file>
  30 is specified.
  31
  32 The restore process is as follows:
  33
  34 =over 4
  35
  36 =item 1.
  37
  38 The dump file will be restored within the current directory or that
  39 specified with B<-dir>.
  40
  41 =item 2.
  42
  43 Within this directory, a subdir is created.  It's name is the RW volume
  44 name that was dumped.  An extension can be appended to this directory name
  45 with B<-extension>.
  46
  47 =item 3.
  48
  49 All mountpoints will appear as symbolic links to the volume name.  The
  50 path name to the volume will be either that in B<-mountpoint>, or B<-dir>.
  51 Symbolic links remain untouched.
  52
  53 =item 4.
  54
  55 You can change your umask during the restore with B<-umask>.  Otherwise,
  56 B<restorevol> uses your current umask.  Mode bits for directories are 0777
  57 (then AND'ed with the umask).  Mode bits for files are the owner mode bits
  58 duplicated accross group and user (then AND'ed with the umask).
  59
  60 =item 5.
  61
  62 For restores of full dumps, if a directory says it has a file and the file
  63 is not found, then a symbolic link F<< AFSFile-<#> >> will appear in that
  64 restored tree.  Restores of incremental dumps remove all these files at
  65 the end (expensive because it is a tree search).
  66
  67 =item 6.
  68
  69 If a file or directory was found in the dump but found not to be connected
  70 to the hierarchical tree, then the file or directory will be connected at
  71 the root of the tree as F<< __ORPHANEDIR__.<#> >> or F<<
  72 __ORPHANFILE__.<#> >>.
  73
  74 =item 7.
  75
  76 ACLs are not restored.
  77
  78 =back
  79
  80 =head1 CAUTIONS
  81
  82 Normally, use L<vos_restore(1)> instead of this command.  B<restorevol> is
  83 a tool of last resort to try to extract data from the data structures
  84 stored in a volume dumpfile and is not as regularly tested or used as the
  85 normal L<vos_restore(1)> implementation.  Using B<restorevol> bypasses
  86 checks done by the L<fileserver(8)> and L<salvager(8)>.
  87
  88 =head1 OPTIONS
  89
  90 =over 4
  91
  92 =item B<-file> <I<dump file>>
  93
  94 Specifies the volume dump file to be read and restored to the local filesystem.
  95 If this option is not given, the volume dump will be read from standard input.
  96
  97 =item B<-dir> <I<restore dir>>
  98
  99 Names the directory in which to create the restored filesystem.  The
 100 current directory is used by default.  Note that any mountpoints inside
 101 the volume will point to the same directory unless the B<-mountpoint>
 102 option is also specified.
 103
 104 =item B<-extension> <I<name extension>>
 105
 106 By default, the name of the directory created matches the RW volume name
 107 of the volume in the dump file.  If this option is used, the directory
 108 name will be the RW volume name I<name extension> as the suffix.
 109
 110 =item B<-mountpoint> <I<mount point root>>
 111
 112 By default, mountpoints inside the volume being restored point to the
 113 value given by I<-dir>.  This option allows mountpoints to be resolved
 114 relative to another path.  A common use for this would be to specify a
 115 path under F</afs> as the mount point root so that mountpoints inside the
 116 restored volume would be resolved via AFS.
 117
 118 The I<mount point root> must exist, and the process running the command
 119 have read access to that directory, or the command will fail.
 120
 121 =item B<-umask> <I<mode mask>>
 122
 123 Sets the umask while creating files. If not specified, the current process
 124 umask is used. All directories are created with mode C<0777> (ANDed with the
 125 umask), and files are created with the owner, group, and user mode bits set to
 126 the owner mode bits of the relevant AFS file (ANDed with the umask).
 127
 128 =item B<-help>
 129
 130 Prints the online help for this command. All other valid options are
 131 ignored.
 132
 133
 134 =back
 135
 136 =head1 EXAMPLES
 137
 138 The following command restores the contents of the dumpfile in
 139 F<sample.dump> to the directory F</tmp/sample.2009-05-17>, but having all
 140 mountpoints inside the volume point to AFS (note that this requires
 141 knowledge of where F<sample> is mounted in AFS):
 142
 143    % restorevol -file sample.dump -dir /tmp -extension .2009-05-17 \
 144        -mountpoint /afs/example.com/sample
 145    Restoring volume dump of 'sample' to directory '/tmp/sample.2009-05-17'
 146
 147 =head1 PRIVILEGE REQUIRED
 148
 149 The issuer must have read access to the dump file and write access to the
 150 directory into which the dump is restored.  If the B<-mountpoint> flag is
 151 given, the issuer must also have read access to that directory.
 152
 153 =head1 SEE ALSO
 154
 155 L<salvager(8)>,
 156 L<voldump(8)>,
 157 L<vos_dump(1)>,
 158 L<vos_restore(1)>
 159
 160 =head1 COPYRIGHT
 161
 162 Copyright 2009 Steven Jenkins <steven@endpoint.com>
 163
 164 This documentation is covered by the BSD License as written in the
 165 doc/LICENSE file. This man page was written by Steven Jenkins for
 166 OpenAFS.