WiP: rework migrate to XCP-ng documentation

docs/installation/migrate-to-xcp-ng.md

@@ -8,9 +8,29 @@ How to migrate from VMware, KVM, etc. to XCP-ng.
 
 This documentation will help you to make a migration to XCP-ng, from any most common other virtualization platform (VMware, KVM, etc.)
 
-:::note
-OVA import method will miss the information if the VM is running BIOS or UEFI mode. Double check your settings on your original system, and then enable (or not) UEFI on XCP-ng side for the destination VM. You can do so in VM advanced tab in Xen Orchestra.
-:::
+## 📋 Prerequisites
+
+Before migrating your VMs, make sure to check the following:
+
+### Uninstall Existing Guest Tools
+
+To avoid conflicts with XCP-ng guest tools, uninstall any existing VM tools (such as VMware Tools or QEMU Guest Agent) from the VM.
+
+### Install Xen Drivers
+
+On some systems (especially RHEL-based and SLES distributions) Xen drivers are not installed by default. Migrating a VM without these drivers can prevent the OS from detecting disks and network interfaces.
+
+Before shutting down the VM, run this command to install the drivers:
+
+```
+dracut --add-drivers "xen-blkfront xen-netfront" --force
+```
+
+### Install XCP-ng Guest Tools After Migration
+
+Guest tools are essential for proper VM operation (especially on Windows). Be sure to install the XCP-ng guest tools after the migration.
+
+See the [guest tools documentation](../vms/vms.md#%EF%B8%8F-guest-tools) for more details.
 
 ## 🇽 From XenServer
 
@@ -26,10 +46,6 @@ If you are running Xen on your usual distro (Debian, Ubuntu…), you are using `
 
 Check [the README](https://github.com/xcp-ng/xen2xcp/blob/master/README.md) for usage instructions.
 
-## 📦 From Virtualbox
-
-Export your VM in OVA format, and use Xen Orchestra to import it. If you have an issue on VM boot, check the [VMware](#-from-vmware) section.
-
 ## 🇻 From VMware
 
 :::warning
@@ -102,48 +118,6 @@ To do this:
 
 Now, you can see the transfer progress in the **Task** view of the Xen Orchestra UI. As soon it's done, you can boot the VM directly!
 
-### OVA
-
-You can also export an OVA from VMware and import an OVA into Xen Orchestra.
-
-An OVA is a big, single file using the standard Open Virtualization Format. The OVA contains an XML describing the metadata (VM name, description, etc.) and your disks in the VMDK format.
-
-:::tip
-To skip Windows activation if the system was already activated, collect info about the network cards used in the Windows VM (ipconfig /all) and use the same MAC address(es) when creating interfaces in XCP-ng.
-:::
-
-:::warning
-
-- **Downtime**: The OVA can only be exported while the VM is off (except if you export a clone, but all blocks written after the clone won't be on the imported VM. If you can sync after, it's fine!). This can take a while, and your VMs won't be reachable until it's fully exported AND imported on destination.
-- **Storage**: You need an intermediary storage where you can export then import the OVA file. If your VMs are small, it's OK.
-- **Manual process**: Even if it's simple to do, it can be cumbersome if you have a lot of VMs to migrate.
-:::
-
-Importing a VMware Linux VM, you may encounter an error similar to this on boot:
-
-`dracut-initqueue[227]: Warning: /dev/mapper/ol-root does not exist`
-
-The fix for this is installing some xen drivers *before* exporting the VM from VMware:
-
-`dracut --add-drivers "xen-blkfront xen-netfront" --force`
-
-[See here](https://unix.stackexchange.com/questions/278385/boot-problem-in-linux/496037#496037) for more details. Once the imported VM is properly booted, remove any VMware related tooling and be sure to install [Xen guest tools](../../vms).
-
-### CloneZilla
-
-An alternative to using OVA. 
-
-1. Insert a CloneZilla live CD in your existing VMware VM, and boot on it. In the meantime, you also have a VM on the destination with the right metadata (same name and disks), which you'll also boot with CloneZilla.
-
-2. From the VM console, you can tell the source VM running CloneZilla to send all the blocks to the destination VM, also running CloneZilla. 
-
-3. As soon it's done, you can safely shut down the original VM and boot the copy on destination!
-
-:::warning
-- **Downtime**: Even if the downtime will be reduced compared to using OVA, you still need to run the export/import process while the VM is off.
-- **Setup time**: Not complex, but various operations are needed until you can start the replication for one VM. If you have a lot of VMs, this can take some effort.
-:::
-
 ### Local migration (same host)
 
 :::tip
@@ -218,16 +192,7 @@ There's two options, both requiring to export your Hyper-V VM disk in VHD format
   Convert-VHD -Path <source path> -DestinationPath <destination path> -VHDType Dynamic
   ```
 
-### Import the VHD in Xen Orchestra
-
-In the left menu, go for "Import" then "Disk". Select the destination SR, and then add your VHD file into it. Depending on the VHD file size, it might take some time. The upload progress can be tracked in another XO tab, in the "Task" menu.
-
-When the disk is imported, you can:
-
-4. Create a VM with the appropriate template, **without any disk in it**
-5. Attach the previously imported disk (VM/Disk/Attach an existing disk)
-6. Boot the VM
-7. Install the tools
+Then [import your VHD](../../installation/migrate-to-xcp-ng/#import-the-vhd)
 
 ### Alternative: direct VHD copy
 
@@ -262,54 +227,127 @@ As soon you did scan the SR, the new disk is visible in the SR/disk view. Don't
 If you lost ability to extend migrated volume (opening journal failed: -2) You need to move disk to another storage, VM should be ON during moving process. This issue can occur when vhd files was directly copied to storage folder.
 :::
 
-## 🇰 From KVM (Libvirt)
+## 🇰 From KVM (Libvirt, Proxmox and others)
+
+First, shut down the virtual machine. If the `qemu-img` command is not available, you can install it as part of the the `qemu-utils` package on your computer or server.
+
+Next, run this command to convert the QCOW2 disk to a VHD format:
+
+```
+qemu-img convert -O vpc disk.qcow2 `uuidgen`.vhd
+```
+
+Then [import your VHD](../../installation/migrate-to-xcp-ng/#import-the-vhd)
+
+## 🔄 Alternatives 
+
+### OVA
+
+You can also export an OVA from your hypervisor (VirtualBox, VMWare...) and import an OVA into Xen Orchestra.
+
+An OVA is a big, single file using the standard Open Virtualization Format. The OVA contains an XML describing the metadata (VM name, description, etc.) and your disks in the VMDK format.
+
+:::tip
+To skip Windows activation in case the system is already activated, run `ipconfig /all` to collect information on the network cards used in the Windows VM, and use the same MAC address(es) when creating interfaces in XCP-ng.
+:::
+
+![](../assets/img/import-ova.png)
+
+:::warning
+
+- **Downtime**: The OVA can only be exported while the VM is off, except if you export a clone. However, all blocks written after the clone won't be on the imported VM. If you can sync after, it's fine!. This can take a while, and your VMs won't be reachable until it's fully exported AND imported on destination.
+- **Storage**: You need an intermediary storage where you can export then import the OVA file. If your VMs are small, it's OK.
+- **Manual process**: Even if it's simple to do, it can be cumbersome if you have a lot of VMs to migrate.
+:::
+
 
-Related forum thread: [https://xcp-ng.org/forum/topic/1465/migrating-from-kvm-to-xcp-ng](https://xcp-ng.org/forum/topic/1465/migrating-from-kvm-to-xcp-ng)
+:::note
+The OVA import process does not retain whether the VM was using BIOS or UEFI. Be sure to check this setting on the source system, then configure the destination VM accordingly. You can enable or disable UEFI in the Advanced tab of the VM settings in Xen Orchestra.
+:::
 
-_Due the fact I have only server here, I have setup a "buffer" machine on my desktop to backup and convert the VM image file._
+### CloneZilla
 
-* Install the dracut packages : yum install dracut-config-generic dracut-network
+Clonezilla is a free and open-source disk imaging and cloning tool used for system backups, recovery, and deployment.
 
-  `dracut --add-drivers xen-blkfront -f /boot/initramfs-$(uname -r).img $(uname -r)`
+1. Insert a CloneZilla live CD in your existing VM, and boot on it. In the meantime, you also have a VM on the destination with the right metadata (same name and disks), which you'll also boot with CloneZilla.
 
-  If your VMs are in BIOS mode :
+2. From the VM console, you can tell the source VM running CloneZilla to send all the blocks to the destination VM, also running CloneZilla. 
 
-  `dracut --regenerate-all -f && grub2-mkconfig -o /boot/grub2/grub.cfg`
+3. Once done, you can safely shut down the original VM and boot the copy on destination!
 
-  If your VMs are in UEFI mode (OVMF Tianocore) :
+:::warning
+- **Downtime**: Even if the downtime will be reduced compared to using OVA, you still need to run the export/import process while the VM is off.
+- **Setup time**: Not complex, but various operations are needed until you can start the replication for one VM. If you have a lot of VMs, this can take some effort.
+:::
 
-  `dracut --regenerate-all -f && grub2-mkconfig -o /boot/efi/EFI/<your distribution>/grub.cfg`
+## 📥 Import the VHD 
 
-* Shutdown the VM
+### With Xen Orchestra
 
-* Use rsync to copy VM files to the "buffer" machine using `--sparse` flag.
+In the left menu, go for **Import** then **Disk**. Select the destination SR, and then add your VHD file into it. Depending on the VHD file size, it might take some time. The upload progress can be tracked in another XO tab, in the **Task** menu.
 
-* Convert the QCOW2 to VHD using QEMU-IMG :
+![](../assets/img/import-disk.png)
 
-  `qemu-img convert -O vpc myvm.qcow2 myvm.vhd`
+When the disk is imported, you can:
 
-* Use rsync to copy the converted files (VHD) to your XCP-ng host.
+- Create a VM with the appropriate template, **without any disk in it**
+- Attach the previously imported disk (VM/Disk/Attach an existing disk)
+- Boot the VM
+- Install the tools
 
-* After the rsync operation, the VHD are not valid for the XAPI, so repair them :
+### Via the CLI
 
-   `vhd-util repair -n myvm.vhd`
+You can transfer the VHD file directly to your XCP-ng storage repository (SR) using SCP:
 
-    `vhd-util check -n myvm.vhd` should return `myvm.vhd is valid`
+```
+scp thegenerateduuid.vhd ip.xcp-ng.server:/run/sr-mount/uuid-of-your-SR
+```
+
+:::warning
+The name of your VHD **must be** a uuid (e.g. `44ad36fc-e9f1-4d74-9090-2d9bffddbee2.vhd`).
+
+You can generate one with the command `uuidgen` on Linux.
+:::
+
+You need to rescan the SR where you new VHD file is, so it can be detected. It will appear in the disk list, without a name or description though. You can use `xe sr-scan` or use the scan button on the storage in Xen Orchestra.
+
+In Xen Orchestra:
+1. Create a new VM without a disk. Go to **Advanced settings** and uncheck the option called **Boot VM after creation**. 
+2. Go to the **Disks** tab
+3. Click **Attach disk**.
+4. Select the VHD you just uploaded, and attach it.
 
-* For each VM, create a VDI on Xen Orchestra with the virtual size of your VHD + 1GB (i.e the virtual size of myvm is 21GB, so I create a VDI with a size of 22GB).
 
-* Get the UUID of the VDI (on Xen Orchestra or CLI) and use the CLI on the XCP-ng host to import the VHD content into the VDI :
+## 🛠️ Troubleshooting
 
-  `xe vdi-import filename=myvm.vhd format=vhd --progress uuid=<VDI UUID>`
+### My imported VM is not booting 
 
-* Once the import is done, create a virtual machine using XO or XCP-ng Center, delete the VM disk that has been created and attach your newly created VDI to the VM. Don't forget to set the VM boot mode to UEFI if your VMs was in UEFI mode.
+- Check if the Boot firmware (in Advanced settings) is on the correct type (BIOS or UEFI).
+- Check if the boot disk is the first in the VM disk tab
+- Check [here](../../installation/migrate-to-xcp-ng/#error-dracut-initqueue227-warning-devmapperol-root-does-not-exist-or-no-bootable-device)
 
-* Boot the VM and find a way to enter in the virtual UEFI of the VM. Here, I type the Escape and F9,F10,F11,F12 keys like crazy. Select Boot Manager, you should see this window :
+### Error "dracut-initqueue[227]: Warning: /dev/mapper/ol-root does not exist" (or no bootable device)
 
-![](../../assets/img/migrate-to-xcp-ng_bootloader.png)
+This error means Xen drivers are missing from the kernel (see [here](../../installation/migrate-to-xcp-ng/#install-xen-drivers))
 
-* Select `UEFI QEMU HARDDISK`, the screen should be black for seconds and you should see the GRUB. Let the machine worked for minutes and you should see the prompt finally 👍
+You can boot a live CD and mount the `root` and `boot` partitions.
+```
+mount <root device> /mnt/
+mount <boot device> /mnt/boot/
 
-* Install Guest Tools and reboot. The reboot shouldn't take long, you don't have to redo step 13, the OS seems to have repair the boot sequence by itself.
+for x in sys proc run dev tmp; do mount --bind /$x /mnt/$x; done
+```
+Check your fstab to see the exact layout of your partition!
+If you have an LVM partition, you can enable them with `vgchange -ay`.
 
-Done !
+Chroot in your mounted partition 
+```
+chroot /mnt
+```
+Find your initrd files (if you have several file, use the more recent version), usualy in /boot or /boot/efi
+Then add the xen drivers:
+```
+dracut --kver <version> -f /boot/initrd<version> --add-drivers "xen-blkfront xen-netfront" --force
+```
+Exit the chroot and unmount all your partitions. Now you can reboot or detach the disk if you used your XO.
+You VM should be booting now!