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