| 1 | .\" Copyright (c) 1985, 1991, 1993 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that the following conditions |
| 6 | .\" are met: |
| 7 | .\" 1. Redistributions of source code must retain the above copyright |
| 8 | .\" notice, this list of conditions and the following disclaimer. |
| 9 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 10 | .\" notice, this list of conditions and the following disclaimer in the |
| 11 | .\" documentation and/or other materials provided with the distribution. |
| 12 | .\" 3. All advertising materials mentioning features or use of this software |
| 13 | .\" must display the following acknowledgement: |
| 14 | .\" This product includes software developed by the University of |
| 15 | .\" California, Berkeley and its contributors. |
| 16 | .\" 4. Neither the name of the University nor the names of its contributors |
| 17 | .\" may be used to endorse or promote products derived from this software |
| 18 | .\" without specific prior written permission. |
| 19 | .\" |
| 20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| 21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| 24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 30 | .\" SUCH DAMAGE. |
| 31 | .\" |
| 32 | .\" @(#)restore.8 8.2 (Berkeley) 12/11/93 |
| 33 | .\" |
| 34 | .Dd December 11, 1993 |
| 35 | .Dt RESTORE 8 |
| 36 | .Os BSD 4 |
| 37 | .Sh NAME |
| 38 | .Nm restore |
| 39 | .Nd "restore files or file systems from backups made with dump" |
| 40 | .Sh SYNOPSIS |
| 41 | .Nm restore |
| 42 | .Ar key |
| 43 | .Op Ar name Ar ... |
| 44 | .Sh DESCRIPTION |
| 45 | The |
| 46 | .Nm restore |
| 47 | command performs the inverse function of |
| 48 | .Xr dump 8 . |
| 49 | A full backup of a file system may be restored and |
| 50 | subsequent incremental backups layered on top of it. |
| 51 | Single files and |
| 52 | directory subtrees may be restored from full or partial |
| 53 | backups. |
| 54 | .Nm Restore |
| 55 | works across a network; |
| 56 | to do this see the |
| 57 | .Fl f |
| 58 | flag described below. |
| 59 | The actions |
| 60 | of |
| 61 | .Nm restore |
| 62 | are controlled by the given |
| 63 | .Cm key , |
| 64 | which |
| 65 | is a string of characters containing |
| 66 | at most one function letter and possibly |
| 67 | one or more function modifiers. |
| 68 | Other arguments to the command are file or directory |
| 69 | names specifying the files that are to be restored. |
| 70 | Unless the |
| 71 | .Cm h |
| 72 | key is specified (see below), |
| 73 | the appearance of a directory name refers to |
| 74 | the files and (recursively) subdirectories of that directory. |
| 75 | .Pp |
| 76 | The function portion of |
| 77 | the key is specified by one of the following letters: |
| 78 | .Bl -tag -width Ds |
| 79 | .It Cm r |
| 80 | Restore (rebuild a file system). |
| 81 | The target file system should be made pristine with |
| 82 | .Xr newfs 8 , |
| 83 | mounted and the |
| 84 | user |
| 85 | .Xr cd Ns 'd |
| 86 | into the pristine file system |
| 87 | before starting the restoration of the initial level 0 backup. If the |
| 88 | level 0 restores successfully, the |
| 89 | .Cm r |
| 90 | key may be used to restore |
| 91 | any necessary incremental backups on top of the level 0. |
| 92 | The |
| 93 | .Cm r |
| 94 | key precludes an interactive file extraction and can be |
| 95 | detrimental to one's health if not used carefully (not to mention |
| 96 | the disk). An example: |
| 97 | .Bd -literal -offset indent |
| 98 | newfs /dev/rrp0g eagle |
| 99 | mount /dev/rp0g /mnt |
| 100 | cd /mnt |
| 101 | |
| 102 | restore rf /dev/rst8 |
| 103 | .Ed |
| 104 | .Pp |
| 105 | Note that |
| 106 | .Nm restore |
| 107 | leaves a file |
| 108 | .Pa restoresymtable |
| 109 | in the root directory to pass information between incremental |
| 110 | restore passes. |
| 111 | This file should be removed when the last incremental has been |
| 112 | restored. |
| 113 | .Pp |
| 114 | .Nm Restore , |
| 115 | in conjunction with |
| 116 | .Xr newfs 8 |
| 117 | and |
| 118 | .Xr dump 8 , |
| 119 | may be used to modify file system parameters |
| 120 | such as size or block size. |
| 121 | .It Cm R |
| 122 | .Nm Restore |
| 123 | requests a particular tape of a multi volume set on which to restart |
| 124 | a full restore |
| 125 | (see the |
| 126 | .Cm r |
| 127 | key above). |
| 128 | This is useful if the restore has been interrupted. |
| 129 | .It Cm x |
| 130 | The named files are read from the given media. |
| 131 | If a named file matches a directory whose contents |
| 132 | are on the backup |
| 133 | and the |
| 134 | .Cm h |
| 135 | key is not specified, |
| 136 | the directory is recursively extracted. |
| 137 | The owner, modification time, |
| 138 | and mode are restored (if possible). |
| 139 | If no file argument is given, |
| 140 | then the root directory is extracted, |
| 141 | which results in the entire content of the |
| 142 | backup being extracted, |
| 143 | unless the |
| 144 | .Cm h |
| 145 | key has been specified. |
| 146 | .It Cm t |
| 147 | The names of the specified files are listed if they occur |
| 148 | on the backup. |
| 149 | If no file argument is given, |
| 150 | then the root directory is listed, |
| 151 | which results in the entire content of the |
| 152 | backup being listed, |
| 153 | unless the |
| 154 | .Cm h |
| 155 | key has been specified. |
| 156 | Note that the |
| 157 | .Cm t |
| 158 | key replaces the function of the old |
| 159 | .Xr dumpdir 8 |
| 160 | program. |
| 161 | .It Cm i |
| 162 | This mode allows interactive restoration of files from a dump. |
| 163 | After reading in the directory information from the dump, |
| 164 | .Nm restore |
| 165 | provides a shell like interface that allows the user to move |
| 166 | around the directory tree selecting files to be extracted. |
| 167 | The available commands are given below; |
| 168 | for those commands that require an argument, |
| 169 | the default is the current directory. |
| 170 | .Bl -tag -width Fl |
| 171 | .It Ic add Op Ar arg |
| 172 | The current directory or specified argument is added to the list of |
| 173 | files to be extracted. |
| 174 | If a directory is specified, then it and all its descendents are |
| 175 | added to the extraction list |
| 176 | (unless the |
| 177 | .Cm h |
| 178 | key is specified on the command line). |
| 179 | Files that are on the extraction list are prepended with a ``*'' |
| 180 | when they are listed by |
| 181 | .Ic ls . |
| 182 | .It Ic \&cd Ar arg |
| 183 | Change the current working directory to the specified argument. |
| 184 | .It Ic delete Op Ar arg |
| 185 | The current directory or specified argument is deleted from the list of |
| 186 | files to be extracted. |
| 187 | If a directory is specified, then it and all its descendents are |
| 188 | deleted from the extraction list |
| 189 | (unless the |
| 190 | .Cm h |
| 191 | key is specified on the command line). |
| 192 | The most expedient way to extract most of the files from a directory |
| 193 | is to add the directory to the extraction list and then delete |
| 194 | those files that are not needed. |
| 195 | .It Ic extract |
| 196 | All the files that are on the extraction list are extracted |
| 197 | from the dump. |
| 198 | .Nm Restore |
| 199 | will ask which volume the user wishes to mount. |
| 200 | The fastest way to extract a few files is to |
| 201 | start with the last volume, and work towards the first volume. |
| 202 | .It Ic help |
| 203 | List a summary of the available commands. |
| 204 | .It Ic \&ls Op Ar arg |
| 205 | List the current or specified directory. |
| 206 | Entries that are directories are appended with a ``/''. |
| 207 | Entries that have been marked for extraction are prepended with a ``*''. |
| 208 | If the verbose key is set the inode number of each entry is also listed. |
| 209 | .It Ic pwd |
| 210 | Print the full pathname of the current working directory. |
| 211 | .It Ic quit |
| 212 | Restore immediately exits, |
| 213 | even if the extraction list is not empty. |
| 214 | .It Ic setmodes |
| 215 | All the directories that have been added to the extraction list |
| 216 | have their owner, modes, and times set; |
| 217 | nothing is extracted from the dump. |
| 218 | This is useful for cleaning up after a restore has been prematurely aborted. |
| 219 | .It Ic verbose |
| 220 | The sense of the |
| 221 | .Cm v |
| 222 | key is toggled. |
| 223 | When set, the verbose key causes the |
| 224 | .Ic ls |
| 225 | command to list the inode numbers of all entries. |
| 226 | It also causes |
| 227 | .Nm restore |
| 228 | to print out information about each file as it is extracted. |
| 229 | .El |
| 230 | .El |
| 231 | .Pp |
| 232 | The following characters may be used in addition to the letter |
| 233 | that selects the function desired. |
| 234 | .Bl -tag -width Ds |
| 235 | .It Cm b |
| 236 | The next argument to |
| 237 | .Nm restore |
| 238 | is used as the block size of the media (in kilobytes). |
| 239 | If the |
| 240 | .Fl b |
| 241 | option is not specified, |
| 242 | .Nm restore |
| 243 | tries to determine the media block size dynamically. |
| 244 | .It Cm f |
| 245 | The next argument to |
| 246 | .Nm restore |
| 247 | is used as the name of the archive instead |
| 248 | of |
| 249 | .Pa /dev/rmt? . |
| 250 | If the name of the file is of the form |
| 251 | .Dq host:file , |
| 252 | .Nm restore |
| 253 | reads from the named file on the remote host using |
| 254 | .Xr rmt 8 . |
| 255 | If the name of the file is |
| 256 | .Ql Fl , |
| 257 | .Nm restore |
| 258 | reads from standard input. |
| 259 | Thus, |
| 260 | .Xr dump 8 |
| 261 | and |
| 262 | .Nm restore |
| 263 | can be used in a pipeline to dump and restore a file system |
| 264 | with the command |
| 265 | .Bd -literal -offset indent |
| 266 | dump 0f - /usr | (cd /mnt; restore xf -) |
| 267 | .Ed |
| 268 | .Pp |
| 269 | .It Cm h |
| 270 | .Nm Restore |
| 271 | extracts the actual directory, |
| 272 | rather than the files that it references. |
| 273 | This prevents hierarchical restoration of complete subtrees |
| 274 | from the dump. |
| 275 | .It Cm m |
| 276 | .Nm Restore |
| 277 | will extract by inode numbers rather than by file name. |
| 278 | This is useful if only a few files are being extracted, |
| 279 | and one wants to avoid regenerating the complete pathname |
| 280 | to the file. |
| 281 | .It Cm s |
| 282 | The next argument to |
| 283 | .Nm restore |
| 284 | is a number which |
| 285 | selects the file on a multi-file dump tape. File numbering |
| 286 | starts at 1. |
| 287 | .It Cm v |
| 288 | Normally |
| 289 | .Nm restore |
| 290 | does its work silently. |
| 291 | The |
| 292 | .Cm v |
| 293 | (verbose) |
| 294 | key causes it to type the name of each file it treats |
| 295 | preceded by its file type. |
| 296 | .It Cm y |
| 297 | .Nm Restore |
| 298 | will not ask whether it should abort the restore if it gets an error. |
| 299 | It will always try to skip over the bad block(s) and continue as |
| 300 | best it can. |
| 301 | .El |
| 302 | .Sh DIAGNOSTICS |
| 303 | Complaints about bad key characters. |
| 304 | .Pp |
| 305 | Complaints if it gets a read error. |
| 306 | If |
| 307 | .Cm y |
| 308 | has been specified, or the user responds |
| 309 | .Ql y , |
| 310 | .Nm restore |
| 311 | will attempt to continue the restore. |
| 312 | .Pp |
| 313 | If a backup was made using more than one tape volume, |
| 314 | .Nm restore |
| 315 | will notify the user when it is time to mount the next volume. |
| 316 | If the |
| 317 | .Cm x |
| 318 | or |
| 319 | .Cm i |
| 320 | key has been specified, |
| 321 | .Nm restore |
| 322 | will also ask which volume the user wishes to mount. |
| 323 | The fastest way to extract a few files is to |
| 324 | start with the last volume, and work towards the first volume. |
| 325 | .Pp |
| 326 | There are numerous consistency checks that can be listed by |
| 327 | .Nm restore . |
| 328 | Most checks are self-explanatory or can ``never happen''. |
| 329 | Common errors are given below. |
| 330 | .Pp |
| 331 | .Bl -tag -width Ds -compact |
| 332 | .It Converting to new file system format. |
| 333 | A dump tape created from the old file system has been loaded. |
| 334 | It is automatically converted to the new file system format. |
| 335 | .Pp |
| 336 | .It <filename>: not found on tape |
| 337 | The specified file name was listed in the tape directory, |
| 338 | but was not found on the tape. |
| 339 | This is caused by tape read errors while looking for the file, |
| 340 | and from using a dump tape created on an active file system. |
| 341 | .Pp |
| 342 | .It expected next file <inumber>, got <inumber> |
| 343 | A file that was not listed in the directory showed up. |
| 344 | This can occur when using a dump created on an active file system. |
| 345 | .Pp |
| 346 | .It Incremental dump too low |
| 347 | When doing incremental restore, |
| 348 | a dump that was written before the previous incremental dump, |
| 349 | or that has too low an incremental level has been loaded. |
| 350 | .Pp |
| 351 | .It Incremental dump too high |
| 352 | When doing incremental restore, |
| 353 | a dump that does not begin its coverage where the previous incremental |
| 354 | dump left off, |
| 355 | or that has too high an incremental level has been loaded. |
| 356 | .Pp |
| 357 | .It Tape read error while restoring <filename> |
| 358 | .It Tape read error while skipping over inode <inumber> |
| 359 | .It Tape read error while trying to resynchronize |
| 360 | A tape (or other media) read error has occurred. |
| 361 | If a file name is specified, |
| 362 | then its contents are probably partially wrong. |
| 363 | If an inode is being skipped or the tape is trying to resynchronize, |
| 364 | then no extracted files have been corrupted, |
| 365 | though files may not be found on the tape. |
| 366 | .Pp |
| 367 | .It resync restore, skipped <num> blocks |
| 368 | After a dump read error, |
| 369 | .Nm restore |
| 370 | may have to resynchronize itself. |
| 371 | This message lists the number of blocks that were skipped over. |
| 372 | .El |
| 373 | .Sh FILES |
| 374 | .Bl -tag -width "./restoresymtable" -compact |
| 375 | .It Pa /dev/rmt? |
| 376 | the default tape drive |
| 377 | .It Pa /tmp/rstdir* |
| 378 | file containing directories on the tape. |
| 379 | .It Pa /tmp/rstmode* |
| 380 | owner, mode, and time stamps for directories. |
| 381 | .It Pa \&./restoresymtable |
| 382 | information passed between incremental restores. |
| 383 | .El |
| 384 | .Sh SEE ALSO |
| 385 | .Xr dump 8 , |
| 386 | .Xr newfs 8 , |
| 387 | .Xr mount 8 , |
| 388 | .Xr mkfs 8 , |
| 389 | .Xr rmt 8 |
| 390 | .Sh BUGS |
| 391 | .Nm Restore |
| 392 | can get confused when doing incremental restores from |
| 393 | dump that were made on active file systems. |
| 394 | .Pp |
| 395 | A level zero dump must be done after a full restore. |
| 396 | Because restore runs in user code, |
| 397 | it has no control over inode allocation; |
| 398 | thus a full restore must be done to get a new set of directories |
| 399 | reflecting the new inode numbering, |
| 400 | even though the contents of the files is unchanged. |
| 401 | .Sh HISTORY |
| 402 | The |
| 403 | .Nm restore |
| 404 | command appeared in |
| 405 | .Bx 4.2 . |