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