feat(backup): incremental NAS backup support for KVM

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

@@ -29,6 +29,12 @@ 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;
 
     public BackupAnswer(final Command command, final boolean success, final String details) {
         super(command, success, details);
@@ -68,4 +74,21 @@ 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;
+    }
+
 }

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

@@ -36,6 +36,17 @@ 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.
+    // 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 +117,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,66 @@
+// 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";
+
+    /**
+     * In-memory chain-mode sentinels used by {@code ChainDecision.mode}. The persisted
+     * full-vs-incremental backup type lives on the {@code backup.type} column (set in
+     * {@code takeBackup}) — single source of truth. Not duplicated into backup_details.
+     */
+    public static final String TYPE_FULL = "full";
+    public static final String TYPE_INCREMENTAL = "incremental";
+
+    /**
+     * 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() {
+    }
+}