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] -- DOMAIN-NAME|ID|UUID
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
115 A small number of configuration options can be controlled by editing
116 the settings file located in the user configuration directory:
117 <USER-CONFIG-DIR>/virt-viewer/settings
119 This file is a text file in INI format, with application options in the
121 [virt-viewer] group and per-guest options in a group identified by the
122 guest's UUID. The application options should not be edited manually.
123 There is also a special [fallback] group which specifies options for
124 all guests that don't have an explicit group.
125 For each guest, the initial fullscreen monitor configuration can be
127 specified by using the monitor-mapping key. This configuration only
128 takes effect when the -f/--full-screen option is specified.
129 The value of this key is a list of mappings between a guest display and
131 a client monitor. Each mapping is separated by a semicolon character,
132 and the mappings have the format
133 <GUEST-DISPLAY-ID>:<CLIENT-MONITOR-ID>.
134 For example, to map guest displays 1 and 2 to client monitors 2 and 3
136 for the guest with a UUID of e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2, use:
137 [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
139 monitor-mapping=1:2;2:3
140
142 To connect to the guest called 'demo' running under Xen
143 virt-viewer demo
145 To connect to the guest with ID 7 running under QEMU
147 virt-viewer --connect qemu:///system 7
149 To wait for the guest with UUID 66ab33c0-6919-a3f7-e659-16c82d248521 to
151 startup and then connect, also reconnecting upon restart of VM
152 virt-viewer --reconnect --wait 66ab33c0-6919-a3f7-e659-16c82d248521
154 To connect to a remote console using TLS
156 virt-viewer --connect xen://example.org/ demo
158 To connect to a remote host using SSH, lookup the guest config and then
160 make a direct non-tunnelled connection of the console
161 virt-viewer --direct --connect xen+ssh://root@example.org/ demo
163
165 Written by Daniel P. Berrange, based on the GTK-VNC example program
166 gvncviewer.
167
169 Report bugs to the mailing list
170 "http://www.redhat.com/mailman/listinfo/virt-tools-list"
171
173 Copyright (C) 2007-2014 Red Hat, Inc., and various contributors. This
174 is free software. You may redistribute copies of it under the terms of
175 the GNU General Public License
176 "https://www.gnu.org/licenses/gpl-2.0.html". There is NO WARRANTY, to
177 the extent permitted by law.
178
180 virsh(1), "virt-manager(1)", the project website
181 "http://virt-manager.org"
182perl v5.18.4 2015-01-12 VIRT-VIEWER(1)