From: Steven Jenkins Date: Tue, 19 May 2009 00:34:40 +0000 (+0000) Subject: STABLE14-man-page-restorevol-20090518 X-Git-Tag: openafs-stable-1_4_11pre1~40 X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=718fc313d3a3a0d84f006aae7f74caaca7a374c6;p=packages%2Fo%2Fopenafs.git STABLE14-man-page-restorevol-20090518 LICENSE IPL10 FIXES 124791 Add man page for restorevol. (cherry picked from commit 97b0d230145c4c5f58ef785b11bf2d201ded2d26) --- diff --git a/doc/man-pages/README b/doc/man-pages/README index 6fe3af95b..defc9ba05 100644 --- a/doc/man-pages/README +++ b/doc/man-pages/README @@ -234,7 +234,6 @@ Known Problems klog.krb krb.conf pagsh.krb - restorevol rmtsysd tokens.krb vsys diff --git a/doc/man-pages/pod1/vos_dump.pod b/doc/man-pages/pod1/vos_dump.pod index 8fdbc7110..2a25eeae1 100644 --- a/doc/man-pages/pod1/vos_dump.pod +++ b/doc/man-pages/pod1/vos_dump.pod @@ -187,6 +187,7 @@ to insert and write in the directory that houses the file. =head1 SEE ALSO +L, L, L, L, diff --git a/doc/man-pages/pod1/vos_restore.pod b/doc/man-pages/pod1/vos_restore.pod index e067b460c..7640f7883 100644 --- a/doc/man-pages/pod1/vos_restore.pod +++ b/doc/man-pages/pod1/vos_restore.pod @@ -221,6 +221,7 @@ logged on to a server machine as the local superuser C. =head1 SEE ALSO +L, L, L, L, diff --git a/doc/man-pages/pod8/restorevol.pod b/doc/man-pages/pod8/restorevol.pod new file mode 100644 index 000000000..03ffd8d8f --- /dev/null +++ b/doc/man-pages/pod8/restorevol.pod @@ -0,0 +1,153 @@ +=head1 NAME + +restorevol - Restore a volume from vos dump to the local file system + +=head1 SYNOPSIS + +=for html +
+ +B S<<< [B<-file> >] >>> S<<< [B<-dir> > ] >>> + S<<< [B<-extension> >] >>> + S<<< [B<-mountpoint> >] >>> + S<<< [B<-umask> >] >>> [B<-verbose>] [B<-help>] + +=for html +
+ +=head1 DESCRIPTION + +B takes an AFS volume in the format produced by B +and restores it to the local file system. Normally, the contents of a +volume are maintained by the AFS File Server in an opaque format and +copying a volume's raw data does not make it easily accessible. This +utility will produce a directory tree that is equivalent to that seen via +an AFS client, but without preserving the AFS-specific Access Control +Lists (ACLs). It's primary use is to recover data from a volume dump or +backup and make it available via a filesystem other than AFS. + +The dump output will read from standard input, or from a file if B<-file> +is specified. + +The restore process is as follows: + +=over 4 + +=item 1. + +The dump file will be restored within the current directory or that +specified with B<-dir>. + +=item 2. + +Within this directory, a subdir is created. It's name is the RW volume +name that was dumped. An extension can be appended to this directory name +with B<-extension>. + +=item 3. + +All mountpoints will appear as symbolic links to the volume name. The +path name to the volume will be either that in B<-mountpoint>, or B<-dir>. +Symbolic links remain untouched. + +=item 4. + +You can change your umask during the restore with B<-umask>. Otherwise, +B uses your current umask. Mode bits for directories are 0777 +(then AND'ed with the umask). Mode bits for files are the owner mode bits +duplicated accross group and user (then AND'ed with the umask). + +=item 5. + +For restores of full dumps, if a directory says it has a file and the file +is not found, then a symbolic link F<< AFSFile-<#> >> will appear in that +restored tree. Restores of incremental dumps remove all these files at +the end (expensive because it is a tree search). + +=item 6. + +If a file or directory was found in the dump but found not to be connected +to the hierarchical tree, then the file or directory will be connected at +the root of the tree as F<< __ORPHANEDIR__.<#> >> or F<< +__ORPHANFILE__.<#> >>. + +=item 7. + +ACLs are not restored. + +=back + +=head1 CAUTIONS + +Normally, use L instead of this command. B is +a tool of last resort to try to extract data from the data structures +stored in a volume dumpfile and is not as regularly tested or used as the +normal L implementation. Using B bypasses +checks done by the L and L. + +=head1 OPTIONS + +=over 4 + +=item B<-file> > + +Specifies the output file for the dump. If this option is not given, the +volume will be dumped to standard output. + +=item B<-dir> > + +Names the directory in which to create the restored filesystem. The +current directory is used by default. Note that any mountpoints inside +the volume will point to the same directory unless the B<-mountpoint> +option is also specified. + +=item B<-extension> > + +By default, the name of the directory created matches the RW volume name +of the volume in the dump file. If this option is used, the directory +name will be the RW volume name I as the suffix. + +=item B<-mountpoint> > + +By default, mountpoints inside the volume being restored point to the +value given by I<-dir>. This option allows mountpoints to be resolved +relative to another path. A common use for this would be to specify a +path under F as the mount point root so that mountpoints inside the +restored volume would be resolved via AFS. + +The I must exist, and the process running the command +have read access to that directory, or the command will fail. + +=back + +=head1 EXAMPLES + +The following command restores the contents of the dumpfile in +F to the directory F, but having all +mountpoints inside the volume point to AFS (note that this requires +knowledge of where F is mounted in AFS): + + % restorevol -file sample.dump -dir /tmp -extension .2009-05-17 \ + -mountpoint /afs/example.org/sample + Restoring volume dump of 'sample' to directory '/tmp/sample.2009-05-17' + +=head1 PRIVILEGE REQUIRED + +The issuer must have read access to the dump file and write access to the +directory into which the dump is restored. If the B<-mountpoint> flag is +given, the issuer must also have read access to that directory. + +=head1 SEE ALSO + +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2009 Steven Jenkins + +This documentation is covered by the BSD License as written in the +doc/LICENSE file. This man page was written by Steven Jenkins for +OpenAFS. diff --git a/doc/man-pages/pod8/voldump.pod b/doc/man-pages/pod8/voldump.pod index ebe0525d4..71d5b4aec 100644 --- a/doc/man-pages/pod8/voldump.pod +++ b/doc/man-pages/pod8/voldump.pod @@ -86,6 +86,7 @@ local superuser C on the file server machine. =head1 SEE ALSO L, +L, L, L, L