From 021b7c985d675d35928d1379e7ea4774908bc7f8 Mon Sep 17 00:00:00 2001 From: Thomas Nikolajsen Date: Mon, 28 Sep 2009 14:22:30 +0200 Subject: [PATCH] vnconfig.8: Describe autocloning & improve markup --- usr.sbin/vnconfig/vnconfig.8 | 168 +++++++++++++++++++++++++++++-------------- 1 file changed, 114 insertions(+), 54 deletions(-) diff --git a/usr.sbin/vnconfig/vnconfig.8 b/usr.sbin/vnconfig/vnconfig.8 index 1a13a36e8e..cf1e158068 100644 --- a/usr.sbin/vnconfig/vnconfig.8 +++ b/usr.sbin/vnconfig/vnconfig.8 @@ -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 , -- 2.11.4.GIT