1REMOTE-VIEWER(1)            Virtualization Support            REMOTE-VIEWER(1)
2
3
4

NAME

6       remote-viewer - a simple remote desktop client
7

SYNOPSIS

9       remote-viewer [OPTIONS] -- [URI]
10

DESCRIPTION

12       remote-viewer is a simple remote display client. The supported
13       protocols are SPICE and VNC.
14
15       Starting remote-viewer without URI will open a simple dialog with an
16       entry and a list of previously successfully accessed URI.
17
18       The URI can also point to a connection settings file, see the
19       CONNECTION FILE section for a description of the format.
20
21       If URI is '-', then remote-viewer will read the standard input as a
22       connection settings file and attempt to connect using it.
23

OPTIONS

25       The following options are accepted when running "remote-viewer":
26
27       -h, --help
28           Display command line help summary
29
30       -V, --version
31           Display program version number
32
33       -v, --verbose
34           Display information about the connection
35
36       -z PCT, --zoom=PCT
37           Zoom level of the display window in percentage. Range 10-400.
38
39       -f, --full-screen
40           Start with the windows maximized to fullscreen.
41
42           If supported, the remote display will be reconfigured to match the
43           physical client monitor configuration, by enabling or disabling
44           extra monitors as necessary. This is currently implemented by the
45           Spice backend only.
46
47           To specify which client monitors are used in fullscreen mode, see
48           the CONFIGURATION section below.
49
50       -t TITLE, --title TITLE
51           Set the window title to TITLE
52
53       --debug
54           Print debugging information
55
56       -H HOTKEYS, --hotkeys HOTKEYS
57           Set global hotkey bindings. By default, keyboard shortcuts only
58           work when the guest display widget does not have focus.  Any
59           actions specified in HOTKEYS will be effective even when the guest
60           display widget has input focus. The format for HOTKEYS is
61           <action1>=<key1>[+<key2>][,<action2>=<key3>[+<key4>]].  Key-names
62           are case-insensitive. Valid actions are: toggle-fullscreen,
63           release-cursor, secure-attention, smartcard-insert and smartcard-
64           remove.  The "secure-attention" action sends a secure attention
65           sequence (Ctrl+Alt+Del) to the guest. Examples:
66
67             --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
68
69             --hotkeys=release-cursor=ctrl+alt
70
71           Note that hotkeys for which no binding is given are disabled.
72           Although the hotkeys specified here are handled by the client, it
73           is still possible to send these key combinations to the guest via a
74           menu item.
75
76       -k, --kiosk
77           Start in kiosk mode. In this mode, the application will start in
78           fullscreen with minimal UI. It will prevent the user from quitting
79           or performing any interaction outside of usage of the remote
80           desktop session.
81
82           Note that it can't offer a complete secure solution by itself. Your
83           kiosk system must have additional configuration and security
84           settings to lock down the OS. In particular, you must configure or
85           disable the window manager, limit the session capabilities, use
86           some restart/watchdog mechanism, disable VT switching etc.
87
88       --kiosk-quit <never|on-disconnect>
89           By default, when kiosk mode is enabled, virt-viewer will remain
90           open when the connection to the remote server is terminated. By
91           setting kiosk-quit option to "on-disconnect" value, virt-viewer
92           will quit instead.
93

HOTKEY

95       A key binding combination is described by a series of key strings
96       separated by '+' that must be pressed together in order to activate the
97       associated action.
98
99       It must be composed of modifiers (shift, ctrl or alt) and a non-
100       modifier key. For example, "shift+f11".
101

CONNECTION FILE

103       remote-viewer connection file is of INI file format, with a mandatory
104       [virt-viewer] group and "type" key.
105
106   Example
107       Opening a file with the following content will start remote-viewer in
108       fullscreen and connect to the host "betsiboka" using the SPICE
109       protocol:
110
111        [virt-viewer]
112        type=spice
113        host=betsiboka
114        port=5900
115        fullscreen=1
116
117   Key list
118       "version" (string)
119           If remote-viewer version number isn't greater or equal to the
120           required version, an error is raised with the expected version.
121
122           The version format accepted is a list of integers separated by '.'.
123           It can be followed by a dash '-' and an additional build number
124           with the same format.
125
126           Version comparison is done by comparing each integer from the list
127           one by one. If any of the component is not a number, the version
128           comparison will fail and consider that the 2 versions are
129           considered to be the same.
130
131       "versions" (osid:version list)
132           This is a list of osid:version couples separated by ';'. osid is an
133           arbitrary string, version is a version number in the same format as
134           in the 'version' field. A given couple indicates that remote-viewer
135           builds matching the given 'osid' (fedora22, debian7, ...) must be
136           at least version 'version'. For consistency, it's recommended to
137           use libosinfo OS shortids as the osid.
138
139       "newer-version-url" (string)
140           If specified, this field is an URL which will be displayed to the
141           user when a version check fails.
142
143       "type" (string, mandatory)
144           The session type, either "spice", "vnc" or "ovirt".
145
146       "unix-path" (string)
147           The server to connect to, using a Unix socket path. (supported with
148           spice, since 8.0)
149
150           This option is incompatible with "host", "port" and "tls-port".
151
152       "host" (string)
153           The server host to connect to.
154
155       "port" (integer)
156           The server port to connect to.
157
158       "tls-port" (integer)
159           The server TLS/SSL port to connect to.
160
161       "username" (string)
162           The username for the session authentication.
163
164       "password" (string)
165           The password for the session authentication.
166
167       "disable-channels" (string list)
168           The list of session channels to disable.
169
170           The current SPICE channels are: main, display, inputs, cursor,
171           playback, record, smartcard, usbredir.
172
173       "tls-ciphers" (string)
174           Set the cipher list to use for the secure connection, in textual
175           OpenSSL cipher list format. (see ciphers(1))
176
177       "title" (string)
178           String to present in the window title.
179
180       "fullscreen" (boolean)
181           Opens the client windows in fullscreen.
182
183       "ca" (string)
184           CA certificate in PEM format (using "\n" to separate the lines).
185           This will be used to verify the SSL certificate used for SPICE TLS
186           sessions.
187
188       "host-subject" (string)
189           Verify the certificate subject matches with the given subject.
190
191       "toggle-fullscreen" (hotkey string)
192           Key binding for entering and leaving fullscreen mode. (see HOTKEY
193           for description of expected string)
194
195       "release-cursor" (hotkey string)
196           Key binding for releasing cursor grab. (see HOTKEY for description
197           of expected string)
198
199       "smartcard-insert" (hotkey string)
200           Key binding for inserting emulated smartcard. (see HOTKEY for
201           description of expected string)
202
203       "smartcard-remove" (hotkey string)
204           Key binding for removing emulated smartcard. (see HOTKEY for
205           description of expected string)
206
207       "color-depth" (integer)
208           Set the color depth of the guest display (16 or 32).
209
210       "disable-effects" (string list)
211           A list of desktop effects to disable in the remote guest.
212
213           The effects that can be disabled with SPICE are: wallpaper, font-
214           smooth, animation or all.
215
216       "enable-smartcard" (boolean)
217           Set to 1 to enable client smartcard redirection.
218
219       "enable-usbredir" (boolean)
220           Set to 1 to enable client USB device redirection.
221
222       "enable-usb-autoshare" (boolean)
223           Set to 1 to enable client USB devices auto-sharing.
224
225       "usb-filter" (string)
226           Set a string specifying a filter to use to determine which USB
227           devices to autoconnect when plugged in, a filter consists of one or
228           more rules. Where each rule has the form of:
229
230           "class,vendor,product,version,allow"
231
232           Use -1 for class/vendor/product/version to accept any value.
233
234           And the rules themselves are concatenated like this:
235
236           "rule1|rule2|rule3"
237
238       "secure-channels" (string list)
239           The list of session channels to secure.
240
241           The current SPICE channels are: main, display, inputs, cursor,
242           playback, record, smartcard, usbredir.
243
244       "delete-this-file" (boolean)
245           Set to 1 for the client to remove this connection file (if it
246           can't, it will fail silently)
247
248       "proxy" (string)
249           A proxy URL to tunnel the connection through.
250
251           At the time of writing this documentation, the only supported proxy
252           method with Spice is HTTP CONNECT.
253
254           For example, to tunnel connection through foobar host HTTP proxy on
255           port 8080, use the value "http://foobar:8080".
256
257   oVirt Support
258       The connection file can also carry some oVirt-specific options when
259       oVirt support is compiled in. These options are used to interact with
260       oVirt REST API.  This is currently only used in order to show a menu
261       allowing to change the CD image being used by the virtual machine from
262       remote-viewer user interface.  These options go in an optional [ovirt]
263       group.
264
265       "host" (string, mandatory)
266           The oVirt instance to connect to. This corresponds to the hostname
267           one would connect to access the oVirt user or admin portal.
268
269       "vm-guid" (string, mandatory)
270           GUID of the oVirt virtual machine to connect to.
271
272       "jsessionid" (string)
273           Value to set the 'jsessionid' cookie to. With oVirt 3.6, setting
274           this authentication cookie to a valid value will allow to interact
275           with the oVirt REST API without being asked for credentials.
276
277       "sso-token" (string)
278           Value to set the 'Authorization' header to. With oVirt 4.0 or
279           newer, setting this authentication header to a valid value will
280           allow to interact with the oVirt REST API without being asked for
281           credentials.
282
283       "ca" (string)
284           CA certificate in PEM format (using "\n" to separate the lines).
285           This will be used to validate the certificate used for the oVirt
286           REST https session remote-viewer will establish.
287

CONFIGURATION

289       A small number of configuration options can be controlled by editing
290       the settings file located in the user configuration directory:
291
292           <USER-CONFIG-DIR>/virt-viewer/settings
293
294       This file is a text file in INI format, with application options in the
295       [virt-viewer] group and per-guest options in a group identified by the
296       guest's UUID. The application options should not be edited manually.
297       There is also a special [fallback] group which specifies options for
298       all guests that don't have an explicit group.
299
300       For each guest, the initial fullscreen monitor configuration can be
301       specified by using the monitor-mapping key. This configuration only
302       takes effect when the -f/--full-screen option is specified.
303
304       The value of this key is a list of mappings between a guest display and
305       a client monitor. Each mapping is separated by a semicolon character,
306       and the mappings have the format
307       <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
308
309       For example, to map guest displays 1 and 2 to client monitors 2 and 3
310       for the guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
311
312           [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
313           monitor-mapping=1:2;2:3
314
315       The monitor-mapping must contain ids of all displays from 1 to the last
316       desired display id, e.g. "monitor-mapping=3:3" is invalid because
317       mappings for displays 1 and 2 are not specified.
318

EXAMPLES

320       To connect to SPICE server on host "makai" with port 5900
321
322          remote-viewer spice://makai:5900
323
324       To connect to VNC server on host "tsingy" with port 5900
325
326          remote-viewer vnc://tsingy:5900
327
328       To connect to a virtual machine named "toliara" on an oVirt server at
329       example.org
330
331          remote-viewer ovirt://[username@]example.org/toliara
332

BUGS

334       Report bugs to the mailing list
335       "http://www.redhat.com/mailman/listinfo/virt-tools-list"
336
338       Copyright (C) 2012-2014 Red Hat, Inc., and various contributors.  This
339       is free software. You may redistribute copies of it under the terms of
340       the GNU General Public License
341       "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
342       the extent permitted by law.
343

SEE ALSO

345       "virt-viewer(1)", "spice-client(1)", the project website
346       "http://virt-manager.org"
347
348
349
350perl v5.28.1                      2018-12-21                  REMOTE-VIEWER(1)
Impressum