1.\" $NetBSD: vnconfig.8,v 1.50 2023/10/21 23:42:03 gdt Exp $ 2.\" 3.\" Copyright (c) 1997 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" Copyright (c) 1993 University of Utah. 31.\" Copyright (c) 1980, 1989, 1991, 1993 32.\" The Regents of the University of California. All rights reserved. 33.\" 34.\" This code is derived from software contributed to Berkeley by 35.\" the Systems Programming Group of the University of Utah Computer 36.\" Science Department. 37.\" 38.\" Redistribution and use in source and binary forms, with or without 39.\" modification, are permitted provided that the following conditions 40.\" are met: 41.\" 1. Redistributions of source code must retain the above copyright 42.\" notice, this list of conditions and the following disclaimer. 43.\" 2. Redistributions in binary form must reproduce the above copyright 44.\" notice, this list of conditions and the following disclaimer in the 45.\" documentation and/or other materials provided with the distribution. 46.\" 3. Neither the name of the University nor the names of its contributors 47.\" may be used to endorse or promote products derived from this software 48.\" without specific prior written permission. 49.\" 50.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 51.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 52.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 53.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 54.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 55.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 56.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 57.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 58.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 59.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 60.\" SUCH DAMAGE. 61.\" 62.\" @(#)vnconfig.8 8.1 (Berkeley) 6/5/93 63.\" 64.Dd October 20, 2023 65.Dt VNDCONFIG 8 66.Os 67.Sh NAME 68.Nm vndconfig 69.Nd configure vnode disks 70.Sh SYNOPSIS 71.Nm 72.\" Fcf:lm:rt:uvz 73.Op Fl cirvz 74.Op Fl f Ar disktab 75.Op Fl t Ar typename 76.Ar vnode_disk 77.Ar regular_file 78.Op Ar geomspec 79.Nm 80.Fl u 81.Op Fl Fv 82.Ar vnode_disk 83.Nm 84.Fl l 85.Op Fl m Ar min 86.Op Ar vnode_disk ... 87.Sh DESCRIPTION 88The 89.Nm 90command configures vnode pseudo disk devices. 91It will associate the vnode disk 92.Ar vnode_disk 93with the regular file 94.Ar regular_file 95allowing the latter to be accessed as though it were a disk. 96Hence a regular file within the filesystem can be used for swapping 97or can contain a filesystem that is mounted in the name space. 98The 99.Ar vnode_disk 100is a special file of raw partition or name of vnode disk like 101.Pa vnd0 . 102.Pp 103By default, accesses to the file bypass normal mechanisms and thus 104do not read from or fill the filesystem cache. 105Because the typical approach is to access the file only via 106.Xr vnd 4 , 107or at least to have regular accesses and 108.Xr vnd 4 109accesses separated in time, this is generally not problematic. 110This bypassing behavior results in not updating the modification 111timestamp of the file. 112Also, file contents read through the filesystem (and thus the 113filesystem's caching layer) may not be the contents written via this 114interface, so caution is in order for backups. 115The 116.Fl i 117option may be useful if it is necessary to avoid inconsistent caching. 118.Pp 119Options indicate an action to be performed: 120.Bl -tag -width indent 121.It Fl c 122Configures the device. 123If successful, references to 124.Ar vnode_disk 125will access the contents of 126.Ar regular_file . 127.Pp 128If 129.Ar geomspec 130is specified, the vnode device will emulate the specified disk geometry. 131The format of the 132.Ar geomspec 133argument is: 134.Bd -ragged -offset indent 135.Sm off 136.Xo Ar secsize Li / Ar nsectors Li / 137.Ar ntracks Li / Ar ncylinders Xc 138.Sm on 139.Ed 140.Pp 141If geometry is not specified, the kernel will choose a default based on 1MB 142cylinders. 143.Ar secsize 144is the number of bytes per sector. 145It must be a power of two, and at least 512. 146.Ar nsectors 147is the number of sectors per track. 148.Ar ntracks 149is the number of tracks per cylinder. 150.Ar ncylinders 151is the number of cylinders in the device. 152.It Fl F 153Force unconfiguration if the device is in use. 154Does not imply 155.Fl u . 156.It Fl f Ar disktab 157Specifies that the 158.Fl t 159option should look up in 160.Ar disktab 161instead of in 162.Pa /etc/disktab . 163.It Fl i 164Configure the device to use regular file I/O even when direct I/O using 165bmap/strategy would be possible. 166.It Fl l 167List the vnd devices and indicate which ones are in use. 168If one or more specific 169.Ar vnode_disks 170are given, then only those will be described. 171.It Fl m Ar min 172Together with 173.Fl l 174and if no specific devices are given, 175causes at least 176.Ar min 177devices to be listed. 178The default for 179.Ar min 180is 4, 181but all vnd devices up to (and sometimes just beyond) 182the highest numbered vnd device configured since 183the system last booted will be listed. 184If 185.Ar min 186is set to 0, 187then only vnd devices currently in use will be shown. 188.It Fl r 189Configure the device as read-only. 190.It Fl t Ar typename 191If configuring the device, look up 192.Ar typename 193in 194.Pa /etc/disktab 195and use the geometry specified in the entry. 196This option and the 197.Ar geomspec 198argument are mutually exclusive. 199.It Fl u 200Unconfigures the device. 201.It Fl v 202Print messages to stdout describing actions taken. 203.It Fl z 204Assume that 205.Ar regular_file 206is a compressed disk image in cloop2 format, and configure it 207read-only. 208See the 209.Xr vndcompress 1 210manpage on how to create such an image. 211.El 212.Pp 213If no action option 214.Op Fl clu 215is given, 216.Fl c 217is assumed. 218.Sh FILES 219.Bl -tag -width /etc/disktab -compact 220.It Pa /dev/rvnd?? 221.It Pa /dev/vnd?? 222.It Pa /etc/disktab 223.El 224.Sh EXIT STATUS 225.Nm 226will exit with status 0 if the operation requested 227completed successfully, 228or 1 otherwise. 229Unsuccessful completion can be caused by unknown or 230incorrectly used options; 231attempting to configure a vnd that is already configured; 232or unconfigure one that is not, or without 233.Fl F , 234one which is still in use; 235or if devices are specified that do not exist or are not 236.Xr vnd 4 237devices, giving an improper geometry, etc. 238.Sh EXAMPLES 239.Dl vndconfig vnd0 /tmp/diskimage 240or 241.Dl vndconfig /dev/rvnd0c /tmp/diskimage 242.Pp 243Configures the vnode disk 244.Pa vnd0 . 245Please note that use of the second form of the command is discouraged because 246it requires knowledge of the raw partition which varies between architectures. 247For the first form, be aware that there must not be a file 248.Ar vnd0 249in the current directory, or it will be assumed to be the vnd device to 250be configured (which will usually fail.) 251.Pp 252.Dl vndconfig vnd0 /tmp/floppy.img 512/18/2/80 253.Pp 254Configures the vnode disk 255.Pa vnd0 256emulating the geometry of 512 bytes per sector, 18 sectors per track, 2572 tracks per cylinder, and 80 cylinders total. 258.Pp 259.Dl vndconfig vnd0 /tmp/image.udf 2048/1/1/0 260.Pp 261Configures the vnode disk 262.Pa vnd0 263for an UDF image to be used with 264.Xr mount_udf 8 . 265.Pp 266.Dl vndconfig -t floppy vnd0 /tmp/floppy.img 267.Pp 268Configures the vnode disk 269.Pa vnd0 270using the geometry specified in the 271.Pa floppy 272entry in 273.Pa /etc/disktab . 274.Pp 275.Dl vndconfig -u vnd0 276.Pp 277Unconfigures the 278.Pa vnd0 279device. 280.Pp 281To obtain status on all vnd devices listed in 282.Pa /dev 283(assuming a system where the 284.Sq d 285partition is the whole device 286.Pq Dv RAW_PART ) , 287use: 288.Pp 289.Dl vndconfig -l /dev/vnd*d 290.Pp 291Using 292.Dl vndconfig -m0 -l /dev/vnd*d 293will omit those devices that are not in use, whereas 294.Dl vndconfig -l 295will list all devices known to the kernel (at least 4 296without 297.Fl m ) 298regardless of what might appear in 299.Pa /dev 300(or elsewhere.) 301.Sh SEE ALSO 302.Xr vndcompress 1 , 303.Xr opendisk 3 , 304.Xr vnd 4 , 305.Xr mount 8 , 306.Xr swapctl 8 , 307.Xr umount 8 308.Sh HISTORY 309The 310.Nm vnconfig 311command appeared in 312.Nx 1.0 . 313It was renamed to 314.Nm 315in 316.Nx 7.0 317for consistency with other similar commands. 318(The original name was also retained as an alternative 319for backwards compatibility.) 320