Running a Porter migration
This document walks through a complete Porter migration, from the first interactive run against an ESXi host to a fully unattended one-line conversion. Before you begin, confirm that you meet the prerequisites in Porter overview.
Authenticating to the ESXi host
Porter requires SSH access to the ESXi host. There are three ways to provide that access, and the method you choose changes the command you run.
| Method | How it works | When to use it |
|---|---|---|
| Interactive prompt | Run Porter with no password flag and it prompts for the ESXi root password. | First run, walking through the process manually. |
| Password file or inline password | Pass --pass-file /tmp/pw.txt, or --pass with the password inline. | A one-line run on a host where an SSH key is not yet set up. |
| Pre-seeded SSH key | If a working key exists at /root/.ssh/id_rsa and is authorized on the ESXi host, Porter finds and uses it. No password, no flag, and no prompt. | Any host that runs migrations regularly. |
The password is used only once. Porter uses it to install its public key on the ESXi host at /etc/ssh/keys-root/authorized_keys, and every connection after that is key-only. The password is then discarded.
Walking through a first migration (ESXi, Windows guest)
Run the first migration fully interactively so that you see every prompt.
Start Porter
sudo porter vmware --esxiSpecify the ESXi host
Porter prompts for the ESXi hostname or IP address. Either value works.
Authenticate
On the first run against a host, Porter finds no key, generates one at /root/.ssh/id_rsa, and prompts once for the root password so that it can install the key. The prompt itself notes that the password is required only one time.
Porter installs the key on the ESXi host and confirms that key authentication works from that point on.
On any later run against the same host there is no password prompt at all. Porter tests the key and continues.
Select the virtual machine
Enter the name of the VM to convert. The name must match the name on the ESXi host exactly. If staging copies of the VM exist on the host, be sure to name the correct one.
Select the VirtIO ISO
Porter lists the VirtIO ISO it finds under /mnt/gold-images and lets you either select it or enter a custom path. This is the driver set that Porter injects for Windows guests.
Select the output directory
Specify where the finished QCOW2 file is written, for example /kvm/win.
Monitor the conversion
Porter locates the VM on the ESXi host, confirms that it is powered off, displays the disk information, and then begins streaming and converting the disk over SSH. During the conversion Porter displays:
- The source, temporary, and output paths.
- A free-space check.
- The
virt-v2vstep list, with a copy progress bar.
On a real disk, expect this to take a while. A representative Windows migration took 10 to 15 minutes, including the cleanup script and the reboots that follow conversion.
Confirm completion
When the copy reaches 100 percent, Porter optimizes the QCOW2 file, cleans up the temporary directory, and prints Conversion Complete along with the final disk path and size. Porter then redefines the VM from the base XML, starts it, and attaches the VirtIO ISO as a CD-ROM. The final screen also describes the actions the VM performs on its own after this point. See Troubleshooting Porter migrations.
Verifying the migrated virtual machine
Confirm that the converted VM is defined and running.
test.user@sit0001red0:~$ sudo virsh list --all
Id Name State
----------------------
2 win runningFor a Windows guest, confirm that the cleanup script ran by reading the cleanup log with reacher.
sudo reacher exec win "Get-Content C:\porter-cleanup.log"For a full example of the log output, see Troubleshooting Porter migrations.
Building up to a one-line conversion
Every prompt in the interactive run has a matching flag. Supplying those flags ahead of time produces the same conversion without any interaction.
The interactive form is the run described above.
sudo porter vmware --esxiSupplying the inputs skips the prompts. The following is a full Windows ESXi migration with a password file.
sudo porter vmware --esxi \
--esxi-host <host> \
--esxi-vm <VMNAME> \
--pass-file /tmp/pw.txt \
--virtio-iso /mnt/gold-images/iso/virtio-win-0.1.271.iso \
--output-dir /kvm/<name> \
--post-migration-script 'C:\path\to\validator.ps1'Once the SSH key is seeded on the ESXi host, drop the password flag entirely.
sudo porter vmware --esxi \
--esxi-host <host> \
--esxi-vm <VMNAME> \
--virtio-iso /mnt/gold-images/iso/virtio-win-0.1.271.iso \
--output-dir /kvm/<name> \
--post-migration-script 'C:\path\to\validator.ps1'With the key at /root/.ssh/id_rsa there is no password flag at all. This is the form to standardize on for any host that runs migrations regularly.
Migrating from a local file
If the VM has already been exported to an .ova, .ovf, or .vmdk file on the SC//Reliant host, use --local instead of --esxi and point Porter at the file with --file. --local is the default mode.
sudo porter vmware --local \
--file <path_to_file> \
--output-dir /kvm/<name>Migrating a Linux guest
For a Linux guest, add --linux. This skips the Windows-specific driver injection and cleanup steps. virt-v2v still injects the VirtIO drivers, but there is no firstboot cleanup script, no ISO mount, and no guest-tools installation step.