OVHcloud API and OS Installation

Learn about fully automating OS installation or reinstallation on a dedicated server with the OVHcloud API.

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 OSes 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 information

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

The response will show information such as:

1 Customers that don't use images from the OVHcloud catalog (installation from a custom image (BYOI/BYOLinux), installation over the network, or manually via IPMI) are not affected by this limitation.

2 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:

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

Create an OS installation 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:

1 Operating system specific; some customization(s) might be required on some operating systems.

name 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 and 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": "my-host",
    "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) with a custom PowerShell post-installation script.

{
  "operatingSystem": "win2022core-std_64",
  "customizations": {
    "hostname": "my-windows",
    "language": "en-us",
    "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 the Windows post-installation script, the following files will 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 installation task ID. You can follow the OS installation task status with the following API call:

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

Manage efi bootloader path

A default efi bootloader path is set when installing from OVHcloud templates but you can 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

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.