1virsh(1M)               System Administration Commands               virsh(1M)
2
3
4

NAME

6       virsh - management user interface for guest domains
7

SYNOPSIS

9       virsh subcommand [arguments]
10
11

DESCRIPTION

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

SUBCOMMANDS

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

EXAMPLES

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

FILES

630       /usr/share/lib/xml/rng/libvirt
631
632           Relax-NG schemas for the XML formats used by libvirt and virsh.
633
634

ATTRIBUTES

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

SEE ALSO

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

AUTHORS

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

NOTES

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)
Impressum