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.
--- 15 unchanged lines hidden (view full) ---
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.\" $Id$
34.\" "
35.Dd December 11, 1993
36.Dt RESTORE 8
37.Os BSD 4
38.Sh NAME
39.Nm restore
40.Nd "restore files or file systems from backups made with dump"
41.Sh SYNOPSIS
42.Nm restore
43.Ar key
44.Op Ar name Ar ...
45.Sh DESCRIPTION
46The
47.Nm restore
48command performs the inverse function of
49.Xr dump 8 .
50A full backup of a file system may be restored and
51subsequent incremental backups layered on top of it.
52Single files and
53directory subtrees may be restored from full or partial
54backups.
55.Nm Restore
56works across a network;
57to do this see the
58.Fl f
59flag described below.
60The actions
61of
62.Nm restore
63are controlled by the given
64.Cm key ,
65which
66is a string of characters containing
67at most one function letter and possibly
68one or more function modifiers.
69Other arguments to the command are file or directory
70names specifying the files that are to be restored.
71Unless the
72.Cm h
73key is specified (see below),
74the appearance of a directory name refers to
75the files and (recursively) subdirectories of that directory.
76.Pp
77The function portion of
78the key is specified by one of the following letters:
79.Bl -tag -width Ds
80.It Cm r
81Restore (rebuild a file system).
82The target file system should be made pristine with
83.Xr newfs 8 ,
84mounted and the
85user
86.Xr cd Ns 'd
87into the pristine file system
88before starting the restoration of the initial level 0 backup. If the
89level 0 restores successfully, the
90.Cm r
91key may be used to restore
92any necessary incremental backups on top of the level 0.
93The
94.Cm r
95key precludes an interactive file extraction and can be
96detrimental to one's health if not used carefully (not to mention
97the disk). An example:
98.Bd -literal -offset indent
99newfs /dev/rrp0g eagle
100mount /dev/rp0g /mnt
101cd /mnt
102
103restore rf /dev/rst8
104.Ed
105.Pp
106Note that
107.Nm restore
108leaves a file
109.Pa restoresymtable
110in the root directory to pass information between incremental
111restore passes.
112This file should be removed when the last incremental has been
113restored.
114.Pp
115.Nm Restore ,
116in conjunction with
117.Xr newfs 8
118and
119.Xr dump 8 ,
120may be used to modify file system parameters
121such as size or block size.
122.It Cm R
123.Nm Restore
124requests a particular tape of a multi volume set on which to restart
125a full restore
126(see the
127.Cm r
128key above).
129This is useful if the restore has been interrupted.
130.It Cm x
131The named files are read from the given media.
132If a named file matches a directory whose contents
133are on the backup
134and the
135.Cm h
136key is not specified,
137the directory is recursively extracted.
138The owner, modification time,
139and mode are restored (if possible).
140If no file argument is given,
141then the root directory is extracted,
142which results in the entire content of the
143backup being extracted,
144unless the
145.Cm h
146key has been specified.
147.It Cm t
148The names of the specified files are listed if they occur
149on the backup.
150If no file argument is given,
151then the root directory is listed,
152which results in the entire content of the
153backup being listed,
154unless the
155.Cm h
156key has been specified.
157Note that the
158.Cm t
159key replaces the function of the old
160.Xr dumpdir 8
161program.
162.It Cm i
163This mode allows interactive restoration of files from a dump.
164After reading in the directory information from the dump,
165.Nm restore
166provides a shell like interface that allows the user to move
167around the directory tree selecting files to be extracted.
168The available commands are given below;
169for those commands that require an argument,
170the default is the current directory.
171.Bl -tag -width Fl
172.It Ic add Op Ar arg
173The current directory or specified argument is added to the list of
174files to be extracted.
175If a directory is specified, then it and all its descendents are
176added to the extraction list
177(unless the
178.Cm h
179key is specified on the command line).
180Files that are on the extraction list are prepended with a ``*''
181when they are listed by
182.Ic ls .
183.It Ic \&cd Ar arg
184Change the current working directory to the specified argument.
185.It Ic delete Op Ar arg
186The current directory or specified argument is deleted from the list of
187files to be extracted.
188If a directory is specified, then it and all its descendents are
189deleted from the extraction list
190(unless the
191.Cm h
192key is specified on the command line).
193The most expedient way to extract most of the files from a directory
194is to add the directory to the extraction list and then delete
195those files that are not needed.
196.It Ic extract
197All the files that are on the extraction list are extracted
198from the dump.
199.Nm Restore
200will ask which volume the user wishes to mount.
201The fastest way to extract a few files is to
202start with the last volume, and work towards the first volume.
203.It Ic help
204List a summary of the available commands.
205.It Ic \&ls Op Ar arg
206List the current or specified directory.
207Entries that are directories are appended with a ``/''.
208Entries that have been marked for extraction are prepended with a ``*''.
209If the verbose key is set the inode number of each entry is also listed.
210.It Ic pwd
211Print the full pathname of the current working directory.
212.It Ic quit
213Restore immediately exits,
214even if the extraction list is not empty.
215.It Ic setmodes
216All the directories that have been added to the extraction list
217have their owner, modes, and times set;
218nothing is extracted from the dump.
219This is useful for cleaning up after a restore has been prematurely aborted.
220.It Ic verbose
221The sense of the
222.Cm v
223key is toggled.
224When set, the verbose key causes the
225.Ic ls
226command to list the inode numbers of all entries.
227It also causes
228.Nm restore
229to print out information about each file as it is extracted.
230.El
231.El
232.Pp
233The following characters may be used in addition to the letter
234that selects the function desired.
235.Bl -tag -width Ds
236.It Cm b
237The next argument to
238.Nm restore
239is used as the block size of the media (in kilobytes).
240If the
241.Fl b
242option is not specified,
243.Nm restore
244tries to determine the media block size dynamically.
245.It Cm f
246The next argument to
247.Nm restore
248is used as the name of the archive instead
249of
250.Pa /dev/rst0 .
251If the name of the file is of the form
252.Dq host:file ,
253.Nm restore
254reads from the named file on the remote host using
255.Xr rmt 8 .
256If the name of the file is
257.Ql Fl ,
258.Nm restore
259reads from standard input.
260Thus,
261.Xr dump 8
262and
263.Nm restore
264can be used in a pipeline to dump and restore a file system
265with the command
266.Bd -literal -offset indent
267dump 0f - /usr | (cd /mnt; restore xf -)
268.Ed
269.Pp
270.It Cm h
271.Nm Restore
272extracts the actual directory,
273rather than the files that it references.
274This prevents hierarchical restoration of complete subtrees
275from the dump.
276.It Cm m
277.Nm Restore
278will extract by inode numbers rather than by file name.
279This is useful if only a few files are being extracted,
280and one wants to avoid regenerating the complete pathname
281to the file.
282.It Cm s
283The next argument to
284.Nm restore
285is a number which
286selects the file on a multi-file dump tape. File numbering
287starts at 1.
288.It Cm v
289Normally
290.Nm restore
291does its work silently.
292The
293.Cm v
294(verbose)
295key causes it to type the name of each file it treats
296preceded by its file type.
297.It Cm y
298.Nm Restore
299will not ask whether it should abort the restore if it gets an error.
300It will always try to skip over the bad block(s) and continue as
301best it can.
302.El
303.Sh DIAGNOSTICS
304Complaints about bad key characters.
305.Pp
306Complaints if it gets a read error.
307If
308.Cm y
309has been specified, or the user responds
310.Ql y ,
311.Nm restore
312will attempt to continue the restore.
313.Pp
314If a backup was made using more than one tape volume,
315.Nm restore
316will notify the user when it is time to mount the next volume.
317If the
318.Cm x
319or
320.Cm i
321key has been specified,
322.Nm restore
323will also ask which volume the user wishes to mount.
324The fastest way to extract a few files is to
325start with the last volume, and work towards the first volume.
326.Pp
327There are numerous consistency checks that can be listed by
328.Nm restore .
329Most checks are self-explanatory or can ``never happen''.
--- 56 unchanged lines hidden (view full) ---
386.Xr dump 8 ,
387.Xr ft 8 ,
388.Xr mount 8 ,
389.Xr newfs 8 ,
390.Xr rmt 8
391.Sh BUGS
392.Nm Restore
393can get confused when doing incremental restores from
394dump that were made on active file systems.
395.Pp
396A level zero dump must be done after a full restore.
397Because restore runs in user code,
398it has no control over inode allocation;
399thus a full dump must be done to get a new set of directories
400reflecting the new inode numbering,
401even though the contents of the files is unchanged.
402.Pp
403To do a network restore, you have to run restore as root. This is due
404to the previous security history of dump and restore. (restore is
405written to be setuid root, but we are not certain all bugs are gone
406from the restore code - run setuid at your own risk.)
407.Sh HISTORY
408The
409.Nm restore
410command appeared in
411.Bx 4.2 .
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.
--- 15 unchanged lines hidden (view full) ---
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.\" $Id$
34.\" "
35.Dd December 11, 1993
36.Dt RESTORE 8
37.Os BSD 4
38.Sh NAME
39.Nm restore
40.Nd "restore files or file systems from backups made with dump"
41.Sh SYNOPSIS
42.Nm restore
43.Ar key
44.Op Ar name Ar ...
45.Sh DESCRIPTION
46The
47.Nm restore
48command performs the inverse function of
49.Xr dump 8 .
50A full backup of a file system may be restored and
51subsequent incremental backups layered on top of it.
52Single files and
53directory subtrees may be restored from full or partial
54backups.
55.Nm Restore
56works across a network;
57to do this see the
58.Fl f
59flag described below.
60The actions
61of
62.Nm restore
63are controlled by the given
64.Cm key ,
65which
66is a string of characters containing
67at most one function letter and possibly
68one or more function modifiers.
69Other arguments to the command are file or directory
70names specifying the files that are to be restored.
71Unless the
72.Cm h
73key is specified (see below),
74the appearance of a directory name refers to
75the files and (recursively) subdirectories of that directory.
76.Pp
77The function portion of
78the key is specified by one of the following letters:
79.Bl -tag -width Ds
80.It Cm r
81Restore (rebuild a file system).
82The target file system should be made pristine with
83.Xr newfs 8 ,
84mounted and the
85user
86.Xr cd Ns 'd
87into the pristine file system
88before starting the restoration of the initial level 0 backup. If the
89level 0 restores successfully, the
90.Cm r
91key may be used to restore
92any necessary incremental backups on top of the level 0.
93The
94.Cm r
95key precludes an interactive file extraction and can be
96detrimental to one's health if not used carefully (not to mention
97the disk). An example:
98.Bd -literal -offset indent
99newfs /dev/rrp0g eagle
100mount /dev/rp0g /mnt
101cd /mnt
102
103restore rf /dev/rst8
104.Ed
105.Pp
106Note that
107.Nm restore
108leaves a file
109.Pa restoresymtable
110in the root directory to pass information between incremental
111restore passes.
112This file should be removed when the last incremental has been
113restored.
114.Pp
115.Nm Restore ,
116in conjunction with
117.Xr newfs 8
118and
119.Xr dump 8 ,
120may be used to modify file system parameters
121such as size or block size.
122.It Cm R
123.Nm Restore
124requests a particular tape of a multi volume set on which to restart
125a full restore
126(see the
127.Cm r
128key above).
129This is useful if the restore has been interrupted.
130.It Cm x
131The named files are read from the given media.
132If a named file matches a directory whose contents
133are on the backup
134and the
135.Cm h
136key is not specified,
137the directory is recursively extracted.
138The owner, modification time,
139and mode are restored (if possible).
140If no file argument is given,
141then the root directory is extracted,
142which results in the entire content of the
143backup being extracted,
144unless the
145.Cm h
146key has been specified.
147.It Cm t
148The names of the specified files are listed if they occur
149on the backup.
150If no file argument is given,
151then the root directory is listed,
152which results in the entire content of the
153backup being listed,
154unless the
155.Cm h
156key has been specified.
157Note that the
158.Cm t
159key replaces the function of the old
160.Xr dumpdir 8
161program.
162.It Cm i
163This mode allows interactive restoration of files from a dump.
164After reading in the directory information from the dump,
165.Nm restore
166provides a shell like interface that allows the user to move
167around the directory tree selecting files to be extracted.
168The available commands are given below;
169for those commands that require an argument,
170the default is the current directory.
171.Bl -tag -width Fl
172.It Ic add Op Ar arg
173The current directory or specified argument is added to the list of
174files to be extracted.
175If a directory is specified, then it and all its descendents are
176added to the extraction list
177(unless the
178.Cm h
179key is specified on the command line).
180Files that are on the extraction list are prepended with a ``*''
181when they are listed by
182.Ic ls .
183.It Ic \&cd Ar arg
184Change the current working directory to the specified argument.
185.It Ic delete Op Ar arg
186The current directory or specified argument is deleted from the list of
187files to be extracted.
188If a directory is specified, then it and all its descendents are
189deleted from the extraction list
190(unless the
191.Cm h
192key is specified on the command line).
193The most expedient way to extract most of the files from a directory
194is to add the directory to the extraction list and then delete
195those files that are not needed.
196.It Ic extract
197All the files that are on the extraction list are extracted
198from the dump.
199.Nm Restore
200will ask which volume the user wishes to mount.
201The fastest way to extract a few files is to
202start with the last volume, and work towards the first volume.
203.It Ic help
204List a summary of the available commands.
205.It Ic \&ls Op Ar arg
206List the current or specified directory.
207Entries that are directories are appended with a ``/''.
208Entries that have been marked for extraction are prepended with a ``*''.
209If the verbose key is set the inode number of each entry is also listed.
210.It Ic pwd
211Print the full pathname of the current working directory.
212.It Ic quit
213Restore immediately exits,
214even if the extraction list is not empty.
215.It Ic setmodes
216All the directories that have been added to the extraction list
217have their owner, modes, and times set;
218nothing is extracted from the dump.
219This is useful for cleaning up after a restore has been prematurely aborted.
220.It Ic verbose
221The sense of the
222.Cm v
223key is toggled.
224When set, the verbose key causes the
225.Ic ls
226command to list the inode numbers of all entries.
227It also causes
228.Nm restore
229to print out information about each file as it is extracted.
230.El
231.El
232.Pp
233The following characters may be used in addition to the letter
234that selects the function desired.
235.Bl -tag -width Ds
236.It Cm b
237The next argument to
238.Nm restore
239is used as the block size of the media (in kilobytes).
240If the
241.Fl b
242option is not specified,
243.Nm restore
244tries to determine the media block size dynamically.
245.It Cm f
246The next argument to
247.Nm restore
248is used as the name of the archive instead
249of
250.Pa /dev/rst0 .
251If the name of the file is of the form
252.Dq host:file ,
253.Nm restore
254reads from the named file on the remote host using
255.Xr rmt 8 .
256If the name of the file is
257.Ql Fl ,
258.Nm restore
259reads from standard input.
260Thus,
261.Xr dump 8
262and
263.Nm restore
264can be used in a pipeline to dump and restore a file system
265with the command
266.Bd -literal -offset indent
267dump 0f - /usr | (cd /mnt; restore xf -)
268.Ed
269.Pp
270.It Cm h
271.Nm Restore
272extracts the actual directory,
273rather than the files that it references.
274This prevents hierarchical restoration of complete subtrees
275from the dump.
276.It Cm m
277.Nm Restore
278will extract by inode numbers rather than by file name.
279This is useful if only a few files are being extracted,
280and one wants to avoid regenerating the complete pathname
281to the file.
282.It Cm s
283The next argument to
284.Nm restore
285is a number which
286selects the file on a multi-file dump tape. File numbering
287starts at 1.
288.It Cm v
289Normally
290.Nm restore
291does its work silently.
292The
293.Cm v
294(verbose)
295key causes it to type the name of each file it treats
296preceded by its file type.
297.It Cm y
298.Nm Restore
299will not ask whether it should abort the restore if it gets an error.
300It will always try to skip over the bad block(s) and continue as
301best it can.
302.El
303.Sh DIAGNOSTICS
304Complaints about bad key characters.
305.Pp
306Complaints if it gets a read error.
307If
308.Cm y
309has been specified, or the user responds
310.Ql y ,
311.Nm restore
312will attempt to continue the restore.
313.Pp
314If a backup was made using more than one tape volume,
315.Nm restore
316will notify the user when it is time to mount the next volume.
317If the
318.Cm x
319or
320.Cm i
321key has been specified,
322.Nm restore
323will also ask which volume the user wishes to mount.
324The fastest way to extract a few files is to
325start with the last volume, and work towards the first volume.
326.Pp
327There are numerous consistency checks that can be listed by
328.Nm restore .
329Most checks are self-explanatory or can ``never happen''.
--- 56 unchanged lines hidden (view full) ---
386.Xr dump 8 ,
387.Xr ft 8 ,
388.Xr mount 8 ,
389.Xr newfs 8 ,
390.Xr rmt 8
391.Sh BUGS
392.Nm Restore
393can get confused when doing incremental restores from
394dump that were made on active file systems.
395.Pp
396A level zero dump must be done after a full restore.
397Because restore runs in user code,
398it has no control over inode allocation;
399thus a full dump must be done to get a new set of directories
400reflecting the new inode numbering,
401even though the contents of the files is unchanged.
402.Pp
403To do a network restore, you have to run restore as root. This is due
404to the previous security history of dump and restore. (restore is
405written to be setuid root, but we are not certain all bugs are gone
406from the restore code - run setuid at your own risk.)
407.Sh HISTORY
408The
409.Nm restore
410command appeared in
411.Bx 4.2 .