From cbe49e9324b71dc0d7f7071fe5fe8462d8741aec Mon Sep 17 00:00:00 2001
From: Tom Rhodes <trhodes@FreeBSD.org>
Date: Wed, 18 Apr 2007 10:00:27 +0000
Subject: [PATCH] Add rudimentary section on gjournal(8), currently commented
 out but here as a documented feature for 7.X release.

Sponsored by:	AiNET Corp.
---
 .../books/handbook/geom/chapter.sgml          | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/en_US.ISO8859-1/books/handbook/geom/chapter.sgml b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml
index 2512ec0b4e..1a5f542b18 100644
--- a/en_US.ISO8859-1/books/handbook/geom/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml
@@ -447,6 +447,93 @@ OK? <userinput>boot</userinput></screen>
       unmounted with the &man.umount.8; command, similar to any other
       disk device.</para>
   </sect1>
+<!--
+  <sect1 id="geom-gjournal">
+    <title>UFS Journaling Through GEOM</title>
+    
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Disk Mirroring</primary>
+    </indexterm>
+
+    <para>With the release of &os;&nbsp;7.0, the long awaited feature
+      of <acronym>UFS</acronym> journals has been implemented.  The
+      implementation itself is provided through the
+      <acronym>GEOM</acronym> subsystem and is easily configured
+      via the &man.gjournal.8; utility.</para>
+
+    <para>What is journaling?  Journaling capability stores a log of
+      file system transactions, i.e.: changes that make up a complete
+      disk write operation, before meta-data and file writes are
+      committed to the disk proper. This transaction log can later
+      be replayed to redo file system transactions, preventing file
+      system inconsistencies.</para>
+
+    <para>This method is yet another mechanism to protect against data
+      loss and inconsistencies of the file system.  Unlike Soft Updates
+      which tracks and enforces meta-data updates and Snapshots which
+      is an image of the file system, an actual log is stored at the
+      end sector and, in some cases, may be stored on another disk
+      entirely.</para>
+
+    <para>Unlike other file system journaling implementations, the
+      <command>gjournal</command> method is block based and not
+      implemented as part of the file system - only as a
+      <acronym>GEOM</acronym> extension.</para>
+
+    <para>To enable support for <command>gjournal</command>, the
+      &os; kernel must have the following option - which is the
+      default on 7.X systems:</para>
+
+    <programlisting>options	UFS_GJOURNAL</programlisting>
+
+    <para>Creating a journal on a free file system may now be done
+      using the following steps, considering that the
+      <devicename>da4</devicename> is a new <acronym>SCSI</acronym>
+      disk:</para>
+
+    <screen>&prompt.root; <userinput>gjournal label /dev/da4</userinput>
+    <userinput>gjournal load</userinput></screen>
+
+    <para>At this point, there should be a
+      <devicename>/dev/da4</devicename> device node and a
+      <devicename>/dev/da4.journal</devicename> device node.  A
+      file system may now be created on this device:</para>
+
+    <screen>&prompt.root; <userinput>newfs -O 2 -J /dev/da4.journal</userinput></screen>
+
+    <para>The previously issued command will create a
+      <acronym>UFS</acronym>2 file system with journaling being made
+      active.
+
+    <para>Effectively <command>mount</command> the device at the
+      desired point with:</para>
+
+    <screen>&prompt.root <userinput>mount /dev/da4.journal /mnt</userinput></screen>
+
+    <note>
+      <para>In the case of several slices, a journal will be created
+	for each individual slice.  For instance, if ad4s1 and ad4s2
+	are both slices, then <command>gjournal</command> will create
+	ad4s1.journal and ad4s2.journal.  In the case of the command
+	being run twice, the result will be
+	<quote>journals</quote>.</para>
+    </note>
+
+    <para>Under some circumstances, keeping the journal on another disk
+      may be desired.  For these cases, the journal provider or storage
+      device should be listed after the device to enable journaling
+      on.  Journaling may also be enabled on current file systems by
+      using <command>tunefs</command>; however, always make a backup
+      before attempting to alter a file system.  In most cases, the
+      <command>gjournal</command> will fail if it is unable to create
+      the actual journal but this does not protect against data loss
+      incurred as a result of misusing
+      <command>tunefs</command>.</para>
+  </sect1>
+-->
 </chapter>
 
 <!--