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