title	excerpt	updated
OVHcloud API and OS Installation (EN)	Use OVHcloud API to install or reinstall an OS on your dedicated server	2025-02-25

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

Warning

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

Instructions

OS Compatibility

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

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

[!api]

@api {v1} /dedicated/server GET /dedicated/server

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

[!api]

@api {v1} /dedicated/server 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 informations

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

[!api]

@api {v1} /dedicated/installationTemplate GET /dedicated/installationTemplate/{templateName}

You can find interesting information such as the following:

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

[!primary]

If you need to see this information for all available OSs in the catalog, you should consider using the API call /dedicated/installationTemplate/templateInfos{.action} instead.

[!api]

@api {v1} /dedicated/installationTemplate 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.

[!api]

@api {v1} /dedicated/installationTemplate GET /dedicated/installationTemplate/{templateName}

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

[!api]

@api {v1} /dedicated/server 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.

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

[!primary]

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

[!primary]

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 customizations section.

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.

Warning

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

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:

[!api]

@api {v1} /dedicated/server GET /dedicated/server/{serviceName}/task/{taskId}

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

[!api]

@api {v1} /dedicated/server GET /dedicated/server/{serviceName}/install/status

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:

[!api]

@api {v1} /dedicated/server GET /dedicated/server/{serviceName}

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

[!api]

@api {v1} /dedicated/server PUT /dedicated/server/{serviceName}

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

guide.pl-pl.md

guide.pl-pl.md

Objective

Requirements

Instructions

OS Compatibility

OS Details informations

OS Questions

Create an OS reinstallation task

Linux payload example

Windows payload example

Example reply

Manage efi bootloader path

Go further

Files

guide.pl-pl.md

Latest commit

History

guide.pl-pl.md

File metadata and controls

Objective

Requirements

Instructions

OS Compatibility

OS Details informations

OS Questions

Create an OS reinstallation task

Linux payload example

Windows payload example

Example reply

Manage efi bootloader path

Go further