1ufsrestore(1M) System Administration Commands ufsrestore(1M)
2
6 ufsrestore - incremental file system restore
7
9 /usr/sbin/ufsrestore i | r | R | t | x [abcdfhlmostvyLT]
10 [archive_file] [factor] [dumpfile] [n] [label]
11 [timeout] [filename]...
12
15 The ufsrestore utility restores files from backup media created with
16 the ufsdump command. ufsrestores's actions are controlled by the key
17 argument. The key is exactly one function letter (i, r, R , t, or x)
18 and zero or more function modifiers (letters). The key string contains
19 no SPACE characters. Function modifier arguments are listed on the com‐
20 mand line in the same order as their corresponding function modifiers
21 appear in the key string.
22 filename arguments which appear on the command line, or as arguments to
25 an interactive command, are treated as shell glob patterns by the x and
26 t functions; any files or directories matching the patterns are
27 selected. The metacharacters *, ?, and [ ] must be protected from the
28 shell if they appear on the command line. There is no way to quote
29 these metacharacters to explicitly match them in a filename.
30 The temporary files rstdir* and rstmode* are placed in /tmp by default.
33 If the environment variable TMPDIR is defined with a non-empty value,
34 that location is used instead of /tmp.
35
37 Function Letters
38 You must specify one (and only one) of the function letters listed
39 below. Note that i, x, and r are intended to restore files into an
40 empty directory. The R function is intended for restoring into a popu‐
41 lated directory.
42 i Interactive. After reading in the directory information from the
44 media, ufsrestore invokes a shell-like interface that allows you
45 to browse through the dump file's directory hierarchy and select
46 individual files to be extracted. Restoration has the same seman‐
47 tics as x (see below). See Interactive Commands, below, for a
48 description of available commands.
49 r Recursive. Starting with an empty directory and a level 0 dump,
52 the r function recreates the filesystem relative to the current
53 working directory, exactly as it appeared when the dump was made.
54 Information used to restore incremental dumps on top of the full
55 dump (for example, restoresymtable) is also included. Several ufs‐
56 restore runs are typical, one for each higher level of dump (0, 1,
57 ..., 9). Files that were deleted between the level 0 and a subse‐
58 quent incremental dump will not exist after the final restore. To
59 completely restore a file system, use the r function restore the
60 level 0 dump, and again for each incremental dump. Although this
61 function letter is intended for a complete restore onto a new file
62 system (one just created with newfs(1M)), if the file system con‐
63 tains files not on the backup media, they are preserved.
64 R Resume restoring. If an r-mode ufsrestore was interrupted, this
67 function prompts for the volume from which to resume restoring and
68 continues the restoration from where it was left off. Otherwise
69 identical to r.
70 t Table of contents. List each filename that appears on the media.
73 If no filename argument is given, the root directory is listed.
74 This results in a list of all files on the media, unless the h
75 function modifier is in effect. The table of contents is taken
76 from the media or from the specified archive file, when the a
77 function modifier is used. The a function modifier is mutually
78 exclusive with the x and r function letters.
79 x Extract the named files from the media. Files are restored to the
82 same relative locations that they had in the original file system.
83 If the filename argument matches a directory whose contents were
85 written onto the media, and the h modifier is not in effect, the
86 directory is recursively extracted, relative to the current direc‐
87 tory, which is expected to be empty. For each file, the owner,
88 modification time, and mode are restored (if possible).
89 If you omit the filename argument or specify ., the root directory
91 is extracted. This results in the entire tape being extracted,
92 unless the h modifier is in effect. . With the x function, exist‐
93 ing files are overwritten and ufsrestore displays the names of the
94 overwritten files. Overwriting a currently-running executable can
95 have unfortunate consequences.
96 Use the x option to restore partial file system dumps, as they are
98 (by definition) not entire file systems.
99 Function Modifiers
102 a archive_file Read the table of contents from archive_file instead
103 of the media. This function modifier can be used in
104 combination with the t, i, or x function letters,
105 making it possible to check whether files are on the
106 media without having to mount the media. When used
107 with the x and interactive (i) function letters, it
108 prompts for the volume containing the file(s) before
109 extracting them.
110 b factor Blocking factor. Specify the blocking factor for
113 tape reads. For variable length SCSI tape devices,
114 unless the data was written with the default block‐
115 ing factor, a blocking factor at least as great as
116 that used to write the tape must be used; otherwise,
117 an error will be generated. Note that a tape block
118 is 512 bytes. Refer to the man page for your spe‐
119 cific tape driver for the maximum blocking factor.
120 c Convert the contents of the media in 4.1BSD format
123 to the new ufs file system format.
124 d Debug. Turn on debugging output.
127 f dump_file Use dump_file instead of /dev/rmt/0 as the file to
130 restore from. Typically dump_file specifies a tape
131 or diskette drive. If dump_file is specified as `−',
132 ufsrestore reads from the standard input. This
133 allows ufsdump(1M) and ufsrestore to be used in a
134 pipeline to copy a file system:
135 example# ufsdump 0f − /dev/rdsk/c0t0d0s7 \
137 | (cd /home;ufsrestore xf −)
138 If the name of the file is of the form
141 machine:device, the restore is done from the speci‐
142 fied machine over the network using rmt(1M). Since
143 ufsrestore is normally run by root, the name of the
144 local machine must appear in the /.rhosts file of
145 the remote machine. If the file is specified as
146 user@machine:device, ufsrestore will attempt to exe‐
147 cute as the specified user on the remote machine.
148 The specified user must have a .rhosts file on the
149 remote machine that allows the user invoking the
150 command from the local machine to access the remote
151 machine.
152 h Extract or list the actual directory, rather than
155 the files that it references. This prevents hierar‐
156 chical restoration of complete subtrees from the
157 tape.
158 l Autoload. When the end-of-tape is reached before the
161 restore is complete, take the drive off-line and
162 wait up to two minutes (the default, see the T func‐
163 tion modifier) for the tape drive to be ready again.
164 This gives autoloading (stackloader) tape drives a
165 chance to load a new tape. If the drive is ready
166 within two minutes, continue. If it is not, prompt
167 for another tape and wait.
168 L label The label that should appear in the header of the
171 dump file. If the labels do not match, ufsrestore
172 issues a diagnostic and exits. The tape label is
173 specific to the ufsdump tape format, and bears no
174 resemblance to IBM or ANSI-standard tape labels.
175 m Extract by inode numbers rather than by filename to
178 avoid regenerating complete pathnames. Regardless of
179 where the files are located in the dump hierarchy,
180 they are restored into the current directory and
181 renamed with their inode number. This is useful if
182 only a few files are being extracted.
183 o Offline. Take the drive off-line when the restore is
186 complete or the end-of-media is reached and rewind
187 the tape, or eject the diskette. In the case of some
188 autoloading 8mm drives, the tape is removed from the
189 drive automatically.
190 s n Skip to the nth file when there are multiple dump
193 files on the same tape. For example, the command:
194 example# ufsrestore xfs /dev/rmt/0hn 5
196 would position you to the fifth file on the tape
199 when reading volume 1 of the dump. If a dump extends
200 over more than one volume, all volumes except the
201 first are assumed to start at position 0, no matter
202 what "s n" value is specified.
203 If "s n" is specified, the backup media must be at
205 BOT (beginning of tape). Otherwise, the initial
206 positioning to read the table of contents will fail,
207 as it is performed by skipping the tape forward n-1
208 files rather than by using absolute positioning.
209 This is because on some devices absolute positioning
210 is very time consuming.
211 T timeout [hms] Sets the amount of time to wait for an autoload com‐
214 mand to complete. This function modifier is ignored
215 unless the l function modifier has also been speci‐
216 fied. The default timeout period is two minutes. The
217 time units may be specified as a trailing h (hours),
218 m (minutes), or s (seconds). The default unit is
219 minutes.
220 v Verbose. ufsrestore displays the name and inode num‐
223 ber of each file it restores, preceded by its file
224 type.
225 y Do not ask whether to abort the restore in the event
228 of tape errors. ufsrestore tries to skip over the
229 bad tape block(s) and continue as best it can.
230 Interactive Commands
233 ufsrestore enters interactive mode when invoked with the i function
234 letters. Interactive commands are reminiscent of the shell. For those
235 commands that accept an argument, the default is the current directory.
236 The interactive options are:
237 add [filename] Add the named file or directory to the list of
239 files to extract. If a directory is specified,
240 add that directory and its files (recursively) to
241 the extraction list (unless the h modifier is in
242 effect).
243 cd directory Change to directory (within the dump file).
246 delete [filename] Delete the current directory, or the named file
249 or directory from the list of files to extract.
250 If a directory is specified, delete that direc‐
251 tory and all its descendents from the extraction
252 list (unless the h modifier is in effect). The
253 most expedient way to extract a majority of files
254 from a directory is to add that directory to the
255 extraction list, and then delete specific files
256 to omit.
257 extract Extract all files on the extraction list from the
260 dump media. ufsrestore asks which volume the user
261 wishes to mount. The fastest way to extract a
262 small number of files is to start with the last
263 volume and work toward the first. If "s n" is
264 given on the command line, volume 1 will automat‐
265 ically be positioned to file n when it is read.
266 help Display a summary of the available commands.
269 ls [directory] List files in directory or the current directory,
272 represented by a `.' (period). Directories are
273 appended with a `/' (slash). Entries marked for
274 extraction are prefixed with a `*' (asterisk). If
275 the verbose option is in effect, inode numbers
276 are also listed.
277 marked [directory] Like ls, except only files marked for extraction
280 are listed.
281 pager Toggle the pagination of the output from the ls
284 and marked commands. The pager used is that
285 defined by the PAGER environment variable, or
286 more(1) if that envar is not defined. The PAGER
287 envar may include white-space-separated arguments
288 for the pagination program.
289 pwd Print the full pathname of the current working
292 directory.
293 quit ufsrestore exits immediately, even if the extrac‐
296 tion list is not empty.
297 setmodes Prompts: set owner/mode for `.' (period). Type y
300 for yes to set the mode (permissions, owner,
301 times) of the current directory `.' (period) into
302 which files are being restored equal to the mode
303 of the root directory of the file system from
304 which they were dumped. Normally, this is what
305 you want when restoring a whole file system, or
306 restoring individual files into the same loca‐
307 tions from which they were dumped. Type n for no,
308 to leave the mode of the current directory
309 unchanged. Normally, this is what you want when
310 restoring part of a dump to a directory other
311 than the one from which the files were dumped.
312 setpager command Sets the command to use for paginating output
315 instead of the default or that inherited from the
316 environment. The command string may include argu‐
317 ments in addition to the command itself.
318 verbose Toggle the status of the v modifier. While v is
321 in effect, the ls command lists the inode numbers
322 of all entries, and ufsrestore displays informa‐
323 tion about each file as it is extracted.
324 what Display the dump header on the media.
327
330 The following operands are supported.
331 filename Specifies the pathname of files (or directories) to be
333 restored to disk. Unless the h function modifier is also
334 used, a directory name refers to the files it contains, and
335 (recursively) its subdirectories and the files they con‐
336 tain. filename is associated with either the x or t func‐
337 tion letters, and must come last.
338
341 See largefile(5) for the description of the behavior of ufsrestore when
342 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
343
345 The following exit values are returned:
346 0 Successful completion.
348 1 An error occurred. Verbose messages are displayed.
351
354 PAGER The command to use as a filter for paginating output. This
355 can also be used to specify the options to be used. Default
356 is more(1).
357 TMPDIR Selects the directory for temporary files. Defaults to /tmp
360 if not defined in the environment.
361
364 /dev/rmt/0 the default tape drive
365 $TMPDIR/rstdir* file containing directories on the tape
368 $TMPDIR/rstmode* owner, mode, and timestamps for directories
371 ./restoresymtable information passed between incremental restores
374
377 See attributes(5) for descriptions of the following attributes:
378 ┌─────────────────────────────┬─────────────────────────────┐
383 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
384 ├─────────────────────────────┼─────────────────────────────┤
385 │Availability │SUNWcsu │
386 └─────────────────────────────┴─────────────────────────────┘
387
389 more(1), mkfs(1M), mount(1M), rmt(1M), ufsdump(1M), ufsdump(4),
390 attributes(5), largefile(5)
391
393 ufsrestore complains about bad option characters.
394 Read errors result in complaints. If y has been specified, or the user
397 responds y, ufsrestore will attempt to continue.
398 If the dump extends over more than one tape, ufsrestore asks the user
401 to change tapes. If the x or i function letter has been specified, ufs‐
402 restore also asks which volume the user wishes to mount. If the s modi‐
403 fier has been specified, and volume 1 is mounted, it is automatically
404 positioned to the indicated file.
405 There are numerous consistency checks that can be listed by ufsrestore.
408 Most checks are self-explanatory or can "never happen". Common errors
409 are given below.
410 Converting to new file system format
412 A dump tape created from the old file system has been loaded. It is
414 automatically converted to the new file system format.
415 filename: not found on tape
418 The specified file name was listed in the tape directory, but was
420 not found on the tape. This is caused by tape read errors while
421 looking for the file, using a dump tape created on an active file
422 system, or restoring a partial dump with the r function.
423 expected next file inumber, got inumber
426 A file that was not listed in the directory showed up. This can
428 occur when using a dump tape created on an active file system.
429 Incremental tape too low
432 When doing an incremental restore, a tape that was written before
434 the previous incremental tape, or that has too low an incremental
435 level has been loaded.
436 Incremental tape too high
439 When doing incremental restore, a tape that does not begin its cov‐
441 erage where the previous incremental tape left off, or one that has
442 too high an incremental level has been loaded.
443 media read error: invalid argument
446 Blocking factor specified for read is smaller than the blocking
448 factor used to write data.
449 Tape read error while restoring
452 Tape read error while skipping over inode inumber
453 Tape read error while trying to resynchronize
454 A tape read error has occurred
455 If a file name is specified, then its contents are probably par‐
457 tially wrong. If an inode is being skipped or the tape is trying to
458 resynchronize, then no extracted files have been corrupted, though
459 files may not be found on the tape.
460 resync ufsrestore, skipped num
463 After a tape read error, ufsrestore may have to resynchronize
465 itself. This message lists the number of blocks that were skipped
466 over.
467 Incorrect tape label. Expected `foo', got `bar'.
470 The L option was specified, and its value did not match what was
472 recorded in the header of the dump file.
473
476 ufsrestore can get confused when doing incremental restores from dump
477 tapes that were made on active file systems.
478 A level 0 dump must be done after a full restore. Because ufsrestore
481 runs in user mode, it has no control over inode allocation. This means
482 that ufsrestore repositions the files, although it does not change
483 their contents. Thus, a full dump must be done to get a new set of
484 directories reflecting the new file positions, so that later incremen‐
485 tal dumps will be correct.
486SunOS 5.11 24 Sep 2002 ufsrestore(1M)