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:

GET /dedicated/server

To list all compatible OSs 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:

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

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": "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.

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.

Create an OS installation task

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

POST /dedicated/server/{serviceName}/install/start

With the following parameters:

userMetadata contains a list of key/value with the answers to the OS-specific questions:

• Key must be the name of the question.
• Value must be the answer to the question, in the requested type.

Linux payload example

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

{
  "details": {
    "customHostname": "my-host"
  },
  "templateName": "debian12_64",
  "userMetadata": [
    {
      "key": "sshKey",
      "value": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9xPpdqP3sx2H+gcBm65tJEaUbuifQ1uGkgrWtNY0PRKNNPdy+3yoVOtxk6Vjo4YZ0EU/JhmQfnrK7X7Q5vhqYxmozi0LiTRt0BxgqHJ+4hWTWMIOgr+C2jLx7ZsCReRk+fy5AHr6h0PHQEuXVLXeUy/TDyuY2JPtUZ5jcqvLYgQ== my-nuclear-power-plant"
    },
    {
      "key": "postInstallationScript",
      "value": "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.

{
  "details": {
    "customHostname": "my-windows"
  },
  "templateName": "win2022core-std_64",
  "userMetadata": [
    {
      "key": "language",
      "value": "en-us"
    },
    {
      "key": "postInstallationScript",
      "value": "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,
    "ticketReference": null,
    "lastUpdate": "2024-01-26T17:57:10+01:00",
    "needSchedule": false,
    "startDate": "2024-01-26T17:57:10+01:00",
    "status": "init",
    "doneDate": null,
    "tags": null,
    "comment": "Start dedicated server installation",
    "plannedInterventionId": null,
    "note": null,
    "function": "reinstallServer"
}

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

GET /dedicated/server/{serviceName}/task/{taskId}

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

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

Go further

For more information and tutorials, please see our other Dedicated Servers support guides or explore the guides for other OVHcloud products and services.