| 1 | .. _qemu-vnc: |
| 2 | |
| 3 | ========================== |
| 4 | QEMU standalone VNC server |
| 5 | ========================== |
| 6 | |
| 7 | Synopsis |
| 8 | -------- |
| 9 | |
| 10 | **qemu-vnc** [*OPTION*]... |
| 11 | |
| 12 | Description |
| 13 | ----------- |
| 14 | |
| 15 | ``qemu-vnc`` is a standalone VNC server that connects to a running QEMU instance |
| 16 | via the D-Bus display interface (:ref:`dbus-display`). It serves the guest |
| 17 | display, input, audio, clipboard, and serial console chardevs over the VNC |
| 18 | protocol, allowing VNC clients to interact with the virtual machine without QEMU |
| 19 | itself binding a VNC socket. |
| 20 | |
| 21 | Options |
| 22 | ------- |
| 23 | |
| 24 | .. program:: qemu-vnc |
| 25 | |
| 26 | .. option:: -h, --help |
| 27 | |
| 28 | Display help and exit. |
| 29 | |
| 30 | .. option:: -V, --version |
| 31 | |
| 32 | Print version information and exit. |
| 33 | |
| 34 | .. option:: -a ADDRESS, --dbus-address=ADDRESS |
| 35 | |
| 36 | D-Bus address to connect to. When not specified, ``qemu-vnc`` connects to the |
| 37 | session bus. |
| 38 | |
| 39 | .. option:: -p FD, --dbus-p2p-fd=FD |
| 40 | |
| 41 | File descriptor of an inherited Unix socket for a peer-to-peer D-Bus |
| 42 | connection to QEMU. This is mutually exclusive with ``--dbus-address`` and |
| 43 | ``--bus-name``. |
| 44 | |
| 45 | .. option:: -n NAME, --bus-name=NAME |
| 46 | |
| 47 | D-Bus bus name of the QEMU instance to connect to. The default is |
| 48 | ``org.qemu``. When a custom ``--dbus-address`` is given without a bus name, |
| 49 | peer-to-peer D-Bus is used. |
| 50 | |
| 51 | .. option:: -W, --wait |
| 52 | |
| 53 | Wait for the D-Bus bus name to appear. Only for bus connections. |
| 54 | |
| 55 | .. option:: --password |
| 56 | |
| 57 | Require VNC password authentication from connecting clients. The password is |
| 58 | set at runtime via the D-Bus ``SetPassword`` method (see |
| 59 | :doc:`/interop/dbus-vnc`). Clients will not be able to connect until a |
| 60 | password has been set. |
| 61 | |
| 62 | This option is ignored when a systemd credential password is present, since |
| 63 | password authentication is already enabled via ``password-secret`` in that |
| 64 | case. |
| 65 | |
| 66 | .. option:: -l ADDR, --vnc-addr=ADDR |
| 67 | |
| 68 | VNC listen address in the same format as the QEMU ``-vnc`` option (default |
| 69 | ``localhost:0``, i.e. TCP port 5900). |
| 70 | |
| 71 | .. option:: -w ADDR, --websocket=ADDR |
| 72 | |
| 73 | Enable WebSocket transport on the given address. *ADDR* can be a port number |
| 74 | or an *address:port* pair. |
| 75 | |
| 76 | .. option:: -O OBJDEF, --object=OBJDEF |
| 77 | |
| 78 | Create a QEMU user-creatable object. *OBJDEF* uses the same key=value syntax |
| 79 | as the QEMU ``-object`` option. This option may be given multiple times. It is |
| 80 | needed, for example, to create authorization objects referenced by |
| 81 | ``--tls-authz``. |
| 82 | |
| 83 | .. option:: -t DIR, --tls-creds=DIR |
| 84 | |
| 85 | Directory containing TLS x509 credentials (``ca-cert.pem``, |
| 86 | ``server-cert.pem``, ``server-key.pem``). When specified, the VNC server |
| 87 | requires TLS from connecting clients. |
| 88 | |
| 89 | .. option:: --tls-authz=ID |
| 90 | |
| 91 | ID of a ``QAuthZ`` object previously created with ``--object`` for TLS client |
| 92 | certificate authorization. When specified, the TLS credentials are created |
| 93 | with ``verify-peer=yes`` so connecting clients must present a valid |
| 94 | certificate. After the TLS handshake, the client certificate Distinguished |
| 95 | Name is checked against the authorization object. This option requires |
| 96 | ``--tls-creds``. |
| 97 | |
| 98 | .. option:: --sasl |
| 99 | |
| 100 | Require that the client use SASL to authenticate with the VNC server. The |
| 101 | exact choice of authentication method used is controlled from the system / |
| 102 | user's SASL configuration file for the 'qemu' service. This is typically found |
| 103 | in ``/etc/sasl2/qemu.conf``. If running QEMU as an unprivileged user, an |
| 104 | environment variable ``SASL_CONF_PATH`` can be used to make it search |
| 105 | alternate locations for the service config. While some SASL auth methods can |
| 106 | also provide data encryption (eg GSSAPI), it is recommended that SASL always |
| 107 | be combined with the 'tls' and 'x509' settings to enable use of SSL and server |
| 108 | certificates. This ensures a data encryption preventing compromise of |
| 109 | authentication credentials. See the :ref:`VNC security` section in the System |
| 110 | Emulation Users Guide for details on using SASL authentication. |
| 111 | |
| 112 | .. option:: --sasl-authz=ID |
| 113 | |
| 114 | ID of a ``QAuthZ`` object previously created with ``--object`` for SASL |
| 115 | username authorization. After successful SASL authentication, the |
| 116 | authenticated username is checked against the authorization object. If the |
| 117 | check fails, the client is disconnected. This option requires ``--sasl``. |
| 118 | |
| 119 | .. option:: -s POLICY, --share=POLICY |
| 120 | |
| 121 | Set display sharing policy. *POLICY* is one of ``allow-exclusive``, |
| 122 | ``force-shared``, or ``ignore``. |
| 123 | |
| 124 | ``allow-exclusive`` allows clients to ask for exclusive access. As suggested |
| 125 | by the RFB spec this is implemented by dropping other connections. Connecting |
| 126 | multiple clients in parallel requires all clients asking for a shared session |
| 127 | (vncviewer: -shared switch). This is the default. |
| 128 | |
| 129 | ``force-shared`` disables exclusive client access. Useful for shared desktop |
| 130 | sessions, where you don't want someone forgetting to specify -shared |
| 131 | disconnect everybody else. |
| 132 | |
| 133 | ``ignore`` completely ignores the shared flag and allows everybody to connect |
| 134 | unconditionally. Doesn't conform to the RFB spec but is traditional QEMU |
| 135 | behavior. |
| 136 | |
| 137 | .. option:: -C NAME, --vt-chardev=NAME |
| 138 | |
| 139 | Chardev type name to expose as a VNC text console. This option may be given |
| 140 | multiple times to expose several chardevs. When not specified, the defaults |
| 141 | ``org.qemu.console.serial.0`` and ``org.qemu.monitor.hmp.0`` are used. |
| 142 | |
| 143 | .. option:: -N, --no-vt |
| 144 | |
| 145 | Do not expose any chardevs as text consoles. This overrides the default |
| 146 | chardev list and any ``--vt-chardev`` options. |
| 147 | |
| 148 | .. option:: -k LAYOUT, --keyboard-layout=LAYOUT |
| 149 | |
| 150 | Keyboard layout (e.g. ``en-us``). Passed through to the VNC server for |
| 151 | key-code translation. |
| 152 | |
| 153 | .. option:: --lossy |
| 154 | |
| 155 | Enable lossy compression methods (gradient, JPEG, ...). If this option is set, |
| 156 | VNC client may receive lossy framebuffer updates depending on its encoding |
| 157 | settings. Enabling this option can save a lot of bandwidth at the expense of |
| 158 | quality. |
| 159 | |
| 160 | .. option:: --non-adaptive |
| 161 | |
| 162 | Disable adaptive encodings. Adaptive encodings are enabled by default. An |
| 163 | adaptive encoding will try to detect frequently updated screen regions, and |
| 164 | send updates in these regions using a lossy encoding (like JPEG). This can be |
| 165 | really helpful to save bandwidth when playing videos. Disabling adaptive |
| 166 | encodings restores the original static behavior of encodings like Tight. |
| 167 | |
| 168 | .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] |
| 169 | |
| 170 | .. include:: ../qemu-option-trace.rst.inc |
| 171 | |
| 172 | Examples |
| 173 | -------- |
| 174 | |
| 175 | Start QEMU with the D-Bus display backend:: |
| 176 | |
| 177 | qemu-system-x86_64 -display dbus ... |
| 178 | |
| 179 | Then attach ``qemu-vnc``:: |
| 180 | |
| 181 | qemu-vnc |
| 182 | |
| 183 | A VNC client can now connect to ``localhost:5900``. |
| 184 | |
| 185 | To listen on a different port with TLS:: |
| 186 | |
| 187 | qemu-vnc --vnc-addr localhost:1 --tls-creds /etc/pki/qemu-vnc |
| 188 | |
| 189 | To require TLS with client certificate authorization:: |
| 190 | |
| 191 | qemu-vnc --object authz-list-file,id=auth0,filename=/etc/qemu/vnc.acl,refresh=on \ |
| 192 | --tls-creds /etc/pki/qemu-vnc --tls-authz auth0 |
| 193 | |
| 194 | To enable SASL authentication with TLS:: |
| 195 | |
| 196 | qemu-vnc --tls-creds /etc/pki/qemu-vnc --sasl |
| 197 | |
| 198 | VNC password authentication |
| 199 | ---------------------------- |
| 200 | |
| 201 | There are two ways to enable VNC password authentication: |
| 202 | |
| 203 | 1. ``--password`` flag -- start ``qemu-vnc`` with ``--password`` and |
| 204 | then set the password at runtime using the D-Bus ``SetPassword`` |
| 205 | method. Clients will be rejected until a password is set. |
| 206 | |
| 207 | 2. systemd credentials -- if the ``CREDENTIALS_DIRECTORY`` |
| 208 | environment variable is set (see :manpage:`systemd.exec(5)`) and |
| 209 | contains a file named ``vnc-password``, the VNC server will use |
| 210 | that file's contents as the password automatically. The |
| 211 | ``--password`` flag is not needed in this case. |
| 212 | |
| 213 | D-Bus interface |
| 214 | --------------- |
| 215 | |
| 216 | ``qemu-vnc`` exposes a D-Bus interface for management and monitoring of |
| 217 | VNC connections. See :doc:`/interop/dbus-vnc` for the full interface |
| 218 | reference. |
| 219 | |
| 220 | See also |
| 221 | -------- |
| 222 | |
| 223 | :manpage:`qemu(1)`, |
| 224 | :doc:`/interop/dbus-display`, |
| 225 | :doc:`/interop/dbus-vnc`, |
| 226 | `The RFB Protocol <https://github.com/rfbproto/rfbproto>`_ |