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