| 1 | .\" Copyright (c) 1980 Regents of the University of California. |
| 2 | .\" All rights reserved. The Berkeley software License Agreement |
| 3 | .\" specifies the terms and conditions for redistribution. |
| 4 | .\" |
| 5 | .\" @(#)restore.8 6.6 (Berkeley) %G% |
| 6 | .\" |
| 7 | .TH RESTORE 8 "" |
| 8 | .UC 4 |
| 9 | .SH NAME |
| 10 | restore \- incremental file system restore |
| 11 | .SH SYNOPSIS |
| 12 | .B /etc/restore |
| 13 | key [ name ... ] |
| 14 | .SH DESCRIPTION |
| 15 | .PP |
| 16 | .I Restore |
| 17 | reads tapes dumped with the |
| 18 | .IR dump (8) |
| 19 | command. |
| 20 | Its actions are controlled by the |
| 21 | .I key |
| 22 | argument. |
| 23 | The |
| 24 | .I key |
| 25 | is a string of characters containing |
| 26 | at most one function letter and possibly |
| 27 | one or more function modifiers. |
| 28 | Other arguments to the command are file or directory |
| 29 | names specifying the files that are to be restored. |
| 30 | Unless the |
| 31 | .B h |
| 32 | key is specified (see below), |
| 33 | the appearance of a directory name refers to |
| 34 | the files and (recursively) subdirectories of that directory. |
| 35 | .PP |
| 36 | The function portion of |
| 37 | the key is specified by one of the following letters: |
| 38 | .TP 5n |
| 39 | .B r |
| 40 | The tape |
| 41 | is read and loaded into the current directory. |
| 42 | This should not be done lightly; the |
| 43 | .B r |
| 44 | key should only be used to restore |
| 45 | a complete dump tape onto a clear file system |
| 46 | or to restore an incremental dump tape after a full level zero restore. |
| 47 | Thus |
| 48 | .IP "" 5n |
| 49 | /etc/newfs /dev/rrp0g eagle |
| 50 | .br |
| 51 | /etc/mount /dev/rp0g /mnt |
| 52 | .br |
| 53 | cd /mnt |
| 54 | .br |
| 55 | restore r |
| 56 | .IP "" 5n |
| 57 | is a typical sequence to restore a complete dump. |
| 58 | Another |
| 59 | .I restore |
| 60 | can be done to get an incremental dump |
| 61 | in on top of this. |
| 62 | Note that |
| 63 | .I restore |
| 64 | leaves a file |
| 65 | .I restoresymtable |
| 66 | in the root directory to pass information between incremental |
| 67 | restore passes. |
| 68 | This file should be removed when the last incremental tape has been |
| 69 | restored. |
| 70 | .br |
| 71 | A |
| 72 | .IR dump (8) |
| 73 | followed by a |
| 74 | .IR newfs (8) |
| 75 | and a |
| 76 | .I restore |
| 77 | is used to change the size of a file system. |
| 78 | .TP 5n |
| 79 | .B R |
| 80 | .I Restore |
| 81 | requests a particular tape of a multi volume set on which to restart |
| 82 | a full restore |
| 83 | (see the |
| 84 | .B r |
| 85 | key above). |
| 86 | This allows |
| 87 | .I restore |
| 88 | to be interrupted and then restarted. |
| 89 | .TP 5n |
| 90 | .B x |
| 91 | The named files are extracted from the tape. |
| 92 | If the named file matches a directory whose contents |
| 93 | had been written onto the tape, |
| 94 | and the |
| 95 | .B h |
| 96 | key is not specified, |
| 97 | the directory is recursively extracted. |
| 98 | The owner, modification time, |
| 99 | and mode are restored (if possible). |
| 100 | If no file argument is given, |
| 101 | then the root directory is extracted, |
| 102 | which results in the entire content of the |
| 103 | tape being extracted, |
| 104 | unless the |
| 105 | .B h |
| 106 | key has been specified. |
| 107 | .TP 5n |
| 108 | .B t |
| 109 | The names of the specified files are listed if they occur |
| 110 | on the tape. |
| 111 | If no file argument is given, |
| 112 | then the root directory is listed, |
| 113 | which results in the entire content of the |
| 114 | tape being listed, |
| 115 | unless the |
| 116 | .B h |
| 117 | key has been specified. |
| 118 | Note that the |
| 119 | .B t |
| 120 | key replaces the function of the old |
| 121 | .I dumpdir |
| 122 | program. |
| 123 | .TP 5n |
| 124 | .B i |
| 125 | This mode allows interactive restoration of files from a dump tape. |
| 126 | After reading in the directory information from the tape, |
| 127 | .I restore |
| 128 | provides a shell like interface that allows the user to move |
| 129 | around the directory tree selecting files to be extracted. |
| 130 | The available commands are given below; |
| 131 | for those commands that require an argument, |
| 132 | the default is the current directory. |
| 133 | .IP "" 10n |
| 134 | .ti -5n |
| 135 | .br |
| 136 | .B ls |
| 137 | [arg] \- |
| 138 | List the current or specified directory. |
| 139 | Entries that are directories are appended with a ``/''. |
| 140 | Entries that have been marked for extraction are prepended with a ``*''. |
| 141 | If the verbose key is set the inode number of each entry is also listed. |
| 142 | .ti -5n |
| 143 | .sp |
| 144 | .B cd |
| 145 | arg \- |
| 146 | Change the current working directory to the specified argument. |
| 147 | .ti -5n |
| 148 | .sp |
| 149 | .B pwd |
| 150 | \- |
| 151 | Print the full pathname of the current working directory. |
| 152 | .ti -5n |
| 153 | .sp |
| 154 | .B add |
| 155 | [arg] \- |
| 156 | The current directory or specified argument is added to the list of |
| 157 | files to be extracted. |
| 158 | If a directory is specified, then it and all its descendents are |
| 159 | added to the extraction list |
| 160 | (unless the |
| 161 | .B h |
| 162 | key is specified on the command line). |
| 163 | Files that are on the extraction list are prepended with a ``*'' |
| 164 | when they are listed by |
| 165 | .BR ls . |
| 166 | .ti -5n |
| 167 | .sp |
| 168 | .B delete |
| 169 | [arg] \- |
| 170 | The current directory or specified argument is deleted from the list of |
| 171 | files to be extracted. |
| 172 | If a directory is specified, then it and all its descendents are |
| 173 | deleted from the extraction list |
| 174 | (unless the |
| 175 | .B h |
| 176 | key is specified on the command line). |
| 177 | The most expedient way to extract most of the files from a directory |
| 178 | is to add the directory to the extraction list and then delete |
| 179 | those files that are not needed. |
| 180 | .ti -5n |
| 181 | .sp |
| 182 | .B extract |
| 183 | \- |
| 184 | All the files that are on the extraction list are extracted |
| 185 | from the dump tape. |
| 186 | .I Restore |
| 187 | will ask which volume the user wishes to mount. |
| 188 | The fastest way to extract a few files is to |
| 189 | start with the last volume, and work towards the first volume. |
| 190 | .ti -5n |
| 191 | .sp |
| 192 | .B setmodes |
| 193 | \- |
| 194 | All the directories that have been added to the extraction list |
| 195 | have their owner, modes, and times set; |
| 196 | nothing is extracted from the tape. |
| 197 | This is useful for cleaning up after a restore has been prematurely aborted. |
| 198 | .ti -5n |
| 199 | .sp |
| 200 | .B verbose |
| 201 | \- |
| 202 | The sense of the |
| 203 | .B v |
| 204 | key is toggled. |
| 205 | When set, the verbose key causes the |
| 206 | .B ls |
| 207 | command to list the inode numbers of all entries. |
| 208 | It also causes |
| 209 | .I restore |
| 210 | to print out information about each file as it is extracted. |
| 211 | .ti -5n |
| 212 | .sp |
| 213 | .B help |
| 214 | \- |
| 215 | List a summary of the available commands. |
| 216 | .ti -5n |
| 217 | .sp |
| 218 | .B quit |
| 219 | \- |
| 220 | Restore immediately exits, |
| 221 | even if the extraction list is not empty. |
| 222 | .sp |
| 223 | .PP |
| 224 | The following characters may be used in addition to the letter |
| 225 | that selects the function desired. |
| 226 | .TP 5n |
| 227 | .B b |
| 228 | The next argument to |
| 229 | .I restore |
| 230 | is used as the block size of the tape (in kilobytes). |
| 231 | If the \fB-b\fP option is not specified, |
| 232 | .I restore |
| 233 | tries to determine the tape block size dynamically. |
| 234 | .TP 5n |
| 235 | .B f |
| 236 | The next argument to |
| 237 | .I restore |
| 238 | is used as the name of the archive instead |
| 239 | of /dev/rmt?. |
| 240 | If the name of the file is ``\-'', |
| 241 | .I restore |
| 242 | reads from standard input. |
| 243 | Thus, |
| 244 | .IR dump (8) |
| 245 | and |
| 246 | .I restore |
| 247 | can be used in a pipeline to dump and restore a file system |
| 248 | with the command |
| 249 | .IP "" 5n |
| 250 | dump 0f - /usr | (cd /mnt; restore xf -) |
| 251 | .TP 5n |
| 252 | .B v |
| 253 | Normally |
| 254 | .I restore |
| 255 | does its work silently. |
| 256 | The |
| 257 | .B v |
| 258 | (verbose) |
| 259 | key causes it to type the name of each file it treats |
| 260 | preceded by its file type. |
| 261 | .TP 5n |
| 262 | .B y |
| 263 | .I Restore |
| 264 | will not ask whether it should abort the restore if gets a tape error. |
| 265 | It will always try to skip over the bad tape block(s) and continue as |
| 266 | best it can. |
| 267 | .TP 5n |
| 268 | .B m |
| 269 | .I Restore |
| 270 | will extract by inode numbers rather than by file name. |
| 271 | This is useful if only a few files are being extracted, |
| 272 | and one wants to avoid regenerating the complete pathname |
| 273 | to the file. |
| 274 | .TP 5n |
| 275 | .B h |
| 276 | .I Restore |
| 277 | extracts the actual directory, |
| 278 | rather than the files that it references. |
| 279 | This prevents hierarchical restoration of complete subtrees |
| 280 | from the tape. |
| 281 | .TP 5n |
| 282 | .B s |
| 283 | The next argument to |
| 284 | .I restore |
| 285 | is a number which |
| 286 | selects the file on a multi-file dump tape. File numbering |
| 287 | starts at 1. |
| 288 | .SH DIAGNOSTICS |
| 289 | Complaints about bad key characters. |
| 290 | .PP |
| 291 | Complaints if it gets a read error. |
| 292 | If |
| 293 | .B y |
| 294 | has been specified, or the user responds ``y'', |
| 295 | .I restore |
| 296 | will attempt to continue the restore. |
| 297 | .PP |
| 298 | If the dump extends over more than one tape, |
| 299 | .I restore |
| 300 | will ask the user to change tapes. |
| 301 | If the |
| 302 | .B x |
| 303 | or |
| 304 | .B i |
| 305 | key has been specified, |
| 306 | .I restore |
| 307 | will also ask which volume the user wishes to mount. |
| 308 | The fastest way to extract a few files is to |
| 309 | start with the last volume, and work towards the first volume. |
| 310 | .PP |
| 311 | There are numerous consistency checks that can be listed by |
| 312 | .IR restore . |
| 313 | Most checks are self-explanatory or can ``never happen''. |
| 314 | Common errors are given below. |
| 315 | .IP "Converting to new file system format." 5n |
| 316 | .br |
| 317 | A dump tape created from the old file system has been loaded. |
| 318 | It is automatically converted to the new file system format. |
| 319 | .IP "<filename>: not found on tape" 5n |
| 320 | .br |
| 321 | The specified file name was listed in the tape directory, |
| 322 | but was not found on the tape. |
| 323 | This is caused by tape read errors while looking for the file, |
| 324 | and from using a dump tape created on an active file system. |
| 325 | .IP "expected next file <inumber>, got <inumber>" 5n |
| 326 | .br |
| 327 | A file that was not listed in the directory showed up. |
| 328 | This can occur when using a dump tape created on an active file system. |
| 329 | .IP "Incremental tape too low" 5n |
| 330 | .br |
| 331 | When doing incremental restore, |
| 332 | a tape that was written before the previous incremental tape, |
| 333 | or that has too low an incremental level has been loaded. |
| 334 | .IP "Incremental tape too high" 5n |
| 335 | .br |
| 336 | When doing incremental restore, |
| 337 | a tape that does not begin its coverage where the previous incremental |
| 338 | tape left off, |
| 339 | or that has too high an incremental level has been loaded. |
| 340 | .IP "Tape read error while restoring <filename>" 5n |
| 341 | .ti -5n |
| 342 | .br |
| 343 | Tape read error while skipping over inode <inumber> |
| 344 | .ti -5n |
| 345 | .br |
| 346 | Tape read error while trying to resynchronize |
| 347 | .br |
| 348 | A tape read error has occurred. |
| 349 | If a file name is specified, |
| 350 | then its contents are probably partially wrong. |
| 351 | If an inode is being skipped or the tape is trying to resynchronize, |
| 352 | then no extracted files have been corrupted, |
| 353 | though files may not be found on the tape. |
| 354 | .IP "resync restore, skipped <num> blocks" 5n |
| 355 | .br |
| 356 | After a tape read error, |
| 357 | .I restore |
| 358 | may have to resynchronize itself. |
| 359 | This message lists the number of blocks that were skipped over. |
| 360 | .SH FILES |
| 361 | /dev/rmt? the default tape drive |
| 362 | .br |
| 363 | /tmp/rstdir* file containing directories on the tape. |
| 364 | .br |
| 365 | /tmp/rstmode* owner, mode, and time stamps for directories. |
| 366 | .br |
| 367 | \&./restoresymtable information passed between incremental restores. |
| 368 | .SH SEE ALSO |
| 369 | rrestore(8C) dump(8), newfs(8), mount(8), mkfs(8) |
| 370 | .SH BUGS |
| 371 | .I Restore |
| 372 | can get confused when doing incremental restores from |
| 373 | dump tapes that were made on active file systems. |
| 374 | .PP |
| 375 | A level zero dump must be done after a full restore. |
| 376 | Because restore runs in user code, |
| 377 | it has no control over inode allocation; |
| 378 | thus a full restore must be done to get a new set of directories |
| 379 | reflecting the new inode numbering, |
| 380 | even though the contents of the files is unchanged. |