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.27 2007/07/24 14:02:10 swildner Exp $ 33.\" 34.Dd July 10, 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 l Ar cpulock 54.Op Fl m Ar size 55.Op Fl n Ar numcpus 56.Op Fl p Ar file 57.Op Fl r Ar file 58.Sh DESCRIPTION 59The 60.Nm 61architecture allows for running 62.Dx 63kernels in userland. 64.Pp 65The following options are available: 66.Bl -tag -width ".Fl m Ar size" 67.It Fl c Ar file 68Specify a readonly CD-ROM image 69.Ar file 70to be used by the kernel, with the first 71.Fl c 72option defining 73.Li vcd0 , 74the second one 75.Li vcd1 , 76and so on. The first 77.Fl r 78or 79.Fl c 80option specified on the command line will be the boot disk. 81The CD9660 filesystem is assumed when booting from this media. 82.It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ... 83Specify an environment to be used by the kernel. 84.It Fl i Ar file 85Specify a memory image 86.Ar file 87to be used by the virtual kernel. 88If no 89.Fl i 90option is given, the kernel will generate a name of the form 91.Pa /var/vkernel/memimg.XXXXXX , 92with the trailing 93.Ql X Ns s 94being replaced by a sequential number, e.g.\& 95.Pa memimg.000001 . 96.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 97Create a virtual network device, with the first 98.Fl I 99option defining 100.Li vke0 , 101the second one 102.Li vke1 , 103and so on. 104.Pp 105The 106.Ar interface 107argument is the name of a 108.Xr tap 4 109device node. 110The 111.Pa /dev/ 112path prefix does not have to be specified and will be automatically prepended. 113Specifying 114.Cm auto 115will pick the first unused 116.Xr tap 4 117device. 118.Pp 119The 120.Ar address1 121and 122.Ar address2 123arguments are the IP addresses of the 124.Xr tap 4 125and 126.Nm vke 127interfaces. 128Optionally, 129.Ar address1 130may be of the form 131.Li bridge Ns Em X 132in which case the 133.Xr tap 4 134interface is added to the specified 135.Xr bridge 4 136interface. 137.Pp 138The 139.Ar netmask 140argument applies to all interfaces for which an address is specified. 141.It Fl l Ar cpulock 142Specify which, if any, real CPUs to lock virtual CPUs to. 143.Ar cpulock 144is one of 145.Cm any , 146.Cm map Ns Op Ns , Ns Ar startCPU , 147or 148.Ar CPU . 149.Pp 150.Cm any 151does not map virtual CPUs to real CPUs. 152This is the default. 153.Pp 154.Cm map Ns Op Ns , Ns Ar startCPU 155maps each virtual CPU to a real CPU starting with real CPU 0 or 156.Ar startCPU 157if specified. 158.Pp 159.Ar CPU 160locks all virtual CPUs to the real CPU specified by 161.Ar CPU . 162.It Fl m Ar size 163Specify the amount of memory to be used by the kernel in bytes, 164.Cm K 165.Pq kilobytes , 166.Cm M 167.Pq megabytes 168or 169.Cm G 170.Pq gigabytes . 171Lowercase versions of 172.Cm K , M , 173and 174.Cm G 175are allowed. 176.It Fl n Ar numcpus 177Specify the number of CPUs you wish to emulate. 178Up to 31 CPUs are supported. 179The virtual kernel must be built with 180.Cd options SMP 181to use this option and will default to 2 CPUs unless otherwise specified. 182.It Fl p Ar file 183Specify a file in which to store the process ID. 184A warning is issued if this file cannot be opened for writing. 185.It Fl r Ar file 186Specify a R/W disk image 187.Ar file 188to be used by the kernel, with the first 189.Fl r 190option defining 191.Li vkd0 , 192the second one 193.Li vkd1 , 194and so on. The first 195.Fl r 196or 197.Fl c 198option specified on the command line will be the boot disk. 199.It Fl s 200Boot into single-user mode. 201.It Fl U 202Enable writing to kernel memory and module loading. 203By default, those are disabled for security reasons. 204.It Fl v 205Turn on verbose booting. 206.El 207.Sh DEVICES 208A number of virtual device drivers exist to supplement the virtual kernel. 209Their names start with 210.Li vk . 211.Ss Disk device 212The 213.Nm vkd 214driver allows for up to 16 215.Xr vn 4 216based disk devices. 217The root device will be 218.Li vkd0 219(see 220.Sx EXAMPLES 221for further information on how to prepare a root image). 222.Ss Network interface 223The 224.Nm vke 225driver supports up to 16 virtual network interfaces which are associated with 226.Xr tap 4 227devices on the host. 228For each 229.Nm vke 230device, the per-interface read only 231.Xr sysctl 3 232variable 233.Va hw.vke Ns Em X Ns Va .tap_unit 234holds the unit number of the associated 235.Xr tap 4 236device. 237.Sh SIGNALS 238The virtual kernel only enables 239.Dv SIGQUIT 240and 241.Dv SIGTERM 242while operating in regular console mode. 243Sending 244.Ql \&^\e 245.Pq Dv SIGQUIT 246to the virtual kernel causes the virtual kernel to enter its internal 247.Xr ddb 4 248debugger and re-enable all other terminal signals. 249Sending 250.Dv SIGTERM 251to the virtual kernel triggers a clean shutdown by passing a 252.Dv SIGUSR2 253to the virtual kernel's 254.Xr init 8 255process. 256.Sh DEBUGGING 257It is possible to directly gdb the virtual kernel's process. 258It is recommended that you do a 259.Ql handle SIGSEGV noprint 260to ignore page faults processed by the virtual kernel itself. 261.Sh EXAMPLES 262A couple of steps are necessary in order to prepare the system to build and 263run a virtual kernel. 264.Ss Setting up the filesystem 265The 266.Nm 267architecture needs a number of files which reside in 268.Pa /var/vkernel . 269Since these files tend to get rather big and the 270.Pa /var 271partition is usually of limited size, we recommend the directory to be 272created in the 273.Pa /home 274partition with a link to it in 275.Pa /var : 276.Bd -literal 277mkdir /home/var.vkernel 278ln -s /home/var.vkernel /var/vkernel 279.Ed 280.Pp 281Next, a filesystem image to be used by the virtual kernel has to be 282created and populated (assuming world has been built previously): 283.Bd -literal 284dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048 285vnconfig -c -s labels vn0 /var/vkernel/rootimg.01 286disklabel -r -w vn0s0 auto 287disklabel -e vn0s0 # edit the label to create a vn0s0a partition 288newfs /dev/vn0s0a 289mount /dev/vn0s0a /mnt 290cd /usr/src 291make installworld DESTDIR=/mnt 292cd etc 293make distribution DESTDIR=/mnt 294echo '/dev/vkd0a / ufs rw 1 1' >/mnt/etc/fstab 295.Ed 296.Pp 297Edit 298.Pa /mnt/etc/ttys 299and replace the 300.Li console 301entry with the following line and turn off all other gettys. 302.Bd -literal 303console "/usr/libexec/getty Pc" cons25 on secure 304.Ed 305.Pp 306Then, unmount the disk. 307.Bd -literal 308umount /mnt 309vnconfig -u vn0 310.Ed 311.Ss Compiling the virtual kernel 312In order to compile a virtual kernel use the 313.Li VKERNEL 314kernel configuration file residing in 315.Pa /usr/src/sys/config 316(or a configuration file derived thereof): 317.Bd -literal 318cd /usr/src 319make -DNO_MODULES buildkernel KERNCONF=VKERNEL 320.Ed 321.Ss Enabling virtual kernel operation 322A special 323.Xr sysctl 8 , 324.Va vm.vkernel_enable , 325must be set to enable 326.Nm 327operation: 328.Bd -literal 329sysctl vm.vkernel_enable=1 330.Ed 331.Ss Configuring the network on the host system 332In order to access a network interface of the host system from the 333.Nm , 334you must add the interface to a 335.Xr bridge 4 336device which will then be passed to the 337.Fl I 338option: 339.Bd -literal 340kldload if_bridge.ko 341kldload if_tap.ko 342ifconfig bridge0 create 343ifconfig bridge0 addm re0 # assuming re0 is the host's interface 344ifconfig bridge0 up 345.Ed 346.Ss Running the kernel 347Finally, the virtual kernel can be run: 348.Bd -literal 349cd /usr/obj/usr/src/sys/VKERNEL 350\&./kernel.debug -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0 351.Ed 352.Pp 353The 354.Xr reboot 8 355command can be used to stop a virtual kernel. 356.Sh BUILDING THE WORLD UNDER A VKERNEL 357The virtual kernel platform does not have all the header files expected 358by a world build, so the easiest thing to do right now is to specify a 359pc32 target when building the world under a virtual kernel, like this: 360.Bd -literal 361vkernel# make MACHINE_PLATFORM=pc32 buildworld 362vkernel# make MACHINE_PLATFORM=pc32 installworld 363.Ed 364.Sh SEE ALSO 365.Xr bridge 4 , 366.Xr tap 4 , 367.Xr vn 4 , 368.Xr build 7 , 369.Xr disklabel 8 , 370.Xr ifconfig 8 , 371.Xr vnconfig 8 372.Sh HISTORY 373Virtual kernels were introduced in 374.Dx 1.7 . 375.Sh AUTHORS 376.An -nosplit 377.An Matt Dillon 378thought up and implemented the 379.Nm 380architecture and wrote the 381.Nm vkd 382device driver. 383.An Sepherosa Ziehau 384wrote the 385.Nm vke 386device driver. 387This manual page was written by 388.An Sascha Wildner . 389