6.2. Managing Guest Tools

This section explains how to install and uninstall guest tools in virtual machines. This functionality is required for Running Commands in Virtual Machines without Network Connectivity.

Note

To be able to use the vinfra CLI tool mentioned in this section, you may need to perform steps listed in “Providing Credentials” in the CLI Reference.

6.2.1. Installing Guest Tools in Linux Virtual Machines

To install guest tools in an existing Linux virtual machine, do the following on the controller node of your compute cluster:

  1. Create an image from a guest tools ISO image. There are two guest tools ISO images: vz-guest-tools-lin.iso for Linux and vz-guest-tools-win.iso for Windows, which are located in /usr/share/vz-guest-tools/. For example:

    # vinfra service compute image create vz-guest-tools-lin \
    --file /usr/share/vz-guest-tools/vz-guest-tools-lin.iso --os-distro linux
    Uploading image to server [Elapsed Time: 0:00:12] ...
    
  2. Create a volume from the image. You will need the image ID that you can obtain with vinfra service compute image list. For example:

    # vinfra service compute volume create vz-guest-tools-lin-vol --storage-policy default \
    --size 1 --image d9a01520-6634-48d5-9803-34e5c38d43d2
    
  3. Attach the guest tools volume to the virtual machine. You will need the IDs of the VM and the guest tools volume. You can obtain them with vinfra service compute server list and vinfra service compute volume list, respectively.

    # vinfra service compute server volume attach \
    --server 1d45a54b-0e20-4d5e-8f11-12c8b4f300db 1a40012a-7976-47a1-81f1-ff498cba90af
    +--------+--------------------------------------+
    | Field  | Value                                |
    +--------+--------------------------------------+
    | device | /dev/sdb                             |
    | id     | 1a40012a-7976-47a1-81f1-ff498cba90af |
    +--------+--------------------------------------+
    
  4. Run guest tools installer inside the VM.

    Note

    Guest tools rely on QEMU guest agent which is installed alongside the tools. The agent daemon/service qemu-ga must be running for the tools to work.

    Log in to the virtual machine, create a mount point for the optical drive with the guest tools image and run the installer:

    # mkdir /mnt/cdrom
    # mount /dev/sdb /mnt/cdrom
    # bash /mnt/cdrom/install
    

6.2.2. Installing Guest Tools in Windows Virtual Machines

Currently you can only attach volumes but not images (i.e. virtual HDDs but not CD-ROMs) to existing VMs. This makes it impossible to attach a guest tools ISO image to an existing Windows VM. Following are two workarounds that allow you to install guest tools in a Windows VM. Perform commands on the controller node of the compute cluster.

Note

Round up the size of volumes to be created from ISO images. E.g., if the OS distribution image is 2.6 GB, use size=3.

6.2.2.1. Method #1

Attach the guest tools ISO image alongside the OS distribution ISO image when creating a new Windows VM. For example:

# vinfra service compute server create newvm --network id=private --flavor medium \
--volume source=blank,size=64,boot-index=0,type=disk \
--volume source=image,id=e6548c13-8479-4460-ab85-5ed60ff0e930,size=3,boot-index=1,type=cdrom \
--volume source=image,id=2e06406a-4ca0-43bd-8bd4-3a3e8372f997,size=1,boot-index=2,type=cdrom

In this example, the first volume is the blank virtual HDD, the second volume is the OS distribution ISO image, and the third volume is the guest tools ISO image. Make sure to specify the correct boot order by means of the boot-index parameter.

6.2.2.2. Method #2

Power off the Windows VM, convert its system volume to a template image, and create a new Windows VM from the template, attaching the guest tools ISO image to it during creation. For example:

# vinfra service compute server stop 60247b5b-2eef-4fb3-9d0d-a87322511489
# vinfra service compute volume upload-to-image 7116d747-a1e1-4200-bd4a-25cc51ef006c | grep id
| id               | 79da5239-b2bb-4779-ada2-46cb8da8ba0e                              |
# vinfra service compute server create newvm --network id=private --flavor medium \
--volume source=image,id=79da5239-b2bb-4779-ada2-46cb8da8ba0e,size=64,boot-index=0,type=disk \
--volume source=image,id=2e06406a-4ca0-43bd-8bd4-3a3e8372f997,size=1,boot-index=1,type=cdrom

In this example, the first volume is the template of the original VM’s system disk and the second volume is the guest tools ISO image. Make sure to specify the correct boot order by means of the boot-index parameter.

Once the ISO is mounted inside the Windows VM, launch the installer in the AutoPlay window if autorun is enabled. Otherwise open the optical drive in Explorer and run setup.exe.

6.2.3. Uninstalling Guest Tools

The steps you need to perform to remove guest tools depend on the guest OS and are described in the following sections.

6.2.3.1. Uninstalling Guest Tools from Linux Virtual Machines

To uninstall guest tools from a Linux guest, log in to the virtual machine and do as follows:

  1. Remove the packages:

    1. On RPM-based systems (CentOS and other):

      # yum remove dkms-vzvirtio_balloon prl_nettool qemu-guest-agent-vz vz-guest-udev
      
    2. On DEB-based systems (Debian and Ubuntu):

      # apt-get remove vzvirtio-balloon-dkms prl-nettool qemu-guest-agent-vz vz-guest-udev
      

      If any of the packages listed above are not installed on your system, the command will fail. In this case, exclude these packages from the command and run it again.

  2. Remove the files:

    # rm -f /usr/bin/prl_backup /usr/share/qemu-ga/VERSION /usr/bin/install-tools \
    /etc/udev/rules.d/90-guest_iso.rules /usr/local/bin/fstrim-static /etc/cron.weekly/fstrim
    
  3. Reload the udev rules:

    # udevadm control --reload
    

After removing guest tools, restart the virtual machine.

6.2.3.2. Uninstalling Guest Tools from Windows Virtual Machines

To uninstall guest tools for Windows, log in to the virtual machine and do as follows:

  1. Remove QEMU device drivers from the device manager.

    Important

    Do not remove the VirtIO/SCSI hard disk driver and NetKVM network driver. Without the former, the VM will not boot; without the latter, the VM will lose network connectivity.

  2. Uninstall QEMU guest agent and guest tools from the list of installed applications.

  3. Stop and delete Guest Tools Monitor:

    > sc stop VzGuestToolsMonitor
    > sc delete VzGuestToolsMonitor
    
  4. Unregister Guest Tools Monitor from Event Log:

    > reg delete HKLM\SYSTEM\CurrentControlSet\services\eventlog\Application\VzGuestToolsMonitor
    
  5. Delete the autorun registry key for RebootNotifier:

    > reg delete HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run /v VzRebootNotifier
    
  6. Delete the C:\Program Files\Qemu-ga\ directory.

    If VzGuestToolsMonitor.exe is locked, close all the Event Viewer windows. If it remains locked, restart the eventlog service:

    > sc stop eventlog
    > sc start eventlog
    

After removing the guest tools, restart the virtual machine.