Install any Operating System from an ISO image source

In this guide we demonstrate how to install an operating system onto an Equinix Metal system from an ISO image source. Note that for production use cases, one should always use a prebuilt operating system available from Equinix or a custom iPXE build. But for experimentation, proofs of concept, and other "just need it to work" scenarios, this will get the job done.

Note: This is an unsupported method for installing an operating system, and as such, not all ISOs are guaranteed to work on all systems or at all. If you encounter any issues with the installation process, check the metal-isometric-xepa repository for the latest status.

Overview

This process is going to take advantage of the Rescue Mode option to install the OS on a blank server which we'll call up with a false request for a custom iPXE OS. The process will look something like this:

1. First, we'll provision a system using the custom iPXE boot option and a dummy URL.
2. Once provisioned, we'll use the server's Rescue Mode to install utilities, like VNC and a KVM hypervisor.
3. Then, we'll download the ISO onto the rescue environment.
4. Next, we'll install the ISO to a virtual machine with the server local storage attached and any devices passed through that might need special drivers for boot.
5. Finally, we'll reboot the machine directly off the newly installed OS on the local storage.

The rest of this guide will walk through these steps in detail using the example of installing Microsoft Windows 11 on our system.

A note on IP addresses

By default, our systems provision with a /31 IPv4 subnet space. For most OSes this is fine, but several (such as Windows or VMWare ESXi) may require a /30 subnet or larger. You can work around these in various ways but the simplest is to request a /30 Elastic IP subnet from Equinix. Since this guide is going to deal with Windows, we'll do that first. We'll cover how to do this with both the Equinix metal CLI and the Equinix Metal Console.

Using metal-cli

Alternatively, use the ip request command.

metal ip request -p $PROJ -m ny -q 4 -t public_ipv4

Where:

In the Equinix Metal Console

To accomplish the same from the Equinix Metal Console, follow these steps:

1. Select Networking and then IPs on the left-hand navigation. Then click the blue + Request IP Addresses button.

   

2. Select the appropriate IP type, metro where you'll deploy the device, and quantity/subnet. Then click Subit Request. For our example we're requesting a /30 subnet, or 4 Public IPv4 addresses in the New York metro.

   

3. Once your request shows an Approved status you're all set.

1. Deploying an Equinix Metal Server

In the Equinix Metal Console

1. While logged into the Metal Console, under Bare Metal Servers select On Demand or Reserved Hardware to create a new device of your desired type, or select the New Server button on the Manage Servers page.

2. Select the Metro and Server Type you'd like to use. For this example we'll be deploying a c3.small.x86 to the New York metro.

   

3. For the OS, select custom_ipxe and fill in the IPXE script URL with a placeholder as we do not need it. In this example we've used http://boot.netboot.xyz.

   

4. If you're using an OS as discussed above that requires a /30 address space, click the Optional Settings dropdown and make changes under the IP Addresses tab as necessary.

   

5. Once you've got the server settings filled in, select Deploy Now.

Using metal-cli

Alternatively, use the device create command.

metal device create -p $PROJ -H "iso-test" -I "http://boot.netboot.xyz" -m ny -O custom_ipxe -P c3.small.x86 -S 30

Where:

2. Log into Rescue Mode and install helper utilities

1. Once the system is provisioned and you're able to click on the hostname in the Manage Servers screen, click it to open the server details page.

2. To enter rescue mode, click the Actions dropdown and select Rescue. Then confirm you're sure on the prompt.

   

3. To login to the server, we'll need to ssh into the out of band console. You can copy the precise ssh command for this using the >_ icon next to the action menu.

   

   

4. Once connected to the out of band console, you'll be able to monitor the reboot process until prompted for a login. Enter root at login and you will be presented with something similar to the image below.

   

5. Once at the prompt, we'll need to do some preparation of the rescue mode environment so it is ready for installing an ISO. Run the command below to streamline this process or if you'd prefer to read what it does first you can find the setup script here. The script mostly installs KVM, libvirtd, and VNC.

   curl -s https://raw.githubusercontent.com/enkelprifti98/metal-isometric-xepa/main/setup.sh | sh
   

   This may take a minute or two to complete and you should be left with the prompt informing you of the URLs to access the system as follows

   

6. The URLs listed here are for the Desktop Environment and the File Upload portal respectively. Also, take note of the boot mode of your Equinix Metal instance (BIOS in the above example). You will need this later.

3. Download an ISO and connect to the Desktop Environment

In order to install from an ISO, we'll need to load the ISO itself onto the rescue system one way or another. If you're going to download it from the internet, we can do so from the rescue interface. More details on how to connect to that later.

However, if you have an ISO on your local system you'd like to upload to the Equinix Metal device, you can either do so through the File Transfer portal (details below) or some other method like scp to copy the image onto the rescue system to directory that is easily accessible by the root user, such as the /root directory.

Uploading through the file transfer portal (optional)

Note, that if you plan to download the ISO (from the internet or other source), you can ignore these steps and proceed to the next heading. You only need to complete these steps to upload an image from your computer.

1. Copy the URL provided in your terminal window under File Transfer portal and paste and navigate to it in your web browser. If you don't see the URL it should be the equivalent of http://<server_public_ip>:8080/. This should load File Browser.

   

2. Login using the username admin and the password admin. This will give you access to the /root folder on the remote server. We'll disable this later.

   

3. From here you can drag the ISO from your local system into the web browser where you would like it to be uploaded. The Downloads folder is a good choice.

Connecting to the Desktop Environment

1. The easiest way to connect to the desktop graphical environment is to paste the public IP of your Equinix Metal server into the URL of your web browser. (If having trouble, ensure it connect to http://<your_public_ip>/ and not https:// as SSL has not been configured).

   

2. Next, click Connect to bring up the desktop in your browser. Alternately, you can point a VNC client of your choice to your server's pubic IP address.

3. When prompted, enter admin for the password and you will be presented with the desktop.

   

4. If you have not already uploaded an ISO image, now would be the time to download one using the desktop environment. You can open the web browser to download the latest version of Microsoft Windows, as we'll do in this example, or use the terminal window and wget to download something from a URL directly. Either way, place it someplace easy to access in the next steps.

4. VM Creation and Install Target Selection

1. Open the Virtual Machine Manager by opening the Application Finder (magnifying glass icon in the bottom dock) and searching for it in the search bar.

   

2. Click the monitor icon to create a new virtual machine.

   

3. Choose to install using Local install media and select Forward.

   

4. When prompted to select the media, click the Browse... button

   

5. On the next screen, you'll need to slect Browse Local to search in your local file system.

   

6. Use the file browser to locate the ISO you've loaded onto the server. In our case, the Windows 11 install media was in the Downloads folder of our home directory. Select the file and click Open on the top-right corner of the window.

   

7. Once the ISO is selected the OS should be detected automatically from the source. In our case it showed Microsoft Windows 10, which is close enough, confirm the OS and press Forward.

   

   (Note, if you can't find your OS, uncheck the Automatically detect... box and use the search field to find best match. You might need to use Generic OS if you can't find a one, or if your OS uses something like Ubuntu or FreeBSD as it's base, you can select that instead of the generic option.)

8. You'll need to allocate CPUs and RAM to the temporary virtual machine. In the example below, we chose 8 GiB of RAM and 8 vCPUs. Click on the Forward button.

   

9. On the next screen, you'll be asked to configure storage. Pick Select or create custom storage and type the system device path to where you want to install the OS in the blank path below. Click Forward.

   

   (Note, to look at the local volumes, open a terminal window and enter the command lsblk -p. This will list available volumes for installation by their device paths. It's good practice to select the smallest device for OS installation; as you can see in the example below, my drives are the same size.)

   

   (Note, depending on the selected server type you may see a number of NVMe storage devices (for example: /dev/nvmean1). You can only use them as a target for the bootable operating system if your instance is running in UEFI boot mode. NVMe drives cannot be used as the bootable devices in BIOS boot mode.)

10. On the next screen, select Customize configuration before install before selecting Finish

    

5. VM Customization

The next screen presents a set of options that allows us to customize some elements of the virtual machine to resemble the actual hardware of the instance we're installing to.

Boot Firmware

The boot firmware of the virtual machine should be set to resemble that of your instance. This was provided at the output of the initial setup script. In this example it let us know The instance is running in BIOS boot mode.

On the Virtual Machine overview page, select the BIOS or the appropriate UEFI option.

Serial Consoles for Out of Band Connection

In order for our Out of Band console to continue working after installation, we need to add two serial console devices to the Virtual Machine that we will enable after the OS installation.

1. Begin by selecting +Add Hardware from the overview window

2. Select Serial device in the left-hand column, ensure the defaults are left under Details, it should look as the example below that uses the Pseudo TTY (pty) device type. Once added, click on Finish.

   

3. Repeat this process again to add a second device. You should now see two devices in the Serial option on the left-hand column of the overview window.

   

TPM for OS Boot Requirements

Some operating systems may require a TPM or Trusted Platform Module chip to run. Windows 11 is one such operating system.

1. Select +Add Hardware from the overview window.

2. Select the TPM category on the left-hand side and adjust the details.

3. The defaults generally should be fine with the Model as CRB, the Backend as Emulated device and Version set to 2.0, select Finish when all set.

   

Attach a PCI device to the virtual machine (optional)

This step is required for an installation where you may want to passthrough the physical networking PCIe card to the virtual machine. This is not strictly required, but it is helpful in cases where the original ISO image may not include drivers for the existing network cards, allowing us to download drivers using the internet provided to the virtual machine through the host.

(Note, this step may not be possible on legacy server types that do not support IOMM or VFIO PCI Passthrough properly. If the host does not support IOMMU or has not been configured properly, virt-manager will show errors when starting the virtual machine with PCI devices attached.).

1. Start by selecting +Add Hardware from the overview window.

2. Select the PCI Host Device category on the left-hand side. On the right side, you will see a large list of different PCI devices available and you will need to look for the network controllers. These may say Ethernet Controller somewhere in the name, or may not. If you scroll to the right, all should mention the interface they represent.

   

   (Note, you should avoid passing through the network interface being used to give the current rescue environment internet access! Typically this is interface eth0, but you're always able to check using the terminal and something like ip address show in the terminal. You can see from the example output that this instance has 4 ethernet ports and it is using eth2 for current service.)

   2: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN qlen 1000
       link/ether 3c:ec:ef:6a:32:3a brd ff:ff:ff:ff:ff:ff
   3: eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN qlen 1000
       link/ether 3c:ec:ef:61:32:3b brd ff:ff:ff:ff:ff:ff
   4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP qlen 1000
       link/ether 0c:42:a1:15:af:00 brd ff:ff:ff:ff:ff:ff
       inet 147.75.75.42/30 scope global eth2
           valid_lft forever preferred_lft forever
       inet6 fe80::e42:a1ff:fe15:af00/64 scope link
           valid_lft forever prefferred_lft forever
   5: eth3:  <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN qlen 1000
       link/ether 0c:42:a1:15:af:01 brd ff:ff:ff:ff:ff:ff
   

3. Select the device you'd like to passthrough to the virtual machine and select Finish.

6. Install the Operating System

1. Now that the VM has been configured, select Begin Installation on the top left of the window.

2. A new window will be launched where the OS will boot into the installer for the ISO.

   

3. When prompted for an installation target, you'll find the storage device (/dev/sda in our example case), recall that we made added this storage device earlier.

   

4. Step through the installation as necessary for your OS, once completed the VM will reboot into the operating system you've now installed directly on the local disc with the normal first time boot behviors. Complete these as you would for any other OS installation.

   

7. Post-Install Configuration

Once the OS has been installed, there are a few more things to configure before rebooting the host device to run the operating system.

Networking Device Driver

After reboot, we'll have to rely on the hardware networking device for internet connection. We've passed this through to the guest OS earlier so we can install this ahead of time now, while we have access to the host passthrough network as a backup. Many OS's already contain working drivers for the hardware in question, but in case it doesn't, now is a good time to check. In my case, I can see the Intel I210 Gigabit Network Connection is already there, matching the device I passed through to the guest OS.

In the event that your device does not show up, you can check for new drivers to install as you would normally using the working network connection.

Serial Console

The serial connections are critical for enabling the Equinix Out-of-Band console which can allow you access to your instance in events of network misconfiguration or other circumstances that may prevent remote access from the internet. Our systems expect to be able to connect to the COM2 serial port (I/O port 0x2F8, IRQ 3) with a baud rate of 115200, 8 data bits, no parity, and 1 stop bit for this console to work.

In some cases the OS may allow activation of the serial port through the GUI, but otherwise we'll need to use a terminal or command prompt to complete configuration.

Windows

Standard Windows operating systems do not support serial console output, but if you're running a server edition of Windows, we can enable Emergency Management Services (EMS) redirection with the following commands ran in Command Prompt as an Administrator:

bcdedit /bootems {default} ON
bcdedit /ems {current} ON
bcdedit /emssettings EMSPORT:2 EMSBAUDRATE:115200

Linux

For Linux based operating systems, you can typically enable serial console output through the GRUB bootloader options found in /etc/default/grub. There you can add the following:

#GRUB_TIMEOUT_STYLE=hidden
GRUB_TIMEOUT=3
GRUB_CMDLINE_LINUX="console=tty0 console=ttyS1,115200n8"
GRUB_TERMINAL="serial console"
GRUB_SERIAL_COMMAND="serial --unit=1 --speed=115200 --word=8 --parity=no --stop=1"

Once you've edited the GRUB config file, you can apply the change with update-grub.

BSD

For BSD based operating systems you should be able to add serial console support by editing the /boot/loader.conf bootloader configuration file. Add the following to the config file:

boot_multicons="YES"
boot_serial="YES"
comconsole_speed="115200"
console="comconsole,vidconsole"
comconsole_port=0x2F8

Once completed, restart the virtual machine to ensure the settings take place.

Before we reboot the host instance, we will confirm through the rescue OS that our serial connection is working. Open a terminal window and run the command virsh console win10 serial1 where win10 is the name of the virtual machine you've just configured.

Notes

A few things to note:

• serial1 is the alias name of the second serial device (Serial 2) we added to the VM which corresponds to COM2. If you need to double check the alias name you can do so by viewing the XML settings of the serial device and look for <alias name="serial1"/>. The Serial 2 device should also be using port 1 in <target type="isa-serial" port="1">.

• On the other hand, the Serial 1 device has alias name of <alias name="serial0"/> and is using port 0 in <target type="isa-serial" port="0"> which corresponds to COM1 or 0x3F8. We need to be using the second serial device/port instead since that is what Equinix Metal uses for the Out-of-Band console.

You should be able to see output and also send keyboard input to the VM through the serial console. If you're not able to see any output you need to go back and adjust the operating system configuration.

Remote Access

After reboot, we'll need to be able to access our OS remotely through the internet. For many operating systems this will be through SSH, but for windows we'll need to enable Remote Desktop Protocol (RDP). You can find this by searching for Remote Desktop Settings in Settings, and turning it on.

For other OS's you'll need to install or enable the SSH server.

8. Rebooting the host instance

Now that post install configuration steps are completed, it's time to reboot into the new OS from the host.

1. Shutdown the Virtual machine, disconnect from the VNC instance or close the browser window.

2. Open the Equinix Metal console, go to Manage Servers, and the server details page.

3. In the Actions menu in the top-right, select Reboot.

   

4. While the server is rebooting, you can (and may want to) monitor its progress using the out of band console. This is useful for detecting any kernel panics or undetected devices that might indicate issues with the underlying installation or hardware compatibility.

   (Note, you may see a message about a kernel panic, indicating that the underlying hardware is not supported by your OS. This OS may not be able to be installed on this instance.)

   *(Another note, you may see a message about missing storage device or missing filesystem mount during the OS boot process, it could mean that the Operating System does not detect the underlying storage drives or controller. Try installing the OS in a different drive type under a different HBA or storage controller. For troubleshooting, try attaching the PCI storage controller to the VM inside the ISO installation environment to verify if the OS can detect the drives.

5. Once the system is rebooted, you should be able to access the instance remotely as normal, in this case, thorugh Microsoft Remote Desktop:

   

One final note, in many cases the operating system will automatically configure the network through DHCP for the first network interface only. It's recommended to configure LACP bonding for the server's network interfaces if the operating system supports it.

Summary

In this guide we covered how to install an OS with an ISO source by using leveraging the Rescue Mode available in Equinix Metal and using common utilities such as KVM, libvirtd, and VNC. It's worth re-iterating that this process should not be used for a production workload, but rather for experimentation and proofs of concept.