This patch updates the user documentation to detail the new syntax options for VNC server configuration. It moves all the display related options into a combined logical section for clarity. It documents the different deployment secenarios possible with the new VNC server capabilities and their security. It also provides a guide for setting up a certificate authority and issuing clients and server with their certificates
diff -r 9e499876ee0e qemu-doc.texi --- a/qemu-doc.texi Tue Jul 31 11:47:13 2007 -0400 +++ b/qemu-doc.texi Tue Jul 31 14:43:50 2007 -0400 @@ -129,6 +129,7 @@ Download the experimental binary install * pcsys_network:: Network emulation * direct_linux_boot:: Direct Linux Boot * pcsys_usb:: USB emulation +* vnc_security:: VNC security * gdb_usage:: GDB usage * pcsys_os_specific:: Target OS specific information @end menu @@ -243,6 +244,56 @@ Simulate an SMP system with @var{n} CPUs Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 CPUs are supported. [EMAIL PROTECTED] -audio-help + +Will show the audio subsystem help: list of drivers, tunable +parameters. + [EMAIL PROTECTED] -soundhw card1,card2,... or -soundhw all + +Enable audio and selected sound hardware. Use ? to print all +available sound hardware. + [EMAIL PROTECTED] +qemu -soundhw sb16,adlib hda +qemu -soundhw es1370 hda +qemu -soundhw all hda +qemu -soundhw ? [EMAIL PROTECTED] example + [EMAIL PROTECTED] -localtime +Set the real time clock to local time (the default is to UTC +time). This option is needed to have correct date in MS-DOS or +Windows. + [EMAIL PROTECTED] -pidfile file +Store the QEMU process PID in @var{file}. It is useful if you launch QEMU +from a script. + [EMAIL PROTECTED] -daemonize +Daemonize the QEMU process after initialization. QEMU will not detach from +standard IO until it is ready to receive connections on any of its devices. +This option is a useful way for external programs to launch QEMU without having +to cope with initialization race conditions. + [EMAIL PROTECTED] -win2k-hack +Use it when installing Windows 2000 to avoid a disk full bug. After +Windows 2000 is installed, you no longer need this option (this option +slows down the IDE transfers). + [EMAIL PROTECTED] -option-rom file +Load the contents of file as an option ROM. This option is useful to load +things like EtherBoot. + [EMAIL PROTECTED] -name string +Sets the name of the guest. This name will be display in the SDL window +caption. The name will also be used for the VNC server. + [EMAIL PROTECTED] table + +Display options: [EMAIL PROTECTED] @option + @item -nographic Normally, QEMU uses SDL to display the VGA output. With this option, @@ -257,21 +308,69 @@ available screen space. This makes the u available screen space. This makes the using QEMU in a dedicated desktop workspace more convenient. [EMAIL PROTECTED] -vnc display [EMAIL PROTECTED] -full-screen +Start in full screen. + [EMAIL PROTECTED] -vnc display[,option[,option[,...]]] Normally, QEMU uses SDL to display the VGA output. With this option, you can have QEMU listen on VNC display @var{display} and redirect the VGA display over the VNC session. It is very useful to enable the usb tablet device when using this option (option @option{-usbdevice tablet}). When using the VNC display, you must use the @option{-k} -option to set the keyboard layout if you are not using en-us. - [EMAIL PROTECTED] may be in the form @var{interface:d}, in which case connections -will only be allowed from @var{interface} on display @var{d}. Optionally, [EMAIL PROTECTED] can be omitted. @var{display} can also be in the form [EMAIL PROTECTED]:path} where @var{path} is the location of a unix socket to listen for -connections on. - +option to set the keyboard layout if you are not using en-us. Available +options for @var{display} are + [EMAIL PROTECTED] @code + [EMAIL PROTECTED] @var{interface:d} + +TCP connections will only be allowed from @var{interface} on display @var{d}. +By convention the TCP port is [EMAIL PROTECTED] Optionally, @var{interface} can +be omitted in which case the server will bind to all interfaces. + [EMAIL PROTECTED] @var{unix:path} + +Connections will be allowed over UNIX domain sockets where @var{path} is the +location of a unix socket to listen for connections on. + [EMAIL PROTECTED] @var{none} + +VNC is initialized by not started. The monitor @code{change} command can be used +to later start the VNC server. + [EMAIL PROTECTED] table + +Following the @var{display} value there may be one or more @var{option} flags +separated by commas. Valid options are + [EMAIL PROTECTED] @code + [EMAIL PROTECTED] @var{tls} + +Require that client use TLS when communicating with the VNC server. This +uses anonymous TLS credentials so is susceptible to a man-in-the-middle +attack. It is recommended that this option be combined with either the [EMAIL PROTECTED] or @var{x509verify} options. + [EMAIL PROTECTED] @var{x509} + +Valid if @var{tls} is specified. Require that x509 credentials are used +for negotiating the TLS session. The server will send its x509 certificate +to the client. It is recommended that a password be set on the VNC server +to provide authentication of the client when this is used. + [EMAIL PROTECTED] @var{x509verify} + +Valid if @var{tls} is specified. Require that x509 credentials are used +for negotiating the TLS session. The server will send its x509 certificate +to the client, and request that the client send its own x509 certificate. +The server will validate the client's certificate against the CA certificate, +and reject clients when validation fails. If the certificate authority is +trusted, this is a sufficient authentication mechanism. You may still wish +to set a password on the VNC server as a second authentication layer. + [EMAIL PROTECTED] table @item -k language @@ -290,53 +389,32 @@ de en-us fi fr-be hr it lv nl- The default is @code{en-us}. [EMAIL PROTECTED] -audio-help - -Will show the audio subsystem help: list of drivers, tunable -parameters. - [EMAIL PROTECTED] -soundhw card1,card2,... or -soundhw all - -Enable audio and selected sound hardware. Use ? to print all -available sound hardware. - [EMAIL PROTECTED] -qemu -soundhw sb16,adlib hda -qemu -soundhw es1370 hda -qemu -soundhw all hda -qemu -soundhw ? [EMAIL PROTECTED] example - [EMAIL PROTECTED] -localtime -Set the real time clock to local time (the default is to UTC -time). This option is needed to have correct date in MS-DOS or -Windows. - [EMAIL PROTECTED] -full-screen -Start in full screen. - [EMAIL PROTECTED] -pidfile file -Store the QEMU process PID in @var{file}. It is useful if you launch QEMU -from a script. - [EMAIL PROTECTED] -daemonize -Daemonize the QEMU process after initialization. QEMU will not detach from -standard IO until it is ready to receive connections on any of its devices. -This option is a useful way for external programs to launch QEMU without having -to cope with initialization race conditions. - [EMAIL PROTECTED] -win2k-hack -Use it when installing Windows 2000 to avoid a disk full bug. After -Windows 2000 is installed, you no longer need this option (this option -slows down the IDE transfers). - [EMAIL PROTECTED] -option-rom file -Load the contents of file as an option ROM. This option is useful to load -things like EtherBoot. - [EMAIL PROTECTED] -name string -Sets the name of the guest. This name will be display in the SDL window -caption. The name will also be used for the VNC server. [EMAIL PROTECTED] -x509cacert filename + +Specify the path to the CA certificate stored in PEM format. This +parameter is mandatory if using the @var{x509} or @var{x509} options +with the VNC server. See the @ref{vnc_security} section for details +on generating certificates. + [EMAIL PROTECTED] -x509cacrl filename + +Specify the path to the CA certificate revocation list stored in PEM +format. This parameter is optional. See the @ref{vnc_security} section +for details on generating certificates. + [EMAIL PROTECTED] -x509cert filename + +Specify the path to the server certificate stored in PEM format.. +This parameter is mandatory if using the @var{x509} or @var{x509} +options with the VNC server. See the @ref{vnc_security} section +for details on generating certificates. + [EMAIL PROTECTED] -x509key filename + +Specify the path to the server private key stored in PEM format. +This parameter is mandatory if using the @var{x509} or @var{x509} +options with the VNC server. See the @ref{vnc_security} section +for details on generating certificates. @end table @@ -862,8 +940,23 @@ Quit the emulator. @item eject [-f] device Eject a removable medium (use -f to force it). [EMAIL PROTECTED] change device filename -Change a removable medium. [EMAIL PROTECTED] change device setting + +Change the configuration of a device + [EMAIL PROTECTED] @option [EMAIL PROTECTED] change diskdevice filename +Change the medium for a removable disk device to point to @var{filename} + [EMAIL PROTECTED] change vnc display,options +Change the configuration of the VNC server. The valid syntax for @var{display} +and @var{options} are described at @ref{sec_invocation}. When using this command +it will prompt for a password to be entered. This is the password that clients +will use to authenticate with the VNC server. If no passwd is desired, simply +hit 'enter' without typing any characters. VNC passwords are only significant +upto 8 letters. + [EMAIL PROTECTED] table @item screendump filename Save screen into PPM image @var{filename}. @@ -1421,6 +1514,222 @@ When relaunching QEMU, you may have to u When relaunching QEMU, you may have to unplug and plug again the USB device to make it work again (this is a bug). [EMAIL PROTECTED] vnc_security [EMAIL PROTECTED] VNC security + +The VNC server capability provides access to the graphical console +of the guest VM across the network. This has a number of security +considerations depending on the deployment scenarios. + [EMAIL PROTECTED] +* vnc_sec_none:: +* vnc_sec_password:: +* vnc_sec_certificate:: +* vnc_sec_certificate_verify:: +* vnc_sec_certificate_pw:: +* vnc_generate_cert:: [EMAIL PROTECTED] menu [EMAIL PROTECTED] vnc_sec_none [EMAIL PROTECTED] Without passwords + +The simplest VNC server setup does not include any form of authentication. +For this setup it is recommended to restrict it to listen on a UNIX domain +socket only. For example + [EMAIL PROTECTED] +qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc [EMAIL PROTECTED] example + +This ensures that only users on local box with read/write access to that +path can access the VNC server. To securely access the VNC server from a +remote machine, a combination of netcat+ssh can be used to provide a secure +tunnel. + [EMAIL PROTECTED] vnc_sec_password [EMAIL PROTECTED] With passwords + +The VNC protocol has limited support for password based authentication. Since +the protocol limits passwords to 8 characters it should not be considered +to provide high security. The password can be fairly easily brute-forced by +a client making repeat connections. For this reason, a VNC server using password +authentication should be restricted to only listen on the loopback interface +or UNIX domain sockets. The password can be set by passing '-vnc none' on the +command line and then using the QEMU monitor: + [EMAIL PROTECTED] +qemu [...OPTIONS...] -vnc none -monitor stdio +(qemu) change vnc :1 +Password: ******** +(qemu) [EMAIL PROTECTED] example + [EMAIL PROTECTED] vnc_sec_certificate [EMAIL PROTECTED] With x509 certificates + +The QEMU VNC server also implements the VeNCrypt extension allowing use of +TLS for encryption of the session, and x509 certificates for authentication. +The use of x509 certificates is strongly recommended, because TLS on its +own is susceptible to man-in-the-middle attacks. Basic x509 certificate +support provides a secure session, but no authentication. This allows any +client to connect, and provides an encrypted session. + [EMAIL PROTECTED] +qemu [...OPTIONS...] -vnc :1,tls,x509 -monitor stdio \ + -x509cacert /etc/pki/CA/cacert.pem \ + -x509cert /etc/pki/qemu/servercert.pem \ + -x509key /etc/pki/qemu/private/serverkey.pem [EMAIL PROTECTED] example + +In the above example @code{/etc/pki} can be replaced with @code{$HOME/.pki} +if running as a non-root user. NB the @code{serverkey.pem} should be protected +to only be readable by the user owning it. + [EMAIL PROTECTED] vnc_sec_certificate_verify [EMAIL PROTECTED] With x509 certificates and client verification + +Certificates can also provide a means to authenticate the client connecting. +The server will request that the client provide a certificate, which it will +then validate against the CA certificate. This is a good choice if deploying +in an environment with a private internal certificate authority. + [EMAIL PROTECTED] +qemu [...OPTIONS...] -vnc tls,x509verify -monitor stdio \ + -x509cacert /etc/pki/CA/cacert.pem \ + -x509cert /etc/pki/qemu/servercert.pem \ + -x509key /etc/pki/qemu/private/serverkey.pem [EMAIL PROTECTED] example + + [EMAIL PROTECTED] vnc_sec_certificate_pw [EMAIL PROTECTED] With x509 certificates, client verification and passwords + +Finally, the previous method can be combined with VNC password authentication +to provide two layers of authentication for clients. + [EMAIL PROTECTED] +qemu [...OPTIONS...] -vnc none -monitor stdio \ + -x509cacert /etc/pki/CA/cacert.pem \ + -x509cert /etc/pki/qemu/servercert.pem \ + -x509key /etc/pki/qemu/private/serverkey.pem +(qemu) change vnc,tls,x509verify :1 +Password: ******** +(qemu) [EMAIL PROTECTED] example + [EMAIL PROTECTED] vnc_generate_cert [EMAIL PROTECTED] Generating certificates for VNC + +The GNU TLS packages provides a command called @code{certtool} which can +be used to generate certificates and keys in PEM format. At a minimum it +is neccessary to setup a certificate authority, and issue certificates to +each server. If using certificates for authentication, then each client +will also need to be issued a certificate. + [EMAIL PROTECTED] +* vnc_generate_ca:: +* vnc_generate_server:: +* vnc_generate_client:: [EMAIL PROTECTED] menu [EMAIL PROTECTED] vnc_generate_ca [EMAIL PROTECTED] Setup the Certificate Authority + +This step only needs to be performed once per organization / organizational +unit. First the CA needs a private key. This key must be kept VERY secret +and secure. If this key is compromised the entire trust chain of the certificates +issued with it is lost. + [EMAIL PROTECTED] +# certtool --generate-privkey > cakey.pem [EMAIL PROTECTED] example + +A CA needs to have a public certificate. For simplicity it can be a self-signed +certificate, or one issue by a commercial certificate issuing authority. To +generate a self-signed certificate requires one core piece of information, the +name of the organization. + [EMAIL PROTECTED] +# cat > ca.info <<EOF +cn = Name of your organization +ca +cert_signing_key +EOF +# certtool --generate-self-signed \ + --load-privkey cakey.pem + --template ca.info \ + --outfile cacert.pem [EMAIL PROTECTED] example + +The cacert.pem file should be copied to all servers and clients wishing to utilize +TLS support in the VNC server. By convention CA certificates are kept in /etc/pki +or $HOME/.pki + [EMAIL PROTECTED] vnc_generate_server [EMAIL PROTECTED] Issuing server certificates + +Each server (or host) needs to be issued with a key and certificate. When connecting +the certificate is sent to the client which validates it against the CA certificate. +The core piece of information for a server certificate is the hostname. This should +be the fully qualified hostname that the client will connect with, since the client +will typically also verify the hostname in the certificate. On the host holding the +secure CA private key: + [EMAIL PROTECTED] +# cat > server.info <<EOF +organization = Name of your organization +cn = server.foo.example.com +tls_www_server +encryption_key +signing_key +EOF +# certtool --generate-privkey > serverkey.pem +# certtool --generate-certificate \ + --load-ca-certificate cacert.pem \ + --load-ca-privkey cakey.pem \ + --load-privkey server serverkey.pem \ + --template server.info \ + --outfile servercert.pem [EMAIL PROTECTED] example + +The @code{serverkey.pem} and @code{servercert.pem} files should now be securely copied +to the server for which they were generated. By convention they are kept in [EMAIL PROTECTED]/etc/pki/qemu/servercert.pem} and @code{/etc/pki/qemu/private/serverkey.pem}, or +the equivalent per user directory @code{$HOME/.pki}. + [EMAIL PROTECTED] vnc_generate_client [EMAIL PROTECTED] Issuing client certificates + +If the QEMU VNC server is to use the @code{x509verify} option to validate client +certificates as its authentication mechanism, each client also needs to be issued +a certificate. The client certificate contains enough metadata to uniquely identify +the client, typically organization, state, city, building, etc. On the host holding +the secure CA private key: + [EMAIL PROTECTED] +# cat > client.info <<EOF +country = GB +state = London +locality = London +organiazation = Name of your organization +cn = client.foo.example.com +tls_www_client +encryption_key +signing_key +EOF +# certtool --generate-privkey > clientkey.pem +# certtool --generate-certificate \ + --load-ca-certificate cacert.pem \ + --load-ca-privkey cakey.pem \ + --load-privkey server clientkey.pem \ + --template client.info \ + --outfile clientcert.pem [EMAIL PROTECTED] example + +The @code{clientkey.pem} and @code{clientcert.pem} files should now be securely copied +to the client for which they were generated. By convention they are kept in [EMAIL PROTECTED]/etc/pki/qemu/clientcert.pem} and @code{/etc/pki/qemu/private/clientkey.pem}, or +the equivalent per user directory @code{$HOME/.pki}. + + @node gdb_usage @section GDB usage -- |=- Red Hat, Engineering, Emerging Technologies, Boston. +1 978 392 2496 -=| |=- Perl modules: http://search.cpan.org/~danberr/ -=| |=- Projects: http://freshmeat.net/~danielpb/ -=| |=- GnuPG: 7D3B9505 F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 -=|