OS templates repositories

Operating systems (OS) from ISPsystem repositories are available in VMmanager by default:

ISPsystem — for KVM clusters;
ISPsystem LXD — for LXD clusters.

To create a VM without an OS, the platform uses the repository "local".

You can connect your own repository with OS templates to VMmanager. This article describes how to create a repository and connect it in the platform settings.

Preparing a repository

You can use a server with access via HTTP (HTTPS) or FTP as a repository. The platform accesses the repository via the URL specified in the settings. For example, http://www.example.com/repo/. The repository directory must contain:

metadata.json file — repository description file;
OS template archives:
- for Linux — in .xz format;
- for Windows and templates for LXD clusters - in .tar.gz format.
Read more about Linux OS templates in Preparing the OS Linux template. Read more about Windows OS templates in Preparing the OS Windows template.
To prepare an OS template that is not in any of the supported groups, use the instructions in Preparing the OS Linux template for a KVM cluster.
OS templates for LXD clusters should not be in the same repository as templates for KVM clusters.
The metadata.json file contains parameters for installing OS templates from the repository:
- type — repository type. Specify the os value;
- os — array of objects to describe OS templates. Each object contains parameters:
  - name — template name. The platform defines the OS type and selects the IP address addition model by the template name:
    Substring in the template name IP address addition model
    alma
    redhat-based
    centos
    fedora
    oracle
    redhat
    rocky
    debian
    debian-based
    ubuntu
    freebsd
    freebsd-based
    windows
    Windows
    If no substring from the table was found, the none model will be assigned to the template. For more information about models, see the article Managing VM IP addresses;
  - tags — template tags. Used for compatibility with scripts;
  - file_name — template file name;
  - image_name — template image name. Used to generate a file name for the template image on the cluster node. Only for KVM clusters;
  - expand — the name of the partition to be expanded when creating the VM. For example, if the template has /dev/sda1 (2 GB) and /dev/sda2 (3 GB) partitions, and you specify /dev/sda2 in the parameter, VMmanager will create /dev/sda1 (2 GB) and /dev/sda2 (8 GB) partitions when installing an OS on a VM with a 10 GB disk. Only for KVM clusters;
  - network_device — network device name. Only for KVM clusters;
    Use standard names for network devices. For example, ens3, eth0, enp0s3, etc.
  - archive_size_mib — archive size in MiB;
  - cpu_mode — CPU emulation mode:
    - default — QEMU virtual CPU is emulated;
    - host-model — the emulated CPU will have the same function flags as the cluster node CPU;
    - host-passthrough — the emulated CPU will exactly match the CPU on the host machine cluster node and have the same function flags;
      For AlmaLinux 9 OS templates the value of the parameter should be host-passthrough.
      If the Custom configuration was selected when creating the VM, the VM will be created with the emulation mode specified in that configuration.
      If the parameter is not specified in the template, the VM will be created with the emulation mode specified in the configuration used.
  - image_size_mib — template image size in MiB. Only for KVM clusters;
  - min_size_mib — minimum disk size for OS in MiB;
    You can determine the file size in MiB using the ls utility:
    ls -l --block-size=M <file_name>
- updated_at — time of the last update of the template file;
- checksum — the hash sum of the archive file, calculated using the SHA-1 algorithm;
  You can find the hash sum of a file using the sha1sum utility:
  sha1sum <file_name>
  - kms_supported — whether the OS supports activation through an own KMS server. Only for Windows templates. Possible values: true — supports, false — does not support;
  - install_script — initial setup script. Only for Windows templates. If the parameter is set, the script from the OS template is not used. Parameter format:
```
"install_script": {
 "file_name": "<scpipt filename>",
 "checksum": "<hash sum of the script file, calculated using the SHA-1 algorithm>",
 "updated_at": "<time of the last modification of the script file>"
 }
```
  - efi_boot — load the template into EFI. Possible values: true — load, false — do not load.
An example of a repository description file for a KVM cluster
```
{
    "type": "os",
    "os": [
        {
            "name": "Ubuntu 20.04 ZFS",
            "tags": [
                "ubuntu20",
                "ubuntu",
                "linux"
            ],
            "file_name": "ubuntu-20.04-zfs.xz",
            "image_name": "ubuntu-20.04-zfs",
            "expand": "/dev/sda3",
            "network_device": "ens3",
            "archive_size_mib": 550,
            "cpu_mode": "host-passthrough",
            "image_size_mib": 2450,
            "min_size_mib": 10240,
            "updated_at": "2020-10-13 01:36:00",
            "checksum": "78e9564a81fdece34f1869ffc33d10e14dbef7d3"
        },
        {
            "name": "Windows Server 2019",
            "tags": [
                "windows",
                "windows2019"
            ],
            "file_name": "Windows-Server-2019-kms.tar.gz",
            "image_name": "windows_server_2019",
            "checksum": "751a72ba46964c89c29892c1c6be5c2c769f94f8",
            "expand": "/dev/sda2",
            "network_device": "eth0",
            "archive_size_mib": 5323,
            "image_size_mib": 15000,
            "min_size_mib": 15002,
            "updated_at": "2020-07-19 10:30",
            "kms_supported": true
             "install_script": {
                "file_name": "windows.cmd",
                "checksum": "0793376f335edff1b728cd580f441ddb2b52501b",
                "updated_at": "2024-04-25 07:20:00"
            } 
        }
    ]
}
```
An example of a repository description file for an LXD cluster
```
{
    "type": "lxd",
    "os": [
        {
			"name": "CentOS 7",
			"tags": ["centos","centos7","linux"],
			"file_name": "CentOS-7-amd64-20201223.tar.gz",
			"checksum": "30e5e1ca5b8a46b390cf1df6b99879f3be897421",
			"archive_size_mib": 180,
			"updated_at": "2020-12-23 08:22:05",
			"min_size_mib": 634
		}
    ]
}
```
Connecting a repository

To connect a repository, enter Templates → Repositories → Add repository button:
1. Enter the repository Name or click generate.
2. Enter the repository Address. E.g., http://example.com/repo/ or ftp://192.168.1.100/intrepo/.
  You may specify authorization settings in the URL. For example, ftp://user:password@www.example.com/repo/.
3. Click Add button. VMmanager will check the format of the metadata.json file. If the file does not contain any errors, VMmanager will add the repository.
To make OS from the repository available for installation, add them to the settings of the required cluster: Clusters → select the cluster → Parameters button → General settings → Operating system → select an OS from the repository → Save button.
Managing repositories
To manage repositories, enter Templates → Repositories.
To view the list of OS in the repository, click on ".. OS" in the "Content" column. The OS list is synchronized with the repository every 15 minutes. To update the repository content manually, click .
To rename a repository, click on its name or .
To delete a repository, click .
We do not recommend deleting ISPsystem and ISPsystem LXD system repositories. This configuration is not supported by the platform.
Useful tips
Related topics:

Substring in the template name	IP address addition model
alma	redhat-based
centos
fedora
oracle
redhat
rocky
debian	debian-based
ubuntu	debian-based
freebsd	freebsd-based
windows	Windows

OS templates repositories

Preparing a repository

Connecting a repository

Managing repositories