share/man/man7/vkernel.7

   1 .\"
   2 .\" Copyright (c) 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.43 2008/09/02 22:41:19 thomas Exp $
  33 .\"
  34 .Dd March 27, 2009
  35 .Dt VKERNEL 7
  36 .Os
  37 .Sh NAME
  38 .Nm vkernel ,
  39 .Nm vcd ,
  40 .Nm vkd ,
  41 .Nm vke
  42 .Nd virtual kernel architecture
  43 .Sh SYNOPSIS
  44 .Cd "platform vkernel"
  45 .Cd "device vcd"
  46 .Cd "device vkd"
  47 .Cd "device vke"
  48 .Pp
  49 .Pa /var/vkernel/boot/kernel
  50 .Op Fl sUv
  51 .Op Fl c Ar file
  52 .Op Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
  53 .Op Fl i Ar file
  54 .Op Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
  55 .Op Fl l Ar cpulock
  56 .Op Fl m Ar size
  57 .Op Fl n Ar numcpus
  58 .Op Fl p Ar file
  59 .Op Fl r Ar file
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 architecture allows for running
  64 .Dx
  65 kernels in userland.
  66 .Pp
  67 The following options are available:
  68 .Bl -tag -width ".Fl m Ar size"
  69 .It Fl c Ar file
  70 Specify a readonly CD-ROM image
  71 .Ar file
  72 to be used by the kernel, with the first
  73 .Fl c
  74 option defining
  75 .Li vcd0 ,
  76 the second one
  77 .Li vcd1 ,
  78 and so on.
  79 The first
  80 .Fl r
  81 or
  82 .Fl c
  83 option specified on the command line will be the boot disk.
  84 The CD9660 filesystem is assumed when booting from this media.
  85 .It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
  86 Specify an environment to be used by the kernel.
  87 .It Fl i Ar file
  88 Specify a memory image
  89 .Ar file
  90 to be used by the virtual kernel.
  91 If no
  92 .Fl i
  93 option is given, the kernel will generate a name of the form
  94 .Pa /var/vkernel/memimg.XXXXXX ,
  95 with the trailing
  96 .Ql X Ns s
  97 being replaced by a sequential number, e.g.\&
  98 .Pa memimg.000001 .
  99 .It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
 100 Create a virtual network device, with the first
 101 .Fl I
 102 option defining
 103 .Li vke0 ,
 104 the second one
 105 .Li vke1 ,
 106 and so on.
 107 .Pp
 108 The
 109 .Ar interface
 110 argument is the name of a
 111 .Xr tap 4
 112 device node.
 113 The
 114 .Pa /dev/
 115 path prefix does not have to be specified and will be automatically prepended.
 116 Specifying
 117 .Cm auto
 118 will pick the first unused
 119 .Xr tap 4
 120 device.
 121 .Pp
 122 The
 123 .Ar address1
 124 and
 125 .Ar address2
 126 arguments are the IP addresses of the
 127 .Xr tap 4
 128 and
 129 .Nm vke
 130 interfaces.
 131 Optionally,
 132 .Ar address1
 133 may be of the form
 134 .Li bridge Ns Em X
 135 in which case the
 136 .Xr tap 4
 137 interface is added to the specified
 138 .Xr bridge 4
 139 interface.
 140 The
 141 .Nm vke
 142 address is not assigned until the interface is brought up in the guest.
 143 .Pp
 144 The
 145 .Ar netmask
 146 argument applies to all interfaces for which an address is specified.
 147 .It Fl l Ar cpulock
 148 Specify which, if any, real CPUs to lock virtual CPUs to.
 149 .Ar cpulock
 150 is one of
 151 .Cm any ,
 152 .Cm map Ns Op Ns , Ns Ar startCPU ,
 153 or
 154 .Ar CPU .
 155 .Pp
 156 .Cm any
 157 does not map virtual CPUs to real CPUs.
 158 This is the default.
 159 .Pp
 160 .Cm map Ns Op Ns , Ns Ar startCPU
 161 maps each virtual CPU to a real CPU starting with real CPU 0 or
 162 .Ar startCPU
 163 if specified.
 164 .Pp
 165 .Ar CPU
 166 locks all virtual CPUs to the real CPU specified by
 167 .Ar CPU .
 168 .It Fl m Ar size
 169 Specify the amount of memory to be used by the kernel in bytes,
 170 .Cm K
 171 .Pq kilobytes ,
 172 .Cm M
 173 .Pq megabytes
 174 or
 175 .Cm G
 176 .Pq gigabytes .
 177 Lowercase versions of
 178 .Cm K , M ,
 179 and
 180 .Cm G
 181 are allowed.
 182 .It Fl n Ar numcpus
 183 Specify the number of CPUs you wish to emulate.
 184 Up to 16 CPUs are supported.
 185 The virtual kernel must be built with
 186 .Cd options SMP
 187 to use this option and will default to 2 CPUs unless otherwise specified.
 188 .It Fl p Ar file
 189 Specify a file in which to store the process ID.
 190 A warning is issued if this file cannot be opened for writing.
 191 .It Fl r Ar file
 192 Specify a R/W disk image
 193 .Ar file
 194 to be used by the kernel, with the first
 195 .Fl r
 196 option defining
 197 .Li vkd0 ,
 198 the second one
 199 .Li vkd1 ,
 200 and so on.
 201 The first
 202 .Fl r
 203 or
 204 .Fl c
 205 option specified on the command line will be the boot disk.
 206 .It Fl s
 207 Boot into single-user mode.
 208 .It Fl U
 209 Enable writing to kernel memory and module loading.
 210 By default, those are disabled for security reasons.
 211 .It Fl v
 212 Turn on verbose booting.
 213 .El
 214 .Sh DEVICES
 215 A number of virtual device drivers exist to supplement the virtual kernel.
 216 .Ss Disk device
 217 The
 218 .Nm vkd
 219 driver allows for up to 16
 220 .Xr vn 4
 221 based disk devices.
 222 The root device will be
 223 .Li vkd0
 224 (see
 225 .Sx EXAMPLES
 226 for further information on how to prepare a root image).
 227 .Ss CD-ROM device
 228 The
 229 .Nm vcd
 230 driver allows for up to 16 virtual CD-ROM devices.
 231 Basically this is a read only
 232 .Nm vkd
 233 device with a block size of 2048.
 234 .Ss Network interface
 235 The
 236 .Nm vke
 237 driver supports up to 16 virtual network interfaces which are associated with
 238 .Xr tap 4
 239 devices on the host.
 240 For each
 241 .Nm vke
 242 device, the per-interface read only
 243 .Xr sysctl 3
 244 variable
 245 .Va hw.vke Ns Em X Ns Va .tap_unit
 246 holds the unit number of the associated
 247 .Xr tap 4
 248 device.
 249 .Sh SIGNALS
 250 The virtual kernel only enables
 251 .Dv SIGQUIT
 252 and
 253 .Dv SIGTERM
 254 while operating in regular console mode.
 255 Sending
 256 .Ql \&^\e
 257 .Pq Dv SIGQUIT
 258 to the virtual kernel causes the virtual kernel to enter its internal
 259 .Xr ddb 4
 260 debugger and re-enable all other terminal signals.
 261 Sending
 262 .Dv SIGTERM
 263 to the virtual kernel triggers a clean shutdown by passing a
 264 .Dv SIGUSR2
 265 to the virtual kernel's
 266 .Xr init 8
 267 process.
 268 .Sh DEBUGGING
 269 It is possible to directly gdb the virtual kernel's process.
 270 It is recommended that you do a
 271 .Ql handle SIGSEGV noprint
 272 to ignore page faults processed by the virtual kernel itself and
 273 .Ql handle SIGUSR1 noprint
 274 to ignore signals used for simulating inter-processor interrupts (SMP build
 275 only).
 276 .Sh FILES
 277 .Bl -tag -width ".It Pa /sys/config/VKERNEL" -compact
 278 .It Pa /sys/config/VKERNEL
 279 default
 280 .Nm
 281 configuration file, for
 282 .Xr config 8 .
 283 .El
 284 .Sh EXAMPLES
 285 A couple of steps are necessary in order to prepare the system to build and
 286 run a virtual kernel.
 287 .Ss Setting up the filesystem
 288 The
 289 .Nm
 290 architecture needs a number of files which reside in
 291 .Pa /var/vkernel .
 292 Since these files tend to get rather big and the
 293 .Pa /var
 294 partition is usually of limited size, we recommend the directory to be
 295 created in the
 296 .Pa /home
 297 partition with a link to it in
 298 .Pa /var :
 299 .Bd -literal
 300 mkdir -p /home/var.vkernel/boot
 301 ln -s /home/var.vkernel /var/vkernel
 302 .Ed
 303 .Pp
 304 Next, a filesystem image to be used by the virtual kernel has to be
 305 created and populated (assuming world has been built previously).
 306 If the image is created on a UFS filesystem you might want to pre-zero it.
 307 On a HAMMER filesystem you should just truncate-extend to the image size
 308 as HAMMER does not re-use data blocks already present in the file.
 309 .Bd -literal
 310 vnconfig -c -s labels -S 2g -T vn0 /var/vkernel/rootimg.01
 311 disklabel -r -w vn0s0 auto
 312 disklabel -e vn0s0      # add `a' partition with fstype `4.2BSD'
 313 newfs /dev/vn0s0a
 314 mount /dev/vn0s0a /mnt
 315 cd /usr/src
 316 make installworld DESTDIR=/mnt
 317 cd etc
 318 make distribution DESTDIR=/mnt
 319 echo '/dev/vkd0s0a      /       ufs     rw      1  1' >/mnt/etc/fstab
 320 echo 'proc              /proc   procfs  rw      0  0' >>/mnt/etc/fstab
 321 .Ed
 322 .Pp
 323 Edit
 324 .Pa /mnt/etc/ttys
 325 and replace the
 326 .Li console
 327 entry with the following line and turn off all other gettys.
 328 .Bd -literal
 329 console "/usr/libexec/getty Pc"         cons25  on  secure
 330 .Ed
 331 .Pp
 332 Replace
 333 .Li \&Pc
 334 with
 335 .Li al.Pc
 336 if you would like to automatically log in as root.
 337 .Pp
 338 Then, unmount the disk.
 339 .Bd -literal
 340 umount /mnt
 341 vnconfig -u vn0
 342 .Ed
 343 .Ss Compiling the virtual kernel
 344 In order to compile a virtual kernel use the
 345 .Li VKERNEL
 346 kernel configuration file residing in
 347 .Pa /sys/config
 348 (or a configuration file derived thereof):
 349 .Bd -literal
 350 cd /usr/src
 351 make -DNO_MODULES buildkernel KERNCONF=VKERNEL
 352 make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
 353 .Ed
 354 .Ss Enabling virtual kernel operation
 355 A special
 356 .Xr sysctl 8 ,
 357 .Va vm.vkernel_enable ,
 358 must be set to enable
 359 .Nm
 360 operation:
 361 .Bd -literal
 362 sysctl vm.vkernel_enable=1
 363 .Ed
 364 .Ss Configuring the network on the host system
 365 In order to access a network interface of the host system from the
 366 .Nm ,
 367 you must add the interface to a
 368 .Xr bridge 4
 369 device which will then be passed to the
 370 .Fl I
 371 option:
 372 .Bd -literal
 373 kldload if_bridge.ko
 374 kldload if_tap.ko
 375 ifconfig bridge0 create
 376 ifconfig bridge0 addm re0       # assuming re0 is the host's interface
 377 ifconfig bridge0 up
 378 .Ed
 379 .Ss Running the kernel
 380 Finally, the virtual kernel can be run:
 381 .Bd -literal
 382 cd /var/vkernel
 383 \&./boot/kernel -m 64m -r rootimg.01 -I auto:bridge0
 384 .Ed
 385 .Pp
 386 You can issue the
 387 .Xr reboot 8 ,
 388 .Xr halt 8 ,
 389 or
 390 .Xr shutdown 8
 391 commands from inside a virtual kernel.
 392 After doing a clean shutdown the
 393 .Xr reboot 8
 394 command will re-exec the virtual kernel binary while the other two will
 395 cause the virtual kernel to exit.
 396 .Sh BUILDING THE WORLD UNDER A VKERNEL
 397 The virtual kernel platform does not have all the header files expected
 398 by a world build, so the easiest thing to do right now is to specify a
 399 pc32 target when building the world under a virtual kernel, like this:
 400 .Bd -literal
 401 vkernel# make MACHINE_PLATFORM=pc32 buildworld
 402 vkernel# make MACHINE_PLATFORM=pc32 installworld
 403 .Ed
 404 .Sh CONFIGURATION FILES
 405 Your virtual kernel is a complete
 406 .Dx
 407 system, but you might not want to run all the services a normal kernel runs.
 408 Here is what a typical virtual kernel's
 409 .Pa /etc/rc.conf
 410 file looks like, with some additional possibilities commented out.
 411 .Bd -literal
 412 hostname="vkernel"
 413 network_interfaces="lo0 vke0"
 414 ifconfig_vke0="DHCP"
 415 sendmail_enable="NO"
 416 #syslog_enable="NO"
 417 blanktime="NO"
 418 .Ed
 419 .Sh SEE ALSO
 420 .Xr vknet 1 ,
 421 .Xr bridge 4 ,
 422 .Xr tap 4 ,
 423 .Xr vn 4 ,
 424 .Xr sysctl.conf 5 ,
 425 .Xr build 7 ,
 426 .Xr disklabel 8 ,
 427 .Xr ifconfig 8 ,
 428 .Xr vknetd 8 ,
 429 .Xr vnconfig 8
 430 .Rs
 431 .%A Aggelos Economopoulos
 432 .%D March 2007
 433 .%T "A Peek at the DragonFly Virtual Kernel"
 434 .Re
 435 .Sh HISTORY
 436 Virtual kernels were introduced in
 437 .Dx 1.7 .
 438 .Sh AUTHORS
 439 .An -nosplit
 440 .An Matt Dillon
 441 thought up and implemented the
 442 .Nm
 443 architecture and wrote the
 444 .Nm vkd
 445 device driver.
 446 .An Sepherosa Ziehau
 447 wrote the
 448 .Nm vke
 449 device driver.
 450 This manual page was written by
 451 .An Sascha Wildner .