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
16 versions 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
19 Operating Systems concurrently on a single hardware system where the
20 basic resources are driven by a Linux instance. The library aims at
21 providing a long term stable C API. It currently supports Xen, QEmu,
22 KVM, LXC, OpenVZ, VirtualBox, OpenNebula, and VMware ESX.
23 The basic structure of most virsh usage is:
25 virsh <command> <domain-id> [OPTIONS]
27 Where command is one of the commands listed below, domain-id is the
29 numeric domain id, or the domain name (which will be internally
30 translated to domain id), and OPTIONS are command specific options.
31 There are a few exceptions to this rule in the cases where the command
32 in question acts on all domains, the entire machine, or directly on the
33 xen hypervisor. Those exceptions will be clear for each of those
34 commands.
35 The virsh program can be used either to run one command at a time by
37 giving the command as an argument on the command line, or as a shell if
38 no command is given in the command line, it will then start a minimal
39 interpreter waiting for your commands and the quit command will then
40 exit the program.
41
43 Most virsh operations rely upon the libvirt library being able to
44 connect to an already running libvirtd service. This can usually be
45 done using the command service libvirtd start.
46 Most virsh commands require root privileges to run due to the
48 communications channels used to talk to the hypervisor. Running as non
49 root will return an error.
50 Most virsh commands act synchronously, except maybe shutdown, setvcpus
52 and setmem. In those cases the fact that the virsh program returned,
53 may not mean the action is complete and you must poll periodically to
54 detect that the guest completed the operation.
55
57 The following commands are generic i.e. not specific to a domain.
58 help optional command
60 This prints a small synopsis about all commands available for virsh
61 help command will print out a detailed help message on that
62 command.
63 quit, exit
65 quit this interactive terminal
66 version
68 Will print out the major version info about what this built from.
69 Example
71 virsh version
73 Compiled against library: libvir 0.0.6
75 Using library: libvir 0.0.6
77 Using API: Xen 3.0.0
79 Running hypervisor: Xen 3.0.0
81 cd optional directory
83 Will change current directory to directory. The default directory
84 for the cd command is the home directory or, if there is no HOME
85 variable in the environment, the root directory.
86 This command is only available in interactive mode.
88 pwd Will print the current directory.
90 connect URI optional --readonly
92 (Re)-Connect to the hypervisor. When the shell is first started,
93 this is automatically run with the URI parameter requested by the
94 "-c" option on the command line. The URI parameter specifies how to
95 connect to the hypervisor. The documentation page at
96 <http://libvirt.org/uri.html> list the values supported, but the
97 most common are:
98 xen:///
100 this is used to connect to the local Xen hypervisor, this is
101 the default
102 qemu:///system
104 connect locally as root to the daemon supervising QEmu and KVM
105 domains
106 qemu:///session
108 connect locally as a normal user to his own set of QEmu and KVM
109 domains
110 lxc:///
112 connect to a local linux container
113 For remote access see the documentation page on how to make URIs.
115 The --readonly option allows for read-only connection
116 uri Prints the hypervisor canonical URI, can be useful in shell mode.
118 hostname
120 Print the hypervisor hostname.
121 nodeinfo
123 Returns basic information about the node, like number and type of
124 CPU, and size of the physical memory.
125 capabilities
127 Print an XML document describing the capabilities of the hypervisor
128 we are currently connected to. This includes a section on the host
129 capabilities in terms of CPU and features, and a set of description
130 for each kind of guest which can be virtualized. For a more
131 complete description see:
132 <http://libvirt.org/formatcaps.html> The XML also show the NUMA
133 topology information if available.
134 list optional --inactive --all
136 Prints information about one or more domains. If no domains are
137 specified it prints out information about running domains.
138 An example format for the list is as follows:
140 virsh list
142 Id Name State
143 ----------------------------------
145 0 Domain-0 running
147 2 fedora paused
148 Name is the name of the domain. ID the domain numeric id. State
150 is the run state (see below).
151 STATES
153 The State field lists 7 states for a domain, and which ones the
155 current domain is in.
156 running
158 The domain is currently running on a CPU
159 idle
161 The domain is idle, and not running or runnable. This can be
162 caused because the domain is waiting on IO (a traditional wait
163 state) or has gone to sleep because there was nothing else for
164 it to do.
165 paused
167 The domain has been paused, usually occurring through the
168 administrator running virsh suspend. When in a paused state
169 the domain will still consume allocated resources like memory,
170 but will not be eligible for scheduling by the hypervisor.
171 shutdown
173 The domain is in the process of shutting down, i.e. the guest
174 operating system has been notified and should be in the process
175 of stopping its operations gracefully.
176 shut off
178 The domain is not running. Usually this indicates the domain
179 has been shut down completely, or has not been started.
180 crashed
182 The domain has crashed, which is always a violent ending.
183 Usually this state can only occur if the domain has been
184 configured not to restart on crash.
185 dying
187 The domain is in process of dying, but hasn't completely
188 shutdown or crashed.
189 freecell optional cellno
191 Prints the available amount of memory on the machine or within a
192 NUMA cell if cellno is provided.
193 cpu-baseline FILE
195 Compute baseline CPU which will be supported by all host CPUs given
196 in <file>. The list of host CPUs is built by extracting all <cpu>
197 elements from the <file>. Thus, the <file> can contain either a set
198 of <cpu> elements separated by new lines or even a set of complete
199 <capabilities> elements printed by capabilities command.
200 cpu-compare FILE
202 Compare CPU definition from XML <file> with host CPU. The XML
203 <file> may contain either host or guest CPU definition. The host
204 CPU definition is the <cpu> element and its contents as printed by
205 capabilities command. The guest CPU definition is the <cpu> element
206 and its contents from domain XML definition. For more information
207 on guest CPU definition see:
208 <http://libvirt.org/formatdomain.html#elementsCPU>
209
211 The following commands manipulate domains directly, as stated
212 previously most commands take domain-id as the first parameter. The
213 domain-id can be specified as an short integer, a name or a full UUID.
214 autostart optional --disable domain-id
216 Configure a domain to be automatically started at boot.
217 The option --disable disables autostarting.
219 console domain-id
221 Connect the virtual serial console for the guest.
222 create FILE optional --console --paused
224 Create a domain from an XML <file>. An easy way to create the XML
225 <file> is to use the dumpxml command to obtain the definition of a
226 pre-existing guest. The domain will be paused if the --paused
227 option is used and supported by the driver; otherwise it will be
228 running. If --console is requested, attach to the console after
229 creation.
230 Example
232 virsh dumpxml <domain-id> > domain.xml
234 edit domain.xml
235 virsh create < domain.xml
236 define FILE
238 Define a domain from an XML <file>. The domain definition is
239 registered but not started.
240 destroy domain-id
242 Immediately terminate the domain domain-id. This doesn't give the
243 domain OS any chance to react, and it's the equivalent of ripping
244 the power cord out on a physical machine. In most cases you will
245 want to use the shutdown command instead.
246 domblkstat domain block-device
248 Get device block stats for a running domain.
249 domifstat domain interface-device
251 Get network interface stats for a running domain.
252 dommemstat domain
254 Get memory stats for a running domain.
255 domblkinfo domain block-device
257 Get block device size info for a domain.
258 dominfo domain-id
260 Returns basic information about the domain.
261 domuuid domain-name-or-id
263 Convert a domain name or id to domain UUID
264 domid domain-name-or-uuid
266 Convert a domain name (or UUID) to a domain id
267 domjobabort domain-id-or-uuid
269 Abort the currently running domain job.
270 domjobinfo domain-id-or-uuid
272 Returns information about jobs running on a domain.
273 domname domain-id-or-uuid
275 Convert a domain Id (or UUID) to domain name
276 domstate domain-id
278 Returns state about a running domain.
279 domxml-from-native format config
281 Convert the file config in the native guest configuration format
282 named by format to a domain XML format.
283 domxml-to-native format xml
285 Convert the file xml in domain XML format to the native guest
286 configuration format named by format.
287 dump domain-id corefilepath
289 Dumps the core of a domain to a file for analysis.
290 dumpxml domain-id optional --inactive --security-info --update-cpu
292 Output the domain information as an XML dump to stdout, this format
293 can be used by the create command. Additional options affecting the
294 XML dump may be used. --inactive tells virsh to dump domain
295 configuration that will be used on next start of the domain as
296 opposed to the current domain configuration. Using --security-info
297 security sensitive information will also be included in the XML
298 dump. --update-cpu updates domain CPU requirements according to
299 host CPU.
300 edit domain-id
302 Edit the XML configuration file for a domain.
303 This is equivalent to:
305 virsh dumpxml domain > domain.xml
307 edit domain.xml
308 virsh define domain.xml
309 except that it does some error checking.
311 The editor used can be supplied by the $VISUAL or $EDITOR
313 environment variables, and defaults to "vi".
314 managedsave domain-id
316 Ask libvirt to save a running domain state in a place managed by
317 libvirt. If libvirt is asked to restart the domain later on it
318 will resume it from the saved domain state (and the state is
319 discarded).
320 managedsave-remove domain-id
322 Remove the managed save file for a domain if it exists. The next
323 time the domain is started it will not restore to its previous
324 state but instead will do a full boot.
325 migrate optional --live --suspend domain-id desturi migrateuri
327 Migrate domain to another host. Add --live for live migration;
328 --suspend leaves the domain paused on the destination host. The
329 desturi is the connection URI of the destination host, and
330 migrateuri is the migration URI, which usually can be omitted.
331 migrate-setmaxdowntime domain-id downtime
333 Set maximum tolerable downtime for a domain which is being live-
334 migrated to another host. The downtime is a number of milliseconds
335 the guest is allowed to be down at the end of live migration.
336 reboot domain-id
338 Reboot a domain. This acts just as if the domain had the reboot
339 command run from the console. The command returns as soon as it
340 has executed the reboot action, which may be significantly before
341 the domain actually reboots.
342 The exact behavior of a domain when it reboots is set by the
344 on_reboot parameter in the domain's XML definition.
345 restore state-file
347 Restores a domain from an virsh save state file. See save for more
348 info.
349 save domain-id state-file
351 Saves a running domain to a state file so that it can be restored
352 later. Once saved, the domain will no longer be running on the
353 system, thus the memory allocated for the domain will be free for
354 other domains to use. virsh restore restores from this state file.
355 This is roughly equivalent to doing a hibernate on a running
357 computer, with all the same limitations. Open network connections
358 may be severed upon restore, as TCP timeouts may have expired.
359 schedinfo optional --set parameter=value domain-id
361 schedinfo optional --weight number optional --cap number domain-id
362 Allows you to show (and set) the domain scheduler parameters. The
363 parameters available for each hypervisor are:
364 LXC, QEMU/KVM (posix scheduler): cpu_shares
366 Xen (credit scheduler): weight, cap
368 ESX (allocation scheduler): reservation, limit, shares
370 Note: The cpu_shares parameter has a valid value range of 0-262144.
372 Note: The weight and cap parameters are defined only for the
374 XEN_CREDIT scheduler and are now DEPRECATED.
375 setmem domain-id kilobytes
377 Change the current memory allocation in the guest domain. This
378 should take effect immediately. The memory limit is specified in
379 kilobytes.
380 For Xen, you can only adjust the memory of a running domain if the
382 domain is paravirtualized or running the PV balloon driver.
383 setmaxmem domain-id kilobytes
385 Change the maximum memory allocation limit in the guest domain.
386 This should not change the current memory use. The memory limit is
387 specified in kilobytes.
388 setvcpus domain-id count
390 Change the number of virtual CPUs active in the guest domain. Note
391 that count may be limited by host, hypervisor or limit coming from
392 the original description of domain.
393 For Xen, you can only adjust the virtual CPUs of a running domain
395 if the domain is paravirtualized.
396 shutdown domain-id
398 Gracefully shuts down a domain. This coordinates with the domain
399 OS to perform graceful shutdown, so there is no guarantee that it
400 will succeed, and may take a variable length of time depending on
401 what services must be shutdown in the domain.
402 The exact behavior of a domain when it shuts down is set by the
404 on_shutdown parameter in the domain's XML definition.
405 start domain-name optional --console --paused
407 Start a (previously defined) inactive domain. The domain will be
408 paused if the --paused option is used and supported by the driver;
409 otherwise it will be running. If --console is requested, attach to
410 the console after creation.
411 suspend domain-id
413 Suspend a running domain. It is kept in memory but won't be
414 scheduled anymore.
415 resume domain-id
417 Moves a domain out of the suspended state. This will allow a
418 previously suspended domain to now be eligible for scheduling by
419 the underlying hypervisor.
420 ttyconsole domain-id
422 Output the device used for the TTY console of the domain. If the
423 information is not available the processes will provide an exit
424 code of 1.
425 undefine domain-id
427 Undefine the configuration for an inactive domain. Since it's not
428 running the domain name or UUID must be used as the domain-id.
429 vcpuinfo domain-id
431 Returns basic information about the domain virtual CPUs, like the
432 number of vCPUs, the running time, the affinity to physical
433 processors.
434 vcpupin domain-id vcpu cpulist
436 Pin domain VCPUs to host physical CPUs. The vcpu number must be
437 provided and cpulist is a comma separated list of physical CPU
438 numbers.
439 vncdisplay domain-id
441 Output the IP address and port number for the VNC display. If the
442 information is not available the processes will provide an exit
443 code of 1.
444
446 The following commands manipulate devices associated to domains. The
447 domain-id can be specified as an short integer, a name or a full UUID.
448 To better understand the values allowed as options for the command
449 reading the documentation at <http://libvirt.org/formatdomain.html> on
450 the format of the device sections to get the most accurate set of
451 accepted values.
452 attach-device domain-id FILE
454 Attach a device to the domain, using a device definition in an XML
455 file. See the documentation to learn about libvirt XML format for
456 a device. For cdrom and floppy devices, this command only replaces
457 the media within the single existing device; consider using update-
458 device for this usage.
459 attach-disk domain-id source target optional --driver driver
461 --subdriver subdriver --type type --mode mode
462 Attach a new disk device to the domain. source and target are
463 paths for the files and devices. driver can be file, tap or phy
464 depending on the kind of access. type can indicate cdrom or floppy
465 as alternative to the disk default, although this use only replaces
466 the media within the existing virtual cdrom or floppy device;
467 consider using update-device for this usage instead. mode can
468 specify the two specific mode readonly or shareable.
469 attach-interface domain-id type source optional --target target --mac
471 mac --script script
472 Attach a new network interface to the domain. type can be either
473 network to indicate a physical network device or bridge to indicate
474 a bridge to a device. source indicates the source device. target
475 allows to indicate the target device in the guest. mac allows to
476 specify the MAC address of the network interface. script allows to
477 specify a path to a script handling a bridge instead of the default
478 one.
479 detach-device domain-id FILE
481 Detach a device from the domain, takes the same kind of XML
482 descriptions as command attach-device.
483 detach-disk domain-id target
485 Detach a disk device from a domain. The target is the device as
486 seen from the domain.
487 detach-interface domain-id type optional --mac mac
489 Detach a network interface from a domain. type can be either
490 network to indicate a physical network device or bridge to indicate
491 a bridge to a device. It is recommended to use the mac option to
492 distinguish between the interfaces if more than one are present on
493 the domain.
494 update-device domain-id file optional --persistent
496 Update the characteristics of a device associated with domain-id,
497 based on the device definition in an XML file. If the --persistent
498 option is used, the changes will affect the next boot of the
499 domain. See the documentation to learn about libvirt XML format
500 for a device.
501
503 The following commands manipulate networks. Libvirt has the capability
504 to define virtual networks which can then be used by domains and linked
505 to actual network devices. For more detailed information about this
506 feature see the documentation at
507 <http://libvirt.org/formatnetwork.html> . A lot of the command for
508 virtual networks are similar to the one used for domains, but the way
509 to name a virtual network is either by its name or UUID.
510 net-autostart network optional --disable
512 Configure a virtual network to be automatically started at boot.
513 The --disable option disable autostarting.
514 net-create file
516 Create a virtual network from an XML file, see the documentation to
517 get a description of the XML network format used by libvirt.
518 net-define file
520 Define a virtual network from an XML file, the network is just
521 defined but not instantiated.
522 net-destroy network
524 Destroy a given virtual network specified by its name or UUID. This
525 takes effect immediately.
526 net-dumpxml network
528 Output the virtual network information as an XML dump to stdout.
529 net-edit network
531 Edit the XML configuration file for a network.
532 This is equivalent to:
534 virsh net-dumpxml network > network.xml
536 edit network.xml
537 virsh net-define network.xml
538 except that it does some error checking.
540 The editor used can be supplied by the $VISUAL or $EDITOR
542 environment variables, and defaults to "vi".
543 net-list optional --inactive or --all
545 Returns the list of active networks, if --all is specified this
546 will also include defined but inactive networks, if --inactive is
547 specified only the inactive ones will be listed.
548 net-name network-UUID
550 Convert a network UUID to network name.
551 net-start network
553 Start a (previously defined) inactive network.
554 net-undefine network
556 Undefine the configuration for an inactive network.
557 net-uuid network-name
559 Convert a network name to network UUID.
560
562 The following commands manipulate storage pools. Libvirt has the
563 capability to manage various storage solutions, including files, raw
564 partitions, and domain-specific formats, used to provide the storage
565 volumes visible as devices within virtual machines. For more detailed
566 information about this feature, see the documentation at
567 <http://libvirt.org/formatstorage.html> . A lot of the commands for
568 pools are similar to the ones used for domains.
569 find-storage-pool-sources type optional srcSpec
571 Returns XML describing all storage pools of a given type that could
572 be found. If srcSpec is provided, it is a file that contains XML
573 to further restrict the query for pools.
574 find-storage-pool-sources type optional host port
576 Returns XML describing all storage pools of a given type that could
577 be found. If host and port are provided, they control where the
578 query is performed.
579 pool-autostart pool-or-uuid optional --disable
581 Configure whether pool should automatically start at boot.
582 pool-build pool-or-uuid
584 Build a given pool.
585 pool-create file
587 Create and start a pool object from the XML file.
588 pool-create-as name --print-xml type optional source-host source-path
590 source-dev source-name <target> --source-format format
591 Create and start a pool object name from the raw parameters. If
592 --print-xml is specified, then print the XML of the pool object
593 without creating the pool. Otherwise, the pool has the specified
594 type.
595 pool-define file
597 Create, but do not start, a pool object from the XML file.
598 pool-define-as name --print-xml type optional source-host source-path
600 source-dev source-name <target> --source-format format
601 Create, but do not start, a pool object name from the raw
602 parameters. If --print-xml is specified, then print the XML of the
603 pool object without defining the pool. Otherwise, the pool has the
604 specified type.
605 pool-destroy pool-or-uuid
607 Destroy a given pool object. Libvirt will no longer manage the
608 storage described by the pool object, but the raw data contained in
609 the pool is not changed, and can be later recovered with pool-
610 create.
611 pool-delete pool-or-uuid
613 Destroy the resources used by a given pool object. This operation
614 is non-recoverable. The pool object will still exist after this
615 command.
616 pool-dumpxml pool-or-uuid
618 Returns the XML information about the pool object.
619 pool-edit pool-or-uuid
621 Edit the XML configuration file for a storage pool.
622 This is equivalent to:
624 virsh pool-dumpxml pool > pool.xml
626 edit pool.xml
627 virsh pool-define pool.xml
628 except that it does some error checking.
630 The editor used can be supplied by the $VISUAL or $EDITOR
632 environment variables, and defaults to "vi".
633 pool-info pool-or-uuid
635 Returns basic information about the pool object.
636 pool-list optional --inactive --all --details
638 List pool objects known to libvirt. By default, only pools in use
639 by active domains are listed; --inactive lists just the inactive
640 pools, and --all lists all pools. The --details option instructs
641 virsh to additionally display pool persistence and capacity related
642 information where available.
643 pool-name uuid
645 Convert the uuid to a pool name.
646 pool-refresh pool-or-uuid
648 Refresh the list of volumes contained in pool.
649 pool-start pool-or-uuid
651 Start the storage pool, which is previously defined but inactive.
652 pool-undefine pool-or-uuid
654 Undefine the configuration for an inactive pool.
655 pool-uuid pool
657 Returns the UUID of the named pool.
658
660 vol-create pool-or-uuid FILE
661 Create a volume from an XML <file>. pool-or-uuid is the name or
662 UUID of the storage pool to create the volume in. FILE is the XML
663 <file> with the volume definition. An easy way to create the XML
664 <file> is to use the vol-dumpxml command to obtain the definition
665 of a pre-existing volume.
666 Example
668 virsh vol-dumpxml --pool storagepool1 appvolume1 > newvolume.xml
670 edit newvolume.xml
671 virsh vol-create differentstoragepool newvolume.xml
672 vol-create-from pool-or-uuid FILE [optional --inputpool pool-or-uuid]
674 vol-name-or-key-or-path
675 Create a volume, using another volume as input. pool-or-uuid is
676 the name or UUID of the storage pool to create the volume in. FILE
677 is the XML <file> with the volume definition. --inputpool pool-or-
678 uuid is the name or uuid of the storage pool the source volume is
679 in. vol-name-or-key-or-path is the name or key or path of the
680 source volume.
681 vol-create-as pool-or-uuid name capacity optional --allocation size
683 --format string --backing-vol vol-name-or-key-or-path
684 --backing-vol-format string
685 Create a volume from a set of arguments. pool-or-uuid is the name
686 or UUID of the storage pool to create the volume in. name is the
687 name of the new volume. capacity is the size of the volume to be
688 created, with optional k, M, G, or T suffix. --allocation size is
689 the initial size to be allocated in the volume, with optional k, M,
690 G, or T suffix. --format string is used in file based storage
691 pools to specify the volume file format to use; raw, bochs, qcow,
692 qcow2, vmdk. --backing-vol vol-name-or-key-or-path is the source
693 backing volume to be used if taking a snapshot of an existing
694 volume. --backing-vol-format string is the format of the snapshot
695 backing volume; raw, bochs, qcow, qcow2, vmdk, host_device.
696 vol-clone [optional --pool pool-or-uuid] vol-name-or-key-or-path name
698 Clone an existing volume. Less powerful, but easier to type,
699 version of vol-create-from. --pool pool-or-uuid is the name or
700 UUID of the storage pool to create the volume in. vol-name-or-key-
701 or-path is the name or key or path of the source volume. name is
702 the name of the new volume.
703 vol-delete [optional --pool pool-or-uuid] vol-name-or-key-or-path
705 Delete a given volume. --pool pool-or-uuid is the name or UUID of
706 the storage pool the volume is in. vol-name-or-key-or-path is the
707 name or key or path of the volume to delete.
708 vol-wipe [optional --pool pool-or-uuid] vol-name-or-key-or-path
710 Wipe a volume, ensure data previously on the volume is not
711 accessible to future reads. --pool pool-or-uuid is the name or
712 UUID of the storage pool the volume is in. vol-name-or-key-or-path
713 is the name or key or path of the volume to wipe.
714 vol-dumpxml [optional --pool pool-or-uuid] vol-name-or-key-or-path
716 Output the volume information as an XML dump to stdout. --pool
717 pool-or-uuid is the name or UUID of the storage pool the volume is
718 in. vol-name-or-key-or-path is the name or key or path of the
719 volume to output the XML of.
720 vol-info [optional --pool pool-or-uuid] vol-name-or-key-or-path
722 Returns basic information about the given storage volume. --pool
723 pool-or-uuid is the name or UUID of the storage pool the volume is
724 in. vol-name-or-key-or-path is the name or key or path of the
725 volume to return information for.
726 vol-list [optional --pool] pool-or-uuid optional --details
728 Return the list of volumes in the given storage pool. --pool pool-
729 or-uuid is the name or UUID of the storage pool. The --details
730 option instructs virsh to additionally display volume type and
731 capacity related information where available.
732 vol-pool [optional --uuid] vol-key-or-path
734 Return the pool name or UUID for a given volume. By default, the
735 pool name is returned. If the --uuid option is given, the pool UUID
736 is returned instead. vol-key-or-path is the key or path of the
737 volume to return the pool information for.
738 vol-path [optional --pool pool-or-uuid] vol-name-or-key
740 Return the path for a given volume. --pool pool-or-uuid is the
741 name or UUID of the storage pool the volume is in. vol-name-or-key
742 is the name or key of the volume to return the path for.
743 vol-name vol-key-or-path
745 Return the name for a given volume. vol-key-or-path is the key or
746 path of the volume to return the name for.
747 vol-key [optional --pool pool-or-uuid] vol-name-or-path
749 Return the volume key for a given volume. --pool pool-or-uuid is
750 the name or UUID of the storage pool the volume is in. vol-name-
751 or-path is the name or path of the volume to return the volume key
752 for.
753
755 The following commands manipulate "secrets" (e.g. passwords,
756 passphrases and encryption keys). Libvirt can store secrets
757 independently from their use, and other objects (e.g. volumes or
758 domains) can refer to the secrets for encryption or possibly other
759 uses. Secrets are identified using an UUID. See
760 <http://libvirt.org/formatsecret.html> for documentation of the XML
761 format used to represent properties of secrets.
762 secret-define file
764 Create a secret with the properties specified in file, with no
765 associated secret value. If file does not specify a UUID, choose
766 one automatically. If file specifies an UUID of an existing
767 secret, replace its properties by properties defined in file,
768 without affecting the secret value.
769 secret-dumpxml secret
771 Output properties of secret (specified by its UUID) as an XML dump
772 to stdout.
773 secret-set-value secret base64
775 Set the value associated with secret (specified by its UUID) to the
776 value Base64-encoded value base64.
777 secret-get-value secret
779 Output the value associated with secret (specified by its UUID) to
780 stdout, encoded using Base64.
781 secret-undefine secret
783 Delete a secret (specified by its UUID), including the associated
784 value, if any.
785 secret-list
787 Output a list of UUIDs of known secrets to stdout.
788
790 The following commands manipulate domain snapshots. Snapshots take the
791 disk, memory, and device state of a domain at a point-of-time, and save
792 it for future use. They have many uses, from saving a "clean" copy of
793 an OS image to saving a domain's state before a potentially destructive
794 operation. Snapshots are identified with a unique name. See
795 <http://libvirt.org/formatsnapshot.html> for documentation of the XML
796 format used to represent properties of snapshots.
797 snapshot-create domain xmlfile
799 Create a snapshot for domain domain with the properties specified
800 in xmlfile. The only properties settable for a domain snapshot are
801 the <name> and <description>; the rest of the fields are ignored,
802 and automatically filled in by libvirt. If xmlfile is completely
803 omitted, then libvirt will choose a value for all fields.
804 snapshot-current domain
806 Output the snapshot XML for the domain's current snapshot (if any).
807 snapshot-list domain
809 List all of the available snapshots for the given domain.
810 snapshot-dumpxml domain snapshot
812 Output the snapshot XML for the domain's snapshot named snapshot.
813 snapshot-revert domain snapshot
815 Revert the given domain to the snapshot specified by snapshot. Be
816 aware that this is a destructive action; any changes in the domain
817 since the snapshot was taken will be lost. Also note that the
818 state of the domain after snapshot-revert is complete will be the
819 state of the domain at the time the original snapshot was taken.
820 snapshot-delete domain snapshot --children
822 Delete the snapshot for the domain named snapshot. If this
823 snapshot has child snapshots, changes from this snapshot will be
824 merged into the children. If --children is passed, then delete
825 this snapshot and any children of this snapshot.
826
828 The following commands manipulate network filters. Network filters
829 allow filtering of the network traffic coming from and going to virtual
830 machines. Individual network traffic filters are written in XML and
831 may contain references to other network filters, describe traffic
832 filtering rules, or contain both. Network filters are referenced by
833 virtual machines from within their interface description. A network
834 filter may be referenced by multiple virtual machines' interfaces.
835 nwfilter-define xmlfile
837 Make a new network filter known to libvirt. If a network filter
838 with the same name already exists, it will be replaced with the new
839 XML. Any running virtual machine referencing this network filter
840 will have its network traffic rules adapted. If for any reason the
841 network traffic filtering rules cannot be instantiated by any of
842 the running virtual machines, then the new XML will be rejected.
843 nwfilter-undefine nwfilter-name
845 Delete a network filter. The deletion will fail if any running
846 virtual machine is currently using this network filter.
847 nwfilter-list
849 List all of the available network filters.
850 nwfilter-dumpxml nwfilter-name
852 Output the network filter XML.
853 nwfilter-edit nwfilter-name
855 Edit the XML of a network filter.
856 This is equivalent to:
858 virsh nwfilter-dumpxml myfilter > myfilter.xml
860 edit myfilter.xml
861 virsh nwfilter-define myfilter.xml
862 except that it does some error checking. The new network filter
864 may be rejected due to the same reason as mentioned in nwfilter-
865 define.
866 The editor used can be supplied by the $VISUAL or $EDITOR
868 environment variables, and defaults to "vi".
869
871 The following environment variables can be set to alter the behaviour
872 of "virsh"
873 VIRSH_DEFAULT_CONNECT_URI
875 The hypervisor to connect to by default. Set this to a URI, in the
876 same format as accepted by the connect option.
877 VISUAL
879 The editor to use by the edit and related options.
880 EDITOR
882 The editor to use by the edit and related options, if "VISUAL" is
883 not set.
884 LIBVIRT_DEBUG=LEVEL
886 Turn on verbose debugging of all libvirt API calls. Valid levels
887 are
888 · LIBVIRT_DEBUG=1
890 Messages at level DEBUG or above
892 · LIBVIRT_DEBUG=2
894 Messages at level INFO or above
896 · LIBVIRT_DEBUG=3
898 Messages at level WARNING or above
900 · LIBVIRT_DEBUG=4
902 Messages at level ERROR or above
904 For further information about debugging options consult
906 "http://libvirt.org/logging.html"
907
909 Report any bugs discovered to the libvirt community via the mailing
910 list "http://libvirt.org/contact.html" or bug tracker
911 "http://libvirt.org/bugs.html". Alternatively report bugs to your
912 software distributor / vendor.
913
915 Please refer to the AUTHORS file distributed with libvirt.
916 Based on the xm man page by:
918 Sean Dague <sean at dague dot net>
919 Daniel Stekloff <dsteklof at us dot ibm dot com>
920
922 Copyright (C) 2005, 2007-2010 Red Hat, Inc., and the authors listed in
923 the libvirt AUTHORS file.
924
926 virsh is distributed under the terms of the GNU LGPL v2+. This is free
927 software; see the source for copying conditions. There is NO warranty;
928 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
929
931 virt-install(1), virt-xml-validate(1), virt-top(1), virt-mem(1),
932 virt-df(1), <http://www.libvirt.org/>
933libvirt-0.8.3 2010-07-20 VIRSH(1)