[Spice-devel] [qxl v2] spiceqxl: Improve the Xspice and Xorg configuration option descriptions
Christophe Fergeau
cfergeau at redhat.com
Mon Dec 12 16:58:01 UTC 2016
Hey,
I've pushed this one with a few small changes: I've moved the 'sasl'
option together with the password/disable-ticketing ones, and I've
channged some 'sets'/'specifies' to 'set'/'specify' for consistency.
Christophe
On Thu, Dec 08, 2016 at 09:15:55AM +0100, Francois Gouget wrote:
> Group the options more logically and improve their descriptions.
> Add the missing help strings for Xspice --help and standardize the
> messages to start with a lowercase and not end with a period.
> In the Xorg configuration, always show the default in the
> commented-out sample.
>
> Signed-off-by: Francois Gouget <fgouget at codeweavers.com>
> ---
>
> Here's the new Xspice --help output:
>
> usage: Xspice [Xspice and Xorg options intermixed]
>
> X and Spice server. example usage: Xspice --port 5900
> --disable-ticketing :1.0
>
> optional arguments:
> -h, --help show this help message and exit
> --xorg XORG specifies the path to the Xorg binary
> --config CONFIG specifies the path to the Xspice configuration
> --auto automatically create a temporary xorg.conf and start
> the X server
> --xsession XSESSION if given, will run after Xorg launch. Should be a
> program like x-session-manager
> --disable-ticketing do not require a client password
> --password PASSWORD set the password required to connect to the server
> --port PORT use the specified port as Spice's regular unencrypted
> port
> --tls-port TLS_PORT use the specified port as a TLS (encrypted) port
> --sasl use SASL to authenticate to the server
> --x509-dir X509_DIR set the directory where the CA certificate, server key
> and server certificate are searched for TLS, using the
> same predefined names QEMU uses
> --cacert-file CACERT_FILE
> set the CA certificate file location for TLS
> --x509-key-file X509_KEY_FILE
> set the server key file location for TLS
> --x509-key-password X509_KEY_PASSWORD
> set the server key's password for TLS
> --x509-cert-file X509_CERT_FILE
> set the server certificate file location for TLS
> --dh-file DH_FILE set the server DH file location for TLS
> --tls-ciphers TLS_CIPHERS
> set the TLS ciphers preference order
> --ipv4-only only accept IP v4 connections
> --ipv6-only only accept IP v6 connections
> --exit-on-disconnect exit the X server when any client disconnects
> --numheads NUMHEADS number of virtual heads to create
> --jpeg-wan-compression {auto,never,always}
> set jpeg wan compression
> --zlib-glz-wan-compression {auto,never,always}
> set zlib glz wan compressions
> --image-compression {off,auto_glz,auto_lz,quic,glz,lz}
> set image compression
> --deferred-fps DEFERRED_FPS
> if non zero, the driver will render all operations to
> the frame buffer, and keep track of a changed
> rectangle list. The changed rectangles will be
> transmitted at the rate requested (e.g. 10 frames per
> second). This can dramatically reduce network
> bandwidth for some use cases
> --streaming-video {off,all,filter}
> set the streaming video method
> --video-codecs VIDEO_CODECS
> sets a semicolon-separated list of preferred video
> codecs to use. Each takes the form encoder:codec, with
> spice:mjpeg being the default and other options being
> provided by gstreamer for the mjpeg, vp8 and h264
> codecs
> --vdagent launch vdagent & vdagentd. They provide clipboard &
> resolution automation
> --vdagent-virtio-path VDAGENT_VIRTIO_PATH
> virtio socket path used by vdagentd
> --vdagent-uinput-path VDAGENT_UINPUT_PATH
> uinput socket path used by vdagent
> --vdagent-udcs-path VDAGENT_UDCS_PATH
> Unix domain socket path used by vdagent and vdagentd
> --vdagentd-exec VDAGENTD_EXEC
> path to spice-vdagentd (used with --vdagent)
> --vdagent-exec VDAGENT_EXEC
> path to spice-vdagent (used with --vdagent)
> --vdagent-no-launch do not launch vdagent & vdagentd, used for debugging
> or if some external script wants to take care of that
> --vdagent-uid VDAGENT_UID
> set vdagent user id. changing it makes sense only in
> conjunction with --vdagent-no-launch
> --vdagent-gid VDAGENT_GID
> set vdagent group id. changing it makes sense only in
> conjunction with --vdagent-no-launch
> --audio-fifo-dir AUDIO_FIFO_DIR
> if a directory is given, any file in that directory
> will be read for audio data to be sent to the client.
> This is designed to work with PulseAudio's module-
> pipe-sink
>
> Any option not parsed by Xspice gets passed to Xorg as is.
>
>
> examples/spiceqxl.xorg.conf.example | 183 +++++++++++++++++++-----------------
> scripts/Xspice | 74 ++++++++-------
> 2 files changed, 141 insertions(+), 116 deletions(-)
>
> diff --git a/examples/spiceqxl.xorg.conf.example b/examples/spiceqxl.xorg.conf.example
> index b6f4840..5feeb09 100644
> --- a/examples/spiceqxl.xorg.conf.example
> +++ b/examples/spiceqxl.xorg.conf.example
> @@ -2,111 +2,126 @@ Section "Device"
> Identifier "XSPICE"
> Driver "spiceqxl"
>
> - # Enable regular port. Either this or SpiceTlsPort, or one of XSPICE_PORT or
> - # XSPICE_TLS_PORT environment variables must be specified
> + # ---- Network and security options
> +
> + # Do not require a client password.
> + # default: False
> + #Option "SpiceDisableTicketing" "False"
> +
> + # Set the password required to connect to the Spice server.
> + #Option "SpicePassword" ""
> +
> + # Use Spice's regular unencrypted port. One of SpicePort or SpiceTlsPort
> + # must be specified. SpicePort can also be set through the XSPICE_PORT
> + # environment variable or the --port Xspice option.
> # Specify 0 to disable the use of the regular port
> # default: 5900
> #Option "SpicePort" "5900"
>
> - # Enable a TLS (encrypted) port. Either this or SpicePort must be specified,
> - # either here or via environment varialbes or via xspice --port or --tls-port
> - #Option "SpiceTlsPort" "5901"
> -
> - # Listen to a specific interface. Default is to listen to all (0.0.0.0)
> - #Option "SpiceAddr" ""
> + # Use a TLS (encrypted) port. One of SpicePort or SpiceTlsPort must be
> + # specified. SpiceTlsPort can also be set through the XSPICE_TLS_PORT
> + # environment variable or the --tls-port Xspice option.
> + #Option "SpiceTlsPort" "5900"
>
> - # Enable usage of SASL supported by spice-gtk client. Not required,
> + # Enable usage of SASL supported by the spice-gtk client. Not required,
> # default: False
> - #Option "SpiceSasl" "True"
> + #Option "SpiceSasl" "False"
>
> - # Do not request any password from client
> - #Option "SpiceDisableTicketing" "0"
> -
> - # Set directory where cacert, server key and server cert are searched
> - # using the same predefined names qemu uses:
> + # Set the directory where the CA certificate, server key and server
> + # certificate are searched for TLS, using the same predefined names QEMU
> + # uses:
> # cacert.pem, server-key.pem, server-cert.pem
> #Option "SpiceX509Dir" ""
>
> - # Set password client will be required to produce.
> - #Option "SpicePassword" ""
> + # Set the CA certificate file location for TLS.
> + #Option "SpiceCacertFile" ""
>
> - # Set spice server key file.
> + # Set the server key file location for TLS.
> #Option "SpiceX509KeyFile" ""
>
> - # Set cert file location.
> + # Set the server key's password for TLS.
> + #Option "SpiceX509KeyPassword" ""
> +
> + # Set the server certificate file location for TLS.
> #Option "SpiceX509CertFile" ""
>
> - # Set key file password.
> - #Option "SpiceX509KeyPassword" ""
> + # Set the server DH file location for TLS.
> + #Option "SpiceDhFile" ""
>
> - # Set tls ciphers used.
> + # Set the TLS ciphers preference order.
> #Option "SpiceTlsCiphers" ""
>
> - # Set cacert file.
> - #Option "SpiceCacertFile" ""
> + # Listen to a specific interface.
> + # default: Listen to all (0.0.0.0).
> + #Option "SpiceAddr" ""
>
> - # Set dh file used.
> - #Option "SpiceDhFile" ""
> + # Set to True to only listen on IPv4 interfaces.
> + # default: False
> + #Option "SpiceIPV4Only" "False"
>
> - # Set streaming video method. Options are filter, off, all
> - # default: filter
> - #Option "SpiceStreamingVideo" ""
> + # Set to True to only listen on IPv6 interfaces.
> + # default: False
> + #Option "SpiceIPV6Only" "False"
>
> - # Set video codecs to use. Provide a semicolon list of
> - # codecs, in preference order. Each codec requires an encoder
> - # which can be one of spice or gstreamer, and then a codec type,
> - # for instance mjpeg or vp8. The default is spice:mjpeg,
> - # which uses the builtin mjpeg encoder.
> - #Option "SpiceVideoCodecs" ""
> + # If set, the Spice server will exit when the first client disconnects.
> + # default: False
> + #Option "SpiceExitOnDisconnect" "True"
> +
> +
> + # ---- Monitor configuration options
> +
> + # The number of heads to allocate by default.
> + # default: 4
> + #Option "NumHeads" "4"
> +
> +
> + # ---- Compression options
>
> # Set zlib glz wan compression. Options are auto, never, always.
> # default: auto
> #Option "SpiceZlibGlzWanCompression" ""
>
> - # Set jpeg wan compression. Options are auto, never, always
> + # Set jpeg wan compression. Options are auto, never, always.
> # default: auto
> #Option "SpiceJpegWanCompression" ""
>
> - # Set image compression. Options are off,auto_glz,auto_lz,quic,glz,lz.
> + # Set image compression. Options are off, auto_glz, auto_lz, quic, glz, lz.
> # default: auto_glz
> #Option "SpiceImageCompression" ""
>
> - # Set to true to only listen on ipv4 interfaces.
> - # default: False
> - #Option "SpiceIPV4Only" ""
> -
> - # Set to true to only listen on ipv6 interfaces.
> - # default: False
> - #Option "SpiceIPV6Only" ""
> -
> # If non zero, the driver will render all operations to the frame buffer,
> - # and keep track of a changed rectangle list. The changed rectangles
> - # will be transmitted at the rate requested (e.g. 10 Frames Per Second)
> + # and keep track of a changed rectangle list. The changed rectangles
> + # will be transmitted at the rate requested (e.g. 10 frames per second).
> # This can dramatically reduce network bandwidth for some use cases.
> #Option "SpiceDeferredFPS" "10"
>
> - # If set, the Spice Server will exit when the first client disconnects
> - #Option "SpiceExitOnDisconnect" "1"
> + # Set the streaming video method. Options are filter, off, all.
> + # default: filter
> + #Option "SpiceStreamingVideo" ""
> +
> + # Sets a semicolon-separated list of preferred video codecs.
> + # Each takes the form encoder:codec, with spice:mjpeg being the default,
> + # and other options being provided by gstreamer for the mjpeg, vp8 and h264
> + # codecs.
> + #Option "SpiceVideoCodecs" ""
>
> - # Enable caching of images directly written with uxa->put_image
> + # Enable caching of images directly written with uxa->put_image.
> # default: True
> #Option "EnableImageCache" "True"
>
> - # Enable caching of images created by uxa->prepare_access
> + # Enable caching of images created by uxa->prepare_access.
> # default: True
> #Option "EnableFallbackCache" "True"
>
> - # Enable the use of off screen srufaces
> + # Enable the use of off-screen surfaces.
> # default: True
> #Option "EnableSurfaces" "True"
>
> - # The number of heads to allocate by default
> - # default: 4
> - #Option "NumHeads" "4"
>
> - #--------------------------------------------------------------
> + # ---- Xspice-specific buffer options
> +
> # Buffer Size notes:
> - # The following buffer sizes are used for Xspice only
> + # The following buffer sizes are used for Xspice only.
> # If you are using the DFPS mode, surface ram is not used,
> # and you can set it to 1.
> # Otherwise, the surface buffer should be at least as large
> @@ -117,13 +132,12 @@ Section "Device"
> # is a command buffer 7x the size of the frame buffer.
> # If you see 'Out of memory' errors in your xorg.log, you probably need
> # to increase the surface or command buffer sizes.
> - #--------------------------------------------------------------
>
> - # The amount of surface buffer ram, in megabytes, to allocate
> + # The amount of surface buffer ram, in megabytes, to allocate.
> # default: 128
> #Option "SurfaceBufferSize" "128"
>
> - # The amount of command buffer ram, in megabytes, to allocate
> + # The amount of command buffer ram, in megabytes, to allocate.
> # default: 128
> #Option "CommandBufferSize" "128"
>
> @@ -134,51 +148,52 @@ Section "Device"
> # default: 16
> #Option "FrameBufferSize" "16"
>
> - # Whether or not to accept Vdagent connections
> +
> + # ---- VDAgent options
> +
> + # Whether or not to accept Vdagent connections.
> # default: False
> #Option "SpiceVdagentEnabled" "False"
>
> - # Default path to listen for agent virtual io connections
> - # default: /tmp/xspice-virtio"
> + # Default path to listen for agent virtual io connections.
> + # default: /tmp/xspice-virtio"
> #Option "SpiceVdagentVirtioPath" "/tmp/xspice-virtio"
>
> - # Default path to listen for agent uinput connections
> - # default: /tmp/xspice-uinput
> + # Default path to listen for agent uinput connections.
> + # default: /tmp/xspice-uinput
> #Option "SpiceVdagentUinputPath" "/tmp/xspice-uinput"
>
> - # Default user id to set for the Virtio and Uinput sockets
> - # default: 0, or none
> - # Note: both uid and gid must be given for either to take
> - # effect
> + # Default user id to set for the Virtio and Uinput sockets.
> + # Note: both uid and gid must be given for either to take effect.
> + # default: 0, or none
> #Option "SpiceVdagentUid" "0"
>
> - # Default group id to set for the Virtio and Uinput sockets
> - # default: 0, or none
> - # Note: both uid and gid must be given for either to take
> - # effect
> + # Default group id to set for the Virtio and Uinput sockets.
> + # Note: both uid and gid must be given for either to take effect.
> + # default: 0, or none
> #Option "SpiceVdagentGid" "0"
>
> - # Set Spice Agent Mouse - Use Agent mouse if an agent connects
> + # Set Spice Agent Mouse - Use Agent mouse if an agent connects.
> # default: True
> #Option "SpiceAgentMouse" "True"
>
> - # Set Spice Playback compression
> + # Set Spice Playback compression.
> # default: True
> #Option "SpicePlaybackCompression" "True"
>
> - # Disable copy and paste
> + # Disable copy and paste.
> # default: False
> #Option "SpiceDisableCopyPaste" "False"
>
> - # If a directory is given, any file in that
> - # directory will be read for audio data to be sent
> - # to the client. Default is no mixing.
> - #Option "SpicePlaybackFIFODir" "/tmp/"
> + # If a directory is given, any file in that directory will be read
> + # for audio data to be sent to the client.
> + # default: Not set.
> + #Option "SpicePlaybackFIFODir" "/tmp/"
>
> - # A unix domain name for a unix domain socket
> - # to communicate with a spiceccid smartcard driver
> - # Default is not to use a smartcard driver.
> - #Option "SpiceSmartCardFile" "/tmp/spice.pcsc.comm"
> + # A unix domain name for a unix domain socket to communicate with
> + # a spiceccid smartcard driver.
> + # default: Not set.
> + #Option "SpiceSmartCardFile" "/tmp/spice.pcsc.comm"
> EndSection
>
> Section "InputDevice"
> diff --git a/scripts/Xspice b/scripts/Xspice
> index bf8112f..9f61d2a 100755
> --- a/scripts/Xspice
> +++ b/scripts/Xspice
> @@ -52,54 +52,64 @@ wan_compression_options = ['auto', 'never', 'always']
> parser = argparse.ArgumentParser("Xspice",
> description="X and Spice server. example usage: Xspice --port 5900 --disable-ticketing :1.0",
> usage="Xspice [Xspice and Xorg options intermixed]",
> - epilog="Any options not parsed by Xspice get passed to Xorg as is.")
> -parser.add_argument('--xorg', default=which('Xorg'))
> -parser.add_argument('--auto', action='store_true', help='Automatically create a temporary xorg.conf and start the X server')
> -parser.add_argument('--xsession', help='If given, will run after Xorg launch. Should be a program like x-session-manager')
> -parser.add_argument('--config', default='spiceqxl.xorg.conf')
> + epilog="Any option not parsed by Xspice gets passed to Xorg as is.")
> +
> +# X-related options
> +parser.add_argument('--xorg', default=which('Xorg'), help='specifies the path to the Xorg binary')
> +parser.add_argument('--config', default='spiceqxl.xorg.conf', help='specifies the path to the Xspice configuration')
> +parser.add_argument('--auto', action='store_true', help='automatically create a temporary xorg.conf and start the X server')
> +parser.add_argument('--xsession', help='if given, will run after Xorg launch. Should be a program like x-session-manager')
> +
> +# Network and security options
> +add_boolean('--disable-ticketing', help="do not require a client password")
> +parser.add_argument('--password', help="set the password required to connect to the server")
> # Don't use any options that are already used by Xorg (unless we must)
> # specifically, don't use -p and -s.
> -parser.add_argument('--port', type=int, help='standard spice port')
> -parser.add_argument('--exit-on-disconnect', action='store_true', help='Exit the X server when any client disconnects')
> -parser.add_argument('--numheads', type=int, help='Number of virtual heads to create.')
> -parser.add_argument('--deferred-fps', type=int, help='If given, render to a buffer and send updates only this many times per second')
> -parser.add_argument('--tls-port', type=int, help='spice tls port', default=0)
> -add_boolean('--disable-ticketing', help="do not require a client password")
> -add_boolean('--sasl', help="enable sasl")
> -parser.add_argument('--x509-dir', help="x509 directory for tls")
> -parser.add_argument('--cacert-file', help="ca certificate file for tls")
> -parser.add_argument('--x509-cert-file', help="server certificate file for tls")
> -parser.add_argument('--x509-key-file', help="server key file for tls")
> -parser.add_argument('--x509-key-password', help="key file password for tls")
> -parser.add_argument('--tls-ciphers')
> -parser.add_argument('--dh-file')
> -parser.add_argument('--password', help="set password required to connect to server")
> -parser.add_argument('--image-compression',
> - choices = ['off', 'auto_glz', 'auto_lz', 'quic',
> - 'glz', 'lz'],
> - help='auto_glz by default')
> +parser.add_argument('--port', type=int, help="use the specified port as Spice's regular unencrypted port")
> +parser.add_argument('--tls-port', type=int, help='use the specified port as a TLS (encrypted) port', default=0)
> +add_boolean('--sasl', help="use SASL to authenticate to the server")
> +parser.add_argument('--x509-dir', help="set the directory where the CA certificate, server key and server certificate are searched for TLS, using the same predefined names QEMU uses")
> +parser.add_argument('--cacert-file', help="set the CA certificate file location for TLS")
> +parser.add_argument('--x509-key-file', help="set the server key file location for TLS")
> +parser.add_argument('--x509-key-password', help="set the server key's password for TLS")
> +parser.add_argument('--x509-cert-file', help="set the server certificate file location for TLS")
> +parser.add_argument('--dh-file', help="set the server DH file location for TLS")
> +parser.add_argument('--tls-ciphers', help="set the TLS ciphers preference order")
> +add_boolean('--ipv4-only', help="only accept IP v4 connections")
> +add_boolean('--ipv6-only', help="only accept IP v6 connections")
> +parser.add_argument('--exit-on-disconnect', action='store_true', help='exit the X server when any client disconnects')
> +
> +# Monitor configuration options
> +parser.add_argument('--numheads', type=int, help='number of virtual heads to create')
> +
> +# Compression options
> parser.add_argument('--jpeg-wan-compression',
> choices=wan_compression_options,
> - help='auto by default')
> + help="set jpeg wan compression")
> parser.add_argument('--zlib-glz-wan-compression',
> choices=wan_compression_options,
> - help='auto by default')
> + help="set zlib glz wan compressions")
> +parser.add_argument('--image-compression',
> + choices = ['off', 'auto_glz', 'auto_lz', 'quic',
> + 'glz', 'lz'],
> + help="set image compression")
> +parser.add_argument('--deferred-fps', type=int, help='if non zero, the driver will render all operations to the frame buffer, and keep track of a changed rectangle list. The changed rectangles will be transmitted at the rate requested (e.g. 10 frames per second). This can dramatically reduce network bandwidth for some use cases')
> # TODO - sound support
> parser.add_argument('--streaming-video', choices=['off', 'all', 'filter'],
> - help='filter by default')
> -parser.add_argument('--video-codecs', help="Sets a semicolon-separated list of preferred video codecs to use. Each takes the form encoder:codec, with spice:mjpeg being the default and other options being provided by gstreamer for the mjpeg, vp8 and h264 codecs.")
> -add_boolean('--ipv4-only')
> -add_boolean('--ipv6-only')
> + help='set the streaming video method')
> +parser.add_argument('--video-codecs', help='sets a semicolon-separated list of preferred video codecs to use. Each takes the form encoder:codec, with spice:mjpeg being the default and other options being provided by gstreamer for the mjpeg, vp8 and h264 codecs')
> +
> +# VDAgent options
> parser.add_argument('--vdagent', action='store_true', dest='vdagent_enabled', default=False, help='launch vdagent & vdagentd. They provide clipboard & resolution automation')
> parser.add_argument('--vdagent-virtio-path', help='virtio socket path used by vdagentd')
> parser.add_argument('--vdagent-uinput-path', help='uinput socket path used by vdagent')
> -parser.add_argument('--vdagent-udcs-path', help='udcs socket path used by vdagent and vdagentd')
> +parser.add_argument('--vdagent-udcs-path', help='Unix domain socket path used by vdagent and vdagentd')
> parser.add_argument('--vdagentd-exec', help='path to spice-vdagentd (used with --vdagent)')
> parser.add_argument('--vdagent-exec', help='path to spice-vdagent (used with --vdagent)')
> parser.add_argument('--vdagent-no-launch', default=True, action='store_false', dest='vdagent_launch', help='do not launch vdagent & vdagentd, used for debugging or if some external script wants to take care of that')
> parser.add_argument('--vdagent-uid', default=str(os.getuid()), help='set vdagent user id. changing it makes sense only in conjunction with --vdagent-no-launch')
> parser.add_argument('--vdagent-gid', default=str(os.getgid()), help='set vdagent group id. changing it makes sense only in conjunction with --vdagent-no-launch')
> -parser.add_argument('--audio-fifo-dir', help="set fifo directory for playback audio. designed to work with PulseAudio's module-pipe-sink")
> +parser.add_argument('--audio-fifo-dir', help="if a directory is given, any file in that directory will be read for audio data to be sent to the client. This is designed to work with PulseAudio's module-pipe-sink")
>
> #TODO
> #Option "SpiceAddr" ""
> --
> 2.10.2
> _______________________________________________
> Spice-devel mailing list
> Spice-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/spice-devel
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/spice-devel/attachments/20161212/85802ae9/attachment-0001.sig>
More information about the Spice-devel
mailing list