Several updates and fixes in Handbook's 'geom' chapter:

- 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

Reviewed by:	trhodes, keramida, gabor, pgj, hrs, rene, remko
This commit is contained in:
Manolis Kiagias 2008-11-25 15:49:09 +00:00
parent 2e083712c5
commit 6f77c596ba
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=33294

View file

@ -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 @@ XXX: What message? Put it inside the screen output above.
<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 @@ Done.</screen>
<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 @@ Done.</screen>
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 @@ mountroot></programlisting>
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 @@ ggate0
<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 @@ ggate0
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 @@ ggate0
<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 @@ ggate0
<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 @@ ggate0
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>