ovh / bringyourownlinux

Bring Your Own Linux

• 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 OVH manager
• How does it work?
  • Partitioning the disks
  • Create config-drive
  • Download and burn the customer's image
  • make_image_bootable.sh
• Related links

What is it?

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

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

Requirements

• Baremetal Server
• Working qcow2 image
  • Only one partition
  • The partition must be formatted with either ext4 or XFS
  • An executable /root/.ovh/make_image_bootable.sh script inside the partition

How to make a BYOL-compatible image: two examples

From an already packaged QCOW2 file

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 baremetal servers, there might be some problems.

Handmade image with QEMU

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.

Example with Packer (using QEMU)

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

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

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

   See example in this file

2. An httpdir directory containing:

   • an empty meta-data file
     or can be filled like this one

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

     #!/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 one

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>

Other possible methods

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

How to use it?

Via OVHcloud API

From CLI

You can use a home-made script with the OVH lib, and use a payload like this one:

{
    "details": {
        "customHostname": "myHostname"
    },
    "partitionSchemeName": "default",
    "templateName": "byolinux_64",
    "userMetadata": [
        {
            "key": "imageURL",
            "value": "https://github.com/myself/myImagesFactory/releases/download/0.1/myCustomImage.qcow2"
        },
        {
            "key": "httpHeaders0Key",
            "value": "Authorization"
        },
        {
            "key": "httpHeaders0Value",
            "value": "Basic dGhlb3dsc2FyZW5vdDp3aGF0dGhleXNlZW1z="
        },
        {
            "key": "imageCheckSum",
            "value": "6a65719e6a7f276a4b8685d3ace0920d56acef7d4bbbf9427fe188db7b19c23be7fc182f7a9b29e394167717731f4cd7cab410a36e60e6c6451954f3b795a15c"
        },
        {
            "key": "imageCheckSumType",
            "value": "sha512"
        },
        {
            "key": "configDriveUserData",
            "value": "#!/bin/bash\necho \"Hi, sounds like BYOLinux as ostemplate is a success!\" >/etc/motd"
        }
    ]
}

The key elements here are:

• templateName: which is boylinux_64
• userMetadata: which holds all information to pass to the installer
• httpHeadersXKey and httpHeadersXvalue: whose configure, if necessary the call to retrieve the customer image.
  In this example, we set a basic authentication
• the other items in userMetadata seem quite self-explanatory

From the OVH API Console

As seen in the CLI section, it matches the JSON Payload, and you have only to fill the same items as in the previous example.

Via the OVHcloud Control Panel

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

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

{.thumbnail}

In the window that appears, select Install from OVHcloud template{.action} and click Next{.action}.

{.thumbnail}

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

{.thumbnail}

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

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.

{.thumbnail}

How does it work?

1. Partitioning the disks
2. Creating a config-drive partition
3. Download and burn the customer's image
4. Set boot order
5. Run make_image_bootable.sh
6. Reboot

Partitioning the disks

For an in-depth presentation about partitioning at OVHcloud, see
this awesome talk by Jean-Baptiste Delon and 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 respecting mount points in /tmp/a/.

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

Create config-drive

Provided cloud-init's meta-data files will be copied in a small vfat partition at the end of the disk.

Download and burn the customer's image

The provided image is downloaded in ram/disk[?], and mounted with qemu-nbd in /dev/shm/image.
All the content of the image is then rsynced to the disks

make_image_bootable.sh

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

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

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

There is no internet access at this moment, so if you try to install something not already in the image, it will fail.

See make_image_bootable.sh example file.

Related links

• Contribute
• Report bugs