Bring Your Own Linux (BYOLinux) (EN)

Objective

The Bring Your Own Linux feature (BYOLinux) enables you to deploy cloudready Linux images directly on your dedicated server. You can therefore use the bare metal service as a resource for your deployments.

What does cloudready mean?

The cloudready standard generally means being agnostic of the infrastructure on which the image is deployed. In addition to the requirements and limitations mentioned below, you must ensure that the image (downloaded or generated) meets the technical expectations of a cloudready image.

This guide explains how to use Bring Your Own Linux (BYOLinux) on your OVHcloud dedicated server.

Requirements

• A dedicated server in your OVHcloud account
• Access to the OVHcloud API (for the "Deployment via API" section of this guide)
• Your image must be smaller than the server RAM minus 3GiB
• An executable script /root/.ovh/make_image_bootable.sh, which will install and configure the bootloader, for example GRUB. This script must not alter the NVRAM boot order (e.g. use grub-install --no-nvram). For more information, see Understanding the dedicated server boot process.

OVHcloud Control Panel Access

• Direct link: Dedicated Servers
• Navigation path: Bare Metal Cloud > Dedicated servers > Select your server

Instructions

Technical limitations:

There are some technical limitations linked to the use of physical products such as dedicated servers. Here is a non-exhaustive list, to keep in mind during your deployment preparation:

• Boot type: UEFI or legacy (depending on the boot type of your server)
• Image format: qcow2
• Only one partition in the qcow2 image
• Partition filesystem: ext4, XFS, or BTRFS (without subvolumes)

Deployment methods:

• Deployment via the Control Panel: allows you to deploy your image using the OVHcloud Control Panel.
• Deployment via API: you can use the OVHcloud API to integrate images into your own scripts to automate deployments.

Deploy your image via the Control Panel

In the General information tab, click the ... button next to "System (OS)" then click Install.

In the window that appears, select Custom in the menu, then Bring Your Own Linux - byolinux, and click Next.

You will be redirected to the configuration page. Make sure your image URL is in the correct format. Fill in the rest of the required fields on this page. Once you have confirmed that the information is correct, click Confirm.

You can find more details on the options in the deployment options section below.

For more information and examples about Cloud-Init's ConfigDrive, please read the official documentation on this page.

Deploy your image via the API

Log in to the API console and go to the /dedicated/server section.

The Bring Your Own Linux (BYOLinux) payload should be similar to the following:

{
  "operatingSystem": "byolinux_64",
  "customizations": {
    "hostname": "mon-tux",
    "imageURL": "https://github.com/ashmonger/akution_test/releases/latest/download/deb11k6.qcow2",
    "efiBootloaderPath": "\\efi\\debian\\grubx64.efi",
    "imageCheckSum": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "httpHeaders": {
      "Authorization": "Basic bG9naW46cGFzc3dvcmQ="
    },
    "imageCheckSumType": "sha512",
    "configDriveUserData": "I2Nsb3VkLWNvbmZpZwpzc2hfYXV0aG9yaXplZF9rZXlzOgogIC0gc3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTVBQUFBSUFiY0QgbXlzZWxmQG15ZG9tYWluLm5ldAoKdXNlcnM6CiAgLSBuYW1lOiBwYXRpZW50MAogICAgc3VkbzogQUxMPShBTEwpIE5PUEFTU1dEOkFMTAogICAgZ3JvdXBzOiB1c2Vycywgc3VkbwogICAgc2hlbGw6IC9iaW4vYmFzaAogICAgbG9ja19wYXNzd2Q6IGZhbHNlCiAgICBzc2hfYXV0aG9yaXplZF9rZXlzOgogICAgICAtIHNzaC1lZDI1NTE5IEFBQUFDM056YUMxbFpESTFOVEU1QUFBQUlBYmNEIG15c2VsZkBteWRvbWFpbi5uZXQKZGlzYWJsZV9yb290OiBmYWxzZQpwYWNrYWdlczoKICAtIHZpbQogIC0gdHJlZQpydW5jbWQ6CiAgLSBlY2hvICJjb3Vjb3UgcnVuY21kIiA+IC9vcHQvY291Y291CiAgLSBjYXQgL2V0Yy9tYWNoaW5lLWlkID4+IC9vcHQvY291Y291CiAgLSBkYXRlICIrJVktJW0tJWQgJUg6JU06JVMiIC0tdXRjID4+IC9vcHQvY291Y291CmZpbmFsX21lc3NhZ2U6IFRoZSBzeXN0ZW0gaXMgZmluYWxseSB1cCwgYWZ0ZXIgJFVQVElNRSBzZWNvbmRzCg=="
  }
}

Even though the configDrive user data could be sent to the API directly in clear text by escaping special characters, it is recommended to send a base64-encoded script to the API. You can use the following UNIX/Linux command to encode your data:

cat my-data.yaml | base64 -w0

Here is the clear-text configDrive user data from the example above:

#cloud-config
ssh_authorized_keys:
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAbcD myself@mydomain.net

users:
  - name: patient0
    sudo: ALL=(ALL) NOPASSWD:ALL
    groups: users, sudo
    shell: /bin/bash
    lock_passwd: false
    ssh_authorized_keys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAbcD myself@mydomain.net
disable_root: false
packages:
  - vim
  - tree
runcmd:
  - echo "coucou runcmd" > /opt/coucou
  - cat /etc/machine-id >> /opt/coucou
  - date "+%Y-%m-%d %H:%M:%S" --utc >> /opt/coucou
final_message: The system is finally up, after $UPTIME seconds

Once you have filled in the fields, start the deployment by clicking Execute.

Deployment options

¹ Can either be a #cloud-config or a script. Its JSON representation must be on a single line with \n for line breaks, as JSON strings cannot contain literal newlines.
² Use only if you need HTTP Headers, such as Basic Auth
³ The EFI bootloader path is used by iPXE to boot your operating system. For more information, see Understanding the dedicated server boot process. Examples:

Common customer errors

The following table gives an overview of well-known customer errors and how to fix them.

See OVHcloud API and Storage Common customer errors for related partitioning issues.

Go further

BYOLinux on GitHub - Examples and in-depth documentation

OVHcloud API & OS installation

OVHcloud API and Storage

Bring Your Own Image (BYOI)

Bring Your Own Image (BYOI) / Bring Your Own Linux (BYOLinux), a comparison sheet

Understanding the dedicated server boot process

Join our user community on https://community.ovh.com/en/.