| blob | ca58f36e3f893af806cb90dfc4867c5d2a33c444 |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH FSSNAP_UFS 1M "May 13, 2017"
7 .SH NAME
8 fssnap_ufs \- create a temporary snapshot of a UFS file system
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBfssnap\fR [\fB-F\fR ufs] [\fB-V\fR] \fB-o\fR \fIbacking-store\fR=\fIpath\fR,
13 [\fIspecific-options\fR] \fI/mount/point\fR
14 .fi
16 .LP
17 .nf
18 \fBfssnap\fR \fB-d\fR [\fB-F\fR ufs] [\fB-V\fR] \fI/mount/point\fR | \fIdev\fR
19 .fi
21 .LP
22 .nf
23 \fBfssnap\fR \fB-i\fR [\fB-F\fR ufs] [\fB-V\fR] [\fB-o\fR \fIspecific-options\fR] \fI/mount/point\fR | \fIdev\fR
24 .fi
26 .SH DESCRIPTION
27 .LP
28 The \fBfssnap\fR command queries, creates, or deletes a temporary snapshot of a
29 \fBUFS\fR file system. A snapshot is a point-in-time image of a file system
30 that provides a stable and unchanging device interface for backups.
31 .sp
32 .LP
33 When creating a file system snapshot, you must specify the file system to be
34 captured and the backing-store file. The backing-store file(s) are where the
35 snapshot subsystem saves old file system data before it is overwritten. Beyond
36 the first backing-store file, \fBfssnap\fR automatically creates additional
37 backing-store files on an as-needed basis.
38 .sp
39 .LP
40 The number and size of the backing store files varies with the amount of
41 activity in the file system. The destination path must have enough free space
42 to hold the backing-store file(s). This location must be different from the
43 file system that is being captured in a snapshot. The backing-store file(s) can
44 reside on any type of file system, including another \fBUFS\fR file system or
45 an \fBNFS\fR-mounted file system.
46 .SH OPTIONS
47 .LP
48 The following options are supported:
49 .sp
50 .ne 2
51 .na
52 \fB\fB-d\fR\fR
53 .ad
54 .sp .6
55 .RS 4n
56 Deletes the snapshot associated with the given file system.
57 .RE
59 .sp
60 .ne 2
61 .na
62 \fB\fB-i\fR\fR
63 .ad
64 .sp .6
65 .RS 4n
66 Displays the state of one or all \fBUFS\fR snapshots. If a mount-point or
67 device is not specified, a list of all snapshots on the system is displayed.
68 When a mount-point or device is specified, detailed information is provided for
69 the specified file system snapshot by default.
70 .sp
71 Use the \fB-o\fR options with the \fB-i\fR option to specify what snapshot
72 information is displayed. Since this feature is provided primarily for use in
73 scripts and on the command line, no labels are displayed for the data. Sizes
74 are all in bytes, and the output is not internationalized or localized. The
75 information is displayed on one line per option. Unrecognized options display a
76 single \fB?\fR on the line. One line per option guarantees that there are the
77 same number of lines as options specified and there is a one-to-one
78 correspondence between an output line and an option.
79 .sp
80 The following \fB-o\fR options display specific information for a given
81 snapshot. See the EXAMPLES section for examples of how to use these options.
82 .sp
83 .ne 2
84 .na
85 \fB\fBsnapnumber\fR\fR
86 .ad
87 .sp .6
88 .RS 4n
89 Display the snapshot number.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fBblockdevname\fR\fR
96 .ad
97 .sp .6
98 .RS 4n
99 Display the block device path.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fBrawdevname\fR\fR
106 .ad
107 .sp .6
108 .RS 4n
109 Display the raw device path.
110 .RE
112 .sp
113 .ne 2
114 .na
115 \fB\fBmountpoint\fR\fR
116 .ad
117 .sp .6
118 .RS 4n
119 Display the mount point of the master file system.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fBstate\fR\fR
126 .ad
127 .sp .6
128 .RS 4n
129 Display the state of the snapshot device.
130 .RE
132 .sp
133 .ne 2
134 .na
135 \fB\fBbacking-store\fR\fR
136 .ad
137 .sp .6
138 .RS 4n
139 Display the location of the first backing-store file for this snapshot. If
140 there are multiple backing-store files, subsequent files have the same name as
141 the first file, with the suffixes \fB\&.2\fR, \fB\&.3\fR, and so forth.
142 .RE
144 .sp
145 .ne 2
146 .na
147 \fB\fBbacking-store-len\fR\fR
148 .ad
149 .sp .6
150 .RS 4n
151 Display the sum of the sizes of the backing-store files.
152 .RE
154 .sp
155 .ne 2
156 .na
157 \fB\fBmaxsize\fR\fR
158 .ad
159 .sp .6
160 .RS 4n
161 Display the \fBmaxsize\fR value specified for the backing-store file(s).
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBcreatetime\fR\fR
168 .ad
169 .sp .6
170 .RS 4n
171 Display the time that the snapshot was created.
172 .RE
174 .sp
175 .ne 2
176 .na
177 \fB\fBchunksize\fR\fR
178 .ad
179 .sp .6
180 .RS 4n
181 Display the copy-on-write granularity.
182 .RE
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fB-o\fR \fIspecific-options\fR\fR
190 .ad
191 .sp .6
192 .RS 4n
193 Without \fB-d\fR or \fB-i\fR, the default action is to create a snapshot.
194 Specify the following options when creating a snapshot. All of these options
195 are discretionary, except for the backing-store file, which is required.
196 .sp
197 .ne 2
198 .na
199 \fB\fBbacking-store=\fR\fIpath\fR\fR
200 .ad
201 .sp .6
202 .RS 4n
203 Uses \fIpath\fR in the creation of the backing-store file(s). \fIpath\fR must
204 not reside on the file system that is being captured in a snapshot and must not
205 be the name of an existing file. If \fIpath\fR is a directory, then a
206 backing-store file is created within it using a name that is generated
207 automatically. If \fIpath\fR is not a directory and does not already exist,
208 then a backing-store file with that name is created. If more than one
209 backing-store file is required, \fBfssnap\fR creates subsequent files
210 automatically. The second and subsequent files have the same name as the first
211 file, with suffixes of \fB\&.2\fR, \fB\&.3\fR, and so forth.
212 .sp
213 This option can be abbreviated as \fBbf=\fR\fIpath\fR or \fBbs=\fR\fIpath\fR.
214 .RE
216 .sp
217 .ne 2
218 .na
219 \fB\fBunlink\fR\fR
220 .ad
221 .sp .6
222 .RS 4n
223 Unlinks the backing-store file after the snapshot is created. This option
224 specifies that the backing-store file does not need to be removed manually when
225 the snapshot is deleted. This might make administration more difficult since
226 the file is not visible in the file system. If this option is not specified,
227 the backing-store files should be removed manually after the snapshot is
228 deleted.
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fB\fBchunksize=\fR\fIn\fR [\fBk\fR,\fBm\fR,\fBg\fR]\fR
235 .ad
236 .sp .6
237 .RS 4n
238 Uses \fIn\fR for the chunk size. Chunk size is the granularity of the data that
239 is sent to the backing store.
240 .sp
241 Specify \fBchunksize\fR in the following units: \fBk\fR for kilobytes, \fBm\fR
242 for megabytes, or \fBg\fR for gigabytes. By default, chunk size is four times
243 the block size of the file system (typically \fB32k\fR).
244 .RE
246 .sp
247 .ne 2
248 .na
249 \fB\fBmaxsize=\fR\fIn\fR[\fBk\fR,\fBm\fR,\fBg\fR]\fR
250 .ad
251 .sp .6
252 .RS 4n
253 Does not allow the sum of the sizes of the backing-store file(s) to exceed
254 \fIn\fR, where \fIn\fR is the unit specified. The snapshot is deleted
255 automatically when the sum of the sizes of the backing-store file(s) exceeds
256 \fBmaxsize\fR.
257 .sp
258 Specify \fBmaxsize\fR in the following units: \fBk\fR for kilobytes, \fBm\fR
259 for megabytes, or \fBg\fR for gigabytes.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBraw\fR\fR
266 .ad
267 .sp .6
268 .RS 4n
269 Displays to standard output the name of the raw device instead of the block
270 device when a snapshot is created. The block device is printed by default (when
271 \fBraw\fR is not specified). This option makes it easier to embed \fBfssnap\fR
272 commands in the command line for commands that require the raw device instead.
273 Both devices are always created. This option affects only the output.
274 .RE
276 .RE
278 .SH OPERANDS
279 .LP
280 The following operands are supported:
281 .sp
282 .ne 2
283 .na
284 \fB\fImount-point\fR\fR
285 .ad
286 .sp .6
287 .RS 4n
288 The directory where the file system resides.
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fIspecial\fR\fR
295 .ad
296 .sp .6
297 .RS 4n
298 The physical device for the file system, such as \fB/dev/dsk/c0t0d0s7\fR.
299 .RE
301 .SH EXAMPLES
302 .LP
303 \fBExample 1 \fRCreating a Snapshot of a File System
304 .sp
305 .LP
306 The following example creates a snapshot of a file system. The block special
307 device created for the snapshot is \fB/dev/fssnap/0\fR.
309 .sp
310 .in +2
311 .nf
312 # fssnap -F ufs -o backing-store=/var/tmp /export/home
313 /dev/fssnap/0
314 .fi
315 .in -2
316 .sp
318 .LP
319 \fBExample 2 \fRBacking Up a File System Snapshot Without Having To Unmount the
320 File System
321 .sp
322 .LP
323 The following example backs up a file system snapshot without having to unmount
324 the file system. Since \fBufsdump\fR requires the path to a raw device, the
325 \fBraw\fR option is used. The \fB/export/home\fR file system snapshot is
326 removed in the second command.
328 .sp
329 .in +2
330 .nf
331 # ufsdump 0uf /dev/rmt/0 `fssnap -F ufs
332 -o raw,bs=/export/snap /export/home`
333 \fI<output from ufsdump>\fR
334 # fssnap -F ufs -d /export/home
335 .fi
336 .in -2
337 .sp
339 .LP
340 \fBExample 3 \fRBacking Up a File System
341 .sp
342 .LP
343 When backing up a file system, do not let the backing-store file(s) exceed
344 \fB400\fR \fBMbytes\fR. The second command removes the \fB/export/home\fR file
345 system snapshot.
347 .sp
348 .in +2
349 .nf
350 # ufsdump 0uf /dev/rmt/0 `fssnap -F ufs
351 -o maxsize=400m,backing-store=/export/snap,raw
352 /export/home`
353 # fssnap -F ufs -d /export/home
354 .fi
355 .in -2
356 .sp
358 .LP
359 \fBExample 4 \fRPerforming an Incremental Dump of a Snapshot
360 .sp
361 .LP
362 The following example uses \fBufsdump\fR to back up a snapshot of \fB/var\fR.
363 Note the use of the \fBN\fR option to \fBufsdump\fR, which writes the name of
364 the device being dumped, rather than the name of the snapshot device, to
365 \fB/etc/dumpdates\fR file. See \fBufsdump\fR(1M) for details on the \fBN\fR
366 flag.
368 .sp
369 .in +2
370 .nf
371 # ufsdump lfNu /dev/rmt/0 /dev/rdsk/c0t3d0s2 `fssnap -F ufs
372 -o raw,bs=/export/scratch,unlink /var`
373 .fi
374 .in -2
375 .sp
377 .LP
378 \fBExample 5 \fRFinding Out What Snapshots Currently Exist
379 .sp
380 .LP
381 The following command displays the currently existing snapshots.
383 .sp
384 .in +2
385 .nf
386 # fssnap -i
387 0 /src
388 1 /export/home
389 \fI<output continues>\fR
390 .fi
391 .in -2
392 .sp
394 .LP
395 \fBExample 6 \fRMounting a File System Snapshot
396 .sp
397 .LP
398 The following example creates a file system snapshot. After you create a file
399 system snapshot, mount it on \fB/tmp/mount\fR for temporary read-only access.
401 .sp
402 .in +2
403 .nf
404 # fssnap -F ufs -o backing-store=/nfs/server/scratch /export/home
405 /dev/fssnap/1
406 # mkdir /tmp/mount
407 # mount -F ufs -o ro /dev/fssnap/1 /tmp/mount
408 .fi
409 .in -2
410 .sp
412 .LP
413 \fBExample 7 \fRCreating a File System Snapshot and Unlinking the Backing-store
414 File
415 .sp
416 .LP
417 The following example creates a file system snapshot and unlinks the
418 backing-store file. After creating a file system snapshot and unlinking the
419 backing-store file, check the state of the snapshot.
421 .sp
422 .in +2
423 .nf
424 # fssnap -o bs=/scratch,unlink /src
425 /dev/fssnap/0
426 # fssnap -i /src
427 Snapshot number : 0
428 Block Device : /dev/fssnap/0
429 Raw Device : /dev/rfssnap/0
430 Mount point : /src
431 Device state : active
432 Backing store path : /scratch/snapshot2 <UNLINKED>
433 Backing store size : 192 KB
434 Maximum backing store size : Unlimited
435 Snapshot create time : Sat May 06 10:55:11 2000
436 Copy-on-write granularity : 32 KB
437 .fi
438 .in -2
439 .sp
441 .LP
442 \fBExample 8 \fRDisplaying the Size and Location of the Backing-store File(s)
443 and the Creation Time for the Snapshot
444 .sp
445 .LP
446 The following example displays the size of the backing-store file(s) in bytes,
447 the location of the backing store, and the creation time for the snapshot of
448 the \fB/test\fR file system.
450 .sp
451 .in +2
452 .nf
453 # fssnap -i -o backing-store-len,backing-store,createtime /test
454 196608
455 /snapshot2
456 Sat May 6 10:55:11 2000
457 .fi
458 .in -2
459 .sp
461 .sp
462 .LP
463 Note that if there are multiple backing-store files stored in \fB/snapshot2\fR,
464 they will have names of the form \fIfile\fR (for the first file), \fIfile\fR.1,
465 \fIfile\fR.2, and so forth.
467 .SH EXIT STATUS
468 .LP
469 The following exit values are returned:
470 .sp
471 .ne 2
472 .na
473 \fB\fB0\fR\fR
474 .ad
475 .sp .6
476 .RS 4n
477 Successful completion.
478 .RE
480 .sp
481 .ne 2
482 .na
483 \fB>\fB0\fR\fR
484 .ad
485 .sp .6
486 .RS 4n
487 An error occurred.
488 .RE
490 .sp
491 .LP
492 The script-readable output mode is a stable interface that can be added to, but
493 will not change. All other interfaces are subject to change.
494 .SH SEE ALSO
495 .LP
496 \fBmlock\fR(3C), \fBattributes\fR(5)
497 .SH NOTES
498 .LP
499 The \fBfssnap\fR device files should be treated like a regular disk block or
500 character device.
501 .sp
502 .LP
503 The association between a file system and the snapshot is lost when the
504 snapshot is deleted or the system reboots. Snapshot persistence across reboots
505 is not supported.
506 .sp
507 .LP
508 To avoid unnecessary performance impacts, perform the snapshot and system
509 backup when the system is least active.
510 .sp
511 .LP
512 It is not possible to perform a snapshot of a file system if any of the
513 following conditions are true:
514 .RS +4
515 .TP
516 .ie t \(bu
517 .el o
518 The file system is in use by system accounting
519 .RE
520 .RS +4
521 .TP
522 .ie t \(bu
523 .el o
524 The file system contains a local swap file
525 .RE
526 .RS +4
527 .TP
528 .ie t \(bu
529 .el o
530 The file system is used as backing store by an application that uses
531 \fBmlock\fR(3C) to lock its pages. Typically, these are real time applications,
532 such as \fBntpd\fR.
533 .RE
534 .sp
535 .LP
536 These conditions result in \fBfssnap\fR being unable to write lock the file
537 system prior to performing the snapshot.