1.\" $OpenBSD: mount_vnd.8,v 1.19 2011/04/18 16:52:11 thib Exp $ 2.\" 3.\" Copyright (c) 1993 University of Utah. 4.\" Copyright (c) 1980, 1989, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" the Systems Programming Group of the University of Utah Computer 9.\" Science Department. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 3. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)vnconfig.8 8.1 (Berkeley) 6/5/93 36.\" 37.\" 38.\" Copyright (c) 2007 Alexander von Gernler <grunk@openbsd.org> 39.\" 40.\" Permission to use, copy, modify, and distribute this software for any 41.\" purpose with or without fee is hereby granted, provided that the above 42.\" copyright notice and this permission notice appear in all copies. 43.\" 44.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 45.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 46.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 47.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 48.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 49.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 50.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 51.\" 52.Dd $Mdocdate: April 18 2011 $ 53.Dt MOUNT_VND 8 54.Os 55.Sh NAME 56.Nm mount_vnd , 57.Nm vnconfig 58.Nd configure vnode disks 59.Sh SYNOPSIS 60.Nm mount_vnd 61.Bk -words 62.Op Fl k 63.Op Fl K Ar rounds 64.Op Fl o Ar options 65.Op Fl S Ar saltfile 66.Op Fl t Ar disktype 67.Ar image 68.Ar vnd_dev 69.Ek 70.Nm vnconfig 71.Bk -words 72.Op Fl ckluv 73.Op Fl K Ar rounds 74.Op Fl S Ar saltfile 75.Op Fl t Ar disktype 76.Ar vnd_dev 77.Ar image 78.Ek 79.Sh DESCRIPTION 80The 81.Nm vnconfig 82command configures vnode pseudo disk devices. 83It will associate (or disassociate) the special file 84.Ar vnd_dev 85with the regular file 86.Ar image , 87allowing the latter to be accessed as though it were a disk. 88.Pp 89.Nm mount_vnd 90works similarly to 91.Nm vnconfig , 92but it provides an interface that can be used by the 93.Xr fstab 5 94infrastructure, so that an 95.Ar image 96file can be configured to a device 97.Ar node 98while booting. 99.Nm mount_vnd 100defaults to the 101.Pa vnd0 102device. 103.Pp 104For 105.Xr fstab 5 106lines with type 107.Dq ffs , 108the 109.Dq noauto 110option must be set to prevent a 111.Xr mount 8 112of the FFS partitions 113before the necessary vnd devices are configured. 114Also, the 115.Dq fs_passno 116field has to be set to 0 to prevent 117.Xr fsck 8 118from checking the file system for the same reasons. 119.Pp 120.Nm mount_vnd 121is invoked by 122.Xr mount 8 123when using the following syntax: 124.Bd -ragged -offset 4n 125.Nm mount Op options 126-t vnd 127.Ar image Ar node 128.Ed 129.Pp 130The options are as follows: 131.Bl -tag -width Ds 132.It Fl c 133.Nm vnconfig 134only. 135Configures the device. 136If successful, references to 137.Ar vnd_dev 138will access the contents of 139.Ar image . 140This is the default operation. 141.It Fl K Ar rounds 142Associate an encryption key with the device. 143All data will be encrypted using the Blowfish cipher before it is 144written to the disk. 145The user is asked for both a passphrase and the name of a salt file. 146The salt file can also be specified on the command line using the 147.Fl S 148option. 149The passphrase and salt are combined according to PKCS #5 PBKDF2 for the 150specified number of 151rounds to generate the actual key used. 152.Ar rounds 153is a number between 1000 and 154.Dv INT_MAX . 155DO NOT LOSE THE SALT FILE. 156Encryption only works with 157.Pa vnd . 158.It Fl k 159Associate an encryption key with the device. 160All data will be encrypted using the Blowfish cipher before it is 161written to the disk. 162Encryption only works with 163.Pa vnd . 164.It Fl l 165.Nm vnconfig 166only. 167List the vnd devices and indicate which ones are in use. 168If a specific 169.Ar vnd_dev 170is given, then only that one will be described. 171.It Fl o Ar options 172.Nm mount_vnd 173only. 174Options are specified with a 175.Fl o 176flag followed by a comma separated string of options. 177See the 178.Xr mount 8 179man page for possible options and their meanings. 180.Pp 181At the moment, 182.Fl o 183is only here for compatibility reasons, but no use is made of supplied 184options. 185.It Fl S Ar saltfile 186When 187.Fl K 188is used, specify the 189.Pa saltfile . 190.It Fl t Ar disktype 191Specify a 192.Ar disktype 193entry from the 194.Xr disktab 5 195database. 196The 197.Ar vnd_dev 198will have the sector size, sectors per track, and tracks per cylinder values 199of the specified 200.Ar disktype . 201The defaults are 512-byte sectors, 100 sectors per track and 1 track per 202cylinder. 203.It Fl u 204.Nm vnconfig 205only. 206Unconfigures a 207.Ar vnd_dev . 208.It Fl v 209.Nm vnconfig 210only. 211Print messages to stdout describing actions taken. 212.El 213.Sh FILES 214.Bl -tag -width /etc/rvnd?? -compact 215.It Pa /dev/{,r}vnd* 216.El 217.Sh EXAMPLES 218Configure a CD-ROM or DVD image file as vnode disk vnd0 219and mount the ISO 9660 file system contained in it: 220.Bd -literal -offset indent 221# vnconfig vnd0 /tmp/diskimage 222# mount -t cd9660 /dev/vnd0c /mnt 223.Ed 224.Pp 225Configure an encrypted image file as vnode disk vnd0 and mount the FFS 226file system contained in the 227.Sq a 228partition of the disklabel. 229The encryption key does not echo and must be entered every time 230the vnode disk is configured. 231.Bd -literal -offset indent 232# vnconfig -k vnd0 /tmp/cryptimg 233Encryption key: 234# mount /dev/vnd0a /mnt 235.Ed 236.Pp 237An equivalent 238.Xr fstab 5 239entry is: 240.Bd -literal -offset indent 241/tmp/cryptimg /dev/vnd0c vnd rw,noauto,-k 0 0 242/dev/vnd0a /mnt ffs rw,noauto 0 0 243.Ed 244.Pp 245Same as above, but now configure the vnode using PKCS #5 PBKDF2 and 246a salt file with 20000 rounds: 247.Bd -literal -offset indent 248# vnconfig -K 20000 vnd0 /tmp/cryptimg 249Encryption key: 250Salt file: /tmp/cryptsalt 251# mount /dev/vnd0a /mnt 252.Ed 253.Pp 254An equivalent 255.Xr fstab 5 256entry is: 257.Bd -literal -offset indent 258/tmp/cryptimg /dev/vnd0c vnd rw,noauto,-K=20000 0 0 259/dev/vnd0a /mnt ffs rw,noauto 0 0 260.Ed 261.Pp 262Unmount the file system and unconfigure the vnode device: 263.Bd -literal -offset indent 264# umount /mnt 265# vnconfig -u vnd0 266.Ed 267.Pp 268A sample of commands to put in 269.Xr rc.local 8 270in order to have vnd images configured at boot time is listed here: 271.Bd -literal -offset indent 272# Example for automatically configuring a vnd device on startup 273echo "configuring vnd devices:" 274mount /dev/vnd0c 275fsck -p /dev/rvnd0a 276mount /mnt 277.Ed 278.Pp 279Mounting images during the first pass of 280.Xr fsck 8 281and 282.Xr mount 8 283is not possible, because the image to be configured to a vnd itself 284resides on a file system that first has to be checked and mounted. 285.Sh SEE ALSO 286.Xr vnd 4 , 287.Xr disktab 5 , 288.Xr fstab 5 , 289.Xr mount 8 , 290.Xr swapon 8 , 291.Xr umount 8 292.Sh HISTORY 293The 294.Nm 295command first appeared in 296.Ox 4.2 . 297.Sh CAVEATS 298The 299.Sq c 300partition of a vnd image should not be used. 301When a superblock becomes damaged, 302.Xr fsck_ffs 8 303needs information contained in the disklabel 304to determine the location of alternate superblocks. 305This information is not available when directly using the 306.Sq c 307partition, 308so checking the file system image will fail. 309.Pp 310Swapping to vnd devices is no longer supported. 311