# Managing Operating System templates MetalSoft provides templates for the important operating systems. The templates are often customized to suit the respective deployment's needs. Use the [CLI](/content/overview/installation/using_the_cli) to list and register (install in the environment) a template from the repository. The CLI pulls the templates from a repository. The default repository is [https://github.com/metalsoft-io/os-templates](https://github.com/metalsoft-io/os-templates) but a company specific template repository could also be used by providing a `--repo` option to the CLI. ## Listing available source templates ``` metalcloud-cli os-template list-source-templates +-----------+-----------------------+--------------+----------------+-----------+-------------------------------------------+ | TYPE | VERSION | ARCHITECTURE | DEPLOY PROCESS | BOOT TYPE | SOURCE TEMPLATE PATH | +-----------+-----------------------+--------------+----------------+-----------+-------------------------------------------+ | AlmaLinux | 8 | x64 | pxe | UEFI | AlmaLinux/non-OOB-8 | | ESXi | 7.0.0 | x64 | virtual_media | UEFI | ESXi/OOB-7.0.0 | | ESXi | 7.0.0.u03-DellEMC-A02 | x64 | virtual_media | UEFI | ESXi/OOB-7.0.0.u03-DellEMC_Customized-A02 | | Ubuntu | 20.04 | x64 | virtual_media | UEFI | Ubuntu/non-OOB-20.04 | | Ubuntu | 20.04 | x64 | pxe | UEFI | Ubuntu/non-OOB-20.04-iscsi-ibft-uefi | | Ubuntu | 20.04.4 | x64 | virtual_media | UEFI | Ubuntu/OOB-20.04 | | Windows | 2019 | x64 | virtual_media | UEFI | Windows/OOB-uefi 2019 | | Windows | 10.0.17763 | x64 | virtual_media | UEFI | Windows/non-OOB-uefi 2019 | | Windows | 2019 | x64 | virtual_media | Legacy | Windows/OOB-bios 2019 | +-----------+-----------------------+--------------+----------------+-----------+-------------------------------------------+ Total: 9 Repository templates ``` ## Registering a new template Besides the *source template*, the original iso is required for registering a new template. 1. Download the ISO from any official repository to a local directory 2. Identify the source template path required for the OS family you are adding such as **Ubuntu/OOB-20.04** in the output of the `metalcloud-cli os-template list-source-templates` command. 3. Create the new template based on the downloaded iso and the entry in the **source template path** column ``` metalcloud-cli os-template register --source-template Ubuntu/OOB-20.04 --name "Ubuntu 20.04.4 OOB" --source-iso /a/iso/ubuntu-22.04.1-live-server-amd64.iso --label ubuntu-2004-oob ``` 4. Upload the ISO on the repo at the specified location if not already uploaded. ## Checking if the template has been registered: You can use the **Sidebar** > **Templates** to verify if the new template exists or use the CLI: ``` metalcloud-cli os-template list +---+-----------------+--------------------+-------------+-------------+--------------+-----------------------+--------------------+---------------+---------+----------------------+----------------------+ | ID| LABEL | NAME | DESCRIPTION | SIZE_MBYTES | BOOT_METHODS | OS | INSTALL_BOOTLOADER | OS_BOOTLOADER | USER_ID | CREATED | UPDATED | +---+-----------------+--------------------+-------------+-------------+--------------+-----------------------+--------------------+---------------+---------+----------------------+----------------------+ | 1 | ubuntu-2004-oob | Ubuntu 20.04.4 OOB | | 2048 | local_drives | Ubuntu 20.04.4 x86_64 | | | 3 | 2023-01-18T10:40:32Z | 2023-01-18T10:40:32Z | +---+-----------------+--------------------+-------------+-------------+--------------+-----------------------+--------------------+---------------+---------+----------------------+----------------------+ Total: 1 Templates ``` ## Customizing a template To add a new software package, change the storage configuration or for other reasons you can view and edit the files (assets) that get injected in the image building process. 1. Enable the Assets view. Normally the assets view is not enabled. Navigate to the **Users & Permissions** > **user** > **Limits** and check the **Enable Template Assets view** checkbox. 2. Navigate to assets Once a template has been registered, navigate to the template **Templates** > **Unattended install templates** > **template** > **Assets** 3. Edit an asset To open an asset select the asset and navigate to the **Content** tab to open the built-in content editor. Assets depend on the operating system. Consult the operating system's unattended installation manual for instructions on how the files are named and their role. Note that additional helper assets might be added by MetalSoft for various purposes such as generating firewall configurations that might not be part of the standard installation process. Refer to the [Template Language and Variables](template_language_and_variables) for more details on the Nunjucks programming language and the runtime variables used by the templates. Click the green **Save** button to save the asset. Note that assets can also be changed via the CLI `metalcloud-cli asset edit` command. Run to the `metalcloud-cli asset` commands for more details on the available commands. 4. Test the template Test the deployment process by deploying an instance array in the usual way. Monitor the deployment of the operating system using the **Job queue** or by navigating to **Infrastructures** > **** > **Open Deploy Graph** or by using the `metalcloud-cli job list` commands. :::{warning} Note that **Save** button will NOT propagate the changes to an ongoing deploy and thus retrying a task on the OS deployment tasks in the graph will not change the already 'materialized' assets. To fix an problem with an asset skip the offending task and try another deploy. ::: ## Upgrading an existing template to a newer version First check for a newer version in the official MetalSoft repository using the `metalcloud-cli os-template list-source-templates` command. If no newer version exists you can attempt the upgrade yourself by using the same `metalcloud-cli os-template register` command as before and using a newer ISO and an older source template. This should be sufficient for most situations as the unattended installation process does not usually change between minor releases of an operating system. ## Building a new template from scratch To build a new template from scratch you will need to build a source repository similar to the provided ones. 1. Create a directory 2. Create a `template.yaml` file (refer to [this](https://github.com/metalsoft-io/os-templates/blob/main/Ubuntu/22.04/oob-adv-uefi-boot/template.yaml) as an example). This file describes the assets and their types. 3. Add the assets, refer to [Template Language and Variables](template_language_and_variables) for how to add variables to the files in order to adapt to each server that gets deployed. 4. Use the newly created directory and use `metalcloud-cli os-template register --source-template ./template-dir` to use the local template as a *source template* for registering the template in the environment. ## Building a new source template for legacy systems Refer to the following resource for building templates for legacy (PXE) environments [Managing OS templates for legacy (PXE)](/content/configuration/os_templates/legacy_os_templates).