'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\"  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
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH fssnap_ufs 1M "29 Jan 2007" "SunOS 5.11" "System Administration Commands"
.SH NAME
fssnap_ufs \- create a temporary snapshot of a UFS file system
.SH SYNOPSIS
.LP
.nf
\fBfssnap\fR [\fB-F\fR ufs] [\fB-V\fR] \fB-o\fR \fIbacking-store\fR=\fIpath\fR, 
     [\fIspecific-options\fR] \fI/mount/point\fR
.fi

.LP
.nf
\fBfssnap\fR \fB-d\fR [\fB-F\fR ufs] [\fB-V\fR] \fI/mount/point\fR | \fIdev\fR
.fi

.LP
.nf
\fBfssnap\fR \fB-i\fR [\fB-F\fR ufs] [\fB-V\fR] [\fB-o\fR \fIspecific-options\fR] \fI/mount/point\fR | \fIdev\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBfssnap\fR command queries, creates, or deletes a temporary snapshot of a
\fBUFS\fR file system. A snapshot is a point-in-time image of a file system
that provides a stable and unchanging device interface for backups.
.sp
.LP
When creating a file system snapshot, you must specify the file system to be
captured and the backing-store file. The backing-store file(s) are where the
snapshot subsystem saves old file system data before it is overwritten. Beyond
the first backing-store file, \fBfssnap\fR automatically creates additional
backing-store files on an as-needed basis.
.sp
.LP
The number and size of the backing store files varies with the amount of
activity in the file system. The destination path must have enough free space
to hold the backing-store file(s). This location must be different from the
file system that is being captured in a snapshot. The backing-store file(s) can
reside on any type of file system, including another \fBUFS\fR file system or
an \fBNFS\fR-mounted file system.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-d\fR\fR
.ad
.sp .6
.RS 4n
Deletes the snapshot associated with the given file system.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-i\fR\fR
.ad
.sp .6
.RS 4n
Displays the state of one or all \fBUFS\fR snapshots. If a mount-point or
device is not specified, a list of all snapshots on the system is displayed.
When a mount-point or device is specified, detailed information is provided for
the specified file system snapshot by default.
.sp
Use the \fB-o\fR options with the \fB-i\fR option to specify what snapshot
information is displayed. Since this feature is provided primarily for use in
scripts and on the command line, no labels are displayed for the data. Sizes
are all in bytes, and the output is not internationalized or localized. The
information is displayed on one line per option. Unrecognized options display a
single \fB?\fR on the line. One line per option guarantees that there are the
same number of lines as options specified and there is a one-to-one
correspondence between an output line and an option.
.sp
The following \fB-o\fR options display specific information for a given
snapshot. See the EXAMPLES section for examples of how to use these options.
.sp
.ne 2
.mk
.na
\fB\fBsnapnumber\fR\fR
.ad
.sp .6
.RS 4n
Display the snapshot number.
.RE

.sp
.ne 2
.mk
.na
\fB\fBblockdevname\fR\fR
.ad
.sp .6
.RS 4n
Display the block device path.
.RE

.sp
.ne 2
.mk
.na
\fB\fBrawdevname\fR\fR
.ad
.sp .6
.RS 4n
Display the raw device path.
.RE

.sp
.ne 2
.mk
.na
\fB\fBmountpoint\fR\fR
.ad
.sp .6
.RS 4n
Display the mount point of the master file system.
.RE

.sp
.ne 2
.mk
.na
\fB\fBstate\fR\fR
.ad
.sp .6
.RS 4n
Display the state of the snapshot device.
.RE

.sp
.ne 2
.mk
.na
\fB\fBbacking-store\fR\fR
.ad
.sp .6
.RS 4n
Display the location of the first backing-store file for this snapshot. If
there are multiple backing-store files, subsequent files have the same name as
the first file, with the suffixes \fB\&.2\fR, \fB\&.3\fR, and so forth.
.RE

.sp
.ne 2
.mk
.na
\fB\fBbacking-store-len\fR\fR
.ad
.sp .6
.RS 4n
Display the sum of the sizes of the backing-store files.
.RE

.sp
.ne 2
.mk
.na
\fB\fBmaxsize\fR\fR
.ad
.sp .6
.RS 4n
Display the \fBmaxsize\fR value specified for the backing-store file(s).
.RE

.sp
.ne 2
.mk
.na
\fB\fBcreatetime\fR\fR
.ad
.sp .6
.RS 4n
Display the time that the snapshot was created.
.RE

.sp
.ne 2
.mk
.na
\fB\fBchunksize\fR\fR
.ad
.sp .6
.RS 4n
Display the copy-on-write granularity.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-o\fR \fIspecific-options\fR\fR
.ad
.sp .6
.RS 4n
Without \fB-d\fR or \fB-i\fR, the default action is to create a snapshot.
Specify the following options when creating a snapshot. All of these options
are discretionary, except for the backing-store file, which is required.
.sp
.ne 2
.mk
.na
\fB\fBbacking-store=\fR\fIpath\fR\fR
.ad
.sp .6
.RS 4n
Uses \fIpath\fR in the creation of the backing-store file(s). \fIpath\fR must
not reside on the file system that is being captured in a snapshot and must not
be the name of an existing file. If \fIpath\fR is a directory, then a
backing-store file is created within it using a name that is generated
automatically. If \fIpath\fR is not a directory and does not already exist,
then a backing-store file with that name is created. If more than one
backing-store file is required, \fBfssnap\fR creates subsequent files
automatically. The second and subsequent files have the same name as the first
file, with suffixes of \fB\&.2\fR, \fB\&.3\fR, and so forth.
.sp
This option can be abbreviated as \fBbf=\fR\fIpath\fR or \fBbs=\fR\fIpath\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBunlink\fR\fR
.ad
.sp .6
.RS 4n
Unlinks the backing-store file after the snapshot is created. This option
specifies that the backing-store file does not need to be removed manually when
the snapshot is deleted. This might make administration more difficult since
the file is not visible in the file system. If this option is not specified,
the backing-store files should be removed manually after the snapshot is
deleted.
.RE

.sp
.ne 2
.mk
.na
\fB\fBchunksize=\fR\fIn\fR [\fBk\fR,\fBm\fR,\fBg\fR]\fR
.ad
.sp .6
.RS 4n
Uses \fIn\fR for the chunk size. Chunk size is the granularity of the data that
is sent to the backing store.
.sp
Specify \fBchunksize\fR in the following units: \fBk\fR for kilobytes, \fBm\fR
for megabytes, or \fBg\fR for gigabytes. By default, chunk size is four times
the block size of the file system (typically \fB32k\fR).
.RE

.sp
.ne 2
.mk
.na
\fB\fBmaxsize=\fR\fIn\fR[\fBk\fR,\fBm\fR,\fBg\fR]\fR
.ad
.sp .6
.RS 4n
Does not allow the sum of the sizes of the backing-store file(s) to exceed
\fIn\fR, where \fIn\fR is the unit specified.  The snapshot is deleted
automatically when the sum of the sizes of the backing-store file(s) exceeds
\fBmaxsize\fR.
.sp
Specify \fBmaxsize\fR in the following units: \fBk\fR for kilobytes, \fBm\fR
for megabytes, or \fBg\fR for gigabytes.
.RE

.sp
.ne 2
.mk
.na
\fB\fBraw\fR\fR
.ad
.sp .6
.RS 4n
Displays to standard output the name of the raw device instead of the block
device when a snapshot is created. The block device is printed by default (when
\fBraw\fR is not specified). This option makes it easier to embed \fBfssnap\fR
commands in the command line for commands that require the raw device instead.
Both devices are always created. This option affects only the output.
.RE

.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fImount-point\fR\fR
.ad
.sp .6
.RS 4n
The directory where the file system resides.
.RE

.sp
.ne 2
.mk
.na
\fB\fIspecial\fR\fR
.ad
.sp .6
.RS 4n
The physical device for the file system, such as \fB/dev/dsk/c0t0d0s7\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a Snapshot of a File System
.sp
.LP
The following example creates a snapshot of a file system. The block special
device created for the snapshot is \fB/dev/fssnap/0\fR.

.sp
.in +2
.nf
# fssnap -F ufs -o backing-store=/var/tmp /export/home
/dev/fssnap/0
.fi
.in -2
.sp

.LP
\fBExample 2 \fRBacking Up a File System Snapshot Without Having To Unmount the
File System
.sp
.LP
The following example backs up a file system snapshot without having to unmount
the file system. Since \fBufsdump\fR requires the path to a raw device, the
\fBraw\fR option is used. The \fB/export/home\fR file system snapshot is
removed in the second command.

.sp
.in +2
.nf
# ufsdump 0uf /dev/rmt/0 `fssnap -F ufs 
      -o raw,bs=/export/snap /export/home`
\fI<output from ufsdump>\fR
# fssnap -F ufs -d /export/home
.fi
.in -2
.sp

.LP
\fBExample 3 \fRBacking Up a File System
.sp
.LP
When backing up a file system, do not let the backing-store file(s) exceed
\fB400\fR \fBMbytes\fR. The second command removes the \fB/export/home\fR file
system snapshot.

.sp
.in +2
.nf
# ufsdump 0uf /dev/rmt/0 `fssnap -F ufs
      -o maxsize=400m,backing-store=/export/snap,raw 
      /export/home` 
# fssnap -F ufs -d /export/home 
.fi
.in -2
.sp

.LP
\fBExample 4 \fRPerforming an Incremental Dump of a Snapshot
.sp
.LP
The following example uses \fBufsdump\fR to back up a snapshot of \fB/var\fR.
Note the use of the \fBN\fR option to \fBufsdump\fR, which writes the name of
the device being dumped, rather than the name of the snapshot device, to
\fB/etc/dumpdates\fR file. See \fBufsdump\fR(1M) for details on the \fBN\fR
flag.

.sp
.in +2
.nf
# ufsdump lfNu /dev/rmt/0 /dev/rdsk/c0t3d0s2 `fssnap -F ufs 
-o raw,bs=/export/scratch,unlink /var`
.fi
.in -2
.sp

.LP
\fBExample 5 \fRFinding Out What Snapshots Currently Exist
.sp
.LP
The following command displays the currently existing snapshots.

.sp
.in +2
.nf
# fssnap -i
0  /src  
1  /export/home
\fI<output continues>\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRMounting a File System Snapshot
.sp
.LP
The following example creates a file system snapshot. After you create a file
system snapshot, mount it on \fB/tmp/mount\fR for temporary read-only access.

.sp
.in +2
.nf
# fssnap -F ufs -o backing-store=/nfs/server/scratch /export/home
/dev/fssnap/1 
# mkdir /tmp/mount 
# mount -F ufs -o ro /dev/fssnap/1 /tmp/mount  
.fi
.in -2
.sp

.LP
\fBExample 7 \fRCreating a File System Snapshot and Unlinking the Backing-store
File
.sp
.LP
The following example creates a file system snapshot and unlinks the
backing-store file. After creating a file system snapshot and unlinking the
backing-store file, check the state of the snapshot.

.sp
.in +2
.nf
# fssnap -o bs=/scratch,unlink /src
/dev/fssnap/0 
# fssnap -i /src 
Snapshot number               : 0 
Block Device                  : /dev/fssnap/0 
Raw Device                    : /dev/rfssnap/0 
Mount point                   : /src 
Device state                  : active 
Backing store path            : /scratch/snapshot2 <UNLINKED> 
Backing store size            : 192 KB 
Maximum backing store size    : Unlimited 
Snapshot create time          : Sat May 06 10:55:11 2000 
Copy-on-write granularity     : 32 KB 
.fi
.in -2
.sp

.LP
\fBExample 8 \fRDisplaying the Size and Location of the Backing-store File(s)
and the Creation Time for the Snapshot
.sp
.LP
The following example displays the size of the backing-store file(s) in bytes,
the location of the backing store, and the creation time for the snapshot of
the \fB/test\fR file system.

.sp
.in +2
.nf
# fssnap -i -o backing-store-len,backing-store,createtime /test 
196608 
/snapshot2 
Sat May 6 10:55:11 2000
.fi
.in -2
.sp

.sp
.LP
Note that if there are multiple backing-store files stored in \fB/snapshot2\fR,
they will have names of the form \fIfile\fR (for the first file), \fIfile\fR.1,
\fIfile\fR.2, and so forth.

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB>\fB0\fR\fR
.ad
.sp .6
.RS 4n
An error occurred.
.RE

.sp
.LP
The script-readable output mode is a stable interface that can be added to, but
will not change. All other interfaces are subject to change.
.SH SEE ALSO
.sp
.LP
\fBmlock\fR(3C), \fBattributes\fR(5)
.sp
.LP
See the \fBntpd\fR man page, delivered in the \fBSUNWntpu\fR package (not a
SunOS man page).
.SH NOTES
.sp
.LP
The \fBfssnap\fR device files should be treated like a regular disk block or
character device.
.sp
.LP
The association between a file system and the snapshot is lost when the
snapshot is deleted or the system reboots. Snapshot persistence across reboots
is not currently supported.
.sp
.LP
To avoid unnecessary performance impacts, perform the snapshot and system
backup when the system is least active.
.sp
.LP
It is not possible to perform a snapshot of a file system if any of  the
following conditions are true:
.RS +4
.TP
.ie t \(bu
.el o
The file system is in use by system accounting
.RE
.RS +4
.TP
.ie t \(bu
.el o
The file system contains a local swap file
.RE
.RS +4
.TP
.ie t \(bu
.el o
The file system is used as backing store by an application that uses
\fBmlock\fR(3C) to lock its pages. Typically, these are real time applications,
such as \fBntpd\fR (delivered in the \fBSUNWntpu\fR package).
.RE
.sp
.LP
These conditions result in \fBfssnap\fR being unable to write lock the file
system prior to performing the snapshot.