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