1VIRSH(1) Virtualization Support VIRSH(1)
2
6 virsh - management user interface
7
9 virsh <subcommand> [args]
10
12 The virsh program is the main interface for managing virsh guest
13 domains. The program can be used to create, pause, and shutdown
14 domains. It can also be used to list current domains. Libvirt is a C
15 toolkit to interact with the virtualization capabilities of recent ver‐
16 sions of Linux (and other OSes). It is free software available under
17 the GNU Lesser General Public License. Virtualization of the Linux
18 Operating System means the ability to run multiple instances of Operat‐
19 ing Systems concurrently on a single hardware system where the basic
20 resources are driven by a Linux instance. The library aim at providing
21 long term stable C API initially for the Xen paravirtualization but
22 should be able to integrate other virtualization mechanisms, it cur‐
23 rently also support QEmu and KVM.
24 The basic structure of most virsh usage is:
26 virsh <command> <domain-id> [OPTIONS]
28 Where command is one of the commands listed below, domain-id is the
30 numeric domain id, or the domain name (which will be internally trans‐
31 lated to domain id), and OPTIONS are command specific options. There
32 are a few exceptions to this rule in the cases where the command in
33 question acts on all domains, the entire machine, or directly on the
34 xen hypervisor. Those exceptions will be clear for each of those com‐
35 mands.
36 The virsh program can be used either to run one command at a time by
38 giving the command as an argument on the command line, or as a shell if
39 no command is given in the command line, it will then start a minimal
40 interpreter waiting for your commands and the quit command will then
41 exit the program.
42
44 All virsh operations rely upon the libvirt library. For any virsh com‐
45 mands to run xend/qemu, or what ever virtual library that libvirt sup‐
46 ports. For this reason you should start xend/qemu as a service when
47 your system first boots using xen/qemu. This can usually be done using
48 the command service start libvirtd .
49 Most virsh commands require root privileges to run due to the communi‐
51 cations channels used to talk to the hypervisor. Running as non root
52 will return an error.
53 Most virsh commands act asynchronously, so just because the virsh pro‐
55 gram returned, doesn't mean the action is complete. This is important,
56 as many operations on domains, like create and shutdown, can take con‐
57 siderable time (30 seconds or more) to bring the machine into a fully
58 compliant state. If you want to know when one of these actions has
59 finished you must poll through virsh list periodically.
60
62 The following commands are generic i.e. not specific to a domain.
63 help optional command
65 This prints a small synopsis about all commands available for virsh
66 help command will print out a detailed help message on that com‐
67 mand.
68 quit
70 quit this interactive terminal
71 version
73 Will print out the major version info about what this built from.
74 Example
76 virsh version
78 Compiled against library: libvir 0.0.6
80 Using library: libvir 0.0.6
82 Using API: Xen 3.0.0
84 Running hypervisor: Xen 3.0.0
86 connect URI optional --readonly
88 (Re)-Connect to the hypervisor. This is a build-in command after
89 shell start up, and usually get an URI parameter specifying how to
90 connect to the hypervisor. The documentation page at <http://lib‐
91 virt.org/uri.html> list the values supported but the most common
92 are:
93 xen:///
95 this is used to connect to the local Xen hypervisor, this is
96 the default
97 qemu:///system
99 allow to connect locally as root to the daemon supervizing QEmu
100 and KVM domains
101 qemu:///session
103 allow to connect locally as a normal user to the his own set of
104 QEmu and KVM domains
105 For remote access see the documentation page on how to make URIs.
107 The --readonly option allows for read-only connection
108 nodeinfo
110 Returns basic information about the node, like number and type of
111 CPU, and size of the physical memory.
112 capabilities
114 Print an XML document describing the capabilities of the hypervisor
115 we are currently connected to. This includes a section on the host
116 capabilities in terms of CPU and features, and a set of description
117 for each kind of guest which can be virtualized. For a more com‐
118 plete description see:
119 <http://libvirt.org/format.html#Capa1> The XML also show the NUMA
120 topology informations if available.
121 list
123 Prints information about one or more domains. If no domains are
124 specified it prints out information about all domains.
125 An example format for the list is as follows:
127 virsh list
129 Id Name State
130 ----------------------------------
132 0 Domain-0 running
134 2 fedora paused
135 Name is the name of the domain. ID the domain numeric id.
137 State is the run state (see below).
138 freecell optional cellno
140 Prints the available amount of memory on the machine or within a
141 NUMA cell if cellno is provided.
142 STATES
144 The State field lists 6 states for a Xen Domain, and which ones
146 the current Domain is in.
147 r - running
149 The domain is currently running on a CPU
150 b - blocked
152 The domain is blocked, and not running or runnable. This can
153 be caused because the domain is waiting on IO (a traditional
154 wait state) or has gone to sleep because there was nothing else
155 for it to do.
156 p - paused
158 The domain has been paused, usually occurring through the
159 administrator running xm pause. When in a paused state the
160 domain will still consume allocated resources like memory, but
161 will not be eligible for scheduling by the Xen hypervisor.
162 s - shutdown
164 The domain is in the process of shutting down, i.e. the guest
165 operating system has been notified and should be in the process
166 of stopping its operations gracefully.
167 c - crashed
169 The domain has crashed, which is always a violent ending. Usu‐
170 ally this state can only occur if the domain has been config‐
171 ured not to restart on crash. See xmdomain.cfg for more info.
172 d - dying
174 The domain is in process of dying, but hasn't completely shut‐
175 down or crashed.
176
178 The following commands manipulate domains directly, as stated previ‐
179 ously most commands take domain-id as the first parameter. The domain-
180 id can be specified as an short integer, a name or a full UUID.
181 autostart optional --disable domain-id
183 Configure a domain to be automatically started at boot.
184 The option --disable disable autostarting.
186 console domain-id
188 Connect the virtual serial console for the guest.
189 create FILE
191 Create a domain from an XML <file> an easy way to create one if you
192 have a pre-existing xen guest created via xm create <XMLFILE>.
193 Example
195 virsh dumpxml <domain-id> > file.
197 define FILE
199 Define a domain from an XML <file>. The domain definitions is reg‐
200 istered but not started.
201 destroy domain-id
203 Immediately terminate the domain domain-id. This doesn't give the
204 domain OS any chance to react, and it the equivalent of ripping the
205 power cord out on a physical machine. In most cases you will want
206 to use the shutdown command instead.
207 dominfo domain-id
209 Returns basic information about the domain.
210 domuuid domain-name-or-id
212 Convert a domain name or id to domain UUID
213 domid domain-name
215 Converts a domain name to a domain id using xend's internal map‐
216 ping.
217 dominfo domain-id
219 Returns basic information about the domain.
220 domname domain-id
222 convert a domain Id to domain name
223 domstate domain-id
225 Returns state about a running domain.
226 dumpxml domain-id
228 Output the domain informations as an XML dump to stdout, this for‐
229 mat can be used by the create command.
230 reboot domain-id
232 Reboot a domain. This acts just as if the domain had the reboot
233 command run from the console. The command returns as soon as it
234 has executed the reboot action, which may be significantly before
235 the domain actually reboots.
236 For xen vm the behavior of what happens to a domain when it reboots
238 is set by the on_reboot parameter of the xmdomain.cfg file when the
239 domain was created.
240 restore state-file
242 Restores a domain from an virsh save state file. See save for more
243 info.
244 save domain-id state-file
246 Saves a running domain to a state file so that it can be restored
247 later. Once saved, the domain will no longer be running on the
248 system, thus the memory allocated for the domain will be free for
249 other domains to use. virsh restore restores from this state file.
250 This is roughly equivalent to doing a hibernate on a running com‐
252 puter, with all the same limitations. Open network connections may
253 be severed upon restore, as TCP timeouts may have expired.
254 setmem domain-id kilobytes
256 Change the current memory allocation in the guest domain. This
257 should take effect immediately. The memory limit is specified in
258 kilobytes.
259 setmaxmem domain-id kilobytes
261 Change the maximum memory allocation limit in the guest domain.
262 This should not change the current memory use. The memory limit is
263 specified in kilobytes.
264 setvcpus domain-id count
266 Change the number of virtual CPUs active in the guest domain. Note
267 that count may be limited by host, hypervisor or limit coming from
268 the original description of domain.
269 shutdown domain-id
271 Gracefully shuts down a domain. This coordinates with the domain
272 OS to perform graceful shutdown, so there is no guarantee that it
273 will succeed, and may take a variable length of time depending on
274 what services must be shutdown in the domain.
275 For a xen guest vm the behavior of what happens to a domain when it
277 reboots is set by the on_shutdown parameter of the xmdomain.cfg
278 file when the domain was created.
279 suspend domain-id
281 Suspend a running domain. It is kept in memory but won't be sched‐
282 uled anymore.
283 resume domain-id
285 Moves a domain out of the suspended state. This will allow a pre‐
286 viously suspended domain to now be eligible for scheduling by the
287 the underlying hypervisor.
288 ttyconsole domain-id
290 Output the device used for the TTY console of the domain. If the
291 information is not available the processes will provide an exit
292 code of 1.
293 undefine domain-id
295 Undefine the configuration for an inactive domain. Since it's not
296 running the domain name or UUId must be used as the domain-id.
297 vcpuinfo domain-id
299 Returns basic information about the domain virtual CPUs, like the
300 number of vCPUs, the running time, the affinity to physical proces‐
301 sors.
302 vcpupin domain-id vcpu cpulist
304 Pin domain VCPUs to host physical CPUs. The vcpu number must be
305 provided and cpulist is a comma separated list of physical CPU num‐
306 bers.
307 vncdisplay domain-id
309 Output the IP address and port number for the VNC display. If the
310 information is not available the processes will provide an exit
311 code of 1.
312
314 The following commands manipulate devices associated to domains. The
315 domain-id can be specified as an short integer, a name or a full UUID.
316 To better understand the values allowed as options for the command
317 reading the documentation at <http://libvirt.org/format.html> on the
318 format of the device sections to get the most accurate set of accepted
319 values.
320 attach-device domain-id FILE
322 Attach a device to the domain, using a device definition in an XML
323 file. See the documentation to learn about libvirt XML format for
324 a device.
325 attach-disk domain-id source target optional --driver driver --sub‐
327 driver subdriver --type type --mode mode
328 Attach a new disk device to the domain. source and target are
329 paths for the files and devices. driver can be file, tap or phy
330 depending on the kind of access. type can indicate cdrom or floppy
331 as alternative to the disk default. mode can specify the two spe‐
332 cific mode readonly or shareable.
333 attach-interface domain-id type source optional --target target --mac
335 mac --script script
336 Attach a new network interface to the domain. type can be either
337 network to indicate a physical network device or bridge to indicate
338 a bridge to a device. source indicates the source device. target
339 allows to indicate the target device in the guest. mac allows to
340 specify the MAC address of the network interface. script allows to
341 specify a path to a script handling a bridge instead of the default
342 one.
343 detach-device domain-id FILE
345 Detach a device from the domain, takes the same kind of XML
346 descriptions as command attach-device.
347 detach-disk domain-id target
349 Detach a disk device from a domain. The target is the device as
350 seen from the domain.
351 detach-interface domain-id type optional --mac mac
353 Detach a network interface from a domain. type can be either net‐
354 work to indicate a physical network device or bridge to indicate a
355 bridge to a device. It is recommended to use the mac option to
356 distinguish between the interfaces if more than one are present on
357 the domain.
358
360 The following commands manipulate networks. Libvirt has the capability
361 to define virtual networks which can then be used by domains and linked
362 to actual network devices. For more detailed informations about this
363 feature see the documentation at <http://libvirt.org/format.html#Net1>
364 . A lot of the command for virtual networks are similar to the one used
365 for domains, but the way to name a virtual network is either by its
366 name or UUID.
367 net-autostart network optional --disable
369 Configure a virtual network to be automatically started at boot.
370 The --disable option disable autostarting.
371 net-create file
373 Create a virtual network from an XML file, see the documentation to
374 get a description of the XML network format used by libvirt.
375 net-define file
377 Define a virtual network from an XML file, the network is just
378 defined but not instantiated.
379 net-destroy network
381 Destroy a given virtual network specified by its name or UUID. This
382 takes effect immediately.
383 net-dumpxml network
385 Output the virtual network information as an XML dump to stdout.
386 net-list optional --inactive or --all
388 Returns the list of active networks, if --all is specified this
389 will also include defined but inactive networks, if --inactive is
390 specified only the inactive ones will be listed.
391 net-name network-UUID
393 Convert a network UUID to network name.
394 net-start network
396 Start a (previously defined) inactive network.
397 net-undefine network
399 Undefine the configuration for an inactive network.
400 net-uuid network-name
402 Convert a network name to network UUID.
403
405 VIRSH_DEFAULT_CONNECT_URI
406 The hypervisor to connect to by default. Set this to a URI, in the
407 same format as accepted by the connect option.
408
410 xm(1), xmdomain.cfg(5), xentop(1) , <http://www.libvirt.org/>
411
413 Andrew Puch <apuch @ redhat.com>
414 Daniel Veillard <veillard @ redhat.com>
415 Based on the xm man paged by
417 Sean Dague <sean at dague dot net>
418 Daniel Stekloff <dsteklof at us dot ibm dot com>
419
421 Bugs can be view on the RedHat buzilla page under the libvirt
422 <https://bugzilla.redhat.com/>
423 <https://bugzilla.redhat.com/bugzilla/buglist.cgi?prod‐
425 uct=Fedora+Core&component=libvirt&bug_status=NEW&bug_sta‐
426 tus=ASSIGNED&bug_status=REOPENED&bug_status=MODI‐
427 FIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=all‐
428 wordssubstr>
429perl v5.8.8 2007-09-28 VIRSH(1)