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