[ikiwiki.git] / docs / newhandbook / vkernel / index.mdwn


# The DragonFly virtual kernels 
[[!toc  levels=3]]


***Obtained from [vkernel(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=vkernel&section=7) written by Sascha Wildner, added by Matthias Schmidt***


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.

The vkernel architecture allows for running DragonFly kernels in userland.


## Supported devices 

A number of virtual device drivers exist to supplement the virtual kernel.

<!-- XXX: why do they only support 16 devices? is this really true? -->

### Disk device 

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`.

### CD-ROM device 

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.

### Network interface 

The vke driver supports up to 16 virtual network interfaces which are

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.


## Setup a virtual kernel environment 


A couple of steps are necessary in order to prepare the system to build and run a virtual kernel.

### Setting up the filesystem 

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`:

    
    % mkdir /home/var.vkernel
    % ln -s /home/var.vkernel /var/vkernel

Next, a filesystem image to be used by the virtual kernel has to be created and populated (assuming world has been built previously):    

    # dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
    # vnconfig -c vn0 /var/vkernel/rootimg.01
    # disklabel -r -w vn0s0 auto
    # disklabel -e vn0s0      # add 'a' partition with fstype `4.2BSD' size could be '*'
    # newfs /dev/vn0s0a
    # mount /dev/vn0s0a /mnt

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.

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).

    # cd /usr/src
    # make installworld DESTDIR=/mnt
    # cd etc
    # make distribution DESTDIR=/mnt


Create a fstab file to let the vkernel find your image file.

    
    # echo '/dev/vkd0s0a      /       ufs     rw      1  1' >/mnt/etc/fstab
    # echo 'proc              /proc   procfs  rw      0  0' >>/mnt/etc/fstab


Edit `/mnt/etc/ttys` and replace the console entry with the following line and turn off all other gettys.

    # console "/usr/libexec/getty Pc"         cons25  on  secure


Then, unmount the disk.

    # umount /mnt
    # vnconfig -u vn0


### Compiling the virtual kernel 

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):
    

    # cd /usr/src
    # make -DNO_MODULES buildkernel KERNCONF=VKERNEL
    # make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel


### Enabling virtual kernel operation 

A special sysctl(8), `vm.vkernel_enable`, must be set to enable vkernel operation:

    # sysctl vm.vkernel_enable=1


To make this change permanent, edit `/etc/sysctl.conf`


## Setup networking 


### Configuring the network on the host system 

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:

    
    # kldload if_bridge.ko
    # kldload if_tap.ko
    # ifconfig bridge0 create
    # ifconfig bridge0 addm re0       # assuming re0 is the host's interface
    # ifconfig bridge0 up


 **Note** : You have to change `re0` to the interface of your host machine.

 
## Run a virtual kernel 


Finally, the virtual kernel can be run:

    # cd /var/vkernel
    # ./boot/kernel/kernel -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0

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.
Commit	Line	Data
3b2bab92	1
3b2bab92	2	# The DragonFly virtual kernels
dfdd88e9	3	[[!toc levels=3]]
3b2bab92	4
	5
	6	*Obtained from [vkernel(7)](http://leaf.dragonflybsd.org/cgi/web-man?command=vkernel&section=7) written by Sascha Wildner, added by Matthias Schmidt*
	7
	8
	9	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.
	10
	11	The vkernel architecture allows for running DragonFly kernels in userland.
	12
	13
	14
	15	## Supported devices
	16
	17	A number of virtual device drivers exist to supplement the virtual kernel.
	18
	19	<!-- XXX: why do they only support 16 devices? is this really true? -->
	20
	21	### Disk device
	22
	23	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`.
	24
	25	### CD-ROM device
	26
	27	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.
	28
	29	### Network interface
	30
	31	The vke driver supports up to 16 virtual network interfaces which are
	32
	33	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.
	34
	35
	36
	37
	38
	39
	40	## Setup a virtual kernel environment
	41
	42
	43
	44	A couple of steps are necessary in order to prepare the system to build and run a virtual kernel.
	45
	46	### Setting up the filesystem
	47
	48	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`:
	49
	50
	51
	52	% mkdir /home/var.vkernel
	53	% ln -s /home/var.vkernel /var/vkernel
	54
	55	Next, a filesystem image to be used by the virtual kernel has to be created and populated (assuming world has been built previously):
	56
	57	# dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
	58	# vnconfig -c vn0 /var/vkernel/rootimg.01
	59	# disklabel -r -w vn0s0 auto
	60	# disklabel -e vn0s0 # add 'a' partition with fstype `4.2BSD' size could be '*'
	61	# newfs /dev/vn0s0a
	62	# mount /dev/vn0s0a /mnt
	63
	64	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.
	65
	66	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).
	67
68	# cd /usr/src
69	# make installworld DESTDIR=/mnt
70	# cd etc
71	# make distribution DESTDIR=/mnt
72
73
74	Create a fstab file to let the vkernel find your image file.
75
76
77
78	# echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab
79	# echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab
80
81
82	Edit `/mnt/etc/ttys` and replace the console entry with the following line and turn off all other gettys.
83
84	# console "/usr/libexec/getty Pc" cons25 on secure
85
86
87	Then, unmount the disk.
88
89	# umount /mnt
90	# vnconfig -u vn0
91
92
93
94	### Compiling the virtual kernel
95
96	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):
97
98
99	# cd /usr/src
100	# make -DNO_MODULES buildkernel KERNCONF=VKERNEL
101	# make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
102
103
104
105	### Enabling virtual kernel operation
106
107	A special sysctl(8), `vm.vkernel_enable`, must be set to enable vkernel operation:
108
109	# sysctl vm.vkernel_enable=1
110
111
112	To make this change permanent, edit `/etc/sysctl.conf`
113
114
115
116
117	## Setup networking
118
119
120
121	### Configuring the network on the host system
122
123	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:
124
125
126
127	# kldload if_bridge.ko
128	# kldload if_tap.ko
129	# ifconfig bridge0 create
130	# ifconfig bridge0 addm re0 # assuming re0 is the host's interface
131	# ifconfig bridge0 up
132
133
134
135	Note : You have to change `re0` to the interface of your host machine.
136
137
138
139
140	## Run a virtual kernel
141
142
143
144	Finally, the virtual kernel can be run:
145
146	# cd /var/vkernel
ab6c3a64	147	# ./boot/kernel/kernel -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
3b2bab92	148
	149	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.
	150
	151
	152
	153