7.2. Managing Guest Tools

This section explains how to install and uninstall the guest tools. 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.

7.2.1. Installing Guest Tools

To be able to install the guest tools in virtual machines, you first need to create and upload compute images from the supplied guest tools ISO files located in /usr/share/vz-guest-tools/. Execute the following commands on the controller node of your compute cluster:

  • For Linux guest tools:

    # 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:05] ...
    
  • For Windows guest tools:

    # vinfra service compute image create vz-guest-tools-win \
    --file /usr/share/vz-guest-tools/vz-guest-tools-win.iso --os-distro windows
    Uploading image to server [Elapsed Time: 0:00:09] ...
    

Next, you need to attach the created image to a VM and run the guest tools installer. The steps differ for new and already existing VMs and are described in the following subsections.

7.2.1.1. Installing Guest Tools in New VMs

When you create a new VM, you can attach the guest tools image to it and install the guest tools after the operating system. To do this, perform the following steps on the controller node of your compute cluster:

  1. Create a new VM with the guest tools image. For example, to create a Linux VM centos, run:

    # vinfra service compute server create centos --network id=private --flavor medium \
    --volume source=blank,size=64,boot-index=0,type=disk \
    --volume source=image,id=centos7,size=3,boot-index=1,type=cdrom \
    --volume source=image,id=vz-guest-tools-lin,size=1,boot-index=2,type=cdrom
    

    Note

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

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

  2. Log in to the virtual machine and install an operating system in it.

  3. Run guest tools installer inside the VM:

    • Inside a Linux VM, create a mount point for the optical drive with the guest tools image and run the installer:

      # mkdir /mnt/cdrom
      # mount /dev/sr1 /mnt/cdrom
      # bash /mnt/cdrom/install
      
    • Inside a Windows VM, launch the installer in the AutoPlay window if autorun is enabled. Otherwise open the optical drive in Explorer and run setup.exe.

      After installing guest tools, restart 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.

7.2.1.2. Installing Guest Tools in Existing VMs

The steps you need to perform to install the guest tools in existing VMs depend on the guest OS type. They are described in the following subsections.

7.2.1.2.1. Installing Guest Tools in Existing Linux VMs

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

  1. Create a volume from the uploaded guest tools image. For example:

    # vinfra service compute volume create vz-guest-tools-lin-vol --storage-policy default \
    --size 1 --image vz-guest-tools-lin
    
  2. Attach the guest tools volume to the virtual machine. For example:

    # vinfra service compute server volume attach \
    --server centos vz-guest-tools-lin-vol
    +--------+--------------------------------------+
    | Field  | Value                                |
    +--------+--------------------------------------+
    | device | /dev/sdb                             |
    | id     | 1a40012a-7976-47a1-81f1-ff498cba90af |
    +--------+--------------------------------------+
    
  3. 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
    

    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.

7.2.1.2.2. Installing Guest Tools in Existing Windows VMs

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

  1. Power off the Windows VM. For example, to stop the win10 VM, run:

    # vinfra service compute server stop win10
    
  2. Convert its system volume to a template image. You will need the volume ID that you can obtain with vinfra service compute volume list. For example, to use the win10 VM boot volume, run:

    # vinfra service compute volume list | grep win10
    | 7116d747-a1e1-4200-bd4a-25cc51ef006c | win10/windows_10_pro_x64.iso/Boot volume   | <...> |
    | ef2f1979-7811-4df6-9955-07e2fc942858 | win10/windows_10_pro_x64.iso/CD/DVD volume | <...> |
    # vinfra service compute volume upload-to-image 7116d747-a1e1-4200-bd4a-25cc51ef006c | grep id
    | id               | 79da5239-b2bb-4779-ada2-46cb8da8ba0e
    
  3. Create a new Windows VM from the template, attaching the guest tools image to it during creation. For example:

    # 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=vz-guest-tools-win,size=1,boot-index=1,type=cdrom
    

    Note

    The size of volume to be created from a template image must be equal to or greater than the minimum volume size specified in the image metadata. You can learn the minimum volume size by using vinfra service compute image show <image_id> | grep min_disk.

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

  4. Once the image 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.

    After installing guest tools, restart 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.

7.2.2. 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.

7.2.2.1. Uninstalling Guest Tools from Linux VMs

To uninstall the 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.

7.2.2.2. Uninstalling Guest Tools from Windows VMs

To uninstall the 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.