vnconfig.8: Describe autocloning & improve markup
authorThomas Nikolajsen <thomas@dragonflybsd.org>
Mon, 28 Sep 2009 12:22:30 +0000 (14:22 +0200)
committerThomas Nikolajsen <thomas@dragonflybsd.org>
Mon, 28 Sep 2009 17:25:45 +0000 (19:25 +0200)
usr.sbin/vnconfig/vnconfig.8

index 1a13a36..cf1e158 100644 (file)
@@ -38,7 +38,7 @@
 .\" $FreeBSD: src/usr.sbin/vnconfig/vnconfig.8,v 1.14.2.8 2003/01/04 22:35:53 keramida Exp $
 .\" $DragonFly: src/usr.sbin/vnconfig/vnconfig.8,v 1.10 2008/07/27 22:36:01 thomas Exp $
 .\"
-.Dd January 30, 2008
+.Dd September 28, 2009
 .Dt VNCONFIG 8
 .Os
 .Sh NAME
@@ -71,9 +71,9 @@ with the regular file
 .Ar regular_file
 allowing the latter to be accessed as though it were a disk.
 Hence a regular file within the filesystem can be used for swapping
-or can contain a filesystem that is mounted in the name space.  If you
-want to use swap backing store for your device instead of a file, you
-can leave
+or can contain a filesystem that is mounted in the name space.
+If you want to use swap backing store for your device instead of a file,
+you can leave
 .Ar regular_file
 out and specify the size of the block device
 with the
@@ -91,6 +91,14 @@ If successful, references to
 .Ar special_file
 will access the contents of
 .Ar regular_file .
+.Pp
+A
+.Nm vn
+device is autocloned if
+.Ar special_file
+is given as
+.Pa vn ,
+the name of the resulting device is printed on stdout.
 .It Fl d
 Disable (if possible) the specified feature.
 .It Fl e
@@ -102,13 +110,15 @@ If no feature was specified,
 is the same as
 .Fl c .
 .It Fl f Ar config_file
-Use
-.Ar config_file
-as an alternate config file.
+Specify configuration file.
+Default is
+.Pa /etc/vntab .
 .It Fl g
 Fiddle global options.
 .It Fl l Ar special_file Ar ...
-List the VN devices and indicate which ones are in use.
+List the
+.Nm vn
+devices and indicate which ones are in use.
 If a
 .Ar special_file
 list is given, only those devices will be described.
@@ -117,32 +127,41 @@ Reset
 .Ar options ,
 which is a comma separated string of options.
 The list of allowed options and their meanings are:
-.Bl -tag -width "follow"
-.It Ar reserve
-Pre-reserve the blocks underlying the file or swap backing store.  Currently only
-works for swap backing store.  This option also disables on-the-fly freeing of
+.Bl -tag -width "reserve"
+.It Cm reserve
+Pre-reserve the blocks underlying the file or swap backing store.
+Currently only works for swap backing store.
+This option also disables on-the-fly freeing of
 the underlying backing store (for example, when you remove a large file).
 Use this option if you wish to avoid long-term fragmentation of the backing
-store.  Also note that when this option is used, the initial contents of the
-backing store may contain garbage rather than zeros.  It may even be possible to
-recover the prior contents of a swap-backed VN across a reboot if the VN device
+store.
+Also note that when this option is used, the initial contents of the
+backing store may contain garbage rather than zeros.
+It may even be possible to
+recover the prior contents of a swap-backed
+.Nm vn
+across a reboot if the
+.Nm vn
+device
 is configured before any swap is allocated by the system.
-.It Ar follow
-debug flow in the
+.It Cm follow
+Debug flow in the
 .Xr vn 4
 driver.
-.It Ar debug
-debug data in the
+.It Cm debug
+Debug data in the
 .Xr vn 4
 driver.
-.It Ar io
-debug I/O in the
+.It Cm io
+Debug
+.Tn I/O
+in the
 .Xr vn 4
 driver.
-.It Ar all
-turn on all options.
-.It Ar none
-turn off all options.
+.It Cm all
+Turn on all options.
+.It Cm none
+Turn off all options.
 .El
 .It Fl s Ar options
 Set
@@ -158,20 +177,29 @@ option.
 .En Cm k , m , g , t
 .Sm on
 .Xc
-If no regular file is specified, VN will use swap for backing store.
-This option specifies the size of the device.  For example,
+If no regular file is specified,
+.Nm vn
+will use swap for backing store.
+This option specifies the size of the device.
+For example,
 .Sq 23m
 for
 23 megabytes.
 In the absence of a size modifier,
 .Cm m
 is implied.
-The VN device will round the size up to a machine page boundary.
-Filesystems up to 7.9 terabytes are supported.  When specified along with
+The
+.Nm vn
+device will round the size up to a machine page boundary.
+Filesystems up to 7.9 terabytes are supported.
+When specified along with
 a regular file, this option overrides the regular file's size insofar as
-VN is concerned.
+.Nm vn
+is concerned.
 .It Fl T
-When a regular file is specified, VN will
+When a regular file is specified,
+.Nm
+will
 .Fn ftruncate
 the file to length 0 first.
 Normally you should also specify the
@@ -182,9 +210,11 @@ This option is only meaningful if the
 .Fl S
 option has been specified.
 .It Fl Z
-When a regular file is specified, VN will zero the contents of the file to
-ensure that all blocks have been allocated by the filesystem.  This option is
-only meaningful if the
+When a regular file is specified,
+.Nm
+will zero the contents of the file to
+ensure that all blocks have been allocated by the filesystem.
+This option is only meaningful if the
 .Fl S
 option has been specified.
 .It Fl u
@@ -203,27 +233,28 @@ argument specifies a feature that can be enabled via the
 .Fl e
 option:
 .Bl -tag -width indent
-.It Dv swap
+.It Cm swap
 Swapping is enabled on the special file.
 See
 .Xr swapon 2 .
-.It Dv mountro Ns = Ns Pa mount_point
+.It Cm mountro= Ns Ar mount_point
 The special file is mounted read-only on
 .Ar mount_point .
 See
 .Xr mount 2 .
-.It Dv mountrw Ns = Ns Pa mount_point
+.It Cm mountrw= Ns Ar mount_point
 The special file is mounted read-write on
 .Ar mount_point .
 See
 .Xr mount 2 .
-.It Dv mount Ns = Ns Pa mount_point
-Same as ``mountrw=''.
+.It Cm mount= Ns Ar mount_point
+Same as
+.Cm mountrw= Ns Ar mount_point .
 .El
 .Pp
 A configuration file contains one line per device/file pair in the form:
 .Bd -literal
-       special_file    regular_file    [ feature ]
+       special_file    regular_file    [feature]
 .Ed
 .Pp
 where fields are separated by white space.
@@ -237,6 +268,12 @@ default configuration file for
 option
 .El
 .Sh EXAMPLES
+.Dl vnconfig vn /tmp/diskimage
+.Pp
+Configures an autocloned vnode disk,
+the name of the resulting device is printed, e.g.\&
+.Pa vn4 .
+.Pp
 .Dl vnconfig vn0 /tmp/diskimage
 .Pp
 Configures the vnode disk
@@ -272,31 +309,54 @@ Configures and enables all devices specified in
 .Dl disklabel -r -w vn0s0 auto
 .Dl disklabel -e vn0s0
 .Pp
-Is an example of how to configure a file-backed VN disk with a disk label
-and to initialize and then edit the label.  Once you create the label, you
-can partition your VN disk and, for example, create a filesystem on one of
-the partitions.  If you are using a file as backing store, it may be possible
-to recover your VN disk after a crash by vnconfig'ing the same file again
-and using the VN configuration already stored in the file rather than
-relabeling and recreating the filesystem.  It is even possible to fsck the
-VN partitions that previously contained filesystems.
+Is an example of how to configure a file-backed
+.Nm vn
+disk with a disk label
+and to initialize and then edit the label.
+Once you create the label, you
+can partition your
+.Nm vn
+disk and, for example, create a filesystem on one of the partitions.
+If you are using a file as backing store, it may be possible
+to recover your
+.Nm vn
+disk after a crash by
+.Nm Ns 'ing
+the same file again and using the
+.Nm vn
+configuration already stored in the file rather than
+relabeling and recreating the filesystem.
+It is even possible to
+.Xr fsck 8
+the
+.Nm vn
+partitions that previously contained filesystems.
 .Pp
 .Dl vnconfig -e -s reserve -S 400m vn1
 .Dl disklabel -r -w vn1s0 auto
 .Dl newfs /dev/vn1s0
 .Dl mount /dev/vn1s0 /usr/obj
 .Pp
-Is an example of a swap-backed VN disk configuration.  This example assumes
+Is an example of a swap-backed
+.Nm vn
+disk configuration.
+This example assumes
 that you have at least 400 megabytes of swap free (and hopefully much more).
 The swap space is pre-reserved in order to maintain maximum performance.
 We then label the disk, newfs it, and mount it as
 .Pa /usr/obj .
-Swap-backed VN
-devices are recoverable after a crash if you (A) use the reserve option, and if
+Swap-backed
+.Nm vn
+devices are recoverable after a crash if you (A) use the
+.Cm reserve
+option, and if
 (B) the same swap is reserved as was the last time, meaning that such
-vnconfig's would have to be run in your rc.local.  In general, though, you
-only use swap-backed VN devices to hold information you don't mind losing
-on every reboot.
+.Nm Ns 's
+would have to be run in your
+.Xr rc.local 8 .
+In general, though, you only use swap-backed
+.Nm vn
+devices to hold information you don't mind losing on every reboot.
 .Sh SEE ALSO
 .Xr mount 2 ,
 .Xr swapon 2 ,