1.\" 2.\" Copyright (c) 2003, 2004, 2005, 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.18 2007/06/14 21:11:29 swildner Exp $ 33.\" 34.Dd June 14, 2007 35.Dt VKERNEL 7 36.Os 37.Sh NAME 38.Nm vkernel , 39.Nm vkd , 40.Nm vke 41.Nd virtual kernel architecture 42.Sh SYNOPSIS 43.Cd "platform vkernel" 44.Cd "device vkd" 45.Cd "device vke" 46.Pp 47.Pa /usr/obj/usr/src/sys/VKERNEL/kernel.debug 48.Op Fl sUv 49.Op Fl c Ar file 50.Op Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ... 51.Op Fl i Ar file 52.Op Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 53.Op Fl m Ar size 54.Op Fl r Ar file 55.Sh DESCRIPTION 56The 57.Nm 58architecture allows for running 59.Dx 60kernels in userland. 61.Pp 62The following options are available: 63.Bl -tag -width ".Fl m Ar size" 64.It Fl c Ar file 65Specify a readonly CD-ROM image 66.Ar file 67to be used by the kernel, with the first 68.Fl c 69option defining 70.Li vcd0 , 71the second one 72.Li vcd1 , 73and so on. The first 74.Fl r 75or 76.Fl c 77option specified on the command line will be the boot disk. 78The CD9660 filesystem is assumed when booting from this media. 79.It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ... 80Specify an environment to be used by the kernel. 81.It Fl i Ar file 82Specify a memory image 83.Ar file 84to be used by the virtual kernel. 85If no 86.Fl i 87option is given, the kernel will generate a name of the form 88.Pa /var/vkernel/memimg.XXXXXX , 89with the trailing 90.Ql X Ns s 91being replaced by a sequential number, e.g.\& 92.Pa memimg.000001 . 93.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc 94Create a virtual network device, with the first 95.Fl I 96option defining 97.Li vke0 , 98the second one 99.Li vke1 , 100and so on. 101.Pp 102The 103.Ar interface 104argument is the name of a 105.Xr tap 4 106device node. 107The 108.Pa /dev/ 109path prefix does not have to be specified and will be automatically prepended. 110Specifying 111.Cm auto 112will pick the first unused 113.Xr tap 4 114device. 115.Pp 116The 117.Ar address1 118and 119.Ar address2 120arguments are the IP addresses of the 121.Xr tap 4 122and 123.Nm vke 124interfaces. 125Optionally, 126.Ar address1 127may be of the form 128.Li bridge Ns Em X 129in which case the 130.Xr tap 4 131interface is added to the specified 132.Xr bridge 4 133interface. 134.Pp 135The 136.Ar netmask 137argument applies to all interfaces for which an address is specified. 138.It Fl m Ar size 139Specify the amount of memory to be used by the kernel in bytes, 140.Cm K 141.Pq kilobytes , 142.Cm M 143.Pq megabytes 144or 145.Cm G 146.Pq gigabytes . 147Lowercase versions of 148.Cm K , M , 149and 150.Cm G 151are allowed. 152.It Fl r Ar file 153Specify a R/W disk image 154.Ar file 155to be used by the kernel, with the first 156.Fl r 157option defining 158.Li vkd0 , 159the second one 160.Li vkd1 , 161and so on. The first 162.Fl r 163or 164.Fl c 165option specified on the command line will be the boot disk. 166.It Fl s 167Boot into single-user mode. 168.It Fl U 169Enable writing to kernel memory and module loading. 170By default, those are disabled for security reasons. 171.It Fl v 172Turn on verbose booting. 173.El 174.Sh DEVICES 175A number of virtual device drivers exist to supplement the virtual kernel. 176Their names start with 177.Li vk . 178.Ss Disk device 179The 180.Nm vkd 181driver allows for up to 16 182.Xr vn 4 183based disk devices. 184The root device will be 185.Li vkd0 186(see 187.Sx EXAMPLES 188for further information on how to prepare a root image). 189.Ss Network interface 190The 191.Nm vke 192driver supports up to 16 virtual network interfaces which are associated with 193.Xr tap 4 194devices on the host. 195For each 196.Nm vke 197device, the per-interface read only 198.Xr sysctl 3 199variable 200.Va hw.vke Ns Em X Ns Va .tap_unit 201holds the unit number of the associated 202.Xr tap 4 203device. 204.Sh SIGNALS 205The virtual kernel enables all terminal signals while in 206.Xr ddb 4 207mode but only enables 208.Ql \&^\e 209.Pq Dv SIGQUIT 210while operating as a console which causes the virtual kernel to enter its 211internal 212.Xr ddb 4 213debugger. 214.Sh DEBUGGING 215It is possible to directly gdb the virtual kernel's process. 216It is recommended that you do a 217.Ql handle SIGSEGV noprint 218to ignore page faults processed by the virtual kernel itself. 219.Sh EXAMPLES 220A couple of steps are necessary in order to prepare the system to build and 221run a virtual kernel. 222.Ss Setting up the filesystem 223The 224.Nm 225architecture needs a number of files which reside in 226.Pa /var/vkernel . 227Since these files tend to get rather big and the 228.Pa /var 229partition is usually of limited size, we recommend the directory to be 230created in the 231.Pa /home 232partition with a link to it in 233.Pa /var : 234.Bd -literal 235mkdir /home/var.vkernel 236ln -s /home/var.vkernel /var/vkernel 237.Ed 238.Pp 239Next, a filesystem image to be used by the virtual kernel has to be 240created and populated (assuming world has been built previously): 241.Bd -literal 242dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048 243vnconfig -c -s labels vn0 /var/vkernel/rootimg.01 244disklabel -r -w vn0s0 auto 245disklabel -e vn0s0 # edit the label to create a vn0s0a partition 246newfs /dev/vn0s0a 247mount /dev/vn0s0a /mnt 248cd /usr/src 249make installworld DESTDIR=/mnt 250cd etc 251make distribution DESTDIR=/mnt 252echo '/dev/vkd0a / ufs rw 1 1' >/mnt/etc/fstab 253.Ed 254.Pp 255Edit 256.Pa /mnt/etc/ttys 257and replace the 258.Li console 259entry with the following line and turn off all other gettys. 260.Bd -literal 261console "/usr/libexec/getty Pc" cons25 on secure 262.Ed 263.Pp 264Then, unmount the disk. 265.Bd -literal 266umount /mnt 267vnconfig -u vn0 268.Ed 269.Ss Compiling the virtual kernel 270In order to compile a virtual kernel use the 271.Li VKERNEL 272kernel configuration file residing in 273.Pa /usr/src/sys/config 274(or a configuration file derived thereof): 275.Bd -literal 276cd /usr/src 277make -DNO_MODULES buildkernel KERNCONF=VKERNEL 278.Ed 279.Ss Enabling virtual kernel operation 280A special 281.Xr sysctl 8 , 282.Va vm.vkernel_enable , 283must be set to enable 284.Nm 285operation: 286.Bd -literal 287sysctl vm.vkernel_enable=1 288.Ed 289.Ss Configuring the network on the host system 290In order to access a network interface of the host system from the 291.Nm , 292you must add the interface to a 293.Xr bridge 4 294device which will then be passed to the 295.Fl I 296option: 297.Bd -literal 298kldload if_bridge.ko 299kldload if_tap.ko 300ifconfig bridge0 create 301ifconfig bridge0 addm re0 # assuming re0 is the host's interface 302ifconfig bridge0 up 303.Ed 304.Ss Running the kernel 305Finally, the virtual kernel can be run: 306.Bd -literal 307cd /usr/obj/usr/src/sys/VKERNEL 308\&./kernel.debug -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0 309.Ed 310.Pp 311The 312.Xr reboot 8 313command can be used to stop a virtual kernel. 314.Sh SEE ALSO 315.Xr bridge 4 , 316.Xr tap 4 , 317.Xr vn 4 , 318.Xr build 7 , 319.Xr disklabel 8 , 320.Xr ifconfig 8 , 321.Xr vnconfig 8 322.Sh HISTORY 323Virtual kernels were introduced in 324.Dx 1.7 . 325.Sh AUTHORS 326.An -nosplit 327.An Matt Dillon 328thought up and implemented the 329.Nm 330architecture and wrote the 331.Nm vkd 332device driver. 333.An Sepherosa Ziehau 334wrote the 335.Nm vke 336device driver. 337This manual page was written by 338.An Sascha Wildner . 339