RESTOREVOL(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💅 restorevol — the manual page, but make it make sense

okay bestie, welcome to restorevol(1), from the AFS Command Reference ✨

🌸 NAME 🌸

restorevol — restore a volume from vos dump straight onto your local file system 🫶

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

so basically 💅 restorevol takes an AFS volume in the format that vos dump produces, and restores it onto your local file system. iconic behavior.

normally the contents of a volume live inside the AFS File Server in an opaque format, and literally just copying a volume's raw data does not make it easy to read. this utility builds you a directory tree that's equivalent to what you'd see through an AFS client — but heads up, it does not preserve the AFS-specific Access Control Lists (ACLs). its main character use case is recovering data from a volume dump or backup and making it available through a filesystem that is not AFS. no cap 🔥

the dump output gets read from standard input, or from a file if you pass -file. easy.

the restore process goes like this, step by step, periodt:

  1. the dump file gets restored inside the current directory, or inside whatever you gave to -dir.
  2. inside that directory, a subdir gets created. its name is the RW volume name that was dumped. you can tack on an extension to that directory name with -extension.
  3. all mountpoints show up as symbolic links to the volume name. the path name to the volume is either the one from -mountpoint, or from -dir. symbolic links stay untouched, they're just vibing.
  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 across group and user (then AND'ed with the umask). math girlies rise 🌈
  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 — and yeah, that's expensive, because it's a whole tree search 😭
  6. if a file or directory was found in the dump but turned out to not be connected to the hierarchical tree, then it gets connected at the root of the tree as __ORPHANEDIR__.<#> or __ORPHANFILE__.<#>. orphaned but slaying, honestly.
  7. ACLs are not restored. gone. not in the building. 🙈

⚠️ CAUTIONS ⚠️

okay so listen 🫶 normally you should use vos_restore(1) instead of this command. restorevol is a tool of last resort — it's for trying to extract data out of the data structures stored in a volume dumpfile, and it 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).

💀 fr fr: last resort means LAST RESORT. you have been warned, bestie.

👑 OPTIONS 👑

  • -file dump file — specifies the volume dump file to be read and restored to the local filesystem. if you don't give this option, the volume dump gets read from standard input.
  • -dir restore dir — names the directory where the restored filesystem gets created. the current directory is the default. note that any mountpoints inside the volume will point to that same directory unless you also specify the -mountpoint option.
  • -extension name extension — by default the name of the created directory matches the RW volume name of the volume in the dump file. if you use this option, the directory name will be the RW volume name with name extension as the suffix. cute little glow-up ✨
  • -mountpoint mount point root — by default, mountpoints inside the volume being restored point to the value given by -dir. this option lets mountpoints resolve relative to another path instead. a super common use would be specifying a path under /afs as the mount point root, so mountpoints inside the restored volume get resolved through AFS.

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

  • -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. she said focus on ME 💅

🦋 EXAMPLES 🦋

the following command restores the contents of the dumpfile in sample.dump to the directory /tmp/sample.2009-05-17, but has 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'

ate. no crumbs. 🎀

🫶 PRIVILEGE REQUIRED 🫶

the issuer must have read access to the dump file and write access to the directory the dump is restored into. 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)

iykyk 💜

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.

and that's the whole page, bestie 💖 this was OpenAFS, dated 2026-07-27 — go forth and restore responsibly, mwah 🎀✨

📦 where this page comes from