Add some information about FFS snapshots to the handbook.

PR:		36725
Requested by:	murray

en_US.ISO8859-1/books/handbook/disks/chapter.sgml

@@ -418,6 +418,103 @@ Filesystem  1K-blocks     Used    Avail Capacity  Mounted on
     </sect2>
   </sect1>
   
+  <sect1 id="snapshots">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 15 JUL 2002 -->
+    </sect1info>
+
+    <title>File System Snapshots</title>
+
+    <indexterm>
+      <primary>File System Snapshots</primary>
+      <secondary>Snapshots</secondary>
+    </indexterm>
+    
+      <para>FreeBSD 5.0 offers a new feature in conjunction with the
+	<option>softupdates</option> option.  File system snapshots.</para>
+
+      <para>Snapshots allow a user to create an image of specified file
+	systems and treat this image as a file.  The -u (or update) flag
+	in &man.mount.8; is required with this option.
+	Snapshot files must be created in the file system that the
+	action is performed on, and a user may create no more than 20
+	snapshots per file system.  Active snapshots are recorded
+	in the superblock so they are persistent across unmount and
+	remount operations along with system reboots.  When a snapshot
+	is no longer required, it can be removed with the standard &man.rm.1;
+	command, like regular files.  Snapshots may be removed in any order,
+	however all the used space may not be acquired as another snapshot will
+	possibly claim some of the blocks that were released.</para>
+
+      <para>During initial creation, the schg flag (see &man.chflags.1; manual page)
+	is set on to ensure that not even root can write to the snapshot.
+	The &man.unlink.1; command makes an exception for snapshot files,
+	however, in which it allows them to be removed even
+	though they have the schg flag set, so it is not necessary to
+	clear the schg flag before removing a snapshot file.</para>
+
+      <para>Once a snapshot has been created, there are several interesting
+	things that an administrator can do with them:</para>
+	
+      <itemizedlist>
+	<listitem>
+	  <para>Some administrators will use a snapshot file for backup purposes,
+	    where the snapshot can be transfered to a CD or tape.</para>
+	</listitem>
+	
+	<listitem>
+	  <para>File integrity, &man.fsck.8; may be ran on the snapshot file.
+	    Assuming that the file system was clean when it was mounted, you
+	    should always get a clean (and unchanging) result from running
+	    &man.fsck.8; on the snapshot.  This is essentially what the
+	    background &man.fsck.8; process does.</para>
+	</listitem>
+	
+	<listitem>
+	  <para>Run the &man.dump.8; utility on the snapshot.
+	    A dump will be returned that is as consistent with the
+	    file system as the timestamp of the snapshot.</para>
+
+	  <warning><para>As of this writing &man.dump.8; has not yet
+	    been changed to set the dumpdates file correctly, so
+	    do not use this feature in production until that fix
+	    is made.</para></warning>
+	</listitem>
+	
+	<listitem>
+	  <para>&man.mount.8; the snapshot as a frozen image of the file system.
+	    To &man.mount.8; the snapshot
+	    <filename>/var/snapshot/snap</filename>:</para>
+
+<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /var/snapshot/snap -u 4</userinput></screen>
+<screen>&prompt.root; <userinput>mount -r /dev/md4 /mnt</userinput></screen>
+
+	</listitem>
+      </itemizedlist>
+
+      <para>You can now walk the hierarchy of your frozen <filename>/var</filename>
+	file system mounted at <filename>/mnt</filename>.  Everything will
+	be in the same state it was during the snapshot creation time.
+	The only exception being that any earlier snapshots will appear
+	as zero length files.  When the use of a snapshot has delimited,
+	it can be unmounted with:</para>
+
+<screen>&prompt.root; <userinput>umount /mnt</userinput></screen>
+<screen>&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen>
+
+      <para>For more information about <option>softupdates</option> and
+	file system snapshots, including technical papers, you can visit
+	Marshall Kirk McKusick's website at
+	<ulink url="http://www.mckusick.com/">http://www.mckusick.com</ulink></para>
+  </sect1>
+  
   <sect1 id="quotas">
     <title>File System Quotas</title>
     <indexterm>