jcs.org
qemu with hax to log dma reads & writes
jcs.org/2018/11/12/vfio
docs/system: convert Texinfo documentation to rST
Apart from targets.rst, which was written by hand, this is an automated
conversion obtained with the following command:
makeinfo --force -o - --docbook \
-D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \
-D 'qemu_system QEMU_SYSTEM_MACRO' \
$texi | pandoc -f docbook -t rst+smart | perl -e '
$/=undef;
$_ = <>;
s/^- − /- /gm;
s/QEMU_SYSTEM_MACRO/|qemu_system|/g;
s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g;
s/(?=::\n\n +\|qemu)/.. parsed-literal/g;
s/:\n\n::$/::/gm;
print' > $rst
In addition, the following changes were made manually:
- target-i386.rst and target-mips.rst: replace CPU model documentation with
an include directive
- monitor.rst: replace the command section with a comment
- images.rst: add toctree
- target-arm.rst: Replace use of :math: (which Sphinx complains
about) with :sup:, and hide it behind |I2C| and |I2C| substitutions.
Content that is not @included remains exclusive to qemu-doc.texi.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200228153619.9906-20-peter.maydell@linaro.org
Message-id: 20200226113034.6741-19-pbonzini@redhat.com
[PMM: Fixed target-arm.rst use of :math:; remove out of date
note about images.rst from commit message; fixed expansion
of |qemu_system_x86|; use parsed-literal in invocation.rst
when we want to use |qemu_system_x86|; fix incorrect subsection
level for "OS requirements" in target-i386.rst; fix incorrect
syntax for making links to other sections of the manual]
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
authored by
Paolo Bonzini
and committed by
Peter Maydell
324b2298
41fba161
+2207
-5
+8
-4
docs/defs.rst.inc
+8
-4
docs/defs.rst.inc
···
3
3
all rST files as part of the epilogue by docs/conf.py. conf.py
4
4
also defines some dynamically generated substitutions like CONFDIR.
5
5
6
-
Note that |qemu_system| is intended to be used inside a parsed-literal
7
-
block: the definition must not include extra literal formatting with
8
-
``..``: this works in the HTML output but the manpages will end up
9
-
misrendered with following normal text incorrectly in boldface.
6
+
Note that |qemu_system| and |qemu_system_x86| are intended to be
7
+
used inside a parsed-literal block: the definition must not include
8
+
extra literal formatting with ``..``: this works in the HTML output
9
+
but the manpages will end up misrendered with following normal text
10
+
incorrectly in boldface.
10
11
11
12
.. |qemu_system| replace:: qemu-system-x86_64
13
+
.. |qemu_system_x86| replace:: qemu_system-x86_64
14
+
.. |I2C| replace:: I\ :sup:`2`\ C
15
+
.. |I2S| replace:: I\ :sup:`2`\ S
+79
docs/system/build-platforms.rst
+79
docs/system/build-platforms.rst
···
1
+
.. _Supported-build-platforms:
2
+
3
+
Supported build platforms
4
+
=========================
5
+
6
+
QEMU aims to support building and executing on multiple host OS
7
+
platforms. This appendix outlines which platforms are the major build
8
+
targets. These platforms are used as the basis for deciding upon the
9
+
minimum required versions of 3rd party software QEMU depends on. The
10
+
supported platforms are the targets for automated testing performed by
11
+
the project when patches are submitted for review, and tested before and
12
+
after merge.
13
+
14
+
If a platform is not listed here, it does not imply that QEMU won't
15
+
work. If an unlisted platform has comparable software versions to a
16
+
listed platform, there is every expectation that it will work. Bug
17
+
reports are welcome for problems encountered on unlisted platforms
18
+
unless they are clearly older vintage than what is described here.
19
+
20
+
Note that when considering software versions shipped in distros as
21
+
support targets, QEMU considers only the version number, and assumes the
22
+
features in that distro match the upstream release with the same
23
+
version. In other words, if a distro backports extra features to the
24
+
software in their distro, QEMU upstream code will not add explicit
25
+
support for those backports, unless the feature is auto-detectable in a
26
+
manner that works for the upstream releases too.
27
+
28
+
The Repology site https://repology.org is a useful resource to identify
29
+
currently shipped versions of software in various operating systems,
30
+
though it does not cover all distros listed below.
31
+
32
+
Linux OS
33
+
--------
34
+
35
+
For distributions with frequent, short-lifetime releases, the project
36
+
will aim to support all versions that are not end of life by their
37
+
respective vendors. For the purposes of identifying supported software
38
+
versions, the project will look at Fedora, Ubuntu, and openSUSE distros.
39
+
Other short- lifetime distros will be assumed to ship similar software
40
+
versions.
41
+
42
+
For distributions with long-lifetime releases, the project will aim to
43
+
support the most recent major version at all times. Support for the
44
+
previous major version will be dropped 2 years after the new major
45
+
version is released, or when it reaches "end of life". For the purposes
46
+
of identifying supported software versions, the project will look at
47
+
RHEL, Debian, Ubuntu LTS, and SLES distros. Other long-lifetime distros
48
+
will be assumed to ship similar software versions.
49
+
50
+
Windows
51
+
-------
52
+
53
+
The project supports building with current versions of the MinGW
54
+
toolchain, hosted on Linux.
55
+
56
+
macOS
57
+
-----
58
+
59
+
The project supports building with the two most recent versions of
60
+
macOS, with the current homebrew package set available.
61
+
62
+
FreeBSD
63
+
-------
64
+
65
+
The project aims to support the all the versions which are not end of
66
+
life.
67
+
68
+
NetBSD
69
+
------
70
+
71
+
The project aims to support the most recent major version at all times.
72
+
Support for the previous major version will be dropped 2 years after the
73
+
new major version is released.
74
+
75
+
OpenBSD
76
+
-------
77
+
78
+
The project aims to support the all the versions which are not end of
79
+
life.
+81
docs/system/gdb.rst
+81
docs/system/gdb.rst
···
1
+
.. _gdb_005fusage:
2
+
3
+
GDB usage
4
+
---------
5
+
6
+
QEMU has a primitive support to work with gdb, so that you can do
7
+
'Ctrl-C' while the virtual machine is running and inspect its state.
8
+
9
+
In order to use gdb, launch QEMU with the '-s' option. It will wait for
10
+
a gdb connection:
11
+
12
+
.. parsed-literal::
13
+
14
+
|qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
15
+
Connected to host network interface: tun0
16
+
Waiting gdb connection on port 1234
17
+
18
+
Then launch gdb on the 'vmlinux' executable::
19
+
20
+
> gdb vmlinux
21
+
22
+
In gdb, connect to QEMU::
23
+
24
+
(gdb) target remote localhost:1234
25
+
26
+
Then you can use gdb normally. For example, type 'c' to launch the
27
+
kernel::
28
+
29
+
(gdb) c
30
+
31
+
Here are some useful tips in order to use gdb on system code:
32
+
33
+
1. Use ``info reg`` to display all the CPU registers.
34
+
35
+
2. Use ``x/10i $eip`` to display the code at the PC position.
36
+
37
+
3. Use ``set architecture i8086`` to dump 16 bit code. Then use
38
+
``x/10i $cs*16+$eip`` to dump the code at the PC position.
39
+
40
+
Advanced debugging options:
41
+
42
+
The default single stepping behavior is step with the IRQs and timer
43
+
service routines off. It is set this way because when gdb executes a
44
+
single step it expects to advance beyond the current instruction. With
45
+
the IRQs and timer service routines on, a single step might jump into
46
+
the one of the interrupt or exception vectors instead of executing the
47
+
current instruction. This means you may hit the same breakpoint a number
48
+
of times before executing the instruction gdb wants to have executed.
49
+
Because there are rare circumstances where you want to single step into
50
+
an interrupt vector the behavior can be controlled from GDB. There are
51
+
three commands you can query and set the single step behavior:
52
+
53
+
``maintenance packet qqemu.sstepbits``
54
+
This will display the MASK bits used to control the single stepping
55
+
IE:
56
+
57
+
::
58
+
59
+
(gdb) maintenance packet qqemu.sstepbits
60
+
sending: "qqemu.sstepbits"
61
+
received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
62
+
63
+
``maintenance packet qqemu.sstep``
64
+
This will display the current value of the mask used when single
65
+
stepping IE:
66
+
67
+
::
68
+
69
+
(gdb) maintenance packet qqemu.sstep
70
+
sending: "qqemu.sstep"
71
+
received: "0x7"
72
+
73
+
``maintenance packet Qqemu.sstep=HEX_VALUE``
74
+
This will change the single step mask, so if wanted to enable IRQs on
75
+
the single step, but not timers, you would use:
76
+
77
+
::
78
+
79
+
(gdb) maintenance packet Qqemu.sstep=0x5
80
+
sending: "qemu.sstep=0x5"
81
+
received: "OK"
+85
docs/system/images.rst
+85
docs/system/images.rst
···
1
+
.. _disk_005fimages:
2
+
3
+
Disk Images
4
+
-----------
5
+
6
+
QEMU supports many disk image formats, including growable disk images
7
+
(their size increase as non empty sectors are written), compressed and
8
+
encrypted disk images.
9
+
10
+
.. _disk_005fimages_005fquickstart:
11
+
12
+
Quick start for disk image creation
13
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14
+
15
+
You can create a disk image with the command::
16
+
17
+
qemu-img create myimage.img mysize
18
+
19
+
where myimage.img is the disk image filename and mysize is its size in
20
+
kilobytes. You can add an ``M`` suffix to give the size in megabytes and
21
+
a ``G`` suffix for gigabytes.
22
+
23
+
See the qemu-img invocation documentation for more information.
24
+
25
+
.. _disk_005fimages_005fsnapshot_005fmode:
26
+
27
+
Snapshot mode
28
+
~~~~~~~~~~~~~
29
+
30
+
If you use the option ``-snapshot``, all disk images are considered as
31
+
read only. When sectors in written, they are written in a temporary file
32
+
created in ``/tmp``. You can however force the write back to the raw
33
+
disk images by using the ``commit`` monitor command (or C-a s in the
34
+
serial console).
35
+
36
+
.. _vm_005fsnapshots:
37
+
38
+
VM snapshots
39
+
~~~~~~~~~~~~
40
+
41
+
VM snapshots are snapshots of the complete virtual machine including CPU
42
+
state, RAM, device state and the content of all the writable disks. In
43
+
order to use VM snapshots, you must have at least one non removable and
44
+
writable block device using the ``qcow2`` disk image format. Normally
45
+
this device is the first virtual hard drive.
46
+
47
+
Use the monitor command ``savevm`` to create a new VM snapshot or
48
+
replace an existing one. A human readable name can be assigned to each
49
+
snapshot in addition to its numerical ID.
50
+
51
+
Use ``loadvm`` to restore a VM snapshot and ``delvm`` to remove a VM
52
+
snapshot. ``info snapshots`` lists the available snapshots with their
53
+
associated information::
54
+
55
+
(qemu) info snapshots
56
+
Snapshot devices: hda
57
+
Snapshot list (from hda):
58
+
ID TAG VM SIZE DATE VM CLOCK
59
+
1 start 41M 2006-08-06 12:38:02 00:00:14.954
60
+
2 40M 2006-08-06 12:43:29 00:00:18.633
61
+
3 msys 40M 2006-08-06 12:44:04 00:00:23.514
62
+
63
+
A VM snapshot is made of a VM state info (its size is shown in
64
+
``info snapshots``) and a snapshot of every writable disk image. The VM
65
+
state info is stored in the first ``qcow2`` non removable and writable
66
+
block device. The disk image snapshots are stored in every disk image.
67
+
The size of a snapshot in a disk image is difficult to evaluate and is
68
+
not shown by ``info snapshots`` because the associated disk sectors are
69
+
shared among all the snapshots to save disk space (otherwise each
70
+
snapshot would need a full copy of all the disk images).
71
+
72
+
When using the (unrelated) ``-snapshot`` option
73
+
(:ref:`disk_005fimages_005fsnapshot_005fmode`),
74
+
you can always make VM snapshots, but they are deleted as soon as you
75
+
exit QEMU.
76
+
77
+
VM snapshots currently have the following known limitations:
78
+
79
+
- They cannot cope with removable devices if they are removed or
80
+
inserted after a snapshot is done.
81
+
82
+
- A few device drivers still have incomplete snapshot support so their
83
+
state is not saved or restored properly (in particular USB).
84
+
85
+
.. include:: qemu-block-drivers.rst.inc
+18
-1
docs/system/index.rst
+18
-1
docs/system/index.rst
···
12
12
Contents:
13
13
14
14
.. toctree::
15
-
:maxdepth: 2
15
+
:maxdepth: 3
16
+
17
+
quickstart
18
+
invocation
19
+
keys
20
+
mux-chardev
21
+
monitor
22
+
images
23
+
net
24
+
usb
25
+
ivshmem
26
+
linuxboot
27
+
vnc-security
28
+
tls
29
+
gdb
16
30
managed-startup
31
+
targets
17
32
security
18
33
vfio-ap
19
34
deprecated
35
+
build-platforms
36
+
license
+242
docs/system/invocation.rst
+242
docs/system/invocation.rst
···
1
+
.. _sec_005finvocation:
2
+
3
+
Invocation
4
+
----------
5
+
6
+
.. parsed-literal::
7
+
8
+
|qemu_system| [options] [disk_image]
9
+
10
+
disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
11
+
not need a disk image.
12
+
13
+
Device URL Syntax
14
+
~~~~~~~~~~~~~~~~~
15
+
16
+
In addition to using normal file images for the emulated storage
17
+
devices, QEMU can also use networked resources such as iSCSI devices.
18
+
These are specified using a special URL syntax.
19
+
20
+
``iSCSI``
21
+
iSCSI support allows QEMU to access iSCSI resources directly and use
22
+
as images for the guest storage. Both disk and cdrom images are
23
+
supported.
24
+
25
+
Syntax for specifying iSCSI LUNs is
26
+
"iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
27
+
28
+
By default qemu will use the iSCSI initiator-name
29
+
'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
30
+
the command line or a configuration file.
31
+
32
+
Since version Qemu 2.4 it is possible to specify a iSCSI request
33
+
timeout to detect stalled requests and force a reestablishment of the
34
+
session. The timeout is specified in seconds. The default is 0 which
35
+
means no timeout. Libiscsi 1.15.0 or greater is required for this
36
+
feature.
37
+
38
+
Example (without authentication):
39
+
40
+
.. parsed-literal::
41
+
42
+
|qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
43
+
-cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
44
+
-drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
45
+
46
+
Example (CHAP username/password via URL):
47
+
48
+
.. parsed-literal::
49
+
50
+
|qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
51
+
52
+
Example (CHAP username/password via environment variables):
53
+
54
+
.. parsed-literal::
55
+
56
+
LIBISCSI_CHAP_USERNAME="user" \
57
+
LIBISCSI_CHAP_PASSWORD="password" \
58
+
|qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
59
+
60
+
``NBD``
61
+
QEMU supports NBD (Network Block Devices) both using TCP protocol as
62
+
well as Unix Domain Sockets. With TCP, the default port is 10809.
63
+
64
+
Syntax for specifying a NBD device using TCP, in preferred URI form:
65
+
"nbd://<server-ip>[:<port>]/[<export>]"
66
+
67
+
Syntax for specifying a NBD device using Unix Domain Sockets;
68
+
remember that '?' is a shell glob character and may need quoting:
69
+
"nbd+unix:///[<export>]?socket=<domain-socket>"
70
+
71
+
Older syntax that is also recognized:
72
+
"nbd:<server-ip>:<port>[:exportname=<export>]"
73
+
74
+
Syntax for specifying a NBD device using Unix Domain Sockets
75
+
"nbd:unix:<domain-socket>[:exportname=<export>]"
76
+
77
+
Example for TCP
78
+
79
+
.. parsed-literal::
80
+
81
+
|qemu_system| --drive file=nbd:192.0.2.1:30000
82
+
83
+
Example for Unix Domain Sockets
84
+
85
+
.. parsed-literal::
86
+
87
+
|qemu_system| --drive file=nbd:unix:/tmp/nbd-socket
88
+
89
+
``SSH``
90
+
QEMU supports SSH (Secure Shell) access to remote disks.
91
+
92
+
Examples:
93
+
94
+
.. parsed-literal::
95
+
96
+
|qemu_system| -drive file=ssh://user@host/path/to/disk.img
97
+
|qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
98
+
99
+
Currently authentication must be done using ssh-agent. Other
100
+
authentication methods may be supported in future.
101
+
102
+
``Sheepdog``
103
+
Sheepdog is a distributed storage system for QEMU. QEMU supports
104
+
using either local sheepdog devices or remote networked devices.
105
+
106
+
Syntax for specifying a sheepdog device
107
+
108
+
::
109
+
110
+
sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
111
+
112
+
Example
113
+
114
+
.. parsed-literal::
115
+
116
+
|qemu_system| --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
117
+
118
+
See also https://sheepdog.github.io/sheepdog/.
119
+
120
+
``GlusterFS``
121
+
GlusterFS is a user space distributed file system. QEMU supports the
122
+
use of GlusterFS volumes for hosting VM disk images using TCP, Unix
123
+
Domain Sockets and RDMA transport protocols.
124
+
125
+
Syntax for specifying a VM disk image on GlusterFS volume is
126
+
127
+
.. parsed-literal::
128
+
129
+
URI:
130
+
gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
131
+
132
+
JSON:
133
+
'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
134
+
"server":[{"type":"tcp","host":"...","port":"..."},
135
+
{"type":"unix","socket":"..."}]}}'
136
+
137
+
Example
138
+
139
+
.. parsed-literal::
140
+
141
+
URI:
142
+
|qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img,
143
+
file.debug=9,file.logfile=/var/log/qemu-gluster.log
144
+
145
+
JSON:
146
+
|qemu_system| 'json:{"driver":"qcow2",
147
+
"file":{"driver":"gluster",
148
+
"volume":"testvol","path":"a.img",
149
+
"debug":9,"logfile":"/var/log/qemu-gluster.log",
150
+
"server":[{"type":"tcp","host":"1.2.3.4","port":24007},
151
+
{"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
152
+
|qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
153
+
file.debug=9,file.logfile=/var/log/qemu-gluster.log,
154
+
file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
155
+
file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
156
+
157
+
See also http://www.gluster.org.
158
+
159
+
``HTTP/HTTPS/FTP/FTPS``
160
+
QEMU supports read-only access to files accessed over http(s) and
161
+
ftp(s).
162
+
163
+
Syntax using a single filename:
164
+
165
+
::
166
+
167
+
<protocol>://[<username>[:<password>]@]<host>/<path>
168
+
169
+
where:
170
+
171
+
``protocol``
172
+
'http', 'https', 'ftp', or 'ftps'.
173
+
174
+
``username``
175
+
Optional username for authentication to the remote server.
176
+
177
+
``password``
178
+
Optional password for authentication to the remote server.
179
+
180
+
``host``
181
+
Address of the remote server.
182
+
183
+
``path``
184
+
Path on the remote server, including any query string.
185
+
186
+
The following options are also supported:
187
+
188
+
``url``
189
+
The full URL when passing options to the driver explicitly.
190
+
191
+
``readahead``
192
+
The amount of data to read ahead with each range request to the
193
+
remote server. This value may optionally have the suffix 'T', 'G',
194
+
'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be
195
+
assumed to be in bytes. The value must be a multiple of 512 bytes.
196
+
It defaults to 256k.
197
+
198
+
``sslverify``
199
+
Whether to verify the remote server's certificate when connecting
200
+
over SSL. It can have the value 'on' or 'off'. It defaults to
201
+
'on'.
202
+
203
+
``cookie``
204
+
Send this cookie (it can also be a list of cookies separated by
205
+
';') with each outgoing request. Only supported when using
206
+
protocols such as HTTP which support cookies, otherwise ignored.
207
+
208
+
``timeout``
209
+
Set the timeout in seconds of the CURL connection. This timeout is
210
+
the time that CURL waits for a response from the remote server to
211
+
get the size of the image to be downloaded. If not set, the
212
+
default timeout of 5 seconds is used.
213
+
214
+
Note that when passing options to qemu explicitly, ``driver`` is the
215
+
value of <protocol>.
216
+
217
+
Example: boot from a remote Fedora 20 live ISO image
218
+
219
+
.. parsed-literal::
220
+
221
+
|qemu_system_x86| --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
222
+
223
+
|qemu_system_x86| --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
224
+
225
+
Example: boot from a remote Fedora 20 cloud image using a local
226
+
overlay for writes, copy-on-read, and a readahead of 64k
227
+
228
+
.. parsed-literal::
229
+
230
+
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
231
+
232
+
|qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
233
+
234
+
Example: boot from an image stored on a VMware vSphere server with a
235
+
self-signed certificate using a local overlay for writes, a readahead
236
+
of 64k and a timeout of 10 seconds.
237
+
238
+
.. parsed-literal::
239
+
240
+
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:password@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2
241
+
242
+
|qemu_system_x86| -drive file=/tmp/test.qcow2
+64
docs/system/ivshmem.rst
+64
docs/system/ivshmem.rst
···
1
+
.. _pcsys_005fivshmem:
2
+
3
+
Inter-VM Shared Memory device
4
+
-----------------------------
5
+
6
+
On Linux hosts, a shared memory device is available. The basic syntax
7
+
is:
8
+
9
+
.. parsed-literal::
10
+
11
+
|qemu_system_x86| -device ivshmem-plain,memdev=hostmem
12
+
13
+
where hostmem names a host memory backend. For a POSIX shared memory
14
+
backend, use something like
15
+
16
+
::
17
+
18
+
-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=hostmem
19
+
20
+
If desired, interrupts can be sent between guest VMs accessing the same
21
+
shared memory region. Interrupt support requires using a shared memory
22
+
server and using a chardev socket to connect to it. The code for the
23
+
shared memory server is qemu.git/contrib/ivshmem-server. An example
24
+
syntax when using the shared memory server is:
25
+
26
+
.. parsed-literal::
27
+
28
+
# First start the ivshmem server once and for all
29
+
ivshmem-server -p pidfile -S path -m shm-name -l shm-size -n vectors
30
+
31
+
# Then start your qemu instances with matching arguments
32
+
|qemu_system_x86| -device ivshmem-doorbell,vectors=vectors,chardev=id
33
+
-chardev socket,path=path,id=id
34
+
35
+
When using the server, the guest will be assigned a VM ID (>=0) that
36
+
allows guests using the same server to communicate via interrupts.
37
+
Guests can read their VM ID from a device register (see
38
+
ivshmem-spec.txt).
39
+
40
+
Migration with ivshmem
41
+
~~~~~~~~~~~~~~~~~~~~~~
42
+
43
+
With device property ``master=on``, the guest will copy the shared
44
+
memory on migration to the destination host. With ``master=off``, the
45
+
guest will not be able to migrate with the device attached. In the
46
+
latter case, the device should be detached and then reattached after
47
+
migration using the PCI hotplug support.
48
+
49
+
At most one of the devices sharing the same memory can be master. The
50
+
master must complete migration before you plug back the other devices.
51
+
52
+
ivshmem and hugepages
53
+
~~~~~~~~~~~~~~~~~~~~~
54
+
55
+
Instead of specifying the <shm size> using POSIX shm, you may specify a
56
+
memory backend that has hugepage support:
57
+
58
+
.. parsed-literal::
59
+
60
+
|qemu_system_x86| -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
61
+
-device ivshmem-plain,memdev=mb1
62
+
63
+
ivshmem-server also supports hugepages mount points with the ``-m``
64
+
memory path argument.
+40
docs/system/keys.rst
+40
docs/system/keys.rst
···
1
+
.. _pcsys_005fkeys:
2
+
3
+
Keys in the graphical frontends
4
+
-------------------------------
5
+
6
+
During the graphical emulation, you can use special key combinations to
7
+
change modes. The default key mappings are shown below, but if you use
8
+
``-alt-grab`` then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt)
9
+
and if you use ``-ctrl-grab`` then the modifier is the right Ctrl key
10
+
(instead of Ctrl-Alt):
11
+
12
+
Ctrl-Alt-f
13
+
Toggle full screen
14
+
15
+
Ctrl-Alt-+
16
+
Enlarge the screen
17
+
18
+
Ctrl-Alt\--
19
+
Shrink the screen
20
+
21
+
Ctrl-Alt-u
22
+
Restore the screen's un-scaled dimensions
23
+
24
+
Ctrl-Alt-n
25
+
Switch to virtual console 'n'. Standard console mappings are:
26
+
27
+
*1*
28
+
Target system display
29
+
30
+
*2*
31
+
Monitor
32
+
33
+
*3*
34
+
Serial port
35
+
36
+
Ctrl-Alt
37
+
Toggle mouse and keyboard grab.
38
+
39
+
In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp and
40
+
Ctrl-PageDown to move in the back log.
+11
docs/system/license.rst
+11
docs/system/license.rst
···
1
+
.. _License:
2
+
3
+
License
4
+
=======
5
+
6
+
QEMU is a trademark of Fabrice Bellard.
7
+
8
+
QEMU is released under the `GNU General Public
9
+
License <https://www.gnu.org/licenses/gpl-2.0.txt>`__, version 2. Parts
10
+
of QEMU have specific licenses, see file
11
+
`LICENSE <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE>`__.
+30
docs/system/linuxboot.rst
+30
docs/system/linuxboot.rst
···
1
+
.. _direct_005flinux_005fboot:
2
+
3
+
Direct Linux Boot
4
+
-----------------
5
+
6
+
This section explains how to launch a Linux kernel inside QEMU without
7
+
having to make a full bootable image. It is very useful for fast Linux
8
+
kernel testing.
9
+
10
+
The syntax is:
11
+
12
+
.. parsed-literal::
13
+
14
+
|qemu_system| -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
15
+
16
+
Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
17
+
give the kernel command line arguments. The ``-initrd`` option can be
18
+
used to provide an INITRD image.
19
+
20
+
If you do not need graphical output, you can disable it and redirect the
21
+
virtual serial port and the QEMU monitor to the console with the
22
+
``-nographic`` option. The typical command line is:
23
+
24
+
.. parsed-literal::
25
+
26
+
|qemu_system| -kernel bzImage -hda rootdisk.img \
27
+
-append "root=/dev/hda console=ttyS0" -nographic
28
+
29
+
Use Ctrl-a c to switch between the serial console and the monitor (see
30
+
:ref:`pcsys_005fkeys`).
+25
docs/system/monitor.rst
+25
docs/system/monitor.rst
···
1
+
.. _pcsys_005fmonitor:
2
+
3
+
QEMU Monitor
4
+
------------
5
+
6
+
The QEMU monitor is used to give complex commands to the QEMU emulator.
7
+
You can use it to:
8
+
9
+
- Remove or insert removable media images (such as CD-ROM or
10
+
floppies).
11
+
12
+
- Freeze/unfreeze the Virtual Machine (VM) and save or restore its
13
+
state from a disk file.
14
+
15
+
- Inspect the VM state without an external debugger.
16
+
17
+
..
18
+
The commands section goes here once it's converted from Texinfo to RST.
19
+
20
+
Integer expressions
21
+
~~~~~~~~~~~~~~~~~~~
22
+
23
+
The monitor understands integers expressions for every integer argument.
24
+
You can use register names to get the value of specifics CPU registers
25
+
by prefixing them with *$*.
+32
docs/system/mux-chardev.rst
+32
docs/system/mux-chardev.rst
···
1
+
.. _mux_005fkeys:
2
+
3
+
Keys in the character backend multiplexer
4
+
-----------------------------------------
5
+
6
+
During emulation, if you are using a character backend multiplexer
7
+
(which is the default if you are using ``-nographic``) then several
8
+
commands are available via an escape sequence. These key sequences all
9
+
start with an escape character, which is Ctrl-a by default, but can be
10
+
changed with ``-echr``. The list below assumes you're using the default.
11
+
12
+
Ctrl-a h
13
+
Print this help
14
+
15
+
Ctrl-a x
16
+
Exit emulator
17
+
18
+
Ctrl-a s
19
+
Save disk data back to file (if -snapshot)
20
+
21
+
Ctrl-a t
22
+
Toggle console timestamps
23
+
24
+
Ctrl-a b
25
+
Send break (magic sysrq in Linux)
26
+
27
+
Ctrl-a c
28
+
Rotate between the frontends connected to the multiplexer (usually
29
+
this switches between the monitor and the console)
30
+
31
+
Ctrl-a Ctrl-a
32
+
Send the escape character to the frontend
+100
docs/system/net.rst
+100
docs/system/net.rst
···
1
+
.. _pcsys_005fnetwork:
2
+
3
+
Network emulation
4
+
-----------------
5
+
6
+
QEMU can simulate several network cards (e.g. PCI or ISA cards on the PC
7
+
target) and can connect them to a network backend on the host or an
8
+
emulated hub. The various host network backends can either be used to
9
+
connect the NIC of the guest to a real network (e.g. by using a TAP
10
+
devices or the non-privileged user mode network stack), or to other
11
+
guest instances running in another QEMU process (e.g. by using the
12
+
socket host network backend).
13
+
14
+
Using TAP network interfaces
15
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16
+
17
+
This is the standard way to connect QEMU to a real network. QEMU adds a
18
+
virtual network device on your host (called ``tapN``), and you can then
19
+
configure it as if it was a real ethernet card.
20
+
21
+
Linux host
22
+
^^^^^^^^^^
23
+
24
+
As an example, you can download the ``linux-test-xxx.tar.gz`` archive
25
+
and copy the script ``qemu-ifup`` in ``/etc`` and configure properly
26
+
``sudo`` so that the command ``ifconfig`` contained in ``qemu-ifup`` can
27
+
be executed as root. You must verify that your host kernel supports the
28
+
TAP network interfaces: the device ``/dev/net/tun`` must be present.
29
+
30
+
See :ref:`sec_005finvocation` to have examples of command
31
+
lines using the TAP network interfaces.
32
+
33
+
Windows host
34
+
^^^^^^^^^^^^
35
+
36
+
There is a virtual ethernet driver for Windows 2000/XP systems, called
37
+
TAP-Win32. But it is not included in standard QEMU for Windows, so you
38
+
will need to get it separately. It is part of OpenVPN package, so
39
+
download OpenVPN from : https://openvpn.net/.
40
+
41
+
Using the user mode network stack
42
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43
+
44
+
By using the option ``-net user`` (default configuration if no ``-net``
45
+
option is specified), QEMU uses a completely user mode network stack
46
+
(you don't need root privilege to use the virtual network). The virtual
47
+
network configuration is the following::
48
+
49
+
guest (10.0.2.15) <------> Firewall/DHCP server <-----> Internet
50
+
| (10.0.2.2)
51
+
|
52
+
----> DNS server (10.0.2.3)
53
+
|
54
+
----> SMB server (10.0.2.4)
55
+
56
+
The QEMU VM behaves as if it was behind a firewall which blocks all
57
+
incoming connections. You can use a DHCP client to automatically
58
+
configure the network in the QEMU VM. The DHCP server assign addresses
59
+
to the hosts starting from 10.0.2.15.
60
+
61
+
In order to check that the user mode network is working, you can ping
62
+
the address 10.0.2.2 and verify that you got an address in the range
63
+
10.0.2.x from the QEMU virtual DHCP server.
64
+
65
+
Note that ICMP traffic in general does not work with user mode
66
+
networking. ``ping``, aka. ICMP echo, to the local router (10.0.2.2)
67
+
shall work, however. If you're using QEMU on Linux >= 3.0, it can use
68
+
unprivileged ICMP ping sockets to allow ``ping`` to the Internet. The
69
+
host admin has to set the ping_group_range in order to grant access to
70
+
those sockets. To allow ping for GID 100 (usually users group)::
71
+
72
+
echo 100 100 > /proc/sys/net/ipv4/ping_group_range
73
+
74
+
When using the built-in TFTP server, the router is also the TFTP server.
75
+
76
+
When using the ``'-netdev user,hostfwd=...'`` option, TCP or UDP
77
+
connections can be redirected from the host to the guest. It allows for
78
+
example to redirect X11, telnet or SSH connections.
79
+
80
+
Hubs
81
+
~~~~
82
+
83
+
QEMU can simulate several hubs. A hub can be thought of as a virtual
84
+
connection between several network devices. These devices can be for
85
+
example QEMU virtual ethernet cards or virtual Host ethernet devices
86
+
(TAP devices). You can connect guest NICs or host network backends to
87
+
such a hub using the ``-netdev
88
+
hubport`` or ``-nic hubport`` options. The legacy ``-net`` option also
89
+
connects the given device to the emulated hub with ID 0 (i.e. the
90
+
default hub) unless you specify a netdev with ``-net nic,netdev=xxx``
91
+
here.
92
+
93
+
Connecting emulated networks between QEMU instances
94
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95
+
96
+
Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``)
97
+
option, it is possible to create emulated networks that span several
98
+
QEMU instances. See the description of the ``-netdev socket`` option in
99
+
:ref:`sec_005finvocation` to have a basic
100
+
example.
+13
docs/system/quickstart.rst
+13
docs/system/quickstart.rst
+227
docs/system/target-arm.rst
+227
docs/system/target-arm.rst
···
1
+
.. _ARM-System-emulator:
2
+
3
+
ARM System emulator
4
+
-------------------
5
+
6
+
Use the executable ``qemu-system-arm`` to simulate a ARM machine. The
7
+
ARM Integrator/CP board is emulated with the following devices:
8
+
9
+
- ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
10
+
11
+
- Two PL011 UARTs
12
+
13
+
- SMC 91c111 Ethernet adapter
14
+
15
+
- PL110 LCD controller
16
+
17
+
- PL050 KMI with PS/2 keyboard and mouse.
18
+
19
+
- PL181 MultiMedia Card Interface with SD card.
20
+
21
+
The ARM Versatile baseboard is emulated with the following devices:
22
+
23
+
- ARM926E, ARM1136 or Cortex-A8 CPU
24
+
25
+
- PL190 Vectored Interrupt Controller
26
+
27
+
- Four PL011 UARTs
28
+
29
+
- SMC 91c111 Ethernet adapter
30
+
31
+
- PL110 LCD controller
32
+
33
+
- PL050 KMI with PS/2 keyboard and mouse.
34
+
35
+
- PCI host bridge. Note the emulated PCI bridge only provides access
36
+
to PCI memory space. It does not provide access to PCI IO space. This
37
+
means some devices (eg. ne2k_pci NIC) are not usable, and others (eg.
38
+
rtl8139 NIC) are only usable when the guest drivers use the memory
39
+
mapped control registers.
40
+
41
+
- PCI OHCI USB controller.
42
+
43
+
- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
44
+
devices.
45
+
46
+
- PL181 MultiMedia Card Interface with SD card.
47
+
48
+
Several variants of the ARM RealView baseboard are emulated, including
49
+
the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only
50
+
certain Linux kernel configurations work out of the box on these boards.
51
+
52
+
Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
53
+
enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
54
+
should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
55
+
disabled and expect 1024M RAM.
56
+
57
+
The following devices are emulated:
58
+
59
+
- ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
60
+
61
+
- ARM AMBA Generic/Distributed Interrupt Controller
62
+
63
+
- Four PL011 UARTs
64
+
65
+
- SMC 91c111 or SMSC LAN9118 Ethernet adapter
66
+
67
+
- PL110 LCD controller
68
+
69
+
- PL050 KMI with PS/2 keyboard and mouse
70
+
71
+
- PCI host bridge
72
+
73
+
- PCI OHCI USB controller
74
+
75
+
- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
76
+
devices
77
+
78
+
- PL181 MultiMedia Card Interface with SD card.
79
+
80
+
The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\"
81
+
and \"Terrier\") emulation includes the following peripherals:
82
+
83
+
- Intel PXA270 System-on-chip (ARM V5TE core)
84
+
85
+
- NAND Flash memory
86
+
87
+
- IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\"
88
+
89
+
- On-chip OHCI USB controller
90
+
91
+
- On-chip LCD controller
92
+
93
+
- On-chip Real Time Clock
94
+
95
+
- TI ADS7846 touchscreen controller on SSP bus
96
+
97
+
- Maxim MAX1111 analog-digital converter on |I2C| bus
98
+
99
+
- GPIO-connected keyboard controller and LEDs
100
+
101
+
- Secure Digital card connected to PXA MMC/SD host
102
+
103
+
- Three on-chip UARTs
104
+
105
+
- WM8750 audio CODEC on |I2C| and |I2S| busses
106
+
107
+
The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the
108
+
following elements:
109
+
110
+
- Texas Instruments OMAP310 System-on-chip (ARM 925T core)
111
+
112
+
- ROM and RAM memories (ROM firmware image can be loaded with
113
+
-option-rom)
114
+
115
+
- On-chip LCD controller
116
+
117
+
- On-chip Real Time Clock
118
+
119
+
- TI TSC2102i touchscreen controller / analog-digital converter /
120
+
Audio CODEC, connected through MicroWire and |I2S| busses
121
+
122
+
- GPIO-connected matrix keypad
123
+
124
+
- Secure Digital card connected to OMAP MMC/SD host
125
+
126
+
- Three on-chip UARTs
127
+
128
+
Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 /
129
+
48) emulation supports the following elements:
130
+
131
+
- Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
132
+
133
+
- RAM and non-volatile OneNAND Flash memories
134
+
135
+
- Display connected to EPSON remote framebuffer chip and OMAP on-chip
136
+
display controller and a LS041y3 MIPI DBI-C controller
137
+
138
+
- TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen
139
+
controllers driven through SPI bus
140
+
141
+
- National Semiconductor LM8323-controlled qwerty keyboard driven
142
+
through |I2C| bus
143
+
144
+
- Secure Digital card connected to OMAP MMC/SD host
145
+
146
+
- Three OMAP on-chip UARTs and on-chip STI debugging console
147
+
148
+
- Mentor Graphics \"Inventra\" dual-role USB controller embedded in a
149
+
TI TUSB6010 chip - only USB host mode is supported
150
+
151
+
- TI TMP105 temperature sensor driven through |I2C| bus
152
+
153
+
- TI TWL92230C power management companion with an RTC on
154
+
|I2C| bus
155
+
156
+
- Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
157
+
through CBUS
158
+
159
+
The Luminary Micro Stellaris LM3S811EVB emulation includes the following
160
+
devices:
161
+
162
+
- Cortex-M3 CPU core.
163
+
164
+
- 64k Flash and 8k SRAM.
165
+
166
+
- Timers, UARTs, ADC and |I2C| interface.
167
+
168
+
- OSRAM Pictiva 96x16 OLED with SSD0303 controller on
169
+
|I2C| bus.
170
+
171
+
The Luminary Micro Stellaris LM3S6965EVB emulation includes the
172
+
following devices:
173
+
174
+
- Cortex-M3 CPU core.
175
+
176
+
- 256k Flash and 64k SRAM.
177
+
178
+
- Timers, UARTs, ADC, |I2C| and SSI interfaces.
179
+
180
+
- OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via
181
+
SSI.
182
+
183
+
The Freecom MusicPal internet radio emulation includes the following
184
+
elements:
185
+
186
+
- Marvell MV88W8618 ARM core.
187
+
188
+
- 32 MB RAM, 256 KB SRAM, 8 MB flash.
189
+
190
+
- Up to 2 16550 UARTs
191
+
192
+
- MV88W8xx8 Ethernet controller
193
+
194
+
- MV88W8618 audio controller, WM8750 CODEC and mixer
195
+
196
+
- 128x64 display with brightness control
197
+
198
+
- 2 buttons, 2 navigation wheels with button function
199
+
200
+
The Siemens SX1 models v1 and v2 (default) basic emulation. The
201
+
emulation includes the following elements:
202
+
203
+
- Texas Instruments OMAP310 System-on-chip (ARM 925T core)
204
+
205
+
- ROM and RAM memories (ROM firmware image can be loaded with
206
+
-pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB
207
+
208
+
- On-chip LCD controller
209
+
210
+
- On-chip Real Time Clock
211
+
212
+
- Secure Digital card connected to OMAP MMC/SD host
213
+
214
+
- Three on-chip UARTs
215
+
216
+
A Linux 2.6 test image is available on the QEMU web site. More
217
+
information is available in the QEMU mailing-list archive.
218
+
219
+
The following options are specific to the ARM emulation:
220
+
221
+
``-semihosting``
222
+
Enable semihosting syscall emulation.
223
+
224
+
On ARM this implements the \"Angel\" interface.
225
+
226
+
Note that this allows guest direct access to the host filesystem, so
227
+
should only be used with trusted guest OS.
+84
docs/system/target-i386.rst
+84
docs/system/target-i386.rst
···
1
+
.. _QEMU-PC-System-emulator:
2
+
3
+
x86 (PC) System emulator
4
+
------------------------
5
+
6
+
.. _pcsys_005fdevices:
7
+
8
+
Peripherals
9
+
~~~~~~~~~~~
10
+
11
+
The QEMU PC System emulator simulates the following peripherals:
12
+
13
+
- i440FX host PCI bridge and PIIX3 PCI to ISA bridge
14
+
15
+
- Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
16
+
extensions (hardware level, including all non standard modes).
17
+
18
+
- PS/2 mouse and keyboard
19
+
20
+
- 2 PCI IDE interfaces with hard disk and CD-ROM support
21
+
22
+
- Floppy disk
23
+
24
+
- PCI and ISA network adapters
25
+
26
+
- Serial ports
27
+
28
+
- IPMI BMC, either and internal or external one
29
+
30
+
- Creative SoundBlaster 16 sound card
31
+
32
+
- ENSONIQ AudioPCI ES1370 sound card
33
+
34
+
- Intel 82801AA AC97 Audio compatible sound card
35
+
36
+
- Intel HD Audio Controller and HDA codec
37
+
38
+
- Adlib (OPL2) - Yamaha YM3812 compatible chip
39
+
40
+
- Gravis Ultrasound GF1 sound card
41
+
42
+
- CS4231A compatible sound card
43
+
44
+
- PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1
45
+
hub.
46
+
47
+
SMP is supported with up to 255 CPUs.
48
+
49
+
QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
50
+
VGA BIOS.
51
+
52
+
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
53
+
54
+
QEMU uses GUS emulation (GUSEMU32 http://www.deinmeister.de/gusemu/) by
55
+
Tibor \"TS\" Schütz.
56
+
57
+
Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU
58
+
must be told to not have parallel ports to have working GUS.
59
+
60
+
.. parsed-literal::
61
+
62
+
|qemu_system_x86| dos.img -soundhw gus -parallel none
63
+
64
+
Alternatively:
65
+
66
+
.. parsed-literal::
67
+
68
+
|qemu_system_x86| dos.img -device gus,irq=5
69
+
70
+
Or some other unclaimed IRQ.
71
+
72
+
CS4231A is the chip used in Windows Sound System and GUSMAX products
73
+
74
+
.. include:: cpu-models-x86.rst.inc
75
+
76
+
.. _pcsys_005freq:
77
+
78
+
OS requirements
79
+
~~~~~~~~~~~~~~~
80
+
81
+
On x86_64 hosts, the default set of CPU features enabled by the KVM
82
+
accelerator require the host to be running Linux v4.5 or newer. Red Hat
83
+
Enterprise Linux 7 is also supported, since the required
84
+
functionality was backported.
+32
docs/system/target-m68k.rst
+32
docs/system/target-m68k.rst
···
1
+
.. _ColdFire-System-emulator:
2
+
3
+
ColdFire System emulator
4
+
------------------------
5
+
6
+
Use the executable ``qemu-system-m68k`` to simulate a ColdFire machine.
7
+
The emulator is able to boot a uClinux kernel.
8
+
9
+
The M5208EVB emulation includes the following devices:
10
+
11
+
- MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
12
+
13
+
- Three Two on-chip UARTs.
14
+
15
+
- Fast Ethernet Controller (FEC)
16
+
17
+
The AN5206 emulation includes the following devices:
18
+
19
+
- MCF5206 ColdFire V2 Microprocessor.
20
+
21
+
- Two on-chip UARTs.
22
+
23
+
The following options are specific to the ColdFire emulation:
24
+
25
+
``-semihosting``
26
+
Enable semihosting syscall emulation.
27
+
28
+
On M68K this implements the \"ColdFire GDB\" interface used by
29
+
libgloss.
30
+
31
+
Note that this allows guest direct access to the host filesystem, so
32
+
should only be used with trusted guest OS.
+120
docs/system/target-mips.rst
+120
docs/system/target-mips.rst
···
1
+
.. _MIPS-System-emulator:
2
+
3
+
MIPS System emulator
4
+
--------------------
5
+
6
+
Four executables cover simulation of 32 and 64-bit MIPS systems in both
7
+
endian options, ``qemu-system-mips``, ``qemu-system-mipsel``
8
+
``qemu-system-mips64`` and ``qemu-system-mips64el``. Five different
9
+
machine types are emulated:
10
+
11
+
- A generic ISA PC-like machine \"mips\"
12
+
13
+
- The MIPS Malta prototype board \"malta\"
14
+
15
+
- An ACER Pica \"pica61\". This machine needs the 64-bit emulator.
16
+
17
+
- MIPS emulator pseudo board \"mipssim\"
18
+
19
+
- A MIPS Magnum R4000 machine \"magnum\". This machine needs the
20
+
64-bit emulator.
21
+
22
+
The generic emulation is supported by Debian 'Etch' and is able to
23
+
install Debian into a virtual disk image. The following devices are
24
+
emulated:
25
+
26
+
- A range of MIPS CPUs, default is the 24Kf
27
+
28
+
- PC style serial port
29
+
30
+
- PC style IDE disk
31
+
32
+
- NE2000 network card
33
+
34
+
The Malta emulation supports the following devices:
35
+
36
+
- Core board with MIPS 24Kf CPU and Galileo system controller
37
+
38
+
- PIIX4 PCI/USB/SMbus controller
39
+
40
+
- The Multi-I/O chip's serial device
41
+
42
+
- PCI network cards (PCnet32 and others)
43
+
44
+
- Malta FPGA serial device
45
+
46
+
- Cirrus (default) or any other PCI VGA graphics card
47
+
48
+
The Boston board emulation supports the following devices:
49
+
50
+
- Xilinx FPGA, which includes a PCIe root port and an UART
51
+
52
+
- Intel EG20T PCH connects the I/O peripherals, but only the SATA bus
53
+
is emulated
54
+
55
+
The ACER Pica emulation supports:
56
+
57
+
- MIPS R4000 CPU
58
+
59
+
- PC-style IRQ and DMA controllers
60
+
61
+
- PC Keyboard
62
+
63
+
- IDE controller
64
+
65
+
The MIPS Magnum R4000 emulation supports:
66
+
67
+
- MIPS R4000 CPU
68
+
69
+
- PC-style IRQ controller
70
+
71
+
- PC Keyboard
72
+
73
+
- SCSI controller
74
+
75
+
- G364 framebuffer
76
+
77
+
The Fulong 2E emulation supports:
78
+
79
+
- Loongson 2E CPU
80
+
81
+
- Bonito64 system controller as North Bridge
82
+
83
+
- VT82C686 chipset as South Bridge
84
+
85
+
- RTL8139D as a network card chipset
86
+
87
+
The mipssim pseudo board emulation provides an environment similar to
88
+
what the proprietary MIPS emulator uses for running Linux. It supports:
89
+
90
+
- A range of MIPS CPUs, default is the 24Kf
91
+
92
+
- PC style serial port
93
+
94
+
- MIPSnet network emulation
95
+
96
+
.. include:: cpu-models-mips.rst.inc
97
+
98
+
.. _nanoMIPS-System-emulator:
99
+
100
+
nanoMIPS System emulator
101
+
~~~~~~~~~~~~~~~~~~~~~~~~
102
+
103
+
Executable ``qemu-system-mipsel`` also covers simulation of 32-bit
104
+
nanoMIPS system in little endian mode:
105
+
106
+
- nanoMIPS I7200 CPU
107
+
108
+
Example of ``qemu-system-mipsel`` usage for nanoMIPS is shown below:
109
+
110
+
Download ``<disk_image_file>`` from
111
+
https://mipsdistros.mips.com/LinuxDistro/nanomips/buildroot/index.html.
112
+
113
+
Download ``<kernel_image_file>`` from
114
+
https://mipsdistros.mips.com/LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/index.html.
115
+
116
+
Start system emulation of Malta board with nanoMIPS I7200 CPU::
117
+
118
+
qemu-system-mipsel -cpu I7200 -kernel <kernel_image_file> \
119
+
-M malta -serial stdio -m <memory_size> -hda <disk_image_file> \
120
+
-append "mem=256m@0x0 rw console=ttyS0 vga=cirrus vesa=0x111 root=/dev/sda"
+61
docs/system/target-ppc.rst
+61
docs/system/target-ppc.rst
···
1
+
.. _PowerPC-System-emulator:
2
+
3
+
PowerPC System emulator
4
+
-----------------------
5
+
6
+
Use the executable ``qemu-system-ppc`` to simulate a complete 40P (PREP)
7
+
or PowerMac PowerPC system.
8
+
9
+
QEMU emulates the following PowerMac peripherals:
10
+
11
+
- UniNorth or Grackle PCI Bridge
12
+
13
+
- PCI VGA compatible card with VESA Bochs Extensions
14
+
15
+
- 2 PMAC IDE interfaces with hard disk and CD-ROM support
16
+
17
+
- NE2000 PCI adapters
18
+
19
+
- Non Volatile RAM
20
+
21
+
- VIA-CUDA with ADB keyboard and mouse.
22
+
23
+
QEMU emulates the following 40P (PREP) peripherals:
24
+
25
+
- PCI Bridge
26
+
27
+
- PCI VGA compatible card with VESA Bochs Extensions
28
+
29
+
- 2 IDE interfaces with hard disk and CD-ROM support
30
+
31
+
- Floppy disk
32
+
33
+
- PCnet network adapters
34
+
35
+
- Serial port
36
+
37
+
- PREP Non Volatile RAM
38
+
39
+
- PC compatible keyboard and mouse.
40
+
41
+
Since version 0.9.1, QEMU uses OpenBIOS https://www.openbios.org/ for
42
+
the g3beige and mac99 PowerMac and the 40p machines. OpenBIOS is a free
43
+
(GPL v2) portable firmware implementation. The goal is to implement a
44
+
100% IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
45
+
46
+
The following options are specific to the PowerPC emulation:
47
+
48
+
``-g WxH[xDEPTH]``
49
+
Set the initial VGA graphic mode. The default is 800x600x32.
50
+
51
+
``-prom-env string``
52
+
Set OpenBIOS variables in NVRAM, for example:
53
+
54
+
::
55
+
56
+
qemu-system-ppc -prom-env 'auto-boot?=false' \
57
+
-prom-env 'boot-device=hd:2,\yaboot' \
58
+
-prom-env 'boot-args=conf=hd:2,\yaboot.conf'
59
+
60
+
More information is available at
61
+
http://perso.magic.fr/l_indien/qemu-ppc/.
+81
docs/system/target-sparc.rst
+81
docs/system/target-sparc.rst
···
1
+
.. _Sparc32-System-emulator:
2
+
3
+
Sparc32 System emulator
4
+
-----------------------
5
+
6
+
Use the executable ``qemu-system-sparc`` to simulate the following Sun4m
7
+
architecture machines:
8
+
9
+
- SPARCstation 4
10
+
11
+
- SPARCstation 5
12
+
13
+
- SPARCstation 10
14
+
15
+
- SPARCstation 20
16
+
17
+
- SPARCserver 600MP
18
+
19
+
- SPARCstation LX
20
+
21
+
- SPARCstation Voyager
22
+
23
+
- SPARCclassic
24
+
25
+
- SPARCbook
26
+
27
+
The emulation is somewhat complete. SMP up to 16 CPUs is supported, but
28
+
Linux limits the number of usable CPUs to 4.
29
+
30
+
QEMU emulates the following sun4m peripherals:
31
+
32
+
- IOMMU
33
+
34
+
- TCX or cgthree Frame buffer
35
+
36
+
- Lance (Am7990) Ethernet
37
+
38
+
- Non Volatile RAM M48T02/M48T08
39
+
40
+
- Slave I/O: timers, interrupt controllers, Zilog serial ports,
41
+
keyboard and power/reset logic
42
+
43
+
- ESP SCSI controller with hard disk and CD-ROM support
44
+
45
+
- Floppy drive (not on SS-600MP)
46
+
47
+
- CS4231 sound device (only on SS-5, not working yet)
48
+
49
+
The number of peripherals is fixed in the architecture. Maximum memory
50
+
size depends on the machine type, for SS-5 it is 256MB and for others
51
+
2047MB.
52
+
53
+
Since version 0.8.2, QEMU uses OpenBIOS https://www.openbios.org/.
54
+
OpenBIOS is a free (GPL v2) portable firmware implementation. The goal
55
+
is to implement a 100% IEEE 1275-1994 (referred to as Open Firmware)
56
+
compliant firmware.
57
+
58
+
A sample Linux 2.6 series kernel and ram disk image are available on the
59
+
QEMU web site. There are still issues with NetBSD and OpenBSD, but most
60
+
kernel versions work. Please note that currently older Solaris kernels
61
+
don't work probably due to interface issues between OpenBIOS and
62
+
Solaris.
63
+
64
+
The following options are specific to the Sparc32 emulation:
65
+
66
+
``-g WxHx[xDEPTH]``
67
+
Set the initial graphics mode. For TCX, the default is 1024x768x8
68
+
with the option of 1024x768x24. For cgthree, the default is
69
+
1024x768x8 with the option of 1152x900x8 for people who wish to use
70
+
OBP.
71
+
72
+
``-prom-env string``
73
+
Set OpenBIOS variables in NVRAM, for example:
74
+
75
+
::
76
+
77
+
qemu-system-sparc -prom-env 'auto-boot?=false' \
78
+
-prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
79
+
80
+
``-M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]``
81
+
Set the emulated machine type. Default is SS-5.
+49
docs/system/target-sparc64.rst
+49
docs/system/target-sparc64.rst
···
1
+
.. _Sparc64-System-emulator:
2
+
3
+
Sparc64 System emulator
4
+
-----------------------
5
+
6
+
Use the executable ``qemu-system-sparc64`` to simulate a Sun4u
7
+
(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
8
+
Niagara (T1) machine. The Sun4u emulator is mostly complete, being able
9
+
to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
10
+
Sun4v emulator is still a work in progress.
11
+
12
+
The Niagara T1 emulator makes use of firmware and OS binaries supplied
13
+
in the S10image/ directory of the OpenSPARC T1 project
14
+
http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2
15
+
and is able to boot the disk.s10hw2 Solaris image.
16
+
17
+
::
18
+
19
+
qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
20
+
-nographic -m 256 \
21
+
-drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
22
+
23
+
QEMU emulates the following peripherals:
24
+
25
+
- UltraSparc IIi APB PCI Bridge
26
+
27
+
- PCI VGA compatible card with VESA Bochs Extensions
28
+
29
+
- PS/2 mouse and keyboard
30
+
31
+
- Non Volatile RAM M48T59
32
+
33
+
- PC-compatible serial ports
34
+
35
+
- 2 PCI IDE interfaces with hard disk and CD-ROM support
36
+
37
+
- Floppy disk
38
+
39
+
The following options are specific to the Sparc64 emulation:
40
+
41
+
``-prom-env string``
42
+
Set OpenBIOS variables in NVRAM, for example:
43
+
44
+
::
45
+
46
+
qemu-system-sparc64 -prom-env 'auto-boot?=false'
47
+
48
+
``-M [sun4u|sun4v|niagara]``
49
+
Set the emulated machine type. The default is sun4u.
+39
docs/system/target-xtensa.rst
+39
docs/system/target-xtensa.rst
···
1
+
.. _Xtensa-System-emulator:
2
+
3
+
Xtensa System emulator
4
+
----------------------
5
+
6
+
Two executables cover simulation of both Xtensa endian options,
7
+
``qemu-system-xtensa`` and ``qemu-system-xtensaeb``. Two different
8
+
machine types are emulated:
9
+
10
+
- Xtensa emulator pseudo board \"sim\"
11
+
12
+
- Avnet LX60/LX110/LX200 board
13
+
14
+
The sim pseudo board emulation provides an environment similar to one
15
+
provided by the proprietary Tensilica ISS. It supports:
16
+
17
+
- A range of Xtensa CPUs, default is the DC232B
18
+
19
+
- Console and filesystem access via semihosting calls
20
+
21
+
The Avnet LX60/LX110/LX200 emulation supports:
22
+
23
+
- A range of Xtensa CPUs, default is the DC232B
24
+
25
+
- 16550 UART
26
+
27
+
- OpenCores 10/100 Mbps Ethernet MAC
28
+
29
+
The following options are specific to the Xtensa emulation:
30
+
31
+
``-semihosting``
32
+
Enable semihosting syscall emulation.
33
+
34
+
Xtensa semihosting provides basic file IO calls, such as
35
+
open/read/write/seek/select. Tensilica baremetal libc for ISS and
36
+
linux platform \"sim\" use this interface.
37
+
38
+
Note that this allows guest direct access to the host filesystem, so
39
+
should only be used with trusted guest OS.
+19
docs/system/targets.rst
+19
docs/system/targets.rst
···
1
+
QEMU System Emulator Targets
2
+
============================
3
+
4
+
QEMU is a generic emulator and it emulates many machines. Most of the
5
+
options are similar for all machines. Specific information about the
6
+
various targets are mentioned in the following sections.
7
+
8
+
Contents:
9
+
10
+
.. toctree::
11
+
12
+
target-i386
13
+
target-ppc
14
+
target-sparc
15
+
target-sparc64
16
+
target-mips
17
+
target-arm
18
+
target-m68k
19
+
target-xtensa
+328
docs/system/tls.rst
+328
docs/system/tls.rst
···
1
+
.. _network_005ftls:
2
+
3
+
TLS setup for network services
4
+
------------------------------
5
+
6
+
Almost all network services in QEMU have the ability to use TLS for
7
+
session data encryption, along with x509 certificates for simple client
8
+
authentication. What follows is a description of how to generate
9
+
certificates suitable for usage with QEMU, and applies to the VNC
10
+
server, character devices with the TCP backend, NBD server and client,
11
+
and migration server and client.
12
+
13
+
At a high level, QEMU requires certificates and private keys to be
14
+
provided in PEM format. Aside from the core fields, the certificates
15
+
should include various extension data sets, including v3 basic
16
+
constraints data, key purpose, key usage and subject alt name.
17
+
18
+
The GnuTLS package includes a command called ``certtool`` which can be
19
+
used to easily generate certificates and keys in the required format
20
+
with expected data present. Alternatively a certificate management
21
+
service may be used.
22
+
23
+
At a minimum it is necessary to setup a certificate authority, and issue
24
+
certificates to each server. If using x509 certificates for
25
+
authentication, then each client will also need to be issued a
26
+
certificate.
27
+
28
+
Assuming that the QEMU network services will only ever be exposed to
29
+
clients on a private intranet, there is no need to use a commercial
30
+
certificate authority to create certificates. A self-signed CA is
31
+
sufficient, and in fact likely to be more secure since it removes the
32
+
ability of malicious 3rd parties to trick the CA into mis-issuing certs
33
+
for impersonating your services. The only likely exception where a
34
+
commercial CA might be desirable is if enabling the VNC websockets
35
+
server and exposing it directly to remote browser clients. In such a
36
+
case it might be useful to use a commercial CA to avoid needing to
37
+
install custom CA certs in the web browsers.
38
+
39
+
The recommendation is for the server to keep its certificates in either
40
+
``/etc/pki/qemu`` or for unprivileged users in ``$HOME/.pki/qemu``.
41
+
42
+
.. _tls_005fgenerate_005fca:
43
+
44
+
Setup the Certificate Authority
45
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46
+
47
+
This step only needs to be performed once per organization /
48
+
organizational unit. First the CA needs a private key. This key must be
49
+
kept VERY secret and secure. If this key is compromised the entire trust
50
+
chain of the certificates issued with it is lost.
51
+
52
+
::
53
+
54
+
# certtool --generate-privkey > ca-key.pem
55
+
56
+
To generate a self-signed certificate requires one core piece of
57
+
information, the name of the organization. A template file ``ca.info``
58
+
should be populated with the desired data to avoid having to deal with
59
+
interactive prompts from certtool::
60
+
61
+
# cat > ca.info <<EOF
62
+
cn = Name of your organization
63
+
ca
64
+
cert_signing_key
65
+
EOF
66
+
# certtool --generate-self-signed \
67
+
--load-privkey ca-key.pem
68
+
--template ca.info \
69
+
--outfile ca-cert.pem
70
+
71
+
The ``ca`` keyword in the template sets the v3 basic constraints
72
+
extension to indicate this certificate is for a CA, while
73
+
``cert_signing_key`` sets the key usage extension to indicate this will
74
+
be used for signing other keys. The generated ``ca-cert.pem`` file
75
+
should be copied to all servers and clients wishing to utilize TLS
76
+
support in the VNC server. The ``ca-key.pem`` must not be
77
+
disclosed/copied anywhere except the host responsible for issuing
78
+
certificates.
79
+
80
+
.. _tls_005fgenerate_005fserver:
81
+
82
+
Issuing server certificates
83
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
84
+
85
+
Each server (or host) needs to be issued with a key and certificate.
86
+
When connecting the certificate is sent to the client which validates it
87
+
against the CA certificate. The core pieces of information for a server
88
+
certificate are the hostnames and/or IP addresses that will be used by
89
+
clients when connecting. The hostname / IP address that the client
90
+
specifies when connecting will be validated against the hostname(s) and
91
+
IP address(es) recorded in the server certificate, and if no match is
92
+
found the client will close the connection.
93
+
94
+
Thus it is recommended that the server certificate include both the
95
+
fully qualified and unqualified hostnames. If the server will have
96
+
permanently assigned IP address(es), and clients are likely to use them
97
+
when connecting, they may also be included in the certificate. Both IPv4
98
+
and IPv6 addresses are supported. Historically certificates only
99
+
included 1 hostname in the ``CN`` field, however, usage of this field
100
+
for validation is now deprecated. Instead modern TLS clients will
101
+
validate against the Subject Alt Name extension data, which allows for
102
+
multiple entries. In the future usage of the ``CN`` field may be
103
+
discontinued entirely, so providing SAN extension data is strongly
104
+
recommended.
105
+
106
+
On the host holding the CA, create template files containing the
107
+
information for each server, and use it to issue server certificates.
108
+
109
+
::
110
+
111
+
# cat > server-hostNNN.info <<EOF
112
+
organization = Name of your organization
113
+
cn = hostNNN.foo.example.com
114
+
dns_name = hostNNN
115
+
dns_name = hostNNN.foo.example.com
116
+
ip_address = 10.0.1.87
117
+
ip_address = 192.8.0.92
118
+
ip_address = 2620:0:cafe::87
119
+
ip_address = 2001:24::92
120
+
tls_www_server
121
+
encryption_key
122
+
signing_key
123
+
EOF
124
+
# certtool --generate-privkey > server-hostNNN-key.pem
125
+
# certtool --generate-certificate \
126
+
--load-ca-certificate ca-cert.pem \
127
+
--load-ca-privkey ca-key.pem \
128
+
--load-privkey server-hostNNN-key.pem \
129
+
--template server-hostNNN.info \
130
+
--outfile server-hostNNN-cert.pem
131
+
132
+
The ``dns_name`` and ``ip_address`` fields in the template are setting
133
+
the subject alt name extension data. The ``tls_www_server`` keyword is
134
+
the key purpose extension to indicate this certificate is intended for
135
+
usage in a web server. Although QEMU network services are not in fact
136
+
HTTP servers (except for VNC websockets), setting this key purpose is
137
+
still recommended. The ``encryption_key`` and ``signing_key`` keyword is
138
+
the key usage extension to indicate this certificate is intended for
139
+
usage in the data session.
140
+
141
+
The ``server-hostNNN-key.pem`` and ``server-hostNNN-cert.pem`` files
142
+
should now be securely copied to the server for which they were
143
+
generated, and renamed to ``server-key.pem`` and ``server-cert.pem``
144
+
when added to the ``/etc/pki/qemu`` directory on the target host. The
145
+
``server-key.pem`` file is security sensitive and should be kept
146
+
protected with file mode 0600 to prevent disclosure.
147
+
148
+
.. _tls_005fgenerate_005fclient:
149
+
150
+
Issuing client certificates
151
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
152
+
153
+
The QEMU x509 TLS credential setup defaults to enabling client
154
+
verification using certificates, providing a simple authentication
155
+
mechanism. If this default is used, each client also needs to be issued
156
+
a certificate. The client certificate contains enough metadata to
157
+
uniquely identify the client with the scope of the certificate
158
+
authority. The client certificate would typically include fields for
159
+
organization, state, city, building, etc.
160
+
161
+
Once again on the host holding the CA, create template files containing
162
+
the information for each client, and use it to issue client
163
+
certificates.
164
+
165
+
::
166
+
167
+
# cat > client-hostNNN.info <<EOF
168
+
country = GB
169
+
state = London
170
+
locality = City Of London
171
+
organization = Name of your organization
172
+
cn = hostNNN.foo.example.com
173
+
tls_www_client
174
+
encryption_key
175
+
signing_key
176
+
EOF
177
+
# certtool --generate-privkey > client-hostNNN-key.pem
178
+
# certtool --generate-certificate \
179
+
--load-ca-certificate ca-cert.pem \
180
+
--load-ca-privkey ca-key.pem \
181
+
--load-privkey client-hostNNN-key.pem \
182
+
--template client-hostNNN.info \
183
+
--outfile client-hostNNN-cert.pem
184
+
185
+
The subject alt name extension data is not required for clients, so the
186
+
the ``dns_name`` and ``ip_address`` fields are not included. The
187
+
``tls_www_client`` keyword is the key purpose extension to indicate this
188
+
certificate is intended for usage in a web client. Although QEMU network
189
+
clients are not in fact HTTP clients, setting this key purpose is still
190
+
recommended. The ``encryption_key`` and ``signing_key`` keyword is the
191
+
key usage extension to indicate this certificate is intended for usage
192
+
in the data session.
193
+
194
+
The ``client-hostNNN-key.pem`` and ``client-hostNNN-cert.pem`` files
195
+
should now be securely copied to the client for which they were
196
+
generated, and renamed to ``client-key.pem`` and ``client-cert.pem``
197
+
when added to the ``/etc/pki/qemu`` directory on the target host. The
198
+
``client-key.pem`` file is security sensitive and should be kept
199
+
protected with file mode 0600 to prevent disclosure.
200
+
201
+
If a single host is going to be using TLS in both a client and server
202
+
role, it is possible to create a single certificate to cover both roles.
203
+
This would be quite common for the migration and NBD services, where a
204
+
QEMU process will be started by accepting a TLS protected incoming
205
+
migration, and later itself be migrated out to another host. To generate
206
+
a single certificate, simply include the template data from both the
207
+
client and server instructions in one.
208
+
209
+
::
210
+
211
+
# cat > both-hostNNN.info <<EOF
212
+
country = GB
213
+
state = London
214
+
locality = City Of London
215
+
organization = Name of your organization
216
+
cn = hostNNN.foo.example.com
217
+
dns_name = hostNNN
218
+
dns_name = hostNNN.foo.example.com
219
+
ip_address = 10.0.1.87
220
+
ip_address = 192.8.0.92
221
+
ip_address = 2620:0:cafe::87
222
+
ip_address = 2001:24::92
223
+
tls_www_server
224
+
tls_www_client
225
+
encryption_key
226
+
signing_key
227
+
EOF
228
+
# certtool --generate-privkey > both-hostNNN-key.pem
229
+
# certtool --generate-certificate \
230
+
--load-ca-certificate ca-cert.pem \
231
+
--load-ca-privkey ca-key.pem \
232
+
--load-privkey both-hostNNN-key.pem \
233
+
--template both-hostNNN.info \
234
+
--outfile both-hostNNN-cert.pem
235
+
236
+
When copying the PEM files to the target host, save them twice, once as
237
+
``server-cert.pem`` and ``server-key.pem``, and again as
238
+
``client-cert.pem`` and ``client-key.pem``.
239
+
240
+
.. _tls_005fcreds_005fsetup:
241
+
242
+
TLS x509 credential configuration
243
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
244
+
245
+
QEMU has a standard mechanism for loading x509 credentials that will be
246
+
used for network services and clients. It requires specifying the
247
+
``tls-creds-x509`` class name to the ``--object`` command line argument
248
+
for the system emulators. Each set of credentials loaded should be given
249
+
a unique string identifier via the ``id`` parameter. A single set of TLS
250
+
credentials can be used for multiple network backends, so VNC,
251
+
migration, NBD, character devices can all share the same credentials.
252
+
Note, however, that credentials for use in a client endpoint must be
253
+
loaded separately from those used in a server endpoint.
254
+
255
+
When specifying the object, the ``dir`` parameters specifies which
256
+
directory contains the credential files. This directory is expected to
257
+
contain files with the names mentioned previously, ``ca-cert.pem``,
258
+
``server-key.pem``, ``server-cert.pem``, ``client-key.pem`` and
259
+
``client-cert.pem`` as appropriate. It is also possible to include a set
260
+
of pre-generated Diffie-Hellman (DH) parameters in a file
261
+
``dh-params.pem``, which can be created using the
262
+
``certtool --generate-dh-params`` command. If omitted, QEMU will
263
+
dynamically generate DH parameters when loading the credentials.
264
+
265
+
The ``endpoint`` parameter indicates whether the credentials will be
266
+
used for a network client or server, and determines which PEM files are
267
+
loaded.
268
+
269
+
The ``verify`` parameter determines whether x509 certificate validation
270
+
should be performed. This defaults to enabled, meaning clients will
271
+
always validate the server hostname against the certificate subject alt
272
+
name fields and/or CN field. It also means that servers will request
273
+
that clients provide a certificate and validate them. Verification
274
+
should never be turned off for client endpoints, however, it may be
275
+
turned off for server endpoints if an alternative mechanism is used to
276
+
authenticate clients. For example, the VNC server can use SASL to
277
+
authenticate clients instead.
278
+
279
+
To load server credentials with client certificate validation enabled
280
+
281
+
.. parsed-literal::
282
+
283
+
|qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
284
+
285
+
while to load client credentials use
286
+
287
+
.. parsed-literal::
288
+
289
+
|qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
290
+
291
+
Network services which support TLS will all have a ``tls-creds``
292
+
parameter which expects the ID of the TLS credentials object. For
293
+
example with VNC:
294
+
295
+
.. parsed-literal::
296
+
297
+
|qemu_system| -vnc 0.0.0.0:0,tls-creds=tls0
298
+
299
+
.. _tls_005fpsk:
300
+
301
+
TLS Pre-Shared Keys (PSK)
302
+
~~~~~~~~~~~~~~~~~~~~~~~~~
303
+
304
+
Instead of using certificates, you may also use TLS Pre-Shared Keys
305
+
(TLS-PSK). This can be simpler to set up than certificates but is less
306
+
scalable.
307
+
308
+
Use the GnuTLS ``psktool`` program to generate a ``keys.psk`` file
309
+
containing one or more usernames and random keys::
310
+
311
+
mkdir -m 0700 /tmp/keys
312
+
psktool -u rich -p /tmp/keys/keys.psk
313
+
314
+
TLS-enabled servers such as qemu-nbd can use this directory like so::
315
+
316
+
qemu-nbd \
317
+
-t -x / \
318
+
--object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \
319
+
--tls-creds tls0 \
320
+
image.qcow2
321
+
322
+
When connecting from a qemu-based client you must specify the directory
323
+
containing ``keys.psk`` and an optional username (defaults to "qemu")::
324
+
325
+
qemu-img info \
326
+
--object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
327
+
--image-opts \
328
+
file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
+137
docs/system/usb.rst
+137
docs/system/usb.rst
···
1
+
.. _pcsys_005fusb:
2
+
3
+
USB emulation
4
+
-------------
5
+
6
+
QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
7
+
plug virtual USB devices or real host USB devices (only works with
8
+
certain host operating systems). QEMU will automatically create and
9
+
connect virtual USB hubs as necessary to connect multiple USB devices.
10
+
11
+
.. _usb_005fdevices:
12
+
13
+
Connecting USB devices
14
+
~~~~~~~~~~~~~~~~~~~~~~
15
+
16
+
USB devices can be connected with the ``-device usb-...`` command line
17
+
option or the ``device_add`` monitor command. Available devices are:
18
+
19
+
``usb-mouse``
20
+
Virtual Mouse. This will override the PS/2 mouse emulation when
21
+
activated.
22
+
23
+
``usb-tablet``
24
+
Pointer device that uses absolute coordinates (like a touchscreen).
25
+
This means QEMU is able to report the mouse position without having
26
+
to grab the mouse. Also overrides the PS/2 mouse emulation when
27
+
activated.
28
+
29
+
``usb-storage,drive=drive_id``
30
+
Mass storage device backed by drive_id (see
31
+
:ref:`disk_005fimages`)
32
+
33
+
``usb-uas``
34
+
USB attached SCSI device, see
35
+
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
36
+
for details
37
+
38
+
``usb-bot``
39
+
Bulk-only transport storage device, see
40
+
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
41
+
for details here, too
42
+
43
+
``usb-mtp,rootdir=dir``
44
+
Media transfer protocol device, using dir as root of the file tree
45
+
that is presented to the guest.
46
+
47
+
``usb-host,hostbus=bus,hostaddr=addr``
48
+
Pass through the host device identified by bus and addr
49
+
50
+
``usb-host,vendorid=vendor,productid=product``
51
+
Pass through the host device identified by vendor and product ID
52
+
53
+
``usb-wacom-tablet``
54
+
Virtual Wacom PenPartner tablet. This device is similar to the
55
+
``tablet`` above but it can be used with the tslib library because in
56
+
addition to touch coordinates it reports touch pressure.
57
+
58
+
``usb-kbd``
59
+
Standard USB keyboard. Will override the PS/2 keyboard (if present).
60
+
61
+
``usb-serial,chardev=id``
62
+
Serial converter. This emulates an FTDI FT232BM chip connected to
63
+
host character device id.
64
+
65
+
``usb-braille,chardev=id``
66
+
Braille device. This will use BrlAPI to display the braille output on
67
+
a real or fake device referenced by id.
68
+
69
+
``usb-net[,netdev=id]``
70
+
Network adapter that supports CDC ethernet and RNDIS protocols. id
71
+
specifies a netdev defined with ``-netdev …,id=id``. For instance,
72
+
user-mode networking can be used with
73
+
74
+
.. parsed-literal::
75
+
76
+
|qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
77
+
78
+
``usb-ccid``
79
+
Smartcard reader device
80
+
81
+
``usb-audio``
82
+
USB audio device
83
+
84
+
.. _host_005fusb_005fdevices:
85
+
86
+
Using host USB devices on a Linux host
87
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
88
+
89
+
WARNING: this is an experimental feature. QEMU will slow down when using
90
+
it. USB devices requiring real time streaming (i.e. USB Video Cameras)
91
+
are not supported yet.
92
+
93
+
1. If you use an early Linux 2.4 kernel, verify that no Linux driver is
94
+
actually using the USB device. A simple way to do that is simply to
95
+
disable the corresponding kernel module by renaming it from
96
+
``mydriver.o`` to ``mydriver.o.disabled``.
97
+
98
+
2. Verify that ``/proc/bus/usb`` is working (most Linux distributions
99
+
should enable it by default). You should see something like that:
100
+
101
+
::
102
+
103
+
ls /proc/bus/usb
104
+
001 devices drivers
105
+
106
+
3. Since only root can access to the USB devices directly, you can
107
+
either launch QEMU as root or change the permissions of the USB
108
+
devices you want to use. For testing, the following suffices:
109
+
110
+
::
111
+
112
+
chown -R myuid /proc/bus/usb
113
+
114
+
4. Launch QEMU and do in the monitor:
115
+
116
+
::
117
+
118
+
info usbhost
119
+
Device 1.2, speed 480 Mb/s
120
+
Class 00: USB device 1234:5678, USB DISK
121
+
122
+
You should see the list of the devices you can use (Never try to use
123
+
hubs, it won't work).
124
+
125
+
5. Add the device in QEMU by using:
126
+
127
+
::
128
+
129
+
device_add usb-host,vendorid=0x1234,productid=0x5678
130
+
131
+
Normally the guest OS should report that a new USB device is plugged.
132
+
You can use the option ``-device usb-host,...`` to do the same.
133
+
134
+
6. Now you can try to use the host USB device in QEMU.
135
+
136
+
When relaunching QEMU, you may have to unplug and plug again the USB
137
+
device to make it work again (this is a bug).
+202
docs/system/vnc-security.rst
+202
docs/system/vnc-security.rst
···
1
+
.. _vnc_005fsecurity:
2
+
3
+
VNC security
4
+
------------
5
+
6
+
The VNC server capability provides access to the graphical console of
7
+
the guest VM across the network. This has a number of security
8
+
considerations depending on the deployment scenarios.
9
+
10
+
.. _vnc_005fsec_005fnone:
11
+
12
+
Without passwords
13
+
~~~~~~~~~~~~~~~~~
14
+
15
+
The simplest VNC server setup does not include any form of
16
+
authentication. For this setup it is recommended to restrict it to
17
+
listen on a UNIX domain socket only. For example
18
+
19
+
.. parsed-literal::
20
+
21
+
|qemu_system| [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
22
+
23
+
This ensures that only users on local box with read/write access to that
24
+
path can access the VNC server. To securely access the VNC server from a
25
+
remote machine, a combination of netcat+ssh can be used to provide a
26
+
secure tunnel.
27
+
28
+
.. _vnc_005fsec_005fpassword:
29
+
30
+
With passwords
31
+
~~~~~~~~~~~~~~
32
+
33
+
The VNC protocol has limited support for password based authentication.
34
+
Since the protocol limits passwords to 8 characters it should not be
35
+
considered to provide high security. The password can be fairly easily
36
+
brute-forced by a client making repeat connections. For this reason, a
37
+
VNC server using password authentication should be restricted to only
38
+
listen on the loopback interface or UNIX domain sockets. Password
39
+
authentication is not supported when operating in FIPS 140-2 compliance
40
+
mode as it requires the use of the DES cipher. Password authentication
41
+
is requested with the ``password`` option, and then once QEMU is running
42
+
the password is set with the monitor. Until the monitor is used to set
43
+
the password all clients will be rejected.
44
+
45
+
.. parsed-literal::
46
+
47
+
|qemu_system| [...OPTIONS...] -vnc :1,password -monitor stdio
48
+
(qemu) change vnc password
49
+
Password: ********
50
+
(qemu)
51
+
52
+
.. _vnc_005fsec_005fcertificate:
53
+
54
+
With x509 certificates
55
+
~~~~~~~~~~~~~~~~~~~~~~
56
+
57
+
The QEMU VNC server also implements the VeNCrypt extension allowing use
58
+
of TLS for encryption of the session, and x509 certificates for
59
+
authentication. The use of x509 certificates is strongly recommended,
60
+
because TLS on its own is susceptible to man-in-the-middle attacks.
61
+
Basic x509 certificate support provides a secure session, but no
62
+
authentication. This allows any client to connect, and provides an
63
+
encrypted session.
64
+
65
+
.. parsed-literal::
66
+
67
+
|qemu_system| [...OPTIONS...] \
68
+
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \
69
+
-vnc :1,tls-creds=tls0 -monitor stdio
70
+
71
+
In the above example ``/etc/pki/qemu`` should contain at least three
72
+
files, ``ca-cert.pem``, ``server-cert.pem`` and ``server-key.pem``.
73
+
Unprivileged users will want to use a private directory, for example
74
+
``$HOME/.pki/qemu``. NB the ``server-key.pem`` file should be protected
75
+
with file mode 0600 to only be readable by the user owning it.
76
+
77
+
.. _vnc_005fsec_005fcertificate_005fverify:
78
+
79
+
With x509 certificates and client verification
80
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81
+
82
+
Certificates can also provide a means to authenticate the client
83
+
connecting. The server will request that the client provide a
84
+
certificate, which it will then validate against the CA certificate.
85
+
This is a good choice if deploying in an environment with a private
86
+
internal certificate authority. It uses the same syntax as previously,
87
+
but with ``verify-peer`` set to ``yes`` instead.
88
+
89
+
.. parsed-literal::
90
+
91
+
|qemu_system| [...OPTIONS...] \
92
+
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
93
+
-vnc :1,tls-creds=tls0 -monitor stdio
94
+
95
+
.. _vnc_005fsec_005fcertificate_005fpw:
96
+
97
+
With x509 certificates, client verification and passwords
98
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99
+
100
+
Finally, the previous method can be combined with VNC password
101
+
authentication to provide two layers of authentication for clients.
102
+
103
+
.. parsed-literal::
104
+
105
+
|qemu_system| [...OPTIONS...] \
106
+
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
107
+
-vnc :1,tls-creds=tls0,password -monitor stdio
108
+
(qemu) change vnc password
109
+
Password: ********
110
+
(qemu)
111
+
112
+
.. _vnc_005fsec_005fsasl:
113
+
114
+
With SASL authentication
115
+
~~~~~~~~~~~~~~~~~~~~~~~~
116
+
117
+
The SASL authentication method is a VNC extension, that provides an
118
+
easily extendable, pluggable authentication method. This allows for
119
+
integration with a wide range of authentication mechanisms, such as PAM,
120
+
GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more. The
121
+
strength of the authentication depends on the exact mechanism
122
+
configured. If the chosen mechanism also provides a SSF layer, then it
123
+
will encrypt the datastream as well.
124
+
125
+
Refer to the later docs on how to choose the exact SASL mechanism used
126
+
for authentication, but assuming use of one supporting SSF, then QEMU
127
+
can be launched with:
128
+
129
+
.. parsed-literal::
130
+
131
+
|qemu_system| [...OPTIONS...] -vnc :1,sasl -monitor stdio
132
+
133
+
.. _vnc_005fsec_005fcertificate_005fsasl:
134
+
135
+
With x509 certificates and SASL authentication
136
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
137
+
138
+
If the desired SASL authentication mechanism does not supported SSF
139
+
layers, then it is strongly advised to run it in combination with TLS
140
+
and x509 certificates. This provides securely encrypted data stream,
141
+
avoiding risk of compromising of the security credentials. This can be
142
+
enabled, by combining the 'sasl' option with the aforementioned TLS +
143
+
x509 options:
144
+
145
+
.. parsed-literal::
146
+
147
+
|qemu_system| [...OPTIONS...] \
148
+
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
149
+
-vnc :1,tls-creds=tls0,sasl -monitor stdio
150
+
151
+
.. _vnc_005fsetup_005fsasl:
152
+
153
+
Configuring SASL mechanisms
154
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
155
+
156
+
The following documentation assumes use of the Cyrus SASL implementation
157
+
on a Linux host, but the principles should apply to any other SASL
158
+
implementation or host. When SASL is enabled, the mechanism
159
+
configuration will be loaded from system default SASL service config
160
+
/etc/sasl2/qemu.conf. If running QEMU as an unprivileged user, an
161
+
environment variable SASL_CONF_PATH can be used to make it search
162
+
alternate locations for the service config file.
163
+
164
+
If the TLS option is enabled for VNC, then it will provide session
165
+
encryption, otherwise the SASL mechanism will have to provide
166
+
encryption. In the latter case the list of possible plugins that can be
167
+
used is drastically reduced. In fact only the GSSAPI SASL mechanism
168
+
provides an acceptable level of security by modern standards. Previous
169
+
versions of QEMU referred to the DIGEST-MD5 mechanism, however, it has
170
+
multiple serious flaws described in detail in RFC 6331 and thus should
171
+
never be used any more. The SCRAM-SHA-1 mechanism provides a simple
172
+
username/password auth facility similar to DIGEST-MD5, but does not
173
+
support session encryption, so can only be used in combination with TLS.
174
+
175
+
When not using TLS the recommended configuration is
176
+
177
+
::
178
+
179
+
mech_list: gssapi
180
+
keytab: /etc/qemu/krb5.tab
181
+
182
+
This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol,
183
+
with the server principal stored in /etc/qemu/krb5.tab. For this to work
184
+
the administrator of your KDC must generate a Kerberos principal for the
185
+
server, with a name of 'qemu/somehost.example.com@EXAMPLE.COM' replacing
186
+
'somehost.example.com' with the fully qualified host name of the machine
187
+
running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
188
+
189
+
When using TLS, if username+password authentication is desired, then a
190
+
reasonable configuration is
191
+
192
+
::
193
+
194
+
mech_list: scram-sha-1
195
+
sasldb_path: /etc/qemu/passwd.db
196
+
197
+
The ``saslpasswd2`` program can be used to populate the ``passwd.db``
198
+
file with accounts.
199
+
200
+
Other SASL configurations will be left as an exercise for the reader.
201
+
Note that all mechanisms, except GSSAPI, should be combined with use of
202
+
TLS to ensure a secure data channel.