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

OPTIONS

22       The following options are accepted when running "virt-viewer":
23
24       -h, --help
25           Display command line help summary
26
27       -V, --version
28           Display program version number
29
30       -v, --verbose
31           Display information about the connection
32
33       -c URI, --connect=URI
34           Specify the hypervisor connection URI
35
36       -w, --wait
37           Wait for the domain to start up before attempting to connect to the
38           console
39
40       -r, --reconnect
41           Automatically reconnect to the domain if it shuts down and restarts
42
43       -z PCT, --zoom=PCT
44           Zoom level of the display window in percentage. Range 10-400.
45
46       -d, --direct
47           Do not attempt to tunnel the console over SSH, even if the main
48           connection URI used SSH.
49
50       -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
60       -f, --full-screen
61           Start with the window maximised to fullscreen
62
63           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
68           To specify which client monitors are used in fullscreen mode, see
69           the CONFIGURATION section below.
70
71       --debug
72           Print debugging information
73
74       -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
85             --hotkeys=toggle-fullscreen=shift+f11,release-cursor=shift+f12
86
87             --hotkeys=release-cursor=ctrl+alt
88
89           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
94       -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
100           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
106       --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
114       --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
120               virt-viewer 2
121
122           To always connect to the virtual machine with the name "2" use the
123           "--domain-name" option:
124
125               virt-viewer --domain-name 2
126

CONFIGURATION

128       A small number of configuration options can be controlled by editing
129       the settings file located in the user configuration directory:
130
131           <USER-CONFIG-DIR>/virt-viewer/settings
132
133       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
139       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
143       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
148       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
151           [e4591275-d9d3-4a44-a18b-ef2fbc8ac3e2]
152           monitor-mapping=1:2;2:3
153
154       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

EXAMPLES

159       To connect to the guest called 'demo' running under Xen
160
161          virt-viewer demo
162
163       To use GUI for connecting to a guest running under QEMU
164
165          virt-viewer --connect qemu:///system
166
167       To connect to the guest with ID 7 running under QEMU
168
169          virt-viewer --connect qemu:///system 7
170
171       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
174          virt-viewer --reconnect --wait 66ab33c0-6919-a3f7-e659-16c82d248521
175
176       To connect to a remote console using TLS
177
178          virt-viewer --connect xen://example.org/ demo
179
180       To connect to a remote host using SSH, lookup the guest config and then
181       make a tunnelled connection of the console
182
183          virt-viewer --connect qemu+ssh://root@example.org/system demo
184
185       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
189       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
192          virt-viewer --direct --connect xen+ssh://root@example.org/ demo
193

AUTHOR

195       Written by Daniel P. Berrange, based on the GTK-VNC example program
196       gvncviewer.
197

BUGS

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

SEE ALSO

210       virsh(1), "virt-manager(1)", "spice-client(1)", the project website
211       "http://virt-manager.org"
212
213
214
215perl v5.28.1                      2018-07-27                    VIRT-VIEWER(1)
Impressum