feat(backup): incremental NAS backup support for KVM

core/src/main/java/org/apache/cloudstack/backup/BackupAnswer.java

@@ -29,6 +29,17 @@ public class BackupAnswer extends Answer {
     private Long virtualSize;
     private Map<String, String> volumes;
     Boolean needsCleanup;
+    // Set by the NAS backup provider after a checkpoint/bitmap was created during this backup.
+    // The provider persists it in backup_details under NASBackupChainKeys.BITMAP_NAME.
+    private String bitmapCreated;
+    // Set when an incremental was requested but the agent had to fall back to a full
+    // (e.g. VM was stopped). Provider should record this backup as type=full.
+    private Boolean incrementalFallback;
+    // Set when the agent had to recreate the parent bitmap before this incremental
+    // (e.g. CloudStack rebuilt the domain XML on the previous VM start, losing bitmaps).
+    // The first incremental after a recreate is larger than usual; subsequent
+    // incrementals return to normal size. Informational — recorded in backup_details.
+    private String bitmapRecreated;
 
     public BackupAnswer(final Command command, final boolean success, final String details) {
         super(command, success, details);
@@ -68,4 +79,28 @@ public Boolean getNeedsCleanup() {
     public void setNeedsCleanup(Boolean needsCleanup) {
         this.needsCleanup = needsCleanup;
     }
+
+    public String getBitmapCreated() {
+        return bitmapCreated;
+    }
+
+    public void setBitmapCreated(String bitmapCreated) {
+        this.bitmapCreated = bitmapCreated;
+    }
+
+    public Boolean getIncrementalFallback() {
+        return incrementalFallback != null && incrementalFallback;
+    }
+
+    public void setIncrementalFallback(Boolean incrementalFallback) {
+        this.incrementalFallback = incrementalFallback;
+    }
+
+    public String getBitmapRecreated() {
+        return bitmapRecreated;
+    }
+
+    public void setBitmapRecreated(String bitmapRecreated) {
+        this.bitmapRecreated = bitmapRecreated;
+    }
 }

core/src/main/java/org/apache/cloudstack/backup/RebaseBackupCommand.java

@@ -0,0 +1,73 @@
+//
+// 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.backup;
+
+import com.cloud.agent.api.Command;
+import com.cloud.agent.api.LogLevel;
+
+/**
+ * Tells the KVM agent to rebase a NAS backup qcow2 onto a new backing parent. Used by the
+ * NAS backup provider during chain repair when a middle incremental is being deleted: the
+ * immediate child must absorb the soon-to-be-deleted parent's blocks and then re-link to
+ * the grandparent. Both target and new-backing paths are NAS-mount-relative.
+ */
+public class RebaseBackupCommand extends Command {
+    private String targetPath;       // mount-relative path of the qcow2 to repoint
+    private String newBackingPath;   // mount-relative path of the new backing parent
+    private String backupRepoType;
+    private String backupRepoAddress;
+    @LogLevel(LogLevel.Log4jLevel.Off)
+    private String mountOptions;
+
+    public RebaseBackupCommand(String targetPath, String newBackingPath,
+                               String backupRepoType, String backupRepoAddress, String mountOptions) {
+        super();
+        this.targetPath = targetPath;
+        this.newBackingPath = newBackingPath;
+        this.backupRepoType = backupRepoType;
+        this.backupRepoAddress = backupRepoAddress;
+        this.mountOptions = mountOptions;
+    }
+
+    public String getTargetPath() {
+        return targetPath;
+    }
+
+    public String getNewBackingPath() {
+        return newBackingPath;
+    }
+
+    public String getBackupRepoType() {
+        return backupRepoType;
+    }
+
+    public String getBackupRepoAddress() {
+        return backupRepoAddress;
+    }
+
+    public String getMountOptions() {
+        return mountOptions == null ? "" : mountOptions;
+    }
+
+    @Override
+    public boolean executeInSequence() {
+        return true;
+    }
+}

core/src/main/java/org/apache/cloudstack/backup/TakeBackupCommand.java

@@ -36,6 +36,18 @@ public class TakeBackupCommand extends Command {
     @LogLevel(LogLevel.Log4jLevel.Off)
     private String mountOptions;
 
+    // Incremental backup fields (NAS provider; null/empty for legacy full-only callers).
+    private String mode;          // "full" or "incremental"; null => legacy behaviour (script default)
+    private String bitmapNew;     // Checkpoint/bitmap name to create with this backup (timestamp-based)
+    private String bitmapParent;  // Incremental: parent bitmap to read changes since
+
+    // Per-volume parent backup file paths (one per VM volume, ordered by deviceId — same
+    // order as volumePaths). The script rebases each new qcow2 onto the matching parent.
+    // Addresses abh1sar review at NASBackupProvider.java:340 — backup file UUIDs differ
+    // across volumes, so a single parentPath would have rebased every data disk onto the
+    // root file. New callers MUST populate parentPaths.
+    private List<String> parentPaths;
+
     public TakeBackupCommand(String vmName, String backupPath) {
         super();
         this.vmName = vmName;
@@ -106,6 +118,38 @@ public void setQuiesce(Boolean quiesce) {
         this.quiesce = quiesce;
     }
 
+    public String getMode() {
+        return mode;
+    }
+
+    public void setMode(String mode) {
+        this.mode = mode;
+    }
+
+    public String getBitmapNew() {
+        return bitmapNew;
+    }
+
+    public void setBitmapNew(String bitmapNew) {
+        this.bitmapNew = bitmapNew;
+    }
+
+    public String getBitmapParent() {
+        return bitmapParent;
+    }
+
+    public void setBitmapParent(String bitmapParent) {
+        this.bitmapParent = bitmapParent;
+    }
+
+    public List<String> getParentPaths() {
+        return parentPaths;
+    }
+
+    public void setParentPaths(List<String> parentPaths) {
+        this.parentPaths = parentPaths;
+    }
+
     @Override
     public boolean executeInSequence() {
         return true;

plugins/backup/nas/src/main/java/org/apache/cloudstack/backup/NASBackupChainKeys.java

@@ -0,0 +1,67 @@
+// 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.backup;
+
+/**
+ * Keys used by the NAS backup provider when storing incremental-chain metadata
+ * in the existing {@code backup_details} key/value table. Stored here (not on
+ * the {@code backups} table) so other providers do not need a schema change to
+ * support their own incremental implementations.
+ */
+public final class NASBackupChainKeys {
+
+    /** UUID of the parent backup (full or previous incremental). Empty for full backups. */
+    public static final String PARENT_BACKUP_ID = "nas.parent_backup_id";
+
+    /** QEMU dirty-bitmap name created by this backup, used as the {@code <incremental>} reference for the next one. */
+    public static final String BITMAP_NAME = "nas.bitmap_name";
+
+    /** Identifier shared by every backup in the same chain (the full anchors a chain; its incrementals inherit the id). */
+    public static final String CHAIN_ID = "nas.chain_id";
+
+    /** Position within the chain: 0 for the full, 1 for the first incremental, and so on. */
+    public static final String CHAIN_POSITION = "nas.chain_position";
+
+    /** Backup type marker: {@value #TYPE_FULL} or {@value #TYPE_INCREMENTAL}. Mirrors {@code backups.type} for fast lookup without a join. */
+    public static final String TYPE = "nas.type";
+
+    public static final String TYPE_FULL = "full";
+    public static final String TYPE_INCREMENTAL = "incremental";
+
+    /** Set to the bitmap name when this incremental had to recreate its parent bitmap on the host (informational; this incremental is larger than usual). */
+    public static final String BITMAP_RECREATED = "nas.bitmap_recreated";
+
+    /**
+     * Tombstone key stored in {@code backup_details} when a backup is requested for deletion
+     * but still has live children. The on-NAS file is preserved until the last child is gone,
+     * at which point cascade deletion collects every tombstoned ancestor. Mirrors the snapshot
+     * subsystem's {@code Hidden} state semantics (see {@code DefaultSnapshotStrategy}).
+     */
+    public static final String DELETE_PENDING = "nas.delete_pending";
+
+    /**
+     * VM-scoped detail (stored in {@code vm_instance_details}) holding the QEMU dirty-bitmap
+     * name that currently exists on the running VM and is therefore the only valid parent
+     * for the next incremental backup. Written by {@link #BITMAP_NAME} on each successful
+     * backup; cleared on restore (the restored disk image has no bitmap, so the next backup
+     * must be a fresh full). When the VM has no detail, {@code decideChain} forces full.
+     */
+    public static final String VM_ACTIVE_CHECKPOINT_ID = "nas.active_checkpoint_id";
+
+    private NASBackupChainKeys() {
+    }
+}