Skip to main content
Version: 3.2

Restore Specific Files or Folders of a VM

Applicable to Classic mode only

You can restore specific files or folders of a VM from a VM backup to the same VM. This is supported for KubeVirt VMs running either a Linux or a 64-bit Windows Server operating system.

note
  • When restoring specific files or folders from a VM backup, selecting a large number of items may result in large custom resource sizes, which can exceed system limits and cause the restore operation to fail.
    If this occurs, reduce the number of selected files or folders and retry the operation.
    You do not need to restore the entire VM to recover specific files or directories. During restore, you can select the disk that contains the required data and choose only the specific files or directories from that disk.
    This is especially useful for VMs with multiple disks, as it allows recovery of only the required content without restoring the full VM or all disks.
  • Only one restore operation for a specific VM is supported at a time. If you start another restore on the same VM, the system queues it and waits for the current restore to complete before processing it.

Requirements​

Ensure that the following prerequisites are met before you restore specific files or folders of a VM from a VM backup:

  • VM Status: VM is in running state.

  • Stork Version: For Linux VM file restore, upgrade Stork to 26.2.0 or later. For Windows Server VM file restore, upgrade Stork to 26.5.0 or later. For information on how to install and upgrade Stork, see Install Stork.

  • QEMU Guest Agent: The QEMU Guest Agent (qemu-guest-agent) is installed and running on the VM.

    note

    For Linux VMs with SELinux enabled, perform the following additional configurations:

    • The /etc/sysconfig/qemu-ga file includes guest-exec and guest-exec-status in the --allow-rpcs list.

      For example:

      FILTER_RPC_ARGS="--allow-rpcs=guest-sync-delimited,guest-sync,guest-ping,guest-get-time,guest-set-time,guest-info,guest-shutdown,guest-fsfreeze-status,guest-fsfreeze-freeze,guest-fsfreeze-freeze-list,guest-fsfreeze-thaw,guest-fstrim,guest-suspend-disk,guest-suspend-ram,guest-suspend-hybrid,guest-network-get-interfaces,guest-get-vcpus,guest-set-vcpus,guest-get-disks,guest-get-fsinfo,guest-set-user-password,guest-get-memory-blocks,guest-set-memory-blocks,guest-get-memory-block-info,guest-get-host-name,guest-get-users,guest-get-timezone,guest-get-osinfo,guest-get-devices,guest-ssh-get-authorized-keys,guest-ssh-add-authorized-keys,guest-ssh-remove-authorized-keys,guest-get-diskstats,guest-get-cpustats,guest-exec,guest-exec-status"
    • The SELinux environment is configured with the following settings:

      cat > qemu-ga-mount-complete.te << 'EOF'
      module qemu-ga-mount-complete 1.0;
      require {
      type virt_qemu_ga_t;
      type unlabeled_t;
      type fs_t;
      type mount_exec_t;
      type bin_t;
      type shell_exec_t;
      type fixed_disk_device_t;
      type virt_qemu_ga_tmp_t;
      type mount_var_run_t;
      type kernel_t;
      class filesystem { mount unmount getattr };
      class file { create write read open getattr setattr unlink execute execute_no_trans ioctl lock map };
      class dir { create write read open getattr setattr search add_name remove_name rmdir reparent mounton };
      class blk_file { read write open getattr ioctl };
      class process setsched;
      class capability { dac_override sys_admin };
      }
      #============= virt_qemu_ga_t ==============
      # Mount/Unmount Operations
      allow virt_qemu_ga_t fs_t:filesystem { mount unmount getattr };
      # Execute Permissions
      allow virt_qemu_ga_t mount_exec_t:file { execute execute_no_trans map };
      allow virt_qemu_ga_t bin_t:file { execute execute_no_trans };
      allow virt_qemu_ga_t shell_exec_t:file { execute execute_no_trans };
      # Device Access
      allow virt_qemu_ga_t fixed_disk_device_t:blk_file { read write open getattr ioctl };
      # Directory Mount Permissions
      allow virt_qemu_ga_t virt_qemu_ga_tmp_t:dir mounton;
      # System Access
      allow virt_qemu_ga_t mount_var_run_t:dir write;
      allow virt_qemu_ga_t kernel_t:process setsched;
      # File Operations on Mounted Filesystems
      allow virt_qemu_ga_t unlabeled_t:file { create write read open getattr setattr unlink ioctl lock };
      allow virt_qemu_ga_t unlabeled_t:dir { create write read open getattr setattr search add_name remove_name rmdir reparent };
      # Capabilities
      allow virt_qemu_ga_t self:capability { dac_override sys_admin };
      EOF

      checkmodule -M -m -o qemu-ga-mount-complete.mod qemu-ga-mount-complete.te
      # Create policy package
      semodule_package -o qemu-ga-mount-complete.pp -m qemu-ga-mount-complete.mod
      # Install the policy
      semodule -i qemu-ga-mount-complete.pp
    • For SELinux-enabled environment, an alternate restore path with the required permissions is configured.

      1. Create a custom recovery path. For example, /tmp/recovery
      mkdir -p /tmp/recovery
      1. Allow write access for qemu-guest-agent.
      chcon -t virt_qemu_ga_tmp_t /tmp/recovery
      1. Set the following permissions.
      chmod 755 /tmp/recovery
  • Windows Server VMs: For file or folder restore of a Windows Server VM, ensure the following additional requirements are met:

    • QEMU Guest Agent service: The QEMU Guest Agent is installed and running as a Windows service, and command execution (guest-exec) is enabled. Some Windows configurations disable guest command execution by default for security reasons.
    • PowerShell: PowerShell is installed and available in the system PATH. Windows Server Core editions without PowerShell are not supported.
    • PowerShell execution policy: The PowerShell execution policy allows command execution. If the policy is set to Restricted, the restore fails. Configure the execution policy as RemoteSigned or Bypass for the SYSTEM account.
    • Security software: Windows Defender, Windows Defender Application Control (WDAC), and third-party antivirus software do not block the QEMU Guest Agent or the PowerShell commands that it runs. If required, configure exceptions for qemu-ga.exe and PowerShell.
    • Permissions: The SYSTEM account that runs the QEMU Guest Agent has permission to bring disks online, access partitions, and copy files. Ensure that User Account Control (UAC) policies do not restrict these operations.
    note

    Hardened Windows Server environments, including those configured according to CIS benchmarks or DoD STIGs, might restrict command execution through the QEMU Guest Agent. Verify that the QEMU Guest Agent can run commands before performing a file or folder restore.

Supported operating systems, filesystems, and SELinux modes​

The following operating systems, filesystems, and SELinux modes are supported for files and folders restore from VM backups:

Linux VMs​

  • Supported Linux versions:

    • Ubuntu 22.04 and 24.04
    • RHEL 9.5
    • Debian 12
    • Oracle Linux Enterprise 7.9
    • Fedora 43
    • OpenSUSE 15.2
  • Supported filesystems:

    • ext3
    • ext4
    • XFS
    • BTRFS
    • FAT32
  • All SELinux modes

Windows Server VMs​

Only 64-bit Windows Server operating systems are supported.

  • Supported Windows Server versions:

    • Windows Server 2016
    • Windows Server 2019
    • Windows Server 2022
    • Windows Server 2025
  • Supported filesystems:

    • NTFS (New Technology File System)
    • ReFS (Resilient File System)
note

File or folder restore is not supported for the following on Windows Server VMs:

  • 32-bit Windows Server operating systems, and Windows Server versions that are no longer supported by Microsoft, such as Windows Server 2012 or earlier
  • Filesystems other than NTFS and ReFS, such as FAT32 and exFAT. FAT32 is supported for Linux VMs only.
  • Encrypted volumes. Ensure that the volumes are unencrypted, or unlock them manually before you start the restore.
  • Windows system state, registry keys, and application-specific attributes

Restore feasibility​

To understand restore feasibility for file-level and folders-level restore based on the backed-up entities (single VM or multiple VMs) and the backup status, see Supported restore types based on VM backup status.

Procedure​

Expected: a temporary drive during restore (Windows Server VMs)

When you restore files or folders to a Windows Server VM, a temporary drive may appear in the VM during the restore and is removed automatically when the restore completes. Windows assigns the next available drive letter (for example, F: or G:).

To restore specific files or folders of a VM from a VM backup, follow these steps:

  1. Log in to Portworx Backup web console.

  2. From the left navigation pane, click the Clusters icon .

  3. On the Clusters page, click the application cluster for which you have taken the backup.
    The system displays the application cluster page.

  4. Click the Applications tab, and select VM to view the list of VMs in the application cluster.

  5. Click Restore under the Actions column for the target VM.
    The system displays the Restore Options page, and prompts you to select the restore option.

  6. Select File or Folder Restore option.
    For information on the Default Restore and Custom Restore options, see Restore all resources of an Individual VM.
    The system displays the Restore (Backup) page.

  7. Select the required VM backup, and click Next.

    tip

    Use the timeframe filter to list the backups based on the required timeline such as last 24 hours, 1 week, one month, or a custom timeframe.

    The system displays the Restore (Backup) page and prompts you to specify the restore details.

  8. On the Restore (Backup) page, perform the following actions:

    1. On the Restore Details page, specify the following information, and click Next.

      • Enter the restore name: Enter a unique name for the restore. You can use this name to identify the restore operation in the Restore tab.
      • Select a Volume: Select the volume where the file or folder resides.
        The system displays the Path Details page.
    2. On the Path Details page, specify the path entries and click Next.

      • File/folder relative source path: Enter the relative path of the file or folder on the drive.

        For example:

        • To restore a README.md file that is located on vda drive which is mounted at /mnt/datadisk, the file is referenced on the VM as /mnt/datadisk/README.md.

          In this case, the relative path for restoring README.md file is README.md.

        • To restore a README.md file that is located in the downloads folder, the file is referenced on the VM as /mnt/datadisk/downloads/README.md.

          In this case, the relative path for restoring README.md file is: downloads/README.md

        For a Windows Server VM, use Windows-style paths with backslashes (\). For example, to restore E:\reports\report.docx, select the volume for the E: drive and enter the relative source path reports\report.docx.

      • Is partitioned?: Select this checkbox if the file or folder to restore from the drive are on partitioned drive.

      • File/folder Partition path: Enter the disk partition on which the file or folder resides. For a Linux VM, use the lowercase Linux partition device name, for example, sdb1 or vda2. Do not capitalize the device letter. For a Windows Server VM, enter the partition number (not a drive letter), for example, 1, 2, or 3, matching the partition number shown by Windows Disk Management or Get-Partition. Drive letters such as C: or E: are not accepted.

      • Destination: Select the destination path for the restore.

        caution

        If SELinux is in Enforcing mode on the guest VM, you must select the Alternate path option and use the recovery path that you configured in the SELinux configuration steps (see Requirements). Restoring to the Original path is not supported under SELinux Enforcing mode, because the original target location does not have the required SELinux label.

        • Original - To restore the file or folder in the VM at the original source path. This is the default option.
          This option is unavailable if the selected drive (source path drive) is no longer attached to the running VM.
        warning

        This option overwrites the file or folder at the original source path with the data from the backup. For a folder, the backed-up content is merged into the existing folder: files with the same name are overwritten by the backup, and files that already exist at the destination but are not part of the backup are preserved (they are not deleted). Overwriting a file cannot be undone, so make sure you no longer need the current contents at the source path before you restore to the original path. To avoid overwriting existing data, use the Alternate path option instead.

        • Alternate path - To restore the selected file or folder in the VM at an alternate path.
          The alternate path is auto-selected if the selected drive exists in backup but is no longer attached to the running VM.
          • File/folder alternate path: Enter the absolute alternate path to restore the file or folder in the VM. For example, /home/myfiles/recovered_instances on a Linux VM, or E:\Recovered on a Windows Server VM.
          • Is Directory: Select this checkbox if the source path specified in File/Folder relative source path field is a folder.
            Selecting this option restores the entire folder tree.
          note
          • Ensure that there is enough space to restore the specified file or folder at the alternate path.
          • The alternate path must be an absolute path and not a relative path. For example, /tmp/recoverFromBackup or /mnt/newdrive/README.md.
          • If you have altered or deleted the disk partition from the VM, ensure that you provide the correct alternate destination path for the file or folder for successful restore.

      Click Add another File/Folder to add multiple path entries for the files or folder to restore.

      The system displays the Review & Restore page.

    3. On the Review & Restore page, review the restore configuration summary, and click Restore.

In this topic: