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.19 2007/06/17 16:46:14 dillon 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
  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 CD-ROM 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 only enables
 206 .Dv SIGQUIT
 207 and
 208 .Dv SIGTERM
 209 while operating in regular console mode.
 210 Sending
 211 .Ql \&^\e
 212 .Pq Dv SIGQUIT
 213 to the virtual kernel causes the virtual kernel to enter its internal
 214 .Xr ddb 4
 215 debugger and re-enable all other terminal signals.
 216 Sending
 217 .Dv SIGTERM
 218 to the virtual kernel triggers a clean shutdown by passing a
 219 .Dv SIGUSR2
 220 to the virtual kernel's
 221 .Xr init 8
 222 process.
 223 .Sh DEBUGGING
 224 It is possible to directly gdb the virtual kernel's process.
 225 It is recommended that you do a
 226 .Ql handle SIGSEGV noprint
 227 to ignore page faults processed by the virtual kernel itself.
 228 .Sh EXAMPLES
 229 A couple of steps are necessary in order to prepare the system to build and
 230 run a virtual kernel.
 231 .Ss Setting up the filesystem
 232 The
 233 .Nm
 234 architecture needs a number of files which reside in
 235 .Pa /var/vkernel .
 236 Since these files tend to get rather big and the
 237 .Pa /var
 238 partition is usually of limited size, we recommend the directory to be
 239 created in the
 240 .Pa /home
 241 partition with a link to it in
 242 .Pa /var :
 243 .Bd -literal
 244 mkdir /home/var.vkernel
 245 ln -s /home/var.vkernel /var/vkernel
 246 .Ed
 247 .Pp
 248 Next, a filesystem image to be used by the virtual kernel has to be
 249 created and populated (assuming world has been built previously):
 250 .Bd -literal
 251 dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
 252 vnconfig -c -s labels vn0 /var/vkernel/rootimg.01
 253 disklabel -r -w vn0s0 auto
 254 disklabel -e vn0s0      # edit the label to create a vn0s0a partition
 255 newfs /dev/vn0s0a
 256 mount /dev/vn0s0a /mnt
 257 cd /usr/src
 258 make installworld DESTDIR=/mnt
 259 cd etc
 260 make distribution DESTDIR=/mnt
 261 echo '/dev/vkd0a / ufs rw 1 1' >/mnt/etc/fstab
 262 .Ed
 263 .Pp
 264 Edit
 265 .Pa /mnt/etc/ttys
 266 and replace the
 267 .Li console
 268 entry with the following line and turn off all other gettys.
 269 .Bd -literal
 270 console "/usr/libexec/getty Pc"         cons25  on  secure
 271 .Ed
 272 .Pp
 273 Then, unmount the disk.
 274 .Bd -literal
 275 umount /mnt
 276 vnconfig -u vn0
 277 .Ed
 278 .Ss Compiling the virtual kernel
 279 In order to compile a virtual kernel use the
 280 .Li VKERNEL
 281 kernel configuration file residing in
 282 .Pa /usr/src/sys/config
 283 (or a configuration file derived thereof):
 284 .Bd -literal
 285 cd /usr/src
 286 make -DNO_MODULES buildkernel KERNCONF=VKERNEL
 287 .Ed
 288 .Ss Enabling virtual kernel operation
 289 A special
 290 .Xr sysctl 8 ,
 291 .Va vm.vkernel_enable ,
 292 must be set to enable
 293 .Nm
 294 operation:
 295 .Bd -literal
 296 sysctl vm.vkernel_enable=1
 297 .Ed
 298 .Ss Configuring the network on the host system
 299 In order to access a network interface of the host system from the
 300 .Nm ,
 301 you must add the interface to a
 302 .Xr bridge 4
 303 device which will then be passed to the
 304 .Fl I
 305 option:
 306 .Bd -literal
 307 kldload if_bridge.ko
 308 kldload if_tap.ko
 309 ifconfig bridge0 create
 310 ifconfig bridge0 addm re0       # assuming re0 is the host's interface
 311 ifconfig bridge0 up
 312 .Ed
 313 .Ss Running the kernel
 314 Finally, the virtual kernel can be run:
 315 .Bd -literal
 316 cd /usr/obj/usr/src/sys/VKERNEL
 317 \&./kernel.debug -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
 318 .Ed
 319 .Pp
 320 The
 321 .Xr reboot 8
 322 command can be used to stop a virtual kernel.
 323 .Sh SEE ALSO
 324 .Xr bridge 4 ,
 325 .Xr tap 4 ,
 326 .Xr vn 4 ,
 327 .Xr build 7 ,
 328 .Xr disklabel 8 ,
 329 .Xr ifconfig 8 ,
 330 .Xr vnconfig 8
 331 .Sh HISTORY
 332 Virtual kernels were introduced in
 333 .Dx 1.7 .
 334 .Sh AUTHORS
 335 .An -nosplit
 336 .An Matt Dillon
 337 thought up and implemented the
 338 .Nm
 339 architecture and wrote the
 340 .Nm vkd
 341 device driver.
 342 .An Sepherosa Ziehau
 343 wrote the
 344 .Nm vke
 345 device driver.
 346 This manual page was written by
 347 .An Sascha Wildner .