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