[Spice-devel] [spice-gtk v2] Add man page
Marc-André Lureau
marcandre.lureau at gmail.com
Fri Apr 4 06:10:15 PDT 2014
ack
On Fri, Apr 4, 2014 at 2:46 PM, Christophe Fergeau <cfergeau at redhat.com>wrote:
> Spice-GTK provides SPICE-specific command line options. This man page
> describes these options as well as the format of SPICE URIs.
> ---
> Changes since v1:
> - forgot to add man/Makefile.am + corresponding configure.ac change :)
>
>
> Makefile.am | 2 +-
> configure.ac | 1 +
> man/Makefile.am | 16 +++++
> man/spice-client.pod | 180
> +++++++++++++++++++++++++++++++++++++++++++++++++++
> 4 files changed, 198 insertions(+), 1 deletion(-)
> create mode 100644 man/Makefile.am
> create mode 100644 man/spice-client.pod
>
> diff --git a/Makefile.am b/Makefile.am
> index 8add19f..5029497 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -1,7 +1,7 @@
> ACLOCAL_AMFLAGS = -I m4
> NULL =
>
> -SUBDIRS = spice-common gtk po doc data
> +SUBDIRS = spice-common gtk man po doc data
>
> if BUILD_TESTS
> SUBDIRS += tests
> diff --git a/configure.ac b/configure.ac
> index 45417d2..d89bd6f 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -732,6 +732,7 @@ gtk/spice-version.h
> gtk/controller/Makefile
> doc/Makefile
> doc/reference/Makefile
> +man/Makefile
> vapi/Makefile
> tests/Makefile
> ])
> diff --git a/man/Makefile.am b/man/Makefile.am
> new file mode 100644
> index 0000000..cf288c7
> --- /dev/null
> +++ b/man/Makefile.am
> @@ -0,0 +1,16 @@
> +NULL =
> +
> +dist_man_MANS = \
> + spice-client.1 \
> + $(NULL)
> +
> +EXTRA_DIST = \
> + spice-client.pod \
> + $(NULL)
> +
> +MAINTAINERCLEANFILES = $(dist_man_MANS)
> +
> +%.1: %.pod
> + $(AM_V_GEN)pod2man $< > $@
> +
> +-include $(top_srcdir)/git.mk
> diff --git a/man/spice-client.pod b/man/spice-client.pod
> new file mode 100644
> index 0000000..1ad11e7
> --- /dev/null
> +++ b/man/spice-client.pod
> @@ -0,0 +1,180 @@
> +=head1 NAME
> +
> +Spice-GTK - a client-side library to access remote SPICE displays
> +
> +=head1 DESCRIPTION
> +
> +Spice-GTK is a library allowing to accesss remote displays. At the
> +moment It's mainly used to access remote virtual machines over the
> +SPICE protocol.
> +
> +The Spice-GTK library provides a set of command line options which
> +can be used to tweak how some SPICE-specific option.
> +
> +=head1 URI
> +
> +The most basic SPICE URI which can be used is in the form
> + spice://hostname.example.com:5900
> +
> +This will try to initiate a SPICE connection to hostname.example.com
> +to port 5900. This connection will be unencrypted. This URI is
> +equivalent to
> + spice://hostname.example.com?port=5900
> +
> +In order to start a TLS connection, one would use
> + spice://hostname.example.com?tls-port=5900
> +
> +Other valid URI parameters are 'username' and 'password'. Be careful that
> +passing a password through a SPICE URI might cause the password to be
> +visible by any local user through 'ps'.
> +
> +Several parameters can be specified at once if they are separated
> +by & or ;
> + spice://hostname.example.com?port=5900;tls-port=5901
> +
> +When using 'tls-port', it's recommended to not specify any non-TLS port.
> +If you give both 'port' and 'tls-port', make sure you use the
> +--spice-secure-channels options to indicate which channels must be secure.
> +Otherwise, Spice-GTK first attempts a connection to the non-TLS port, and
> +then try to use the TLS port. This means a man-in-the-middle could force
> +the whole SPICE session to go in clear text regardless of the TLS settings
> +of the SPICE server.
> +
> +=head1 OPTIONS
> +
> +The following options are accepted when running a SPICE client which
> +makes use of the default Spice-GTK options:
> +
> +=over 4
> +
> +=item --spice-secure-channels=<main,display,inputs,...,all>
> +
> +Force the specified channels to be secured
> +
> +This instructs the SPICE client that it must use a TLS connection for
> these
> +channels. If the server only offers non-TLS connections for these
> channels,
> +the client will not use these. If the special value "all" is used, this
> +indicates that all SPICE channels must be encrypted.
> +
> +=item --spice-disable-effects=<wallpaper,font-smooth,animation,all>
> +
> +Disable guest display effects
> +
> +This tells the SPICE client that it should attempt to disable some guest
> +features in order to lower bandwidth usage. This requires guest support,
> +usually through a SPICE agent. This is currently only supported on Windows
> +guests.
> +
> +"wallpaper" will disable the guest wallpaper, "font-smooth" will disable
> +font antialiasing, "animation" will try to disable some of the desktop
> +environment animations. "all" will attempt to disable everything which
> +can be disabled.
> +
> +=item --spice-color-depth=<16,32>
> +
> +Guest display color depth
> +
> +This tells the SPICE client that it should attempt to force the guest OS
> +color depth. A lower color depth should lower bandwith usage. This
> requires
> +guest support, usually through a SPICE agent. This is currently only
> +supported on Windows guests.
> +
> +=item --spice-ca-file=<file>
> +
> +Truststore file for secure connections
> +
> +This option is used to specify a .crt file containing the CA certificate
> with which
> +the SPICE server TLS certificates are signed. This is useful when using
> self-signed
> +TLS certificates rather than certificates signed by an official CA.
> +
> +
> +=item --spice-host-subject=<host-subject>
> +
> +Subject of the host certificate (field=value pairs separated by commas)
> +
> +When using self-signed certificates, or when the guest is migrated between
> +different hosts, the subject/altSubject of the TLS certificate the SPICE
> +server will provide will not necessarily match the hostname we are
> connecting to.
> +This option makes it possible to override the expected subject of the TLS
> certificate.
> +
> +The subject must correspond to the "Subject:" line returned by:
> + openssl x509 -noout -text -in server-cert.pem
> +
> +=item --spice-debug
> +
> +Enable Spice-GTK debugging. This can also be toggled on with the
> +SPICE_DEBUG environment variable, or using G_MESSAGES_DEBUG=all
> +
> +=item --spice-disable-audio
> +
> +Disable audio support
> +
> +=item --spice-disable-usbredir
> +
> +Disable USB redirection support
> +
> +=item --spice-usbredir-auto-redirect-filter=<filter-string>
> +
> +Filter selecting USB devices to be auto-redirected when plugged in
> +
> +=item --spice-usbredir-redirect-on-connect=<filter-string>
> +
> +Filter selecting USB devices to redirect on connect
> +
> +=item --spice-gtk-version
> +
> +Display Spice-GTK version information
> +
> +=item --spice-smartcard
> +
> +Enable smartcard support
> +
> +=item --spice-smartcard-db=<certificate-db>
> +
> +Path to the local certificate database to use for software smartcard
> certificates
> +
> +This option is only useful for testing purpose. Instead of having a
> hardware
> +smartcard reader, and a physical smartcard, you can specify a file
> containing 3
> +certificates which will be used to emulate a smartcard in software. See
> +C<
> http://www.spice-space.org/page/SmartcardUsage#Using_a_software_smartcard>
> +for more details about how to generate these certificates.
> +
> +=item --spice-smartcard-certificates=<certificates>
> +
> +Certificates to use for software smartcards (field=values separated by
> commas)
> +
> +This option is only useful for testing purpose. This allows to specify
> which
> +certificates from the certificate database specified with
> --spice-smartcard-db
> +should be used for smartcard emulation.
> +
> +=item --spice-cache-size=<bytes>
> +
> +Image cache size
> +
> +This option should only be used for testing/debugging.
> +
> +=item --spice-glz-window-size=<bytes>
> +
> +Glz compression history size
> +
> +This option should only be used for testing/debugging.
> +
> +=back
> +
> +=head1 BUGS
> +
> +Report bugs to the mailing list C<
> http://lists.freedesktop.org/mailman/listinfo/spice-devel>
> +
> +=head1 COPYRIGHT
> +
> +Copyright (C) 2011, 2014 Red Hat, Inc., and various contributors.
> +This is free software. You may redistribute copies of it under the terms
> of
> +the GNU Lesser General Public License
> +C<https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html>.
> +There is NO WARRANTY, to the extent permitted by law.
> +
> +=head1 SEE ALSO
> +
> +C<virt-viewer(1)>, the project website C<http://spice-space.org>
> +
> +=cut
> --
> 1.9.0
>
> _______________________________________________
> Spice-devel mailing list
> Spice-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/spice-devel
>
--
Marc-André Lureau
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/spice-devel/attachments/20140404/9152709e/attachment-0001.html>
More information about the Spice-devel
mailing list