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