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