Sort sections in various manual pages.
[dragonfly.git] / share / man / man7 / vkernel.7
CommitLineData
4af18995 1.\"
98b2ba80 2.\" Copyright (c) 2006, 2007
4af18995
SW
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.\"
b6a66df5 32.Dd March 28, 2010
4af18995
SW
33.Dt VKERNEL 7
34.Os
35.Sh NAME
0592e24d 36.Nm vkernel ,
98b2ba80 37.Nm vcd ,
0592e24d
SW
38.Nm vkd ,
39.Nm vke
4af18995
SW
40.Nd virtual kernel architecture
41.Sh SYNOPSIS
b6a66df5
SW
42.Cd "platform vkernel # for 32 bit vkernels"
43.Cd "platform vkernel64 # for 64 bit vkernels"
98b2ba80 44.Cd "device vcd"
c8e7d028
SW
45.Cd "device vkd"
46.Cd "device vke"
47.Pp
c009fcfa 48.Pa /var/vkernel/boot/kernel
03071031 49.Op Fl sUv
a72d8a9f 50.Op Fl c Ar file
09b03fff 51.Op Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
dd54cb3a 52.Op Fl i Ar file
09b03fff 53.Op Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
702acf06 54.Op Fl l Ar cpulock
4af18995 55.Op Fl m Ar size
c5b0b0ba 56.Op Fl n Ar numcpus
b02b4170 57.Op Fl p Ar file
4af18995 58.Op Fl r Ar file
4af18995
SW
59.Sh DESCRIPTION
60The
61.Nm
62architecture allows for running
63.Dx
64kernels in userland.
65.Pp
66The following options are available:
67.Bl -tag -width ".Fl m Ar size"
a72d8a9f 68.It Fl c Ar file
7834fbcc 69Specify a readonly CD-ROM image
a72d8a9f
MD
70.Ar file
71to be used by the kernel, with the first
72.Fl c
73option defining
74.Li vcd0 ,
75the second one
76.Li vcd1 ,
62aea38e
SW
77and so on.
78The first
a72d8a9f
MD
79.Fl r
80or
81.Fl c
82option specified on the command line will be the boot disk.
7834fbcc 83The CD9660 filesystem is assumed when booting from this media.
09b03fff
SW
84.It Fl e Ar name Ns = Ns Li value : Ns Ar name Ns = Ns Li value : Ns ...
85Specify an environment to be used by the kernel.
dd54cb3a
SW
86.It Fl i Ar file
87Specify a memory image
88.Ar file
89to be used by the virtual kernel.
90If no
91.Fl i
92option is given, the kernel will generate a name of the form
93.Pa /var/vkernel/memimg.XXXXXX ,
94with the trailing
95.Ql X Ns s
96being replaced by a sequential number, e.g.\&
97.Pa memimg.000001 .
09b03fff
SW
98.It Fl I Ar interface Ns Op Ar :address1 Ns Oo Ar :address2 Oc Ns Oo Ar /netmask Oc
99Create a virtual network device, with the first
100.Fl I
101option defining
0592e24d 102.Li vke0 ,
09b03fff 103the second one
0592e24d 104.Li vke1 ,
09b03fff
SW
105and so on.
106.Pp
107The
108.Ar interface
109argument is the name of a
110.Xr tap 4
111device node.
112The
113.Pa /dev/
114path prefix does not have to be specified and will be automatically prepended.
115Specifying
116.Cm auto
117will pick the first unused
118.Xr tap 4
119device.
120.Pp
121The
122.Ar address1
123and
124.Ar address2
125arguments are the IP addresses of the
126.Xr tap 4
127and
0592e24d 128.Nm vke
09b03fff
SW
129interfaces.
130Optionally,
131.Ar address1
132may be of the form
133.Li bridge Ns Em X
134in which case the
135.Xr tap 4
136interface is added to the specified
137.Xr bridge 4
138interface.
a8cc122d
SW
139The
140.Nm vke
141address is not assigned until the interface is brought up in the guest.
09b03fff
SW
142.Pp
143The
144.Ar netmask
145argument applies to all interfaces for which an address is specified.
702acf06
JT
146.It Fl l Ar cpulock
147Specify which, if any, real CPUs to lock virtual CPUs to.
148.Ar cpulock
149is one of
26ea2793
SW
150.Cm any ,
151.Cm map Ns Op Ns , Ns Ar startCPU ,
152or
153.Ar CPU .
702acf06
JT
154.Pp
155.Cm any
26ea2793
SW
156does not map virtual CPUs to real CPUs.
157This is the default.
702acf06
JT
158.Pp
159.Cm map Ns Op Ns , Ns Ar startCPU
160maps each virtual CPU to a real CPU starting with real CPU 0 or
161.Ar startCPU
162if specified.
163.Pp
164.Ar CPU
26ea2793
SW
165locks all virtual CPUs to the real CPU specified by
166.Ar CPU .
4af18995
SW
167.It Fl m Ar size
168Specify the amount of memory to be used by the kernel in bytes,
169.Cm K
3cea05a4 170.Pq kilobytes ,
4af18995 171.Cm M
3cea05a4
SW
172.Pq megabytes
173or
4af18995 174.Cm G
3cea05a4 175.Pq gigabytes .
09b03fff 176Lowercase versions of
4af18995
SW
177.Cm K , M ,
178and
179.Cm G
180are allowed.
c5b0b0ba 181.It Fl n Ar numcpus
8cf87c92 182Specify the number of CPUs you wish to emulate.
43cfb771 183Up to 16 CPUs are supported.
8cf87c92
SW
184The virtual kernel must be built with
185.Cd options SMP
186to use this option and will default to 2 CPUs unless otherwise specified.
b02b4170 187.It Fl p Ar file
dec8c72c 188Specify a file in which to store the process ID.
b02b4170 189A warning is issued if this file cannot be opened for writing.
4af18995 190.It Fl r Ar file
a72d8a9f 191Specify a R/W disk image
4af18995 192.Ar file
ec1a8a4d
SW
193to be used by the kernel, with the first
194.Fl r
195option defining
0592e24d 196.Li vkd0 ,
ec1a8a4d 197the second one
0592e24d 198.Li vkd1 ,
62aea38e
SW
199and so on.
200The first
a72d8a9f
MD
201.Fl r
202or
203.Fl c
204option specified on the command line will be the boot disk.
c8e7d028
SW
205.It Fl s
206Boot into single-user mode.
03071031
SW
207.It Fl U
208Enable writing to kernel memory and module loading.
209By default, those are disabled for security reasons.
4af18995
SW
210.It Fl v
211Turn on verbose booting.
212.El
0592e24d
SW
213.Sh DEVICES
214A number of virtual device drivers exist to supplement the virtual kernel.
0592e24d
SW
215.Ss Disk device
216The
217.Nm vkd
218driver allows for up to 16
219.Xr vn 4
220based disk devices.
221The root device will be
222.Li vkd0
223(see
224.Sx EXAMPLES
225for further information on how to prepare a root image).
98b2ba80
SW
226.Ss CD-ROM device
227The
228.Nm vcd
229driver allows for up to 16 virtual CD-ROM devices.
230Basically this is a read only
231.Nm vkd
232device with a block size of 2048.
0592e24d
SW
233.Ss Network interface
234The
235.Nm vke
236driver supports up to 16 virtual network interfaces which are associated with
237.Xr tap 4
238devices on the host.
239For each
240.Nm vke
241device, the per-interface read only
242.Xr sysctl 3
243variable
244.Va hw.vke Ns Em X Ns Va .tap_unit
245holds the unit number of the associated
246.Xr tap 4
247device.
1e4d9fd9 248.Sh SIGNALS
dec8c72c 249The virtual kernel only enables
bb195a01 250.Dv SIGQUIT
dec8c72c
SW
251and
252.Dv SIGTERM
253while operating in regular console mode.
254Sending
1e4d9fd9
SW
255.Ql \&^\e
256.Pq Dv SIGQUIT
bb195a01 257to the virtual kernel causes the virtual kernel to enter its internal
1e4d9fd9 258.Xr ddb 4
dec8c72c 259debugger and re-enable all other terminal signals.
bb195a01 260Sending
dec8c72c
SW
261.Dv SIGTERM
262to the virtual kernel triggers a clean shutdown by passing a
263.Dv SIGUSR2
264to the virtual kernel's
bb195a01
MD
265.Xr init 8
266process.
974b26bf
SW
267.Sh DEBUGGING
268It is possible to directly gdb the virtual kernel's process.
269It is recommended that you do a
270.Ql handle SIGSEGV noprint
4010bf94 271to ignore page faults processed by the virtual kernel itself and
e7c2f376 272.Ql handle SIGUSR1 noprint
4010bf94
NT
273to ignore signals used for simulating inter-processor interrupts (SMP build
274only).
a154d422
TN
275.Sh FILES
276.Bl -tag -width ".It Pa /sys/config/VKERNEL" -compact
277.It Pa /sys/config/VKERNEL
278default
279.Nm
280configuration file, for
281.Xr config 8 .
282.El
a68e0df0
SW
283.Sh CONFIGURATION FILES
284Your virtual kernel is a complete
285.Dx
286system, but you might not want to run all the services a normal kernel runs.
287Here is what a typical virtual kernel's
288.Pa /etc/rc.conf
289file looks like, with some additional possibilities commented out.
290.Bd -literal
291hostname="vkernel"
292network_interfaces="lo0 vke0"
293ifconfig_vke0="DHCP"
294sendmail_enable="NO"
295#syslog_enable="NO"
296blanktime="NO"
297.Ed
c8e7d028 298.Sh EXAMPLES
4af18995
SW
299A couple of steps are necessary in order to prepare the system to build and
300run a virtual kernel.
301.Ss Setting up the filesystem
302The
303.Nm
304architecture needs a number of files which reside in
305.Pa /var/vkernel .
306Since these files tend to get rather big and the
307.Pa /var
308partition is usually of limited size, we recommend the directory to be
309created in the
310.Pa /home
311partition with a link to it in
312.Pa /var :
c8e7d028 313.Bd -literal
c009fcfa 314mkdir -p /home/var.vkernel/boot
4af18995
SW
315ln -s /home/var.vkernel /var/vkernel
316.Ed
317.Pp
318Next, a filesystem image to be used by the virtual kernel has to be
62aea38e
SW
319created and populated (assuming world has been built previously).
320If the image is created on a UFS filesystem you might want to pre-zero it.
49802d4e
MD
321On a HAMMER filesystem you should just truncate-extend to the image size
322as HAMMER does not re-use data blocks already present in the file.
c8e7d028 323.Bd -literal
49802d4e 324vnconfig -c -s labels -S 2g -T vn0 /var/vkernel/rootimg.01
58c55700 325disklabel -r -w vn0s0 auto
c009fcfa 326disklabel -e vn0s0 # add `a' partition with fstype `4.2BSD'
58c55700
SW
327newfs /dev/vn0s0a
328mount /dev/vn0s0a /mnt
c8e7d028
SW
329cd /usr/src
330make installworld DESTDIR=/mnt
331cd etc
332make distribution DESTDIR=/mnt
7a3238b8 333echo '/dev/vkd0s0a / ufs rw 1 1' >/mnt/etc/fstab
98b2ba80 334echo 'proc /proc procfs rw 0 0' >>/mnt/etc/fstab
7834fbcc
SW
335.Ed
336.Pp
337Edit
338.Pa /mnt/etc/ttys
339and replace the
340.Li console
341entry with the following line and turn off all other gettys.
342.Bd -literal
343console "/usr/libexec/getty Pc" cons25 on secure
344.Ed
345.Pp
eed435dd
SK
346Replace
347.Li \&Pc
348with
349.Li al.Pc
350if you would like to automatically log in as root.
351.Pp
7834fbcc
SW
352Then, unmount the disk.
353.Bd -literal
4af18995
SW
354umount /mnt
355vnconfig -u vn0
356.Ed
357.Ss Compiling the virtual kernel
358In order to compile a virtual kernel use the
359.Li VKERNEL
360kernel configuration file residing in
a154d422 361.Pa /sys/config
4af18995 362(or a configuration file derived thereof):
c8e7d028 363.Bd -literal
4af18995 364cd /usr/src
09b03fff 365make -DNO_MODULES buildkernel KERNCONF=VKERNEL
79b58aae 366make -DNO_MODULES installkernel KERNCONF=VKERNEL DESTDIR=/var/vkernel
4af18995
SW
367.Ed
368.Ss Enabling virtual kernel operation
369A special
370.Xr sysctl 8 ,
371.Va vm.vkernel_enable ,
372must be set to enable
373.Nm
374operation:
c8e7d028 375.Bd -literal
4af18995
SW
376sysctl vm.vkernel_enable=1
377.Ed
09b03fff
SW
378.Ss Configuring the network on the host system
379In order to access a network interface of the host system from the
380.Nm ,
381you must add the interface to a
382.Xr bridge 4
383device which will then be passed to the
384.Fl I
385option:
386.Bd -literal
387kldload if_bridge.ko
388kldload if_tap.ko
389ifconfig bridge0 create
390ifconfig bridge0 addm re0 # assuming re0 is the host's interface
391ifconfig bridge0 up
392.Ed
4af18995
SW
393.Ss Running the kernel
394Finally, the virtual kernel can be run:
c8e7d028 395.Bd -literal
79b58aae 396cd /var/vkernel
c009fcfa 397\&./boot/kernel -m 64m -r rootimg.01 -I auto:bridge0
4af18995 398.Ed
c8e7d028 399.Pp
79b58aae
MD
400You can issue the
401.Xr reboot 8 ,
402.Xr halt 8 ,
403or
404.Xr shutdown 8
405commands from inside a virtual kernel.
406After doing a clean shutdown the
c8e7d028 407.Xr reboot 8
79b58aae
MD
408command will re-exec the virtual kernel binary while the other two will
409cause the virtual kernel to exit.
34caba04
MD
410.Sh BUILDING THE WORLD UNDER A VKERNEL
411The virtual kernel platform does not have all the header files expected
412by a world build, so the easiest thing to do right now is to specify a
b6a66df5
SW
413pc32 (in a 32 bit vkernel) or pc64 (in a 64 bit vkernel) target when
414building the world under a virtual kernel, like this:
34caba04
MD
415.Bd -literal
416vkernel# make MACHINE_PLATFORM=pc32 buildworld
417vkernel# make MACHINE_PLATFORM=pc32 installworld
418.Ed
4af18995 419.Sh SEE ALSO
666855ca 420.Xr vknet 1 ,
09b03fff
SW
421.Xr bridge 4 ,
422.Xr tap 4 ,
c8e7d028 423.Xr vn 4 ,
a154d422 424.Xr sysctl.conf 5 ,
c8e7d028
SW
425.Xr build 7 ,
426.Xr disklabel 8 ,
09b03fff 427.Xr ifconfig 8 ,
dbfd168b 428.Xr vknetd 8 ,
c8e7d028 429.Xr vnconfig 8
c203b6f9
SW
430.Rs
431.%A Aggelos Economopoulos
432.%D March 2007
433.%T "A Peek at the DragonFly Virtual Kernel"
434.Re
4af18995
SW
435.Sh HISTORY
436Virtual kernels were introduced in
437.Dx 1.7 .
438.Sh AUTHORS
439.An -nosplit
440.An Matt Dillon
441thought up and implemented the
442.Nm
0592e24d
SW
443architecture and wrote the
444.Nm vkd
445device driver.
446.An Sepherosa Ziehau
447wrote the
448.Nm vke
449device driver.
4af18995
SW
450This manual page was written by
451.An Sascha Wildner .