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