test

System Administration Guide, Volume I

Chapter 36 The ufsdump and ufsrestore Commands (Reference)

This chapter contains reference information on the ufsdump and ufsrestore commands.

This is a list of reference information in this chapter.

How ufsdump Works

The ufsdump command makes two passes when backing up a file system. On the first pass, it scans the raw device file for the file system and builds a table of directories and files in memory. It then writes the table to the backup media. In the second pass, ufsdump goes through the inodes in numerical order, reading the file contents and writing the data to the media.

Determining Device Characteristics

The ufsdump command needs to know only an appropriate block size and how to detect the end of media.

Detecting the End of Media

ufsdump writes a sequence of fixed-size records. When ufsdump receives notification that a record was only partially written, it assumes that it has reached the physical end of the media. This method works for most devices. If a device is not able to notify ufsdump that only a partial record has been written, a media error occurs as ufsdump tries to write.

Note -

DAT devices and 8mm tape devices detect end-of-media. Cartridge tape devices and 1/2-inch tape devices do not detect end-of-media.

Copying Data

The ufsdump command copies data only from the raw disk slice. If the file system is still active, anything in memory buffers is probably not copied. The backup done by ufsdump does not copy free blocks, nor does it make an image of the disk slice. If symbolic links point to files on other slices, the link itself is copied.

The Role of the /etc/dumpdates File

The ufsdump command, when used with the -u option, maintains and updates the /etc/dumpdates file. Each line in /etc/dumpdates shows the file system backed up, the level of the last backup, and the day, date, and time of the backup. Here is a typical /etc/dumpdates file from a file server: 


/dev/rdsk/c0t3d0s0               0 Tue Jun  9 14:30:16 1998
/dev/rdsk/c0t3d0s0               9 Tue Jun  9 11:04:41 1998
/dev/rdsk/c0t3d0s7               0 Tue Jun  9 13:54:27 1998

When you do an incremental backup, the ufsdump command consults /etc/dumpdates to find the date of the most recent backup of the next lower level. Then it copies to the media all files that were modified since the date of that lower-level backup. After the backup is complete, a new information line, describing the backup you just completed, replaces the information line for the previous backup at that level.

Use the /etc/dumpdates file to verify that backups are being done. This verification is particularly important if you are having equipment problems. If a backup cannot be completed because of equipment failure, the backup is not recorded in the /etc/dumpdates file.

If you need to restore an entire disk, check the /etc/dumpdates file for a list of the most recent dates and levels of backups so that you can determine which tapes you need to restore the entire file system.

Note -

The /etc/dumpdates file is a text file that can be edited, but edit it only at your own risk. If you make changes to the file that do not match your archive tapes, you may not be able to find the tapes (or files) you need.

Backup Device (dump-file) Argument

The dump-file argument (to the -f option) specifies the destination of the backup, which can be one of the following:

Use this argument when the destination is not the default local tape drive /dev/rmt/0. If you use the -f option, then you must specify a value for dump-file.

Note -

The dump-file argument can also point to a file on a local or remote disk, which, if used by mistake, can fill up a file system.

Local Tape or Diskette Drive

Typically, dump-file specifies a raw device file for a tape or diskette drive. When ufsdump writes to an output device, it creates a single backup file which may span multiple tapes or diskettes.

You specify the tape or diskette device on your system using a device abbreviation. The first device is always 0. For example, if you have a SCSI tape controller and one QIC-24 tape drive that uses medium-density formatting, use this device name:

/dev/rmt/0m

When you specify a tape device name, you can also type the letter "n" at the end of the name to indicate that the tape drive should not rewind after the backup is completed. For example:

/dev/rmt/0mn

Use the "no-rewind" option if you want to put more than one file onto the tape. If you run out of space during a backup, the tape does not rewind before ufsdump asks for a new tape. See "Backup Device Names" for a complete description of device naming conventions.

Remote Tape or Diskette Drive

You specify a remote tape or diskette drive using the syntax host:device. ufsdump writes to the remote device when root on the local system has access to the remote system. If you usually run ufsdump as root, the name of the local system must be included in the /.rhosts file on the remote system. If you specify the device as user@host:device, ufsdump tries to access the device on the remote system as the specified user. In this case, the specified user must be included in the /.rhosts file on the remote system.

Use the naming convention for the device that matches the operating system for the system on which the device resides, not the system from which you run the ufsdump command. If the drive is on a system that is running a previous SunOS release (for example, 4.1.1), use the SunOS 4.1 device name (for example, /dev/rst0). If the system is running Solaris software, use the SunOS 5.7 convention (for example, /dev/rmt/0).

Note -

You must specify remote devices explicitly with the dump-file argument. In previous SunOS releases, the rdump command directed the output to the remote device defined by the dumphost alias. ufsdump does not have an rufsdump counterpart.

Standard Output

When you specify a dash (-) as the dump-file argument, ufsdump writes to the standard output.

Note -

The -v option (verify) does not work when the dump-file argument is standard output.

You can use the ufsdump and ufsrestore commands in a pipeline to copy a file system by writing to the standard output with ufsdump and reading from the standard input with ufsrestore, as shown in this example:


# ufsdump 0f - /dev/rdsk/c0t0d0s7 | (cd /home; ufsrestore xf -)

Specifying Files to Back Up

You must always include files-to-backup as the last argument on the command line. This argument specifies the source or contents of the backup. It usually identifies a file system but can also identify individual files or directories.

For a file system, specify the raw device file for a disk slice. It includes the disk controller abbreviation (c), the target number (t) for SCSI devices only, a number indicating the disk number (d), and the slice number (s). For example, if you have a SCSI disk controller on your standalone system (or server) and you want to back up /usr located in slice 6, specify the device as follows:

/dev/rdsk/c0t0d0s6

You can specify the file system by its mount point directory (for example, /home), as long as there is an entry for it in the /etc/vfstab file.

See "Backup Device Names" for a complete description of device naming conventions.

For individual files or directories, type one or more names separated by spaces.

Note -

When you use ufsdump to back up one or more directories or files (rather than a whole file system), a level 0 backup is done. Incremental backups do not apply.

End-of-Media Detection

The ufsdump command automatically detects the end-of-media for most devices. Therefore, you do not usually need to use the -c, -d, -s, and -t options to perform multivolume backups.

The only time you need to use the end-of-media options is when ufsdump does not understand the way the device detects the end-of-media or you are going to restore the files on a system with an older version of the restore command. To ensure compatibility with older versions of the restore command, the size option can still force ufsdump to go to the next tape or diskette before reaching the end of the current tape or diskette.

Specifying Tape Characteristics

If you do not specify any tape characteristics, the ufsdump command uses a set of defaults. You can specify tape cartridge (c), density (d), size (s), and number of tracks (t). Note that you can specify the options in any order as long as the arguments that follow match the order of the options.

Limitations of the ufsdump Command

Table 36-1 lists tasks you cannot perform with the ufsdump command.

Table 36-1 Tasks You Cannot Perform With the ufsdump Command

The ufsdump Command Does Not ...

Comments 

Automatically calculate the number of tapes or diskettes needed for backing up file systems 

You can use the dry run mode (S option) to determine the amount of space that is needed before actually backing up file systems. 

Provide built-in error checking to minimize problems when backing up an active file system 

-- 

Enable you to back up files that are remotely mounted from a server 

Files on the server must be backed up on the server itself. Users are denied permission to run ufsdump on files they own that are located on a server.

Options and Arguments for the ufsdump Command

This section describes in detail the options and arguments for the ufsdump command. The syntax for the ufsdump command is:


/usr/sbin/ufsdump [options] [arguments] files-to-back-up

options

Is a single string of one-letter option names. 

arguments

Identifies option arguments and may be multiple strings. The option letters and the arguments that go with them must be in the same order  

files-to-back-up

Identifies the files to back up and these arguments must always come last. 

Default Command Options

If you run the ufsdump command without any options, use this syntax:


# ufsdump files-to-back-up

ufsdump uses these options, by default:


ufsdump 9uf /dev/rmt/0 files-to-back-up

These options do a level 9 incremental backup to the default tape drive at its preferred density.

Options for the ufsdump Command

Table 36-2 describes the options for the ufsdump command.

Table 36-2 Options for the ufsdump Command

Option 

Description 

0-9

Backup level. Level 0 is for a full backup of the whole file system specified by files-to-backup. Levels 1-9 are for incremental backups of files that have changed since the last lower-level backup.

a archive-file

Archive file. Store (archive) a backup table of contents in a specified file on the disk. The file can be understood only by ufsrestore, which uses it to determine whether a file to be restored is present in a backup file, and if so, on which volume of the media it resides.

b factor

Blocking factor. The number of 512-byte blocks to write to tape at a time. 

c

Cartridge. Back up to cartridge tape. When end-of-media detection applies, this option sets the block size to 126. 

d bpi

Tape density. You need to use this option only when ufsdump cannot detect the end of the media.

D

Diskette. Back up to diskette. 

f dump-file

Dump file. Write the files to the destination specified by dump-file instead of the default device. If the file is specified as user@system:device, ufsdump attempts to execute as the specified user on the remote system. The specified user must have a /.rhosts file on the remote system that allows the user invoking the command on the local system to access the remote system.

l

Autoload. Use this option if you have an autoloading (stackloader) tape drive. When the end of a tape is reached, this option takes the drive offline and waits up to two minutes for the tape drive to be ready again. If the drive is ready within two minutes, it continues. If it is not ready after two minutes, it prompts the operator to load another tape. 

n

Notify. When intervention is needed, send a message to all terminals of all users in the sys group.

o

Offline. When finished with a tape or diskette, take the drive offline, rewind (if tape), and if possible remove the media (for example, eject a diskette or remove 8-mm autoloaded tape). 

s size

Size. Specify the length of tapes in feet or number of 1024-byte blocks for diskettes. You need to use this option only when ufsdump cannot detect the end of the media.

S

Estimate size of backup. Determine the amount of space that is needed to perform the backup, without actually doing it, and output a single number indicating the estimated size of the backup in bytes. 

t tracks

Tracks. Specify the number of tracks for 1/4-inch cartridge tape. You need to use this option only when ufsdump cannot detect the end of the media.

u

Update the dump record. For a completed backup on a file system, add an entry to the /etc/dumpdates file. The entry indicates the device name for the file system's disk slice, the backup level (0-9), and the date. No record is written when you do not use the u option or when you back up individual files or directories. If a record already exists for a backup at the same level, it is replaced.

v

Verify. After each tape or diskette is written, verify the contents of the media against the source file system. If any discrepancies occur, prompt the operator to mount new media, then repeat the process. Use this option on an unmounted file system only, because any activity in the file system causes it to report discrepancies. 

w

Warning. List the file systems appearing in /etc/dumpdates that have not been backed up within a day. When you use this option all other options are ignored.

W

Warning with highlight. Show all the file systems that appear in /etc/dumpdates and highlight those file systems that have not been backed up within a day. When you use this option all other options are ignored.

Note -

The /etc/vfstab file does not contain information about how often to back up a file system.

The ufsdump Command and Security Issues

If you are concerned about security:

Options and Arguments for the ufsrestore Command

Command Syntax

The syntax of the ufsrestore command is: 


ufsrestore [options][arguments][filename ...]

options

Is a single string of one-letter option names. You must choose one and only one of these options: i, r, R, t, or x.

arguments

Follows the option string with the arguments that match the options. The option names and the arguments that go with them must be in the same order. 

filename

Specifies files to be restored as arguments to the x or t options, and must always come last.

Options and Arguments

You must use one (and only one) of the ufsrestore options shown in Table 36-3.

Table 36-3 One Required Option for the ufsrestore Command

Option 

Description 

i

Interactive. Runs ufsrestore in an interactive mode. In this mode, you can use a limited set of shell-like commands to browse the contents of the media and select individual files or directories to restore. See "Commands for Interactive Restore" for a list of available commands.

r

Recursive. Restores the entire contents of the media into the current working directory (which should be the top level of the file system). Information used to restore incremental dumps on top of the full dump (e.g., restoresymtable) is also included. To completely restore a file system, use this option to restore the full (level 0) dump and each subsequent incremental dump. Although intended for a new file system (one just created with the newfs command), files not on the backup media are preserved.

R

Resume restoring. Prompts for the volume from which to resume restoring and restarts from a checkpoint. You rerun the ufsrestore command with this option after a full restore (r option) is interrupted.

x [filename...]

 

Extract. Selectively restores the files you specify by the filename argument. filename can be a list of files and directories. All files under a specified directory are restored unless you also use the h option also. If you omit filename or enter "." for the root directory, all files on all volumes of the media (or from standard input) are restored. Existing files are overwritten, and warnings are displayed.

t [filename...]

Table of contents. Checks the files specified in the filename argument against the media. For each file, lists the full file name and the inode number (if the file is found) or indicates the file is not on the "volume" (meaning any volume in a multivolume dump). If you do not enter the filename argument, all files on all volumes of the media are listed (without distinguishing on which volume files are located). If you also use the h option, only the directory files specified in filename, not their contents, are checked and listed. The table of contents is read from the first volume of the media, or, if you use the a option, from the specified archive file. This option is mutually exclusive with the x and r options.

In addition to one of the options shown in Table 36-3, you can choose from the options shown in Table 36-4.

Table 36-4 Additional Options for the ufsrestore Command

Option 

Description 

a archive-file [filename...]

Takes the dump table of contents from the specified archive-file instead of from the media (first volume). You can use this option in combination with the t, i, or x options to check for the files in the dump without having to mount any media. If you use it with the x and interactive extract options, you will be prompted to mount the appropriate volume before extracting the file(s).

b factor

Blocking factor. Number of 512-byte blocks read from tape at a time. By default, ufsrestore tries to figure out the block size that was used in writing the tape.

d

Debug. Turn on debugging messages. 

f backup-file

Backup file. Reads the files from the source indicated by backup-file, instead of from the default device file /dev/rmt/0m. If you use the f option, you must specify a value for backup-file. When backup-file is of the form system:device, ufsrestore reads from the remote device. You can also use the backup-file argument to specify a file on a local or remote disk. If backup-file is `-', the files are read from standard input.

h

Turns off directory expansion. Only the directory file you specify is extracted or listed. 

m

Restores specified files into the current directory on the disk regardless of where they are located in the backup hierarchy and renames them with their inode number. For example, if the current working directory is /files, a file in the backup named ./dready/fcs/test with inode number 42, is restored as /files/42. This option is useful only when you are extracting a few files.

s n

Skips to the nth backup file on the media (first volume). This option is useful when you put more than one backup on a single tape.

v

Verbose. Displays the names and inode numbers of each file as it is restored. 

y

Continues when errors occur reading the media and tries to skip over bad blocks instead of stopping and asking whether to continue. This option tells the command to assume a yes response. 

Commands for Interactive Restore

Table 36-5 Commands for Interactive Restore

Option 

Description 

ls [directory-name]

Lists the contents of either the current directory or the specified directory. Directories are marked by a / suffix and entries in the current list to be restored (extracted) are marked by an * prefix. Inode numbers are shown if the verbose option is used.

cd directory-name

Changes to the specified directory in the backup hierarchy. 

add [filename]

Adds the current directory or the specified file or directory to the list of files to extract (restore). If you do not use the h option, all files in a specified directory and its subdirectories are added to the list. Note that all the files you want to restore to a directory might not be on a single backup tape or diskette. You might need to restore from multiple backups at different levels to get the latest revisions of all the files.

delete [filename]

Deletes the current directory or the specified file or directory from the list of files to extract (restore). If you do not use the h option, all files in the specified directory and its subdirectories are deleted from the list. Note that the files and directories are deleted only from the extract list you are building. They are not deleted from the media or the file system.

extract

Extracts the files in the list and restores them relative to the current working directory on the disk. Specify 1 when asked for a volume number for a single-volume backup. If you are doing a multitape or multidiskette restore and restoring a small number of files, start with the last tape or diskette instead.

help

Displays a list of commands you can use in interactive mode. 

pwd

Displays the path name of the current working directory in the backup hierarchy. 

q

Quits interactive mode without restoring any additional files. 

setmodes

Lets you set the mode for files to be restored to match the mode of the root directory of the file system from which they were backed up. You are prompted with: set owner/mode for '.' [yn]? Type y (for yes) to set the mode (permissions, owner, times) of the current directory to match the root directory of the file system from which they were backed up. Use this mode when restoring a whole file system. Type n (for no) to leave the mode of the current directory unchanged. Use this mode when restoring part of a backup to a directory other than the one from which the files were backed up.

verbose

Turns on or off the verbose option (which can also be entered as v on the command line outside of interactive mode). When verbose is on, the interactive ls command lists inode numbers and the ufsrestore command displays information on each file as it is extracted.

what

Displays the backup header from the tape or diskette.