Cast sentinel for execl() to (char *) to quiet gcc4 warning.
[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.\"
c8e7d028 32.\" $DragonFly: src/share/man/man7/vkernel.7,v 1.2 2007/01/14 10:43:32 swildner Exp $
4af18995 33.\"
c8e7d028 34.Dd January 14, 2007
4af18995
SW
35.Dt VKERNEL 7
36.Os
37.Sh NAME
38.Nm vkernel
39.Nd virtual kernel architecture
40.Sh SYNOPSIS
c8e7d028
SW
41.Cd "machine vkernel"
42.Cd "device vkd"
43.Cd "device vke"
44.Pp
4af18995 45.Pa /usr/obj/usr/src/sys/VKERNEL/kernel.debug
c8e7d028 46.Op Fl sv
4af18995
SW
47.Op Fl e Ar environment
48.\".Op Fl i Ar file
c8e7d028 49.\".Op Fl I Ar interface
4af18995
SW
50.Op Fl m Ar size
51.Op Fl r Ar file
4af18995
SW
52.Sh DESCRIPTION
53The
54.Nm
55architecture allows for running
56.Dx
57kernels in userland.
58.Pp
59The following options are available:
60.Bl -tag -width ".Fl m Ar size"
61.It Fl e Ar environment
c8e7d028 62Specify an
4af18995 63.Ar environment
c8e7d028
SW
64to be used by the kernel.
65The argument is a string of the form
4af18995
SW
66.Li name=value:name=value:...
67.\".It Fl i Ar file
68.\"Specify a memory image
69.\".Ar file
70.\"to be used by the kernel.
c8e7d028
SW
71.\".It Fl I Ar interface
72.\"Specify the host system's network interface to be used by the virtual kernel.
73.\"This is usually a
74.\".Xr tap 4
75.\"interface.
4af18995
SW
76.It Fl m Ar size
77Specify the amount of memory to be used by the kernel in bytes,
78.Cm K
79(kilobytes),
80.Cm M
81(megabytes) or
82.Cm G
83(gigabytes).
84Lowercase version of
85.Cm K , M ,
86and
87.Cm G
88are allowed.
89.It Fl r Ar file
90Specify the root image
91.Ar file
92to be used by the kernel.
93See
c8e7d028 94.Sx EXAMPLES
4af18995 95for further information on how to prepare a root image.
c8e7d028
SW
96.It Fl s
97Boot into single-user mode.
4af18995
SW
98.It Fl v
99Turn on verbose booting.
100.El
c8e7d028 101.Sh EXAMPLES
4af18995
SW
102A couple of steps are necessary in order to prepare the system to build and
103run a virtual kernel.
104.Ss Setting up the filesystem
105The
106.Nm
107architecture needs a number of files which reside in
108.Pa /var/vkernel .
109Since these files tend to get rather big and the
110.Pa /var
111partition is usually of limited size, we recommend the directory to be
112created in the
113.Pa /home
114partition with a link to it in
115.Pa /var :
c8e7d028 116.Bd -literal
4af18995
SW
117mkdir /home/var.vkernel
118ln -s /home/var.vkernel /var/vkernel
119.Ed
120.Pp
121Next, a filesystem image to be used by the virtual kernel has to be
c8e7d028
SW
122created and populated (assuming world has been built previously):
123.Bd -literal
4af18995
SW
124dd if=/dev/zero of=/var/vkernel/rootimg.01 bs=1m count=2048
125vnconfig -c -s labels vn0 /var/vkernel/rootimg.01
126disklabel -r -w vn0 auto
c8e7d028 127disklabel -e vn0 # edit the label to create a vn0a partition
4af18995
SW
128newfs /dev/vn0a
129mount /dev/vn0a /mnt
c8e7d028
SW
130cd /usr/src
131make installworld DESTDIR=/mnt
132cd etc
133make distribution DESTDIR=/mnt
134echo '/dev/vkd0 / ufs rw 1 1' >/mnt/etc/fstab
135echo 'console "/usr/libexec/getty Pc" cons25 on secure' >/mnt/etc/ttys
4af18995
SW
136umount /mnt
137vnconfig -u vn0
138.Ed
139.Ss Compiling the virtual kernel
140In order to compile a virtual kernel use the
141.Li VKERNEL
142kernel configuration file residing in
143.Pa /usr/src/sys/config
144(or a configuration file derived thereof):
c8e7d028 145.Bd -literal
4af18995
SW
146cd /usr/src
147make buildkernel KERNCONF=VKERNEL
148.Ed
149.Ss Enabling virtual kernel operation
150A special
151.Xr sysctl 8 ,
152.Va vm.vkernel_enable ,
153must be set to enable
154.Nm
155operation:
c8e7d028 156.Bd -literal
4af18995
SW
157sysctl vm.vkernel_enable=1
158.Ed
159.Ss Running the kernel
160Finally, the virtual kernel can be run:
c8e7d028 161.Bd -literal
4af18995
SW
162cd /usr/obj/usr/src/sys/VKERNEL
163\&./kernel.debug -m 64m -r /var/vkernel/rootimg.01
164.Ed
c8e7d028
SW
165.Pp
166The
167.Xr reboot 8
168command can be used to stop a virtual kernel.
169.\".Ss Setting up the network in the host system
170.\".Bd -literal
171.\"XXX
172.\".Ed
4af18995 173.Sh SEE ALSO
c8e7d028
SW
174.\".Xr tap 4 ,
175.Xr vn 4 ,
176.Xr build 7 ,
177.Xr disklabel 8 ,
178.Xr vnconfig 8
4af18995
SW
179.Sh HISTORY
180Virtual kernels were introduced in
181.Dx 1.7 .
182.Sh AUTHORS
183.An -nosplit
184.An Matt Dillon
185thought up and implemented the
186.Nm
187architecture.
188This manual page was written by
189.An Sascha Wildner .
190.Sh BUGS
191Virtual kernels are not yet fully operational.