--- title: "Install an OS via the OVHcloud API on a Dedicated Server" description: "Use OVHcloud API to install or reinstall an OS on your dedicated server" url: https://docs.ovhcloud.com/en/guides/bare-metal-cloud/dedicated-servers/api-os-installation lang: en lastUpdated: 2025-06-06 --- # Install an OS via the OVHcloud API on a Dedicated Server ## Objective Fully automating OS installation or reinstallation on a [dedicated server](https://www.ovhcloud.com/en-gb/bare-metal/) with the [OVHcloud API](/en/guides/manage-and-operate/api/first-steps.md) can be interesting in various situations. ## Requirements - A [dedicated server](https://www.ovhcloud.com/en-gb/bare-metal/) in your OVHcloud account - Access to the [OVHcloud API](/en/guides/manage-and-operate/api/first-steps.md) :::warning A new installation will erase all the data on the server. ::: ## Instructions ### OS Compatibility [](#) Log in to the [API console](https://eu.api.ovh.com/) and go to the `/dedicated/server ` section. You can list all your [dedicated servers](https://www.ovhcloud.com/en-gb/bare-metal/) with the following API call: 🇪🇺EU▾ [GET/dedicated/server](https://eu.api.ovh.com/console/?section=/dedicated/server&branch=v1#get-/dedicated/server) To list all compatible OSs for a specific dedicated server, you can use the following API call: 🇪🇺EU▾ [GET/dedicated/server/{serviceName}/install/compatibleTemplates](https://eu.api.ovh.com/console/?section=/dedicated/server&branch=v1#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 ` section, you can display the details for a specific OS: 🇪🇺EU▾ [GET/dedicated/installationTemplate/{templateName}](https://eu.api.ovh.com/console/?section=/dedicated/installationTemplate&branch=v1#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](/en/guides/bare-metal-cloud/dedicated-servers/bring-your-own-image.md) /[BYOLinux](/en/guides/bare-metal-cloud/dedicated-servers/bring-your-own-linux.md) ), installation over the network, or manually via IPMI) are not affected by this limitation. ² For more details, see [partitioning customization](/en/guides/bare-metal-cloud/dedicated-servers/partitioning-ovh.md) . :::info If you need to see this information for all available OSs in the catalog, you should consider using the API call `/dedicated/installationTemplate/templateInfos ` instead. ::: 🇪🇺EU▾ [GET/dedicated/installationTemplate/templateInfos](https://eu.api.ovh.com/console/?section=/dedicated/installationTemplate&branch=v1#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. 🇪🇺EU▾ [GET/dedicated/installationTemplate/{templateName}](https://eu.api.ovh.com/console/?section=/dedicated/installationTemplate&branch=v1#get-/dedicated/installationTemplate/-templateName-) Example of specific questions for Debian 12 (Bookworm): ```json { "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): ```json { "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: 🇪🇺EU▾ [POST/dedicated/server/{serviceName}/reinstall](https://eu.api.ovh.com/console/?section=/dedicated/server&branch=v1#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 | ❌ | ¹ 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](/en/guides/bare-metal-cloud/dedicated-servers/partitioning-ovh.md) 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: ```json { "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: ```bash cat my-script.sh | base64 -w0 ``` Here is the clear-text post-installation bash script from the example above: ```bash #!/bin/bash echo "coucou postInstallationScript" > /opt/coucou cat /etc/machine-id >> /opt/coucou date "+%Y-%m-%d %H:%M:%S" --utc >> /opt/coucou ``` :::info 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. ```json { "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: ```ps1 [System.Convert]::ToBase64String((Get-Content -Path .\my-script.ps1 -Encoding Byte)) ``` Here is the clear-text post-installation PowerShell script from the example above: ```ps1 "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. :::info 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 ```json { "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: 🇪🇺EU▾ [GET/dedicated/server/{serviceName}/task/{taskId}](https://eu.api.ovh.com/console/?section=/dedicated/server&branch=v1#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: 🇪🇺EU▾ [GET/dedicated/server/{serviceName}/install/status](https://eu.api.ovh.com/console/?section=/dedicated/server&branch=v1#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: 🇪🇺EU▾ [GET/dedicated/server/{serviceName}](https://eu.api.ovh.com/console/?section=/dedicated/server&branch=v1#get-/dedicated/server/-serviceName-) You also can set it in the payload of the following API call: 🇪🇺EU▾ [PUT/dedicated/server/{serviceName}](https://eu.api.ovh.com/console/?section=/dedicated/server&branch=v1#put-/dedicated/server/-serviceName-) ## Go further [Getting started with a dedicated server](/en/guides/bare-metal-cloud/dedicated-servers/getting-started-with-dedicated-server.md) [Getting started with a Kimsufi, So You Start or Rise dedicated server](/en/guides/bare-metal-cloud/dedicated-servers/getting-started-with-dedicated-server-eco.md) [Bring Your Own Image (BYOI)](/en/guides/bare-metal-cloud/dedicated-servers/bring-your-own-image.md) [Bring Your Own Linux (BYOLinux)](/en/guides/bare-metal-cloud/dedicated-servers/bring-your-own-linux.md) [OVHcloud API and Storage](/en/guides/bare-metal-cloud/dedicated-servers/partitioning-ovh.md) [Managing software RAID](/en/guides/bare-metal-cloud/dedicated-servers/raid-soft.md) [Managing hardware RAID](/en/guides/bare-metal-cloud/dedicated-servers/raid-hard.md) [Installing CUDA on a Dedicated Server with GPU](/en/guides/bare-metal-cloud/dedicated-servers/cuda-installation-on-gpu.md) Join our [community of users](https://community.ovhcloud.com/).