1.\" Copyright (c) 1993 University of Utah. 2.\" Copyright (c) 1980, 1989, 1991, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" the Systems Programming Group of the University of Utah Computer 7.\" Science Department. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)vnconfig.8 8.1 (Berkeley) 6/5/93 34.\" $FreeBSD: src/usr.sbin/vnconfig/vnconfig.8,v 1.14.2.8 2003/01/04 22:35:53 keramida Exp $ 35.\" $DragonFly: src/usr.sbin/vnconfig/vnconfig.8,v 1.10 2008/07/27 22:36:01 thomas Exp $ 36.\" 37.Dd September 28, 2009 38.Dt VNCONFIG 8 39.Os 40.Sh NAME 41.Nm vnconfig 42.Nd configure and enable vnode disks 43.Sh SYNOPSIS 44.Nm 45.Op Fl cdeguvTZ 46.Op Fl s Ar options 47.Op Fl r Ar options 48.Op Fl S Ar value 49.Ar special_file Op Ar regular_file 50.Op Ar feature 51.Nm 52.Fl a 53.Op Fl cdeguv 54.Op Fl s Ar options 55.Op Fl r Ar options 56.Op Fl f Ar config_file 57.Nm 58.Fl l 59.Op Ar special_file Ar ... 60.Sh DESCRIPTION 61The 62.Nm 63command configures, enables and lists vnode pseudo disk devices. 64The first form of the command will associate the special file 65.Ar special_file 66with the regular file 67.Ar regular_file 68allowing the latter to be accessed as though it were a disk. 69Hence a regular file within the filesystem can be used for swapping 70or can contain a filesystem that is mounted in the name space. 71If you want to use swap backing store for your device instead of a file, 72you can leave 73.Ar regular_file 74out and specify the size of the block device 75with the 76.Fl S 77option. 78.Pp 79Options indicate an action to be performed: 80.Bl -tag -width indent 81.It Fl a 82Read a command file and performs the 83specified actions for each device/file pair. 84.It Fl c 85Configure the device. 86If successful, references to 87.Ar special_file 88will access the contents of 89.Ar regular_file . 90.Pp 91A 92.Nm vn 93device is autocloned if 94.Ar special_file 95is given as 96.Pa vn , 97the name of the resulting device is printed on stdout. 98.It Fl d 99Disable (if possible) the specified feature. 100.It Fl e 101Configure the device and enables any 102.Ar feature 103that was specified. 104If no feature was specified, 105.Fl e 106is the same as 107.Fl c . 108.It Fl f Ar config_file 109Specify configuration file. 110Default is 111.Pa /etc/vntab . 112.It Fl g 113Fiddle global options. 114.It Fl l Ar special_file Ar ... 115List the 116.Nm vn 117devices and indicate which ones are in use. 118If a 119.Ar special_file 120list is given, only those devices will be described. 121.It Fl r Ar options 122Reset 123.Ar options , 124which is a comma separated string of options. 125The list of allowed options and their meanings are: 126.Bl -tag -width "reserve" 127.It Cm reserve 128Pre-reserve the blocks underlying the file or swap backing store. 129Currently only works for swap backing store. 130This option also disables on-the-fly freeing of 131the underlying backing store (for example, when you remove a large file). 132Use this option if you wish to avoid long-term fragmentation of the backing 133store. 134Also note that when this option is used, the initial contents of the 135backing store may contain garbage rather than zeros. 136It may even be possible to 137recover the prior contents of a swap-backed 138.Nm vn 139across a reboot if the 140.Nm vn 141device 142is configured before any swap is allocated by the system. 143.It Cm follow 144Debug flow in the 145.Xr vn 4 146driver. 147.It Cm debug 148Debug data in the 149.Xr vn 4 150driver. 151.It Cm io 152Debug 153.Tn I/O 154in the 155.Xr vn 4 156driver. 157.It Cm all 158Turn on all options. 159.It Cm none 160Turn off all options. 161.El 162.It Fl s Ar options 163Set 164.Ar options , 165which is a comma separated string of options. 166The list of allowed options and their meanings are the same as for the 167.Fl r 168option. 169.It Fl S Xo 170.Sm off 171.Ar value 172.Es \&{ \&} 173.En Cm k , m , g , t 174.Sm on 175.Xc 176If no regular file is specified, 177.Nm vn 178will use swap for backing store. 179This option specifies the size of the device. 180For example, 181.Sq 23m 182for 18323 megabytes. 184In the absence of a size modifier, 185.Cm m 186is implied. 187The 188.Nm vn 189device will round the size up to a machine page boundary. 190Filesystems up to 7.9 terabytes are supported. 191When specified along with 192a regular file, this option overrides the regular file's size insofar as 193.Nm vn 194is concerned. 195.It Fl T 196When a regular file is specified, 197.Nm 198will 199.Fn ftruncate 200the file to length 0 first. 201Normally you should also specify the 202.Fl S 203option to set the size of the file. 204This option also creates the file if it did not previously exist. 205This option is only meaningful if the 206.Fl S 207option has been specified. 208.It Fl Z 209When a regular file is specified, 210.Nm 211will zero the contents of the file to 212ensure that all blocks have been allocated by the filesystem. 213This option is only meaningful if the 214.Fl S 215option has been specified. 216.It Fl u 217Disable and ``unconfigure'' the device. 218.It Fl v 219Print messages to stdout describing actions taken. 220.El 221.Pp 222If no action option is given, 223.Fl c 224is assumed. 225.Pp 226The 227.Ar feature 228argument specifies a feature that can be enabled via the 229.Fl e 230option: 231.Bl -tag -width indent 232.It Cm swap 233Swapping is enabled on the special file. 234See 235.Xr swapon 2 . 236.It Cm mountro= Ns Ar mount_point 237The special file is mounted read-only on 238.Ar mount_point . 239See 240.Xr mount 2 . 241.It Cm mountrw= Ns Ar mount_point 242The special file is mounted read-write on 243.Ar mount_point . 244See 245.Xr mount 2 . 246.It Cm mount= Ns Ar mount_point 247Same as 248.Cm mountrw= Ns Ar mount_point . 249.El 250.Pp 251A configuration file contains one line per device/file pair in the form: 252.Bd -literal 253 special_file regular_file [feature] 254.Ed 255.Pp 256where fields are separated by white space. 257The previously described action options serve to configure, enable, 258disable or unconfigure all devices in the configuration file. 259.Sh FILES 260.Bl -tag -width /etc/vntab -compact 261.It Pa /etc/vntab 262default configuration file for 263.Fl a 264option 265.El 266.Sh EXAMPLES 267.Dl vnconfig vn /tmp/diskimage 268.Pp 269Configures an autocloned vnode disk, 270the name of the resulting device is printed, e.g.\& 271.Pa vn4 . 272.Pp 273.Dl vnconfig vn0 /tmp/diskimage 274.Pp 275Configures the vnode disk 276.Pa vn0 . 277.Pp 278.Dl vnconfig -e vn0 /var/swapfile swap 279.Pp 280Configures 281.Pa vn0 282and enables swapping on it. 283.Pp 284.Dl vnconfig -c -v /dev/vn0 cdimage.iso 285.Dl mount -t cd9660 -o ro /dev/vn0 /mnt 286.Pp 287Mount an ISO9660 CD image file. 288.Pp 289.Dl umount /mnt 290.Dl vnconfig -u vn0 291.Pp 292Unmount the CD image file. 293.Pp 294.Dl vnconfig -d vn0 myfilesystem mount=/mnt 295.Pp 296Unmounts (disables) 297.Pa vn0 . 298.Pp 299.Dl vnconfig -ae 300.Pp 301Configures and enables all devices specified in 302.Pa /etc/vntab . 303.Pp 304.Dl vnconfig -c vn0 somebackingfile 305.Dl disklabel -r -w vn0s0 auto 306.Dl disklabel -e vn0s0 307.Pp 308Is an example of how to configure a file-backed 309.Nm vn 310disk with a disk label 311and to initialize and then edit the label. 312Once you create the label, you 313can partition your 314.Nm vn 315disk and, for example, create a filesystem on one of the partitions. 316If you are using a file as backing store, it may be possible 317to recover your 318.Nm vn 319disk after a crash by 320.Nm Ns 'ing 321the same file again and using the 322.Nm vn 323configuration already stored in the file rather than 324relabeling and recreating the filesystem. 325It is even possible to 326.Xr fsck 8 327the 328.Nm vn 329partitions that previously contained filesystems. 330.Pp 331.Dl vnconfig -e -s reserve -S 400m vn1 332.Dl disklabel -r -w vn1s0 auto 333.Dl newfs /dev/vn1s0 334.Dl mount /dev/vn1s0 /usr/obj 335.Pp 336Is an example of a swap-backed 337.Nm vn 338disk configuration. 339This example assumes 340that you have at least 400 megabytes of swap free (and hopefully much more). 341The swap space is pre-reserved in order to maintain maximum performance. 342We then label the disk, newfs it, and mount it as 343.Pa /usr/obj . 344Swap-backed 345.Nm vn 346devices are recoverable after a crash if you (A) use the 347.Cm reserve 348option, and if 349(B) the same swap is reserved as was the last time, meaning that such 350.Nm Ns 's 351would have to be run in your 352.Xr rc.local 8 . 353In general, though, you only use swap-backed 354.Nm vn 355devices to hold information you don't mind losing on every reboot. 356.Sh SEE ALSO 357.Xr mount 2 , 358.Xr swapon 2 , 359.Xr unmount 2 , 360.Xr vn 4 361