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 --spice-controller
51 Use the SPICE controller to initialize the connection with the
52 SPICE server. This option is used by the SPICE browser addons to
53 allow web page to start a client.
54 --debug
56 Print debugging information
57 -H HOTKEYS, --hotkeys HOTKEYS
59 Set global hotkey bindings. By default, keyboard shortcuts only
60 work when the guest display widget does not have focus. Any
61 actions specified in HOTKEYS will be effective even when the guest
62 display widget has input focus. The format for HOTKEYS is
63 <action1>=<key1>[+<key2>][,<action2>=<key3>[+<key4>]]. Key-names
64 are case-insensitive. Valid actions are: toggle-fullscreen,
65 release-cursor, secure-attention, smartcard-insert and smartcard-
66 remove. The "secure-attention" action sends a secure attention
67 sequence (Ctrl+Alt+Del) to the guest. Examples:
68 --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
70 --hotkeys=release-cursor=ctrl+alt
72 Note that hotkeys for which no binding is given are disabled.
74 Although the hotkeys specified here are handled by the client, it
75 is still possible to send these key combinations to the guest via a
76 menu item.
77 -k, --kiosk
79 Start in kiosk mode. In this mode, the application will start in
80 fullscreen with minimal UI. It will prevent the user from quitting
81 or performing any interaction outside of usage of the remote
82 desktop session.
83 Note that it can't offer a complete secure solution by itself. Your
85 kiosk system must have additional configuration and security
86 settings to lock down the OS. In particular, you must configure or
87 disable the window manager, limit the session capabilities, use
88 some restart/watchdog mechanism, disable VT switching etc.
89 --kiosk-quit <never|on-disconnect>
91 By default, when kiosk mode is enabled, virt-viewer will remain
92 open when the connection to the remote server is terminated. By
93 setting kiosk-quit option to "on-disconnect" value, virt-viewer
94 will quit instead.
95
97 A key binding combination is described by a series of key strings
98 separated by '+' that must be pressed together in order to activate the
99 associated action.
100 It must be composed of modifiers (shift, ctrl or alt) and a non-
102 modifier key. For example, "shift+f11".
103
105 remote-viewer connection file is of INI file format, with a mandatory
106 [virt-viewer] group and "type" key.
107 Example
109 Opening a file with the following content will start remote-viewer in
110 fullscreen and connect to the host "betsiboka" using the SPICE
111 protocol:
112 [virt-viewer]
114 type=spice
115 host=betsiboka
116 port=5900
117 fullscreen=1
118 Key list
120 "version" (string)
121 If remote-viewer version number isn't greater or equal to the
122 required version, an error is raised with the expected version.
123 The version format accepted is a list of integers separated by '.'.
125 It can be followed by a dash '-' and an additional build number
126 with the same format.
127 Version comparison is done by comparing each integer from the list
129 one by one. If any of the component is not a number, the version
130 comparison will fail and consider that the 2 versions are
131 considered to be the same.
132 "versions" (osid:version list)
134 This is a list of osid:version couples separated by ';'. osid is an
135 arbitrary string, version is a version number in the same format as
136 in the 'version' field. A given couple indicates that remote-viewer
137 builds matching the given 'osid' (fedora22, debian7, ...) must be
138 at least version 'version'. For consistency, it's recommended to
139 use libosinfo OS shortids as the osid.
140 "newer-version-url" (string)
142 If specified, this field is an URL which will be displayed to the
143 user when a version check fails.
144 "type" (string, mandatory)
146 The session type, either "spice", "vnc" or "ovirt".
147 "host" (string, mandatory)
149 The server host to connect to.
150 "port" (integer)
152 The server port to connect to.
153 "tls-port" (integer)
155 The server TLS/SSL port to connect to.
156 "username" (string)
158 The username for the session authentication.
159 "password" (string)
161 The password for the session authentication.
162 "disable-channels" (string list)
164 The list of session channels to disable.
165 The current SPICE channels are: main, display, inputs, cursor,
167 playback, record, smartcard, usbredir.
168 "tls-ciphers" (string)
170 Set the cipher list to use for the secure connection, in textual
171 OpenSSL cipher list format. (see ciphers(1))
172 "title" (string)
174 String to present in the window title.
175 "fullscreen" (boolean)
177 Opens the client windows in fullscreen.
178 "ca" (string)
180 CA certificate in PEM format (using "\n" to separate the lines).
181 This will be used to verify the SSL certificate used for SPICE TLS
182 sessions.
183 "host-subject" (string)
185 Verify the certificate subject matches with the given subject.
186 "toggle-fullscreen" (hotkey string)
188 Key binding for entering and leaving fullscreen mode. (see HOTKEY
189 for description of expected string)
190 "release-cursor" (hotkey string)
192 Key binding for releasing cursor grab. (see HOTKEY for description
193 of expected string)
194 "smartcard-insert" (hotkey string)
196 Key binding for inserting emulated smartcard. (see HOTKEY for
197 description of expected string)
198 "smartcard-remove" (hotkey string)
200 Key binding for removing emulated smartcard. (see HOTKEY for
201 description of expected string)
202 "color-depth" (integer)
204 Set the color depth of the guest display (16 or 32).
205 "disable-effects" (string list)
207 A list of desktop effects to disable in the remote guest.
208 The effects that can be disabled with SPICE are: wallpaper, font-
210 smooth, animation or all.
211 "enable-smartcard" (boolean)
213 Set to 1 to enable client smartcard redirection.
214 "enable-usbredir" (boolean)
216 Set to 1 to enable client USB device redirection.
217 "enable-usb-autoshare" (boolean)
219 Set to 1 to enable client USB devices auto-sharing.
220 "usb-filter" (string)
222 Set a string specifying a filter to use to determine which USB
223 devices to autoconnect when plugged in, a filter consists of one or
224 more rules. Where each rule has the form of:
225 "class,vendor,product,version,allow"
227 Use -1 for class/vendor/product/version to accept any value.
229 And the rules themselves are concatenated like this:
231 "rule1|rule2|rule3"
233 "secure-channels" (string list)
235 The list of session channels to secure.
236 The current SPICE channels are: main, display, inputs, cursor,
238 playback, record, smartcard, usbredir.
239 "delete-this-file" (boolean)
241 Set to 1 for the client to remove this connection file (if it
242 can't, it will fail silently)
243 "proxy" (string)
245 A proxy URL to tunnel the connection through.
246 At the time of writing this documentation, the only supported proxy
248 method with Spice is HTTP CONNECT.
249 For example, to tunnel connection through foobar host HTTP proxy on
251 port 8080, use the value "http://foobar:8080".
252 oVirt Support
254 The connection file can also carry some oVirt-specific options when
255 oVirt support is compiled in. These options are used to interact with
256 oVirt REST API. This is currently only used in order to show a menu
257 allowing to change the CD image being used by the virtual machine from
258 remote-viewer user interface. These options go in an optional [ovirt]
259 group.
260 "host" (string, mandatory)
262 The oVirt instance to connect to. This corresponds to the hostname
263 one would connect to access the oVirt user or admin portal.
264 "vm-guid" (string, mandatory)
266 GUID of the oVirt virtual machine to connect to.
267 "jsessionid" (string)
269 Value to set the 'jsessionid' cookie to. Setting this
270 authentication cookie to a valid value will allow to interact with
271 the oVirt REST API without being asked for credentials.
272 "ca" (string)
274 CA certificate in PEM format (using "\n" to separate the lines).
275 This will be used to validate the certificate used for the oVirt
276 REST https session remote-viewer will establish.
277
279 A small number of configuration options can be controlled by editing
280 the settings file located in the user configuration directory:
281 <USER-CONFIG-DIR>/virt-viewer/settings
283 This file is a text file in INI format, with application options in the
285 [virt-viewer] group and per-guest options in a group identified by the
286 guest's UUID. The application options should not be edited manually.
287 There is also a special [fallback] group which specifies options for
288 all guests that don't have an explicit group.
289 For each guest, the initial fullscreen monitor configuration can be
291 specified by using the monitor-mapping key. This configuration only
292 takes effect when the -f/--full-screen option is specified.
293 The value of this key is a list of mappings between a guest display and
295 a client monitor. Each mapping is separated by a semicolon character,
296 and the mappings have the format
297 <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
298 For example, to map guest displays 1 and 2 to client monitors 2 and 3
300 for the guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
301 [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
303 monitor-mapping=1:2;2:3
304
306 To connect to SPICE server on host "makai" with port 5900
307 remote-viewer spice://makai:5900
309 To connect to VNC server on host "tsingy" with port 5900
311 remote-viewer vnc://tsingy:5900
313 To connect to a virtual machine named "toliara" on an oVirt server at
315 example.org
316 remote-viewer ovirt://[username@]example.org/toliara
318
320 Report bugs to the mailing list
321 "http://www.redhat.com/mailman/listinfo/virt-tools-list"
322
324 Copyright (C) 2012-2014 Red Hat, Inc., and various contributors. This
325 is free software. You may redistribute copies of it under the terms of
326 the GNU General Public License
327 "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
328 the extent permitted by law.
329
331 "virt-viewer(1)", the project website "http://virt-manager.org"
332perl v5.10.1 2017-03-23 REMOTE-VIEWER(1)