Sync ahc(4) and ahd(4) with FreeBSD 6.
[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.\"
34caba04 32.\" $DragonFly: src/share/man/man7/vkernel.7,v 1.23 2007/07/03 18:05:55 dillon Exp $
4af18995 33.\"
7834fbcc 34.Dd June 14, 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
MD
154.It Fl n Ar numcpus
155Specify the number of cpus you wish to emulate.
156Up to 32 cpus are supported.
157The virtual kernel must be built with options SMP to use this option
158and will default to 2 cpus unless otherwise specified.
b02b4170 159.It Fl p Ar file
dec8c72c 160Specify a file in which to store the process ID.
b02b4170 161A warning is issued if this file cannot be opened for writing.
4af18995 162.It Fl r Ar file
a72d8a9f 163Specify a R/W disk image
4af18995 164.Ar file
ec1a8a4d
SW
165to be used by the kernel, with the first
166.Fl r
167option defining
0592e24d 168.Li vkd0 ,
ec1a8a4d 169the second one
0592e24d 170.Li vkd1 ,
a72d8a9f
MD
171and so on. The first
172.Fl r
173or
174.Fl c
175option specified on the command line will be the boot disk.
c8e7d028
SW
176.It Fl s
177Boot into single-user mode.
03071031
SW
178.It Fl U
179Enable writing to kernel memory and module loading.
180By default, those are disabled for security reasons.
4af18995
SW
181.It Fl v
182Turn on verbose booting.
183.El
0592e24d
SW
184.Sh DEVICES
185A number of virtual device drivers exist to supplement the virtual kernel.
186Their names start with
187.Li vk .
188.Ss Disk device
189The
190.Nm vkd
191driver allows for up to 16
192.Xr vn 4
193based disk devices.
194The root device will be
195.Li vkd0
196(see
197.Sx EXAMPLES
198for further information on how to prepare a root image).
199.Ss Network interface
200The
201.Nm vke
202driver supports up to 16 virtual network interfaces which are associated with
203.Xr tap 4
204devices on the host.
205For each
206.Nm vke
207device, the per-interface read only
208.Xr sysctl 3
209variable
210.Va hw.vke Ns Em X Ns Va .tap_unit
211holds the unit number of the associated
212.Xr tap 4
213device.
1e4d9fd9 214.Sh SIGNALS
dec8c72c 215The virtual kernel only enables
bb195a01 216.Dv SIGQUIT
dec8c72c
SW
217and
218.Dv SIGTERM
219while operating in regular console mode.
220Sending
1e4d9fd9
SW
221.Ql \&^\e
222.Pq Dv SIGQUIT
bb195a01 223to the virtual kernel causes the virtual kernel to enter its internal
1e4d9fd9 224.Xr ddb 4
dec8c72c 225debugger and re-enable all other terminal signals.
bb195a01 226Sending
dec8c72c
SW
227.Dv SIGTERM
228to the virtual kernel triggers a clean shutdown by passing a
229.Dv SIGUSR2
230to the virtual kernel's
bb195a01
MD
231.Xr init 8
232process.
974b26bf
SW
233.Sh DEBUGGING
234It is possible to directly gdb the virtual kernel's process.
235It is recommended that you do a
236.Ql handle SIGSEGV noprint
237to ignore page faults processed by the virtual kernel itself.
c8e7d028 238.Sh EXAMPLES
4af18995
SW
239A couple of steps are necessary in order to prepare the system to build and
240run a virtual kernel.
241.Ss Setting up the filesystem
242The
243.Nm
244architecture needs a number of files which reside in
245.Pa /var/vkernel .
246Since these files tend to get rather big and the
247.Pa /var
248partition is usually of limited size, we recommend the directory to be
249created in the
250.Pa /home
251partition with a link to it in
252.Pa /var :
c8e7d028 253.Bd -literal
4af18995
SW
254mkdir /home/var.vkernel
255ln -s /home/var.vkernel /var/vkernel
256.Ed
257.Pp
258Next, a filesystem image to be used by the virtual kernel has to be
c8e7d028
SW
259created and populated (assuming world has been built previously):
260.Bd -literal
4af18995
SW
261dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
262vnconfig -c -s labels vn0 /var/vkernel/rootimg.01
58c55700
SW
263disklabel -r -w vn0s0 auto
264disklabel -e vn0s0 # edit the label to create a vn0s0a partition
265newfs /dev/vn0s0a
266mount /dev/vn0s0a /mnt
c8e7d028
SW
267cd /usr/src
268make installworld DESTDIR=/mnt
269cd etc
270make distribution DESTDIR=/mnt
6a060312 271echo '/dev/vkd0a / ufs rw 1 1' >/mnt/etc/fstab
7834fbcc
SW
272.Ed
273.Pp
274Edit
275.Pa /mnt/etc/ttys
276and replace the
277.Li console
278entry with the following line and turn off all other gettys.
279.Bd -literal
280console "/usr/libexec/getty Pc" cons25 on secure
281.Ed
282.Pp
283Then, unmount the disk.
284.Bd -literal
4af18995
SW
285umount /mnt
286vnconfig -u vn0
287.Ed
288.Ss Compiling the virtual kernel
289In order to compile a virtual kernel use the
290.Li VKERNEL
291kernel configuration file residing in
292.Pa /usr/src/sys/config
293(or a configuration file derived thereof):
c8e7d028 294.Bd -literal
4af18995 295cd /usr/src
09b03fff 296make -DNO_MODULES buildkernel KERNCONF=VKERNEL
4af18995
SW
297.Ed
298.Ss Enabling virtual kernel operation
299A special
300.Xr sysctl 8 ,
301.Va vm.vkernel_enable ,
302must be set to enable
303.Nm
304operation:
c8e7d028 305.Bd -literal
4af18995
SW
306sysctl vm.vkernel_enable=1
307.Ed
09b03fff
SW
308.Ss Configuring the network on the host system
309In order to access a network interface of the host system from the
310.Nm ,
311you must add the interface to a
312.Xr bridge 4
313device which will then be passed to the
314.Fl I
315option:
316.Bd -literal
317kldload if_bridge.ko
318kldload if_tap.ko
319ifconfig bridge0 create
320ifconfig bridge0 addm re0 # assuming re0 is the host's interface
321ifconfig bridge0 up
322.Ed
4af18995
SW
323.Ss Running the kernel
324Finally, the virtual kernel can be run:
c8e7d028 325.Bd -literal
4af18995 326cd /usr/obj/usr/src/sys/VKERNEL
09b03fff 327\&./kernel.debug -m 64m -r /var/vkernel/rootimg.01 -I auto:bridge0
4af18995 328.Ed
c8e7d028
SW
329.Pp
330The
331.Xr reboot 8
332command can be used to stop a virtual kernel.
34caba04
MD
333.Sh BUILDING THE WORLD UNDER A VKERNEL
334The virtual kernel platform does not have all the header files expected
335by a world build, so the easiest thing to do right now is to specify a
336pc32 target when building the world under a virtual kernel, like this:
337.Bd -literal
338vkernel# make MACHINE_PLATFORM=pc32 buildworld
339vkernel# make MACHINE_PLATFORM=pc32 installworld
340.Ed
4af18995 341.Sh SEE ALSO
09b03fff
SW
342.Xr bridge 4 ,
343.Xr tap 4 ,
c8e7d028
SW
344.Xr vn 4 ,
345.Xr build 7 ,
346.Xr disklabel 8 ,
09b03fff 347.Xr ifconfig 8 ,
c8e7d028 348.Xr vnconfig 8
4af18995
SW
349.Sh HISTORY
350Virtual kernels were introduced in
351.Dx 1.7 .
352.Sh AUTHORS
353.An -nosplit
354.An Matt Dillon
355thought up and implemented the
356.Nm
0592e24d
SW
357architecture and wrote the
358.Nm vkd
359device driver.
360.An Sepherosa Ziehau
361wrote the
362.Nm vke
363device driver.
4af18995
SW
364This manual page was written by
365.An Sascha Wildner .