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 If URI is '-', then remote-viewer will read the standard input as a
22 connection settings file and attempt to connect using it.
23 In some circumstances the viewer may need to grab the mouse pointer.
25 The default key sequence for releasing the grab is "Ctrl_L"+"Alt_L",
26 however, this can be overridden using the "--hotkeys" argument
27 documented below.
28
30 The following options are accepted when running "remote-viewer":
31 -h, --help
33 Display command line help summary
34 -V, --version
36 Display program version number
37 -v, --verbose
39 Display information about the connection
40 -z PCT, --zoom=PCT
42 Zoom level of the display window in percentage. Range 10-400.
43 -f, --full-screen
45 Start with the windows maximized to fullscreen.
46 If supported, the remote display will be reconfigured to match the
48 physical client monitor configuration, by enabling or disabling
49 extra monitors as necessary. This is currently implemented by the
50 Spice backend only and can be disabled by the "--auto-resize"
51 arguemnt.
52 To specify which client monitors are used in fullscreen mode, see
54 the CONFIGURATION section below.
55 --auto-resize <always|never>
57 Controls whether it is permitted to attempt to resize the remote
58 framebuffer to match the local window size. This currently defaults
59 to on, but note that not all servers will support this.
60 -t TITLE, --title TITLE
62 Set the window title to TITLE
63 -s, --shared
65 Permitted a shared session with multiple clients
66 --cursor auto|local
68 Control how the mouse cursor is rendered. "auto" is the default
69 behaviour, which will honour the behaviour requested by the remote
70 server. This may involve the server remote rendering the cursor
71 into the framebuffer, or sending the cursor details to the client
72 to render. "local" overrides this default to request that the
73 local desktop cursor is always rendered regardless of what the
74 server requests. The latter is rarely needed, but can be used if
75 the server has a bad configuration that results in its own cursor
76 being hidden.
77 --debug
79 Print debugging information
80 -H HOTKEYS, --hotkeys HOTKEYS
82 Set global hotkey bindings. By default, keyboard shortcuts only
83 work when the guest display widget does not have focus. Any
84 actions specified in HOTKEYS will be effective even when the guest
85 display widget has input focus. The format for HOTKEYS is
86 <action1>=<key1>[+<key2>][,<action2>=<key3>[+<key4>]]. Key-names
87 are case-insensitive. Valid actions are: toggle-fullscreen,
88 release-cursor, zoom-in, zoom-out, zoom-reset, secure-attention,
89 usb-device-reset, smartcard-insert and smartcard-remove. The
90 "secure-attention" action sends a secure attention sequence
91 (Ctrl+Alt+Del) to the guest. Examples:
92 --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
94 --hotkeys=release-cursor=ctrl+alt
96 Note that hotkeys for which no binding is given are disabled.
98 Although the hotkeys specified here are handled by the client, it
99 is still possible to send these key combinations to the guest via a
100 menu item.
101 -K, --keymap
103 Remap and/or block supplied keypresses to the host. All key
104 identifiers are case-sensitive and follow the naming convention as
105 defined in gdkkeysyms.h without the GDK_KEY_ prefix.
106 Running the application with --debug will display keypress symbols
108 in the following way:
109 "Key pressed was keycode='0x63', gdk_keyname='c'"
110 "Key pressed was keycode='0xffeb', gdk_keyname='Super_L'"
111 The format for supplying a keymap is:
113 <srcKeySym1>=[<destKeySym1>][+<destKeySym2][,<srckeySym2>=[<destKeySym1]
114 To block a keypress simply assign an empty parameter to the
116 srcKeySym.
117 Example:
119 --keymap=Super_L=,Alt_L=,1=Shift_L+F1,2=Shift_L+F2
120 This will block the Super_L (typically Windows Key) and ALT_L
122 keypresses and remap key 1 to Shift F1, 2 to Shift F2.
123 -k, --kiosk
125 Start in kiosk mode. In this mode, the application will start in
126 fullscreen with minimal UI. It will prevent the user from quitting
127 or performing any interaction outside of usage of the remote
128 desktop session.
129 Note that it can't offer a complete secure solution by itself. Your
131 kiosk system must have additional configuration and security
132 settings to lock down the OS. In particular, you must configure or
133 disable the window manager, limit the session capabilities, use
134 some restart/watchdog mechanism, disable VT switching etc.
135 --kiosk-quit <never|on-disconnect>
137 By default, when kiosk mode is enabled, virt-viewer will remain
138 open when the connection to the remote server is terminated. By
139 setting kiosk-quit option to "on-disconnect" value, virt-viewer
140 will quit instead.
141
143 A key binding combination is described by a series of key strings
144 separated by '+' that must be pressed together in order to activate the
145 associated action.
146 It must be composed of modifiers (shift, ctrl or alt) and a non-
148 modifier key. For example, "shift+f11".
149
151 remote-viewer connection file is of INI file format, with a mandatory
152 [virt-viewer] group and "type" key.
153 Example
155 Opening a file with the following content will start remote-viewer in
156 fullscreen and connect to the host "betsiboka" using the SPICE
157 protocol:
158 [virt-viewer]
160 type=spice
161 host=betsiboka
162 port=5900
163 fullscreen=1
164 Key list
166 "version" (string)
167 If remote-viewer version number isn't greater or equal to the
168 required version, an error is raised with the expected version.
169 The version format accepted is a list of integers separated by '.'.
171 It can be followed by a dash '-' and an additional build number
172 with the same format.
173 Version comparison is done by comparing each integer from the list
175 one by one. If any of the component is not a number, the version
176 comparison will fail and consider that the 2 versions are
177 considered to be the same.
178 "versions" (osid:version list)
180 This is a list of osid:version couples separated by ';'. osid is an
181 arbitrary string, version is a version number in the same format as
182 in the 'version' field. A given couple indicates that remote-viewer
183 builds matching the given 'osid' (fedora22, debian7, ...) must be
184 at least version 'version'. For consistency, it's recommended to
185 use libosinfo OS shortids as the osid.
186 "newer-version-url" (string)
188 If specified, this field is an URL which will be displayed to the
189 user when a version check fails.
190 "type" (string, mandatory)
192 The session type, either "spice", "vnc" or "ovirt".
193 "unix-path" (string)
195 The server to connect to, using a Unix socket path. (supported with
196 spice, since 8.0)
197 This option is incompatible with "host", "port" and "tls-port".
199 "host" (string)
201 The server host to connect to.
202 "port" (integer)
204 The server port to connect to.
205 "tls-port" (integer)
207 The server TLS/SSL port to connect to.
208 "username" (string)
210 The username for the session authentication.
211 "password" (string)
213 The password for the session authentication.
214 "disable-channels" (string list)
216 The list of session channels to disable.
217 The current SPICE channels are: main, display, inputs, cursor,
219 playback, record, smartcard, usbredir.
220 "tls-ciphers" (string)
222 Set the cipher list to use for the secure connection, in textual
223 OpenSSL cipher list format. (see ciphers(1))
224 "title" (string)
226 String to present in the window title.
227 "fullscreen" (boolean)
229 Opens the client windows in fullscreen.
230 "ca" (string)
232 CA certificate in PEM format (using "\n" to separate the lines).
233 This will be used to verify the SSL certificate used for SPICE TLS
234 sessions.
235 "host-subject" (string)
237 Verify the certificate subject matches with the given subject.
238 "toggle-fullscreen" (hotkey string)
240 Key binding for entering and leaving fullscreen mode. (see HOTKEY
241 for description of expected string)
242 "release-cursor" (hotkey string)
244 Key binding for releasing cursor grab. (see HOTKEY for description
245 of expected string)
246 "zoom-in" (hotkey string)
248 Key binding for zooming in and enlarging client window size. (see
249 HOTKEY for description of expected string)
250 "zoom-out" (hotkey string)
252 Key binding for zooming out and reducing client window size. (see
253 HOTKEY for description of expected string)
254 "zoom-reset" (hotkey string)
256 Key binding for reseting zoom and client window size. (see HOTKEY
257 for description of expected string)
258 "smartcard-insert" (hotkey string)
260 Key binding for inserting emulated smartcard. (see HOTKEY for
261 description of expected string)
262 "smartcard-remove" (hotkey string)
264 Key binding for removing emulated smartcard. (see HOTKEY for
265 description of expected string)
266 "color-depth" (integer)
268 Set the color depth of the guest display (16 or 32).
269 "disable-effects" (string list)
271 A list of desktop effects to disable in the remote guest.
272 The effects that can be disabled with SPICE are: wallpaper, font-
274 smooth, animation or all.
275 "enable-smartcard" (boolean)
277 Set to 1 to enable client smartcard redirection.
278 "enable-usbredir" (boolean)
280 Set to 1 to enable client USB device redirection.
281 "enable-usb-autoshare" (boolean)
283 Set to 1 to enable client USB devices auto-sharing.
284 "usb-filter" (string)
286 Set a string specifying a filter to use to determine which USB
287 devices to autoconnect when plugged in, a filter consists of one or
288 more rules. Where each rule has the form of:
289 "class,vendor,product,version,allow"
291 Use -1 for class/vendor/product/version to accept any value.
293 And the rules themselves are concatenated like this:
295 "rule1|rule2|rule3"
297 "secure-channels" (string list)
299 The list of session channels to secure.
300 The current SPICE channels are: main, display, inputs, cursor,
302 playback, record, smartcard, usbredir.
303 "delete-this-file" (boolean)
305 Set to 1 for the client to remove this connection file (if it
306 can't, it will fail silently)
307 "proxy" (string)
309 A proxy URL to tunnel the connection through.
310 At the time of writing this documentation, the only supported proxy
312 method with Spice is HTTP CONNECT.
313 For example, to tunnel connection through foobar host HTTP proxy on
315 port 8080, use the value "http://foobar:8080".
316 oVirt Support
318 The connection file can also carry some oVirt-specific options when
319 oVirt support is compiled in. These options are used to interact with
320 oVirt REST API. This is currently only used in order to show a menu
321 allowing to change the CD image being used by the virtual machine from
322 remote-viewer user interface. These options go in an optional [ovirt]
323 group.
324 "host" (string, mandatory)
326 The oVirt instance to connect to. This corresponds to the hostname
327 one would connect to access the oVirt user or admin portal.
328 "vm-guid" (string, mandatory)
330 GUID of the oVirt virtual machine to connect to.
331 "jsessionid" (string)
333 Value to set the 'jsessionid' cookie to. With oVirt 3.6, setting
334 this authentication cookie to a valid value will allow to interact
335 with the oVirt REST API without being asked for credentials.
336 "sso-token" (string)
338 Value to set the 'Authorization' header to. With oVirt 4.0 or
339 newer, setting this authentication header to a valid value will
340 allow to interact with the oVirt REST API without being asked for
341 credentials.
342 "ca" (string)
344 CA certificate in PEM format (using "\n" to separate the lines).
345 This will be used to validate the certificate used for the oVirt
346 REST https session remote-viewer will establish.
347
349 A small number of configuration options can be controlled by editing
350 the settings file located in the user configuration directory:
351 <USER-CONFIG-DIR>/virt-viewer/settings
353 This file is a text file in INI format, with application options in the
355 [virt-viewer] group and per-guest options in a group identified by the
356 guest's UUID. The application options should not be edited manually.
357 There is also a special [fallback] group which specifies options for
358 all guests that don't have an explicit group.
359 For each guest, the initial fullscreen monitor configuration can be
361 specified by using the monitor-mapping key. This configuration only
362 takes effect when the -f/--full-screen option is specified.
363 The value of this key is a list of mappings between a guest display and
365 a client monitor. Each mapping is separated by a semicolon character,
366 and the mappings have the format
367 <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
368 For example, to map guest displays 1 and 2 to client monitors 2 and 3
370 for the guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
371 [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
373 monitor-mapping=1:2;2:3
374 The monitor-mapping must contain ids of all displays from 1 to the last
376 desired display id, e.g. "monitor-mapping=3:3" is invalid because
377 mappings for displays 1 and 2 are not specified.
378 Configuration key share-clipboard contains a boolean value. If it's
380 "true", then clipboard is shared with guests if clipboard sharing is
381 supported by used protocol.
382
384 To connect to SPICE server on host "makai" with port 5900
385 remote-viewer spice://makai:5900
387 To connect to VNC server on host "tsingy" with port 5900
389 remote-viewer vnc://tsingy:5900
391 To connect to a virtual machine named "toliara" on an oVirt server at
393 example.org
394 remote-viewer ovirt://[username@]example.org/toliara
396
398 Report bugs to https://gitlab.com/virt-viewer/virt-viewer/-/issues
399
401 Copyright (C) 2012-2020 Red Hat, Inc., and various contributors. This
402 is free software. You may redistribute copies of it under the terms of
403 the GNU General Public License
404 "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
405 the extent permitted by law.
406
408 "virt-viewer(1)", "spice-client(1)", the project website
409 "http://gitlab.com/virt-viewer/virt-viewer"
410Virt-Viewer 11.0 2023-07-22 Remote-Viewer(1)