Bring Your Own Linux (BYOLinux)

View as Markdown

The Bring Your Own Linux (BYOLinux) feature 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.

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 reinstall and configure the bootloader, for example, GRUB

Info

To apply OVHcloud customizations at first boot, your image must include cloud-init or a compatible alternative (such as FreeBSD's nuageinit).

OVHcloud Control Panel Access

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

Warning

NOTE: As with any classical OS installation, a new installation with BYOLinux will erase all the data on the 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 more options ... button next to Operating system (OS), then click Install my server.

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.

Deploy your image via the API

POST/dedicated/server/{serviceName}/reinstall

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

Warning

NOTE: In the customizations section, only imageURL is mandatory. Also, the imageCheckSum value has been masked because it changes regularly whenever the target image is rebuilt.

{
  "operatingSystem": "byolinux_64",
  "customizations": {
    "hostname": "my-host",
    "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 configDriveUserData 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 version of configDriveUserData from the example above:

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

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.com
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 filled in the fields, start the deployment by clicking Execute.

Deployment options

Field	Description	Required
customizations/hostname	Hostname	❌
userMetadata/sshKey	SSH public key	❌
userMetadata/imageURL	Linux image URL	✅
userMetadata/imageCheckSum	Image checksum	❌
userMetadata/imageCheckSumType	Image checksum type (md5, sha1, sha256, sha512)	❌(except if checksum provided)
userMetadata/configDriveUserData	cloud-init user-data1	❌
userMetadata/configDriveMetadata	Custom cloud-init metadata, exposed under the `meta_data.json`4	❌
userMetadata/httpHeaders?Key	HTTP Headers key	❌2
userMetadata/httpHeaders?Value	HTTP Headers value	❌2
userMetadata/ediBootloaderPath	EFI bootloader path	✅3

1 Standard cloud-init user-data; typically a #cloud-config document or a script (see the official cloud-init examples). Equivalent to OpenStack's server create --user-data <file>. Its JSON representation must be on a single line \n for line breaks, as JSON strings cannot contain carriage returns.

2 Use only if you need HTTP Headers, such as Basic Auth

3 The EFI bootloader path is used by iPXE to boot your operating system. Examples:

Info

The paths below use JSON escaping: \\ represents a single backslash. For example, \\efi\\debian\\grubx64.efi is the path \efi\debian\grubx64.efi.

Operating System	efiBootloaderPath
Debian	`\\efi\\debian\\grubx64.efi`
Ubuntu	`\\efi\\ubuntu\\grubx64.efi`
Windows	`\\efi\\microsoft\\boot\\bootmgfw.efi`
FreeBSD	`\\efi\\FreeBSD\\loader.efi`
Alma	`\\efi\\almalinux\\shimx64.efi`
Arch Linux	`\\efi\\arch\\grubx64.efi`
Gentoo	`\\efi\\boot\\bootx64.efi`

4 JSON object of arbitrary key/value pairs, equivalent to OpenStack's server create --property key=value. The pairs are written to the config drive's meta_data.json under the meta key, where cloud-init can read them. Example: "configDriveMetadata": {"role": "webserver", "env": "prod"} becomes "meta": {"role": "webserver", "env": "prod"} in meta_data.json. See the OpenStack metadata service documentation for the full schema.

Info

During installation, OVHcloud adds a small config drive partition to your server. Cloud-init reads it at first boot to apply OVHcloud's baseline configuration. Set configDriveUserData to add your own cloud-init user-data.

Warning

NOTE: Unlike standard OVHcloud OS templates (e.g., Debian 12, Windows Server), BYOLinux does not support the postInstallationScript customization option. To run commands or scripts after installation, use configDriveUserData with a cloud-init runcmd directive instead, as in the above example.

Common customer errors

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

Error message	Details	Solution(s)
Please provide checkSum AND checkSumType or none of them	You have specified only one of the arguments `imageCheckSum` and `imageCheckSumType`.	Either provide both arguments or none of them.
image provided format is `x` which does not match expected qcow2 format	Not matter what the file extension is, the real format has to be qcow2.	Convert your image to qcow2 format.
image provided has a size of `n` bytes which is larger than `device` of `m` bytes	The image is larger than the disk chosen for the OS installation.	If your server has several disk groups, you can try to reinstall the OS on another disk group by specifying the `diskgroupid` argument. You need to reduce the size of your image.
Could not download, qcow2 image is too big to download in memory.	Your server doesn't have enough RAM to download the image.	You need to reduce the size of your image.
Could not download image: `<error message>`	Cannot download image from `imageURL`.	Check that a download with the `curl` command from your server works in rescue mode. If some HTTP specific headers are required, you can provide them with the `httpHeaders` argument.
Bad `checkSumType` for downloaded file, got: `n` while expecting `m`.	Incorrect checksum.	Please ensure that you have specified the correct checksum. Check that a download with the `curl` command from your server works in rescue mode.

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

Go further

BYOLinux on GitHub - Examples and in-depth documentation

OVHcloud API and OS Installation

OVHcloud API and Storage

Bring Your Own Image (BYOI)

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

Browse all the Dedicated Servers guides.

Browse the rest of the OVHcloud US documentation for guides on our other products and services.

Learn more about Dedicated Servers on the OVHcloud US website.