share/man/man7/vkernel.7

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