Supported Operating System Images¶

Equinix Metal™ provides a range of operating systems available for you to deploy on our platform. In general, Equinix Metal OS images are lightly modified versions of the OS cloud images tailored to be compatible with our server hardware and network configurations.

About Our Images¶

Changes to our OS images are tracked in equinixmetal-images/changelog. Images are kept as close to upstream releases as possible.

The changelog aims to show what packages have changed since the last published image, the kernel used in the image, and what deviations from the upstream cloud image (if any) are in the new published image.

When you provision a server using one of our OS images, you get the most recent image we have published. Once you have provisioned your server, we no longer have access, and keeping the Operating System up-to-date is your responsibility.

If we do not offer an operating system or a version of an operating system that meets your use-case, you can bring your own OS images using Custom iPXE.

Operating Systems Reference¶

If you would like to check whether an operating system is currently available on a specific standard or legacy server plan, use the Operating System Compatibility page.

AlmaLinux¶

Operating System	Slug
AlmaLinux 9	`alma_9`
AlmaLinux 8	`alma_8`

Alpine Linux¶

Operating System	Slug
Alpine 3	`alpine_3`

CentOS¶

Operating System	Slug
CentOS 7	`centos_7`

Debian¶

Operating System	Slug
Debian 11	`debian_11`
Debian 10	`debian_10`

Flatcar Linux¶

Operating System	Slug
Flatcar Linux - Stable	`flatcar_stable`
Flatcar Linux - Beta	`flatcar_beta`

FreeBSD¶

Operating System	Slug
FreeBSD 13.1	`freebsd_13_1`

NixOS¶

Operating System	Slug
NixOS 22.11	`nixos_22_11`
NixOS 22.05	`nixos_22_05`

Rocky Linux¶

Operating System	Slug
Rocky Linux 9	`rocky_9`
Rocky Linux 8	`rocky_8`

Talos¶

Operating System	Slug
Talos v1	`talos_v1`

Ubuntu¶

Operating System	Slug
Ubuntu 22.04 LTS	`ubuntu_22_04`
Ubuntu 20.04 LTS	`ubuntu_20_04`
Ubuntu 18.04 LTS	`ubuntu_18_04`

Hardware Compatibility¶

All of our operating system images go through a validation process in order to be provisionable on our hardware. Not all operating systems are available on every server.

Which operating systems are available on a specific server is listed on its product page and on the OS Compatibility page.

CLI

To get a list of which operating systems are available on which servers, use the metal operating-systems get command, and specify the output as JSON.

metal operating-systems get -o json

The response contains a "provisionable_on" object, which is an array of servers that operating system is provisionable on. (The example response is truncated.)

{
    "name": "AlmaLinux OS 8",
    "slug": "alma_8",
    "distro": "alma",
    "version": "8",
    "provisionable_on": [
        "a3.large.x86",
        "c2.medium.x86",
        "c3.large.arm64",
        "c3.medium.x86",
        "c3.small.x86",
        ....    
    ]
},

API

To get a list of which operating systems are available on which servers, send a GET request to the /operating-systems endpoint.

curl -X GET \
-H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/operating-systems"

The response will contain the operating system name, ID, and slug, which is useful if you are provisioning servers through the API or CLI. It will also contain "provisionable_on", which is an array of servers that operating system is provisionable on. (The example response is truncated.)

{
    "name": "AlmaLinux OS 8",
    "slug": "alma_8",
    "distro": "alma",
    "version": "8",
    "provisionable_on": [
        "a3.large.x86",
        "c2.medium.x86",
        "c3.large.arm64",
        "c3.medium.x86",
        "c3.small.x86",
        ....    
    ]
},

Provisioning a Supported Operating System¶

Console

When you provision a server through the Equinix Metal console, the available operating systems are filtered by the server you choose.

On Demand Operating System Selection in the Console

Your OS options are similarly filtered if you are provisioning from your Reserved Hardware or through the Spot Market.

CLI

When provisioning servers in the CLI with the metal device create command, the required --operating-system or -O parameter is how you specify which operating system to install on the server.

metal device create -p $METAL_PROJECT_ID -m <metro> -P <plan_slug> -O <os_slug>

If you attempt to provision a server with an OS that is not compatible with the hardware, you will receive an ... is not a valid operating system error in response.

API

If you are provisioning servers in the API, the operating_systems field is where you specify which OS to install on your server. It is also a required field.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
    "metro": "<metro>",
    "plan": "<plan_slug>",
    "operating_system": "<os_slug>"
}'

If you attempt to provision a server with an OS that is not compatible with the hardware, you will receive an ... is not a valid operating system error in response.

End-of-Life Images¶

When an operating system image is end-of-life, you will no longer be available to provision it on new servers through the console or the API. Servers currently running end-of-life operating systems will continue to run normally.