• What is it?
• Requirements
• How to make a BYOL-compatible image
  • From a QCOW2 file
    • With Qemu
    • With Packer
  • Other methods
• How to use it?
  • Via api.ovh.com
  • Via the OVHcloud Control Panel
• How does it work?
  • Partitioning the disks
  • Create config-drive
  • Download and burn the customer's image
  • make_image_bootable.sh
• Related links

Bring Your Own Linux is somewhat of an extension of the Bring Your Own Image feature. It enables you to install any Linux of your choice with additional features, like:

• Custom partitioning using the OVHcloud API, software RAID, LVM, ZFS, etc.
• Custom cloud-init meta-data

• A bare metal server
• Working qcow2 image
  • Only one partition
  • The partition must be formatted with ext4, XFS, or BTRFS (without subvolumes)
  • An executable /root/.ovh/make_image_bootable.sh script inside the partition

You can use an already packaged Linux image made by your favorite distro:

• Debian
• Ubuntu
• Fedora
• whatever Linux you want

Be aware that some Linux distributions have virtualization-oriented kernels within their QCOW2 images. When trying to boot these kernels on bare metal servers, there might be some problems.

The following procedure was executed on a Debian 11 bare metal server as the root user

# qemu-system will be used to connect to the virtual machine
# libguestfs-tools will allow you to change the root password before booting
apt install -y qemu-system libguestfs-tools
wget https://cdimage.debian.org/cdimage/cloud/bookworm/latest/debian-12-generic-amd64.qcow2
virt-customize -a debian-12-generic-amd64.qcow2 --root-password password:password
qemu-system-x86_64 -m 512 -nographic -hdb debian-12-generic-amd64.qcow2 -device vmxnet3,netdev=eno1 -netdev user,id=eno1
# you are now on the login prompt of the image
# and you can begin customization

Be careful as you might not have enough space left on the disk to add too much stuff.

root@localhost:~# df -h
Filesystem      Size  Used Avail Use% Mounted on
udev            210M     0  210M   0% /dev
tmpfs            46M  408K   46M   1% /run
/dev/sda1       1.9G  997M  744M  58% /
tmpfs           229M     0  229M   0% /dev/shm
tmpfs           5.0M     0  5.0M   0% /run/lock
/dev/sda15      124M   12M  113M  10% /boot/efi
tmpfs            46M     0   46M   0% /run/user/0

As seen in the video, every modification done while in qemu will be saved. You can add scripts, files, packages, services.

All the following process is done on a Debian 11 bare metal server as root user

Contrary to the previous method, you can add all you want in this one as packer will automatically expand the disk.

1. A mydistrib.json file is required to run packer

   For an example, see this file

2. An httpdir directory containing:

   • an empty meta-data file or filled as in this example

   • a user-data file that can be either a script, as follows:

     #!/bin/bash
     set -e
     export DEBIAN_FRONTEND=noninteractive
     apt-get -y update
     apt-get -y install linux-image-amd64
     apt-get -y autoremove
     apt-get clean
     shutdown -Hr now

     or a cloud-init script like this example

3. Install packer, qemu-system-x86, genisoimage, and qemu-utils

       apt install --no-install-recommends packer qemu-system-x86 qemu-utils genisoimage

4. Run packer

       PACKER_LOG=1 packer build mydistrib.json

5. The resulting image is in <output_directory>/<vm_name>

Although we will not provide detailed procedures for these, the following methods could also be used (not an exhaustive list):

• From an ISO installation in a VM (possibly via Packer)
• Using tools such as debootstrap

You can use a home-made script with a payload like this one:

POST /dedicated/server/{serviceName}/reinstall

{
  "operatingSystem": "byolinux_64",
  "customizations": {
    "hostname": "myHostname",
    "imageURL": "https://github.com/myself/myImagesFactory/releases/download/0.1/myCustomImage.qcow2",
    "imageCheckSum": "6a65719e6a7f276a4b8685d3ace0920d56acef7d4bbbf9427fe188db7b19c23be7fc182f7a9b29e394167717731f4cd7cab410a36e60e6c6451954f3b795a15c",
    "httpHeaders": {
      "Authorization": "Basic dGhlb3dsc2FyZW5vdDp3aGF0dGhleXNlZW1z="
    },
    "imageCheckSumType": "sha512",
    "configDriveUserData": "#!/bin/bash\necho \"Hi, sounds like BYOLinux as ostemplate is a success!\" >/etc/motd"
  }
}

The key elements here are:

• operatingSystem: which is byolinux_64
• customizations: which holds all information to pass to the installer
• customizations/httpHeaders: which can be used to configure headers for retrieving the customer image, if necessary. In this example, we use Basic authentication
• The other items in customizations are self-explanatory

Log in to the OVHcloud Control Panel and go to the Bare Metal Cloud section, then select your server under Dedicated servers.

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

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 How to use it? section.

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

1. Partition the disks
2. Create the config-drive partition
3. Download and write the customer's image
4. Run make_image_bootable.sh
5. Reboot

For an in-depth presentation about partitioning at OVHcloud, see the official documentation

With the provided partition scheme, the disks will be partitioned and formatted with the selected filesystem. All partitions are mounted on their respective mount points in /tmp/a/.

/tmp/a/home
/tmp/a/boot
/tmp/a/var

The provided cloud-init meta-data files will be copied to a small vfat partition at the end of the disk.

The provided image is downloaded into memory and mounted with qemu-nbd at /dev/shm/image. All the content of the image is then rsynced to the disks.

make_image_bootable.sh has to be located in /root/.ovh/ and be executable.

The script is executed once, right after the image is deployed on the partitioned disk, and right before the first reboot into the new installation.

The script can be used, for instance, to generate an ad hoc initramfs, embedding drivers dedicated to the system the image will boot on.

The script runs chrooted into the deployed filesystem, not the rescue system itself. Internet access may be available, but it is recommended to include all necessary packages in your image rather than relying on network access during this step.

See the make_image_bootable.sh example file.

• Report bugs