--- title: "Bring Your Own Image (BYOI)" description: "The Bring Your Own Image technology (BYOI) enables you to deploy cloudready images directly on your dedicated server. You can therefore use the bare metal servi" url: https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/bring-your-own-image lang: en --- > For AI agents: the complete documentation index is available at https://docs.us.ovhcloud.com/en/llms.txt, the full documentation bundle is available at https://docs.us.ovhcloud.com/en/llms-full.txt. # Bring Your Own Image (BYOI) The Bring Your Own Image technology (BYOI) enables you to deploy _cloudready_ 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](https://us.ovhcloud.com/bare-metal/) in your OVHcloud account - Access to the [OVHcloud API](https://docs.us.ovhcloud.com/en/manage-and-operate/api/first-steps.md) (for the "[Deployment via API](#deploying-your-image-via-the-apis)" section of this guide) - Your image must be smaller than the server RAM minus 3GiB **Note:** To apply OVHcloud customization at first boot, your image must include [clout-init](https://cloud-init.io/) or a compatible alternative (such as FreeBSD's `nuageinit`). #### OVHcloud Control Panel Access - **Direct link:** [Dedicated Servers](https://manager.us.ovhcloud.com/#/dedicated-servers/server) - **Navigation path:** `Bare Metal Cloud` > `Dedicated servers` > Select your server **Warning:** **NOTE:** As with any classical OS installation, a new installation with BYOI 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** - Partition type: **MBR** or **GPT** - Image format: **qcow2** or **raw** **Warning:** **About RAID:** - Bring Your Own Image (BYOI) does not support software RAID configuration at install time, but you can use the service [Bring Your Own Linux (BYOLinux)](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/bring-your-own-linux.md) for that. Choose the custom image method that fits your needs: [Bring Your Own Image (BYOI) / Bring Your Own Linux (BYOLinux), a comparison sheet](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/bring-your-own-image-versus-bring-your-own-linux.md). - BYOI deploys the image to a single disk: the first disk of the target disk group. - Hardware RAID works on servers with a RAID controller, because it presents the array to the operating system as a single virtual disk. **Deployment methods:** - [Deployment via the Control Panel](#deploy-your-image-via-the-control-panel): allows you to deploy your image using the OVHcloud Control Panel. - [Deployment via API](#deploying-your-image-via-the-apis): 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)** and select `Install`. In the window that appears, select `Custom` in the menu, then `Bring Your Own Image - byoi`, 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](#deployment-options) section below.   ### Deploying your image via the API Log in to the [API console](https://api.us.ovhcloud.com/) and go to the `/dedicated/server` section. [POST /dedicated/server/{serviceName}/reinstall](https://api.us.ovhcloud.com/console/?section=/dedicated/server&branch=v1#post-/dedicated/server/-serviceName-/reinstall) The Bring Your Own Image (BYOI) payload should be similar to the following: **Warning:** **NOTE:** In the `customizations` section, only `imageURL`, `imageType`, and `efiBootloaderPath` are mandatory. ```json { "operatingSystem": "byoi_64", "customizations": { "hostname": "my-host", "imageURL": "https://cdimage.debian.org/cdimage/cloud/bullseye/20230124-1270/debian-11-generic-amd64-20230124-1270.raw", "imageType": "raw", "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9xPpdqP3sx2H+gcBm65tJEaUbuifQ1uGkgrWtNY0PRKNNPdy+3yoVOtxk6Vjo4YZ0EU/JhmQfnrK7X7Q5vhqYxmozi0LiTRt0BxgqHJ+4hWTWMIOgr+C2jLx7ZsCReRk+fy5AHr6h0PHQEuXVLXeUy/TDyuY2JPtUZ5jcqvLYgQ== my-nuclear-power-plant", "efiBootloaderPath": "\\efi\\debian\\grubx64.efi", "imageCheckSum": "2cbd3dd5606ef95a5cfa47943b3ad453fcc43522915be7f559a296a71395f82f88e621e558df7aa5f3d2e62c20043f9430ad18c900e565a1c070066e8d008aaa", "httpHeaders": { "Authorization": "Basic bG9naW46cGFzc3dvcmQ=" }, "imageCheckSumType": "sha512", "configDriveUserData": "I2Nsb3VkLWNvbmZpZwpzc2hfYXV0aG9yaXplZF9rZXlzOgogIC0gc3NoLXJzYSBBQUFBQjhkallpdz09IG15c2VsZkBteWRvbWFpbi5uZXQKCnVzZXJzOgogIC0gbmFtZTogcGF0aWVudDAKICAgIHN1ZG86IEFMTD0oQUxMKSBOT1BBU1NXRDpBTEwKICAgIGdyb3VwczogdXNlcnMsIHN1ZG8KICAgIHNoZWxsOiAvYmluL2Jhc2gKICAgIGxvY2tfcGFzc3dkOiBmYWxzZQogICAgc3NoX2F1dGhvcml6ZWRfa2V5czoKICAgICAgLSBzc2gtcnNhIEFBQUFCOGRqWWl3PT0gbXlzZWxmQG15ZG9tYWluLm5ldApkaXNhYmxlX3Jvb3Q6IGZhbHNlCnBhY2thZ2VzOgogIC0gdmltCiAgLSB0cmVlCmZpbmFsX21lc3NhZ2U6IFRoZSBzeXN0ZW0gaXMgZmluYWxseSB1cCwgYWZ0ZXIgJFVQVElNRSBzZWNvbmRzCg==" } } ``` 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: ```bash cat my-data.yaml | base64 -w0 ``` Here is the clear-text version of `configDriveUserData` from the example above: ```yaml #cloud-config ssh_authorized_keys: - ssh-rsa AAAAB8djYiw== myself@mydomain.com users: - name: patient0 sudo: ALL=(ALL) NOPASSWD:ALL groups: users, sudo shell: /bin/bash lock_passwd: false ssh_authorized_keys: - ssh-rsa AAAAB8djYiw== myself@mydomain.com disable_root: false packages: - vim - tree 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 | Image URL | ✅ | | userMetadata/imageType | Image format (qcow2, raw) | ✅ | | 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` key of 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](https://cloudinit.readthedocs.io/en/latest/explanation/format.html) — typically a `#cloud-config` document or a script (see the [official cloud-init examples](https://docs.cloud-init.io/en/latest/reference/examples.html)). Equivalent to OpenStack's `server create --user-data `. Its JSON representation must be on a single line with `\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: **Note:** 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](https://docs.openstack.org/nova/latest/user/metadata.html#openstack-format-metadata) for the full schema. **Note:** When you set any customization on this page, OVHcloud adds a small [config drive](https://docs.cloud-init.io/en/latest/reference/datasources/configdrive.html) partition during installation; otherwise, no config drive is created. Cloud-init reads it at first boot. Set `configDriveUserData` to add your own cloud-init user-data.   #### 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 | No matter what the file extension is, the real format has to be qcow2. | | | 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. | | | Can't write `t` on disk | Impossible to write qcow2/raw image on disk. | Modify your image so that the command `qemu-img convert -f "$imageType" -O raw $pathToImageFile "$device"` works. | | Could not download, `t` 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: `` | 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. | | image provided format is not of type raw because no partition table was found. It seems to contain: `x` | A raw image must contain a partition table. | Check that your image contains a partition table. | | Bad `checkSumType` for downloaded file, got: `n` while expecting `m`. | Incorrect checksum. | |   ## Go further [OVHcloud API and OS Installation](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/ovhcloud-api-os-installation.md) [Bring Your Own Linux (BYOLinux)](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/bring-your-own-linux.md) [Bring Your Own Image (BYOI) / Bring Your Own Linux (BYOLinux), a comparison sheet](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/bring-your-own-image-versus-bring-your-own-linux.md) Browse all the [Dedicated Servers guides](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/landing-page-dedicated-servers.md). Browse the rest of the [OVHcloud US documentation](https://docs.us.ovhcloud.com/en/index.md) for guides on our other products and services. Learn more about [Dedicated Servers](https://us.ovhcloud.com/bare-metal/) on the OVHcloud US website.