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