doc-el commit 1089:272728385333 - Updates and fixes in the Engli...

freebsd-doc-el at lists.hellug.gr freebsd-doc-el at lists.hellug.gr
Sat Nov 29 00:02:55 EET 2008


changeset: 1089:272728385333
user:      Manolis Kiagias <sonicy at otenet.gr>
date:      2008-11-25 16:49 +0200
details:   http://hg.hellug.gr/freebsd/doc-el/?cmd=changeset;node=272728385333

description:
	Updates and fixes in the English version of 'geom' chapter (description below)
	- Add missing messages in an example
	- Avoid use of /mnt as a permanent mount point in an example
	- Convert a vi editing session to a <note>
	- Clearly explain how to create all types of labels (permanent, temporary, file system specific, non-file system specific)
	- Add a complete example: Labeling partitions on a boot disk
	- Last sector of a journaled volume stores metadata and not the log itself
	- Mention loading geom_journal at startup or building it into custom kernel
	- Add a reference to gjournal-desktop article
	- Few other minor fixes, mostly to avoid repeating information and enhance consistency

diffstat:

1 file changed, 114 insertions(+), 27 deletions(-)
en_US.ISO8859-1/books/handbook/geom/chapter.sgml |  141 +++++++++++++++++-----

diffs (235 lines):

diff -r 0bdedf593c56 -r 272728385333 en_US.ISO8859-1/books/handbook/geom/chapter.sgml
--- a/en_US.ISO8859-1/books/handbook/geom/chapter.sgml	Tue Nov 25 15:59:19 2008 +0200
+++ b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml	Tue Nov 25 16:49:07 2008 +0200
@@ -147,7 +147,7 @@
     <procedure>
       <title>Creating a stripe of unformatted ATA disks</title>
 
-      <step><para>Load the <filename>geom_stripe</filename>
+      <step><para>Load the <filename>geom_stripe.ko</filename>
         module:</para>
 
     <screen>&prompt.root; <userinput>kldload geom_stripe</userinput></screen>
@@ -167,13 +167,11 @@
 	for example <filename>/dev/ad2</filename> and
 	<filename>/dev/ad3</filename>:</para>
 
-        <screen>&prompt.root; <userinput>gstripe label -v st0 /dev/ad2 /dev/ad3</userinput></screen>
+        <screen>&prompt.root; <userinput>gstripe label -v st0 /dev/ad2 /dev/ad3</userinput>
+Metadata value stored on /dev/ad2.
+Metadata value stored on /dev/ad3.
+Done.</screen>
 
-<!-- 
-    <para>A message should be returned explaining that meta data has
-      been stored on the devices.
-XXX: What message?  Put it inside the screen output above.
--->
       </step>
 
       <step><para>Write a standard label, also known as a partition
@@ -206,12 +204,15 @@
 
   <para>To mount this striped file system automatically during the boot
     process, place the volume information in
-    <filename>/etc/fstab</filename> file:</para>
+    <filename>/etc/fstab</filename> file.  For this purpose, a permanent mount
+    point, named <filename class="directory">stripe</filename>, is
+    created:</para>
 
-  <screen>&prompt.root; <userinput>echo "/dev/stripe/st0a /mnt ufs rw 2 2" \</userinput>
+  <screen>&prompt.root; <userinput>mkdir /stripe</userinput>
+&prompt.root; <userinput>echo "/dev/stripe/st0a /stripe ufs rw 2 2" \</userinput>
     <userinput>&gt;&gt; /etc/fstab</userinput></screen>
 
-  <para>The <filename>geom_stripe</filename> module must also be automatically loaded during
+  <para>The <filename>geom_stripe.ko</filename> module must also be automatically loaded during
     system initialization, by adding a line to
     <filename>/boot/loader.conf</filename>:</para>
 
@@ -290,9 +291,11 @@
 
       <para>Edit the <filename>/etc/fstab</filename> file, replacing
 	references to the old <devicename>da0</devicename> with the
-	new device nodes of the <devicename>gm0</devicename> mirror device.
-	As the <username>root</username> user, edit the
-	<filename>/etc/fstab</filename>:</para>
+	new device nodes of the <devicename>gm0</devicename> mirror device.</para>
+
+      <note>
+	<para>If &man.vi.1; is your preferred editor, the following is
+	  an easy way to accomplish this task:</para>
 
       <screen>&prompt.root; <userinput>vi /etc/fstab</userinput></screen>
 
@@ -302,6 +305,7 @@
 	replace all old <devicename>da0</devicename> references
 	with <devicename>gm0</devicename> by typing
 	<userinput>:%s/da/mirror\/gm/g</userinput>.<para>
+      </note>
 
       <para>The resulting <filename>fstab</filename> file should look
 	similar to the following.  It does not matter if the disk
@@ -380,7 +384,9 @@
 OK? <userinput>boot</userinput></screen>
 
 	<para>If this works then for whatever reason the module was not
-	  being loaded properly.  Place:</para>
+	  being loaded properly.  Check whether the relevant entry in
+	  <filename>/boot/loader.conf</filename> is correct.  If the problem
+	  persists, place:</para>
 
 	<programlisting>options	GEOM_MIRROR</programlisting>
 
@@ -518,27 +524,30 @@
       <title>Label Types and Examples</title>
 
       <para>There are two types of labels, a generic label and a
-	file system label.  The difference between the labels is
-	the auto detection associated with permanent labels, and the
-	fact that this type of label will be persistent across reboots.
-	These labels are given a special directory in
+	file system label.  Labels can be permanent or temporary.
+	Permanent labels can be created with the &man.tunefs.8;
+	or &man.newfs.8; commands.  They will then be created
+	in a sub-directory of
 	<filename class="directory">/dev</filename>, which will be named
-	based on their file system type.  For example,
+	according to their file system type.  For example,
 	<acronym>UFS</acronym>2 file system labels will be created in
 	the <filename class="directory">/dev/ufs</filename>
-	directory.</para>
+	directory.  Permanent labels can also be created with the
+	<command>glabel label</command> command.  These are not file system
+	specific, and will be created in the <filename
+	  class="directory">/dev/label</filename> directory.</para>
 
-      <para>A generic label will go away with the next reboot. These
+      <para>A temporary label will go away with the next reboot. These
 	labels will be created in the
 	<filename class="directory">/dev/label</filename> directory and
-	are perfect for experimentation.</para>
+	are perfect for experimentation.  A temporary label can be
+	created using the <command>glabel create</command> command.  For more
+	information, please read the manual page of &man.glabel.8;.</para>
 
 <!-- XXXTR: How do you create a file system label without running newfs
             or when there is no newfs (e.g.: cd9660)? -->
 
-      <para>Permanent labels may be placed on the file system using the
-	<command>tunefs</command> or <command>newfs</command>
-	utilities.  To create a permanent label for a
+      <para>To create a permanent label for a
 	<acronym>UFS</acronym>2 file system without destroying any
 	data, issue the following command:</para>
 
@@ -582,6 +591,65 @@
 	label:</para>
 
       <screen>&prompt.root; <userinput>glabel destroy home</userinput></screen>
+
+      <para>The following example shows how to label the partitions of a
+	boot disk.</para>
+
+      <example>
+	<title>Labeling Partitions on the Boot Disk</title>
+
+	<para>By permanently labeling the partitions on the boot disk,
+	  the system should be able to continue to boot normally, even
+	  if the disk is moved to another controller or transferred
+	  to a different system.  For this example, it is assumed that a
+	  single <acronym>ATA</acronym> disk is used, which is currently
+	  recognized by the system as <devicename>ad0</devicename>.  It is
+	  also assumed that the standard &os; partition scheme is used, with
+	  <filename class="directory">/</filename>,
+	  <filename class="directory">/var</filename>,
+	  <filename class="directory">/usr</filename> and
+	  <filename class="directory">/tmp</filename> file systems, as well
+	  as a swap partition.</para>
+
+	<para>Reboot the system, and at the &man.loader.8; prompt, press
+	  <keycap>4</keycap> to boot into single user mode.  Then enter the
+	  following commands:</para>
+
+	<screen>&prompt.root; <userinput>glabel label rootfs /dev/ad0s1a</userinput>
+GEOM_LABEL: Label for provider /dev/ad0s1a is label/rootfs
+&prompt.root; <userinput>glabel label var /dev/ad0s1d</userinput>
+GEOM_LABEL: Label for provider /dev/ad0s1d is label/var
+&prompt.root; <userinput>glabel label usr /dev/ad0s1f</userinput>
+GEOM_LABEL: Label for provider /dev/ad0s1f is label/usr
+&prompt.root; <userinput>glabel label tmp /dev/ad0s1e</userinput>
+GEOM_LABEL: Label for provider /dev/ad0s1e is label/tmp
+&prompt.root; <userinput>glabel label swap /dev/ad0s1b</userinput>
+GEOM_LABEL: Label for provider /dev/ad0s1b is label/swap
+&prompt.root; <userinput>exit</userinput></screen>
+
+	<para>The system will continue with multi-user boot.  After the boot
+	  completes, edit <filename>/etc/fstab</filename> and replace the
+	  conventional device names, with their respective labels.  The
+	  final <filename>/etc/fstab</filename> file will look like the
+	  following:</para>
+
+	<programlisting># Device                Mountpoint      FStype  Options         Dump    Pass#
+/dev/label/swap         none            swap    sw              0       0
+/dev/label/rootfs       /               ufs     rw              1       1
+/dev/label/tmp          /tmp            ufs     rw              2       2
+/dev/label/usr          /usr            ufs     rw              2       2
+/dev/label/var          /var            ufs     rw              2       2</programlisting>
+
+	<para>The system can now be rebooted.  If everything went well, it
+	  will come up normally and <command>mount</command> will show:</para>
+
+	<screen>&prompt.root; <userinput>mount</userinput>
+/dev/label/rootfs on / (ufs, local)
+devfs on /dev (devfs, local)
+/dev/label/tmp on /tmp (ufs, local, soft-updates)
+/dev/label/usr on /usr (ufs, local, soft-updates)
+/dev/label/var on /var (ufs, local, soft-updates)</screen>
+      </example>
     </sect2>
   </sect1>
 
@@ -611,8 +679,9 @@
     <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
+      is an image of the file system, an actual log is stored in disk
+      space specifically reserved for this task,
+      and in some cases may be stored on another disk
       entirely.</para>
 
     <para>Unlike other file system journaling implementations, the
@@ -626,6 +695,19 @@
 
     <programlisting>options	UFS_GJOURNAL</programlisting>
 
+    <para>If journaled volumes need to be mounted during startup, the
+      <filename>geom_journal.ko</filename> kernel module will also have to be
+      loaded, by adding the following line in
+      <filename>/boot/loader.conf</filename>:</para>
+
+    <programlisting>geom_journal_load="YES"</programlisting>
+
+    <para>Alternatively, this function can also be built into a custom
+      kernel, by adding the following line in the kernel configuration
+      file:</para>
+
+    <programlisting>options	GEOM_JOURNAL</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>
@@ -669,6 +751,11 @@
       the actual journal but this does not protect against data loss
       incurred as a result of misusing
       <command>tunefs</command>.</para>
+
+    <para>It is also possible to journal the boot disk of a &os; system.
+      Please refer to the article <ulink
+	url="&url.articles.gjournal-desktop;">Implementing UFS Journaling on
+	a Desktop PC</ulink> for detailed instructions on this task.</para>
   </sect1>
 </chapter>
 




More information about the Freebsd-doc-el mailing list