[Spice-devel,qxl,v2] spiceqxl: Improve the Xspice and Xorg configuration option descriptions

Submitted by Francois Gouget on Dec. 8, 2016, 8:15 a.m.

Details

Message ID E1cEtrv-0003uw-Gq@amboise
State New
Headers show
Series "spiceqxl: Improve the Xspice and Xorg configuration option descriptions" ( rev: 2 ) in Spice

Not browsing as part of any series.

Commit Message

Francois Gouget Dec. 8, 2016, 8:15 a.m.
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@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(-)

Patch hide | download patch | download mbox

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" ""

Comments

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@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@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/spice-devel