NAME

       restorevol - Restore a volume from vos dump to the local file system

SYNOPSIS

       restorevol [-file <dump file>] [-dir <restore dir> ]
           [-extension <name extension>]
           [-mountpoint <mount point root>]
           [-umask <mode mask>] [-help]

DESCRIPTION

       restorevol takes an AFS volume in the format produced by vos dump 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 -file is specified.

       The restore process is as follows:

       1.  The dump file will be restored within the current directory or that specified with -dir.

       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 -extension.

       3.  All mountpoints will appear as symbolic links to the volume name.  The path name to the  volume  will
           be either that in -mountpoint, or -dir.  Symbolic links remain untouched.

       4.  You  can  change  your umask during the restore with -umask.  Otherwise, restorevol 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).

       5.  For restores of full dumps, if a directory says it has a file and the  file  is  not  found,  then  a
           symbolic  link  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).

       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 __ORPHANEDIR__.<#> or
           __ORPHANFILE__.<#>.

       7.  ACLs are not restored.

CAUTIONS

       Normally, use vos_restore(1) instead of this command.  restorevol 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 vos_restore(1) implementation.  Using restorevol bypasses checks done by the  fileserver(8)
       and salvager(8).

OPTIONS

       -file <dump file>
           Specifies  the  volume  dump file to be read and restored to the local filesystem.  If this option is
           not given, the volume dump will be read from standard input.

       -dir <restore 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
           -mountpoint option is also specified.

       -extension <name 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 name extension as the
           suffix.

       -mountpoint <mount point root>
           By default, mountpoints inside the volume being restored point to the  value  given  by  -dir.   This
           option allows mountpoints to be resolved relative to another path.  A common use for this would be to
           specify  a  path  under  /afs  as the mount point root so that mountpoints inside the restored volume
           would be resolved via AFS.

           The mount point root must exist, and the process  running  the  command  have  read  access  to  that
           directory, or the command will fail.

       -umask <mode mask>
           Sets  the  umask  while  creating  files.  If  not  specified, the current process umask is used. All
           directories are created with mode 0777 (ANDed with the umask), and files are created with the  owner,
           group, and user mode bits set to the owner mode bits of the relevant AFS file (ANDed with the umask).

       -help
           Prints the online help for this command. All other valid options are ignored.

EXAMPLES

       The   following  command  restores  the  contents  of  the  dumpfile  in  sample.dump  to  the  directory
       /tmp/sample.2009-05-17, but having all mountpoints inside  the  volume  point  to  AFS  (note  that  this
       requires knowledge of where sample is mounted in AFS):

          % restorevol -file sample.dump -dir /tmp -extension .2009-05-17 \
              -mountpoint /afs/example.com/sample
          Restoring volume dump of 'sample' to directory '/tmp/sample.2009-05-17'

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 -mountpoint flag is given, the issuer must also have read access to that directory.

SEE ALSO

       salvager(8), voldump(8), vos_dump(1), vos_restore(1)

COPYRIGHT

       Copyright 2009 Steven Jenkins <steven@endpoint.com>

       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.

OpenAFS                                            2025-05-19                                      RESTOREVOL(1)