Add units to offset adjustment messages.
[dragonfly.git] / share / man / man7 / vkernel.7
CommitLineData
4af18995
SW
1.\"
2.\" Copyright (c) 2003, 2004, 2005, 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.\"
702acf06 32.\" $DragonFly: src/share/man/man7/vkernel.7,v 1.25 2007/07/10 18:35:38 josepht Exp $
4af18995 33.\"
8cf87c92 34.Dd July 2, 2007
4af18995
SW
35.Dt VKERNEL 7
36.Os
37.Sh NAME
0592e24d
SW
38.Nm vkernel ,
39.Nm vkd ,
40.Nm vke
4af18995
SW
41.Nd virtual kernel architecture
42.Sh SYNOPSIS
65d7306b 43.Cd "platform vkernel"
c8e7d028
SW
44.Cd "device vkd"
45.Cd "device vke"
46.Pp
4af18995 47.Pa /usr/obj/usr/src/sys/VKERNEL/kernel.debug
03071031 48.Op Fl sUv
a72d8a9f 49.Op Fl c Ar file
09b03fff 50.Op Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
dd54cb3a 51.Op Fl i Ar file
09b03fff 52.Op Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
702acf06 53.Op Fl l Ar cpulock
4af18995 54.Op Fl m Ar size
c5b0b0ba 55.Op Fl n Ar numcpus
b02b4170 56.Op Fl p Ar file
4af18995 57.Op Fl r Ar file
4af18995
SW
58.Sh DESCRIPTION
59The
60.Nm
61architecture allows for running
62.Dx
63kernels in userland.
64.Pp
65The following options are available:
66.Bl -tag -width ".Fl m Ar size"
a72d8a9f 67.It Fl c Ar file
7834fbcc 68Specify a readonly CD-ROM image
a72d8a9f
MD
69.Ar file
70to be used by the kernel, with the first
71.Fl c
72option defining
73.Li vcd0 ,
74the second one
75.Li vcd1 ,
76and so on. The first
77.Fl r
78or
79.Fl c
80option specified on the command line will be the boot disk.
7834fbcc 81The CD9660 filesystem is assumed when booting from this media.
09b03fff
SW
82.It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
83Specify an environment to be used by the kernel.
dd54cb3a
SW
84.It Fl i Ar file
85Specify a memory image
86.Ar file
87to be used by the virtual kernel.
88If no
89.Fl i
90option is given, the kernel will generate a name of the form
91.Pa /var/vkernel/memimg.XXXXXX ,
92with the trailing
93.Ql X Ns s
94being replaced by a sequential number, e.g.\&
95.Pa memimg.000001 .
09b03fff
SW
96.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
97Create a virtual network device, with the first
98.Fl I
99option defining
0592e24d 100.Li vke0 ,
09b03fff 101the second one
0592e24d 102.Li vke1 ,
09b03fff
SW
103and so on.
104.Pp
105The
106.Ar interface
107argument is the name of a
108.Xr tap 4
109device node.
110The
111.Pa /dev/
112path prefix does not have to be specified and will be automatically prepended.
113Specifying
114.Cm auto
115will pick the first unused
116.Xr tap 4
117device.
118.Pp
119The
120.Ar address1
121and
122.Ar address2
123arguments are the IP addresses of the
124.Xr tap 4
125and
0592e24d 126.Nm vke
09b03fff
SW
127interfaces.
128Optionally,
129.Ar address1
130may be of the form
131.Li bridge Ns Em X
132in which case the
133.Xr tap 4
134interface is added to the specified
135.Xr bridge 4
136interface.
137.Pp
138The
139.Ar netmask
140argument applies to all interfaces for which an address is specified.
702acf06
JT
141.It Fl l Ar cpulock
142Specify which, if any, real CPUs to lock virtual CPUs to.
143.Ar cpulock
144is one of
145.Cm any,
146.Cm map Ns Op Ns , Ns Ar startCPU Ns
147, or
148.Ar CPU
149.Pp
150.Cm any
151does not map virtual CPUs to real CPUs. This is the default.
152.Pp
153.Cm map Ns Op Ns , Ns Ar startCPU
154maps each virtual CPU to a real CPU starting with real CPU 0 or
155.Ar startCPU
156if specified.
157.Pp
158.Ar CPU
159locks all virtual CPUs to the real CPU spcified by
160.Ar CPU
161
4af18995
SW
162.It Fl m Ar size
163Specify the amount of memory to be used by the kernel in bytes,
164.Cm K
3cea05a4 165.Pq kilobytes ,
4af18995 166.Cm M
3cea05a4
SW
167.Pq megabytes
168or
4af18995 169.Cm G
3cea05a4 170.Pq gigabytes .
09b03fff 171Lowercase versions of
4af18995
SW
172.Cm K , M ,
173and
174.Cm G
175are allowed.
c5b0b0ba 176.It Fl n Ar numcpus
8cf87c92
SW
177Specify the number of CPUs you wish to emulate.
178Up to 32 CPUs are supported.
179The virtual kernel must be built with
180.Cd options SMP
181to use this option and will default to 2 CPUs unless otherwise specified.
b02b4170 182.It Fl p Ar file
dec8c72c 183Specify a file in which to store the process ID.
b02b4170 184A warning is issued if this file cannot be opened for writing.
4af18995 185.It Fl r Ar file
a72d8a9f 186Specify a R/W disk image
4af18995 187.Ar file
ec1a8a4d
SW
188to be used by the kernel, with the first
189.Fl r
190option defining
0592e24d 191.Li vkd0 ,
ec1a8a4d 192the second one
0592e24d 193.Li vkd1 ,
a72d8a9f
MD
194and so on. The first
195.Fl r
196or
197.Fl c
198option specified on the command line will be the boot disk.
c8e7d028
SW
199.It Fl s
200Boot into single-user mode.
03071031
SW
201.It Fl U
202Enable writing to kernel memory and module loading.
203By default, those are disabled for security reasons.
4af18995
SW
204.It Fl v
205Turn on verbose booting.
206.El
0592e24d
SW
207.Sh DEVICES
208A number of virtual device drivers exist to supplement the virtual kernel.
209Their names start with
210.Li vk .
211.Ss Disk device
212The
213.Nm vkd
214driver allows for up to 16
215.Xr vn 4
216based disk devices.
217The root device will be
218.Li vkd0
219(see
220.Sx EXAMPLES
221for further information on how to prepare a root image).
222.Ss Network interface
223The
224.Nm vke
225driver supports up to 16 virtual network interfaces which are associated with
226.Xr tap 4
227devices on the host.
228For each
229.Nm vke
230device, the per-interface read only
231.Xr sysctl 3
232variable
233.Va hw.vke Ns Em X Ns Va .tap_unit
234holds the unit number of the associated
235.Xr tap 4
236device.
1e4d9fd9 237.Sh SIGNALS
dec8c72c 238The virtual kernel only enables
bb195a01 239.Dv SIGQUIT
dec8c72c
SW
240and
241.Dv SIGTERM
242while operating in regular console mode.
243Sending
1e4d9fd9
SW
244.Ql \&^\e
245.Pq Dv SIGQUIT
bb195a01 246to the virtual kernel causes the virtual kernel to enter its internal
1e4d9fd9 247.Xr ddb 4
dec8c72c 248debugger and re-enable all other terminal signals.
bb195a01 249Sending
dec8c72c
SW
250.Dv SIGTERM
251to the virtual kernel triggers a clean shutdown by passing a
252.Dv SIGUSR2
253to the virtual kernel's
bb195a01
MD
254.Xr init 8
255process.
974b26bf
SW
256.Sh DEBUGGING
257It is possible to directly gdb the virtual kernel's process.
258It is recommended that you do a
259.Ql handle SIGSEGV noprint
260to ignore page faults processed by the virtual kernel itself.
c8e7d028 261.Sh EXAMPLES
4af18995
SW
262A couple of steps are necessary in order to prepare the system to build and
263run a virtual kernel.
264.Ss Setting up the filesystem
265The
266.Nm
267architecture needs a number of files which reside in
268.Pa /var/vkernel .
269Since these files tend to get rather big and the
270.Pa /var
271partition is usually of limited size, we recommend the directory to be
272created in the
273.Pa /home
274partition with a link to it in
275.Pa /var :
c8e7d028 276.Bd -literal
4af18995
SW
277mkdir /home/var.vkernel
278ln -s /home/var.vkernel /var/vkernel
279.Ed
280.Pp
281Next, a filesystem image to be used by the virtual kernel has to be
c8e7d028
SW
282created and populated (assuming world has been built previously):
283.Bd -literal
4af18995
SW
284dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
285vnconfig -c -s labels vn0 /var/vkernel/rootimg.01
58c55700
SW
286disklabel -r -w vn0s0 auto
287disklabel -e vn0s0 # edit the label to create a vn0s0a partition
288newfs /dev/vn0s0a
289mount /dev/vn0s0a /mnt
c8e7d028
SW
290cd /usr/src
291make installworld DESTDIR=/mnt
292cd etc
293make distribution DESTDIR=/mnt
6a060312 294echo '/dev/vkd0a / ufs rw 1 1' >/mnt/etc/fstab
7834fbcc
SW
295.Ed
296.Pp
297Edit
298.Pa /mnt/etc/ttys
299and replace the
300.Li console
301entry with the following line and turn off all other gettys.
302.Bd -literal
303console "/usr/libexec/getty Pc" cons25 on secure
304.Ed
305.Pp
306Then, unmount the disk.
307.Bd -literal
4af18995
SW
308umount /mnt
309vnconfig -u vn0
310.Ed
311.Ss Compiling the virtual kernel
312In order to compile a virtual kernel use the
313.Li VKERNEL
314kernel configuration file residing in
315.Pa /usr/src/sys/config
316(or a configuration file derived thereof):
c8e7d028 317.Bd -literal
4af18995 318cd /usr/src
09b03fff 319make -DNO_MODULES buildkernel KERNCONF=VKERNEL
4af18995
SW
320.Ed
321.Ss Enabling virtual kernel operation
322A special
323.Xr sysctl 8 ,
324.Va vm.vkernel_enable ,
325must be set to enable
326.Nm
327operation:
c8e7d028 328.Bd -literal
4af18995
SW
329sysctl vm.vkernel_enable=1
330.Ed
09b03fff
SW
331.Ss Configuring the network on the host system
332In order to access a network interface of the host system from the
333.Nm ,
334you must add the interface to a
335.Xr bridge 4
336device which will then be passed to the
337.Fl I
338option:
339.Bd -literal
340kldload if_bridge.ko
341kldload if_tap.ko
342ifconfig bridge0 create
343ifconfig bridge0 addm re0 # assuming re0 is the host's interface
344ifconfig bridge0 up
345.Ed
4af18995
SW
346.Ss Running the kernel
347Finally, the virtual kernel can be run:
c8e7d028 348.Bd -literal
4af18995 349cd /usr/obj/usr/src/sys/VKERNEL
09b03fff 350\&./kernel.debug -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
4af18995 351.Ed
c8e7d028
SW
352.Pp
353The
354.Xr reboot 8
355command can be used to stop a virtual kernel.
34caba04
MD
356.Sh BUILDING THE WORLD UNDER A VKERNEL
357The virtual kernel platform does not have all the header files expected
358by a world build, so the easiest thing to do right now is to specify a
359pc32 target when building the world under a virtual kernel, like this:
360.Bd -literal
361vkernel# make MACHINE_PLATFORM=pc32 buildworld
362vkernel# make MACHINE_PLATFORM=pc32 installworld
363.Ed
4af18995 364.Sh SEE ALSO
09b03fff
SW
365.Xr bridge 4 ,
366.Xr tap 4 ,
c8e7d028
SW
367.Xr vn 4 ,
368.Xr build 7 ,
369.Xr disklabel 8 ,
09b03fff 370.Xr ifconfig 8 ,
c8e7d028 371.Xr vnconfig 8
4af18995
SW
372.Sh HISTORY
373Virtual kernels were introduced in
374.Dx 1.7 .
375.Sh AUTHORS
376.An -nosplit
377.An Matt Dillon
378thought up and implemented the
379.Nm
0592e24d
SW
380architecture and wrote the
381.Nm vkd
382device driver.
383.An Sepherosa Ziehau
384wrote the
385.Nm vke
386device driver.
4af18995
SW
387This manual page was written by
388.An Sascha Wildner .