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