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
25 The following options are accepted when running "remote-viewer":
26 -h, --help
28 Display command line help summary
29 -V, --version
31 Display program version number
32 -v, --verbose
34 Display information about the connection
35 -z PCT, --zoom=PCT
37 Zoom level of the display window in percentage. Range 10-400.
38 -f, --full-screen
40 Start with the windows maximized to fullscreen.
41 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 To specify which client monitors are used in fullscreen mode, see
48 the CONFIGURATION section below.
49 -t TITLE, --title TITLE
51 Set the window title to TITLE
52 --debug
54 Print debugging information
55 -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 --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
68 --hotkeys=release-cursor=ctrl+alt
70 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 -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 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 --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
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 It must be composed of modifiers (shift, ctrl or alt) and a non-
100 modifier key. For example, "shift+f11".
101
103 remote-viewer connection file is of INI file format, with a mandatory
104 [virt-viewer] group and "type" key.
105 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 [virt-viewer]
112 type=spice
113 host=betsiboka
114 port=5900
115 fullscreen=1
116 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 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 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 "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 "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 "type" (string, mandatory)
144 The session type, either "spice", "vnc" or "ovirt".
145 "unix-path" (string)
147 The server to connect to, using a Unix socket path. (supported with
148 spice, since 8.0)
149 This option is incompatible with "host", "port" and "tls-port".
151 "host" (string)
153 The server host to connect to.
154 "port" (integer)
156 The server port to connect to.
157 "tls-port" (integer)
159 The server TLS/SSL port to connect to.
160 "username" (string)
162 The username for the session authentication.
163 "password" (string)
165 The password for the session authentication.
166 "disable-channels" (string list)
168 The list of session channels to disable.
169 The current SPICE channels are: main, display, inputs, cursor,
171 playback, record, smartcard, usbredir.
172 "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 "title" (string)
178 String to present in the window title.
179 "fullscreen" (boolean)
181 Opens the client windows in fullscreen.
182 "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 "host-subject" (string)
189 Verify the certificate subject matches with the given subject.
190 "toggle-fullscreen" (hotkey string)
192 Key binding for entering and leaving fullscreen mode. (see HOTKEY
193 for description of expected string)
194 "release-cursor" (hotkey string)
196 Key binding for releasing cursor grab. (see HOTKEY for description
197 of expected string)
198 "smartcard-insert" (hotkey string)
200 Key binding for inserting emulated smartcard. (see HOTKEY for
201 description of expected string)
202 "smartcard-remove" (hotkey string)
204 Key binding for removing emulated smartcard. (see HOTKEY for
205 description of expected string)
206 "color-depth" (integer)
208 Set the color depth of the guest display (16 or 32).
209 "disable-effects" (string list)
211 A list of desktop effects to disable in the remote guest.
212 The effects that can be disabled with SPICE are: wallpaper, font-
214 smooth, animation or all.
215 "enable-smartcard" (boolean)
217 Set to 1 to enable client smartcard redirection.
218 "enable-usbredir" (boolean)
220 Set to 1 to enable client USB device redirection.
221 "enable-usb-autoshare" (boolean)
223 Set to 1 to enable client USB devices auto-sharing.
224 "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 "class,vendor,product,version,allow"
231 Use -1 for class/vendor/product/version to accept any value.
233 And the rules themselves are concatenated like this:
235 "rule1|rule2|rule3"
237 "secure-channels" (string list)
239 The list of session channels to secure.
240 The current SPICE channels are: main, display, inputs, cursor,
242 playback, record, smartcard, usbredir.
243 "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 "proxy" (string)
249 A proxy URL to tunnel the connection through.
250 At the time of writing this documentation, the only supported proxy
252 method with Spice is HTTP CONNECT.
253 For example, to tunnel connection through foobar host HTTP proxy on
255 port 8080, use the value "http://foobar:8080".
256 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 "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 "vm-guid" (string, mandatory)
270 GUID of the oVirt virtual machine to connect to.
271 "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 "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 "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
289 A small number of configuration options can be controlled by editing
290 the settings file located in the user configuration directory:
291 <USER-CONFIG-DIR>/virt-viewer/settings
293 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 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 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 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 [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
313 monitor-mapping=1:2;2:3
314 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 Configuration key share-clipboard contains a boolean value. If it's
320 "true", then clipboard is shared with guests if clipboard sharing is
321 supported by used protocol.
322
324 To connect to SPICE server on host "makai" with port 5900
325 remote-viewer spice://makai:5900
327 To connect to VNC server on host "tsingy" with port 5900
329 remote-viewer vnc://tsingy:5900
331 To connect to a virtual machine named "toliara" on an oVirt server at
333 example.org
334 remote-viewer ovirt://[username@]example.org/toliara
336
338 Report bugs to https://gitlab.com/virt-viewer/virt-viewer/-/issues
339
341 Copyright (C) 2012-2020 Red Hat, Inc., and various contributors. This
342 is free software. You may redistribute copies of it under the terms of
343 the GNU General Public License
344 "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
345 the extent permitted by law.
346
348 "virt-viewer(1)", "spice-client(1)", the project website
349 "http://gitlab.com/virt-viewer/virt-viewer"
350perl v5.30.2 2020-04-03 REMOTE-VIEWER(1)