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 September 3, 2008 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. 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 16 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 and 271.Ql handle SIGUSR1 noprint 272to ignore signals used for simulating inter-processor interrupts (SMP build 273only). 274.Sh FILES 275.Bl -tag -width ".It Pa /sys/config/VKERNEL" -compact 276.It Pa /sys/config/VKERNEL 277default 278.Nm 279configuration file, for 280.Xr config 8 . 281.El 282.Sh EXAMPLES 283A couple of steps are necessary in order to prepare the system to build and 284run a virtual kernel. 285.Ss Setting up the filesystem 286The 287.Nm 288architecture needs a number of files which reside in 289.Pa /var/vkernel . 290Since these files tend to get rather big and the 291.Pa /var 292partition is usually of limited size, we recommend the directory to be 293created in the 294.Pa /home 295partition with a link to it in 296.Pa /var : 297.Bd -literal 298mkdir -p /home/var.vkernel/boot 299ln -s /home/var.vkernel /var/vkernel 300.Ed 301.Pp 302Next, a filesystem image to be used by the virtual kernel has to be 303created and populated (assuming world has been built previously): 304.Bd -literal 305dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048 306vnconfig -c -s labels vn0 /var/vkernel/rootimg.01 307disklabel -r -w vn0s0 auto 308disklabel -e vn0s0 # add `a' partition with fstype `4.2BSD' 309newfs /dev/vn0s0a 310mount /dev/vn0s0a /mnt 311cd /usr/src 312make installworld DESTDIR=/mnt 313cd etc 314make distribution DESTDIR=/mnt 315echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab 316echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab 317.Ed 318.Pp 319Edit 320.Pa /mnt/etc/ttys 321and replace the 322.Li console 323entry with the following line and turn off all other gettys. 324.Bd -literal 325console "/usr/libexec/getty Pc" cons25 on secure 326.Ed 327.Pp 328Then, unmount the disk. 329.Bd -literal 330umount /mnt 331vnconfig -u vn0 332.Ed 333.Ss Compiling the virtual kernel 334In order to compile a virtual kernel use the 335.Li VKERNEL 336kernel configuration file residing in 337.Pa /sys/config 338(or a configuration file derived thereof): 339.Bd -literal 340cd /usr/src 341make -DNO_MODULES buildkernel KERNCONF=VKERNEL 342make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel 343.Ed 344.Ss Enabling virtual kernel operation 345A special 346.Xr sysctl 8 , 347.Va vm.vkernel_enable , 348must be set to enable 349.Nm 350operation: 351.Bd -literal 352sysctl vm.vkernel_enable=1 353.Ed 354.Ss Configuring the network on the host system 355In order to access a network interface of the host system from the 356.Nm , 357you must add the interface to a 358.Xr bridge 4 359device which will then be passed to the 360.Fl I 361option: 362.Bd -literal 363kldload if_bridge.ko 364kldload if_tap.ko 365ifconfig bridge0 create 366ifconfig bridge0 addm re0 # assuming re0 is the host's interface 367ifconfig bridge0 up 368.Ed 369.Ss Running the kernel 370Finally, the virtual kernel can be run: 371.Bd -literal 372cd /var/vkernel 373\&./boot/kernel -m 64m -r rootimg.01 -I auto:bridge0 374.Ed 375.Pp 376You can issue the 377.Xr reboot 8 , 378.Xr halt 8 , 379or 380.Xr shutdown 8 381commands from inside a virtual kernel. 382After doing a clean shutdown the 383.Xr reboot 8 384command will re-exec the virtual kernel binary while the other two will 385cause the virtual kernel to exit. 386.Sh BUILDING THE WORLD UNDER A VKERNEL 387The virtual kernel platform does not have all the header files expected 388by a world build, so the easiest thing to do right now is to specify a 389pc32 target when building the world under a virtual kernel, like this: 390.Bd -literal 391vkernel# make MACHINE_PLATFORM=pc32 buildworld 392vkernel# make MACHINE_PLATFORM=pc32 installworld 393.Ed 394.Sh CONFIGURATION FILES 395Your virtual kernel is a complete 396.Dx 397system, but you might not want to run all the services a normal kernel runs. 398Here is what a typical virtual kernel's 399.Pa /etc/rc.conf 400file looks like, with some additional possibilities commented out. 401.Bd -literal 402hostname="vkernel" 403network_interfaces="lo0 vke0" 404ifconfig_vke0="DHCP" 405sendmail_enable="NO" 406#syslog_enable="NO" 407blanktime="NO" 408.Ed 409.Sh SEE ALSO 410.Xr bridge 4 , 411.Xr tap 4 , 412.Xr vn 4 , 413.Xr sysctl.conf 5 , 414.Xr build 7 , 415.Xr disklabel 8 , 416.Xr ifconfig 8 , 417.Xr vknetd 8 , 418.Xr vknet 1 , 419.Xr vnconfig 8 420.Rs 421.%A Aggelos Economopoulos 422.%D March 2007 423.%T "A Peek at the DragonFly Virtual Kernel" 424.Re 425.Sh HISTORY 426Virtual kernels were introduced in 427.Dx 1.7 . 428.Sh AUTHORS 429.An -nosplit 430.An Matt Dillon 431thought up and implemented the 432.Nm 433architecture and wrote the 434.Nm vkd 435device driver. 436.An Sepherosa Ziehau 437wrote the 438.Nm vke 439device driver. 440This manual page was written by 441.An Sascha Wildner . 442