weizhouapache · Mar 30, 2026 · Mar 30, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/engine/schema/pom.xml b/engine/schema/pom.xml
@@ -88,8 +88,15 @@
                                 <script><![CDATA[
                                     def projectVersion = project.properties.getProperty('project.systemvm.template.version')
                                     String[] versionParts = projectVersion.tokenize('.')
-                                    project.properties.setProperty('cs.version', versionParts[0] + "." + versionParts[1])
-                                    project.properties.setProperty('patch.version', versionParts[2])
+                                    if (versionParts[0].toInteger() >= 24) {
+                                        // new versioning: directory 24, templates systemvmtemplate-24.0-...
+                                        project.properties.setProperty('cs.version', versionParts[0])
+                                        project.properties.setProperty('patch.version', versionParts[1])
+                                    } else {
+                                        // legacy versioning: directory 4.22, templates systemvmtemplate-4.22.0-...
+                                        project.properties.setProperty('cs.version', versionParts[0] + "." + versionParts[1])
+                                        project.properties.setProperty('patch.version', versionParts[2])
+                                    }
                                 ]]></script>
                             </scripts>
                         </configuration>

diff --git a/engine/schema/src/main/resources/META-INF/db/schema-21to22.sql b/engine/schema/src/main/resources/META-INF/db/schema-21to22.sql
@@ -964,11 +964,6 @@ INSERT INTO `cloud`.`vm_template` (id, unique_name, name, public, created, type,
 INSERT INTO `cloud`.`vm_template` (id, unique_name, name, public, created, type, hvm, bits, account_id, url, checksum, enable_password, display_text, format, guest_os_id, featured, cross_zones, hypervisor_type)
     VALUES (8, 'routing-8', 'SystemVM Template (vSphere)', 0, now(), 'SYSTEM', 0, 32, 1, 'http://download.cloudstack.org/releases/2.2.0/systemvm.ova', '3c9d4c704af44ebd1736e1bc78cec1fa', 0, 'SystemVM Template (vSphere)', 'OVA', 15, 0, 1, 'VMware');
 
-INSERT INTO `cloud`.`vm_template` (id, unique_name, name, public, created, type, hvm, bits, account_id, url, checksum, display_text, enable_password, format, guest_os_id, featured, cross_zones, hypervisor_type, extractable)
-    VALUES (4, 'centos55-x86_64', 'CentOS 5.5(64-bit) no GUI (KVM)', 1, now(), 'BUILTIN', 0, 64, 1, 'http://download.cloudstack.org/releases/2.2.0/eec2209b-9875-3c8d-92be-c001bd8a0faf.qcow2.bz2', 'ed0e788280ff2912ea40f7f91ca7a249', 'CentOS 5.5(64-bit) no GUI (KVM)', 0, 'QCOW2', 112, 1, 1, 'KVM', 1);
-
-INSERT INTO `cloud`.`vm_template` (id, unique_name, name, public, created, type, hvm, bits, account_id, url, checksum, enable_password, display_text,  format, guest_os_id, featured, cross_zones, hypervisor_type, extractable)
-    VALUES (7, 'centos53-x64', 'CentOS 5.3(64-bit) no GUI (vSphere)', 1, now(), 'BUILTIN', 0, 64, 1, 'http://download.cloudstack.org/releases/2.2.0/CentOS5.3-x86_64.ova', 'f6f881b7f2292948d8494db837fe0f47', 0, 'CentOS 5.3(64-bit) no GUI (vSphere)', 'OVA', 12, 1, 1, 'VMware', 1);
 UPDATE vm_instance SET guest_os_id=15 where vm_template_id=1;
 UPDATE vm_instance SET vm_template_id=(SELECT id FROM vm_template WHERE name='systemvm-xenserver-2.2.4' AND removed IS NULL) where vm_template_id=1;
 

diff --git a/engine/schema/src/main/resources/META-INF/db/schema-2214to30.sql b/engine/schema/src/main/resources/META-INF/db/schema-2214to30.sql
@@ -625,9 +625,6 @@ UPDATE `cloud`.`event` e set e.domain_id = (select acc.domain_id from `cloud`.`a
 
 update `cloud`.`vm_template` set removed=now() where id=2;
 
-INSERT INTO `cloud`.`vm_template` (id, unique_name, name, public, created, type, hvm, bits, account_id, url, checksum, enable_password, display_text,  format, guest_os_id, featured, cross_zones, hypervisor_type, extractable)
-    VALUES (5, 'centos56-x86_64-xen', 'CentOS 5.6(64-bit) no GUI (XenServer)', 1, now(), 'BUILTIN', 0, 64, 1, 'http://download.cloudstack.org/templates/builtin/centos56-x86_64.vhd.bz2', '905cec879afd9c9d22ecc8036131a180', 0, 'CentOS 5.6(64-bit) no GUI (XenServer)', 'VHD', 12, 1, 1, 'XenServer', 1);
-
 DELETE from `cloud`.`configuration` where name='firewall.rule.ui.enabled';
 
 DELETE FROM `cloud`.`resource_limit` WHERE domain_id = 1 AND account_id IS NULL;

diff --git a/engine/schema/src/main/resources/META-INF/db/schema-421to430.sql b/engine/schema/src/main/resources/META-INF/db/schema-421to430.sql
@@ -129,7 +129,6 @@ ALTER TABLE `cloud`.`volumes` ADD COLUMN `hv_ss_reserve` int(32) unsigned DEFAUL
 UPDATE `cloud`.`disk_offering` SET `state`='Inactive' WHERE `removed` IS NOT NULL;
 UPDATE `cloud`.`disk_offering` SET `removed`=NULL;
 
-UPDATE `cloud`.`vm_template` SET `guest_os_id`= "142" WHERE `id` = "5";
 UPDATE `cloud`.`vm_template` SET `state`='Inactive' WHERE `removed` IS NOT NULL;
 UPDATE `cloud`.`vm_template` SET `state`='Active' WHERE `removed` IS NULL;
 UPDATE `cloud`.`vm_template` SET `removed`=NULL;

diff --git a/engine/schema/src/main/resources/META-INF/db/schema-42300to2400.sql b/engine/schema/src/main/resources/META-INF/db/schema-42300to2400.sql
@@ -226,3 +226,21 @@ CREATE TABLE IF NOT EXISTS `cloud`.`instance_boot_group_details` (
     PRIMARY KEY (`id`),
     CONSTRAINT `fk_instance_boot_group_details__group_id` FOREIGN KEY (`boot_group_id`) REFERENCES `instance_boot_group` (`id`) ON DELETE CASCADE
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Set the guest OS of the built-in Debian 13 templates to 'Debian GNU/Linux 12 (64-bit)', which is only added by later upgrade scripts and is not available in templates.sql
+UPDATE `cloud`.`vm_template` SET `guest_os_id` = (SELECT `id` FROM `cloud`.`guest_os` WHERE `display_name` = 'Debian GNU/Linux 12 (64-bit)' AND `removed` IS NULL LIMIT 1)
+    WHERE `id` = 4 AND `unique_name` = 'debian13-x86_64-kvm' AND `type` = 'BUILTIN';
+UPDATE `cloud`.`vm_template` SET `guest_os_id` = (SELECT `id` FROM `cloud`.`guest_os` WHERE `display_name` = 'Debian GNU/Linux 12 (64-bit)' AND `removed` IS NULL LIMIT 1)
+    WHERE `id` = 5 AND `unique_name` = 'debian13-x86_64-xen' AND `type` = 'BUILTIN';
+UPDATE `cloud`.`vm_template` SET `guest_os_id` = (SELECT `id` FROM `cloud`.`guest_os` WHERE `display_name` = 'Debian GNU/Linux 12 (64-bit)' AND `removed` IS NULL LIMIT 1)
+    WHERE `id` = 7 AND `unique_name` = 'debian13-x86_64-vmware' AND `type` = 'BUILTIN';
+
+-- Use the NIC and disk controller of the built-in Debian 13 VMware template image (vmxnet3, pvscsi), as the guest kernel has no driver for the default e1000 NIC
+INSERT INTO `cloud`.`vm_template_details` (`template_id`, `name`, `value`)
+    SELECT `id`, 'nicAdapter', 'Vmxnet3' FROM `cloud`.`vm_template`
+    WHERE `id` = 7 AND `unique_name` = 'debian13-x86_64-vmware' AND `type` = 'BUILTIN'
+    AND NOT EXISTS (SELECT 1 FROM `cloud`.`vm_template_details` WHERE `template_id` = 7 AND `name` = 'nicAdapter');
+INSERT INTO `cloud`.`vm_template_details` (`template_id`, `name`, `value`)
+    SELECT `id`, 'rootDiskController', 'pvscsi' FROM `cloud`.`vm_template`
+    WHERE `id` = 7 AND `unique_name` = 'debian13-x86_64-vmware' AND `type` = 'BUILTIN'
+    AND NOT EXISTS (SELECT 1 FROM `cloud`.`vm_template_details` WHERE `template_id` = 7 AND `name` = 'rootDiskController');
diff --git a/engine/schema/templateConfig.sh b/engine/schema/templateConfig.sh
@@ -28,9 +28,7 @@ function getTemplateVersion() {
   subversion2="$(cut -d'.' -f2 <<<"$version")"
   minorversion="$(cut -d'.' -f3 <<<"$version")"
   fourthversion="$(cut -d'.' -f4 <<<"$version")"
-  export CS_VERSION="${subversion1}"."${subversion2}"
   export CS_MINOR_VERSION="${minorversion}"
-  export VERSION="${CS_VERSION}.${CS_MINOR_VERSION}"
   if [[ "$subversion1" -ge "$NEW_VERSIONING_CUTOVER_MAJOR_VERSION" ]]; then
     # New versioning (major.minor.security): the third component is the
     # security release itself, there is no separate patch component. A
@@ -40,11 +38,17 @@ function getTemplateVersion() {
       echo "Invalid version '${projVersion}': major versions at or above ${NEW_VERSIONING_CUTOVER_MAJOR_VERSION} do not support a 4-component major.minor.patch.security format" >&2
       exit 1
     fi
-    export FULL_VERSION="${VERSION}"
+    # The templates are in the directory named after the major version (24),
+    # and the file names contain major.minor (24.0), like 4.22 and 4.22.0 before
+    export CS_VERSION="${subversion1}"
+    export VERSION="${subversion1}.${subversion2}"
+    export FULL_VERSION="${subversion1}.${subversion2}.${minorversion}"
   else
     # Legacy versioning: major.minor.patch, or major.minor.patch.security when a 4th
     # component is present. Without a 4th component, VERSION is already correct as-is;
     # appending an empty security component would leave a dangling trailing dot.
+    export CS_VERSION="${subversion1}"."${subversion2}"
+    export VERSION="${CS_VERSION}.${CS_MINOR_VERSION}"
     if [[ -n "$fourthversion" ]]; then
       export FULL_VERSION="${VERSION}.${fourthversion}"
     else

diff --git a/engine/schema/test_templateConfig.sh b/engine/schema/test_templateConfig.sh
@@ -51,6 +51,7 @@ assert_eq "legacy: VERSION" "4.22.0" "$VERSION"
 assert_eq "legacy: FULL_VERSION keeps the 4th (security) component" "4.22.0.0" "$FULL_VERSION"
 
 getTemplateVersion "4.23.0.1-SNAPSHOT"
+assert_eq "legacy with -SNAPSHOT suffix: CS_VERSION" "4.23" "$CS_VERSION"
 assert_eq "legacy with -SNAPSHOT suffix: VERSION" "4.23.0" "$VERSION"
 assert_eq "legacy with -SNAPSHOT suffix: FULL_VERSION" "4.23.0.1" "$FULL_VERSION"
 
@@ -62,16 +63,18 @@ assert_eq "legacy 3-component (no security): FULL_VERSION has no trailing dot" "
 # --- getTemplateVersion: new versioning (major >= 24, post-cutover) ---
 
 getTemplateVersion "24.0.0"
-assert_eq "cutover: CS_VERSION" "24.0" "$CS_VERSION"
-assert_eq "cutover: VERSION" "24.0.0" "$VERSION"
+assert_eq "cutover: CS_VERSION (directory) is the major version" "24" "$CS_VERSION"
+assert_eq "cutover: VERSION (file names) is major.minor" "24.0" "$VERSION"
 assert_eq "cutover: FULL_VERSION has no trailing dot (patch dropped)" "24.0.0" "$FULL_VERSION"
 
 getTemplateVersion "24.1.2-SNAPSHOT"
-assert_eq "cutover with -SNAPSHOT suffix: VERSION" "24.1.2" "$VERSION"
+assert_eq "cutover with -SNAPSHOT suffix: CS_VERSION" "24" "$CS_VERSION"
+assert_eq "cutover with -SNAPSHOT suffix: VERSION" "24.1" "$VERSION"
 assert_eq "cutover with -SNAPSHOT suffix: FULL_VERSION" "24.1.2" "$FULL_VERSION"
 
 getTemplateVersion "99.9.9"
-assert_eq "future major: VERSION" "99.9.9" "$VERSION"
+assert_eq "future major: CS_VERSION" "99" "$CS_VERSION"
+assert_eq "future major: VERSION" "99.9" "$VERSION"
 assert_eq "future major: FULL_VERSION" "99.9.9" "$FULL_VERSION"
 
 # A 4-component major.minor.patch.security value is invalid at/after the cutover (matches
@@ -96,7 +99,7 @@ run_create_metadata_file() {
   : > "$METADATAFILE"
 
   createMetadataFile
-  grep '^version = ' "$METADATAFILE" | head -1 | cut -d' ' -f3
+  grep "^${2:-version} = " "$METADATAFILE" | head -1 | cut -d' ' -f3
 
   rm -rf "$workdir"
 }
@@ -107,6 +110,26 @@ assert_eq "metadata.ini legacy 'version' line" "4.22.0.0" "$actual"
 actual="$(run_create_metadata_file "24.0.0")"
 assert_eq "metadata.ini cutover 'version' line has no trailing dot" "24.0.0" "$actual"
 
+# --- createMetadataFile: file names, directory, template name and checksum ---
+
+actual="$(run_create_metadata_file "4.22.0.0" downloadurl)"
+assert_eq "metadata.ini legacy downloadurl" "https://download.cloudstack.org/systemvm//4.22/systemvmtemplate-4.22.0-x86_64-kvm.qcow2.bz2" "$actual"
+actual="$(run_create_metadata_file "4.22.0.0" templatename)"
+assert_eq "metadata.ini legacy templatename" "systemvm-kvm-4.22.0-x86_64" "$actual"
+actual="$(run_create_metadata_file "4.22.0.0" checksum)"
+assert_eq "metadata.ini legacy checksum is found" "abc123" "$actual"
+
+actual="$(run_create_metadata_file "24.0.0" downloadurl)"
+assert_eq "metadata.ini cutover downloadurl" "https://download.cloudstack.org/systemvm//24/systemvmtemplate-24.0-x86_64-kvm.qcow2.bz2" "$actual"
+actual="$(run_create_metadata_file "24.0.0" filename)"
+assert_eq "metadata.ini cutover filename" "systemvmtemplate-24.0-x86_64-kvm.qcow2.bz2" "$actual"
+actual="$(run_create_metadata_file "24.0.0" templatename)"
+assert_eq "metadata.ini cutover templatename" "systemvm-kvm-24.0-x86_64" "$actual"
+actual="$(run_create_metadata_file "24.0.0" checksum)"
+assert_eq "metadata.ini cutover checksum is found" "abc123" "$actual"
+actual="$(run_create_metadata_file "24.0.1" downloadurl)"
+assert_eq "metadata.ini cutover security release uses the same template" "https://download.cloudstack.org/systemvm//24/systemvmtemplate-24.0-x86_64-kvm.qcow2.bz2" "$actual"
+
 echo ""
 echo "${pass} passed, ${fail} failed"
 [[ $fail -eq 0 ]]
diff --git a/...e/storage/src/main/java/org/apache/cloudstack/storage/image/BaseImageStoreDriverImpl.java b/...e/storage/src/main/java/org/apache/cloudstack/storage/image/BaseImageStoreDriverImpl.java
@@ -52,6 +52,7 @@
 import org.apache.cloudstack.storage.datastore.db.VolumeDataStoreVO;
 import org.apache.cloudstack.storage.endpoint.DefaultEndPointSelector;
 import org.apache.cloudstack.storage.image.deployasis.DeployAsIsHelper;
+import org.apache.commons.lang3.StringUtils;
 import org.apache.logging.log4j.Logger;
 import org.apache.logging.log4j.LogManager;
 
@@ -229,7 +230,11 @@ protected Void createTemplateAsyncCallback(AsyncCallbackDispatcher<? extends Bas
             updateBuilder.setErrorString(answer.getErrorString());
             updateBuilder.setJobId(answer.getJobId());
             updateBuilder.setLocalDownloadPath(answer.getDownloadPath());
-            updateBuilder.setInstallPath(answer.getInstallPath());
+            if (StringUtils.isNotEmpty(answer.getInstallPath())) {
+                // an error answer, like a timeout, has no install path. Do not clear the install path of the entry with it,
+                // as the next download of the template would use no install path and go to a directory named "null".
+                updateBuilder.setInstallPath(answer.getInstallPath());
+            }
             if (!VMTemplateStorageResourceAssoc.ERROR_DOWNLOAD_STATES.contains(answer.getDownloadStatus())) {
                 updateBuilder.setSize(answer.getTemplateSize());
                 updateBuilder.setPhysicalSize(answer.getTemplatePhySicalSize());

diff --git a/...orage/src/test/java/org/apache/cloudstack/storage/image/BaseImageStoreDriverImplTest.java b/...orage/src/test/java/org/apache/cloudstack/storage/image/BaseImageStoreDriverImplTest.java
@@ -0,0 +1,123 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.cloudstack.storage.image;
+
+import java.util.Collections;
+
+import org.apache.cloudstack.engine.subsystem.api.storage.CreateCmdResult;
+import org.apache.cloudstack.engine.subsystem.api.storage.DataObject;
+import org.apache.cloudstack.engine.subsystem.api.storage.DataStore;
+import org.apache.cloudstack.framework.async.AsyncCallbackDispatcher;
+import org.apache.cloudstack.framework.async.AsyncCompletionCallback;
+import org.apache.cloudstack.storage.datastore.db.TemplateDataStoreDao;
+import org.apache.cloudstack.storage.datastore.db.TemplateDataStoreVO;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.mockito.Mock;
+import org.mockito.Mockito;
+import org.mockito.junit.MockitoJUnitRunner;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import com.cloud.agent.api.storage.DownloadAnswer;
+import com.cloud.alert.AlertManager;
+import com.cloud.storage.VMTemplateStorageResourceAssoc.Status;
+import com.cloud.storage.VMTemplateVO;
+import com.cloud.storage.VMTemplateZoneVO;
+import com.cloud.storage.dao.VMTemplateDao;
+import com.cloud.storage.dao.VMTemplateZoneDao;
+
+@RunWith(MockitoJUnitRunner.Silent.class)
+public class BaseImageStoreDriverImplTest {
+
+    @Mock
+    private VMTemplateDao templateDao;
+    @Mock
+    private TemplateDataStoreDao templateStoreDao;
+    @Mock
+    private VMTemplateZoneDao vmTemplateZoneDao;
+    @Mock
+    private AlertManager alertManager;
+    @Mock
+    private DataObject data;
+    @Mock
+    private DataStore store;
+    @Mock
+    private AsyncCompletionCallback<CreateCmdResult> parentCallback;
+    @Mock
+    private AsyncCallbackDispatcher<BaseImageStoreDriverImpl, DownloadAnswer> callback;
+    @Mock
+    private TemplateDataStoreVO existingRef;
+    @Mock
+    private VMTemplateZoneVO templateZone;
+
+    private BaseImageStoreDriverImpl driver;
+    private TemplateDataStoreVO updateBuilder;
+
+    @Before
+    public void setUp() {
+        driver = Mockito.mock(BaseImageStoreDriverImpl.class, Mockito.CALLS_REAL_METHODS);
+        ReflectionTestUtils.setField(driver, "logger", org.apache.logging.log4j.LogManager.getLogger(BaseImageStoreDriverImpl.class));
+        ReflectionTestUtils.setField(driver, "_templateDao", templateDao);
+        ReflectionTestUtils.setField(driver, "_templateStoreDao", templateStoreDao);
+        ReflectionTestUtils.setField(driver, "_vmTemplateZoneDao", vmTemplateZoneDao);
+        ReflectionTestUtils.setField(driver, "_alertMgr", alertManager);
+
+        Mockito.when(data.getId()).thenReturn(7L);
+        Mockito.when(data.getDataStore()).thenReturn(store);
+        Mockito.when(store.getId()).thenReturn(1L);
+        Mockito.when(templateDao.findById(7L)).thenReturn(Mockito.mock(VMTemplateVO.class));
+        Mockito.when(templateDao.createForUpdate()).thenReturn(Mockito.mock(VMTemplateVO.class));
+        Mockito.when(existingRef.getId()).thenReturn(3L);
+        Mockito.when(existingRef.getDownloadState()).thenReturn(Status.DOWNLOAD_IN_PROGRESS);
+        Mockito.when(templateStoreDao.findByStoreTemplate(1L, 7L)).thenReturn(existingRef);
+        updateBuilder = Mockito.mock(TemplateDataStoreVO.class);
+        Mockito.when(templateStoreDao.createForUpdate()).thenReturn(updateBuilder);
+        Mockito.when(templateZone.getZoneId()).thenReturn(2L);
+        Mockito.when(vmTemplateZoneDao.listByTemplateId(7L)).thenReturn(Collections.singletonList(templateZone));
+    }
+
+    private void callWith(DownloadAnswer answer) {
+        Mockito.when(callback.getResult()).thenReturn(answer);
+        BaseImageStoreDriverImpl.CreateContext<CreateCmdResult> context = driver.new CreateContext<>(parentCallback, data);
+        driver.createTemplateAsyncCallback(callback, context);
+    }
+
+    @Test
+    public void testErrorAnswerWithoutInstallPathKeepsInstallPath() {
+        DownloadAnswer answer = new DownloadAnswer("Timeout waiting for response from storage host", Status.DOWNLOAD_ERROR);
+
+        callWith(answer);
+
+        Mockito.verify(updateBuilder, Mockito.never()).setInstallPath(Mockito.any());
+        Mockito.verify(updateBuilder).setDownloadState(Status.DOWNLOAD_ERROR);
+        Mockito.verify(templateStoreDao).update(3L, updateBuilder);
+    }
+
+    @Test
+    public void testAnswerWithInstallPathSetsInstallPath() {
+        DownloadAnswer answer = new DownloadAnswer("job", 100, null, Status.DOWNLOADED, "/dl/path", "template/tmpl/2/7", 10L, 10L, "checksum");
+
+        callWith(answer);
+
+        Mockito.verify(updateBuilder).setInstallPath("template/tmpl/2/7");
+        Mockito.verify(templateStoreDao).update(3L, updateBuilder);
+    }
+}
diff --git a/pom.xml b/pom.xml
@@ -50,7 +50,7 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
         <project.systemvm.template.location>https://download.cloudstack.org/systemvm</project.systemvm.template.location>
-        <project.systemvm.template.version>4.22.0.0</project.systemvm.template.version>
+        <project.systemvm.template.version>24.0.0</project.systemvm.template.version>
         <sonar.organization>apache</sonar.organization>
         <sonar.host.url>https://sonarcloud.io</sonar.host.url>
         <sonar.exclusions>engine/schema/src/main/java/org/apache/cloudstack/backup/BackupOfferingDetailsVO.java</sonar.exclusions>