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

OPTIONS

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

HOTKEY

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

CONNECTION FILE

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

CONFIGURATION

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

EXAMPLES

311       To connect to SPICE server on host "makai" with port 5900
312
313          remote-viewer spice://makai:5900
314
315       To connect to VNC server on host "tsingy" with port 5900
316
317          remote-viewer vnc://tsingy:5900
318
319       To connect to a virtual machine named "toliara" on an oVirt server at
320       example.org
321
322          remote-viewer ovirt://[username@]example.org/toliara
323

BUGS

325       Report bugs to the mailing list
326       "http://www.redhat.com/mailman/listinfo/virt-tools-list"
327
329       Copyright (C) 2012-2014 Red Hat, Inc., and various contributors.  This
330       is free software. You may redistribute copies of it under the terms of
331       the GNU General Public License
332       "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
333       the extent permitted by law.
334

SEE ALSO

336       "virt-viewer(1)", "spice-client(1)", the project website
337       "http://virt-manager.org"
338
339
340
341perl v5.16.3                      2018-11-02                  REMOTE-VIEWER(1)
Impressum