1Virt-Viewer(1)              Virtualization Support              Virt-Viewer(1)
2
3
4

NAME

6       virt-viewer - display the graphical console for a virtual machine
7

SYNOPSIS

9       virt-viewer [OPTIONS] [ID|UUID|DOMAIN-NAME]
10

DESCRIPTION

12       virt-viewer is a minimal tool for displaying the graphical console of a
13       virtual machine. The console is accessed using the VNC or SPICE
14       protocol. The guest can be referred to based on its name, ID, or UUID.
15       If the guest is not already running, then the viewer can be told to
16       wait until it starts before attempting to connect to the console.  The
17       viewer can connect to remote hosts to lookup the console information
18       and then also connect to the remote console using the same network
19       transport.
20
21       In some circumstances the viewer may need to grab the mouse pointer.
22       The default key sequence for releasing the grab is "Ctrl_L"+"Alt_L",
23       however, this can be overridden using the "--hotkeys" argument
24       documented below.
25

OPTIONS

27       The following options are accepted when running "virt-viewer":
28
29       -h, --help
30           Display command line help summary
31
32       -V, --version
33           Display program version number
34
35       -v, --verbose
36           Display information about the connection
37
38       -c URI, --connect=URI
39           Specify the hypervisor connection URI
40
41       -w, --wait
42           Wait for the domain to start up before attempting to connect to the
43           console
44
45       -r, --reconnect
46           Automatically reconnect to the domain if it shuts down and restarts
47
48       -z PCT, --zoom=PCT
49           Zoom level of the display window in percentage. Range 10-400.
50
51       -d, --direct
52           Do not attempt to tunnel the console over SSH, even if the main
53           connection URI used SSH.
54
55       -a, --attach
56           Instead of making a direct TCP/UNIX socket connection to the remote
57           display, ask libvirt to provide a pre-connected socket for the
58           display. This avoids the need to authenticate with the remote
59           display server directly. This option will only work when connecting
60           to a guest that is running on the same host as the virt-viewer
61           program. If attaching to the guest via libvirt fails, virt-viewer
62           will automatically fallback to trying a regular direct TCP/UNIX
63           socket connection.
64
65       -f, --full-screen
66           Start with the window maximised to fullscreen
67
68           If supported, the remote display will be reconfigured to match the
69           physical client monitor configuration, by enabling or disabling
70           extra monitors as necessary. This is currently implemented by the
71           Spice backend only.
72
73           To specify which client monitors are used in fullscreen mode, see
74           the CONFIGURATION section below.
75
76       --auto-resize <always|never>
77           Controls whether it is permitted to attempt to resize the remote
78           framebuffer to match the local window size. This currently defaults
79           to on, but note that not all servers will support this.
80
81       -s, --shared
82           Permitted a shared session with multiple clients
83
84       --cursor auto|local
85           Control how the mouse cursor is rendered. "auto" is the default
86           behaviour, which will honour the behaviour requested by the remote
87           server. This may involve the server remote rendering the cursor
88           into the framebuffer, or sending the cursor details to the client
89           to render.  "local" overrides this default to request that the
90           local desktop cursor is always rendered regardless of what the
91           server requests. The latter is rarely needed, but can be used if
92           the server has a bad configuration that results in its own cursor
93           being hidden.
94
95       --debug
96           Print debugging information
97
98       -H HOTKEYS, --hotkeys HOTKEYS
99           Set global hotkey bindings. By default, keyboard shortcuts only
100           work when the guest display widget does not have focus.  Any
101           actions specified in HOTKEYS will be effective even when the guest
102           display widget has input focus. The format for HOTKEYS is
103           <action1>=<key1>[+<key2>][,<action2>=<key3>[+<key4>]].  Key-names
104           are case-insensitive. Valid actions are: toggle-fullscreen,
105           release-cursor, zoom-in, zoom-out, zoom-reset, secure-attention,
106           usb-device-reset, smartcard-insert and smartcard-remove.  The
107           "secure-attention" action sends a secure attention sequence
108           (Ctrl+Alt+Del) to the guest. Examples:
109
110             --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
111
112             --hotkeys=release-cursor=ctrl+alt
113
114           Note that hotkeys for which no binding is given are disabled.
115           Although the hotkeys specified here are handled by the client, it
116           is still possible to send these key combinations to the guest via a
117           menu item.
118
119       -K, --keymap
120           Remap and/or block supplied keypresses to the host. All key
121           identifiers are case-sensitive and follow the naming convention as
122           defined in gdkkeysyms.h without the GDK_KEY_ prefix.
123
124           Running the application with --debug will display keypress symbols
125           in the following way:
126             "Key pressed was keycode='0x63', gdk_keyname='c'"
127             "Key pressed was keycode='0xffeb', gdk_keyname='Super_L'"
128
129           The format for supplying a keymap is:
130           <srcKeySym1>=[<destKeySym1>][+<destKeySym2][,<srckeySym2>=[<destKeySym1]
131
132           To block a keypress simply assign an empty parameter to the
133           srcKeySym.
134
135           Example:
136             --keymap=Super_L=,Alt_L=,1=Shift_L+F1,2=Shift_L+F2
137
138           This will block the Super_L (typically Windows Key) and ALT_L
139           keypresses and remap key 1 to Shift F1, 2 to Shift F2.
140
141       -k, --kiosk
142           Start in kiosk mode. In this mode, the application will start in
143           fullscreen with minimal UI. It will prevent the user from quitting
144           or performing any interaction outside of usage of the remote
145           desktop session.
146
147           Note that it can't offer a complete secure solution by itself. Your
148           kiosk system must have additional configuration and security
149           settings to lock down the OS. In particular, you must configure or
150           disable the window manager, limit the session capabilities, use
151           some restart/watchdog mechanism, disable VT switching etc.
152
153       --kiosk-quit <never|on-disconnect>
154           By default, when kiosk mode is enabled, virt-viewer will remain
155           open when the connection to the remote server is terminated. By
156           setting kiosk-quit option to "on-disconnect" value, virt-viewer
157           will quit instead. Please note that --reconnect takes precedence
158           over this option, and will attempt to do a reconnection before it
159           quits.
160
161       --id, --uuid, --domain-name
162           Connect to the virtual machine by its id, uuid or name. These
163           options are mutual exclusive. For example the following command may
164           sometimes connect to a virtual machine with the id 2 or with the
165           name 2 (depending on the number of running machines):
166
167               virt-viewer 2
168
169           To always connect to the virtual machine with the name "2" use the
170           "--domain-name" option:
171
172               virt-viewer --domain-name 2
173

CONFIGURATION

175       A small number of configuration options can be controlled by editing
176       the settings file located in the user configuration directory:
177
178           <USER-CONFIG-DIR>/virt-viewer/settings
179
180       This file is a text file in INI format, with application options in the
181       [virt-viewer] group and per-guest options in a group identified by the
182       guest's UUID. The application options should not be edited manually.
183       There is also a special [fallback] group which specifies options for
184       all guests that don't have an explicit group.
185
186       For each guest, the initial fullscreen monitor configuration can be
187       specified by using the monitor-mapping key. This configuration only
188       takes effect when the -f/--full-screen option is specified.
189
190       The value of this key is a list of mappings between a guest display and
191       a client monitor. Each mapping is separated by a semicolon character,
192       and the mappings have the format
193       <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
194
195       For example, to map guest displays 1 and 2 to client monitors 2 and 3
196       for the guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
197
198           [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
199           monitor-mapping=1:2;2:3
200
201       The monitor-mapping must contain ids of all displays from 1 to the last
202       desired display id, e.g. "monitor-mapping=3:3" is invalid because
203       mappings for displays 1 and 2 are not specified.
204

EXAMPLES

206       To connect to the guest called 'demo' running under Xen
207
208          virt-viewer demo
209
210       To use GUI for connecting to a guest running under QEMU
211
212          virt-viewer --connect qemu:///system
213
214       To connect to the guest with ID 7 running under QEMU
215
216          virt-viewer --connect qemu:///system 7
217
218       To wait for the guest with UUID 66ab33c0-6919-a3f7-e659-16c82d248521 to
219       startup and then connect, also reconnecting upon restart of VM
220
221          virt-viewer --reconnect --wait 66ab33c0-6919-a3f7-e659-16c82d248521
222
223       To connect to a remote console using TLS
224
225          virt-viewer --connect xen://example.org/ demo
226
227       To connect to a remote host using SSH, lookup the guest config and then
228       make a tunnelled connection of the console
229
230          virt-viewer --connect qemu+ssh://root@example.org/system demo
231
232       When using a SSH tunnel to connect to a SPICE console, it's recommended
233       to have ssh-agent running to avoid getting multiple authentication
234       prompts.
235
236       To connect to a remote host using SSH, lookup the guest config and then
237       make a direct non-tunnelled connection of the console
238
239          virt-viewer --direct --connect xen+ssh://root@example.org/ demo
240

AUTHOR

242       Written by Daniel P. Berrange, based on the GTK-VNC example program
243       gvncviewer.
244

BUGS

246       Report bugs to https://gitlab.com/virt-viewer/virt-viewer/-/issues
247
249       Copyright (C) 2007-2020 Red Hat, Inc., and various contributors.  This
250       is free software. You may redistribute copies of it under the terms of
251       the GNU General Public License
252       "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
253       the extent permitted by law.
254

SEE ALSO

256       virsh(1), "virt-manager(1)", "spice-client(1)", the project website
257       "http://gitlab.com/virt-viewer/virt-viewer"
258
259
260
261Virt-Viewer 11.0                  2022-01-22                    Virt-Viewer(1)
Impressum