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