1virsh(1M) System Administration Commands virsh(1M)
2
3
4
6 virsh - management user interface for guest domains
7
9 virsh subcommand [arguments]
10
11
13 The virsh command provides the main interface for command and control
14 of both xVM and guest domains. Users should use virsh wherever possi‐
15 ble, as it provides a generic and stable interface to controlling vir‐
16 tualized operating systems. Some xVM operations are not yet implemented
17 by virsh. In those cases, the legacy utility xm(1M) can be used for
18 detailed control.
19
20
21 virsh can be used to administer both transient and managed guests. A
22 managed guest has a persistent configuration which is maintained across
23 multiple invocations of the guest. The configuration of a transient
24 guest is discarded when the guest shuts down.
25
26
27 With minor exceptions, the basic form of a virsh command is:
28
29 # virsh subcommand domain-id | name | uuid [options]
30
31
32
33
34 The components of a virsh command are described as follows:
35
36 subcommand
37
38 One of the subcommands described below.
39
40
41 domain-id | name | uuid
42
43 An identifier for a specific domain.
44
45
46 options
47
48 A subcommand-specific option.
49
50
51
52 Exceptions to command form described above occur when a subcommand acts
53 on all domains, the entire machine, or directly on the Solaris xVM
54 hypervisor.
55
56
57 Most virsh subcommands require root privileges or that you assume the
58 Primary Administrator role.
59
60
61 Many virsh commands act asynchronously, so that the system prompt
62 returns immediately while activity proceeds in the background. Many
63 operations on domains, such as create and shutdown, can take consider‐
64 able time (30 seconds or more) to reach completion. Use the list sub‐
65 command to determine whether such an operation is complete.
66
68 The virsh subcommands are categorized under the rubrics "generic",
69 "domain", and "device" and are described in the following subsections
70 of those names.
71
72 Generic Subcommands
73 capabilities
74
75 Display an XML document describing the capabilities of the hypervi‐
76 sor to which we are currently connected. This includes a section on
77 the host capabilities in terms of CPU features, and a description
78 for each kind of guest which can be virtualized. For a more com‐
79 plete description, see the page under libvirt.org entitled "XML
80 Format". The XML also shows the NUMA topology information, if
81 available.
82
83
84 connect URI [--readonly]
85
86 Connect to the hypervisor. The URI parameter, if provided, speci‐
87 fies how to connect to the hypervisor. Without this parameter, the
88 connection will be to the local hypervisor. The web page entitled
89 "Connection URIs", under libvirt.org, lists the possible values,
90 but not all types are supported by all systems.
91
92 With the --readonly option, the connection is read-only.
93
94
95 help [subcommand]
96
97 With no argument, help displays a brief synopsis of all subcom‐
98 mands. With a specified subcommand, displays a brief description of
99 that subcommand.
100
101
102 nodeinfo
103
104 Returns basic information about a node, such as the number and type
105 of CPUs, and the size of physical memory.
106
107
108 quit
109
110 Quit this interactive terminal.
111
112
113 version
114
115 Display version information about this instance of virsh.
116
117
118 Domain Subcommands
119 The following subcommands manipulate domains directly. Most take a
120 domain identifier as their first argument. In the following descrip‐
121 tion, the notation domain can be either a symbolic domain name, a
122 numeric domain id, or a UUID, any of which uniquely identify a domain.
123
124 console domain [--verbose]
125
126 Connect the virtual serial console for the guest. This subcommand
127 takes the following option:
128
129 --verbose
130
131 Displays verbose connection and disconnection messages.
132
133
134
135 create file
136
137 Create (and start) a domain based on the parameters contained in
138 the XML file file, where file is an absolute pathname. Such a file
139 can be created using virsh dumpxml subcommand. Directly editing
140 XML configuration is not recommended. Use this subcommand to create
141 a transient guest. Use define (below) to create a managed guest.
142
143
144 define file [--relative-path path]
145
146 Define (but do not start) a domain from the specified XML file. If
147 the disk paths in the XML file contain relative paths, the domain
148 will be created with those paths relative to path, if provided.
149
150
151 destroy domain
152
153 Immediately terminate a domain. This is the equivalent of abruptly
154 terminating power to a machine. In most cases, you should use the
155 shutdown subcommand instead.
156
157
158 domid domain_name
159
160 Converts a domain name to a numeric domain ID.
161
162
163 dominfo domain
164
165 Returns basic information about a domain. In dominfo output, note
166 that the OS Type field displays the type of virtualization--hvm for
167 a Hardware-assisted Virtual Machine (HVM), linux for a paravirtual‐
168 ized domain--not the guest OS installed in a domain.
169
170 Note that, when the domain is running, dominfo displays dynamic
171 data. Memory values include any hypervisor overhead.
172
173
174 domname domain_id
175
176 Converts a numeric domain id to a domain name.
177
178
179 domstate domain
180
181 Returns the state of a running domain. See the description of the
182 list subcommand.
183
184
185 domuuid domain
186
187 Convert the specified domain name or ID to a domain UUID.
188
189
190 dump domain file
191
192 Dump the core of the domain specified by domain to the file speci‐
193 fied by file for analysis.
194
195
196 dumpxml domain [--relative-path path]
197
198 Output the configuration of the given domain in XML format. Cap‐
199 tured in a file, this data can be used as the argument to a subse‐
200 quent create subcommand.
201
202 By default, all paths in the XML will be absolute. Adding the
203 --relative-path option will make all disk paths relative to path.
204
205
206 edit
207
208 Starts the editor specified by the value of $EDITOR and, in this
209 editor, opens the result of the command virsh dumpxml. The subcom‐
210 mand then redefines the domain with the edited XML. Editing XML is
211 not recommended.
212
213
214 hostname
215
216 Returns the hostname of the control domain.
217
218
219 list [domain...]
220
221 Displays information about one or more domains. If no domains are
222 specified, displays information about all defined domains. This
223 subcommand takes the following options:
224
225 --active Display only running domains.
226
227
228 --inactive Display only non-running domains.
229
230
231 --all Display both running and non-running domains.
232
233 By default, all domains are displayed.
234
235 An example of list output is as follows:
236
237 % virsh list
238 Id Name State
239
240 ----------------------------------
241
242 0 Domain-0 running
243 2 fedora paused
244 - solaris-hvm shut off
245
246
247 Id is the numeric id for a domain; Name is the symbolic name. State
248 is the run state and can be one of the following:
249
250 running
251
252 The domain is currently running on a CPU.
253
254
255 idle
256
257 The domain is not currently running on any CPU. This can be
258 because the domain is waiting on I/O (a traditional wait state)
259 or has gone to sleep because of inactivity.
260
261
262 paused
263
264 The domain has been paused, usually as a result of the adminis‐
265 trator running virsh suspend. When in a paused state the domain
266 still consumes allocated resources, such as memory, but is not
267 eligible for scheduling by the xVM hypervisor.
268
269
270 in shutdown
271
272 The domain is in process of shutting down, but has not com‐
273 pletely shutdown or crashed.
274
275
276 shut off
277
278 The domain is down.
279
280
281 crashed
282
283 The domain has crashed as a result of a sudden event. Normally,
284 this state can occur only if the domain has been configured not
285 to restart following a crash.
286
287
288
289 migrate [--live] domain dest_uri [migrate_uri]
290
291 Migrate the domain to the host specified by dest_uri. The --live
292 option attempts a live migration. The optional migrate_uri is a
293 separate URI that specifies a transport method between the host and
294 destination.
295
296
297 reboot domain
298
299 Reboot a domain. The effect of this command is identical to the
300 effect of running init 6. The command returns immediately, however,
301 if successful, the entire reboot process might take a minute or
302 more. There is no guarantee that the subcommand will succeed and it
303 might take an unexpected length of time, depending on what services
304 in the domain must be shutdown.
305
306
307 restore state-file
308
309 Restores a domain from a virsh save state file. See the description
310 of the save subcommand.
311
312
313 resume domain
314
315 Moves a domain out of the paused state, making the domain eligible
316 for scheduling by the underlying hypervisor.
317
318
319 save domain state-file
320
321 Saves a running domain to a file state-file, so that it can later
322 be restored, using the restore subcommand. Once saved, the domain
323 will no longer be running on the system, thus the memory allocated
324 for the domain will be free for the use of other domains.
325
326 Note that network connections present before the save operation
327 might be severed, as TCP timeouts might have expired.
328
329
330 schedinfo domain
331
332 Show or set the scheduling parameters for the specified domain
333 name, ID or UUID. schedinfo works only on running domains. This
334 subcommand takes the following options:
335
336 --weight number weight for credit scheduler
337
338
339 --cap number cap for credit scheduler
340
341
342 --set Not implemented.
343
344
345
346 setmaxmem domain kilobytes
347
348 Change the maximum memory allocation limit in the specified guest
349 domain. The kilobytes parameter is the maximum memory limit in
350 kilobytes. If this subcommand is applied to a running domain, the
351 specified value applies only after the domain has been rebooted.
352
353
354 setmem domain kilobytes
355
356 Change the current memory allocation in the specified guest domain.
357 The kilobytes parameter is the number of kilobytes of memory. Note
358 that only paravirtualized domains support changing this value by
359 means of the balloon driver, and it cannot exceed the maximum mem‐
360 ory limit for the domain . A Solaris paravirtualized domain can
361 never exceed the memory value set at boot time.
362
363
364 setvcpus domain count
365
366 Change the number of virtual CPUs active in the specified guest
367 domain. The count parameter is the number of virtual CPUs. Only
368 paravirtualized domains can dynamically change this value, and only
369 up to the value that was set at boot time. To change the number of
370 CPUs in a way that persists, you must change the value when the
371 domain is not running.
372
373
374 shutdown domain
375
376 Coordinates with the domain OS to perform graceful shutdown. The
377 effect of this command is identical to the effect of running init
378 5. There is no guarantee that the subcommand will succeed and it
379 might take an unexpected length of time, depending on what services
380 in the domain must be shutdown.
381
382
383 start domain
384
385 Start a (previously defined) inactive domain.
386
387
388 suspend domain
389
390 Suspend a domain. When in this state, a domain still consumes allo‐
391 cated resources, such as memory, but is not eligible for scheduling
392 by the xVM hypervisor.
393
394
395 ttyconsole
396
397 Return the pseudo-terminal used by the domain's serial console, if
398 any.
399
400
401 undefine domain
402
403 Undefine the configuration for the inactive domain which is speci‐
404 fied by either its domain name or UUID.
405
406
407 uri
408
409 Return the URI of the libvirt connection.
410
411
412 vcpuinfo domain
413
414 Return basic information about the domain virtual CPUs.
415
416
417 vcpupin domain vcpu cpulist
418
419 Pin domain VCPUs to the host physical CPUs. The domain parameter is
420 the domain name, ID, or uuid. The vcpu parameter is the VCPU num‐
421 ber. The cpulist parameter is a list of host CPU numbers, separated
422 by commas.
423
424 This subcommand applies only to running domains.
425
426
427 vncdisplay domain
428
429 Output the IP address and port number for the VNC display.
430
431
432 Device Subcommands
433 The following subcommands manipulate devices associated with domains.
434 In the following descriptions, domain can stand for either a symbolic
435 domain name, a numeric domain id, or a UUID, any of which uniquely
436 identify a domain.
437
438 attach-device domain file
439
440 Attach a device defined by the given XML file (file) to the speci‐
441 fied domain.
442
443
444 attach-disk domain source target --driver driver --subdriver subdriver
445 --type type --mode mode
446
447 Attach a new or existing disk device to the domain. A disk device
448 can be a removable media device, such as a CD or DVD drive. source
449 and target are paths for the files and devices. driver can be file,
450 tap or phy, depending on the kind of access. type can indicate
451 cdrom or floppy as an alternative to the default, disk. mode can
452 specify either readonly or shareable.
453
454 Note that in a Solaris Hardware-assisted Virtual Machine (HVM)
455 domU, you must run eject(1) in the domU to unlock a removable-media
456 device (for example, a CD device) before running the attach-disk
457 subcommand.
458
459
460 attach-interface domain type source --target target --mac mac --script
461 script --capped-bandwidth bandwidth --vlanid vid
462
463 Attach a new network interface to the domain. type can be either
464 network, to indicate a physical network device, or bridge, to indi‐
465 cate a bridge to a device. source indicates the source device. The
466 --target option allows you to specify the target device in the
467 guest. --mac allows you to specify the MAC address of the network
468 interface. --script specifies a path to a script handling a bridge.
469 --capped-bandwidth sets the bandwidth for this interface. Bandwidth
470 should be specified as an integer with one of the scale suffixes
471 (K, M, or G for Kbps, Mbps, or Gbps, respectively). Bandwidth will
472 be rounded up to 1.2M, if the input number is smaller than that.
473 --vlanid sets the VLAN ID for this interface to vid.
474
475
476 detach-device domain file
477
478 Detach a device defined by the given XML file (file) from the spec‐
479 ified domain. This subcommand takes the same type of XML descrip‐
480 tions as the subcommand attach-device.
481
482
483 detach-disk domain target
484
485 Detach a disk device from a domain. The target is the device as
486 seen from the domain.
487
488
489 detach-interface domain type --mac mac
490
491 Detach a network interface from a domain. type can be either net‐
492 work, to indicate a physical network device, or bridge, to indicate
493 a bridge to a device. It is recommended you use the --mac option to
494 distinguish between the interfaces if more than one is present in
495 the domain.
496
497
499 Example 1 Adding an ISO File to a Solaris Domain as a Virtual Disk
500
501
502 The following command adds an ISO file to a paravirtualized Solaris
503 domain as a virtual disk /dev/dsk/c0t1d0.
504
505
506 # virsh attach-disk --type cdrom --driver file --mode readonly \
507 domu-220 /data.iso xvdb
508
509
510
511 Example 2 Migrating a Domain, Relying on sshd Configuration
512
513
514 To migrate a domain named domu to a machine named foo over ssh(1),
515 first create the ssh connection:
516
517
518 # ssh -N -L 8003:localhost:8002 root@foo
519
520
521
522
523 ...then run the virsh migrate command:
524
525
526 # virsh migrate --live domu xen:/// xenmigr://localhost:8003
527
528
529
530
531 This example assumes that TCP port forwarding is allowed by sshd_con‐
532 fig(4). Note that this example does not require any modification of
533 xend(1M) properties.
534
535
536 Example 3 Migrating a Domain, Relying on xend Configuration
537
538
539 The following virsh migrate command requires the proper setting of the
540 xend xend-relocation-address and xend-relocation-hosts-allow proper‐
541 ties, as described in the xend(1M) man page.
542
543
544 # virsh migrate --live domu xen:/// xenmigr://remotehost
545
546
547
548 Example 4 Changing a CD in a Solaris HVM Guest Domain
549
550
551 The following sequence of commands attaches a CD drive to a guest
552 domain.
553
554
555
556 In the guest domain, eject the CD:
557
558
559 solaris-hvm# eject cdrom
560
561
562
563
564 Then, in the control domain, enter:
565
566
567 # virsh attach-disk solaris-hvm --type cdrom --driver file \
568 --mode readonly /isos/solaris.iso hdc
569
570
571
572
573 Finally, in the guest domain, load the CD:
574
575
576 solaris-hvm# rmformat
577
578
579
580 Example 5 Displaying dominfo Output
581
582
583 The following command displays information about domain 0.
584
585
586 # virsh dominfo Domain-0
587
588 Id: 0
589 Name: Domain-0
590 UUID: 00000000-0000-0000-0000-000000000000
591 OS Type: linux
592 State: running
593 CPU(s): 4
594 CPU time: 14436.6s
595 Max memory: no limit
596 Used memory: 3145728 kB
597
598
599
600
601 In the preceding output, note that the OS Type, linux, indicates a par‐
602 avirtualized domain.
603
604
605 Example 6 Attaching an Interface
606
607
608 The following command attaches a new network interface to a guest
609 domain, connected to the NIC e1000g0, with an auto-generated MAC
610 address (that is, the --mac option is omitted).
611
612
613 # virsh attach-interface pv-domu bridge e1000g0
614
615
616
617 Example 7 Attaching a Disk
618
619
620 The following command attaches a disk generated by vdiskadm(1M) to a
621 paravirtualized domain.
622
623
624 # virsh attach-disk domu-223 /disks/data.vdisk xvdb --driver \
625 tap --subdriver vdisk
626
627
628
630 /usr/share/lib/xml/rng/libvirt
631
632 Relax-NG schemas for the XML formats used by libvirt and virsh.
633
634
636 See attributes(5) for descriptions of the following attributes:
637
638
639
640
641 ┌─────────────────────────────┬─────────────────────────────┐
642 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
643 ├─────────────────────────────┼─────────────────────────────┤
644 │Availability │SUNWlibvirt │
645 ├─────────────────────────────┼─────────────────────────────┤
646 │Interface Stability │Volatile │
647 └─────────────────────────────┴─────────────────────────────┘
648
650 init(1M), vdiskadm(1M), xend(1M), xentop(1M), xm(1M), attributes(5),
651 xVM(5)
652
653
654 The ldm(1M) man page shipped with the LDoms software.
655
656
657 The virtualization library (libvirt) web site, at the date of this pub‐
658 lication, at:
659
660 http://www.libvirt.org
661
662
663
665 o Andrew Puch, apuch at redhat dot com
666
667 o Daniel Veillard, veillard at redhat dot com
668
669
670 The preceding authors credit the xm man page authored by:
671
672 o Sean Dague, sean at dague dot net
673
674 o Daniel Stekloff, dsteklof at us dot ibm dot com
675
677 Terminology differs between xm(1M) and virsh. In particular, the sus‐
678 pend and resume commands have different meanings.
679
680
681
682
683 virsh xm
684 ─────────────────────────────────────────────────────────────────────
685 suspend pause
686 resume unpause
687 save suspend (without output file argument)
688 restore resume (without output file argument)
689
690
691
692 Terminology for the domain states differs between LDoms utilities, such
693 as ldm, and virsh.
694
695
696
697
698 virsh LDoms utility
699 ───────────────────────────────────────────────────────────
700 running active
701 shut off inactive
702 in shutdown bound
703
704
705
706
707SunOS 5.11 9 Jul 2009 virsh(1M)