In this article:
NAME
vmfix — detect and fix virtual machines issuesSYNOPSIS
| vmfix | [-Aabdhlnpqrsv] [directory …] |
DESCRIPTION
Detect and fix virtual machines issues, also provide a few cleaning functionalities.OPTIONS
Tests selection options
Test selection options order has no impact on the tests execution order.- -b
-
Delete temporary bakup directories.Especially when manipulating large files (like disk image files), vmtools(7) commands try to create temporary directories near to (and hopefully on the same partition than) the virtual machine being manipulated instead of using system’s default path.These directories should normally be automatically deleted, even after a normal error (in such case the directory content is automatically used for the rollback process). However, in case of a crash or a any other severe issue it is possible for some temporary backup directories to remain.
- -d
-
Delete work files (cosmetic).When a virtual machine is started, it generates a few files which won’t be deleted upon its exit (by default a PID file and a socket file allowing to access the Qemu monitor shell).The presence of these files is normal and do not cause any issue (except some warning message in applications like archival utilities related to the presence of socket files which, obviously, cannot be archived). This test allows to delete them to take the virtual machine home directories back to a clean and pristine state.
- -l
-
Delete lock files.vmtools(7) commands rely on lock files to prevent concurrent access and modification of a virtual machine. Normally these are transient files which should be deleted as soon as the associated operation ends, let alone when the command itself exits.In case of a crash or any other severe issue, unused lock files may remain in a virtual machine home directory, making it impossible to start or otherwise modify the associated virtual machine.
- -p
-
Fix parent-child link issues.Several vmtools(7) commands need to keep track of the parent and childs (forked) virtual machines. A double linked chaining is implemented between a parent and each of its childs. This link is properly updated when using commands such as vmmv(1) or vmrm(1) to manipulate virtual machine home directories.This link will may be broken typically when a virtual machine has been moved, renamed or deleted without using the aforementioned commands. This test will detect such incoherency and attempt to solve them.In order to fully solve a broken link betwen a parent and its child, it may be necessary to execute this test against each one of them (a recursive execution using -r may be also fine).See CAVEATS below for potential limitations. You may want to use vminfo(1) to ensure that the fixed virtual machines tree matches your expectation.
- -s
-
Fix storage image files path issues.This test is very similar to the parent-child test (see -p), except that it focuses on the storage image files path. This test checks the path pointing to the storage image file and also, if applicable, the QCow2 backing file path. Both of these paths are updated notably when moving a renaming a virtual machine using the vmmv(1), however they will become invalid if for instance the system’s mv(1) command is used instead.See CAVEATS below for potential limitations.
Other options
The other options are as follows:- -A
- Execute all tests, including the cosmetic ones (equivalent to -bdlps).
- -a
- Execute all defects tests (equivalent to -blps).
- -h
- Show usage information summary then exit.
- -n
- Do not modify anything, only check for issues.
- -q
-
Decrease verbosity. Add several -q options to decrease verbosity even more (-qq by default to get minimal output). See vmtools.conf(5) for more information about verbosity levels.See -v to increase the verbosity level.
- -r
- Enable recursive mode.
- -v
-
Increase verbosity. Add several -v options to increase verbosity even more (-vvv by default to get the most verbose output, including debugging messages). See vmtools.conf(5) for more information about verbosity levels.See -q to decrease the verbosity level.
ENVIRONMENT
- TMPDIR
- Default location to store temporary files, by default /tmp.
- XDG_CONFIG_HOME
- Location of user’s configuration files, by default ~/.config.
FILES
- /usr/local/lib/vmtools
- Libraries shared by the vmtools project utilities.
- /usr/local/share/vmtools/vmtools.conf
- Virtual machine default settings, see vmtools.conf(5).
- ~/.config/vmtools
- User overrides (if cfg_include_userhome is set to “yes”).
- /etc/vmtools
- System-wide overrides.
EXIT STATUS
- 0
- No issue has been found.
- 1
- An internal error occurred.
- 2
- Wrong usage.
- 3
- At least one of the selected tests has found an issue.
EXAMPLES
- Example 1:
-
Force to remove a lock preventing to start the current virtual machine:
cd ~/myVM vmfix -l
- Example 2:
-
Check that a virtual machine tree has no issue (simple reporting, the -n flag prevents any modification):
vmfix -ran /path/to/virtual_machines - Example 3:
-
Quickly remove all remaining lock files and temporary directories from a virtual machine tree (useful as a system startup script, cleaning-up the environment before any virtual machine gets started):
vmfix -rtl /path/to/virtual_machines
CAVEATS
-
After having found and solved one or several issues, it is recommended to run the vmfix command another time in order to ensure that there is no remaining issue.The command should produce no output and have a return code of 0 if there is no remaining issue.
- Some tests require to lock the targeted virtual machine. These tests will be ignored and a warning message dispayed if a locking issue has been detected or of some virtual machines are currently running.
-
The -p (parent-child issues) and -s (storage path issues) only attempt to fix situations considered as non-ambiguous. Facing more complex situations, they will bet on the safe side and limit themselves to reporting the issues found but not apply any fix.In such conditions, a manual fix may be required (always do a backup before doing any manual modification!):
- The parent and storage image paths are defined in the virtual machine settings file. The file name is defined by the cfg_file_vmsettings setting and is vm.settings by default.
- The childs paths are defined in the childs database file. The file name is defined by the cfg_file_childs setting and is childs.lst by default.
-
QCow2 files backing chain path is stored directly in the QCow2 binary file. It can be modified using the following command:
qemu-img rebase -u -b backing_file image_fileCheck qemu-img(1) for more information.