Dumping and Restoring Volumes

Dumping and Restoring Volumes
	Chapter 5. Managing Volumes

Dumping a volume with the vos dump command converts its contents into ASCII format and writes them to the file you specify. The vos restore command places a dump file's contents into a volume after converting them into the volume format appropriate for the indicated file server machine.

About Dumping Volumes

Dumping a volume can be useful in several situations, including the following:

You want to back it up to tape, perhaps by using a third-party backup utility. To facilitate this type of backup operation, the vos dump command can write to a named pipe. To learn about using the AFS Backup System instead, see Configuring the AFS Backup Systemand Backing Up and Restoring AFS Data.
You are removing the volume from your cell (perhaps because its owner is leaving your cell). The vos dump command enables you to create a copy for safekeeping without incurring the overhead of the Backup System. For complete instructions on removing a volume, see Removing Volumes and their Mount Points.
You want to create a copy of the volume for safekeeping on a non-AFS server partition, perhaps while you move the actual volume to another machine or perform maintenance tasks on the partition that houses the volume.
You need to replace a corrupted read/write volume. If an uncorrupted read-only or backup version of the volume exists, dump it and restore the data into the read/write volume, overwriting the corrupted contents.
You want to copy or transfer the contents of the volume to another cell. You cannot use the vos move command, because AFS supports volume moves only between file server machines that belong to the same cell.
You want to have another read/write copy of the volume's contents. The second volume must have a different name than the original one. If you want the contents of the two volumes to remain identical, you must update them both manually. AFS provides no facility for keeping read/write volumes synchronized in this way.
You want a copy of only the files and directories in the volume with modification time stamps after a certain date. The vos dump command can create an incremental dump file as described in Step 3of the following instructions.

You can use the vos dump command to create a full dump, which contains the complete contents of the volume at the time you issue the command, or an incremental dump, which contains only those files and directories with modification timestamps (as displayed by the ls -l command) that are later than a date and time you specify. See Step 3of the following instructions.

Dumping a volume does not change its VLDB entry or permanently affect its status on the file server machine, but the volume's contents are inaccessible during the dump operation. To avoid interrupting access to the volume, it is generally best to dump the volume's backup version, just after using the vos backup or vos backupsys command to create a new backup version.

If you do not provide a filename into which to write the dump, the vos dump command directs the output to the standard output stream. You can pipe it directly to the vos restore command if you wish.

Because a volume dump file is in ASCII format, you can read its contents using a text editor or a command such as the cat command. However, dump files sometimes contain special characters that do not have alphanumeric correlates, which can cause problems for some display programs.

By default, the vos command interpreter consults the Volume Location Database (VLDB) to learn the volume's location, so the -server and -partition arguments are not required. If the -id argument identifies a read-only volume that resides at multiple sites, then the command dumps the version from just one of them (normally, the one listed first in the volume's VLDB entry as reported by the vos examine or vos listvldb command). To dump the read-only volume from a particular site, use the -server and -partition arguments to specify the site. To bypass the VLDB lookup entirely, provide a volume ID number (rather than a volume name) as the value for the -id argument, along with the -server and -partition arguments. This makes it possible to dump a volume for which there is no VLDB entry.

To dump a volume

Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Verify that you have the permissions necessary to create the dump file. If placing it in AFS, you must have the i( insert) permission on the ACL of the file's directory. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.
```
   % fs listacl [<dir/file path>]
```
Members of the system:administrators group always implicitly have the a( administer) and by default also the l( lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.
Issue the vos dump command to dump the volume.
```
   % vos dump -id <volume name or ID> [-time <dump from time>] [-file <arg>] [-server <server>] [-partition <partition>]
```
where
-id
Identifies the volume to be dumped by its complete name or volume ID number. If you want to dump the read-only or backup version, specify its volume ID number or add the appropriate extension ( .readonly or .backup) to the name.
To bypass the normal VLDB lookup of the volume's location, provide the volume ID number and combine this argument with the -server and -partition arguments.
-time
Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one of three acceptable values:
The value 0(zero) to create a full dump.
A date in the format mm / dd / yyyy (month, day and year) to create an incremental dump that includes only files and directories with modification timestamps later than midnight (12:00 a.m.) on the indicated date. Valid values for the year range from 1970 to 2037; higher values are not valid because the latest possible date in the standard UNIX representation is in 2038. The command interpreter automatically reduces later dates to the maximum value. An example is 01/13/1999.
A date and time in the format " mm / dd / yyyy hh : MM " to create an incremental dump that includes only files and directories with modification timestamps later than the specified date and time. The date format is the same as for a date alone. Express the time as hours and minutes (hh:MM) in 24-hour format (for example, 20:30 is 8:30 p.m.). Surround the entire expression with double quotes (" ") because it contains a space. An example is "01/13/1999 22:30".
-file
Specifies the pathname of the file to which to write the dump. The file can be in AFS, but not in the volume being dumped. A partial pathname is interpreted relative to the current working directory. Omit this argument to direct the dump to the standard output stream.
-server
Specifies the file server machine on which the volume resides. Provide the -partition argument along with this one.
-partition
Specifies the partition on which the volume resides. Provide the -server argument along with this one.

About Restoring Volumes

Although you can dump any of the three types of volumes (read/write, read-only, or backup), you can restore a dump file to the file system only as a read/write volume, using the vos restore command. The command automatically translates the dump file's contents from ASCII back into the volume format appropriate for the file server machine that stores the restored version. As with the vos dump command, you can restore a dump file via a named pipe, which facilitates interoperation with third-party backup utilities.

You can restore the contents of a dump file in one of two basic ways. In either case, you must restore a full dump of the volume before restoring any incremental dumps. Any incremental dumps that you then restore must have been created after the full dump. If there is more than one incremental dump, you must restore them in the order they were created.

You can restore volume data into a brand new volume with a new name and at a location that you specify. See To restore a dump into a new volume and mount it.
You can assign a volume ID number as you restore the volume, though it is best to have the Volume Server allocate a volume number automatically. The most common reason for specifying the volume ID is that a volume's VLDB entry has disappeared for some reason, but you know the former read/write volume ID number and want to reuse it.
You can restore volume data into an existing volume (usually the one that was previously dumped), overwriting its current contents. This is convenient if the current contents are corrupted or otherwise incorrect, because it allows you to replace them with a coherent version from the past or from one of the volume's clones. See To restore a dump file, overwriting an existing volume.
Provide the -overwrite argument to preconfirm that you wish to overwrite the volume's contents, and to specify whether you are restoring a full or incremental dump. If you omit the -overwrite argument, the Volume Server generates the following prompt to confirm that you want to overwrite the existing volume with either a full ( f) or incremental ( i) dump:
```
   Do you want to do a full/incremental restore or abort? [fia](a):
```
If you pipe in the dump file via the standard input stream instead of using the -file argument to name it, you must include the -overwrite argument because there is nowhere for the Volume Server to display the prompt in this case.
You can move the volume to a new site as you overwrite it with a full dump, by using the -server and -partition arguments to specify the new site. You cannot move the volume when restoring an incremental dump.

The vos restore command sets the restored volume's creation date in the volume header to the time of the restore operation, as reported in the Creation field in the output from the vos examine and vos listvol commands.

To restore a dump into a new volume and mount it

Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Verify that you have permissions needed to read the dump file and to mount the new volume. If the dump file resides in AFS, you need the r( read) permission on the ACL of its directory. You need the i( insert) and a( administer) permissions on the ACL of the directory where you are mounting the new volume. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.
```
   % fs listacl [<dir/file path>]
```
Members of the system:administrators group always implicitly have the a( administer) and by default also the l( lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.
Select a site (disk partition on a file server machine) for the new volume. If your cell groups different types of volumes onto different file server machines, that can guide your decision. It often makes sense to put the volume on the emptiest partition that meets your other criteria. To display how much space is available on a file server machine's partitions, use the vos partinfo command, which is described fully in Creating Read/write Volumes.
```
   % vos partinfo <machine name> [<partition name>]
```
Issue the vos restore command to create a new volume and restore the dump file into it. Type it on a single line; it appears on multiple lines here only for legibility.
```
   % vos restore <machine name> <partition name> \
                   <name of volume to be restored> \
                   [-file <dump file>] [-id <volume ID>]
```
where
res
Is the shortest acceptable abbreviation of restore.
machine name
Names the file server machine on which to create the new volume.
partition name
Names the partition on which to create the new volume.
name of volume to be restored
Names the new read/write volume, which must not already have a VLDB entry. It can be up to 22 characters in length.
-file
Is the dump file to restore. Partial pathnames are interpreted with respect to the current working directory. Omit this argument if using a pipe to read in the dump file from the standard input stream.
-volume
Specifies the new volume's ID number. It is appropriate only if you are restoring a volume that no longer exists and want to use the volume ID number it had previously.
Issue the fs mkmount command to mount the new volume, making its contents accessible. Complete instructions appear in To create a regular or read/write mount point.
```
   % fs mkmount <directory> <volume name>
```
(Optional) Issue the fs lsmount command to verify that the mount point refers to the correct volume. Complete instructions appear in To display a mount point.
```
   % fs lsmount <directory>
```

To restore a dump file, overwriting an existing volume

Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Verify that you have permissions needed to read the dump file. If it resides in AFS, you need the r( read) permission on the ACL of its directory. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.
```
   % fs listacl [<dir/file path>]
```
Members of the system:administrators group always implicitly have the a( administer) and by default also the l( lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.
Restore the contents of the dump file into a read/write volume, overwriting the current contents. The volume retains its current volume ID number. Type it on a single line; it appears on multiple lines here only for legibility.
```
   % vos restore <machine name> <partition name>  \
                 <name of volume to be restored>   \
                 [-file <dump file>] [-id <volume ID>]
```
where
res
Is the shortest acceptable abbreviation of restore.
machine name
Names the file server machine where the volume already exists, or the machine to which to move it. In the latter case, the value for the -overwrite argument must be full.
partition name
Names the partition where the volume already exists, or the partition to which to move it. In the latter case, the value for the -overwrite argument must be full.
name of volume to be restored
Names the read/write volume to overwrite with the contents of the dump file.
-file
Is the dump file to restore. Partial pathnames are interpreted with respect to the current working directory. Omit this argument if using a pipe to read in the dump file from the standard input stream; in this case, you must provide the -overwrite argument.
-overwrite
Preconfirms that you want to overwrite the existing volume and specifies which type of dump file you are restoring. Provide one of the following values:
f or full if restoring a full dump file
i or incremental if restoring an incremental dump file. This value is not acceptable if you are moving the volume while restoring it.
a to terminate the restore operation
If the volume is replicated, issue the vos release command to release the newly restored contents to read-only sites. Complete instructions appear in Replicating Volumes (Creating Read-only Volumes).
```
   % vos release <volume name or ID>
```
Issue the vos backup command to create a new backup version of the volume. Complete instructions appear in Creating Backup Volumes.
```
   % vos backup <volume name or ID>
```


Removing Volumes and their Mount Points		Renaming Volumes