1.\" 2.\" Copyright (c) 2003, 2004, 2005, 2006, 2007 3.\" The DragonFly Project. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 3. Neither the name of The DragonFly Project nor the names of its 16.\" contributors may be used to endorse or promote products derived 17.\" from this software without specific, prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $DragonFly: src/share/man/man7/vkernel.7,v 1.21 2007/06/23 20:52:41 swildner Exp $ 33.\" 34.Dd June 14, 2007 35.Dt VKERNEL 7 36.Os 37.Sh NAME 38.Nm vkernel , 39.Nm vkd , 40.Nm vke 41.Nd virtual kernel architecture 42.Sh SYNOPSIS 43.Cd "platform vkernel" 44.Cd "device vkd" 45.Cd "device vke" 46.Pp 47.Pa /usr/obj/usr/src/sys/VKERNEL/kernel.debug 48.Op Fl sUv 49.Op Fl c Ar file 50.Op Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ... 51.Op Fl i Ar file 52.Op Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 53.Op Fl m Ar size 54.Op Fl p Ar file 55.Op Fl r Ar file 56.Sh DESCRIPTION 57The 58.Nm 59architecture allows for running 60.Dx 61kernels in userland. 62.Pp 63The following options are available: 64.Bl -tag -width ".Fl m Ar size" 65.It Fl c Ar file 66Specify a readonly CD-ROM image 67.Ar file 68to be used by the kernel, with the first 69.Fl c 70option defining 71.Li vcd0 , 72the second one 73.Li vcd1 , 74and so on. The first 75.Fl r 76or 77.Fl c 78option specified on the command line will be the boot disk. 79The CD9660 filesystem is assumed when booting from this media. 80.It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ... 81Specify an environment to be used by the kernel. 82.It Fl i Ar file 83Specify a memory image 84.Ar file 85to be used by the virtual kernel. 86If no 87.Fl i 88option is given, the kernel will generate a name of the form 89.Pa /var/vkernel/memimg.XXXXXX , 90with the trailing 91.Ql X Ns s 92being replaced by a sequential number, e.g.\& 93.Pa memimg.000001 . 94.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 95Create a virtual network device, with the first 96.Fl I 97option defining 98.Li vke0 , 99the second one 100.Li vke1 , 101and so on. 102.Pp 103The 104.Ar interface 105argument is the name of a 106.Xr tap 4 107device node. 108The 109.Pa /dev/ 110path prefix does not have to be specified and will be automatically prepended. 111Specifying 112.Cm auto 113will pick the first unused 114.Xr tap 4 115device. 116.Pp 117The 118.Ar address1 119and 120.Ar address2 121arguments are the IP addresses of the 122.Xr tap 4 123and 124.Nm vke 125interfaces. 126Optionally, 127.Ar address1 128may be of the form 129.Li bridge Ns Em X 130in which case the 131.Xr tap 4 132interface is added to the specified 133.Xr bridge 4 134interface. 135.Pp 136The 137.Ar netmask 138argument applies to all interfaces for which an address is specified. 139.It Fl m Ar size 140Specify the amount of memory to be used by the kernel in bytes, 141.Cm K 142.Pq kilobytes , 143.Cm M 144.Pq megabytes 145or 146.Cm G 147.Pq gigabytes . 148Lowercase versions of 149.Cm K , M , 150and 151.Cm G 152are allowed. 153.It Fl p Ar file 154Specify a file in which to store the process ID. 155A warning is issued if this file cannot be opened for writing. 156.It Fl r Ar file 157Specify a R/W disk image 158.Ar file 159to be used by the kernel, with the first 160.Fl r 161option defining 162.Li vkd0 , 163the second one 164.Li vkd1 , 165and so on. The first 166.Fl r 167or 168.Fl c 169option specified on the command line will be the boot disk. 170.It Fl s 171Boot into single-user mode. 172.It Fl U 173Enable writing to kernel memory and module loading. 174By default, those are disabled for security reasons. 175.It Fl v 176Turn on verbose booting. 177.El 178.Sh DEVICES 179A number of virtual device drivers exist to supplement the virtual kernel. 180Their names start with 181.Li vk . 182.Ss Disk device 183The 184.Nm vkd 185driver allows for up to 16 186.Xr vn 4 187based disk devices. 188The root device will be 189.Li vkd0 190(see 191.Sx EXAMPLES 192for further information on how to prepare a root image). 193.Ss Network interface 194The 195.Nm vke 196driver supports up to 16 virtual network interfaces which are associated with 197.Xr tap 4 198devices on the host. 199For each 200.Nm vke 201device, the per-interface read only 202.Xr sysctl 3 203variable 204.Va hw.vke Ns Em X Ns Va .tap_unit 205holds the unit number of the associated 206.Xr tap 4 207device. 208.Sh SIGNALS 209The virtual kernel only enables 210.Dv SIGQUIT 211and 212.Dv SIGTERM 213while operating in regular console mode. 214Sending 215.Ql \&^\e 216.Pq Dv SIGQUIT 217to the virtual kernel causes the virtual kernel to enter its internal 218.Xr ddb 4 219debugger and re-enable all other terminal signals. 220Sending 221.Dv SIGTERM 222to the virtual kernel triggers a clean shutdown by passing a 223.Dv SIGUSR2 224to the virtual kernel's 225.Xr init 8 226process. 227.Sh DEBUGGING 228It is possible to directly gdb the virtual kernel's process. 229It is recommended that you do a 230.Ql handle SIGSEGV noprint 231to ignore page faults processed by the virtual kernel itself. 232.Sh EXAMPLES 233A couple of steps are necessary in order to prepare the system to build and 234run a virtual kernel. 235.Ss Setting up the filesystem 236The 237.Nm 238architecture needs a number of files which reside in 239.Pa /var/vkernel . 240Since these files tend to get rather big and the 241.Pa /var 242partition is usually of limited size, we recommend the directory to be 243created in the 244.Pa /home 245partition with a link to it in 246.Pa /var : 247.Bd -literal 248mkdir /home/var.vkernel 249ln -s /home/var.vkernel /var/vkernel 250.Ed 251.Pp 252Next, a filesystem image to be used by the virtual kernel has to be 253created and populated (assuming world has been built previously): 254.Bd -literal 255dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048 256vnconfig -c -s labels vn0 /var/vkernel/rootimg.01 257disklabel -r -w vn0s0 auto 258disklabel -e vn0s0 # edit the label to create a vn0s0a partition 259newfs /dev/vn0s0a 260mount /dev/vn0s0a /mnt 261cd /usr/src 262make installworld DESTDIR=/mnt 263cd etc 264make distribution DESTDIR=/mnt 265echo '/dev/vkd0a / ufs rw 1 1' >/mnt/etc/fstab 266.Ed 267.Pp 268Edit 269.Pa /mnt/etc/ttys 270and replace the 271.Li console 272entry with the following line and turn off all other gettys. 273.Bd -literal 274console "/usr/libexec/getty Pc" cons25 on secure 275.Ed 276.Pp 277Then, unmount the disk. 278.Bd -literal 279umount /mnt 280vnconfig -u vn0 281.Ed 282.Ss Compiling the virtual kernel 283In order to compile a virtual kernel use the 284.Li VKERNEL 285kernel configuration file residing in 286.Pa /usr/src/sys/config 287(or a configuration file derived thereof): 288.Bd -literal 289cd /usr/src 290make -DNO_MODULES buildkernel KERNCONF=VKERNEL 291.Ed 292.Ss Enabling virtual kernel operation 293A special 294.Xr sysctl 8 , 295.Va vm.vkernel_enable , 296must be set to enable 297.Nm 298operation: 299.Bd -literal 300sysctl vm.vkernel_enable=1 301.Ed 302.Ss Configuring the network on the host system 303In order to access a network interface of the host system from the 304.Nm , 305you must add the interface to a 306.Xr bridge 4 307device which will then be passed to the 308.Fl I 309option: 310.Bd -literal 311kldload if_bridge.ko 312kldload if_tap.ko 313ifconfig bridge0 create 314ifconfig bridge0 addm re0 # assuming re0 is the host's interface 315ifconfig bridge0 up 316.Ed 317.Ss Running the kernel 318Finally, the virtual kernel can be run: 319.Bd -literal 320cd /usr/obj/usr/src/sys/VKERNEL 321\&./kernel.debug -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0 322.Ed 323.Pp 324The 325.Xr reboot 8 326command can be used to stop a virtual kernel. 327.Sh SEE ALSO 328.Xr bridge 4 , 329.Xr tap 4 , 330.Xr vn 4 , 331.Xr build 7 , 332.Xr disklabel 8 , 333.Xr ifconfig 8 , 334.Xr vnconfig 8 335.Sh HISTORY 336Virtual kernels were introduced in 337.Dx 1.7 . 338.Sh AUTHORS 339.An -nosplit 340.An Matt Dillon 341thought up and implemented the 342.Nm 343architecture and wrote the 344.Nm vkd 345device driver. 346.An Sepherosa Ziehau 347wrote the 348.Nm vke 349device driver. 350This manual page was written by 351.An Sascha Wildner . 352