OVHcloud API and OS Installation – Support Guides

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

NOTE: A new installation will erase all the data on the server.

Instructions

OS Compatibility

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

GET /dedicated/server

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

GET /dedicated/server/{serviceName}/install/compatibleTemplates

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:

GET /dedicated/installationTemplate/{templateName}

The response will show information such as:

Attribute	Description
distribution	OS Name
description	OS Display Name
endOfInstall	OVHcloud OS end of availability date¹
usage,category,family	Usage, category, and OS family
project/os	Information about OS governance, version, release notes, and project URL
project/usage	Same as project/os, but at the software layer if applicable
license/os	Information about OS license: licensing contract URL and licensing type
license/usage	Same as license/os, but at the software layer if applicable
filesystems	Compatible file systems types
softRaidOnlyMirroring,lvmReady	Compatibility with hardware raids, software raids, and LVM²
inputs	OS-specific questions (see explanation below)

¹ 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.

² For more details, see partitioning customization.

If you need to see this information for all available OSes in the catalog, you should consider using the following API call instead:

GET /dedicated/installationTemplate/templateInfos

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:

Attribute	Description
default	If no answer is provided, this value will be used
mandatory	If this question is mandatory¹
type	Value type expected in the answer
name	Question name (used as identifier)
description	Question description
enum	Possible values (only applicable for `enum` `type`)

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

Disk Groups

Some dedicated servers have multiple groups of disks. For example, one group with SATA disks and another group with SSD disks. Those servers are sometimes also called hybrid servers.

To list the disk groups and their disks, you can use the following API call to identify the disk group on which you want the OS to be installed:

GET /dedicated/server/{serviceName}/specifications/hardware

Example reply:

{
  "bootMode": "uefi",
  "defaultHardwareRaidSize": null,
  "description": "SCALE-7 - AMD Epyc 7763",
  "expansionCards": null,
  "threadsPerProcessor": 128,
  "memorySize": {
    "unit": "MB",
    "value": 524288
  },
  "defaultHardwareRaidType": null,
  "diskGroups": [
    {
      "defaultHardwareRaidType": null,
      "numberOfDisks": 2,
      "diskGroupId": 1,
      "diskType": "SSD",
      "defaultHardwareRaidSize": null,
      "diskSize": {
        "unit": "GB",
        "value": 480
      },
      "description": "2 X Disk SSD 480 GB, JBOD",
      "raidController": null
    },
    {
      "defaultHardwareRaidType": null,
      "numberOfDisks": 2,
      "diskGroupId": 2,
      "diskType": "NVME",
      "defaultHardwareRaidSize": null,
      "diskSize": {
        "unit": "GB",
        "value": 1920
      },
      "raidController": null,
      "description": "2 X Disk NVME 1920 GB, JBOD"
    }
  ],
  "processorArchitecture": "x86_64",
  "coresPerProcessor": 64,
  "processorName": "Epyc7763",
  "formFactor": "1u",
  "motherboard": "S8036-M",
  "numberOfProcessors": 1,
  "usbKeys": null
}

In this example, there are two disk groups:

the first one (diskGroupId=1) contains 2 x 480 GB disks.
the second one (diskGroupId=2) contains 2 x 1.9 TB disks.

By default, the OS will be installed on diskGroupId 1.

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:

POST /dedicated/server/{serviceName}/reinstall

With the following parameters:

Parameter	Value	Required
serviceName	Server name	✅
operatingSystem	OS to install	✅
customizations	OS reinstallation customizations	⚠️¹
storage	OS reinstallation storage configurations	❌
properties	Arbitrary properties to pass to cloud-init's config drive datasource	❌

¹ 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.

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

For UNIX/Linux OS, you can provide scripts in any programming language (if running stack is installed on the target OS) that matches the provided shebang.

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.

For Windows OS, you can provide PowerShell or batch scripts. If you want to provide a batch script, please provide cmd value to key postInstallationScriptExtension in the userMetadata payload.

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.

NOTE: The Windows post-installation script is run as the Administrator local account. You can finish your script with a shutdown /l command to log off the Windows session, although the Administrator local account is locked and cannot be accessed remotely (via RDP connection).

Example reply:

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