[Midnightbsd-cvs] src: man/man4: add geom_uzip(4) man page
laffer1 at midnightbsd.org
laffer1 at midnightbsd.org
Sun Mar 29 12:30:12 EDT 2009
Log Message:
-----------
add geom_uzip(4) man page
Modified Files:
--------------
src/share/man/man4:
Makefile (r1.13 -> r1.14)
geom.4 (r1.1.1.1 -> r1.2)
geom_fox.4 (r1.1.1.1 -> r1.2)
Added Files:
-----------
src/share/man/man4:
geom_uzip.4 (r1.1)
-------------- next part --------------
Index: geom.4
===================================================================
RCS file: /home/cvs/src/share/man/man4/geom.4,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -L share/man/man4/geom.4 -L share/man/man4/geom.4 -u -r1.1.1.1 -r1.2
--- share/man/man4/geom.4
+++ share/man/man4/geom.4
@@ -32,29 +32,38 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/share/man/man4/geom.4,v 1.13 2005/06/15 13:31:22 ru Exp $
+.\" $FreeBSD: src/share/man/man4/geom.4,v 1.16 2006/05/25 13:39:27 ceri Exp $
.\"
-.Dd March 27, 2002
+.Dd May 25, 2006
.Os
.Dt GEOM 4
.Sh NAME
.Nm GEOM
-.Nd modular disk I/O request transformation framework.
+.Nd "modular disk I/O request transformation framework"
.Sh DESCRIPTION
-The GEOM framework provides an infrastructure in which "classes"
+The
+.Nm
+framework provides an infrastructure in which
+.Dq classes
can perform transformations on disk I/O requests on their path from
the upper kernel to the device drivers and back.
.Pp
-Transformations in a GEOM context range from the simple geometric
+Transformations in a
+.Nm
+context range from the simple geometric
displacement performed in typical disk partitioning modules over RAID
algorithms and device multipath resolution to full blown cryptographic
protection of the stored data.
.Pp
-Compared to traditional "volume management", GEOM differs from most
+Compared to traditional
+.Dq "volume management" ,
+.Nm
+differs from most
and in some cases all previous implementations in the following ways:
.Bl -bullet
.It
-GEOM is extensible.
+.Nm
+is extensible.
It is trivially simple to write a new class
of transformation and it will not be given stepchild treatment.
If
@@ -62,10 +71,11 @@
recognizing and configuring their VTOC information would be a trivial
matter.
.It
-GEOM is topologically agnostic.
+.Nm
+is topologically agnostic.
Most volume management implementations
have very strict notions of how classes can fit together, very often
-one fixed hierarchy is provided for instance subdisk - plex -
+one fixed hierarchy is provided, for instance, subdisk - plex -
volume.
.El
.Pp
@@ -74,34 +84,56 @@
.Pp
Fixed hierarchies are bad because they make it impossible to express
the intent efficiently.
-In the fixed hierarchy above it is not possible to mirror two
+In the fixed hierarchy above, it is not possible to mirror two
physical disks and then partition the mirror into subdisks, instead
one is forced to make subdisks on the physical volumes and to mirror
-these two and two resulting in a much more complex configuration.
-GEOM on the other hand does not care in which order things are done,
+these two and two, resulting in a much more complex configuration.
+.Nm
+on the other hand does not care in which order things are done,
the only restriction is that cycles in the graph will not be allowed.
-.Pp
-.Sh "TERMINOLOGY and TOPOLOGY"
-GEOM is quite object oriented and consequently the terminology
+.Sh "TERMINOLOGY AND TOPOLOGY"
+.Nm
+is quite object oriented and consequently the terminology
borrows a lot of context and semantics from the OO vocabulary:
.Pp
-A "class", represented by the data structure g_class implements one
+A
+.Dq class ,
+represented by the data structure
+.Vt g_class
+implements one
particular kind of transformation.
Typical examples are MBR disk
partition, BSD disklabel, and RAID5 classes.
.Pp
-An instance of a class is called a "geom" and represented by the
-data structure "g_geom".
-In a typical i386 FreeBSD system, there
+An instance of a class is called a
+.Dq geom
+and represented by the data structure
+.Vt g_geom .
+In a typical i386
+.Fx
+system, there
will be one geom of class MBR for each disk.
.Pp
-A "provider", represented by the data structure "g_provider", is
-the front gate at which a geom offers service.
-A provider is "a disk-like thing which appears in /dev" - a logical
+A
+.Dq provider ,
+represented by the data structure
+.Vt g_provider ,
+is the front gate at which a geom offers service.
+A provider is
+.Do
+a disk-like thing which appears in
+.Pa /dev
+.Dc - a logical
disk in other words.
-All providers have three main properties: name, sectorsize and size.
-.Pp
-A "consumer" is the backdoor through which a geom connects to another
+All providers have three main properties:
+.Dq name ,
+.Dq sectorsize
+and
+.Dq size .
+.Pp
+A
+.Dq consumer
+is the backdoor through which a geom connects to another
geom provider and through which I/O requests are sent.
.Pp
The topological relationship between these entities are as follows:
@@ -126,7 +158,7 @@
assigned as follows:
.Bl -enum
.It
-A geom with no attached consumers has rank=1
+A geom with no attached consumers has rank=1.
.It
A geom with attached consumers has a rank one higher than the
highest rank of the geoms of the providers its consumers are
@@ -137,74 +169,83 @@
to a provider, and detach, which breaks the bond, a number of special
topological maneuvers exists to facilitate configuration and to
improve the overall flexibility.
-.Pp
-.Em TASTING
+.Bl -inset
+.It Em TASTING
is a process that happens whenever a new class or new provider
-is created and it provides the class a chance to automatically configure an
-instance on providers, which it recognize as its own.
+is created, and it provides the class a chance to automatically configure an
+instance on providers which it recognizes as its own.
A typical example is the MBR disk-partition class which will look for
-the MBR table in the first sector and if found and validated it will
+the MBR table in the first sector and, if found and validated, will
instantiate a geom to multiplex according to the contents of the MBR.
.Pp
A new class will be offered to all existing providers in turn and a new
provider will be offered to all classes in turn.
.Pp
Exactly what a class does to recognize if it should accept the offered
-provider is not defined by GEOM, but the sensible set of options are:
+provider is not defined by
+.Nm ,
+but the sensible set of options are:
.Bl -bullet
.It
Examine specific data structures on the disk.
.It
-Examine properties like sectorsize or mediasize for the provider.
+Examine properties like
+.Dq sectorsize
+or
+.Dq mediasize
+for the provider.
.It
Examine the rank number of the provider's geom.
.It
Examine the method name of the provider's geom.
.El
-.Pp
-.Em ORPHANIZATION
+.It Em ORPHANIZATION
is the process by which a provider is removed while
it potentially is still being used.
.Pp
When a geom orphans a provider, all future I/O requests will
-"bounce" on the provider with an error code set by the geom.
+.Dq bounce
+on the provider with an error code set by the geom.
Any
consumers attached to the provider will receive notification about
-the orphanization when the eventloop gets around to it, and they
+the orphanization when the event loop gets around to it, and they
can take appropriate action at that time.
.Pp
A geom which came into being as a result of a normal taste operation
-should selfdestruct unless it has a way to keep functioning lacking
-the orphaned provider.
-Geoms like diskslicers should therefore selfdestruct whereas
-RAID5 or mirror geoms will be able to continue, as long as they do
-not loose quorum.
+should self-destruct unless it has a way to keep functioning whilst
+lacking the orphaned provider.
+Geoms like disk slicers should therefore self-destruct whereas
+RAID5 or mirror geoms will be able to continue as long as they do
+not lose quorum.
.Pp
When a provider is orphaned, this does not necessarily result in any
immediate change in the topology: any attached consumers are still
attached, any opened paths are still open, any outstanding I/O
requests are still outstanding.
.Pp
-The typical scenario is
+The typical scenario is:
+.Pp
.Bl -bullet -offset indent -compact
.It
A device driver detects a disk has departed and orphans the provider for it.
.It
The geoms on top of the disk receive the orphanization event and
-orphans all their providers in turn.
-Providers, which are not attached to, will typically self-destruct
+orphan all their providers in turn.
+Providers which are not attached to will typically self-destruct
right away.
This process continues in a quasi-recursive fashion until all
-relevant pieces of the tree has heard the bad news.
+relevant pieces of the tree have heard the bad news.
.It
Eventually the buck stops when it reaches geom_dev at the top
of the stack.
.It
-Geom_dev will call destroy_dev(9) to stop any more request from
+Geom_dev will call
+.Xr destroy_dev 9
+to stop any more requests from
coming in.
-It will sleep until all (if any) outstanding I/O requests have
+It will sleep until any and all outstanding I/O requests have
been returned.
-It will explicitly close (ie: zero the access counts), a change
+It will explicitly close (i.e.: zero the access counts), a change
which will propagate all the way down through the mesh.
It will then detach and destroy its geom.
.It
@@ -218,93 +259,120 @@
While this approach seems byzantine, it does provide the maximum
flexibility and robustness in handling disappearing devices.
.Pp
-The one absolutely crucial detail to be aware is that if the
+The one absolutely crucial detail to be aware of is that if the
device driver does not return all I/O requests, the tree will
not unravel.
-.Pp
-.Em SPOILING
+.It Em SPOILING
is a special case of orphanization used to protect
against stale metadata.
It is probably easiest to understand spoiling by going through
an example.
.Pp
-Imagine a disk, "da0" on top of which a MBR geom provides
-"da0s1" and "da0s2" and on top of "da0s1" a BSD geom provides
-"da0s1a" through "da0s1e", both the MBR and BSD geoms have
+Imagine a disk,
+.Pa da0 ,
+on top of which an MBR geom provides
+.Pa da0s1
+and
+.Pa da0s2 ,
+and on top of
+.Pa da0s1
+a BSD geom provides
+.Pa da0s1a
+through
+.Pa da0s1e ,
+and that both the MBR and BSD geoms have
autoconfigured based on data structures on the disk media.
-Now imagine the case where "da0" is opened for writing and those
-data structures are modified or overwritten: Now the geoms would
+Now imagine the case where
+.Pa da0
+is opened for writing and those
+data structures are modified or overwritten: now the geoms would
be operating on stale metadata unless some notification system
can inform them otherwise.
.Pp
-To avoid this situation, when the open of "da0" for write happens,
-all attached consumers are told about this, and geoms like
-MBR and BSD will selfdestruct as a result.
-When "da0" is closed again, it will be offered for tasting again
-and if the data structures for MBR and BSD are still there, new
+To avoid this situation, when the open of
+.Pa da0
+for write happens,
+all attached consumers are told about this and geoms like
+MBR and BSD will self-destruct as a result.
+When
+.Pa da0
+is closed, it will be offered for tasting again
+and, if the data structures for MBR and BSD are still there, new
geoms will instantiate themselves anew.
.Pp
Now for the fine print:
.Pp
If any of the paths through the MBR or BSD module were open, they
-would have opened downwards with an exclusive bit rendering it
-impossible to open "da0" for writing in that case and conversely
+would have opened downwards with an exclusive bit thus rendering it
+impossible to open
+.Pa da0
+for writing in that case.
+Conversely,
the requested exclusive bit would render it impossible to open a
-path through the MBR geom while "da0" is open for writing.
+path through the MBR geom while
+.Pa da0
+is open for writing.
.Pp
From this it also follows that changing the size of open geoms can
only be done with their cooperation.
.Pp
Finally: the spoiling only happens when the write count goes from
-zero to non-zero and the retasting only when the write count goes
+zero to non-zero and the retasting happens only when the write count goes
from non-zero to zero.
-.Pp
-.Em INSERT/DELETE
-are a very special operation which allows a new geom
+.It Em INSERT/DELETE
+are very special operations which allow a new geom
to be instantiated between a consumer and a provider attached to
each other and to remove it again.
.Pp
-To understand the utility of this, imagine a provider with
+To understand the utility of this, imagine a provider
being mounted as a file system.
-Between the DEVFS geoms consumer and its provider we insert
+Between the DEVFS geom's consumer and its provider we insert
a mirror module which configures itself with one mirror
copy and consequently is transparent to the I/O requests
on the path.
We can now configure yet a mirror copy on the mirror geom,
request a synchronization, and finally drop the first mirror
copy.
-We have now in essence moved a mounted file system from one
+We have now, in essence, moved a mounted file system from one
disk to another while it was being used.
At this point the mirror geom can be deleted from the path
-again, it has served its purpose.
-.Pp
-.Em CONFIGURE
+again; it has served its purpose.
+.It Em CONFIGURE
is the process where the administrator issues instructions
for a particular class to instantiate itself.
There are multiple
-ways to express intent in this case, a particular provider can be
-specified with a level of override forcing for instance a BSD
+ways to express intent in this case - a particular provider may be
+specified with a level of override forcing, for instance, a BSD
disklabel module to attach to a provider which was not found palatable
during the TASTE operation.
.Pp
-Finally IO is the reason we even do this: it concerns itself with
+Finally, I/O is the reason we even do this: it concerns itself with
sending I/O requests through the graph.
-.Pp
-.Em "I/O REQUESTS
-represented by struct bio, originate at a consumer,
-are scheduled on its attached provider, and when processed, returned
+.It Em "I/O REQUESTS" ,
+represented by
+.Vt "struct bio" ,
+originate at a consumer,
+are scheduled on its attached provider and, when processed, are returned
to the consumer.
-It is important to realize that the struct bio which
-enters through the provider of a particular geom does not "come
-out on the other side".
+It is important to realize that the
+.Vt "struct bio"
+which enters through the provider of a particular geom does not
+.Do
+come out on the other side
+.Dc .
Even simple transformations like MBR and BSD will clone the
-struct bio, modify the clone, and schedule the clone on their
+.Vt "struct bio" ,
+modify the clone, and schedule the clone on their
own consumer.
-Note that cloning the struct bio does not involve cloning the
-actual data area specified in the IO request.
-.Pp
-In total four different IO requests exist in GEOM: read, write,
-delete, and get attribute.
+Note that cloning the
+.Vt "struct bio"
+does not involve cloning the
+actual data area specified in the I/O request.
+.Pp
+In total, four different I/O requests exist in
+.Nm :
+read, write, delete, and
+.Dq "get attribute".
.Pp
Read and write are self explanatory.
.Pp
@@ -320,24 +388,32 @@
request and consequently there is no guarantee that the data actually
will be erased or made unavailable unless guaranteed by specific
geoms in the graph.
-If "secure delete" semantics are required, a
+If
+.Dq "secure delete"
+semantics are required, a
geom should be pushed which converts delete indications into (a
sequence of) write requests.
.Pp
-Get attribute supports inspection and manipulation
+.Dq "Get attribute"
+supports inspection and manipulation
of out-of-band attributes on a particular provider or path.
-Attributes are named by ascii strings and they will be discussed in
+Attributes are named by
+.Tn ASCII
+strings and they will be discussed in
a separate section below.
+.El
.Pp
-(stay tuned while the author rests his brain and fingers: more to come.)
+(Stay tuned while the author rests his brain and fingers: more to come.)
.Sh DIAGNOSTICS
-Several flags are provided for tracing GEOM operations and unlocking
+Several flags are provided for tracing
+.Nm
+operations and unlocking
protection mechanisms via the
.Va kern.geom.debugflags
sysctl.
All of these flags are off by default, and great care should be taken in
turning them on.
-.Bl -tag -width FAIL
+.Bl -tag -width indent
.It 0x01 Pq Dv G_T_TOPOLOGY
Provide tracing of topology change events.
.It 0x02 Pq Dv G_T_BIO
@@ -350,22 +426,29 @@
This would, for example, allow the super-user to overwrite the MBR on the root
disk or write random sectors elsewhere to a mounted disk.
The implications are obvious.
-.It 0x20 Pq Dv G_T_DETAILS
-This appears to be unused at this time.
.It 0x40 Pq Dv G_F_DISKIOCTL
-This appears to be unused at this time.
+This is unused at this time.
.It 0x80 Pq Dv G_F_CTLDUMP
Dump contents of gctl requests.
.El
.Sh HISTORY
-This software was developed for the FreeBSD Project by Poul-Henning Kamp
+This software was developed for the
+.Fx
+Project by
+.An Poul-Henning Kamp
and NAI Labs, the Security Research Division of Network Associates, Inc.\&
-under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
+under DARPA/SPAWAR contract N66001-01-C-8035
+.Pq Dq CBOSS ,
+as part of the
DARPA CHATS research program.
.Pp
-The first precursor for GEOM was a gruesome hack to Minix 1.2 and was
+The first precursor for
+.Nm
+was a gruesome hack to Minix 1.2 and was
never distributed.
An earlier attempt to implement a less general scheme
-in FreeBSD never succeeded.
+in
+.Fx
+never succeeded.
.Sh AUTHORS
.An "Poul-Henning Kamp" Aq phk at FreeBSD.org
--- /dev/null
+++ share/man/man4/geom_uzip.4
@@ -0,0 +1,106 @@
+.\"
+.\" Copyright (c) 2006 Ceri Davies
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD: src/share/man/man4/geom_uzip.4,v 1.2 2006/10/09 12:50:16 ceri Exp $
+.\"
+.Dd October 9, 2006
+.Os
+.Dt GEOM_UZIP 4
+.Sh NAME
+.Nm geom_uzip
+.Nd "GEOM based compressed disk images"
+.Sh SYNOPSIS
+To compile this driver into the kernel,
+place the following line in your
+kernel configuration file:
+.Bd -ragged -offset indent
+.Cd "options GEOM_UZIP"
+.Ed
+.Pp
+Alternatively, to load the driver as a
+module at boot time, place the following line in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+geom_uzip_load="YES"
+.Ed
+.Sh DESCRIPTION
+The
+.Nm
+framework provides support for compressed read only
+disk images.
+This allows significant storage savings at the expense of
+a little CPU time on each read.
+Data written in the GEOM label area allows
+.Nm
+to detect compressed images which have been created with
+.Xr mkuzip 8
+and presented to the kernel as a logical disk device via
+.Xr md 4 .
+.Nm
+creates a unique
+.Pa md#.uzip
+device for each image.
+.Pp
+The
+.Nm
+device is subsequently used by the
+.Fx
+kernel to access the disk images.
+The
+.Nm
+driver does not allow write operations to the underlying disk image.
+To check which
+.Xr md 4
+devices match a given
+.Nm
+device:
+.Bd -literal -offset indent
+# geom uzip list
+Geom name: md1.uzip
+Providers:
+1. Name: md1.uzip
+ Mediasize: 22003712 (21M)
+ Sectorsize: 512
+ Mode: r1w0e1
+Consumers:
+1. Name: md1
+ Mediasize: 9563648 (9.1M)
+ Sectorsize: 512
+ Mode: r1w0e1
+.Ed
+.Pp
+.Sh SEE ALSO
+.Xr GEOM 4 ,
+.Xr md 4 ,
+.Xr geom 8 ,
+.Xr mkuzip 8
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+driver was written by
+.An "Max Khon" Aq fjoe at FreeBSD.org .
+This manual page was written by
+.An "Ceri Davies" Aq ceri at FreeBSD.org .
Index: Makefile
===================================================================
RCS file: /home/cvs/src/share/man/man4/Makefile,v
retrieving revision 1.13
retrieving revision 1.14
diff -L share/man/man4/Makefile -L share/man/man4/Makefile -u -r1.13 -r1.14
--- share/man/man4/Makefile
+++ share/man/man4/Makefile
@@ -91,6 +91,7 @@
gem.4 \
geom.4 \
geom_fox.4 \
+ geom_uzip.4 \
gif.4 \
gre.4 \
harp.4 \
Index: geom_fox.4
===================================================================
RCS file: /home/cvs/src/share/man/man4/geom_fox.4,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -L share/man/man4/geom_fox.4 -L share/man/man4/geom_fox.4 -u -r1.1.1.1 -r1.2
--- share/man/man4/geom_fox.4
+++ share/man/man4/geom_fox.4
@@ -23,7 +23,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/share/man/man4/geom_fox.4,v 1.1.2.1 2006/01/10 18:08:55 wilko Exp $
+.\" $FreeBSD: src/share/man/man4/geom_fox.4,v 1.3 2006/09/30 15:14:48 ru Exp $
.\"
.Dd January 2, 2005
.Os
@@ -32,34 +32,47 @@
.Nm geom_fox
.Nd "GEOM based basic disk multipathing"
.Sh SYNOPSIS
-.Cd "kldload geom_fox"
+To compile this driver into the kernel,
+place the following line in your
+kernel configuration file:
+.Bd -ragged -offset indent
+.Cd "options GEOM_FOX"
+.Ed
+.Pp
+Alternatively, to load the driver as a
+module at boot time, place the following line in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+geom_fox_load="YES"
+.Ed
.Sh DESCRIPTION
The intent of the
-.Nm
+.Nm
framework is to provide basic multipathing support to access direct
access devices.
Basic in the above sentence should be read as:
.Nm
only provides path failover functionality, not load balancing over
-the available paths etc.
-Using suitable hardware like SCSI or FibreChannel disks it is
-possible to have multiple (typically 2) host bus adapters access
+the available paths etc.
+Using suitable hardware like SCSI or FibreChannel disks it is
+possible to have multiple (typically 2) host bus adapters access
the same physical disk drive.
.Pp
Without a multipathing driver the
.Fx
kernel would probe the disks multiple times, resulting in the creation of
-multiple
+multiple
.Pa /dev
entries for the same underlying physical device.
A unique label written in the GEOM label area allows
-.Nm
-to detect multiple paths. Using this information it creates a unique
+.Nm
+to detect multiple paths.
+Using this information it creates a unique
.Pa da#.fox
device.
.Pp
-The
-.Nm
+The
+.Nm
device is subsequently used by the
.Fx
kernel to access the disks.
@@ -68,14 +81,14 @@
kernel can continue to access the data.
.Pp
The
-.Nm
-driver will disallow write operations to the underlying devices once the
+.Nm
+driver will disallow write operations to the underlying devices once the
fox device has been opened for writing.
.Sh EXAMPLES
.Pp
.Bl -bullet -compact
.It
-.Nm
+.Nm
needs a label on the disk as follows in order to work properly:
.Bd -literal
"0123456789abcdef0123456789abcdef"
@@ -83,21 +96,21 @@
.Ed
.Pp
For the unique ID 16 bytes are available.
-The
-.Li GEOM::FOX
+The
+.Dq Li GEOM::FOX
is the magic to mark a
.Nm
device.
.Pp
The actual labelling is accomplished by
-.Bd -literal
+.Bd -literal
echo "GEOM::FOX someid" | dd of=/dev/da2 conv=sync
.Ed
.Pp
For FibreChannel devices it is suggested to use the Node World Wide
Name (Node WWN) as this is guaranteed by the FibreChannel standard to
be worldwide unique.
-The use of the Port WWN not recommended as each port of a given
+The use of the Port WWN not recommended as each port of a given
device has a different WWN, thereby confusing things.
.Pp
The Node WWN can be obtained from a verbose boot as in for example
@@ -108,7 +121,7 @@
.Ed
.Pp
This Node WWN would then be used like so:
-.Bd -literal
+.Bd -literal
echo "GEOM::FOX 20000004cfc8aca2" | dd of=/dev/da2 conv=sync
.Ed
.Pp
@@ -121,7 +134,7 @@
module is loaded the kernel will inform you that it has found a new
.Nm
device with a message similar to
-.Bd -literal
+.Bd -literal
Creating new fox (da2)
fox da2.fox lock 0xfffffc0000fdba20
.Ed
@@ -164,12 +177,12 @@
.Xr GEOM 4 ,
.Xr geom 8
.Sh CAVEATS
-The
-.Nm
+The
+.Nm
driver depends on the underlying hardware drivers to do the right thing in case
of a path failure.
If for example a hardware driver continues to retry forever,
-.Nm
+.Nm
is not able to re-initiate the I/O to an alternative physical path.
.Pp
You have to be very sure to provide a unique label for each of the
@@ -177,8 +190,16 @@
devices.
Safety belts are not provided.
For FibreChannel devices it is suggested to use the Port WWN of the device.
-The World Wide Name is guaranteed to be worldwide unique per the
+The World Wide Name is guaranteed to be worldwide unique per the
FibreChannel standard.
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+driver was written by
+.An "Poul-Henning Kamp" Aq phk at FreeBSD.org .
+This manual page was written by
+.An "Wilko Bulte" Aq wilko at FreeBSD.org .
.Sh BUGS
The
.Nm
@@ -191,11 +212,3 @@
Just remember that any sly fox has multiple exits from its hole.
.Pp
The examples provided are too FibreChannel-centric.
-.Sh AUTHORS
-.An -nosplit
-The
-.Nm
-driver was written by
-.An "Poul-Henning Kamp" Aq phk at FreeBSD.org .
-This manual page was written by
-.An "Wilko Bulte" Aq wilko at FreeBSD.org .
More information about the Midnightbsd-cvs
mailing list