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
22 The following options are accepted when running "virt-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 -c URI, --connect=URI
34 Specify the hypervisor connection URI
35 -w, --wait
37 Wait for the domain to start up before attempting to connect to the
38 console
39 -r, --reconnect
41 Automatically reconnect to the domain if it shuts down and restarts
42 -z PCT, --zoom=PCT
44 Zoom level of the display window in percentage. Range 10-400.
45 -d, --direct
47 Do not attempt to tunnel the console over SSH, even if the main
48 connection URI used SSH.
49 -a, --attach
51 Instead of making a direct TCP/UNIX socket connection to the remote
52 display, ask libvirt to provide a pre-connected socket for the
53 display. This avoids the need to authenticate with the remote
54 display server directly. This option will only work when connecting
55 to a guest that is running on the same host as the virt-viewer
56 program. If attaching to the guest via libvirt fails, virt-viewer
57 will automatically fallback to trying a regular direct TCP/UNIX
58 socket connection.
59 -f, --full-screen
61 Start with the window maximised to fullscreen
62 If supported, the remote display will be reconfigured to match the
64 physical client monitor configuration, by enabling or disabling
65 extra monitors as necessary. This is currently implemented by the
66 Spice backend only.
67 To specify which client monitors are used in fullscreen mode, see
69 the CONFIGURATION section below.
70 --debug
72 Print debugging information
73 -H HOTKEYS, --hotkeys HOTKEYS
75 Set global hotkey bindings. By default, keyboard shortcuts only
76 work when the guest display widget does not have focus. Any
77 actions specified in HOTKEYS will be effective even when the guest
78 display widget has input focus. The format for HOTKEYS is
79 <action1>=<key1>[+<key2>][,<action2>=<key3>[+<key4>]]. Key-names
80 are case-insensitive. Valid actions are: toggle-fullscreen,
81 release-cursor, secure-attention, smartcard-insert and smartcard-
82 remove. The "secure-attention" action sends a secure attention
83 sequence (Ctrl+Alt+Del) to the guest. Examples:
84 --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
86 --hotkeys=release-cursor=ctrl+alt
88 Note that hotkeys for which no binding is given are disabled.
90 Although the hotkeys specified here are handled by the client, it
91 is still possible to send these key combinations to the guest via a
92 menu item.
93 -k, --kiosk
95 Start in kiosk mode. In this mode, the application will start in
96 fullscreen with minimal UI. It will prevent the user from quitting
97 or performing any interaction outside of usage of the remote
98 desktop session.
99 Note that it can't offer a complete secure solution by itself. Your
101 kiosk system must have additional configuration and security
102 settings to lock down the OS. In particular, you must configure or
103 disable the window manager, limit the session capabilities, use
104 some restart/watchdog mechanism, disable VT switching etc.
105 --kiosk-quit <never|on-disconnect>
107 By default, when kiosk mode is enabled, virt-viewer will remain
108 open when the connection to the remote server is terminated. By
109 setting kiosk-quit option to "on-disconnect" value, virt-viewer
110 will quit instead. Please note that --reconnect takes precedence
111 over this option, and will attempt to do a reconnection before it
112 quits.
113 --id, --uuid, --domain-name
115 Connect to the virtual machine by its id, uuid or name. These
116 options are mutual exclusive. For example the following command may
117 sometimes connect to a virtual machine with the id 2 or with the
118 name 2 (depending on the number of running machines):
119 virt-viewer 2
121 To always connect to the virtual machine with the name "2" use the
123 "--domain-name" option:
124 virt-viewer --domain-name 2
126
128 A small number of configuration options can be controlled by editing
129 the settings file located in the user configuration directory:
130 <USER-CONFIG-DIR>/virt-viewer/settings
132 This file is a text file in INI format, with application options in the
134 [virt-viewer] group and per-guest options in a group identified by the
135 guest's UUID. The application options should not be edited manually.
136 There is also a special [fallback] group which specifies options for
137 all guests that don't have an explicit group.
138 For each guest, the initial fullscreen monitor configuration can be
140 specified by using the monitor-mapping key. This configuration only
141 takes effect when the -f/--full-screen option is specified.
142 The value of this key is a list of mappings between a guest display and
144 a client monitor. Each mapping is separated by a semicolon character,
145 and the mappings have the format
146 <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
147 For example, to map guest displays 1 and 2 to client monitors 2 and 3
149 for the guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
150 [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
152 monitor-mapping=1:2;2:3
153 The monitor-mapping must contain ids of all displays from 1 to the last
155 desired display id, e.g. "monitor-mapping=3:3" is invalid because
156 mappings for displays 1 and 2 are not specified.
157
159 To connect to the guest called 'demo' running under Xen
160 virt-viewer demo
162 To use GUI for connecting to a guest running under QEMU
164 virt-viewer --connect qemu:///system
166 To connect to the guest with ID 7 running under QEMU
168 virt-viewer --connect qemu:///system 7
170 To wait for the guest with UUID 66ab33c0-6919-a3f7-e659-16c82d248521 to
172 startup and then connect, also reconnecting upon restart of VM
173 virt-viewer --reconnect --wait 66ab33c0-6919-a3f7-e659-16c82d248521
175 To connect to a remote console using TLS
177 virt-viewer --connect xen://example.org/ demo
179 To connect to a remote host using SSH, lookup the guest config and then
181 make a tunnelled connection of the console
182 virt-viewer --connect qemu+ssh://root@example.org/system demo
184 When using a SSH tunnel to connect to a SPICE console, it's recommended
186 to have ssh-agent running to avoid getting multiple authentication
187 prompts.
188 To connect to a remote host using SSH, lookup the guest config and then
190 make a direct non-tunnelled connection of the console
191 virt-viewer --direct --connect xen+ssh://root@example.org/ demo
193
195 Written by Daniel P. Berrange, based on the GTK-VNC example program
196 gvncviewer.
197
199 Report bugs to the mailing list
200 "http://www.redhat.com/mailman/listinfo/virt-tools-list"
201
203 Copyright (C) 2007-2014 Red Hat, Inc., and various contributors. This
204 is free software. You may redistribute copies of it under the terms of
205 the GNU General Public License
206 "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
207 the extent permitted by law.
208
210 virsh(1), "virt-manager(1)", "spice-client(1)", the project website
211 "http://virt-manager.org"
212perl v5.28.1 2018-07-27 VIRT-VIEWER(1)