20.7. Managing a Virtual Machine Configuration
This section provides information about managing a virtual machine configuration.
20.7.1. Saving a Guest Virtual Machine's Configuration
The
virsh save [--bypass-cache] domain file [--xml string] [--running] [--paused] [--verbose] command stops the specified domain, saving the current state of the guest virtual machine's system memory to a specified file. This may take a considerable amount of time, depending on the amount of memory in use by the guest virtual machine. You can restore the state of the guest virtual machine with the virsh restore (Section 20.6.4, “Restoring a Guest Virtual Machine”) command.
The difference between the
virsh save command and the virsh suspend command, is that the virsh suspend stops the domain CPUs, but leaves the domain's qemu process running and its memory image resident in the host system. This memory image will be lost if the host system is rebooted.
The
virsh save command stores the state of the domain on the hard disk of the host system and terminates the qemu process. This enables restarting the domain from the saved state.
You can monitor the process of
virsh save with the virsh domjobinfo command and cancel it with the virsh domjobabort command.
The
virsh save command can take the following arguments:
--bypass-cache- causes the restore to avoid the file system cache but note that using this flag may slow down the restore operation.--xml- this argument must be used with an XML file name. Although this argument is usually omitted, it can be used to supply an alternative XML file for use on a restored guest virtual machine with changes only in the host-specific portions of the domain XML. For example, it can be used to account for the file naming differences in underlying storage due to disk snapshots taken after the guest was saved.--running- overrides the state recorded in the save image to start the guest virtual machine as running.--paused- overrides the state recorded in the save image to start the guest virtual machine as paused.--verbose- displays the progress of the save.
Example 20.8. How to save a guest virtual machine running configuration
The following example saves the guest1 virtual machine's running configuration to the
guest1-config.xml file:
# virsh save guest1 guest1-config.xml --running20.7.2. Defining a Guest Virtual Machine with an XML File
The
virsh define filename command defines a guest virtual machine from an XML file. The guest virtual machine definition in this case is registered but not started. If the guest virtual machine is already running, the changes the changes will take effect once the domain is shut down and started again.
Example 20.9. How to create a guest virtual machine from an XML file
The following example creates a virtual machine from the pre-existing guest1-config.xml XML file, which contains the configuration for the virtual machine:
# virsh define guest1-config.xml20.7.3. Updating the XML File That will be Used for Restoring a Guest Virtual Machine
Note
This command should only be used to recover from a situation where the guest virtual machine does not run properly. It is not meant for general use.
The
virsh save-image-define filename [--xml /path/to/file] [--running] [--paused] command updates the guest virtual machine's XML file that will be used when the virtual machine is restored used during the virsh restore command. The --xml argument must be an XML file name containing the alternative XML elements for the guest virtual machine's XML. For example, it can be used to account for the file naming differences resulting from creating disk snapshots of underlying storage after the guest was saved. The save image records if the guest virtual machine should be restored to a running or paused state. Using the arguments --running or --paused dictates the state that is to be used.
Example 20.10. How to save the guest virtual machine's running configuration
The following example updates the guest1-config.xml configuration file with the state of the corresponding running guest:
# virsh save-image-define guest1-config.xml --running20.7.4. Extracting the Guest Virtual Machine XML File
Note
This command should only be used to recover from a situation where the guest virtual machine does not run properly. It is not meant for general use.
The
virsh save-image-dumpxml file --security-info command will extract the guest virtual machine XML file that was in effect at the time the saved state file (used in the virsh save command) was referenced. Using the --security-info argument includes security sensitive information in the file.
Example 20.11. How to pull the XML configuration from the last save
The following example triggers a dump of the configuration file that was created the last time the guest virtual machine was saved. In this example, the resulting dump file is named guest1-config-xml:
# virsh save-image-dumpxml guest1-config.xml20.7.5. Editing the Guest Virtual Machine Configuration
Note
This command should only be used to recover from a situation where the guest virtual machine does not run properly. It is not meant for general use.
The
virsh save-image-edit <file> [--running] [--paused] command edits the XML configuration file that was created by the virsh save command. See Section 20.7.1, “Saving a Guest Virtual Machine's Configuration” for information on the virsh save command.
When the guest virtual machine is saved, the resulting image file will indicate if the virtual machine should be restored to a
--running or --paused state. Without using these arguments in the save-image-edit command, the state is determined by the image file itself. By selecting --running (to select the running state) or --paused (to select the paused state) you can overwrite the state that virsh restore should use.
Example 20.12. How to edit a guest virtual machine's configuration and restore the machine to running state
The following example opens a guest virtual machine's configuration file, named guest1-config.xml, for editing in your default editor. When the edits are saved, the virtual machine boots with the new settings:
# virsh save-image-edit guest1-config.xml --running