VKERNEL(7) BSD Miscellaneous Information Manual VKERNEL(7)NAME
vkernel, vcd, vkd, vke — virtual kernel architecture
SYNOPSIS
platform vkernel # for 32 bit vkernels
platform vkernel64 # for 64 bit vkernels
device vcd
device vkd
device vke
/var/vkernel/boot/kernel/kernel [-hsUv] [-c file]
[-e name=value:name=value:...] [-i file]
[-I interface[:address1[:address2][/netmask]]] [-l cpulock] [-m size]
[-n numcpus] [-p file] [-r file]
DESCRIPTION
The vkernel architecture allows for running DragonFly kernels in user‐
land.
The following options are available:
-c file Specify a readonly CD-ROM image file to be used by the kernel,
with the first -c option defining vcd0, the second one vcd1, and
so on. The first -r or -c option specified on the command line
will be the boot disk. The CD9660 filesystem is assumed when
booting from this media.
-e name=value:name=value:...
Specify an environment to be used by the kernel.
-h Shows a list of available options, each with a short descrip‐
tion.
-i file Specify a memory image file to be used by the virtual kernel.
If no -i option is given, the kernel will generate a name of the
form /var/vkernel/memimg.XXXXXX, with the trailing ‘Xs’ being
replaced by a sequential number, e.g. memimg.000001.
-I interface[:address1[:address2][/netmask]]
Create a virtual network device, with the first -I option defin‐
ing vke0, the second one vke1, and so on.
The interface argument is the name of a tap(4) device node. The
/dev/ path prefix does not have to be specified and will be
automatically prepended. Specifying auto will pick the first
unused tap(4) device.
The address1 and address2 arguments are the IP addresses of the
tap(4) and vke interfaces. Optionally, address1 may be of the
form bridgeX in which case the tap(4) interface is added to the
specified bridge(4) interface. The vke address is not assigned
until the interface is brought up in the guest.
The netmask argument applies to all interfaces for which an
address is specified.
-l cpulock
Specify which, if any, real CPUs to lock virtual CPUs to.
cpulock is one of any, map[,startCPU], or CPU.
any does not map virtual CPUs to real CPUs. This is the
default.
map[,startCPU] maps each virtual CPU to a real CPU starting with
real CPU 0 or startCPU if specified.
CPU locks all virtual CPUs to the real CPU specified by CPU.
-m size Specify the amount of memory to be used by the kernel in bytes,
K (kilobytes), M (megabytes) or G (gigabytes). Lowercase ver‐
sions of K, M, and G are allowed.
-n numcpus
Specify the number of CPUs you wish to emulate. Up to 16 CPUs
are supported. The virtual kernel must be built with options
SMP to use this option and will default to 2 CPUs unless other‐
wise specified.
-p file Specify a file in which to store the process ID. A warning is
issued if this file cannot be opened for writing.
-r file Specify a R/W disk image file to be used by the kernel, with the
first -r option defining vkd0, the second one vkd1, and so on.
The first -r or -c option specified on the command line will be
the boot disk.
-s Boot into single-user mode.
-U Enable writing to kernel memory and module loading. By default,
those are disabled for security reasons.
-v Turn on verbose booting.
DEVICES
A number of virtual device drivers exist to supplement the virtual ker‐
nel.
Disk device
The vkd driver allows for up to 16 vn(4) based disk devices. The root
device will be vkd0 (see EXAMPLES for further information on how to pre‐
pare a root image).
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) devices on the host. For each vke device, the
per-interface read only sysctl(3) variable hw.vkeX.tap_unit holds the
unit number of the associated tap(4) device.
SIGNALS
The virtual kernel only enables SIGQUIT and SIGTERM while operating in
regular console mode. Sending ‘^\’ (SIGQUIT) to the virtual kernel
causes the virtual kernel to enter its internal ddb(4) debugger and re-
enable all other terminal signals. Sending SIGTERM to the virtual kernel
triggers a clean shutdown by passing a SIGUSR2 to the virtual kernel's
init(8) process.
DEBUGGING
It is possible to directly gdb the virtual kernel's process. It is rec‐
ommended that you do a ‘handle SIGSEGV noprint’ to ignore page faults
processed by the virtual kernel itself and ‘handle SIGUSR1 noprint’ to
ignore signals used for simulating inter-processor interrupts (SMP build
only).
FILES
/sys/config/VKERNEL default vkernel configuration file, for config(8).
CONFIGURATION FILES
Your virtual kernel is a complete DragonFly system, but you might not
want to run all the services a normal kernel runs. Here is what a typi‐
cal virtual kernel's /etc/rc.conf file looks like, with some additional
possibilities commented out.
hostname="vkernel"
network_interfaces="lo0 vke0"
ifconfig_vke0="DHCP"
sendmail_enable="NO"
#syslog_enable="NO"
blanktime="NO"
EXAMPLES
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 par‐
tition is usually of limited size, we recommend the directory to be cre‐
ated in the /home partition with a link to it in /var:
mkdir -p /home/var.vkernel/boot
ln -s /home/var.vkernel /var/vkernel
Next, a filesystem image to be used by the virtual kernel has to be cre‐
ated and populated (assuming world has been built previously). If the
image is created on a UFS filesystem you might want to pre-zero it. On a
HAMMER filesystem you should just truncate-extend to the image size as
HAMMER does not re-use data blocks already present in the file.
vnconfig -c -S 2g -T vn0 /var/vkernel/rootimg.01
disklabel -r -w vn0s0 auto
disklabel -e vn0s0 # add `a' partition with fstype `4.2BSD'
newfs /dev/vn0s0a
mount /dev/vn0s0a /mnt
cd /usr/src
make installworld DESTDIR=/mnt
cd etc
make distribution DESTDIR=/mnt
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
Replace Pc with al.Pc if you would like to automatically log in as root.
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 /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
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) 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
Running the kernel
Finally, the virtual kernel can be run:
cd /var/vkernel
./boot/kernel/kernel -m 64m -r 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.
BUILDING THE WORLD UNDER A VKERNEL
The virtual kernel platform does not have all the header files expected
by a world build, so the easiest thing to do right now is to specify a
pc32 (in a 32 bit vkernel) or pc64 (in a 64 bit vkernel) target when
building the world under a virtual kernel, like this:
vkernel# make MACHINE_PLATFORM=pc32 buildworld
vkernel# make MACHINE_PLATFORM=pc32 installworld
SEE ALSOvknet(1), bridge(4), tap(4), vn(4), sysctl.conf(5), build(7),
disklabel(8), ifconfig(8), vknetd(8), vnconfig(8)
Aggelos Economopoulos, A Peek at the DragonFly Virtual Kernel, March
2007.
HISTORY
Virtual kernels were introduced in DragonFly 1.7.
AUTHORS
Matt Dillon thought up and implemented the vkernel architecture and wrote
the vkd device driver. Sepherosa Ziehau wrote the vke device driver.
This manual page was written by Sascha Wildner.
BSD March 28, 2010 BSD
