--- title: "OVHcloud API and OS Installation" description: "Learn about fully automating OS installation or reinstallation on a dedicated server with the OVHcloud API." url: https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/ovhcloud-api-os-installation lang: en --- > For AI agents: the complete documentation index is available at https://docs.us.ovhcloud.com/en/llms.txt, the full documentation bundle is available at https://docs.us.ovhcloud.com/en/llms-full.txt. # OVHcloud API and OS Installation **Learn about fully automating OS installation or reinstallation on a [dedicated server](https://us.ovhcloud.com/bare-metal/) with the [OVHcloud API](https://docs.us.ovhcloud.com/en/manage-and-operate/api/first-steps.md).**   ## Requirements - A [dedicated server](https://us.ovhcloud.com/bare-metal/) in your OVHcloud account - Access to the [OVHcloud API](https://docs.us.ovhcloud.com/en/manage-and-operate/api/first-steps.md) **Warning:** **NOTE:** A new installation will erase all the data on the server.   ## Instructions ### OS Compatibility Log in to the [API console](https://api.us.ovhcloud.com/) and go to the `/dedicated/server` section. You can list all your dedicated servers with the following API call: [GET /dedicated/server](https://api.us.ovhcloud.com/console/?section=/dedicated/server&branch=v1#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](https://api.us.ovhcloud.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 information In the `/dedicated/installationTemplate` section, you can display the details for a specific OS: [GET /dedicated/installationTemplate/{templateName}](https://api.us.ovhcloud.com/console/?section=/dedicated/installationTemplate&branch=v1#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) | 1 Customers that don't use images from the OVHcloud catalog (installation from a custom image ([BYOI](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/bring-your-own-image.md)/[BYOLinux](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/bring-your-own-linux.md)), installation over the network, or manually via IPMI) are not affected by this limitation. 2 For more details, see [partitioning customization](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/partitioning-ovh.md). **Note:** 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](https://api.us.ovhcloud.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. 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`) | 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: [POST /dedicated/server/{serviceName}/reinstall](https://api.us.ovhcloud.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 | ⚠️1 | | storage | OS reinstallation storage configurations | ❌ | 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](https://docs.us.ovhcloud.com/en/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": "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: ```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 ``` **Note:** 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. ```json { "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: ```powershell [System.Convert]::ToBase64String((Get-Content -Path .\my-script.ps1 -Encoding Byte)) ``` Here is the clear-text post-installation PowerShell script from the example above: ```powershell "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. **Note:** 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`. **Warning:** **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: ```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 installation task ID. You can follow the OS installation task status with the following API call: [GET /dedicated/server/{serviceName}/task/{taskId}](https://api.us.ovhcloud.com/console/?section=/dedicated/server&branch=v1#get-/dedicated/server/-serviceName-/task/-taskId-) You can also monitor the progress of the installation process with the following API call that displays a detailed list of steps: [GET /dedicated/server/{serviceName}/install/status](https://api.us.ovhcloud.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 can manage it. You can retrieve it with the following API call: [GET /dedicated/server/{serviceName}](https://api.us.ovhcloud.com/console/?section=/dedicated/server&branch=v1#get-/dedicated/server/-serviceName-) You also can set it in the payload of the following API call: [PUT /dedicated/server/{serviceName}](https://api.us.ovhcloud.com/console/?section=/dedicated/server&branch=v1#put-/dedicated/server/-serviceName-)   ## Go further Browse all the [Dedicated Servers guides](https://docs.us.ovhcloud.com/en/bare-metal-cloud/dedicated-servers/landing-page-dedicated-servers.md). Browse the rest of the [OVHcloud US documentation](https://docs.us.ovhcloud.com/en/index.md) for guides on our other products and services. Learn more about [Dedicated Servers](https://us.ovhcloud.com/bare-metal/) on the OVHcloud US website.