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