usr/src/man/man1m/fssnap_ufs.1m

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