docs/newhandbook/vkernel/index.mdwn

   1
   2
   3
   4 # The DragonFly virtual kernels
   5 [[!toc  levels=3]]
   6
   7
   8 ***Obtained from [vkernel(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=vkernel&section=7) written by Sascha Wildner, added by Matthias Schmidt***
   9
  10
  11 The idea behind the development of the vkernel architecture was to find an elegant solution to debugging of the kernel and its components. It eases debugging, as it allows for a virtual kernel being loaded in userland and hence debug it without affecting the real kernel itself. By being able to load it on a running system it also removes the need for reboots between kernel compiles.
  12
  13 The vkernel architecture allows for running DragonFly kernels in userland.
  14
  15
  16
  17 ## Supported devices
  18
  19 A number of virtual device drivers exist to supplement the virtual kernel.
  20
  21 <!-- XXX: why do they only support 16 devices? is this really true? -->
  22
  23 ### Disk device
  24
  25 The vkd driver allows for up to 16 [vn(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=vn&section=4) based disk devices.  The root device will be `vkd0`.
  26
  27 ### CD-ROM device
  28
  29 The vcd driver allows for up to 16 virtual CD-ROM devices.  Basically this is a read only `vkd` device with a block size of 2048.
  30
  31 ### Network interface
  32
  33 The vke driver supports up to 16 virtual network interfaces which are
  34
  35 associated with [tap(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=tap&section=4) devices on the host.  For each `vke` device, the per-interface read only [sysctl(3)](http://leaf.dragonflybsd.org/cgi/web-man?command=sysctl&section=3) variable `hw.vkeX.tap_unit` holds the unit number of the associated [tap(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=tap&section=4) device.
  36
  37
  38
  39
  40
  41
  42 ## Setup a virtual kernel environment
  43
  44
  45
  46 A couple of steps are necessary in order to prepare the system to build and run a virtual kernel.
  47
  48 ### Setting up the filesystem
  49
  50 The vkernel architecture needs a number of files which reside in `/var/vkernel`.  Since these files tend to get rather big and the `/var` partition is usually of limited size, we recommend the directory to be created in the `/home` partition with a link to it in `/var`:
  51
  52
  53
  54     % mkdir /home/var.vkernel
  55     % ln -s /home/var.vkernel /var/vkernel
  56
  57 Next, a filesystem image to be used by the virtual kernel has to be created and populated (assuming world has been built previously):
  58
  59     # dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
  60     # vnconfig -c vn0 /var/vkernel/rootimg.01
  61     # disklabel -r -w vn0s0 auto
  62     # disklabel -e vn0s0      # add 'a' partition with fstype `4.2BSD' size could be '*'
  63     # newfs /dev/vn0s0a
  64     # mount /dev/vn0s0a /mnt
  65
  66 If instead of using `vn0` you specify `vn` to `vnconfig`, a new `vn` device will be created and a message saying which `vnX` was created will appear. This effectively lifts the limit of 4 vn devices.
  67
  68 Assuming that you build your world before, you can populate the image now.  If you didn't build your world see [chapter 21](../updating-makeworld.html).
  69
  70     # cd /usr/src
  71     # make installworld DESTDIR=/mnt
  72     # cd etc
  73     # make distribution DESTDIR=/mnt
  74
  75
  76 Create a fstab file to let the vkernel find your image file.
  77
  78
  79
  80     # echo '/dev/vkd0s0a      /       ufs     rw      1  1' >/mnt/etc/fstab
  81     # echo 'proc              /proc   procfs  rw      0  0' >>/mnt/etc/fstab
  82
  83
  84 Edit `/mnt/etc/ttys` and replace the console entry with the following line and turn off all other gettys.
  85
  86     # console "/usr/libexec/getty Pc"         cons25  on  secure
  87
  88
  89 Then, unmount the disk.
  90
  91     # umount /mnt
  92     # vnconfig -u vn0
  93
  94
  95
  96 ### Compiling the virtual kernel
  97
  98 In order to compile a virtual kernel use the VKERNEL kernel configuration file residing in `/usr/src/sys/config` (or a configuration file derived thereof):
  99
 100
 101     # cd /usr/src
 102     # make -DNO_MODULES buildkernel KERNCONF=VKERNEL
 103     # make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
 104
 105
 106
 107 ### Enabling virtual kernel operation
 108
 109 A special sysctl(8), `vm.vkernel_enable`, must be set to enable vkernel operation:
 110
 111     # sysctl vm.vkernel_enable=1
 112
 113
 114 To make this change permanent, edit `/etc/sysctl.conf`
 115
 116
 117
 118
 119 ## Setup networking
 120
 121
 122
 123 ### Configuring the network on the host system
 124
 125 In order to access a network interface of the host system from the vkernel, you must add the interface to a [bridge(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=bridge&section=4) device which will then be passed to the `-I` option:
 126
 127
 128
 129     # kldload if_bridge.ko
 130     # kldload if_tap.ko
 131     # ifconfig bridge0 create
 132     # ifconfig bridge0 addm re0       # assuming re0 is the host's interface
 133     # ifconfig bridge0 up
 134
 135
 136
 137  **Note** : You have to change `re0` to the interface of your host machine.
 138
 139
 140
 141
 142 ## Run a virtual kernel
 143
 144
 145
 146 Finally, the virtual kernel can be run:
 147
 148     # cd /var/vkernel
 149     # ./boot/kernel -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
 150
 151 You can issue the reboot(8), halt(8), or shutdown(8) commands from inside a virtual kernel.  After doing a clean shutdown the reboot(8) command will re-exec the virtual kernel binary while the other two will cause the virtual kernel to exit.
 152
 153
 154
 155