-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathqrun.1
291 lines (291 loc) · 6.78 KB
/
qrun.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
.\" Copyright (c) 2010 Todd T. Fries <todd@fries.net>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt QRUN 1
.Os
.Sh NAME
.Nm qrun
.Nd qemu wrapper
.Sh SYNOPSIS
.Nm qrun
.Fl i Ar path
.Op Fl v
.Op Fl b Ar interface
.Op Fl C Ar path
.Op Fl c Ar path
.Op Fl M Ar mode
.Op Fl m Ar memsize
.Op Fl n Ar string
.Op Fl o Cm usernet \*(Ba bridge \*(Ba console \*(Ba netcfg
.Op Fl p Ar path
.Op Fl s Ar size
.Op Fl u Ar user
.Op Ar qemu-options
.Sh DESCRIPTION
.Nm
requires at least the
.Fl i
option to specify the disk image.
If a file does not exist, it will be created.
.Pp
.Nm
is based on semantics for qemu 2.12.0.
If trying to use it on another version of qemu, your mileage may vary.
.Pp
By default, user mode network emulation will be used, so no further
options are required for quick start usage.
See the
.Sx EXAMPLES
section below for other simple usages.
.Pp
The options
.Fl b ,
.Fl n ,
.Fl o ,
and
.Fl u
require
.Nm
to be executed as root, since they utilize privileged operations.
.Pp
The options are as follows:
.Pp
.Bl -tag -width Ds -compact
.It Fl b Ar interface
Specifies the
.Xr bridge 4
interface to bridge to a guest network interface.
If used multiple times, a new guest network interface will be created
for each instance, bridged to the network interfaces in the order specified.
.Pp
.It Fl C Ar path
Specifies the CD-ROM image or device from which to read blocks of data
when presenting the guest OS with a simulated
.Xr atapiscsi 4
CD-ROM device.
.Pp
.It Fl c Ar path
Identical to the
.Fl C
option, but additionally boots the guest OS from the simulated CD-ROM device.
.Pp
.It Fl i Ar path
Specifies the file or device from which to read blocks of data
when presenting the guest OS with a simulated
.Xr wd 4
device.
.Pp
.It Fl M Ar mode
Changes the machine presented to the guest OS.
By default, an i386 machine is presented.
The only other valid mode is amd64.
.Pp
.It Fl m Ar memsize
Alters the memory presented to the guest OS.
By default,
.Ar memsize
is 128m.
.Pp
.It Fl n Ar string
A string passed to
.Xr ifconfig 8
to configure the
.Xr tun 4
device.
This is for routing
.Xr qemu 1
sessions natively and/or NAT-ing them via
.Xr pf 4 .
Like the
.Fl b
option, multiple
.Fl n
options may be specified, each one coinciding with an interface presented
to the guest OS, in the order specified.
The
.Fl n
and
.Fl b
options may be both used if desired.
.Pp
.It Fl o Ar usernet,model=<nicmodel>,macaddr=52:54:01:00:XX:XX
.It Fl o Ar bridge=interface,model=<nicmodel>,macaddr=52:54:01:00:XX:XX
.It Fl o Ar netcfg=string,model=<nicmodel>,macaddr=52:54:01:00:XX:XX
.It Fl o Ar console=com0,monitor=stdio,serial=unix,vnc=[::]:3
.It Fl o Ar controllertype=<ctype>
Provides a more advanced usage of the
.Fl b
and
.Fl n
options as well as enabling a serial console to be presented at a terminal
prompt.
<nicmodel> can be one of
.Pp
.It Ar e1000
.It Ar rtl8139
.It Ar virtio-net
.it Ar etc...
.Pp
<ctype> can be one of
.Pp
.It Ar ahci
.It Ar isa-ide
.It Ar lsi53c895a
.It Ar virtio-blk-pci
.It Ar usb-storage
If combined with the
.Fl p
option and an
.Pa /etc/boot.conf
file containing
.Dq set tty com0 ,
a system may be booted to a serial console in a terminal without requiring
graphics.
This can be especially useful for running inside
.Xr tmux 1 .
.Pp
The
.Ar interface
option to bridge may be a physical interface, such as em0, or a special
notation:
.Bd -literal -offset indent
.Ar group:string
.Ed
.Pp
This special notation permits multiple qrun instances to be bridged together,
by adding the string to the interface group of the
.Xr bridge 4
instead of bridging to a physical interface.
This mainly for the
.Xr qnet 1
script, but advanced users may choose to use it themselves.
The string is limited by interface group limitations and therefore
may not end in a number.
.Pp
.It Fl p Ar path
Specifies the tftpboot dir from which to
.Xr pxeboot 8
the guest OS.
The guest virtual machines BIOS will TFTP the file
.Dq pxeboot
from the
.Ar path
specified and start executing it as a real system would.
.Pp
.It Fl s Ar size
Specifies the size of the disk image to create, if
.Nm
is auto-creating the disk image.
.Pp
.It Fl u Ar user
Runs
.Xr qemu 1
as user
.Ar user .
This is recommended if one of the options requiring root privileges is
used, as the environment will be set up then the fdpass program will drop
privileges to the user specified and qemu will not be running as root.
.Pp
.It Fl v
Provides verbose information while setting up
.Xr bridge 4
and
.Xr tun 4
interfaces as well as showing the
.Xr qemu 1
command line used when starting qemu.
.El
.Sh ENVIRONMENT
No environment variables are useful at this time.
.Sh EXAMPLES
Here are examples on how to use
.Nm .
.Pp
The most basic simple usage would be to install a guest OS with user mode
networking:
.Pp
.Dl $ qrun -i test.hd -c cd47.iso
.Pp
After the installation, one would issue
.Dq quit
at the
.Dq (qemu)
prompt and then start
.Xr qemu 1
subsequently via:
.Pp
.Dl $ qrun -i test.hd
.Pp
Another common way to use
.Nm
would be to bridge the native Ethernet to a
.Xr qemu 1
guest's network interface:
.Pp
.Dl $ sudo qrun -u $USER -i test.hd -b em0
.Pp
This sets up a
.Xr bridge 4
interface to connect the
.Xr em 4
interface of the native system and the
.Xr tun 4
interface of the
.Xr qemu 1
guest OS.
.Pp
The third common way to use
.Nm
would be to route the
.Xr qemu 1
guest's network interface:
.Pp
.Dl $ sudo qrun -u $USER -i test.hd -n 10.0.1.1/24
.Pp
This would set up a
.Xr tun 4
interface with
.Dq 10.0.1.1 netmask 255.255.255.0
and it would be up to the user to run
.Xr dhcpd 8
on the
.Xr tun 4
interface connected to the
.Xr qemu 1
guest OS.
.Pp
One final advanced example that most people will not want to bother with but
can show the power of
.Nm :
.Bd -literal -offset indent
$ sudo qrun -u $USER -i `pwd`/test.hd \e
-o bridge=em0,model=rtl8139,macaddr=52:54:01:00:XX:XX \e
-o console=com0 \e
-- \e
-serial telnet:127.0.0.1:30000,server,nowait \e
-monitor telnet:127.0.0.1:40000,server,nowait \e
-daemonize
.Ed
.Sh SEE ALSO
.Xr fdpass 1 ,
.Xr qemu 1 ,
.Xr bridge 4 ,
.Xr pf 4 ,
.Xr tun 4
.Sh HISTORY
This utility is entirely a new creation from
.An Todd T. Fries Aq todd@fries.net ,
inspired by
.An Bob Beck Aq beck@openbsd.org .