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