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