1.\" 2.\" Copyright (c) 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.43 2008/09/02 22:41:19 thomas Exp $ 33.\" 34.Dd March 27, 2009 35.Dt VKERNEL 7 36.Os 37.Sh NAME 38.Nm vkernel , 39.Nm vcd , 40.Nm vkd , 41.Nm vke 42.Nd virtual kernel architecture 43.Sh SYNOPSIS 44.Cd "platform vkernel" 45.Cd "device vcd" 46.Cd "device vkd" 47.Cd "device vke" 48.Pp 49.Pa /var/vkernel/boot/kernel 50.Op Fl sUv 51.Op Fl c Ar file 52.Op Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ... 53.Op Fl i Ar file 54.Op Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 55.Op Fl l Ar cpulock 56.Op Fl m Ar size 57.Op Fl n Ar numcpus 58.Op Fl p Ar file 59.Op Fl r Ar file 60.Sh DESCRIPTION 61The 62.Nm 63architecture allows for running 64.Dx 65kernels in userland. 66.Pp 67The following options are available: 68.Bl -tag -width ".Fl m Ar size" 69.It Fl c Ar file 70Specify a readonly CD-ROM image 71.Ar file 72to be used by the kernel, with the first 73.Fl c 74option defining 75.Li vcd0 , 76the second one 77.Li vcd1 , 78and so on. 79The first 80.Fl r 81or 82.Fl c 83option specified on the command line will be the boot disk. 84The CD9660 filesystem is assumed when booting from this media. 85.It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ... 86Specify an environment to be used by the kernel. 87.It Fl i Ar file 88Specify a memory image 89.Ar file 90to be used by the virtual kernel. 91If no 92.Fl i 93option is given, the kernel will generate a name of the form 94.Pa /var/vkernel/memimg.XXXXXX , 95with the trailing 96.Ql X Ns s 97being replaced by a sequential number, e.g.\& 98.Pa memimg.000001 . 99.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 100Create a virtual network device, with the first 101.Fl I 102option defining 103.Li vke0 , 104the second one 105.Li vke1 , 106and so on. 107.Pp 108The 109.Ar interface 110argument is the name of a 111.Xr tap 4 112device node. 113The 114.Pa /dev/ 115path prefix does not have to be specified and will be automatically prepended. 116Specifying 117.Cm auto 118will pick the first unused 119.Xr tap 4 120device. 121.Pp 122The 123.Ar address1 124and 125.Ar address2 126arguments are the IP addresses of the 127.Xr tap 4 128and 129.Nm vke 130interfaces. 131Optionally, 132.Ar address1 133may be of the form 134.Li bridge Ns Em X 135in which case the 136.Xr tap 4 137interface is added to the specified 138.Xr bridge 4 139interface. 140The 141.Nm vke 142address is not assigned until the interface is brought up in the guest. 143.Pp 144The 145.Ar netmask 146argument applies to all interfaces for which an address is specified. 147.It Fl l Ar cpulock 148Specify which, if any, real CPUs to lock virtual CPUs to. 149.Ar cpulock 150is one of 151.Cm any , 152.Cm map Ns Op Ns , Ns Ar startCPU , 153or 154.Ar CPU . 155.Pp 156.Cm any 157does not map virtual CPUs to real CPUs. 158This is the default. 159.Pp 160.Cm map Ns Op Ns , Ns Ar startCPU 161maps each virtual CPU to a real CPU starting with real CPU 0 or 162.Ar startCPU 163if specified. 164.Pp 165.Ar CPU 166locks all virtual CPUs to the real CPU specified by 167.Ar CPU . 168.It Fl m Ar size 169Specify the amount of memory to be used by the kernel in bytes, 170.Cm K 171.Pq kilobytes , 172.Cm M 173.Pq megabytes 174or 175.Cm G 176.Pq gigabytes . 177Lowercase versions of 178.Cm K , M , 179and 180.Cm G 181are allowed. 182.It Fl n Ar numcpus 183Specify the number of CPUs you wish to emulate. 184Up to 16 CPUs are supported. 185The virtual kernel must be built with 186.Cd options SMP 187to use this option and will default to 2 CPUs unless otherwise specified. 188.It Fl p Ar file 189Specify a file in which to store the process ID. 190A warning is issued if this file cannot be opened for writing. 191.It Fl r Ar file 192Specify a R/W disk image 193.Ar file 194to be used by the kernel, with the first 195.Fl r 196option defining 197.Li vkd0 , 198the second one 199.Li vkd1 , 200and so on. 201The first 202.Fl r 203or 204.Fl c 205option specified on the command line will be the boot disk. 206.It Fl s 207Boot into single-user mode. 208.It Fl U 209Enable writing to kernel memory and module loading. 210By default, those are disabled for security reasons. 211.It Fl v 212Turn on verbose booting. 213.El 214.Sh DEVICES 215A number of virtual device drivers exist to supplement the virtual kernel. 216.Ss Disk device 217The 218.Nm vkd 219driver allows for up to 16 220.Xr vn 4 221based disk devices. 222The root device will be 223.Li vkd0 224(see 225.Sx EXAMPLES 226for further information on how to prepare a root image). 227.Ss CD-ROM device 228The 229.Nm vcd 230driver allows for up to 16 virtual CD-ROM devices. 231Basically this is a read only 232.Nm vkd 233device with a block size of 2048. 234.Ss Network interface 235The 236.Nm vke 237driver supports up to 16 virtual network interfaces which are associated with 238.Xr tap 4 239devices on the host. 240For each 241.Nm vke 242device, the per-interface read only 243.Xr sysctl 3 244variable 245.Va hw.vke Ns Em X Ns Va .tap_unit 246holds the unit number of the associated 247.Xr tap 4 248device. 249.Sh SIGNALS 250The virtual kernel only enables 251.Dv SIGQUIT 252and 253.Dv SIGTERM 254while operating in regular console mode. 255Sending 256.Ql \&^\e 257.Pq Dv SIGQUIT 258to the virtual kernel causes the virtual kernel to enter its internal 259.Xr ddb 4 260debugger and re-enable all other terminal signals. 261Sending 262.Dv SIGTERM 263to the virtual kernel triggers a clean shutdown by passing a 264.Dv SIGUSR2 265to the virtual kernel's 266.Xr init 8 267process. 268.Sh DEBUGGING 269It is possible to directly gdb the virtual kernel's process. 270It is recommended that you do a 271.Ql handle SIGSEGV noprint 272to ignore page faults processed by the virtual kernel itself and 273.Ql handle SIGUSR1 noprint 274to ignore signals used for simulating inter-processor interrupts (SMP build 275only). 276.Sh FILES 277.Bl -tag -width ".It Pa /sys/config/VKERNEL" -compact 278.It Pa /sys/config/VKERNEL 279default 280.Nm 281configuration file, for 282.Xr config 8 . 283.El 284.Sh EXAMPLES 285A couple of steps are necessary in order to prepare the system to build and 286run a virtual kernel. 287.Ss Setting up the filesystem 288The 289.Nm 290architecture needs a number of files which reside in 291.Pa /var/vkernel . 292Since these files tend to get rather big and the 293.Pa /var 294partition is usually of limited size, we recommend the directory to be 295created in the 296.Pa /home 297partition with a link to it in 298.Pa /var : 299.Bd -literal 300mkdir -p /home/var.vkernel/boot 301ln -s /home/var.vkernel /var/vkernel 302.Ed 303.Pp 304Next, a filesystem image to be used by the virtual kernel has to be 305created and populated (assuming world has been built previously). 306If the image is created on a UFS filesystem you might want to pre-zero it. 307On a HAMMER filesystem you should just truncate-extend to the image size 308as HAMMER does not re-use data blocks already present in the file. 309.Bd -literal 310vnconfig -c -s labels -S 2g -T vn0 /var/vkernel/rootimg.01 311disklabel -r -w vn0s0 auto 312disklabel -e vn0s0 # add `a' partition with fstype `4.2BSD' 313newfs /dev/vn0s0a 314mount /dev/vn0s0a /mnt 315cd /usr/src 316make installworld DESTDIR=/mnt 317cd etc 318make distribution DESTDIR=/mnt 319echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab 320echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab 321.Ed 322.Pp 323Edit 324.Pa /mnt/etc/ttys 325and replace the 326.Li console 327entry with the following line and turn off all other gettys. 328.Bd -literal 329console "/usr/libexec/getty Pc" cons25 on secure 330.Ed 331.Pp 332Replace 333.Li \&Pc 334with 335.Li al.Pc 336if you would like to automatically log in as root. 337.Pp 338Then, unmount the disk. 339.Bd -literal 340umount /mnt 341vnconfig -u vn0 342.Ed 343.Ss Compiling the virtual kernel 344In order to compile a virtual kernel use the 345.Li VKERNEL 346kernel configuration file residing in 347.Pa /sys/config 348(or a configuration file derived thereof): 349.Bd -literal 350cd /usr/src 351make -DNO_MODULES buildkernel KERNCONF=VKERNEL 352make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel 353.Ed 354.Ss Enabling virtual kernel operation 355A special 356.Xr sysctl 8 , 357.Va vm.vkernel_enable , 358must be set to enable 359.Nm 360operation: 361.Bd -literal 362sysctl vm.vkernel_enable=1 363.Ed 364.Ss Configuring the network on the host system 365In order to access a network interface of the host system from the 366.Nm , 367you must add the interface to a 368.Xr bridge 4 369device which will then be passed to the 370.Fl I 371option: 372.Bd -literal 373kldload if_bridge.ko 374kldload if_tap.ko 375ifconfig bridge0 create 376ifconfig bridge0 addm re0 # assuming re0 is the host's interface 377ifconfig bridge0 up 378.Ed 379.Ss Running the kernel 380Finally, the virtual kernel can be run: 381.Bd -literal 382cd /var/vkernel 383\&./boot/kernel -m 64m -r rootimg.01 -I auto:bridge0 384.Ed 385.Pp 386You can issue the 387.Xr reboot 8 , 388.Xr halt 8 , 389or 390.Xr shutdown 8 391commands from inside a virtual kernel. 392After doing a clean shutdown the 393.Xr reboot 8 394command will re-exec the virtual kernel binary while the other two will 395cause the virtual kernel to exit. 396.Sh BUILDING THE WORLD UNDER A VKERNEL 397The virtual kernel platform does not have all the header files expected 398by a world build, so the easiest thing to do right now is to specify a 399pc32 target when building the world under a virtual kernel, like this: 400.Bd -literal 401vkernel# make MACHINE_PLATFORM=pc32 buildworld 402vkernel# make MACHINE_PLATFORM=pc32 installworld 403.Ed 404.Sh CONFIGURATION FILES 405Your virtual kernel is a complete 406.Dx 407system, but you might not want to run all the services a normal kernel runs. 408Here is what a typical virtual kernel's 409.Pa /etc/rc.conf 410file looks like, with some additional possibilities commented out. 411.Bd -literal 412hostname="vkernel" 413network_interfaces="lo0 vke0" 414ifconfig_vke0="DHCP" 415sendmail_enable="NO" 416#syslog_enable="NO" 417blanktime="NO" 418.Ed 419.Sh SEE ALSO 420.Xr vknet 1 , 421.Xr bridge 4 , 422.Xr tap 4 , 423.Xr vn 4 , 424.Xr sysctl.conf 5 , 425.Xr build 7 , 426.Xr disklabel 8 , 427.Xr ifconfig 8 , 428.Xr vknetd 8 , 429.Xr vnconfig 8 430.Rs 431.%A Aggelos Economopoulos 432.%D March 2007 433.%T "A Peek at the DragonFly Virtual Kernel" 434.Re 435.Sh HISTORY 436Virtual kernels were introduced in 437.Dx 1.7 . 438.Sh AUTHORS 439.An -nosplit 440.An Matt Dillon 441thought up and implemented the 442.Nm 443architecture and wrote the 444.Nm vkd 445device driver. 446.An Sepherosa Ziehau 447wrote the 448.Nm vke 449device driver. 450This manual page was written by 451.An Sascha Wildner . 452