1Virt-Viewer(1) Virtualization Support Virt-Viewer(1)
2
6 virt-viewer - display the graphical console for a virtual machine
7
9 virt-viewer [OPTIONS] [ID|UUID|DOMAIN-NAME]
10
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 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
27 The following options are accepted when running "virt-viewer":
28 -h, --help
30 Display command line help summary
31 -V, --version
33 Display program version number
34 -v, --verbose
36 Display information about the connection
37 -c URI, --connect=URI
39 Specify the hypervisor connection URI
40 -w, --wait
42 Wait for the domain to start up before attempting to connect to the
43 console
44 -r, --reconnect
46 Automatically reconnect to the domain if it shuts down and restarts
47 -z PCT, --zoom=PCT
49 Zoom level of the display window in percentage. Range 10-400.
50 -d, --direct
52 Do not attempt to tunnel the console over SSH, even if the main
53 connection URI used SSH.
54 -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 -f, --full-screen
66 Start with the window maximised to fullscreen
67 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 To specify which client monitors are used in fullscreen mode, see
74 the CONFIGURATION section below.
75 --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 -s, --shared
82 Permitted a shared session with multiple clients
83 --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 --debug
96 Print debugging information
97 -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 --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
111 --hotkeys=release-cursor=ctrl+alt
113 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 -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 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 The format for supplying a keymap is:
130 <srcKeySym1>=[<destKeySym1>][+<destKeySym2][,<srckeySym2>=[<destKeySym1]
131 To block a keypress simply assign an empty parameter to the
133 srcKeySym.
134 Example:
136 --keymap=Super_L=,Alt_L=,1=Shift_L+F1,2=Shift_L+F2
137 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 -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 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 --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 --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 virt-viewer 2
168 To always connect to the virtual machine with the name "2" use the
170 "--domain-name" option:
171 virt-viewer --domain-name 2
173
175 A small number of configuration options can be controlled by editing
176 the settings file located in the user configuration directory:
177 <USER-CONFIG-DIR>/virt-viewer/settings
179 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 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 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 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 [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
199 monitor-mapping=1:2;2:3
200 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
206 To connect to the guest called 'demo' running under Xen
207 virt-viewer demo
209 To use GUI for connecting to a guest running under QEMU
211 virt-viewer --connect qemu:///system
213 To connect to the guest with ID 7 running under QEMU
215 virt-viewer --connect qemu:///system 7
217 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 virt-viewer --reconnect --wait 66ab33c0-6919-a3f7-e659-16c82d248521
222 To connect to a remote console using TLS
224 virt-viewer --connect xen://example.org/ demo
226 To connect to a remote host using SSH, lookup the guest config and then
228 make a tunnelled connection of the console
229 virt-viewer --connect qemu+ssh://root@example.org/system demo
231 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 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 virt-viewer --direct --connect xen+ssh://root@example.org/ demo
240
242 Written by Daniel P. Berrange, based on the GTK-VNC example program
243 gvncviewer.
244
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
256 virsh(1), "virt-manager(1)", "spice-client(1)", the project website
257 "http://gitlab.com/virt-viewer/virt-viewer"
258Virt-Viewer 11.0 2022-01-22 Virt-Viewer(1)