Oxide VMs can run Windows guests, but to use all the Oxide platform’s features, those guests need extra drivers and software beyond what Windows Setup provides. This guide describes what you need to do to prepare a Windows installation for use in an Oxide VM, how you should configure projects that will run Windows instances, and how you can access and interact with a running Windows instance.
Preparing Windows Images
Before you upload a Windows image to the rack, you need to ensure that it has all the drivers, software, and settings it needs to function correctly in an Oxide VM. This requires you to install Windows in a VM outside the rack and use that VM to add the necessary drivers and software. Running Windows Setup from within the Oxide rack is not currently supported.
The easiest way to prepare an Oxide-compatible Windows image is to use the Oxide Windows image builder tools. These tools run Windows Setup in a VM on a Linux workstation, install all the required drivers and software, generalize the installation, and minimize the size of the resulting image. See the tools' README for more information about these tools and how they configure the images they produce.
If you have an existing Windows VM that you want to convert into a reusable image, you can download and manually install and configure the required drivers and software, then shut down the VM and upload the image into the rack. Keep in mind that you may want to sysprep (generalize) the installation before creating a reusable image from it.
Image Configuration
Firmware & Boot Disk Configuration
Oxide VMs boot with a UEFI firmware image. When booting with UEFI firmware, Windows requires the boot disk to be formatted with a GUID partition table (GPT) and not a master boot record (MBR). New Windows installations will have a GPT by default if Setup was run on a machine with UEFI firmware. Existing disks with an MBR can be converted to have a GPT using Microsoft’s MBR2GPT utility.
Disk Partition Layout
When you use a Windows image to create a new disk, the OS partition on that disk can only expand to fill the unused space on the disk if the OS partition is the last partition in the image. Windows Setup is not guaranteed to produce this layout by default; when you install Windows to start preparing a new image, Setup will usually place an extra "recovery" partition after the OS partition. When preparing a new installation of Windows, you can ensure the OS partition is last using the following methods:
Install Windows normally and then delete the recovery partition using the
diskpartcommand-line utility.Install Windows unattended and use the
CreatePartitions,ModifyPartitions, andInstallToconfiguration options to control the partition layout. (This is the method the Windows image builder tools use.)
If you use MBR2GPT to set up a GPT, it may place the EFI system partition after the OS partition. Refer to the MBR2GPT documentation for more information on how Windows decides where to place the EFI system partition during an MBR-GPT conversion.
Drivers
Oxide VMs use
virtio
devices for networking and for the storage device that contains instance
metadata. Windows does not ship in-box drivers for these devices, so you’ll need
to install them. Oxide runs Windows tests using the prebuilt signed drivers from
the
Fedora project’s virtio-win driver repository, but you can use any signed
Windows virtio driver that’s compatible with the version of Windows you’re
configuring.
If you’re using the Fedora project’s drivers, you’ll need to install
netkvm.sys and viostor.sys:
netkvm.sysis the driver for virtio network adapters and is required for guest networking to function.viostor.sysis the driver for virtio block devices and is required for guests to be able to access the cloud-init metadata drive.
If you’re using another vendor’s drivers, you’ll need to install the equivalent drivers for these two devices.
Additional Guest Software
SSH Service
If you plan to access your Windows VMs via SSH, you will need to install an SSH server in the guest and make sure it’s configured to start when the guest boots. Microsoft maintains a fork of the Portable OpenSSH project that you can install to add an SSH server to your images. For more information, see Microsoft’s documentation on getting started with OpenSSH and the Win32-OpenSSH GitHub wiki.
Cloud-init Metadata Service
The Oxide control plane provides instance metadata to VMs using a cloud-init "no-cloud" configuration drive. This metadata includes the instance’s hostname, any SSH keys that should be authorized to access any "cloud user" accounts managed by the guest’s metadata service, and the instance’s cloud-init user data.
The cloudbase-init project maintains an open-source cloud-init agent for Windows that can be configured to recognize and apply settings from most cloud-init configuration drives.
An MSI installer for an Oxide-compatible version of cloudbase-init is available at https://oxide-omicron-build.s3.amazonaws.com/CloudbaseInitSetup.msi. This installer contains an additional patch that allows cloudbase-init to process SSH keys from Oxide metadata drives. (Note that this change has not yet been upstreamed, so this installer is currently built from a fork).
When you install cloudbase-init, you need to supply it with configuration files that tell it which of its services and plugins to enable. The Oxide Windows image builder includes its own configuration that you can use as a template. It includes the settings necessary to read the configuration drive, set the Windows computer name to match the VM’s hostname, create a default user, copy authorized SSH keys for that user, and automatically extend the Windows OS partition to include all available space on its disk. Other cloudbase-init services, plugins, and options may work in an Oxide VM, but Oxide does not regularly test them.
Sysprep
Full installations of Windows store some data and settings (e.g., in the Windows
registry) that uniquely identify the installation and describe the
installation’s underlying hardware platform. When you upload a guest image to
the rack, it’s possible to use that same image to create multiple VMs, possibly
with distinct hardware configurations. Windows supports this kind of image reuse
through a process called generalization. Generalizing a Windows installation
with the Windows sysprep utility removes installation-specific data from that
installation. Once a system is generalized, it can be configured to specialize
itself on a subsequent boot, which generates new identifiers and
machine-specific configuration.
See Microsoft’s documentation for more information about generalizing a Windows installation and the Unattended Windows Setup Reference for more information about how to configure the actions Windows Setup should take when it specializes an installation.
When deciding how to generalize and specialize your images, keep in mind that Oxide doesn’t currently support access to VMs' graphical consoles. If your image isn’t configured to set up a user account or isn’t configured to skip the Windows out-of-box experience (OOBE), it may not be possible to complete Windows setup or access the VM. See Accessing Windows Instances for more details.
Configuring Projects With Windows VMs
Projects that will run Windows VMs need special VPC configuration to grant those VMs network access to the Windows services and protocols they intend to use. The default Oxide VPC configuration’s firewall rules do not grant access to any Windows-specific ports by default. One common addition to the default rules is to allow inbound connections to port 3389 for Remote Desktop access. Refer to Microsoft’s documentation to determine which rules to add for the services your VMs will use.
Accessing Windows Instances
Windows instances support remote access over the serial console, SSH (if an SSH server is installed in the guest), and Remote Desktop.
Command prompt access via the serial console and Remote Desktop access require a username and password. There are several ways to set up password authentication for Windows VMs. For example:
If you plan to install a cloud-init metadata service and SSH server in your image, you can configure the metadata service to create a default user and add authorized SSH keys for that user. You can then set the cloud user’s password by logging in via SSH and changing the password at the command prompt using
net user <username> *.You can create an image that’s configured to give the local administrator account a well-known password that a VM’s user can change after using the instance for the first time.
If you’re using Active Directory to administer your VMs, you can configure the image to join an Active Directory domain automatically on first boot.
Refer to Microsoft’s Unattended Windows Setup Reference for more information about the actions Setup can be configured to take when a VM boots for the first time and completes the setup process.
Serial Console
Windows Server installations include a Special Administration Console (SAC) that can be accessed over a serial port. To access this console, you need to enable Emergency Management Services in your instance’s boot configuration store and configure it to write to COM1:
bcdedit /ems on
bcdedit /emssettings EMSPORT:1 EMSBAUDRATE:115200The SAC provides access to basic management functionality (shutting down and rebooting guests) and debugging tools (viewing running processes and network configuration). It also provides serial console-based access to a Windows command prompt.
SSH
SSH access requires an SSH server to be running in the guest and either a username and password or a set of authorized SSH public keys such as those installed by a guest metadata agent.
Remote Desktop
You can access Windows instances over Remote Desktop provided that you have properly configured the instance’s firewall rules, the guest’s Remote Desktop access settings, and the guest’s OS-managed firewall rules. Specifically:
The instance’s firewall rules must allow TCP connections on the Remote Desktop listening port (by default, port 3389).
Windows’s firewall rules must allow connections on this port. To set these firewall rules, run the following command from within the guest:
netsh advfirewall firewall set rule group="remote desktop" new enable=YesFinally, the Windows registry must be configured to allow Remote Desktop connections. To enable this setting, run the following command from within the guest:
reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server" /f /v fDenyTSConnections /t REG_DWORD /d 0