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 May 17, 2012 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 Ns Op Ar :lbits Ns Oo Ar :cbits Oc 57.Op Fl p Ar pidfile 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. 86This option can be specified more than once. 87.It Fl h 88Shows a list of available options, each with a short description. 89.It Fl i Ar file 90Specify a memory image 91.Ar file 92to be used by the virtual kernel. 93If no 94.Fl i 95option is given, the kernel will generate a name of the form 96.Pa /var/vkernel/memimg.XXXXXX , 97with the trailing 98.Ql X Ns s 99being replaced by a sequential number, e.g.\& 100.Pa memimg.000001 . 101.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 102Create a virtual network device, with the first 103.Fl I 104option defining 105.Li vke0 , 106the second one 107.Li vke1 , 108and so on. 109.Pp 110The 111.Ar interface 112argument is the name of a 113.Xr tap 4 114device node or the path to a 115.Xr vknetd 8 116socket. 117The 118.Pa /dev/ 119path prefix does not have to be specified and will be automatically prepended 120for a device node. 121Specifying 122.Cm auto 123will pick the first unused 124.Xr tap 4 125device. 126.Pp 127The 128.Ar address1 129and 130.Ar address2 131arguments are the IP addresses of the 132.Xr tap 4 133and 134.Nm vke 135interfaces. 136Optionally, 137.Ar address1 138may be of the form 139.Li bridge Ns Em X 140in which case the 141.Xr tap 4 142interface is added to the specified 143.Xr bridge 4 144interface. 145The 146.Nm vke 147address is not assigned until the interface is brought up in the guest. 148.Pp 149The 150.Ar netmask 151argument applies to all interfaces for which an address is specified. 152.Pp 153When running multiple vkernels it is often more convenient to simply 154connect to a 155.Xr vknetd 8 156socket and let vknetd deal with the tap and/or bridge. An example of 157this would be '/var/run/vknet:0.0.0.0:10.2.0.2/16'. 158.It Fl l Ar cpulock 159Specify which, if any, real CPUs to lock virtual CPUs to. 160.Ar cpulock 161is one of 162.Cm any , 163.Cm map Ns Op Ns , Ns Ar startCPU , 164or 165.Ar CPU . 166.Pp 167.Cm any 168does not map virtual CPUs to real CPUs. 169This is the default. 170.Pp 171.Cm map Ns Op Ns , Ns Ar startCPU 172maps each virtual CPU to a real CPU starting with real CPU 0 or 173.Ar startCPU 174if specified. 175.Pp 176.Ar CPU 177locks all virtual CPUs to the real CPU specified by 178.Ar CPU . 179.It Fl m Ar size 180Specify the amount of memory to be used by the kernel in bytes, 181.Cm K 182.Pq kilobytes , 183.Cm M 184.Pq megabytes 185or 186.Cm G 187.Pq gigabytes . 188Lowercase versions of 189.Cm K , M , 190and 191.Cm G 192are allowed. 193.It Fl n Ar numcpus Ns Op Ar :lbits Ns Oo Ar :cbits Oc 194.Ar numcpus 195specifies the number of CPUs you wish to emulate. 196Up to 16 CPUs are supported with 2 being the default unless otherwise 197specified. 198.Ar lbits 199specifies the number of bits within APICID(=CPUID) needed for representing 200the logical ID. 201Controls the number of threads/core (0bits - 1 thread, 1bit - 2 threads). 202This parameter is optional (mandatory only if 203.Ar cbits 204is specified). 205.Ar cbits 206specifies the number of bits within APICID(=CPUID) needed for representing 207the core ID. 208Controls the number of core/package (0bits - 1 core, 1bit - 2 cores). 209This parameter is optional. 210.It Fl p Ar pidfile 211Specify a pidfile in which to store the process ID. 212Scripts can use this file to locate the vkernel pid for the purpose of 213shutting down or killing it. 214.Pp 215The vkernel will hold a lock on the pidfile while running. 216Scripts may test for the lock to determine if the pidfile is valid or 217stale so as to avoid accidentally killing a random process. 218Something like '/usr/bin/lockf -ks -t 0 pidfile echo -n' may be used 219to test the lock. 220A non-zero exit code indicates that the pidfile represents a running 221vkernel. 222.Pp 223An error is issued and the vkernel exits if this file cannot be opened for 224writing or if it is already locked by an active vkernel process. 225.It Fl r Ar file 226Specify a R/W disk image 227.Ar file 228to be used by the kernel, with the first 229.Fl r 230option defining 231.Li vkd0 , 232the second one 233.Li vkd1 , 234and so on. 235The first 236.Fl r 237or 238.Fl c 239option specified on the command line will be the boot disk. 240.It Fl s 241Boot into single-user mode. 242.It Fl U 243Enable writing to kernel memory and module loading. 244By default, those are disabled for security reasons. 245.It Fl v 246Turn on verbose booting. 247.El 248.Sh DEVICES 249A number of virtual device drivers exist to supplement the virtual kernel. 250.Ss Disk device 251The 252.Nm vkd 253driver allows for up to 16 254.Xr vn 4 255based disk devices. 256The root device will be 257.Li vkd0 258(see 259.Sx EXAMPLES 260for further information on how to prepare a root image). 261.Ss CD-ROM device 262The 263.Nm vcd 264driver allows for up to 16 virtual CD-ROM devices. 265Basically this is a read only 266.Nm vkd 267device with a block size of 2048. 268.Ss Network interface 269The 270.Nm vke 271driver supports up to 16 virtual network interfaces which are associated with 272.Xr tap 4 273devices on the host. 274For each 275.Nm vke 276device, the per-interface read only 277.Xr sysctl 3 278variable 279.Va hw.vke Ns Em X Ns Va .tap_unit 280holds the unit number of the associated 281.Xr tap 4 282device. 283.Sh SIGNALS 284The virtual kernel only enables 285.Dv SIGQUIT 286and 287.Dv SIGTERM 288while operating in regular console mode. 289Sending 290.Ql \&^\e 291.Pq Dv SIGQUIT 292to the virtual kernel causes the virtual kernel to enter its internal 293.Xr ddb 4 294debugger and re-enable all other terminal signals. 295Sending 296.Dv SIGTERM 297to the virtual kernel triggers a clean shutdown by passing a 298.Dv SIGUSR2 299to the virtual kernel's 300.Xr init 8 301process. 302.Sh DEBUGGING 303It is possible to directly gdb the virtual kernel's process. 304It is recommended that you do a 305.Ql handle SIGSEGV noprint 306to ignore page faults processed by the virtual kernel itself and 307.Ql handle SIGUSR1 noprint 308to ignore signals used for simulating inter-processor interrupts. 309.Sh PROFILING 310To compile a vkernel with profiling support, the 311.Va CONFIGARGS 312variable needs to be used to pass 313.Fl p 314to 315.Xr config 8 . 316.Bd -literal 317cd /usr/src 318make -DNO_MODULES CONFIGARGS=-p buildkernel KERNCONF=VKERNEL 319.Ed 320.Sh FILES 321.Bl -tag -width ".It Pa /sys/config/VKERNEL" -compact 322.It Pa /sys/config/VKERNEL 323.It Pa /sys/config/VKERNEL64 324.El 325.Pp 326Per architecture 327.Nm 328configuration files, for 329.Xr config 8 . 330.Sh CONFIGURATION FILES 331Your virtual kernel is a complete 332.Dx 333system, but you might not want to run all the services a normal kernel runs. 334Here is what a typical virtual kernel's 335.Pa /etc/rc.conf 336file looks like, with some additional possibilities commented out. 337.Bd -literal 338hostname="vkernel" 339network_interfaces="lo0 vke0" 340ifconfig_vke0="DHCP" 341sendmail_enable="NO" 342#syslog_enable="NO" 343blanktime="NO" 344.Ed 345.Sh DISKLESS OPERATION 346To boot a 347.Nm 348from a NFS root, a number of tunables need to be set: 349.Bl -tag -width indent 350.It Va boot.netif.ip 351IP address to be set in the vkernel interface. 352.It Va boot.netif.netmask 353Netmask for the IP to be set. 354.It Va boot.netif.name 355Network interface name inside the vkernel. 356.It Va boot.nfsroot.server 357Host running 358.Xr nfsd 8 . 359.It Va boot.nfsroot.path 360Host path where a world and distribution 361targets are properly installed. 362.El 363.Pp 364See an example on how to boot a diskless 365.Nm 366in the 367.Sx EXAMPLES 368section. 369.Sh EXAMPLES 370A couple of steps are necessary in order to prepare the system to build and 371run a virtual kernel. 372.Ss Setting up the filesystem 373The 374.Nm 375architecture needs a number of files which reside in 376.Pa /var/vkernel . 377Since these files tend to get rather big and the 378.Pa /var 379partition is usually of limited size, we recommend the directory to be 380created in the 381.Pa /home 382partition with a link to it in 383.Pa /var : 384.Bd -literal 385mkdir -p /home/var.vkernel/boot 386ln -s /home/var.vkernel /var/vkernel 387.Ed 388.Pp 389Next, a filesystem image to be used by the virtual kernel has to be 390created and populated (assuming world has been built previously). 391If the image is created on a UFS filesystem you might want to pre-zero it. 392On a HAMMER filesystem you should just truncate-extend to the image size 393as HAMMER does not re-use data blocks already present in the file. 394.Bd -literal 395vnconfig -c -S 2g -T vn0 /var/vkernel/rootimg.01 396disklabel -r -w vn0s0 auto 397disklabel -e vn0s0 # add `a' partition with fstype `4.2BSD' 398newfs /dev/vn0s0a 399mount /dev/vn0s0a /mnt 400cd /usr/src 401make installworld DESTDIR=/mnt 402cd etc 403make distribution DESTDIR=/mnt 404echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab 405echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab 406.Ed 407.Pp 408Edit 409.Pa /mnt/etc/ttys 410and replace the 411.Li console 412entry with the following line and turn off all other gettys. 413.Bd -literal 414console "/usr/libexec/getty Pc" cons25 on secure 415.Ed 416.Pp 417Replace 418.Li \&Pc 419with 420.Li al.Pc 421if you would like to automatically log in as root. 422.Pp 423Then, unmount the disk. 424.Bd -literal 425umount /mnt 426vnconfig -u vn0 427.Ed 428.Ss Compiling the virtual kernel 429In order to compile a virtual kernel use the 430.Li VKERNEL 431kernel configuration file residing in 432.Pa /sys/config 433(or a configuration file derived thereof): 434.Bd -literal 435cd /usr/src 436make -DNO_MODULES buildkernel KERNCONF=VKERNEL 437make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel 438.Ed 439.Ss Enabling virtual kernel operation 440A special 441.Xr sysctl 8 , 442.Va vm.vkernel_enable , 443must be set to enable 444.Nm 445operation: 446.Bd -literal 447sysctl vm.vkernel_enable=1 448.Ed 449.Ss Configuring the network on the host system 450In order to access a network interface of the host system from the 451.Nm , 452you must add the interface to a 453.Xr bridge 4 454device which will then be passed to the 455.Fl I 456option: 457.Bd -literal 458kldload if_bridge.ko 459kldload if_tap.ko 460ifconfig bridge0 create 461ifconfig bridge0 addm re0 # assuming re0 is the host's interface 462ifconfig bridge0 up 463.Ed 464.Ss Running the kernel 465Finally, the virtual kernel can be run: 466.Bd -literal 467cd /var/vkernel 468\&./boot/kernel/kernel -m 64m -r rootimg.01 -I auto:bridge0 469.Ed 470.Pp 471You can issue the 472.Xr reboot 8 , 473.Xr halt 8 , 474or 475.Xr shutdown 8 476commands from inside a virtual kernel. 477After doing a clean shutdown the 478.Xr reboot 8 479command will re-exec the virtual kernel binary while the other two will 480cause the virtual kernel to exit. 481.Ss Diskless operation 482Booting a 483.Nm 484with a 485.Xr vknetd 8 486network configuration: 487.Bd -literal 488\&./boot/kernel/kernel -m 64m -m -i memimg.0000 -I /var/run/vknet 489 -e boot.netif.ip=172.1.0.4 490 -e boot.netif.netmask=255.255.0.0 491 -e boot.netif.name=vke0 492 -e boot.nfsroot.server=172.1.0.1 493 -e boot.nfsroot.path=/home/vkernel/vkdiskless 494.Ed 495.Sh BUILDING THE WORLD UNDER A VKERNEL 496The virtual kernel platform does not have all the header files expected 497by a world build, so the easiest thing to do right now is to specify a 498pc32 (in a 32 bit vkernel) or pc64 (in a 64 bit vkernel) target when 499building the world under a virtual kernel, like this: 500.Bd -literal 501vkernel# make MACHINE_PLATFORM=pc32 buildworld 502vkernel# make MACHINE_PLATFORM=pc32 installworld 503.Ed 504.Sh SEE ALSO 505.Xr vknet 1 , 506.Xr bridge 4 , 507.Xr tap 4 , 508.Xr vn 4 , 509.Xr sysctl.conf 5 , 510.Xr build 7 , 511.Xr config 8 , 512.Xr disklabel 8 , 513.Xr ifconfig 8 , 514.Xr vknetd 8 , 515.Xr vnconfig 8 516.Rs 517.%A Aggelos Economopoulos 518.%D March 2007 519.%T "A Peek at the DragonFly Virtual Kernel" 520.Re 521.Sh HISTORY 522Virtual kernels were introduced in 523.Dx 1.7 . 524.Sh AUTHORS 525.An -nosplit 526.An Matt Dillon 527thought up and implemented the 528.Nm 529architecture and wrote the 530.Nm vkd 531device driver. 532.An Sepherosa Ziehau 533wrote the 534.Nm vke 535device driver. 536This manual page was written by 537.An Sascha Wildner . 538