fssnap_ufs(1M)						  System Administration Commands					    fssnap_ufs(1M)

NAME

       fssnap_ufs - create a temporary snapshot of a UFS file system

SYNOPSIS

       fssnap [-F ufs] [-V] -o backing-store=path,
	    [specific-options] /mount/point

       fssnap -d [-F ufs] [-V] /mount/point | dev

       fssnap -i [-F ufs] [-V] [-o specific-options] /mount/point | dev

DESCRIPTION

       The  fssnap  command  queries, creates, or deletes a temporary snapshot of a UFS file system. A snapshot is a point-in-time image of a file
       system that provides a stable and unchanging device interface for backups.

       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, fssnap automati-
       cally creates additional backing-store files on an as-needed basis.

       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 UFS file system or an NFS-mounted file system.

OPTIONS

       The following options are supported:

       -d

	   Deletes the snapshot associated with the given file system.

       -i

	   Displays the state of one or all UFS 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.

	   Use the -o options with the -i 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 interna-
	   tionalized or localized. The information is displayed on one line per option. Unrecognized options display a single ? 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.

	   The following -o options display specific information for a given snapshot. See the EXAMPLES section for examples of how to	use  these
	   options.

	   snapnumber

	       Display the snapshot number.

	   blockdevname

	       Display the block device path.

	   rawdevname

	       Display the raw device path.

	   mountpoint

	       Display the mount point of the master file system.

	   state

	       Display the state of the snapshot device.

	   backing-store

	       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 .2, .3, and so forth.

	   backing-store-len

	       Display the sum of the sizes of the backing-store files.

	   maxsize

	       Display the maxsize value specified for the backing-store file(s).

	   createtime

	       Display the time that the snapshot was created.

	   chunksize

	       Display the copy-on-write granularity.

       -o specific-options

	   Without -d or -i, 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.

	   backing-store=path

	       Uses  path  in the creation of the backing-store file(s). path must not reside on the file system that is being captured in a snap-
	       shot and must not be the name of an existing file. If path is a directory, then a backing-store file is created within it  using  a
	       name  that  is  generated automatically. If path 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, fssnap creates subsequent files  automatically.  The  second  and
	       subsequent files have the same name as the first file, with suffixes of .2, .3, and so forth.

	       This option can be abbreviated as bf=path or bs=path.

	   unlink

	       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.

	   chunksize=n [k,m,g]

	       Uses n for the chunk size. Chunk size is the granularity of the data that is sent to the backing store.

	       Specify	chunksize  in  the  following  units: k for kilobytes, m for megabytes, or g for gigabytes. By default, chunk size is four
	       times the block size of the file system (typically 32k).

	   maxsize=n[k,m,g]

	       Does not allow the sum of the sizes of the backing-store file(s) to exceed n, where n is  the  unit  specified.	 The  snapshot	is
	       deleted automatically when the sum of the sizes of the backing-store file(s) exceeds maxsize.

	       Specify maxsize in the following units: k for kilobytes, m for megabytes, or g for gigabytes.

	   raw

	       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 raw is not specified). This option makes it easier to embed fssnap commands in the command line  for  com-
	       mands that require the raw device instead. Both devices are always created. This option affects only the output.

OPERANDS

       The following operands are supported:

       mount-point

	   The directory where the file system resides.

       special

	   The physical device for the file system, such as /dev/dsk/c0t0d0s7.

EXAMPLES

       Example 1 Creating a Snapshot of a File System

       The following example creates a snapshot of a file system. The block special device created for the snapshot is /dev/fssnap/0.

	 # fssnap -F ufs -o backing-store=/var/tmp /export/home
	 /dev/fssnap/0

       Example 2 Backing Up a File System Snapshot Without Having To Unmount the File System

       The  following  example backs up a file system snapshot without having to unmount the file system. Since ufsdump requires the path to a raw
       device, the raw option is used. The /export/home file system snapshot is removed in the second command.

	 # ufsdump 0uf /dev/rmt/0 `fssnap -F ufs
	       -o raw,bs=/export/snap /export/home`
	 <output from ufsdump>
	 # fssnap -F ufs -d /export/home

       Example 3 Backing Up a File System

       When backing up a file system, do not let the backing-store file(s) exceed 400 Mbytes. The second command  removes  the	/export/home  file
       system snapshot.

	 # ufsdump 0uf /dev/rmt/0 `fssnap -F ufs
	       -o maxsize=400m,backing-store=/export/snap,raw
	       /export/home`
	 # fssnap -F ufs -d /export/home

       Example 4 Performing an Incremental Dump of a Snapshot

       The  following  example	uses  ufsdump to back up a snapshot of /var. Note the use of the N option to ufsdump, which writes the name of the
       device being dumped, rather than the name of the snapshot device, to /etc/dumpdates file. See ufsdump(1M) for details on the N flag.

	 # ufsdump lfNu /dev/rmt/0 /dev/rdsk/c0t3d0s2 `fssnap -F ufs
	 -o raw,bs=/export/scratch,unlink /var`

       Example 5 Finding Out What Snapshots Currently Exist

       The following command displays the currently existing snapshots.

	 # fssnap -i
	 0  /src
	 1  /export/home
	 <output continues>

       Example 6 Mounting a File System Snapshot

       The following example creates a file system snapshot. After you create a file system snapshot, mount it on /tmp/mount for  temporary  read-
       only access.

	 # 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

       Example 7 Creating a File System Snapshot and Unlinking the Backing-store File

       The  following example creates a file system snapshot and unlinks the backing-store file. After creating a file system snapshot and unlink-
       ing the backing-store file, check the state of the snapshot.

	 # 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

       Example 8 Displaying the Size and Location of the Backing-store File(s) and the Creation Time for the Snapshot

       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 /test file system.

	 # fssnap -i -o backing-store-len,backing-store,createtime /test
	 196608
	 /snapshot2
	 Sat May 6 10:55:11 2000

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

EXIT STATUS

       The following exit values are returned:

       0

	   Successful completion.

       >0

	   An error occurred.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

       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.

SEE ALSO

       xntpd(1M), mlock(3C), attributes(5)

NOTES

       The fssnap device files should be treated like a regular disk block or character device.

       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.

       To avoid unnecessary performance impacts, perform the snapshot and system backup when the system is least active.

       It is not possible to perform a snapshot of a file system if any of  the following conditions are true:

	   o	  The file system is in use by system accounting

	   o	  The file system contains a local swap file

	   o	  The file system is used as backing store by an application that uses mlock(3C) to lock its pages. Typically, these are real time
		  applications, such as xntpd(1M).

       These conditions result in fssnap being unable to write lock the file system prior to performing the snapshot.

SunOS 5.11							    29 Jan 2007 						    fssnap_ufs(1M)