.\" Man page generated from reStructuredText .\" by the Docutils 0.23 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "QEMU-VNC" "1" "Aug 28, 2026" "11.1.1" "QEMU" .SH NAME qemu-vnc \- QEMU standalone VNC server .SH SYNOPSIS .sp \fBqemu\-vnc\fP [\fIOPTION\fP]... .SH DESCRIPTION .sp \fBqemu\-vnc\fP is a standalone VNC server that connects to a running QEMU instance via the D\-Bus display interface (D\-Bus display \%<#\:dbus-display>). It serves the guest display, input, audio, clipboard, and serial console chardevs over the VNC protocol, allowing VNC clients to interact with the virtual machine without QEMU itself binding a VNC socket. .SH OPTIONS .INDENT 0.0 .TP .B \-h, \-\-help Display help and exit. .UNINDENT .INDENT 0.0 .TP .B \-V, \-\-version Print version information and exit. .UNINDENT .INDENT 0.0 .TP .B \-a ADDRESS, \-\-dbus\-address=ADDRESS D\-Bus address to connect to. When not specified, \fBqemu\-vnc\fP connects to the session bus. .UNINDENT .INDENT 0.0 .TP .B \-p FD, \-\-dbus\-p2p\-fd=FD File descriptor of an inherited Unix socket for a peer\-to\-peer D\-Bus connection to QEMU. This is mutually exclusive with \fB\-\-dbus\-address\fP and \fB\-\-bus\-name\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-n NAME, \-\-bus\-name=NAME D\-Bus bus name of the QEMU instance to connect to. The default is \fBorg.qemu\fP\&. When a custom \fB\-\-dbus\-address\fP is given without a bus name, peer\-to\-peer D\-Bus is used. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-wait Wait for the D\-Bus bus name to appear. Only for bus connections. .UNINDENT .INDENT 0.0 .TP .B \-\-password Require VNC password authentication from connecting clients. The password is set at runtime via the D\-Bus \fBSetPassword\fP method (see D\-Bus VNC \%<>). Clients will not be able to connect until a password has been set. .sp This option is ignored when a systemd credential password is present, since password authentication is already enabled via \fBpassword\-secret\fP in that case. .UNINDENT .INDENT 0.0 .TP .B \-l ADDR, \-\-vnc\-addr=ADDR VNC listen address in the same format as the QEMU \fB\-vnc\fP option (default \fBlocalhost:0\fP, i.e. TCP port 5900). .UNINDENT .INDENT 0.0 .TP .B \-w ADDR, \-\-websocket=ADDR Enable WebSocket transport on the given address. \fIADDR\fP can be a port number or an \fIaddress:port\fP pair. .UNINDENT .INDENT 0.0 .TP .B \-O OBJDEF, \-\-object=OBJDEF Create a QEMU user\-creatable object. \fIOBJDEF\fP uses the same key=value syntax as the QEMU \fB\-object\fP option. This option may be given multiple times. It is needed, for example, to create authorization objects referenced by \fB\-\-tls\-authz\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-t DIR, \-\-tls\-creds=DIR Directory containing TLS x509 credentials (\fBca\-cert.pem\fP, \fBserver\-cert.pem\fP, \fBserver\-key.pem\fP). When specified, the VNC server requires TLS from connecting clients. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-authz=ID ID of a \fBQAuthZ\fP object previously created with \fB\-\-object\fP for TLS client certificate authorization. When specified, the TLS credentials are created with \fBverify\-peer=yes\fP so connecting clients must present a valid certificate. After the TLS handshake, the client certificate Distinguished Name is checked against the authorization object. This option requires \fB\-\-tls\-creds\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-sasl Require that the client use SASL to authenticate with the VNC server. The exact choice of authentication method used is controlled from the system / user\(aqs SASL configuration file for the \(aqqemu\(aq service. This is typically found in \fB/etc/sasl2/qemu.conf\fP\&. If running QEMU as an unprivileged user, an environment variable \fBSASL_CONF_PATH\fP can be used to make it search alternate locations for the service config. While some SASL auth methods can also provide data encryption (eg GSSAPI), it is recommended that SASL always be combined with the \(aqtls\(aq and \(aqx509\(aq settings to enable use of SSL and server certificates. This ensures a data encryption preventing compromise of authentication credentials. See the VNC security \%<#\:vnc-security> section in the System Emulation Users Guide for details on using SASL authentication. .UNINDENT .INDENT 0.0 .TP .B \-\-sasl\-authz=ID ID of a \fBQAuthZ\fP object previously created with \fB\-\-object\fP for SASL username authorization. After successful SASL authentication, the authenticated username is checked against the authorization object. If the check fails, the client is disconnected. This option requires \fB\-\-sasl\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-s POLICY, \-\-share=POLICY Set display sharing policy. \fIPOLICY\fP is one of \fBallow\-exclusive\fP, \fBforce\-shared\fP, or \fBignore\fP\&. .sp \fBallow\-exclusive\fP allows clients to ask for exclusive access. As suggested by the RFB spec this is implemented by dropping other connections. Connecting multiple clients in parallel requires all clients asking for a shared session (vncviewer: \-shared switch). This is the default. .sp \fBforce\-shared\fP disables exclusive client access. Useful for shared desktop sessions, where you don\(aqt want someone forgetting to specify \-shared disconnect everybody else. .sp \fBignore\fP completely ignores the shared flag and allows everybody to connect unconditionally. Doesn\(aqt conform to the RFB spec but is traditional QEMU behavior. .UNINDENT .INDENT 0.0 .TP .B \-C NAME, \-\-vt\-chardev=NAME Chardev type name to expose as a VNC text console. This option may be given multiple times to expose several chardevs. When not specified, the defaults \fBorg.qemu.console.serial.0\fP and \fBorg.qemu.monitor.hmp.0\fP are used. .UNINDENT .INDENT 0.0 .TP .B \-N, \-\-no\-vt Do not expose any chardevs as text consoles. This overrides the default chardev list and any \fB\-\-vt\-chardev\fP options. .UNINDENT .INDENT 0.0 .TP .B \-k LAYOUT, \-\-keyboard\-layout=LAYOUT Keyboard layout (e.g. \fBen\-us\fP). Passed through to the VNC server for key\-code translation. .UNINDENT .INDENT 0.0 .TP .B \-\-lossy Enable lossy compression methods (gradient, JPEG, ...). If this option is set, VNC client may receive lossy framebuffer updates depending on its encoding settings. Enabling this option can save a lot of bandwidth at the expense of quality. .UNINDENT .INDENT 0.0 .TP .B \-\-non\-adaptive Disable adaptive encodings. Adaptive encodings are enabled by default. An adaptive encoding will try to detect frequently updated screen regions, and send updates in these regions using a lossy encoding (like JPEG). This can be really helpful to save bandwidth when playing videos. Disabling adaptive encodings restores the original static behavior of encodings like Tight. .UNINDENT .INDENT 0.0 .TP .B \-T, \-\-trace [[enable=]PATTERN][,events=FILE][,file=FILE] Specify tracing options. .sp \fB[enable=]PATTERN\fP .INDENT 7.0 .INDENT 3.5 Immediately enable events matching \fIPATTERN\fP (either event name or a globbing pattern). This option is only available if QEMU has been compiled with the \fBsimple\fP, \fBlog\fP or \fBftrace\fP tracing backend. To specify multiple events or patterns, specify the \fB\-trace\fP option multiple times. .sp Use \fB\-trace help\fP to print a list of names of trace points. .UNINDENT .UNINDENT .sp \fBevents=FILE\fP .INDENT 7.0 .INDENT 3.5 Immediately enable events listed in \fIFILE\fP\&. The file must contain one event name (as listed in the \fBtrace\-events\-all\fP file) per line; globbing patterns are accepted too. This option is only available if QEMU has been compiled with the \fBsimple\fP, \fBlog\fP or \fBftrace\fP tracing backend. .UNINDENT .UNINDENT .sp \fBfile=FILE\fP .INDENT 7.0 .INDENT 3.5 Log output traces to \fIFILE\fP\&. This option is only available if QEMU has been compiled with the \fBsimple\fP tracing backend. .UNINDENT .UNINDENT .UNINDENT .SH EXAMPLES .sp Start QEMU with the D\-Bus display backend: .INDENT 0.0 .INDENT 3.5 .sp .EX qemu\-system\-x86_64 \-display dbus ... .EE .UNINDENT .UNINDENT .sp Then attach \fBqemu\-vnc\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX qemu\-vnc .EE .UNINDENT .UNINDENT .sp A VNC client can now connect to \fBlocalhost:5900\fP\&. .sp To listen on a different port with TLS: .INDENT 0.0 .INDENT 3.5 .sp .EX qemu\-vnc \-\-vnc\-addr localhost:1 \-\-tls\-creds /etc/pki/qemu\-vnc .EE .UNINDENT .UNINDENT .sp To require TLS with client certificate authorization: .INDENT 0.0 .INDENT 3.5 .sp .EX qemu\-vnc \-\-object authz\-list\-file,id=auth0,filename=/etc/qemu/vnc.acl,refresh=on \e \-\-tls\-creds /etc/pki/qemu\-vnc \-\-tls\-authz auth0 .EE .UNINDENT .UNINDENT .sp To enable SASL authentication with TLS: .INDENT 0.0 .INDENT 3.5 .sp .EX qemu\-vnc \-\-tls\-creds /etc/pki/qemu\-vnc \-\-sasl .EE .UNINDENT .UNINDENT .SH VNC PASSWORD AUTHENTICATION .sp There are two ways to enable VNC password authentication: .INDENT 0.0 .IP 1. 3 \fB\-\-password\fP flag \-\- start \fBqemu\-vnc\fP with \fB\-\-password\fP and then set the password at runtime using the D\-Bus \fBSetPassword\fP method. Clients will be rejected until a password is set. .IP 2. 3 systemd credentials \-\- if the \fBCREDENTIALS_DIRECTORY\fP environment variable is set (see \fBsystemd.exec(5)\fP) and contains a file named \fBvnc\-password\fP, the VNC server will use that file\(aqs contents as the password automatically. The \fB\-\-password\fP flag is not needed in this case. .UNINDENT .SH D-BUS INTERFACE .sp \fBqemu\-vnc\fP exposes a D\-Bus interface for management and monitoring of VNC connections. See D\-Bus VNC \%<> for the full interface reference. .SH SEE ALSO .sp \fBqemu(1)\fP, D\-Bus display \%<>, D\-Bus VNC \%<>, The RFB Protocol \% .SH Copyright 2026, The QEMU Project Developers .\" End of generated man page.