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.Brq Cm k , m , g , t 173.Sm on 174.Xc 175If no regular file is specified, 176.Nm vn 177will use swap for backing store. 178This option specifies the size of the device. 179For example, 180.Sq 23m 181for 18223 megabytes. 183In the absence of a size modifier, 184.Cm m 185is implied. 186The 187.Nm vn 188device will round the size up to a machine page boundary. 189Filesystems up to 7.9 terabytes are supported. 190When specified along with 191a regular file, this option overrides the regular file's size insofar as 192.Nm vn 193is concerned. 194.It Fl T 195When a regular file is specified, 196.Nm 197will 198.Fn ftruncate 199the file to length 0 first. 200Normally you should also specify the 201.Fl S 202option to set the size of the file. 203This option also creates the file if it did not previously exist. 204This option is only meaningful if the 205.Fl S 206option has been specified. 207.It Fl Z 208When a regular file is specified, 209.Nm 210will zero the contents of the file to 211ensure that all blocks have been allocated by the filesystem. 212This option is only meaningful if the 213.Fl S 214option has been specified. 215.It Fl u 216Disable and ``unconfigure'' the device. 217.It Fl v 218Print messages to stdout describing actions taken. 219.El 220.Pp 221If no action option is given, 222.Fl c 223is assumed. 224.Pp 225The 226.Ar feature 227argument specifies a feature that can be enabled via the 228.Fl e 229option: 230.Bl -tag -width indent 231.It Cm swap 232Swapping is enabled on the special file. 233See 234.Xr swapon 2 . 235.It Cm mountro= Ns Ar mount_point 236The special file is mounted read-only on 237.Ar mount_point . 238See 239.Xr mount 2 . 240.It Cm mountrw= Ns Ar mount_point 241The special file is mounted read-write on 242.Ar mount_point . 243See 244.Xr mount 2 . 245.It Cm mount= Ns Ar mount_point 246Same as 247.Cm mountrw= Ns Ar mount_point . 248.El 249.Pp 250A configuration file contains one line per device/file pair in the form: 251.Bd -literal 252 special_file regular_file [feature] 253.Ed 254.Pp 255where fields are separated by white space. 256The previously described action options serve to configure, enable, 257disable or unconfigure all devices in the configuration file. 258.Sh FILES 259.Bl -tag -width /etc/vntab -compact 260.It Pa /etc/vntab 261default configuration file for 262.Fl a 263option 264.El 265.Sh EXAMPLES 266.Dl vnconfig vn /tmp/diskimage 267.Pp 268Configures an autocloned vnode disk, 269the name of the resulting device is printed, e.g.\& 270.Pa vn4 . 271.Pp 272.Dl vnconfig vn0 /tmp/diskimage 273.Pp 274Configures the vnode disk 275.Pa vn0 . 276.Pp 277.Dl vnconfig -e vn0 /var/swapfile swap 278.Pp 279Configures 280.Pa vn0 281and enables swapping on it. 282.Pp 283.Dl vnconfig -c -v /dev/vn0 cdimage.iso 284.Dl mount -t cd9660 -o ro /dev/vn0 /mnt 285.Pp 286Mount an ISO9660 CD image file. 287.Pp 288.Dl umount /mnt 289.Dl vnconfig -u vn0 290.Pp 291Unmount the CD image file. 292.Pp 293.Dl vnconfig -d vn0 myfilesystem mount=/mnt 294.Pp 295Unmounts (disables) 296.Pa vn0 . 297.Pp 298.Dl vnconfig -ae 299.Pp 300Configures and enables all devices specified in 301.Pa /etc/vntab . 302.Pp 303.Dl vnconfig -c vn0 somebackingfile 304.Dl disklabel -r -w vn0s0 auto 305.Dl disklabel -e vn0s0 306.Pp 307Is an example of how to configure a file-backed 308.Nm vn 309disk with a disk label 310and to initialize and then edit the label. 311Once you create the label, you 312can partition your 313.Nm vn 314disk and, for example, create a filesystem on one of the partitions. 315If you are using a file as backing store, it may be possible 316to recover your 317.Nm vn 318disk after a crash by 319.Nm Ns 'ing 320the same file again and using the 321.Nm vn 322configuration already stored in the file rather than 323relabeling and recreating the filesystem. 324It is even possible to 325.Xr fsck 8 326the 327.Nm vn 328partitions that previously contained filesystems. 329.Pp 330.Dl vnconfig -e -s reserve -S 400m vn1 331.Dl disklabel -r -w vn1s0 auto 332.Dl newfs /dev/vn1s0 333.Dl mount /dev/vn1s0 /usr/obj 334.Pp 335Is an example of a swap-backed 336.Nm vn 337disk configuration. 338This example assumes 339that you have at least 400 megabytes of swap free (and hopefully much more). 340The swap space is pre-reserved in order to maintain maximum performance. 341We then label the disk, newfs it, and mount it as 342.Pa /usr/obj . 343Swap-backed 344.Nm vn 345devices are recoverable after a crash if you (A) use the 346.Cm reserve 347option, and if 348(B) the same swap is reserved as was the last time, meaning that such 349.Nm Ns 's 350would have to be run in your 351.Xr rc.local 8 . 352In general, though, you only use swap-backed 353.Nm vn 354devices to hold information you don't mind losing on every reboot. 355.Sh SEE ALSO 356.Xr mount 2 , 357.Xr swapon 2 , 358.Xr unmount 2 , 359.Xr vn 4 360