1REMOTE-VIEWER(1) Virtualization Support REMOTE-VIEWER(1)
2
6 remote-viewer - a simple remote desktop client
7
9 remote-viewer [OPTIONS] -- [URI]
10
12 remote-viewer is a simple remote display client. The supported
13 protocols are SPICE and VNC.
14 Starting remote-viewer without URI will open a simple dialog with an
16 entry and a list of previously successfully accessed URI.
17 The URI can also point to a connection settings file, see the
19 CONNECTION FILE section for a description of the format.
20
22 The following options are accepted when running "remote-viewer":
23 -h, --help
25 Display command line help summary
26 -V, --version
28 Display program version number
29 -v, --verbose
31 Display information about the connection
32 -z PCT, --zoom=PCT
34 Zoom level of the display window in percentage. Range 10-400.
35 -f, --full-screen
37 Start with the windows maximized to fullscreen.
38 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 To specify which client monitors are used in fullscreen mode, see
45 the CONFIGURATION section below.
46 -t TITLE, --title TITLE
48 Set the window title to TITLE
49 --debug
51 Print debugging information
52 -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 --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
65 --hotkeys=release-cursor=ctrl+alt
67 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 -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 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 --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
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 It must be composed of modifiers (shift, ctrl or alt) and a non-
97 modifier key. For example, "shift+f11".
98
100 remote-viewer connection file is of INI file format, with a mandatory
101 [virt-viewer] group and "type" key.
102 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 [virt-viewer]
109 type=spice
110 host=betsiboka
111 port=5900
112 fullscreen=1
113 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 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 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 "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 "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 "type" (string, mandatory)
141 The session type, either "spice", "vnc" or "ovirt".
142 "host" (string, mandatory)
144 The server host to connect to.
145 "port" (integer)
147 The server port to connect to.
148 "tls-port" (integer)
150 The server TLS/SSL port to connect to.
151 "username" (string)
153 The username for the session authentication.
154 "password" (string)
156 The password for the session authentication.
157 "disable-channels" (string list)
159 The list of session channels to disable.
160 The current SPICE channels are: main, display, inputs, cursor,
162 playback, record, smartcard, usbredir.
163 "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 "title" (string)
169 String to present in the window title.
170 "fullscreen" (boolean)
172 Opens the client windows in fullscreen.
173 "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 "host-subject" (string)
180 Verify the certificate subject matches with the given subject.
181 "toggle-fullscreen" (hotkey string)
183 Key binding for entering and leaving fullscreen mode. (see HOTKEY
184 for description of expected string)
185 "release-cursor" (hotkey string)
187 Key binding for releasing cursor grab. (see HOTKEY for description
188 of expected string)
189 "smartcard-insert" (hotkey string)
191 Key binding for inserting emulated smartcard. (see HOTKEY for
192 description of expected string)
193 "smartcard-remove" (hotkey string)
195 Key binding for removing emulated smartcard. (see HOTKEY for
196 description of expected string)
197 "color-depth" (integer)
199 Set the color depth of the guest display (16 or 32).
200 "disable-effects" (string list)
202 A list of desktop effects to disable in the remote guest.
203 The effects that can be disabled with SPICE are: wallpaper, font-
205 smooth, animation or all.
206 "enable-smartcard" (boolean)
208 Set to 1 to enable client smartcard redirection.
209 "enable-usbredir" (boolean)
211 Set to 1 to enable client USB device redirection.
212 "enable-usb-autoshare" (boolean)
214 Set to 1 to enable client USB devices auto-sharing.
215 "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 "class,vendor,product,version,allow"
222 Use -1 for class/vendor/product/version to accept any value.
224 And the rules themselves are concatenated like this:
226 "rule1|rule2|rule3"
228 "secure-channels" (string list)
230 The list of session channels to secure.
231 The current SPICE channels are: main, display, inputs, cursor,
233 playback, record, smartcard, usbredir.
234 "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 "proxy" (string)
240 A proxy URL to tunnel the connection through.
241 At the time of writing this documentation, the only supported proxy
243 method with Spice is HTTP CONNECT.
244 For example, to tunnel connection through foobar host HTTP proxy on
246 port 8080, use the value "http://foobar:8080".
247 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 "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 "vm-guid" (string, mandatory)
261 GUID of the oVirt virtual machine to connect to.
262 "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 "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 "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
280 A small number of configuration options can be controlled by editing
281 the settings file located in the user configuration directory:
282 <USER-CONFIG-DIR>/virt-viewer/settings
284 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 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 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 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 [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
304 monitor-mapping=1:2;2:3
305 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
311 To connect to SPICE server on host "makai" with port 5900
312 remote-viewer spice://makai:5900
314 To connect to VNC server on host "tsingy" with port 5900
316 remote-viewer vnc://tsingy:5900
318 To connect to a virtual machine named "toliara" on an oVirt server at
320 example.org
321 remote-viewer ovirt://[username@]example.org/toliara
323
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
336 "virt-viewer(1)", "spice-client(1)", the project website
337 "http://virt-manager.org"
338perl v5.16.3 2018-11-02 REMOTE-VIEWER(1)