OVHcloud API and OS Installation

Objective

Fully automating OS installation or reinstallation on a dedicated server with the OVHcloud API can be interesting in various situations.

Requirements

• A dedicated server in your OVHcloud account
• Access to the OVHcloud API

Instructions

OS Compatibility

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

You can list all your dedicated servers with the following API call:

To list all compatible OSs for a specific dedicated server, you can use the following API call:

In the response, look at the contents of the ovh key: this is the list of OSs in the OVHcloud catalog that you can install on this server.

OS Details informations

In the /dedicated/installationTemplate section, you can display the details for a specific OS:

You can find interesting information such as the following:

¹ Customers that don't use images from the OVHcloud catalogue (installation from a custom image (BYOI/BYOLinux), installation over the network, or manually via IPMI) are not affected by this limitation.
² For more details, see partitioning customization.

OS Questions

Some OSs can have a list of specific questions. If that is the case, the inputs key contains a list of questions.

Example of specific questions for Debian 12 (Bookworm):

{
    "inputs": [
        {
            "name": "hostname",
            "description": "Custom hostname",
            "default": "",
            "mandatory": false,
            "type": "hostname",
            "enum": []
        },
        {
            "name": "sshKey",
            "description": "SSH Public Key",
            "default": "",
            "mandatory": false,
            "type": "sshPubKey",
            "enum": []
        },
        {
            "name": "postInstallationScript",
            "description": "Post-Installation Script",
            "default": "",
            "mandatory": false,
            "type": "text",
            "enum": []
        }
    ]
}

Example of specific questions for Windows Server 2022 Standard (Core):

{
    "inputs": [
        {
            "name": "language",
            "description": "Display Language",
            "default": "en-us",
            "mandatory": false,
            "type": "enum",
            "enum": [
                "en-us",
                "fr-fr"
            ]
        },
        {
            "name": "postInstallationScript",
            "description": "Post-Installation Script",
            "default": "",
            "mandatory": false,
            "type": "text",
            "enum": []
        },
        {
            "name": "postInstallationScriptExtension",
            "description": "Post-Installation Script File Extension",
            "default": "ps1",
            "mandatory": true,
            "type": "enum",
            "enum": [
                "ps1",
                "cmd"
            ]
        }
    ]
}

Each question has the following attributes:

¹ If a mandatory question without default value is not answered, the API will return an error.

Create an OS reinstallation task

When you have gathered all the information that you need, you can create the OS reinstallation task with the following API call:

With the following parameters:

¹ Operating system specific, some customization(s) might be required on some operating systems.

customizations contains a hash with the answers to the OS-specific questions: hash key is the name of the question and its value is the answer to that question, in the requested type.

storage contains customization related to disks & hardware RAID, partitions, software RAID, LVM, ZFS, etc. See OVHcloud API and Storage for more details.

Linux payload example

The following payload will install Debian 12 (Bookworm) with SSH key-based authentication and a custom bash post-installation script:

{
  "operatingSystem": "debian12_64",
  "customizations": {
    "hostname": "mon-tux",
    "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9xPpdqP3sx2H+gcBm65tJEaUbuifQ1uGkgrWtNY0PRKNNPdy+3yoVOtxk6Vjo4YZ0EU/JhmQfnrK7X7Q5vhqYxmozi0LiTRt0BxgqHJ+4hWTWMIOgr+C2jLx7ZsCReRk+fy5AHr6h0PHQEuXVLXeUy/TDyuY2JPtUZ5jcqvLYgQ== my-nuclear-power-plant",
    "postInstallationScript": "IyEvYmluL2Jhc2gKZWNobyAiY291Y291IHBvc3RJbnN0YWxsYXRpb25TY3JpcHQiID4gL29wdC9jb3Vjb3UKY2F0IC9ldGMvbWFjaGluZS1pZCAgPj4gL29wdC9jb3Vjb3UKZGF0ZSAiKyVZLSVtLSVkICVIOiVNOiVTIiAtLXV0YyA+PiAvb3B0L2NvdWNvdQo="
  }
}

Even though the post-installation script could be sent to 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 script:

cat my-script.sh | base64 -w0

Here is the clear-text post-installation bash script from the example above:

#!/bin/bash
echo "coucou postInstallationScript" > /opt/coucou
cat /etc/machine-id  >> /opt/coucou
date "+%Y-%m-%d %H:%M:%S" --utc >> /opt/coucou

Windows payload example

The following payload will install Windows Server 2022 Standard (Core) in French with a custom PowerShell post-installation script.

{
  "operatingSystem": "win2022core-std_64",
  "customizations": {
    "hostname": "ma-fenetre",
    "language": "fr-fr",
    "postInstallationScript": "ImNvdWNvdSBwb3N0SW5zdGFsbGF0aW9uU2NyaXB0UG93ZXJTaGVsbCIgfCBPdXQtRmlsZSAtRmlsZVBhdGggImM6XG92aHVwZFxzY3JpcHRcY291Y291LnR4dCIKKEdldC1JdGVtUHJvcGVydHkgLUxpdGVyYWxQYXRoICJSZWdpc3RyeTo6SEtMTVxTT0ZUV0FSRVxNaWNyb3NvZnRcQ3J5cHRvZ3JhcGh5IiAtTmFtZSAiTWFjaGluZUd1aWQiKS5NYWNoaW5lR3VpZCB8IE91dC1GaWxlIC1GaWxlUGF0aCAiYzpcb3ZodXBkXHNjcmlwdFxjb3Vjb3UudHh0IiAtQXBwZW5kCihHZXQtRGF0ZSkuVG9Vbml2ZXJzYWxUaW1lKCkuVG9TdHJpbmcoInl5eXktTU0tZGQgSEg6bW06c3MiKSB8IE91dC1GaWxlIC1GaWxlUGF0aCAiYzpcb3ZodXBkXHNjcmlwdFxjb3Vjb3UudHh0IiAtQXBwZW5kCg=="
  }
}

Even though the post-installation script could be sent to 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 PowerShell command to encode your script:

[System.Convert]::ToBase64String((Get-Content -Path .\my-script.ps1 -Encoding Byte))

Here is the clear-text post-installation PowerShell script from the example above:

"coucou postInstallationScriptPowerShell" | Out-File -FilePath "c:\ovhupd\script\coucou.txt"
(Get-ItemProperty -LiteralPath "Registry::HKLM\SOFTWARE\Microsoft\Cryptography" -Name "MachineGuid").MachineGuid | Out-File -FilePath "c:\ovhupd\script\coucou.txt" -Append
(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd HH:mm:ss") | Out-File -FilePath "c:\ovhupd\script\coucou.txt" -Append

As you can see, this PowerShell script for Windows is equivalent to the previous bash script for Linux.

While running Windows post-installation script, the following files while remain:

• The script itself: c:\ovhupd\script\custrun.ps1 (or c:\ovhupd\script\custrun.cmd if batch script).
• Log file: c:\ovhupd\script\customerscriptlog.txt.

Example reply

{
    "taskId": 123456789,
    "status": "init",
    "startDate": "2024-01-26T17:57:10+01:00",
    "doneDate": null,
    "function": "reinstallServer",
    "comment": "Start bare metal OS installation"
}

123456789 is the OS reinstallation task ID. You can follow the OS reinstallation task status with the following API call:

You can also monitor the progress of the reinstallation process with the following API call which displays a detailed list of steps:

Manage efi bootloader path

A default efi bootloader path is set when installing from OVHcloud templates but you have the possibility to manage it.

You can retrieve it with the following API call:

You also can set it in the payload of the following API call:

Go further

Getting started with a dedicated server

Getting started with a Kimsufi, So You Start or Rise dedicated server

Bring Your Own Image (BYOI)

Bring Your Own Linux (BYOLinux)

OVHcloud API and Storage

Managing software RAID

Managing hardware RAID

Join our community of users.