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