Regenerate the pciconf(8) database from the following files:
[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.\"
66931b32 32.\" $DragonFly: src/share/man/man7/vkernel.7,v 1.34 2007/11/06 22:06:33 swildner Exp $
4af18995 33.\"
405996b0 34.Dd September 27, 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
79b58aae 49.Pa /var/vkernel/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 ,
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.
a8cc122d
SW
139The
140.Nm vke
141address is not assigned until the interface is brought up in the guest.
09b03fff
SW
142.Pp
143The
144.Ar netmask
145argument applies to all interfaces for which an address is specified.
702acf06
JT
146.It Fl l Ar cpulock
147Specify which, if any, real CPUs to lock virtual CPUs to.
148.Ar cpulock
149is one of
26ea2793
SW
150.Cm any ,
151.Cm map Ns Op Ns , Ns Ar startCPU ,
152or
153.Ar CPU .
702acf06
JT
154.Pp
155.Cm any
26ea2793
SW
156does not map virtual CPUs to real CPUs.
157This is the default.
702acf06
JT
158.Pp
159.Cm map Ns Op Ns , Ns Ar startCPU
160maps each virtual CPU to a real CPU starting with real CPU 0 or
161.Ar startCPU
162if specified.
163.Pp
164.Ar CPU
26ea2793
SW
165locks all virtual CPUs to the real CPU specified by
166.Ar CPU .
4af18995
SW
167.It Fl m Ar size
168Specify the amount of memory to be used by the kernel in bytes,
169.Cm K
3cea05a4 170.Pq kilobytes ,
4af18995 171.Cm M
3cea05a4
SW
172.Pq megabytes
173or
4af18995 174.Cm G
3cea05a4 175.Pq gigabytes .
09b03fff 176Lowercase versions of
4af18995
SW
177.Cm K , M ,
178and
179.Cm G
180are allowed.
c5b0b0ba 181.It Fl n Ar numcpus
8cf87c92 182Specify the number of CPUs you wish to emulate.
3217a401 183Up to 31 CPUs are supported.
8cf87c92
SW
184The virtual kernel must be built with
185.Cd options SMP
186to use this option and will default to 2 CPUs unless otherwise specified.
b02b4170 187.It Fl p Ar file
dec8c72c 188Specify a file in which to store the process ID.
b02b4170 189A warning is issued if this file cannot be opened for writing.
4af18995 190.It Fl r Ar file
a72d8a9f 191Specify a R/W disk image
4af18995 192.Ar file
ec1a8a4d
SW
193to be used by the kernel, with the first
194.Fl r
195option defining
0592e24d 196.Li vkd0 ,
ec1a8a4d 197the second one
0592e24d 198.Li vkd1 ,
a72d8a9f
MD
199and so on. The first
200.Fl r
201or
202.Fl c
203option specified on the command line will be the boot disk.
c8e7d028
SW
204.It Fl s
205Boot into single-user mode.
03071031
SW
206.It Fl U
207Enable writing to kernel memory and module loading.
208By default, those are disabled for security reasons.
4af18995
SW
209.It Fl v
210Turn on verbose booting.
211.El
0592e24d
SW
212.Sh DEVICES
213A number of virtual device drivers exist to supplement the virtual kernel.
0592e24d
SW
214.Ss Disk device
215The
216.Nm vkd
217driver allows for up to 16
218.Xr vn 4
219based disk devices.
220The root device will be
221.Li vkd0
222(see
223.Sx EXAMPLES
224for further information on how to prepare a root image).
98b2ba80
SW
225.Ss CD-ROM device
226The
227.Nm vcd
228driver allows for up to 16 virtual CD-ROM devices.
229Basically this is a read only
230.Nm vkd
231device with a block size of 2048.
0592e24d
SW
232.Ss Network interface
233The
234.Nm vke
235driver supports up to 16 virtual network interfaces which are associated with
236.Xr tap 4
237devices on the host.
238For each
239.Nm vke
240device, the per-interface read only
241.Xr sysctl 3
242variable
243.Va hw.vke Ns Em X Ns Va .tap_unit
244holds the unit number of the associated
245.Xr tap 4
246device.
1e4d9fd9 247.Sh SIGNALS
dec8c72c 248The virtual kernel only enables
bb195a01 249.Dv SIGQUIT
dec8c72c
SW
250and
251.Dv SIGTERM
252while operating in regular console mode.
253Sending
1e4d9fd9
SW
254.Ql \&^\e
255.Pq Dv SIGQUIT
bb195a01 256to the virtual kernel causes the virtual kernel to enter its internal
1e4d9fd9 257.Xr ddb 4
dec8c72c 258debugger and re-enable all other terminal signals.
bb195a01 259Sending
dec8c72c
SW
260.Dv SIGTERM
261to the virtual kernel triggers a clean shutdown by passing a
262.Dv SIGUSR2
263to the virtual kernel's
bb195a01
MD
264.Xr init 8
265process.
974b26bf
SW
266.Sh DEBUGGING
267It is possible to directly gdb the virtual kernel's process.
268It is recommended that you do a
269.Ql handle SIGSEGV noprint
270to ignore page faults processed by the virtual kernel itself.
c8e7d028 271.Sh EXAMPLES
4af18995
SW
272A couple of steps are necessary in order to prepare the system to build and
273run a virtual kernel.
274.Ss Setting up the filesystem
275The
276.Nm
277architecture needs a number of files which reside in
278.Pa /var/vkernel .
279Since these files tend to get rather big and the
280.Pa /var
281partition is usually of limited size, we recommend the directory to be
282created in the
283.Pa /home
284partition with a link to it in
285.Pa /var :
c8e7d028 286.Bd -literal
4af18995
SW
287mkdir /home/var.vkernel
288ln -s /home/var.vkernel /var/vkernel
289.Ed
290.Pp
291Next, a filesystem image to be used by the virtual kernel has to be
c8e7d028
SW
292created and populated (assuming world has been built previously):
293.Bd -literal
4af18995
SW
294dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
295vnconfig -c -s labels vn0 /var/vkernel/rootimg.01
58c55700
SW
296disklabel -r -w vn0s0 auto
297disklabel -e vn0s0 # edit the label to create a vn0s0a partition
298newfs /dev/vn0s0a
299mount /dev/vn0s0a /mnt
c8e7d028
SW
300cd /usr/src
301make installworld DESTDIR=/mnt
302cd etc
303make distribution DESTDIR=/mnt
7a3238b8 304echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab
98b2ba80 305echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab
7834fbcc
SW
306.Ed
307.Pp
308Edit
309.Pa /mnt/etc/ttys
310and replace the
311.Li console
312entry with the following line and turn off all other gettys.
313.Bd -literal
314console "/usr/libexec/getty Pc" cons25 on secure
315.Ed
316.Pp
317Then, unmount the disk.
318.Bd -literal
4af18995
SW
319umount /mnt
320vnconfig -u vn0
321.Ed
322.Ss Compiling the virtual kernel
323In order to compile a virtual kernel use the
324.Li VKERNEL
325kernel configuration file residing in
326.Pa /usr/src/sys/config
327(or a configuration file derived thereof):
c8e7d028 328.Bd -literal
4af18995 329cd /usr/src
09b03fff 330make -DNO_MODULES buildkernel KERNCONF=VKERNEL
79b58aae 331make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
4af18995
SW
332.Ed
333.Ss Enabling virtual kernel operation
334A special
335.Xr sysctl 8 ,
336.Va vm.vkernel_enable ,
337must be set to enable
338.Nm
339operation:
c8e7d028 340.Bd -literal
4af18995
SW
341sysctl vm.vkernel_enable=1
342.Ed
09b03fff
SW
343.Ss Configuring the network on the host system
344In order to access a network interface of the host system from the
345.Nm ,
346you must add the interface to a
347.Xr bridge 4
348device which will then be passed to the
349.Fl I
350option:
351.Bd -literal
352kldload if_bridge.ko
353kldload if_tap.ko
354ifconfig bridge0 create
355ifconfig bridge0 addm re0 # assuming re0 is the host's interface
356ifconfig bridge0 up
357.Ed
4af18995
SW
358.Ss Running the kernel
359Finally, the virtual kernel can be run:
c8e7d028 360.Bd -literal
79b58aae
MD
361cd /var/vkernel
362\&./kernel -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
4af18995 363.Ed
c8e7d028 364.Pp
79b58aae
MD
365You can issue the
366.Xr reboot 8 ,
367.Xr halt 8 ,
368or
369.Xr shutdown 8
370commands from inside a virtual kernel.
371After doing a clean shutdown the
c8e7d028 372.Xr reboot 8
79b58aae
MD
373command will re-exec the virtual kernel binary while the other two will
374cause the virtual kernel to exit.
34caba04
MD
375.Sh BUILDING THE WORLD UNDER A VKERNEL
376The virtual kernel platform does not have all the header files expected
377by a world build, so the easiest thing to do right now is to specify a
378pc32 target when building the world under a virtual kernel, like this:
379.Bd -literal
380vkernel# make MACHINE_PLATFORM=pc32 buildworld
381vkernel# make MACHINE_PLATFORM=pc32 installworld
382.Ed
79b58aae 383.Sh CONFIGURATION FILES
63568417
SW
384Your virtual kernel is a complete
385.Dx
386system, but you might not want to run all the services a normal kernel runs.
79b58aae
MD
387Here is what a typical virtual kernel's
388.Pa /etc/rc.conf
389file looks like, with some additional possibilities commented out.
390.Bd -literal
391hostname="vkernel"
392network_interfaces="lo0 vke0"
393ifconfig_vke0="DHCP"
394sendmail_enable="NO"
395#syslog_enable="NO"
66931b32 396blanktime="NO"
79b58aae 397.Ed
4af18995 398.Sh SEE ALSO
09b03fff
SW
399.Xr bridge 4 ,
400.Xr tap 4 ,
c8e7d028
SW
401.Xr vn 4 ,
402.Xr build 7 ,
403.Xr disklabel 8 ,
09b03fff 404.Xr ifconfig 8 ,
c8e7d028 405.Xr vnconfig 8
4af18995
SW
406.Sh HISTORY
407Virtual kernels were introduced in
408.Dx 1.7 .
409.Sh AUTHORS
410.An -nosplit
411.An Matt Dillon
412thought up and implemented the
413.Nm
0592e24d
SW
414architecture and wrote the
415.Nm vkd
416device driver.
417.An Sepherosa Ziehau
418wrote the
419.Nm vke
420device driver.
4af18995
SW
421This manual page was written by
422.An Sascha Wildner .