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